From 0ef5381ed7f75cfcd96574a38ca4c564002e826a Mon Sep 17 00:00:00 2001 From: healby <92+healby@noreply.gitea.privcloud.tech> Date: Sat, 24 Oct 2026 08:36:24 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A3=D0=B4=D0=B0=D0=BB=D0=B8=D1=82=D1=8C=20DE?= =?UTF-8?q?FENSE=5FTHEORY.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEFENSE_THEORY.md | 265 ---------------------------------------------- 1 file changed, 265 deletions(-) delete mode 100644 DEFENSE_THEORY.md diff --git a/DEFENSE_THEORY.md b/DEFENSE_THEORY.md deleted file mode 100644 index ecda3bbc..00000000 --- a/DEFENSE_THEORY.md +++ /dev/null @@ -1,265 +0,0 @@ -# Теория к защите лабораторной № 2 - -Конспект составлен по README.md, контракту, app.py, миграции, Compose и тестам этого репозитория. Описания реализации основаны на чтении кода; после исправлений выполнены smoke, persistence, проверки кэша, пять регрессионных тестов и EXPLAIN на 10 000 сообщениях. Измерения описаны в REPORT.md. - -## 1. Готовое вступление на 1–2 минуты - -«В лабораторной я реализовал REST API мессенджера на FastAPI. Основная задача — вынести состояние из памяти приложения в PostgreSQL и связать запросы с аутентифицированным пользователем. В базе хранятся пользователи, чаты, участники, сообщения и сессии. - -При регистрации пароль хешируется Argon2id. При входе клиент передаёт Basic credentials, после проверки получает случайный непрозрачный токен. Дальнейшие запросы используют Bearer. Сервер проверяет срок действия и отзыв сессии, а затем членство пользователя в конкретном чате. - -Создание чата вместе с участниками выполняется в одной транзакции. Ограничения базы обеспечивают уникальность username и целостность связей. История упорядочена по времени и UUID, используется курсорная пагинация и составной индекс. - -Valkey используется как TTL-кэш сессий. Источником истины остаётся PostgreSQL: исчезновение кэша не должно уничтожать действующие сессии. PostgreSQL и Valkey запускаются через Docker Compose с именованными volumes. В проекте есть проверки API, сохранности после рестарта и отдельных сценариев согласованности кэша». - -Про доказанную производительность и полное выполнение трека на «5» нужно говорить с учётом ограничений из раздела 12. - -## 2. Архитектура и хранение состояния - -Путь запроса: клиент → Uvicorn → FastAPI → PostgreSQL; при работе с сессиями приложение также обращается к Valkey. - -| Компонент | Назначение | -| --- | --- | -| FastAPI | Маршрутизация HTTP, проверка данных, аутентификация и бизнес-логика | -| Uvicorn | ASGI-сервер, запускающий приложение | -| PostgreSQL | Постоянное реляционное хранилище, источник истины | -| Valkey | Хранилище ключ–значение в памяти, используемое для кэша сессий | -| Docker Compose | Описание совместного запуска и связей сервисов | -| Volume | Данные вне записываемого слоя конкретного контейнера | - -Память процесса пропадает при его завершении. Файлы в слое контейнера не переживают его удаление и пересоздание без отдельного хранилища. Именованный volume сохраняется при обычном пересоздании контейнеров, но сам по себе не защищает от потери диска или хоста и не заменяет резервную копию. - -В compose.yaml объявлены postgres_data и valkey_data. Внутри сети Compose приложение обращается к db:5432 и valkey:6379; localhost внутри контейнера обозначает сам этот контейнер. - -## 3. Модель данных и ограничения - -Схема находится в migrations/001_initial_schema.sql. - -| Таблица | Что хранит | Основные ограничения | -| --- | --- | --- | -| users | Пользователей и хеши паролей | UUID PK, UNIQUE username, обязательные поля | -| chats | Чаты | UUID PK | -| chat_members | Участие пользователей в чатах | PK (chat_id, user_id), внешние ключи | -| messages | Сообщения | UUID PK, ссылки на чат и отправителя | -| sessions | Токены, владельцев, expiry и отзыв | UUID PK, UNIQUE token, ссылка на пользователя | -| schema_migrations | Применённые версии схемы | PRIMARY KEY version | - -**Первичный ключ** однозначно определяет строку. **Внешний ключ** запрещает ссылку на отсутствующую строку. **UNIQUE** запрещает повтор значения. **NOT NULL** запрещает отсутствие значения, но не запрещает пустую строку. - -chat_members реализует отношение многие-ко-многим: у пользователя несколько чатов, у чата несколько пользователей. Составной первичный ключ не допускает повторного включения одного пользователя в один чат. - -ON DELETE CASCADE удаляет зависимые строки при удалении родительской. В обязательном API удаления пользователей и чатов нет; это поведение схемы. - -Внешние ключи messages отдельно подтверждают существование чата и пользователя, но не доказывают членство отправителя в чате. Это проверяет приложение. - -**Гонка регистрации:** два запроса могут одновременно проверить, что username свободен. Поэтому проверка перед INSERT не гарантирует уникальность. Финальную гарантию даёт UNIQUE в PostgreSQL; один INSERT проходит, второй получает нарушение ограничения, которое API должен преобразовать в 409. - -## 4. Транзакции, ACID и COMMIT - -Транзакция объединяет действия в одну логическую операцию. В insert_chat сначала создаётся чат, затем строки участников и только после этого выполняется commit(). При исключении контекст соединения psycopg откатывает незавершённую транзакцию. - -Пример: если добавление участника нарушило внешний ключ, в базе не должен остаться чат с частичным составом участников. - -| Свойство ACID | Смысл в лабораторной | -| --- | --- | -| Atomicity — атомарность | Все части создания чата фиксируются вместе либо откатываются | -| Consistency — целостность | После операции сохраняются ограничения схемы | -| Isolation — изоляция | Параллельные операции взаимодействуют по правилам уровня изоляции | -| Durability — долговечность | Зафиксированные изменения сохраняются в пределах настроенных гарантий хранения | - -Приложение не задаёт особый уровень изоляции; стандартный уровень PostgreSQL — Read Committed. Каждый SQL-запрос видит снимок зафиксированных данных на момент начала этого запроса. Несколько запросов одной транзакции могут увидеть разные уже зафиксированные изменения других транзакций. - -**Что подтверждает COMMIT?** Успешную фиксацию транзакции. При стандартных настройках долговечности PostgreSQL перед подтверждением обеспечивает запись необходимых WAL-данных на устойчивое хранилище. WAL — журнал изменений, используемый для восстановления после сбоя; страницы таблиц могут записываться позднее. - -Гарантии зависят от fsync, synchronous_commit и фактической надёжности диска. Локальный COMMIT не означает наличие резервной копии или синхронной реплики. При обрыве соединения во время фиксации клиент может не знать, успел ли сервер выполнить COMMIT. - -Вставка сообщения фиксируется до успешного ответа. Последующий запрос к основной БД видит зафиксированное сообщение: это основа read-after-write в данном решении. История сообщений здесь не кэшируется. - -## 5. SQL, соединения и миграции - -SQL-запросы передают значения отдельными параметрами: cur.execute("... WHERE username = %s", (username,)). Драйвер обрабатывает значение как данные. Конкатенация пользовательской строки с SQL может привести к SQL injection. Параметры значений не служат заменой безопасного выбора имён таблиц или столбцов. - -В Store.connect заданы: - -- connect_timeout=5 — таймаут установления соединения; -- statement_timeout=5000 — ограничение выполнения SQL-команды в миллисекундах; -- lock_timeout=500 — ограничение ожидания блокировки в миллисекундах; -- autocommit=False — явные транзакции. - -Connection pool переиспользует соединения и ограничивает их количество. В текущем коде используется psycopg_pool.ConnectionPool: минимум 1, максимум DB_POOL_MAX_SIZE (по умолчанию 10), ожидание до 5 секунд, очередь до 20 запросов. Store.connect выдаёт контекст соединения; при выходе соединение возвращается в пул. Пул открывается при старте и закрывается при завершении приложения. - -Миграции — версионируемые изменения схемы. Store.init читает SQL-файлы, сверяется с schema_migrations, выполняет отсутствующие миграции и записывает версии. Повторный обычный запуск пропускает применённую версию. Уже применённую миграцию следует сохранять, а дальнейшее изменение оформлять новым файлом. Одновременный запуск мигратора несколькими экземплярами потребовал бы отдельной координации; в текущем коде её нет. - -## 6. Пароли, Basic, Bearer и права доступа - -**Аутентификация** устанавливает личность. **Авторизация** проверяет право выполнить действие над ресурсом. Действительная сессия не даёт доступ ко всем чатам. - -Последовательность работы: - -1. POST /api/v1/users принимает username, display_name, password; сохраняет хеш пароля. -2. POST /api/v1/auth/sessions принимает Authorization: Basic base64(username:password). -3. Сервер проверяет пароль библиотекой и создаёт сессию. -4. Клиент получает token и expires_at. -5. Защищённые запросы передают Authorization: Bearer . -6. Сервер проверяет сессию и доступ к конкретному чату. - -Basic использует Base64 — обратимое кодирование, которое не скрывает пароль. Bearer означает, что предъявитель токена получает права сессии. Для передачи credentials по недоверенной сети нужен TLS; контракт допускает HTTP для локального изолированного учебного стенда. - -Токен создаётся secrets.token_urlsafe(32): используется 32 случайных байта, то есть 256 бит исходной случайности. Это opaque-токен: клиент не извлекает из него сведения о пользователе, сервер ищет сессию по значению. JWT для этого не требуется. - -Argon2id — функция выработки ключа из пароля с затратами памяти и вычислений. В коде PasswordHasher получает time_cost=3, memory_cost=65536 KiB, parallelism=2, hash_len=32, salt_len=16. Соль генерирует библиотека; она и параметры входят в строковое представление хеша. - -Соль делает хеши одинаковых паролей различными и мешает использовать общие заранее рассчитанные таблицы. Соль не является секретом. Быстрый SHA-256 подходит для задач контроля целостности, но без password KDF позволяет слишком быстро перебирать кандидаты пароля. Проверка пароля выполняется verify(), а не сравнением с заново созданным хешем со случайной солью. - -sender_id определяется сервером из сессии. X-User-Id не заменяет аутентификацию. Для чужого чата контракт требует 404, чтобы ответ не подтверждал его существование. Неизвестная, истёкшая или отозванная сессия даёт 401. - -## 7. Сессии, TTL и logout - -В PostgreSQL сессия содержит token, user_id, expires_at, revoked_at. Она действительна, если существует, не отозвана и её expires_at позже текущего времени. - -SESSION_TTL_SECONDS по умолчанию равен 3600. Время истечения записывается как абсолютная дата. Рестарт не выдаёт сессии новый час жизни. - -Valkey хранит JSON под ключом session:. SETEX записывает значение со сроком жизни. TTL вычисляется из оставшегося времени до expires_at. Исчезновение кэш-ключа и истечение самой сессии — разные события: кэш можно восстановить, если запись в PostgreSQL ещё действительна. - -Logout сначала устанавливает revoked_at и фиксирует транзакцию в PostgreSQL, затем пытается удалить кэш-ключ. Даже если удаление из Valkey не удалось, проверка состояния БД должна запретить использование отозванного токена. Удаление токена только на клиенте серверную сессию не отзывает. - -Текущая проверка выполняет чтение сессии из БД до обращения к кэшу. Данные кэша полностью сравниваются с прочитанной сессией; при несовпадении ключ удаляется и восстанавливается. Возвращаются только данные из БД. Повторного SELECT сессии нет. Кэш по-прежнему не устраняет обязательную проверку БД; ускорение относительно полного отсутствия кэша не доказано. - -## 8. Согласованность кэша: термины и сценарии - -**Cache hit** — значение найдено в кэше. **Cache miss** — значения нет, нужно обратиться к источнику истины. **Инвалидация** — удаление или признание недействительной устаревшей записи. - -**Stale read** — чтение устаревшего значения. Пример: logout уже отозвал сессию в БД, но кэш всё ещё разрешает доступ. TTL лишь ограничивает период устаревания и сам по себе не гарантирует немедленный отзыв. - -**Cache stampede** — много одновременных запросов обнаруживают отсутствие популярного ключа и одновременно нагружают БД восстановлением. Возможные меры: один выполняющий загрузку запрос на ключ, распределённая блокировка с ограниченным сроком, разброс TTL. Для сессий нельзя отдавать отозванные данные ради доступности. - -**Гонка заполнения и logout:** запрос A читает действующую сессию; B отзывает её и удаляет ключ; A затем записывает старую сессию обратно. Одной операции DELETE недостаточно, чтобы исключить такую гонку. Проверка источника истины на последующем запросе позволяет отклонить отозванную сессию. Уже выполнявшийся параллельно logout запрос требует отдельно оговорённой семантики. - -**Read-after-write** означает, что чтение после подтверждённой записи видит эту запись. По контракту это особенно важно для сообщений. В проекте история читается из PostgreSQL, но отдельный эксперимент с конкурентным кэшированием истории не реализован. - -## 9. Индексы и курсорная пагинация - -История сортируется по created_at ASC, id ASC. Одного времени недостаточно: несколько сообщений могут иметь одинаковую метку. UUID обеспечивает однозначный порядок при равном времени, но UUIDv4 сам по себе не задаёт порядок создания. - -Индекс idx_messages_chat_created построен по (chat_id, created_at, id). По умолчанию это B-tree. Первым идёт chat_id, потому что история выбирается для конкретного чата; оставшиеся поля соответствуют порядку выдачи и позиции курсора. - -Идея запроса следующей страницы: - -```sql -SELECT id, chat_id, sender_id, text, created_at -FROM messages -WHERE chat_id = $1 - AND (created_at, id) > ($2, $3) -ORDER BY created_at, id -LIMIT $4; -``` - -Здесь $1…$4 обозначают параметры SQL. В app.py драйвер использует %s, граница записана сравнением кортежей. Эквивалентная логическая запись: - -```sql -created_at > cursor_time -OR (created_at = cursor_time AND id > cursor_id) -``` - -Логическая эквивалентность не гарантирует одинаковый план выполнения. План нужно проверять для SQL из реального обработчика. - -OFFSET N заставляет пропустить N строк перед выдачей страницы и обычно дорожает для глубоких страниц. Keyset-пагинация продолжает обход после ключа последней записи. При подходящем плане она позволяет искать границу по индексу и читать ограниченное число строк. Индекс занимает место и увеличивает стоимость INSERT/UPDATE/DELETE. - -Сервер запрашивает limit+1 строку: дополнительная показывает наличие продолжения. Клиенту возвращаются первые limit, курсор строится по последней выданной строке. Курсор содержит привязку к чату, поэтому курсор другого чата даёт 400. - -Курсор не создаёт единый снимок на весь обход. Если конкурентная вставка получает ключ меньше уже пройденной границы, она может не попасть в последующие страницы. Контракт гарантирует отсутствие повторов для неизменной истории; ограничения конкурентных вставок нужно объяснять отдельно. - -## 10. Как читать EXPLAIN - -EXPLAIN показывает план. EXPLAIN ANALYZE действительно выполняет запрос и добавляет измерения. BUFFERS показывает работу с буферами. - -| Поле | Значение | -| --- | --- | -| Index Scan | Чтение с использованием индекса с обращением к таблице | -| Seq Scan | Последовательный просмотр таблицы; иногда оптимален для небольшой таблицы | -| Index Cond | Условие, используемое для поиска в индексе | -| Filter | Дополнительная проверка строк после чтения | -| cost | Оценка планировщика в условных единицах | -| actual time | Фактическое время в миллисекундах | -| rows, loops | Число строк и повторов узла; при нескольких loops значения времени/строк усредняются на выполнение | -| shared hit | Блок найден в shared buffers PostgreSQL | -| shared read | Блок загружен в shared buffers; он мог находиться в кэше ОС | - -В scripts/explain_pagination.py создаются 10 000 временных сообщений. Измеряются непустые страницы после позиций 0, 5000 и 9900 с LIMIT 51 и таким же предикатом границы, как в API. В выполненной проверке все три плана использовали Index Scan. В конце транзакция откатывается, чтобы не накапливать тестовые строки. - -## 11. Отказы, перезапуск и проверки - -| Событие | Ожидаемое поведение и объяснение | -| --- | --- | -| Рестарт API | Данные и действующие сессии остаются в PostgreSQL | -| Потеря/очистка Valkey | Валидная сессия восстанавливается из БД | -| Недоступность Valkey | RedisError обрабатывается как обход кэша; возможны задержки до таймаутов | -| Недоступность PostgreSQL | Нельзя подтвердить состояние и отзыв сессии; запрос не должен получать доверенный доступ | -| Истечение сессии | 401 независимо от наличия ключа в кэше | -| Рестарт с volumes | Данные сохраняются, срок сессии продолжает идти | -| Удаление volumes | Проверяемая гарантия сохранности теряется | - -Для Valkey включены AOF и RDB-настройка save 60 1. RDB сохраняет снимки, AOF журналирует изменения. Возможная потеря последних изменений при аварии зависит от политики синхронизации AOF; один флаг appendonly не означает нулевую потерю данных. В этой архитектуре восстановление сессий опирается на PostgreSQL. - -GET /health/live отвечает, что процесс жив. GET /health/ready выполняет SELECT 1 в PostgreSQL. Valkey не входит в readiness, поскольку предусмотрен обход кэша. Одна готовность БД ещё не доказывает корректность всей бизнес-логики. - -Команды из репозитория для демонстрации при запущенном стенде: - -```sh -make check -make validate -make test -make cache-consistency -make test-persistence ACTION_SCRIPT=scripts/restart.sh -``` - -make check проверяет структуру и контракт, make validate — схемы, make test — публичный API. Persistence-тест проверяет сохранность данных и токена после action script; scripts/restart.sh пересоздаёт app, db и valkey с сохранением volumes. Прохождение smoke само по себе не подтверждает все критерии оценки. - -## 12. Исправления и ограничения исследования - -Исправлены подмена идентичности через кэш, обработка JSON с отсутствующими полями и повторный SELECT сессии. Добавлен ограниченный pool, устранены вложенные захваты соединений и утечка соединения при создании сессии. Миграции теперь входят в Docker-образ. Запрос и EXPLAIN используют сравнение составного ключа. - -scripts/research_cache.py воспроизводит прежний алгоритм в изолированной функции и сравнивает его с исправленным Store. Между чтением БД и чтением кэша отдельный поток записывает чужую идентичность. До исправления возвращалась подмена, после — владелец токена из БД. На 100 прогретых чтениях число SELECT сессии сократилось с 200 до 100. Задержка в измеренном запуске не улучшилась: среднее 5,154 → 6,867 мс. Поэтому корректный вывод — устранена подмена и лишний SELECT, ускорение не доказано. - -Ограничения: локальный benchmark уровня Store, последовательное измерение до/после, искусственно заданное конкурентное чередование; подмена требует возможности испортить кэш. Это не нагрузочное исследование HTTP и не доказательство защиты от всех гонок. Отдельная проверка cache miss моделирует потерю ключа, а persistence-тест действительно перезапускает сервисы. История сообщений читается непосредственно из PostgreSQL; кэш истории и защита от stampede не реализованы. Полную оценку определяет преподаватель по всем требованиям README. - -## 13. Короткие ответы на вопросы преподавателя - -**Почему PostgreSQL?** Нужны постоянное хранение, связи, ограничения, транзакции и индексированная история. PostgreSQL также прямо требуется заданием. - -**Зачем Valkey, если есть БД?** По замыслу — быстрый TTL-кэш сессий с восстановлением из БД. В текущей реализации выигрыш скорости ещё нужно доказать. - -**Что будет после FLUSHDB?** Исчезнут кэш-ключи. Действующие сессии останутся в PostgreSQL и смогут заполнить кэш снова. - -**Почему нельзя доверять только TTL?** Он ограничивает время жизни ключа, но не отражает немедленный logout и не обеспечивает сохранность при рестарте. - -**Почему не SHA-256 для пароля?** Он слишком быстр для перебора. Argon2id делает каждую попытку затратной по памяти и вычислениям. - -**Почему не зашифровать пароли?** Для проверки входа не нужно восстанавливать исходный пароль. Password KDF позволяет проверять кандидата без хранения обратимо восстанавливаемого секрета. - -**Почему 404 для чужого чата?** Так требует контракт: ответ не подтверждает постороннему существование ресурса. - -**Как исключена подмена отправителя?** sender_id берётся из серверной сессии, после чего проверяется членство в чате. Поэтому корректность данных самой сессии критична. - -**Почему время не является ключом?** Несколько сообщений могут иметь одинаковое время. Для полного порядка добавляется UUID. - -**Гарантирует ли индекс быструю страницу?** Только подходящий реальный план подтверждает эффективное использование индекса. Наличие индекса отдельно этого не доказывает. - -**Что произойдёт при ошибке в середине создания чата?** Транзакция откатится, частичный результат не зафиксируется. - -**Что гарантирует UNIQUE при двух регистрациях?** Одинаковый username не будет зафиксирован у двух пользователей, даже если запросы пришли одновременно. - -**Чем рестарт отличается от аварии хоста?** Проверка рестарта сохраняет хранилище. Потеря хоста или диска требует отдельных механизмов резервирования и восстановления. - -**Может ли один тест доказать оценку «5»?** Нет. Нужны все нижние уровни и законченный эксперимент с гипотезой, конкурентным сценарием, сравнением результатов и ограничениями. - -## 14. Что повторить перед защитой - -- Вступление из раздела 1 и роли трёх сервисов. -- Пять предметных таблиц и смысл ключей. -- Атомарность создания чата и смысл COMMIT/WAL. -- Различия Basic, Bearer, Argon2id, аутентификации и авторизации. -- Различие expiry сессии, TTL кэша и logout. -- Индекс (chat_id, created_at, id), курсор и limit+1. -- Какие проверки есть и чего они не доказывают. -- Исправления и ограничения исследования из раздела 12.