Files
mtusi2026lab2/REPORT.md
T

18 KiB
Raw Blame History

Лабораторная работа 2. PostgreSQL, сессии, Valkey и устойчивость после рестарта

1. Общая информация

  • Автор: Савин Александр
  • Группа: БВТ2303
  • Целевая оценка: 5
  • Выбранный трек: 1 — согласованность кэша (cache consistency)
  • Статус: выполнено, локально верифицировано на Colima-backed Docker, финальная версия отправлена в удалённый Gitea
  • Используемая инфраструктура: FastAPI + Uvicorn, PostgreSQL, Valkey, Python 3.13, Docker Compose, Colima

2. Цель работы

Лабораторная работа направлена на перенос состояния в постоянное хранилище и безопасную привязку операций к аутентифицированному пользователю. Основной задачей является не просто «сделать рабочий сервер», а обеспечить корректную модель данных, обработку сессий, обработку кэша, устойчивость к перезапускам и проверяемый жизненный сценарий.

В рамках настоящего решения реализованы:

  • хранение пользователей, чатов, сообщений и сессий в 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.

Применённый стартовый набор команд:

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
make check
make validate
make test
make cache-consistency
ACTION_SCRIPT=scripts/restart.sh make test-persistence

7. Результаты проверок

7.1 Smoke test

python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.

7.2 Cache consistency

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

7.3 Persistence / restart test

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 Итоговая таблица результатов

Проверка Цель проверки Результат Статус
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 всей истории, был использован сценарий с объяснением плана запроса.

Команда:

cd /Users/alexander/Documents/вп/mtusi2026lab2
. .venv/bin/activate
python3 scripts/explain_pagination.py | head -n 40

Фрагмент вывода:

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)))

Это доказывает, что запрос работает через индекс по (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 Выполнено

Данный отчёт отражает реальный результат проверки и соответствует фактическому состоянию проекта после исправления и локальной верификации.