Files
mtusi2026lab2/REPORT.md
T

9.1 KiB
Raw Blame History

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

  • Автор, группа: Бушков Евгений, БВТ2301
  • Целевая оценка: 4
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, psycopg 3, psycopg_pool, redis-py, argon2-cffi, PostgreSQL; помощь ИИ — генерация каркаса кода и текста отчёта, проверка и адаптация вручную.

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

Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.9+ (для тестов), make.

cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться /health/ready (healthcheck в compose)
make test BASE_URL=http://localhost:8080
make test-unit BASE_URL=http://localhost:8080
chmod +x scripts/restart.sh scripts/stop-redis.sh scripts/start-redis.sh scripts/stop-postgres.sh scripts/start-postgres.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
make test-deps BASE_URL=http://localhost:8080
make seed-history BASE_URL=http://localhost:8080
# Expiry — отдельный стенд с коротким TTL:
SESSION_TTL_SECONDS=2 docker compose --env-file .env up -d api
make test-expiry BASE_URL=http://localhost:8080
docker compose --env-file .env up -d api   # вернуть TTL=3600

Версии образов закреплены: postgres:16.4-alpine, redis:7.4-alpine, python:3.12-slim. Миграции применяются автоматически при старте API (app/db.py::apply_migrations), идемпотентно через таблицу schema_migrations.

Безопасная остановка: docker compose down (volumes сохраняются). Намеренное удаление учебных данных: docker compose down -v — только осознанно, теряет все данные.

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

  • Процессы: api (FastAPI/uvicorn), postgres (источник истины), redis (кэш сессий с TTL).
  • Источник истины: PostgreSQL. Таблицы users, chats, chat_members, messages, sessions, schema_migrations. PK/FK, UNIQUE(username), составной PK (chat_id, user_id).
  • Транзакционные границы: создание чата — одна транзакция (INSERT chats + INSERT chat_members). Создание сообщения — одна транзакция. Создание сессии — одна транзакция.
  • Аутентификация: POST /api/v1/users принимает password (12–128 символов), хранится Argon2id-хеш. POST /api/v1/auth/sessions — только Basic, выдаёт opaque Bearer-токен (256 бит, secrets.token_urlsafe(32)); в БД хранится SHA-256 от токена. DELETE /api/v1/auth/sessions/current отзывает сессию. X-User-Id игнорируется.
  • Сессии: источник истины — sessions в PostgreSQL; Redis — кэш session:<sha256> с TTL = остаток жизни сессии. При недоступности Redis — fallback на БД (не принимаем анонимов). При logout инвалидируется и БД, и кэш.
  • Пул и таймауты: psycopg_pool.ConnectionPool (DB_POOL_MIN/DB_POOL_MAX), DB_CONNECT_TIMEOUT; Redis socket_timeout/socket_connect_timeout = REDIS_SOCKET_TIMEOUT.
  • Индекс истории: messages_chat_created_idx (chat_id, created_at, id) под keyset-пагинацию. Проверка — scripts/explain_history.sql.
  • Соответствие .env.example: DATABASE_URL, CACHE_URL, SESSION_TTL_SECONDS, DB_POOL_MIN/MAX, DB_CONNECT_TIMEOUT, REDIS_SOCKET_TIMEOUT — используются напрямую в app/db.py, app/sessions.py, app/main.py.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (уровень 3) make test PASS: lab2 public API scenario вывод консоли
Persistence (уровень 3) make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session вывод консоли
Миграции с нуля docker compose down -v && docker compose up -d --build API стартует, schema_migrations содержит 001/002 docker compose exec postgres psql -U messenger -c "select * from schema_migrations"
Redis используется для сессий с TTL docker compose exec redis redis-cli TTL session:<hash> TTL > 0, уменьшается вывод консоли
Параметризованные запросы код app/store.py, app/sessions.py все запросы через %s исходники
Ограниченный пул и таймауты app/db.py, app/main.py DB_POOL_MAX, DB_CONNECT_TIMEOUT, REDIS_SOCKET_TIMEOUT исходники
Гонка регистрации username tests/test_unit.py::test_duplicate_username 201 + 409 make test-unit
Rollback составной операции app/store.py::create_chat — conn.transaction() при ошибке вставки участника чат не создаётся исходники
Индекс истории + EXPLAIN make seed-history (10 000 сообщений) Index Scan по messages_chat_created_idx evidence/explain.txt
Expiry при коротком TTL SESSION_TTL_SECONDS=2 docker compose up -d api + make test-expiry 401 после истечения, повторный вход работает tests/test_expiry.py
Logout tests/test_unit.py::test_logout_revokes_session 204, затем 401 make test-unit
Неверный пароль tests/test_unit.py::test_wrong_password_returns_401 401 make test-unit
Недоступность Redis make test-deps (тест test_redis_down_falls_back_to_db) валидный токен 200, аноним 401, /health/ready 200 tests/test_dependency_failure.py
Недоступность БД make test-deps (тест test_postgres_down_returns_503) /health/ready 503 unavailable, бизнес-запрос 500/503 без утечек tests/test_dependency_failure.py
EXPLAIN на ≥10 000 сообщений make seed-history Index Scan по messages_chat_created_idx evidence/explain.txt

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

Гипотеза: при остановке Redis API продолжает обслуживать запросы (кэш — не источник истины); при остановке PostgreSQL /health/ready возвращает 503, бизнес-запросы — 500/503 без утечки деталей.

Hardware: локальная машина разработчика (Windows 11, Docker Desktop). Объём данных: синтетические пользователи/чаты/сообщения из тестов. Профиль нагрузки: tests/load.py --duration 30 --concurrency 4 (closed-loop, ограничен клиентом).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart api postgres redis (volumes сохранены) данные и сессии сохранены PASS persistence ~5–10 с, потерь нет
docker compose stop redis API работает, сессии из БД smoke PASS восстановление после start redis
docker compose stop postgres /health/ready → 503 503 unavailable после start postgres — 200
SESSION_TTL_SECONDS=2 сессия истекает 401 после истечения, повторный вход работает —
make seed-history (10 000 сообщений) Index Scan, без Seq Scan Index Scan по messages_chat_created_idx —

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

  • Redis — кэш, не источник истины; при его недоступности latency сессий растёт (каждый запрос идёт в БД).
  • Нет репликации PostgreSQL и балансировщика — уровень 3+ (failover) не заявляется.
  • Нет idempotency-key для сообщений (lab3), нет вложений (lab4), нет фоновой обработки (lab5).
  • tests/load.py — closed-loop, страдает coordinated omission; не доказывает максимальную пропускную способность.
  • Трек 5 не выполнялся.