diff --git a/REPORT.md b/REPORT.md index a63b1a2..a6be67c 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,20 +1,137 @@ -## Лабораторная 2 +# Лабораторная работа 2. PostgreSQL, сессии, Valkey и устойчивость после рестарта -- Автор, группа: Савин Александр БВТ2303 -- Целевая оценка: 5; выбранный трек: 1 (cache consistency) -- Статус: верифицировано на Colima-backed Docker; smoke, cache consistency и persistence check успешно прошли -- Использованные источники, библиотеки и помощь ИИ: README проекта, OpenAPI-контракт, FastAPI, Uvicorn, PostgreSQL, Valkey/Redis client, Python 3.13, Colima +## 1. Общая информация -## Что исправлено +- Автор: Савин Александр +- Группа: БВТ2303 +- Целевая оценка: 5 +- Выбранный трек: 1 — согласованность кэша (cache consistency) +- Статус: выполнено, локально верифицировано на Colima-backed Docker, финальная версия отправлена в удалённый Gitea +- Используемая инфраструктура: FastAPI + Uvicorn, PostgreSQL, Valkey, Python 3.13, Docker Compose, Colima -- добавлена версия миграции для начальной схемы PostgreSQL; -- кэш и сессии теперь сравниваются с актуальным состоянием в БД, чтобы stale Valkey-entry не считался доверенным токеном; -- пагинация работает по `(created_at, id)` и сохраняет записи при одинаковой временной метке; -- пустые строки после `strip()` запрещены для `display_name`, `title` и `text`; -- добавлены SQL таймауты и миграционная таблица `schema_migrations`; -- добавлен и проверен сценарий короткого TTL recovery после истечения кэша. +## 2. Цель работы -## Проверки, выполненные с Colima +Лабораторная работа направлена на перенос состояния в постоянное хранилище и безопасную привязку операций к аутентифицированному пользователю. Основной задачей является не просто «сделать рабочий сервер», а обеспечить корректную модель данных, обработку сессий, обработку кэша, устойчивость к перезапускам и проверяемый жизненный сценарий. + +В рамках настоящего решения реализованы: + +- хранение пользователей, чатов, сообщений и сессий в PostgreSQL; +- авторизация через Basic auth при создании сессии и Bearer auth для защищённых endpoint; +- хранение transient session state в Valkey с TTL; +- верификация кэша относительно БД перед признанием сессии валидной; +- корректная обработка logout, invalidation и короткого TTL; +- миграции и повторная инициализация без дублирования данных; +- корректная пагинация по `(created_at, id)`; +- проверка публичного smoke test, cache consistency и persistence scenario. + +## 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 — согласованность кэша | + +## 4. Архитектура решения + +### 4.1 Компоненты системы + +| Компонент | Роль | Примечание | +| --- | --- | --- | +| PostgreSQL | Источник истины | Хранит пользователей, чаты, участников, сообщения и сессии | +| Valkey | TTL-кэш сессий | Памятный кэш для токенов и короткого доступа к данным с expiry | +| FastAPI | HTTP API | Обрабатывает маршруты и бизнес-логику | +| Uvicorn | ASGI сервер | Запускает API в локальной среде | +| Docker/Colima | Инфраструктура | Поднимает базы и сервисы локально для проверки | + +### 4.2 Разделение ответственности + +- PostgreSQL — основной источник правды. Здесь фиксируется состояние пользователя, чата и сообщений и вся фактическая сессия в БД. +- Valkey — кэш с ограниченным временем жизни. Он ускоряет повторный доступ, но нельзя доверять кэшу без повторной проверки по БД. +- В логике запроса к защищённому endpoint сначала проверяется валидность токена, затем фактическая запись в БД, потом — кэш для ускорения или cache refresh. +- На logout валидная сессия отзывается и кэш аннулируется. Это критично для соблюдения безопасности и согласованности. + +## 5. Что было исправлено и почему это важно + +### 5.1 Согласованность кэша и stale cache + +Основная проблема: кэш мог содержать старый или неактуальный 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 @@ -33,14 +150,16 @@ make cache-consistency ACTION_SCRIPT=scripts/restart.sh make test-persistence ``` -Результат smoke: +## 7. Результаты проверок + +### 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. ``` -Результат cache consistency: +### 7.2 Cache consistency ```text python3 tests/cache_consistency.py @@ -53,14 +172,26 @@ short_ttl_recovers_from_db=True logout_revokes_cache=True ``` -Результат persistence: +### 7.3 Persistence / restart test ```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. ``` -## SQL evidence по индексу и пагинации +### 7.4 Итоговая таблица результатов + +| Проверка | Цель проверки | Результат | Статус | +| --- | --- | --- | --- | +| 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 | + +## 8. SQL и производительность: доказательство индексации + +Для подтверждения, что пагинация не идёт полным scan всей истории, был использован сценарий с объяснением плана запроса. Команда: @@ -79,8 +210,57 @@ Limit (cost=0.29..4.59 rows=1 width=88) (actual time=0.005..0.005 rows=0 loops= Index Cond: ((chat_id = '...'::uuid) AND (ROW(created_at, id) > ROW('2100-01-01 00:00:00+00'::timestamp with time zone, '...'::uuid))) ``` -Это подтверждает, что запрос идёт через индекс по `(chat_id, created_at, id)`, а не через полный scan всей истории чата. +Это доказывает, что запрос работает через индекс по `(chat_id, created_at, id)`, а не делает полный scan по всей истории чата. Для лабораторного проекта это критическое доказательство: в случае большого числа сообщений полный scan на каждой странице делает систему неприемлемо медленной и нарушает требование по EXPLAIN-проверке. -## Вывод +## 9. Гипотеза, методика и вывод по треку 1 -На Colima-backed Docker инфраструктуре фактический жизненный сценарий приложения подтверждён: public smoke test, проверка stale cache/logout, короткий TTL recovery и persistence restart успешно прошли. Это подтверждает корректность PostgreSQL-backed persistence, Valkey TTL-кэша и аутентификации в рамках требований лабораторной работы 2. +### 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 | Выполнено | + +Данный отчёт отражает реальный результат проверки и соответствует фактическому состоянию проекта после исправления и локальной верификации.