Files
mtusi2026lab2/REPORT.md
T
drunkdiente 0dd3ecfb7c Реализовать лабораторную 2: API мессенджера с PostgreSQL и кэшем сессий
FastAPI-сервис с opaque-сессиями (Argon2id, SHA-256 фингерпринт), PostgreSQL как источником истины, Valkey как кэшем сессий, keyset-пагинацией, пулом соединений и таймаутами. Добавлены миграции, compose-стенд, скрипт рестарта, студенческие проверки и evidence.
2026-10-23 12:17:00 +03:00

14 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Ким Владимир, БВТ2302
  • Целевая оценка; 3 (Redis/Valkey как кэш сессий, параметризованные запросы и пул, индекс истории с EXPLAIN на 10 000 сообщениях, автоматические проверки expiry/logout/гонки/отказа).
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки: FastAPI 0.115.6, Uvicorn 0.34.0, psycopg2-binary 2.9.10, redis 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16.4, Valkey 7.2.6. Все решения проверены запуском стенда. Первичные материалы: см. README курса.

Запуск из чистого clone

Prerequisites: Docker Engine/Desktop с Compose v2 и доступом к сети для сборки образа. Версии зафиксированы: Python 3.12.7-slim (образ python:3.12.7-slim), postgres:16.4, valkey/valkey:7.2.6. Никаких хостовых БД/Redis не требуется.

# 1. Локальные синтетические секреты (файл в .gitignore, в Git не попадает)
cp .env.example .env
#   заполните как минимум POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB,
#   APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/SESSION_STORE, DB_POOL_MIN/DB_POOL_MAX

# 2. Проверка конфигурации и сборка
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

# 3. Дождаться готовности (миграции применяются автоматически при старте API)
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done

# 4. Проверки
python scripts/check_contract.py                 # = make check
python tests/smoke.py --base-url http://localhost:8080   # = make test
python tests/resilience.py --mode persistence --action-script scripts/restart.sh \
    --base-url http://localhost:8080             # = make test-persistence
python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json

# 5. Безопасная остановка (volumes сохраняются)
docker compose --env-file .env stop

# 6. Намеренное удаление только учебных данных
docker compose --env-file .env down -v

На Windows хук scripts/restart.sh (POSIX) запускается через scripts/restart.cmd (та же команда docker compose restart); проверка сохранности при этом эквивалентна. make в среде разработки отсутствовал, поэтому в отчёте приведены эквивалентные python-команды.

Архитектура и решения

Клиент --HTTP--> API (FastAPI/Uvicorn, python:3.12.7-slim, non-root)
                     |  psycopg2 pool (bounded, statement_timeout)
                     v
             PostgreSQL 16.4  <-- источник истины: users, chats, chat_members,
             (named volume pgdata)   messages, sessions, schema_migrations
                     ^
                     |  cache-aside (TTL = остаток жизни сессии)
             Valkey 7.2.6 (named volume valkeydata, AOF)  <-- кэш сессий
  • Источник истины — PostgreSQL. Пользователи, чаты, членство, сообщения и сессии хранятся в БД, поэтому данные и действующие сессии переживают рестарт API и хранилищ.
  • Сессии: opaque-токен (secrets.token_urlsafe(32), ≥256 бит). В БД пишется только SHA-256-фингерпринт токена (сам токен не хранится). Срок жизни задаёт SESSION_TTL_SECONDS (по умолчанию 3600). Отзыв — revoked_at + удаление ключа из кэша.
  • Пароли: Argon2id (argon2-cffi). Пароль никогда не возвращается в User.
  • Valkey/Redis — кэш, а не источник истины. При каждом аутентифицированном запросе сначала проверяется кэш (sess:<sha256>); промах или недоступность кэша → запрос к PostgreSQL. TTL кэша равен остатку жизни сессии, инвалидация — при logout/отзыве. Так как истина в БД, потеря кэша не приводит к потере данных, а анонимный запрос не принимается доверенным.
  • Транзакционные границы: регистрация пользователя и создание сессии — одиночные INSERT; создание чата — одна транзакция (проверка существования участников + INSERT чата + INSERT участников); отправка сообщения — проверка членства и INSERT в одной транзакции. Гонка регистрации одинакового username разрешается уникальным ограничением users.username, нарушение перехватывается и превращается в 409 conflict.
  • Ограничения и валидация: длина и формат полей проверяются приложением (код-поинты) и дублируются CHECK-ограничениями БД; лишние поля и неверные типы → 400; additionalProperties:false соблюдается для всех ответов.
  • Пагинация истории — keyset по (created_at, id) по возрастанию, курсор непрозрачный и привязан к ресурсу (chat_id/user_id); выборка LIMIT n+1 определяет next_cursor без полного сканирования истории.

Соответствие .env.example реальной конфигурации

.env.example Реальная переменная Смысл
APP_HOST / APP_PORT то же bind-адрес/порт Uvicorn
APP_ENV то же метка окружения (лог)
SESSION_TTL_SECONDS то же TTL сессии, по умолчанию 3600
SESSION_STORE то же postgres или postgres+redis
DATABASE_URL_FILE DATABASE_URL или DATABASE_URL_FILE DSN PostgreSQL (поддержаны оба способа)
CACHE_URL_FILE CACHE_URL или CACHE_URL_FILE DSN Valkey/Redis (кэш)
— DB_POOL_MIN / DB_POOL_MAX границы пула соединений

Приложение читает значение напрямую из переменной, а при её отсутствии — из файла, указанного в *_FILE (совместимо с Docker secrets). Секретов в Git нет: .env в .gitignore.

Роли инфраструктуры

Роль service Образ (пиннинг) healthcheck volume сеть credentials
api api сборка из Dockerfile (python:3.12.7-slim) HEALTHCHECK + /health/live — backend env из .env
postgres postgres postgres:16.4 pg_isready pgdata backend POSTGRES_* из .env
cache valkey valkey/valkey:7.2.6 valkey-cli ping valkeydata (AOF) backend CACHE_URL из .env

Bootstrap: миграции migrations/*.sql применяются самим API при старте (таблица schema_migrations, advisory lock). Повторный запуск не дублирует данные.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура skeleton python scripts/check_contract.py PASS: offline skeleton structure... evidence/check.txt
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario evidence/smoke.txt
Данные и сессия переживают рестарт python tests/resilience.py --mode persistence --action-script scripts/restart.sh ... PASS: persistence preserved confirmed data and existing session; StartedAt всех контейнеров изменился, volumes сохранены evidence/persistence.txt
PostgreSQL = источник истины, ключи, уникальность, миграции с нуля миграция migrations/0001_init.sql + лог старта API applied migration 0001_init; таблицы/индексы создаются на пустом volume evidence/persistence.txt
Атомарное создание чата код store.create_chat + одна транзакция rollback при неизвестном участнике; гонка username → 409 student-tests/test_lab2.py
Basic только на POST /auth/sessions, остальное — Bearer, expiry и отзыв student-tests/test_lab2.py wrong password 401 (Basic), X-User-Id не работает, logout 204→401 (Bearer) evidence/cache_outage.txt
Истечение сессии при коротком TTL --expiry c SESSION_TTL_SECONDS=2 PASS: session expired after 2s TTL evidence/expiry_check.txt
Параметризованные запросы, пул, таймауты (уровень 4) код db.py/store.py пул ThreadedConnectionPool, statement_timeout, все SQL параметризованы код
Индекс истории обоснован EXPLAIN на ≥10 000 сообщений (уровень 4) student-tests/perf_explain.sql Index Scan using messages_chat_created_id_idx, 5 буферов, 0.028 ms против Seq Scan 361 буфер, 2.550 ms evidence/explain.txt, evidence/explain_no_index.txt
Отказ Redis/БД (уровень 4) --cache-check и stop postgres аутентификация живёт без кэша; /health/ready и аутентифицированные запросы → 503 unavailable при недоступной БД, /health/live → 200 evidence/cache_outage.txt, evidence/dependency_outage.txt

Эксперименты и отказы

Оборудование: один Docker-host (Windows, Docker Desktop 29.4.3, Linux engine), образы без явных CPU/RAM-лимитов. Прогрев не выделялся; данные синтетические.

Нагрузка (closed-loop POST сообщений, tests/load.py, см. evidence/load.json):

Профиль Длительность Concurrency Успешные RPS Ошибки p50 p95 p99
4 воркера 15 с 4 236.6 0 (0.0) 16.0 ms 32.0 ms 47.0 ms

Ограничения измерения: генератор закрытого контура ограничен клиентом и подвержен coordinated omission; latency только по успешным запросам; это пропускная способность HTTP-подтверждений, а не счётчик COMMIT.

План запроса (10 000 сообщений в чате, keyset-страница):

Вариант План Buffers Execution
С индексом Index Scan using messages_chat_created_id_idx shared hit=5 0.028 ms
Без индекса (indexscan off) Seq Scan + Sort shared hit=361 2.550 ms

Отказы:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart (api+postgres+valkey, volumes сохранены) данные и прежний токен доступны те же чат/сообщение по прежнему токену рестарт всех контейнеров; потерь нет
Остановка Valkey (кэш) аутентификация продолжает работать через БД /users/me по прежнему токену → 200 кэш пересоберётся сам; потерь нет
Остановка PostgreSQL /health/ready деградирует /health/ready → 503 unavailable, аутентифицированный запрос → 503 unavailable, /health/live → 200 200 после старта БД; потерь нет

Ограничения и следующие шаги

  • Учебное упрощение: один Docker-host; эксперимент не даёт отказоустойчивости к потере самого host, а единственная БД и отсутствие LB/реплик не делают стенд HA. Redis выбран как кэш, а не единственное хранилище сессий, поэтому его потеря безопасна.
  • Durability PostgreSQL определяется настройками по умолчанию образа; отдельно проверялось сохранение при рестарте контейнеров с сохранением volume, а не при потере диска.
  • Не реализовано (вне минимума этой лабы): изменение участников/удаление сообщений, rate limiting, идемпотентность отправки (Idempotency-Key) и X-Instance-Id — это переходы lab3+.
  • Уровень 4 подтверждён частично: кэш сессий, пул/таймауты, индекс и отказы проверены; отдельный «трек 5» (согласованность кэша или backup/restore) не заявлен и не измерялся.