diff --git a/DEFENSE_THEORY.md b/DEFENSE_THEORY.md new file mode 100644 index 0000000..ecda3bb --- /dev/null +++ b/DEFENSE_THEORY.md @@ -0,0 +1,265 @@ +# Теория к защите лабораторной № 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. diff --git a/Dockerfile b/Dockerfile index 6bafd8e..b0e6fd4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,5 +11,6 @@ WORKDIR /app COPY requirements.txt /app/requirements.txt RUN pip install --no-cache-dir -r /app/requirements.txt COPY app.py /app/app.py +COPY migrations /app/migrations EXPOSE 8080 CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"] diff --git a/Makefile b/Makefile index 9fd0478..d25bf0a 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) -.PHONY: help check validate test load test-persistence cache-consistency +.PHONY: help check validate test load test-persistence cache-consistency test-storage research-cache help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; cache-consistency: cache TTL/stale-session proof" @@ -21,6 +21,12 @@ test: cache-consistency: $(PYTHON) tests/cache_consistency.py +test-storage: + $(PYTHON) tests/storage_regression.py + +research-cache: + $(PYTHON) scripts/research_cache.py + load: $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) diff --git a/REPORT.md b/REPORT.md index 18d896c..2c242ea 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,266 +1,133 @@ # Лабораторная работа 2. -## 1. Общая информация +## Автор и состояние -- Автор: Савин Александр -- Группа: БВТ2303 -- Целевая оценка: 5 -- Выбранный трек: 1 — согласованность кэша -- Статус: выполнено, локально верифицировано на Colima-backed Docker, финальная версия отправлена в удалённый Gitea -- Используемая инфраструктура: FastAPI + Uvicorn, PostgreSQL, Valkey, Python 3.13, Docker Compose, Colima +- Автор: Савин Александр, БВТ2303. +- Целевая оценка: 5, трек 1 — согласованность кэша. +- Последняя локальная проверка исправлений: 24 октября 2026 года. +- Среда: macOS, Colima/Docker, docker-compose; API в образе Python 3.11, локальные исследовательские скрипты — Python 3.13. +- Исправления подготовлены для ветки master репозитория healby/mtusi2026lab2, связанной с PR №63. +- При подготовке исправлений, тестов и учебного конспекта использовался Codex. Публичный контракт и публичные smoke/resilience-тесты не изменялись. -## 2. Цель работы +## Исправление замечания PR №63, комментарий №436 -Лабораторная работа направлена на перенос состояния в постоянное хранилище и безопасную привязку операций к аутентифицированному пользователю. Основной задачей является не просто «сделать рабочий сервер», а обеспечить корректную модель данных, обработку сессий, обработку кэша, устойчивость к перезапускам и проверяемый жизненный сценарий. +Замечание: действительный токен пользователя A при конфликтующей, ещё не истёкшей записи session:T в Valkey возвращал пользователя B, в том числе во всех восьми параллельных запросах. [Исходный комментарий](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/63#issuecomment-436). -В рамках настоящего решения реализованы: +Причина: прежний код сверял действительность сессии в PostgreSQL, но возвращал user_id и user из кэша без сравнения с БД. Исправление в Store.get_session_by_token/get_cached_session: PostgreSQL определяет возвращаемую идентичность; несовпадающий кэш удаляется и восстанавливается из авторитетной записи. Повторный SELECT сессии устранён. -- хранение пользователей, чатов, сообщений и сессий в PostgreSQL; -- авторизация через Basic auth при создании сессии и Bearer auth для защищённых endpoint; -- хранение transient session state в Valkey с TTL; -- верификация кэша относительно БД перед признанием сессии валидной; -- корректная обработка logout, invalidation и короткого TTL; -- миграции и повторная инициализация без дублирования данных; -- корректная пагинация по `(created_at, id)`; -- проверка публичного smoke test, cache consistency и persistence scenario. +В tests/cache_consistency.py добавлены проверки конфликтующего payload с expires_at=2100 год, восьми параллельных GET /api/v1/users/me, повреждённой записи и повторного заполнения кэша после logout. В последнем запуске на исправленном контейнере все восемь запросов вернули владельца токена A: concurrent_identity_checks=8/8. Отдельно проверены forged_identity_rejected=True, malformed_cache_recovers=True, repopulated_revoked_cache_rejected=True. Это дополняет прежнюю проверку истёкшего payload, которая не покрывала замечание №436. -## 3. Требования README и соответствие реализации +## Архитектура и схема -| Критерий | Что требовалось по README | Реализация в проекте | -| --- | --- | --- | -| Хранение состояния | PostgreSQL как источник истины | Используется PostgreSQL для пользователей, чатов, сообщений, участников и сессий | -| Аутентификация | Basic для POST /auth/sessions, Bearer для защищённых операций | Реализованы Basic/Bearer flow и привязка токена к пользователю | -| Сессии | TTL, expiry, logout, запись/отзыв | Session cache в Valkey с TTL, логика logout и очистка кэша | -| Устойчивость | данные переживают restart, volumes и migrations | Применяются миграции, persistence-скрипт и валидный restart-контроль | -| Redis/Valkey | должен быть использован осмысленно | Valkey применён как session cache, а не как единственный источник истины | -| Параметры SQL | таймауты, pool, safe queries | Добавлены statement/lock timeouts, безопасные DB запросы | -| Индексы и пагинация | запросы должны быть индексированными, не полным scan | Используется индекс по `(chat_id, created_at, id)` | -| Проверки | smoke + persistence + evidence | Запущены и зафиксированы smoke, cache consistency и persistence | -| Трек 5 | выбрать и доказать один эксперимент | Выбран трек 1 — согласованность кэша | +FastAPI/Uvicorn обслуживает REST API. PostgreSQL 16 — источник истины для пользователей, чатов, участников, сообщений и сессий. Valkey 8 хранит JSON-кэш сессий под session:. История сообщений читается непосредственно из PostgreSQL. -## 4. Архитектура решения +Миграция migrations/001_initial_schema.sql задаёт PK, FK, UNIQUE username/token, составной PK членства и индексы. Store.init ведёт schema_migrations и пропускает применённые версии. Миграции включены в Docker-образ. Создание чата и всех участников — одна транзакция; исключение приводит к rollback. -### 4.1 Компоненты системы +SQL параметризован. psycopg_pool.ConnectionPool ограничивает количество соединений: min_size=1, DB_POOL_MAX_SIZE=10 по умолчанию, timeout=5 секунд, max_waiting=20. На соединениях заданы connect_timeout=5 секунд, statement_timeout=5000 мс и lock_timeout=500 мс. Пул открывается при старте API и закрывается при shutdown. Операции не удерживают соединение при повторном получении другого соединения; smoke отдельно прошёл при DB_POOL_MAX_SIZE=1. -| Компонент | Роль | Примечание | -| --- | --- | --- | -| PostgreSQL | Источник истины | Хранит пользователей, чаты, участников, сообщения и сессии | -| Valkey | TTL-кэш сессий | Памятный кэш для токенов и короткого доступа к данным с expiry | -| FastAPI | HTTP API | Обрабатывает маршруты и бизнес-логику | -| Uvicorn | ASGI сервер | Запускает API в локальной среде | -| Docker/Colima | Инфраструктура | Поднимает базы и сервисы локально для проверки | +## Аутентификация и сессии -### 4.2 Разделение ответственности +Регистрация использует библиотечный Argon2id: time_cost=3, memory_cost=65536 KiB, parallelism=2, hash_len=32, salt_len=16. Basic принимается только при создании сессии. Токен генерируется secrets.token_urlsafe(32); защищённые операции требуют Bearer и проверяют членство в чате. -- PostgreSQL — основной источник правды. Здесь фиксируется состояние пользователя, чата и сообщений и вся фактическая сессия в БД. -- Valkey — кэш с ограниченным временем жизни. Он ускоряет повторный доступ, но нельзя доверять кэшу без повторной проверки по БД. -- В логике запроса к защищённому endpoint сначала проверяется валидность токена, затем фактическая запись в БД, потом — кэш для ускорения или cache refresh. -- На logout валидная сессия отзывается и кэш аннулируется. Это критично для соблюдения безопасности и согласованности. +Сессия хранит expires_at и revoked_at в PostgreSQL. При каждом запросе выполняется один SELECT сессии с JOIN пользователя. Если сессия истекла или отозвана, кэш не даёт доступ. Если сессия действительна, кэш сравнивается с авторитетными данными целиком; повреждённое или несовпадающее значение заменяется. Возвращаются данные из БД, поэтому чужой user_id из кэша не используется. -## 5. Что было исправлено и почему это важно +TTL кэша рассчитывается из оставшегося времени сессии; он не продлевает expires_at. Logout фиксирует revoked_at, затем удаляет кэш. RedisError приводит к обходу кэша, а недоступность PostgreSQL не позволяет подтвердить сессию. Для OperationalError, включая ошибки пула, API формирует 503. Health/live проверяет процесс, health/ready — PostgreSQL; Valkey не является обязательным для доступности. -### 5.1 Согласованность кэша и stale cache +Важно: кэш не устраняет обязательный SELECT сессии. Преимущество кэша относительно решения вообще без Valkey не доказано. -Основная проблема: кэш мог содержать старый или неактуальный payload сессии, который приложение ошибочно принимало за действительный. +## Воспроизводимый запуск -Исправление: - -- перед допуском к защищённому endpoint сверяется актуальная сессия из БД; -- если запись в кэше устарела, отсутствует, конфликтует с БД или была отозвана, запрос отклоняется; -- при logout токен и кэшовая запись удаляются синхронно. - -Следствие: - -- stale payload больше не считается доверенным; -- возможен корректный recovery, если TTL истёк, но DB всё ещё содержит действующую сессию. - -### 5.2 Короткий TTL recovery - -Проверялся сценарий, когда TTL кэша истекает раньше ожидаемого. При этом приложение должно восстанавливать состояние из БД, а не принимать устаревший кэш. - -Результат: - -- обнаружен и подтверждён short-TTL recovery; -- запросы после истечения TTL корректно возвращаются к актуальному состоянию из БД; -- кэш не приводит к ложноположительному признанию токена валидным. - -### 5.3 Пагинация по истории сообщений - -Проблема заключалась в том, что при одинаковой временной метке `created_at` логика пагинации теряла стабильность порядка и часть записей могла пропускаться или повторяться. - -Исправление: - -- курсор построен по составному ключу `(created_at, id)`; -- индекс включает `chat_id`, `created_at`, `id`; -- использовались безопасные SQL-предикаты с `WHERE ... AND (created_at, id) > (...)` вместо менее устойчивых решений. - -Это важно, потому что задача лабораторной явно проверяет корректный поток сообщений по страницам и устойчивость истории чата. - -### 5.4 Валидация входных данных - -Входные значения вида пробелов, пустых строк и значений после `strip()` были допускались в некорректном виде. - -Исправление: - -- строки приводятся к `strip()`; -- если после очистки строка пустая, запрос отвергается; -- это применимо к значениям вроде `display_name`, `title`, `text`. - -### 5.5 Миграции и версияция схемы - -Проблема: схема инициализировалась по принципу «создать, если нет», но не вела чёткий журнал миграций. - -Исправление: - -- добавлена таблица `schema_migrations`; -- включена версия миграции и механизм повторного применения без дублирования; -- схема PostgreSQL задаётся как управляемый state, а не только как ad hoc bootstrap. - -### 5.6 SQL таймауты и безопасные соединения - -Для устойчивости при задержках БД или перегрузке были настроены безопасные параметры: - -- statement timeout; -- lock timeout; -- ограниченные connection-пулы; -- безопасная параметризация запросов. - -Это закрывает часть требований по уровню 4 и снижает риск зависаний и deadlock-подобных симптомов. - -## 6. Проверка в окружении Colima - -Для подтверждения работоспособности проект был запущен в локальной среде на Colima и Docker Compose. - -Применённый стартовый набор команд: - -```bash -colima start -cd /Users/alexander/Documents/вп/mtusi2026lab2 -docker-compose up -d db valkey -. .venv/bin/activate -DATABASE_URL=postgresql://messenger:messenger@localhost:5432/messenger \ -CACHE_URL=redis://localhost:6379/0 \ -SESSION_STORE=valkey \ -SESSION_TTL_SECONDS=3600 \ -uvicorn app:app --host 0.0.0.0 --port 8080 +```sh +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt +# Подготовить локальный .env по .env.example. +docker-compose up -d --build +# Дождаться 200 от http://localhost:8080/health/ready. make check -make validate -make test -make cache-consistency -ACTION_SCRIPT=scripts/restart.sh make test-persistence +make validate PYTHON=.venv/bin/python +make test PYTHON=.venv/bin/python +make cache-consistency PYTHON=.venv/bin/python +make test-storage PYTHON=.venv/bin/python +make research-cache PYTHON=.venv/bin/python +.venv/bin/python scripts/explain_pagination.py +make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh ``` -## 7. Результаты проверок +Если установлен плагин Compose v2, эквивалентная команда — docker compose. Скрипт restart.sh поддерживает обе формы. Прямые SQL/Valkey-проверки по умолчанию используют опубликованные localhost:5432 и localhost:6379; при иных настройках задать DATABASE_URL и CACHE_URL. Для API-тестов можно задать BASE_URL. -### 7.1 Smoke test +## Результаты после исправлений -```text -python3 tests/smoke.py --base-url "http://localhost:8080" -PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. -``` +| Проверка | Результат | +| --- | --- | +| make check | PASS | +| make validate | PASS | +| Smoke на локальном API :8081 с pool max_size=1 | PASS | +| Smoke на пересобранном контейнере :8080 | PASS | +| Cache consistency на пересобранном контейнере | PASS | +| tests/storage_regression.py | 5/5 PASS | +| tests/session_expiry.py на API с SESSION_TTL_SECONDS=2 | PASS: неверный пароль, действующая сессия, затем 401 после expiry | +| EXPLAIN на 10 000 временных сообщениях | Index Scan, 3 непустые страницы | +| Полный persistence через scripts/restart.sh | PASS | -### 7.2 Cache consistency +Регрессионные тесты проверили откат составной операции при несуществующем участнике, две конкурентные регистрации одного username, обход семи сообщений с одинаковой временной меткой страницами по два, истечение сессии в БД при наличии кэша и fallback при RedisError. Созданные ими пользователи/чаты удаляются после проверки. -```text -python3 tests/cache_consistency.py -cache_key_exists=True -ttl_seconds=3599 -avg_latency_ms=15.33 -p95_latency_ms=15.63 -stale_cache_rejected=True -short_ttl_recovers_from_db=True -logout_revokes_cache=True -``` +Расширенная проверка cache_consistency подтвердила: stale_cache_rejected, forged_identity_rejected, malformed_cache_recovers, repopulated_revoked_cache_rejected, short_ttl_recovers_from_db, logout_revokes_cache. Пример последнего запуска на контейнере: avg_latency_ms=2.36, p95_latency_ms=2.49 (10 запросов; это не надёжный benchmark). -### 7.3 Persistence / restart test +Короткий TTL кэша проверяет восстановление, а не expiry сессии. Регрессионный тест отдельно сдвигает expires_at в прошлое. Дополнительно tests/session_expiry.py выполнен на временном API :8082 с SESSION_TTL_SECONDS=2: неверный пароль дал 401, действующая сессия — 200, истёкшая — 401. Полная матрица реальных остановок зависимостей пока не выполнена; имитация RedisError не заменяет её. -```text -python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080" -PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. -``` +## Индекс и пагинация -### 7.4 Итоговая таблица результатов +Индекс: messages(chat_id, created_at, id). Запрос использует WHERE chat_id = %s AND (created_at, id) > (%s, %s::uuid), ORDER BY created_at ASC, id ASC, LIMIT limit+1. Это позволяет продолжать чтение после составного ключа без OFFSET в API. Составной ключ устраняет неоднозначность одинакового created_at. -| Проверка | Цель проверки | Результат | Статус | -| --- | --- | --- | --- | -| make check | базовая проверка проекта | успешно завершилась | PASS | -| make validate | проверка OpenAPI/JSON schema | успешно завершилась | PASS | -| make test | public smoke test | успешно завершилась | PASS | -| make cache-consistency | stale cache / TTL / logout | успешно завершилась | PASS | -| ACTION_SCRIPT=scripts/restart.sh make test-persistence | restart persistence | успешно завершилась | PASS | +scripts/explain_pagination.py создаёт 10 000 строк в транзакции, измеряет страницы после позиций 0, 5000 и 9900 с LIMIT 51 и откатывает fixtures. OFFSET используется только для выбора экспериментальных границ, не в запросе истории. -## 8. SQL и производительность: доказательство индексации +| Позиция | Возвращено строк | План | shared hit | Execution Time | +| --- | --- | --- | --- | --- | +| 0 | 51 | Index Scan idx_messages_chat_created | 5 | 0.052 мс | +| 5000 | 51 | Index Scan idx_messages_chat_created | 5 | 0.025 мс | +| 9900 | 51 | Index Scan idx_messages_chat_created | 6 | 0.027 мс | -Для подтверждения, что пагинация не идёт полным scan всей истории, был использован сценарий с объяснением плана запроса. +Это локальное измерение на прогретом небольшом наборе. Оно подтверждает план конкретных страниц, но не универсальные задержки под нагрузкой. Курсор не поддерживает единый снимок между HTTP-запросами; вставки с ключом до уже пройденной границы могут быть пропущены. -Команда: +## Трек 1: конкурентная подмена данных кэша -```bash -cd /Users/alexander/Documents/вп/mtusi2026lab2 -. .venv/bin/activate -python3 scripts/explain_pagination.py | head -n 40 -``` +Гипотеза: проверка действительности токена в БД без сверки идентичности из кэша допускает возврат чужого пользователя. Исправление должно возвращать авторитетную идентичность и исключить повторный SELECT сессии. -Фрагмент вывода: +Методика scripts/research_cache.py: -```text -Limit (cost=0.29..4.59 rows=1 width=88) (actual time=0.005..0.005 rows=0 loops=1) - Buffers: shared hit=2 - -> Index Scan using idx_messages_chat_created on messages (cost=0.29..60.56 rows=14 width=88) (actual time=0.005..0.005 rows=0 loops=1) - Index Cond: ((chat_id = '...'::uuid) AND (ROW(created_at, id) > ROW('2100-01-01 00:00:00+00'::timestamp with time zone, '...'::uuid))) -``` +1. Создать двух тестовых пользователей и действующую сессию первого. +2. В отдельной изолированной функции воспроизвести прежний алгоритм: SELECT сессии, чтение кэша, повторный SELECT действительности, возврат кэша. +3. Измерить 100 прогретых последовательных чтений каждого алгоритма, подсчитать вызовы SELECT сессии. +4. Использовать два потока и Event: после первого чтения БД, до GET кэша, записать в кэш идентичность второго пользователя с действующим expiry. +5. Убедиться, что прежний алгоритм вернул чужую идентичность, исправленный вернул владельца токена. +6. Удалить собственный ключ и проверить восстановление из БД. В конце удалить fixtures. -Это доказывает, что запрос работает через индекс по `(chat_id, created_at, id)`, а не делает полный scan по всей истории чата. Для лабораторного проекта это критическое доказательство: в случае большого числа сообщений полный scan на каждой странице делает систему неприемлемо медленной и нарушает требование по EXPLAIN-проверке. - -## 9. Гипотеза, методика и вывод по треку 1 - -### 9.1 Гипотеза - -Если Valkey содержит stale или некорректный payload сессии, приложение не должно считать его доверенным. Вместо этого необходимо: - -- перепроверить окорректность токена по БД; -- отвергнуть сессию, если она была отозвана, истекла или конфликтует с актуальным состоянием; -- восстановиться из PostgreSQL, если кэш устарел. - -### 9.2 Методика - -1. Создать пользователя и получить токен сессии. -2. Подтвердить, что session key существует в Valkey и имеет срок TTL. -3. Сымитировать stale payload или короткий TTL. -4. Выполнить защищённый запрос и убедиться, что сервис отклоняет неактуальный кэш. -5. Выполнить logout и проверить аннулирование кэша. -6. Повторить проверку после перезапуска или истечения TTL. - -### 9.3 Результат - -Проверка подтвердила, что stale cache и logout корректно обрабатываются. Сервис не принимает устаревший токен как действующий и возвращает корректный ответ на ошибку доступа или требует повторной проверки сессии в БД. Это соответствует требованиям трека 1 и является важной частью уровня 5. - -## 10. Ограничения и замечания - -- PostgreSQL остаётся источником истины; Valkey является кэшем и не должен быть единственным решением для хранения жизненно важных сессий. -- В данном отчёте подтверждён корректный уровень лабораторной проверки, но не проводился большой production benchmark на миллионах записей. -- На уровне лабораторной работы цель — доказать корректность архитектуры, а не показать scalable production-load тесты. - -## 11. Вывод - -Лабораторная работа выполнена в полном объёме. Реализована корректная архитектура с PostgreSQL в качестве источника истины, Valkey как TTL-кэшем для сессий и безопасной авторизацией через Basic/Bearer. Проблемы stale cache, invalidation, short TTL recovery, pagination и schema migration были устранены и подтверждены в реальном локальном запуске. - -Финальная верификация показывает: - -- smoke test прошёл успешно; -- проверка согласованности кэша прошла успешно; -- сценарий persistence/restart прошёл успешно; -- индексация и пагинация подтверждены через EXPLAIN-план; -- проект соответствует требованиям лабораторной работы уровня 5 с выбранным треком 1. - -## 12. Приложение: краткая сводка по критериям оценки - -| Уровень | Критерий | Статус | +| Показатель | Прежний алгоритм | Исправленный | | --- | --- | --- | -| 3 | PostgreSQL + users/chats/messages + миграции + атомарные операции | Выполнено | -| 3 | Basic/Bearer, expiry, logout | Выполнено | -| 4 | Valkey TTL, safe SQL, таймауты, повторный запуск | Выполнено | -| 4 | short TTL validation, stale cache handling | Выполнено | -| 5 | Трек 1: cache consistency | Выполнено | +| Чтений | 100 | 100 | +| SELECT сессии | 200 | 100 | +| Среднее | 5.154 мс | 6.867 мс | +| p95 | 6.739 мс | 8.805 мс | +| Чужая идентичность при конкурентной подмене | Да | Нет | -Данный отчёт отражает реальный результат проверки и соответствует фактическому состоянию проекта после исправления и локальной верификации. +Вывод: исправлена подмена и устранён лишний SELECT. Улучшение задержки не подтверждено: в этом запуске исправленный вариант медленнее. Алгоритмы измерены последовательно в локальной среде; влияние нагрузки и порядка не исключено. Baseline существует только внутри исследовательского скрипта и не публикует небезопасный API. + +Граница эксперимента: детерминированное чередование чтения и повреждения кэша, а не случайный stress-тест. Возможность записать чужое значение в кэш предполагается. Защита от cache stampede и кэш истории не реализованы. Read-after-write сообщений обеспечивается фиксацией до ответа и чтением из основной БД; smoke и persistence проверяют подтверждённые сообщения. Удаление собственного ключа моделирует cache miss, а реальный рестарт проверяется отдельно. + +## Сохранность и ограничения + +scripts/restart.sh пересоздаёт app, db, valkey с сохранением именованных volumes. Persistence-тест подтвердил, что прежний токен читает прежние подтверждённые данные после этого действия. PostgreSQL хранит основное состояние; Valkey использует AOF и RDB-настройку save 60 1. TTL не продлевается при рестарте. + +Проверка не моделирует потерю хоста, диска, volumes или аварийное отключение питания. Volume не является резервной копией. Нет координации одновременных миграторов нескольких API-реплик. Полное выполнение всех критериев уровней 4/5 и итоговая оценка требуют проверки всей рубрики README; перечисленные локальные PASS не заменяют отсутствующие эксперименты. + +## Повтор проверки короткой сессии + +В отдельном терминале запустить временный API, затем выполнить тест и остановить временный процесс: + +```sh +SESSION_TTL_SECONDS=2 .venv/bin/uvicorn app:app --host 127.0.0.1 --port 8082 +# В другом терминале: +BASE_URL=http://127.0.0.1:8082 .venv/bin/python tests/session_expiry.py +``` + +Обычный Compose-стенд сохраняет TTL=3600. Как и публичный smoke, HTTP-тест оставляет созданного синтетического пользователя в БД. diff --git a/app.py b/app.py index 370c433..d2a24ed 100644 --- a/app.py +++ b/app.py @@ -10,6 +10,7 @@ from pathlib import Path from typing import Any, Dict, List, Optional, Tuple import psycopg +from psycopg_pool import ConnectionPool import redis from argon2 import PasswordHasher from fastapi import FastAPI, Header, HTTPException, Request @@ -99,6 +100,13 @@ class Store: self.cache_url = self._resolve_cache_url() self.session_store = os.getenv("SESSION_STORE", "valkey") self.password_hasher = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=2, hash_len=32, salt_len=16) + self.pool = ConnectionPool( + self.connection_url, min_size=1, + max_size=int(os.getenv("DB_POOL_MAX_SIZE", "10")), + timeout=5, max_waiting=20, open=False, + kwargs={"connect_timeout": 5, "autocommit": False, + "options": "-c statement_timeout=5000 -c lock_timeout=500"}, + ) def _resolve_database_url(self) -> str: value = os.getenv("DATABASE_URL") @@ -121,12 +129,7 @@ class Store: return os.getenv("DEFAULT_CACHE_URL", "redis://localhost:6379/0") def connect(self): - return psycopg.connect( - self.connection_url, - connect_timeout=5, - autocommit=False, - options="-c statement_timeout=5000 -c lock_timeout=500", - ) + return self.pool.connection() def cache_client(self): return redis.Redis.from_url(self.cache_url, decode_responses=True, socket_connect_timeout=2, socket_timeout=2) @@ -148,7 +151,7 @@ class Store: except redis.RedisError: return - def get_cached_session(self, token: str, *, conn=None) -> Optional[Dict[str, Any]]: + def get_cached_session(self, token: str, *, db_session) -> Optional[Dict[str, Any]]: if self.session_store != "valkey": return None try: @@ -167,16 +170,11 @@ class Store: if not self.is_session_valid(session): client.delete(f"session:{token}") return None - if conn is None: - with self.connect() as db_conn: - db_session = self.fetch_session_by_token(token, db_conn) - else: - db_session = self.fetch_session_by_token(token, conn) - if db_session is None or not self.is_session_valid(db_session): + if session != db_session: client.delete(f"session:{token}") return None - return session - except (redis.RedisError, TypeError, ValueError): + return db_session + except (redis.RedisError, KeyError, TypeError, ValueError): return None def delete_cached_session(self, token: str) -> None: @@ -450,8 +448,8 @@ class Store: cursor_dt = datetime.fromisoformat(cursor_ts_raw.replace("Z", "+00:00")).astimezone(timezone.utc) except ValueError as exc: raise ApiError(400, "invalid_request", "invalid cursor") from exc - query += " AND (created_at > %s OR (created_at = %s AND id > %s::uuid))" - params.extend([cursor_dt, cursor_dt, cursor_id]) + query += " AND (created_at, id) > (%s, %s::uuid)" + params.extend([cursor_dt, cursor_id]) query += " ORDER BY created_at ASC, id ASC LIMIT %s" params.append(limit + 1) cur.execute(query, tuple(params)) @@ -483,7 +481,8 @@ class Store: (uuid.uuid4(), token, user_id, expires_at, self.utc_now()), ) conn.commit() - user = self.fetch_user(user_id, self.connect()) + with self.connect() as conn: + user = self.fetch_user(user_id, conn) if user is None: raise ApiError(500, "internal_error", "session user missing") session = { @@ -502,21 +501,17 @@ class Store: } def get_session_by_token(self, token: str, conn=None): - should_close = conn is None - conn = conn or self.connect() - try: - db_session = self.fetch_session_by_token(token, conn) - if db_session is None or not self.is_session_valid(db_session): - self.delete_cached_session(token) - return None - cached = self.get_cached_session(token, conn=conn) - if cached is not None: - return cached + if conn is None: + with self.connect() as db_conn: + return self.get_session_by_token(token, db_conn) + db_session = self.fetch_session_by_token(token, conn) + if db_session is None or not self.is_session_valid(db_session): + self.delete_cached_session(token) + return None + cached = self.get_cached_session(token, db_session=db_session) + if cached is None: self.cache_session(db_session) - return db_session - finally: - if should_close: - conn.close() + return db_session def revoke_current_session(self, token: str): with self.connect() as conn: @@ -545,9 +540,20 @@ app = FastAPI(title="MTUSI Messenger") @app.on_event("startup") def startup_event() -> None: + store.pool.open(wait=True, timeout=10) store.init() +@app.on_event("shutdown") +def shutdown_event() -> None: + store.pool.close() + + +@app.exception_handler(psycopg.OperationalError) +async def database_error_handler(request: Request, exc): + return await api_error_handler(request, ApiError(503, "unavailable", "database unavailable")) + + @app.middleware("http") async def request_id_middleware(request: Request, call_next): request_id = uuid.uuid4().hex @@ -683,8 +689,8 @@ async def create_session(request: Request): user = store.require_user_by_username(username, conn) if user is None or not store.verify_password(user["password_hash"], password): raise ApiError(401, "unauthorized", "invalid credentials", headers={"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'}) - session = store.create_session(user["id"], username) - return SessionOut.model_validate(session) + session = store.create_session(user["id"], username) + return SessionOut.model_validate(session) except ApiError: raise except Exception as exc: @@ -737,8 +743,8 @@ async def create_chat_endpoint(request: Request): cur.execute("SELECT id FROM users WHERE id = %s", (member_id,)) if cur.fetchone() is None: raise ApiError(400, "invalid_request", "unknown member") - chat = store.insert_chat(title, normalized, session["user_id"]) - return ChatOut.model_validate(chat) + chat = store.insert_chat(title, normalized, session["user_id"]) + return ChatOut.model_validate(chat) except ApiError: raise except Exception as exc: @@ -798,7 +804,7 @@ async def create_message(request: Request, chat_id: str): chat = store.fetch_chat(chat_id, conn) if chat is None or not store.fetch_chat_membership(chat_id, session["user_id"], conn): raise ApiError(404, "not_found", "chat not found") - message = store.insert_message(chat_id, session["user_id"], payload.text) + message = store.insert_message(chat_id, session["user_id"], payload.text) return MessageOut.model_validate(message) @@ -820,7 +826,7 @@ async def list_messages(request: Request, chat_id: str): with store.connect() as conn: if not store.fetch_chat_membership(chat_id, session["user_id"], conn): raise ApiError(404, "not_found", "chat not found") - result = store.list_messages_for_chat(chat_id, limit_int, cursor) + result = store.list_messages_for_chat(chat_id, limit_int, cursor) return {"items": [MessageOut.model_validate(item) for item in result["items"]], "next_cursor": result["next_cursor"]} diff --git a/requirements.txt b/requirements.txt index 88dee42..af6803d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,7 @@ fastapi==0.115.0 uvicorn==0.30.6 psycopg[binary]==3.3.6 +psycopg-pool==3.2.6 argon2-cffi==23.1.0 python-dotenv==1.0.1 redis==5.1.0 diff --git a/scripts/explain_pagination.py b/scripts/explain_pagination.py index df4a892..a5d9a46 100644 --- a/scripts/explain_pagination.py +++ b/scripts/explain_pagination.py @@ -18,13 +18,9 @@ def main() -> None: cur.execute("INSERT INTO chat_members(chat_id, user_id) VALUES (%s, %s)", (chat_id, user_id)) for idx in range(10000): cur.execute( - "INSERT INTO messages(id, chat_id, sender_id, text, created_at) VALUES (%s, %s, %s, %s, NOW() - INTERVAL '%s milliseconds')", + "INSERT INTO messages(id, chat_id, sender_id, text, created_at) VALUES (%s, %s, %s, %s, NOW() - %s * INTERVAL '1 millisecond')", (uuid.uuid4(), chat_id, user_id, f"msg-{idx}", idx), ) - conn.commit() - - cursor_ts = "2100-01-01T00:00:00Z" - cursor_id = str(uuid.uuid4()) explain_sql = """ EXPLAIN (ANALYZE, BUFFERS) SELECT id, chat_id, sender_id, text, created_at @@ -32,12 +28,16 @@ def main() -> None: WHERE chat_id = %s AND (created_at, id) > (%s::timestamptz, %s::uuid) ORDER BY created_at ASC, id ASC - LIMIT 1 + LIMIT 51 """ - cur.execute(explain_sql, (chat_id, cursor_ts, cursor_id)) - plan = cur.fetchall() - - print("\n".join(row[0] for row in plan)) + for offset in (0, 5000, 9900): + cur.execute("SELECT created_at, id FROM messages WHERE chat_id = %s ORDER BY created_at, id OFFSET %s LIMIT 1", (chat_id, offset)) + cursor_ts, cursor_id = cur.fetchone() + cur.execute(explain_sql, (chat_id, cursor_ts, cursor_id)) + print(f"Page after position {offset}:") + print("\n".join(row[0] for row in cur.fetchall())) + # Keep the measurement repeatable without accumulating fixtures. + conn.rollback() if __name__ == "__main__": main() diff --git a/scripts/research_cache.py b/scripts/research_cache.py new file mode 100644 index 0000000..cf062d6 --- /dev/null +++ b/scripts/research_cache.py @@ -0,0 +1,118 @@ +"""Isolated before/after session-cache experiment; never used by the API. + +Run against a local test database and Valkey. Creates and removes its own users. +The baseline reproduces the former two-read algorithm accepting cached identity. +""" +import json +import statistics +import sys +import threading +import time +import uuid +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path +from unittest.mock import patch + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from app import Store + + +def main(): + store = Store() + store.pool.open(wait=True) + store.init() + cache = store.cache_client() + users, tokens = [], [] + try: + for _ in range(2): + users.append(store.insert_user("research_" + uuid.uuid4().hex[:16], "Research", "research-password")) + result = store.create_session(users[0]["id"], users[0]["username"]) + token = result["token"] + tokens.append(token) + with store.connect() as conn: + canonical = store.fetch_session_by_token(token, conn) + forged = dict(canonical, user_id=users[1]["id"], user=users[1]) + + def baseline(): + # Former algorithm: DB validity does not authenticate cached fields. + with store.connect() as conn: + db_session = store.fetch_session_by_token(token, conn) + if not store.is_session_valid(db_session): + return None + payload = cache.get(f"session:{token}") + if payload: + cached = json.loads(payload) + if store.is_session_valid(cached): + again = store.fetch_session_by_token(token, conn) + if store.is_session_valid(again): + return cached + store.cache_session(db_session) + return db_session + + outputs = {} + for name, read in (("before", baseline), ("after", lambda: store.get_session_by_token(token))): + store.cache_session(canonical) + count = 0 + original = store.fetch_session_by_token + def counted(*args, **kwargs): + nonlocal count + count += 1 + return original(*args, **kwargs) + latencies = [] + with patch.object(store, "fetch_session_by_token", side_effect=counted): + for _ in range(100): + start = time.perf_counter() + assert read()["user_id"] == users[0]["id"] + latencies.append((time.perf_counter() - start) * 1000) + + # Force a cache writer between the DB read and cache read. + db_read, writer_done = threading.Event(), threading.Event() + first = True + def interleaved(*args, **kwargs): + nonlocal first + session = original(*args, **kwargs) + if first: + first = False + db_read.set() + if not writer_done.wait(5): + raise AssertionError("cache writer timed out") + return session + def writer(): + if not db_read.wait(5): + raise AssertionError("DB reader timed out") + try: + cache.setex(f"session:{token}", 60, json.dumps(forged)) + finally: + writer_done.set() + with ThreadPoolExecutor(max_workers=1) as executor: + future = executor.submit(writer) + with patch.object(store, "fetch_session_by_token", side_effect=interleaved): + observed = read() + future.result() + outputs[name] = { + "requests": 100, "session_selects": count, + "mean_ms": round(statistics.mean(latencies), 3), + "p95_ms": round(sorted(latencies)[94], 3), + "concurrent_wrong_identity": observed["user_id"] != users[0]["id"], + } + + # A cache restart/flush is a miss; delete only our key on shared fixtures. + cache.delete(f"session:{token}") + assert store.get_session_by_token(token)["user_id"] == users[0]["id"] + assert cache.exists(f"session:{token}") + assert outputs["before"]["concurrent_wrong_identity"] + assert not outputs["after"]["concurrent_wrong_identity"] + assert outputs["after"]["session_selects"] == 100 + print(json.dumps({"results": outputs, "cache_miss_recovered": True, + "limitations": "Local sequential Store benchmark, warm DB; deterministic interleaving; baseline is former algorithm, not a deployed insecure API. No host-failure or HTTP throughput claim."}, indent=2)) + finally: + for token in tokens: + store.delete_cached_session(token) + with store.connect() as conn: + for user in users: + conn.execute("DELETE FROM users WHERE id = %s", (user["id"],)) + store.pool.close() + + +if __name__ == "__main__": + main() diff --git a/tests/cache_consistency.py b/tests/cache_consistency.py index 68340a9..2179b55 100644 --- a/tests/cache_consistency.py +++ b/tests/cache_consistency.py @@ -8,6 +8,7 @@ import time import urllib.error import urllib.request import uuid +from concurrent.futures import ThreadPoolExecutor BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080") @@ -27,6 +28,8 @@ def http_json(method, path, *, expected=200, headers=None, body=None): payload = resp.read() if not payload: return {"status": resp.status, "headers": dict(resp.headers), "body": None} + if resp.status not in (expected if isinstance(expected, (list, tuple, set)) else [expected]): + raise AssertionError(f"Expected {expected}, got {resp.status}") return {"status": resp.status, "headers": dict(resp.headers), "body": json.loads(payload.decode("utf-8"))} except urllib.error.HTTPError as exc: payload = exc.read() @@ -91,6 +94,25 @@ def main(): assert stale_result["status"] == 200, stale_result assert stale_result["body"]["username"] == username, stale_result + # An unexpired payload must not be able to substitute another identity. + stale_payload["expires_at"] = "2100-01-01T00:00:00Z" + r.setex(key, 120, json.dumps(stale_payload)) + forged = http_json("GET", "/api/v1/users/me", headers={"Authorization": "Bearer " + token}) + assert forged["body"]["id"] == session["body"]["user"]["id"], forged + assert forged["body"]["username"] == username, forged + + r.setex(key, 120, json.dumps(stale_payload)) + def read_identity(_): + return http_json("GET", "/api/v1/users/me", headers={"Authorization": "Bearer " + token})["body"]["id"] + with ThreadPoolExecutor(max_workers=8) as executor: + identities = list(executor.map(read_identity, range(8))) + assert identities == [session["body"]["user"]["id"]] * 8, identities + + # Syntactically valid JSON with missing fields must be treated as a miss. + r.setex(key, 120, "{}") + malformed = http_json("GET", "/api/v1/users/me", headers={"Authorization": "Bearer " + token}) + assert malformed["body"]["username"] == username, malformed + r.setex(key, 1, json.dumps({ "token": token, "user_id": str(uuid.uuid4()), @@ -110,11 +132,23 @@ def main(): after_logout = http_json("GET", "/api/v1/users/me", expected=401, headers={"Authorization": "Bearer " + token}) assert after_logout["status"] == 401, after_logout + # Simulate a writer repopulating the cache after logout's DELETE. + stale_payload.update(session["body"]) + stale_payload["user_id"] = session["body"]["user"]["id"] + stale_payload["revoked_at"] = None + r.setex(key, 120, json.dumps(stale_payload)) + http_json("GET", "/api/v1/users/me", expected=401, headers={"Authorization": "Bearer " + token}) + assert not r.exists(key), "stale key after logout must be removed" + print("cache_key_exists=True") print(f"ttl_seconds={ttl}") print(f"avg_latency_ms={avg:.2f}") print(f"p95_latency_ms={p95:.2f}") print("stale_cache_rejected=True") + print("forged_identity_rejected=True") + print("concurrent_identity_checks=8/8") + print("malformed_cache_recovers=True") + print("repopulated_revoked_cache_rejected=True") print("short_ttl_recovers_from_db=True") print("logout_revokes_cache=True") diff --git a/tests/session_expiry.py b/tests/session_expiry.py new file mode 100644 index 0000000..53bf349 --- /dev/null +++ b/tests/session_expiry.py @@ -0,0 +1,34 @@ +"""Run against an isolated API started with SESSION_TTL_SECONDS=2. + +BASE_URL defaults to http://localhost:8080; do not use a normal one-hour server. +""" +import base64 +import time +import uuid +from datetime import datetime, timezone + +from cache_consistency import http_json + + +def main(): + username = "expiry_" + uuid.uuid4().hex[:16] + password = "expiry-password-123" + http_json("POST", "/api/v1/users", expected=201, + body={"username": username, "display_name": "Expiry", "password": password}) + credentials = base64.b64encode(f"{username}:{password}".encode()).decode() + http_json("POST", "/api/v1/auth/sessions", expected=401, + headers={"Authorization": "Basic " + base64.b64encode(f"{username}:wrong-password".encode()).decode()}) + result = http_json("POST", "/api/v1/auth/sessions", expected=201, + headers={"Authorization": "Basic " + credentials}) + session = result["body"] + remaining = (datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00")) - datetime.now(timezone.utc)).total_seconds() + assert 0 < remaining <= 3, "Use an isolated server with SESSION_TTL_SECONDS=2" + headers = {"Authorization": "Bearer " + session["token"]} + http_json("GET", "/api/v1/users/me", headers=headers) + time.sleep(max(0, remaining) + 0.2) + http_json("GET", "/api/v1/users/me", expected=401, headers=headers) + print("PASS: wrong password rejected; live session accepted; expired session rejected") + + +if __name__ == "__main__": + main() diff --git a/tests/storage_regression.py b/tests/storage_regression.py new file mode 100644 index 0000000..fc6740b --- /dev/null +++ b/tests/storage_regression.py @@ -0,0 +1,91 @@ +"""Run with .venv/bin/python tests/storage_regression.py against local test DB.""" +import sys +import unittest +import uuid +from concurrent.futures import ThreadPoolExecutor +from datetime import timedelta +from pathlib import Path +from unittest.mock import patch + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import app +import psycopg +import redis + + +class StorageRegression(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.store = app.Store() + cls.store.pool.open(wait=True) + cls.store.init() + + @classmethod + def tearDownClass(cls): + cls.store.pool.close() + + def setUp(self): + self.user = self.store.insert_user("reg_" + uuid.uuid4().hex[:20], "Regression", "test-password-123") + + def tearDown(self): + with self.store.connect() as conn: + conn.execute("DELETE FROM chats WHERE id IN (SELECT chat_id FROM chat_members WHERE user_id = %s)", (self.user["id"],)) + conn.execute("DELETE FROM users WHERE id = %s", (self.user["id"],)) + + def test_atomic_chat_rollback(self): + title = "rollback_" + uuid.uuid4().hex + with self.assertRaises(psycopg.errors.ForeignKeyViolation): + self.store.insert_chat(title, [self.user["id"], str(uuid.uuid4())], self.user["id"]) + with self.store.connect() as conn: + self.assertEqual(conn.execute("SELECT count(*) FROM chats WHERE title = %s", (title,)).fetchone()[0], 0) + + def test_registration_race(self): + username = "race_" + uuid.uuid4().hex[:20] + def register(_): + try: + return self.store.insert_user(username, "Race", "test-password-123")["id"] + except psycopg.errors.UniqueViolation: + return None + with ThreadPoolExecutor(max_workers=2) as executor: + results = list(executor.map(register, range(2))) + try: + self.assertEqual(sum(result is not None for result in results), 1) + finally: + with self.store.connect() as conn: + conn.execute("DELETE FROM users WHERE username = %s", (username,)) + + def test_equal_timestamp_pagination(self): + chat = self.store.insert_chat("Paging", [self.user["id"]], self.user["id"]) + ids = sorted(str(uuid.uuid4()) for _ in range(7)) + with self.store.connect() as conn: + for message_id in ids: + conn.execute("INSERT INTO messages(id, chat_id, sender_id, text, created_at) VALUES (%s,%s,%s,'same time',%s)", + (message_id, chat["id"], self.user["id"], "2026-01-01T00:00:00Z")) + cursor, actual = None, [] + while True: + page = self.store.list_messages_for_chat(chat["id"], 2, cursor) + actual.extend(item["id"] for item in page["items"]) + cursor = page["next_cursor"] + if cursor is None: + break + self.assertEqual(actual, ids) + + def test_expired_db_session_overrides_live_cache(self): + session = self.store.create_session(self.user["id"], self.user["username"]) + with self.store.connect() as conn: + conn.execute("UPDATE sessions SET expires_at = %s WHERE token = %s", + (self.store.utc_now() - timedelta(seconds=1), session["token"])) + self.assertIsNone(self.store.get_session_by_token(session["token"])) + + def test_cache_unavailable_falls_back_to_db(self): + session = self.store.create_session(self.user["id"], self.user["username"]) + try: + with patch.object(self.store, "cache_client", side_effect=redis.ConnectionError("offline")): + actual = self.store.get_session_by_token(session["token"]) + self.assertEqual(actual["user_id"], self.user["id"]) + finally: + self.store.delete_cached_session(session["token"]) + + +if __name__ == "__main__": + unittest.main(verbosity=2)