Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Санжаровский, БВТ2304
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации (ветка solution/bvt2304-sanzharovskiy)
  • Источники и библиотеки: FastAPI, uvicorn, Pydantic, psycopg 3 + psycopg-pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN, индексы), Redis persistence, RFC 7617 (Basic), RFC 6750 (Bearer).
  • Помощь ИИ: Claude (Anthropic) помогал проектировать схему, писать код, тесты и отчёт. Все решения я разобрал и могу объяснить; результаты проверок получены реальными запусками (файлы в evidence/).

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

Нужно: Docker Desktop (Compose v2), Python 3.9+ для тестов. Образы закреплены: python:3.12.7-slim-bookworm, postgres:16.4-alpine, redis:7.4.1-alpine; Python-зависимости закреплены в requirements.txt.

cp .env.example .env              # Windows: copy .env.example .env ; задать свой POSTGRES_PASSWORD
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# миграции применяются автоматически при старте API (MIGRATE_ON_START=true);
# вручную/повторно:  docker compose --env-file .env exec api python -m app.migrate
curl http://localhost:8080/health/ready          # ждём {"status":"ok"}

make check
make test                                        # без make: python tests/smoke.py --base-url http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
#   Windows: python tests\resilience.py --mode persistence --action-script scripts\restart.cmd --base-url http://localhost:8080
python student-tests/run.py      --base-url http://localhost:8080
python student-tests/race.py     --base-url http://localhost:8080
python student-tests/outage.py   --base-url http://localhost:8080
python student-tests/logout_cache.py --base-url http://localhost:8080
docker compose --env-file .env --profile ttl up -d api-ttl
python student-tests/expiry.py   --base-url http://localhost:8081
docker compose cp student-tests/rollback_check.py api:/tmp/rollback_check.py
docker compose exec api python /tmp/rollback_check.py
docker compose cp student-tests/explain.sql postgres:/tmp/explain.sql
docker compose exec postgres psql -U messenger -d messenger -f /tmp/explain.sql

Остановка без потери данных: docker compose --env-file .env down (volume pgdata сохраняется). Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volume pgdata, только осознанно).

Действий оператора, кроме создания .env, не требуется. .env и секреты в Git не попадают (.gitignore), в образ — тоже (.dockerignore).

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

клиент ──HTTP──▶ api (FastAPI/uvicorn, без состояния)
                   │  ограниченный пул psycopg (max 10), таймауты
                   ├──▶ postgres  — ИСТОЧНИК ИСТИНЫ: users, chats, chat_members, messages, sessions
                   │               volume pgdata, миграции migrations/NNNN_*.sql
                   └──▶ redis     — только КЭШ поиска сессии (ключ sess:<sha256(token)>, TTL)
Роль Service Версия Health/readiness Volume Порт Credentials
api api собирается из Dockerfile (multi-stage, non-root uid 10001) HEALTHCHECK → /health/ready нет (stateless) 127.0.0.1:8080 env из .env
postgres postgres postgres:16.4-alpine pg_isready pgdata только внутренняя сеть POSTGRES_* из .env
redis redis redis:7.4.1-alpine redis-cli ping нет (кэш, persistence выключен) только внутренняя сеть без пароля, наружу не опубликован
api-ttl api-ttl (profile ttl) тот же образ, SESSION_TTL_SECONDS=2 — — 127.0.0.1:8081 —

Схема БД (migrations/0001_init.sql): users (PK uuid, username UNIQUE + CHECK по шаблону, password_hash), chats (FK created_by), chat_members (PK (chat_id,user_id), FK на chats ON DELETE CASCADE и на users, position для порядка участников), messages (FK на chat и sender, CHECK длины текста, индекс (chat_id, created_at, id)), sessions (PK token_hash bytea, FK user, expires_at, revoked_at).

Миграции: таблица schema_migrations + pg_advisory_lock (несколько API не применят миграцию дважды), каждый файл — в своей транзакции. Повторный запуск: applied: nothing (up to date), данные не дублируются (evidence/migrations.txt).

Транзакционные границы: создание чата = INSERT chats + INSERT chat_members в одной транзакции (откат проверен rollback_check.py). Вход = проверка пароля + INSERT sessions. Сообщение — один INSERT. Регистрация защищена от гонки ограничением UNIQUE: проигравший получает 409.

Аутентификация: пароль — Argon2id (argon2-cffi, параметры библиотеки, своя соль у каждого хэша); для несуществующего пользователя проверяется хэш-заглушка, чтобы время ответа не выдавало существование username. POST /api/v1/auth/sessions принимает только Basic (без JSON), username ASCII, пароль UTF-8 12–128, двоеточие в пароле допустимо. Токен — secrets.token_urlsafe(32) (256 бит), в БД хранится только SHA-256 от него. Все остальные endpoint — только Bearer; X-User-Id игнорируется. Аутентификация — FastAPI dependency, поэтому 401 возвращается раньше валидации тела. Доступ к чату проверяется отдельно (не участник → 404).

Сессии и Redis (уровень 4):

  • Источник истины — таблица sessions в PostgreSQL. Срок задаёт expires_at = now + SESSION_TTL_SECONDS, рестарт его не продлевает.
  • Чтение Bearer: сначала Redis sess:<sha256>; промах → SELECT … WHERE revoked_at IS NULL AND expires_at > now() → запись в кэш.
  • Политика expiry кэша: TTL ключа = min(SESSION_CACHE_TTL_SECONDS=60, время до expires_at), при чтении из кэша дополнительно сверяется exp. Кэш никогда не продлевает сессию.
  • Инвалидация (logout) атомарна для БД и кэша (app/sessions.py, revoke): в одной транзакции UPDATE sessions SET revoked_at и затем DEL ключа в Redis. Если Redis не ответил (остановлен, приостановлен, таймаут), транзакция откатывается и клиент получает 503 unavailable: logout не подтверждён, сессия остаётся согласованной. 204 возвращается только когда отозвано и в БД, и в кэше, поэтому после 204 старый токен не принимается никогда, в том числе после восстановления Redis.
  • Гонка «параллельное чтение кладёт отозванную сессию в кэш после DEL» закрыта блокировкой: чтение сессии из БД идёт с SELECT … FOR SHARE и кладёт её в кэш, не отпуская строку; UPDATE в logout ждёт окончания такого чтения и удаляет ключ уже после него.
  • Redis недоступен / flush / рестарт → кэш обходится, всё читается из PostgreSQL; сессии не теряются. Поэтому Redis запущен без persistence (--save "" --appendonly no) — осознанно: он не единственное хранилище.
  • PostgreSQL недоступен → 503 unavailable (обработчик OperationalError/PoolTimeout), /health/ready = 503, /health/live = 200. Неизвестный токен никогда не принимается.

Пагинация: keyset по (created_at, id): WHERE chat_id=$1 AND (created_at,id) > ($2,$3) ORDER BY created_at, id LIMIT limit+1. Курсор — base64 JSON с привязкой к чату (курсор от другого чата → 400).

Пул и таймауты: AsyncConnectionPool(min=1, max=DB_POOL_MAX=10), ожидание свободного соединения DB_POOL_TIMEOUT=3 c, connect_timeout=3 c, statement_timeout=5000 мс, Redis socket_timeout=0.5 c. Все запросы параметризованы (%s), SQL из пользовательских строк не собирается.

Из lab1 перенесено: формат ошибок {"error":{code,message,request_id}}, X-Request-Id, 422→400, extra="forbid", graceful shutdown, multi-stage non-root Dockerfile. Изменено: хранилище в памяти + threading.Lock заменены PostgreSQL (конкурентность обеспечивают транзакции и ограничения БД), X-User-Id заменён на Basic → Bearer.

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

Переменная skeleton В решении
APP_HOST, APP_PORT используются как есть
APP_ENV только метка, на поведение не влияет
SESSION_TTL_SECONDS срок сессии (expires_at)
DATABASE_URL_FILE поддерживается (приоритетнее DATABASE_URL); в compose DATABASE_URL собирается из POSTGRES_*
SESSION_STORE=postgres сессии всегда в PostgreSQL
CACHE_URL_FILE поддерживается, также CACHE_URL (в compose redis://redis:6379/0); пусто — кэш выключен
дополнительно SESSION_CACHE_TTL_SECONDS, DB_POOL_MAX, DB_POOL_TIMEOUT, DB_STATEMENT_TIMEOUT_MS, REDIS_TIMEOUT, MIGRATE_ON_START, LOG_LEVEL

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

Стенд для приложенных файлов: 2 vCPU, 7 GiB RAM, Linux, Python 3.11, PostgreSQL 16, Redis 7; API на 127.0.0.1:8092. На этом стенде Docker-образы скачать нельзя (нет доступа к registry), поэтому сервисы запущены процессами с теми же настройками, а restart-hook делал то же самое средствами pg_ctl/redis-server. На защите те же сценарии выполняются через docker compose.

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make check, make validate, make test все три PASS evidence/smoke.txt
Данные и сессии переживают рестарт API и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh (restart.sh: docker compose restart postgres redis api, volumes не трогает) PASS: тот же токен читает те же данные evidence/persistence.txt
Миграции с нуля и повторно python -m app.migrate на пустой и на заполненной БД ['0001_init'], затем nothing (up to date), число users не изменилось evidence/migrations.txt
PK/FK, UNIQUE username, атомарный чат migrations/0001_init.sql; rollback_check.py вставка неизвестного участника падает на FK, после отката chats=0, members=0 evidence/rollback.txt
Basic только на /auth/sessions, Bearer, X-User-Id не даёт доступ student-tests/run.py (раздел «аутентификация») Basic на бизнес-endpoint → 401; X-User-Id → 401 и не подменяет владельца evidence/student-tests.txt
Неверный пароль, неизвестный user run.py одинаковый 401 + WWW-Authenticate: Basic … evidence/student-tests.txt
Logout run.py 204 → токен 401 → повторный logout 401 evidence/student-tests.txt
Logout при приостановленном Redis logout_cache.py (прогрев кэша → docker compose pause redis → logout → unpause → старый токен) logout не подтверждается (503, не 204); после восстановления повторный logout → 204, старый токен → 401. На версии до исправления: 204 и старый токен снова принимался evidence/logout-cache.txt
Тип содержимого run.py (раздел «Content-Type») корректный JSON с text/plain → 415 unsupported_media_type; без токена сначала 401; application/json; charset=utf-8 принимается; битый JSON → 400 evidence/student-tests.txt
Expiry при коротком TTL expiry.py против api-ttl (TTL=2) expires_at ≈ +2 c; до истечения 200, после — 401 (кэш не продлил сессию) evidence/expiry.txt
Гонка регистрации одного username run.py: 20 параллельных POST ровно один 201 и девятнадцать 409 evidence/student-tests.txt
Конкурентная запись race.py: 10 клиентов × 10 сообщений 100 принято, 100 уникальных в истории evidence/student-tests.txt
Индекс истории + EXPLAIN на ≥10 000 student-tests/explain.sql (60 000 сообщений, 12 000 в чате) Index Scan, 4–5 буферов, ~0.1 мс; без индекса Seq Scan, 740 буферов, 6.8 мс evidence/explain.txt
Недоступность Redis/БД outage.py без Redis всё работает в обход кэша; без PostgreSQL 503, ready 503, live 200, аноним 401; после восстановления тот же токен работает evidence/outage.txt
Пул, таймауты, параметризованный SQL app/db.py, app/config.py, app/repo.py см. раздел «Архитектура» —
Секреты не в Git .gitignore, .dockerignore, .env.example .env не коммитится, токены в evidence не печатаются —

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

EXPLAIN (evidence/explain.txt). Гипотеза: составной индекс (chat_id, created_at, id) позволяет читать страницу истории за O(limit) независимо от её позиции, без сортировки. Данные: 60 000 сообщений в 10 чатах, в целевом — 12 000; ANALYZE перед замером; всё в транзакции с ROLLBACK.

Запрос План Buffers Время
первая страница (51 строка) Index Scan messages_chat_created_id_idx 4 0.03 мс
страница из середины (keyset) Index Scan, условие ROW(created_at,id) > ROW(...) в Index Cond 5 0.09 мс
та же страница с запрещённым индексом Seq Scan + top-N sort, отброшено 54 001 строк 740 6.8 мс

Вывод: keyset-страница не читает предыдущие страницы (в отличие от OFFSET) и не сканирует всю таблицу. Цена — дополнительный индекс при записи.

Нагрузка (evidence/load.json): tests/load.py --duration 15 --concurrency 4, closed loop, POST сообщений, без прогрева: 6636 успешных, 0 ошибок, 439 RPS, p50 8.5 мс, p95 13.1 мс, p99 17.7 мс. Клиент на той же машине, есть coordinated omission, поэтому это не предел пропускной способности.

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
рестарт API + PostgreSQL + Redis (volume сохранён) данные и сессия на месте PASS resilience, тот же токен работает несколько секунд до ready; потерь нет
остановка Redis кэш обходится, сервис работает /users/me 200, запись 201, вход 201, поддельный токен 401 сразу; потерь нет (Redis — только кэш)
остановка PostgreSQL ограниченная ошибка, не зависание 503, ready 503, live 200, аноним 401 после старта БД ready 200, тот же токен читает историю
истечение TTL (2 c) 401 после срока 401 + WWW-Authenticate: Bearer —
сбой посреди создания чата откат целиком chats=0, members=0 —

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

  • Пока Redis недоступен, logout возвращает 503 и его нужно повторить после восстановления: так отзыв никогда не подтверждается без инвалидации кэша. Остальные операции в это время работают в обход кэша.
  • При недоступном PostgreSQL сессия из кэша ещё распознаётся, но любое действие с данными получает 503.
  • Durability: ответ 201 означает COMMIT в PostgreSQL с настройками по умолчанию (synchronous_commit=on, fsync). Реплик и бэкапов нет — отказ диска с volume означает потерю данных.
  • created_at назначает API по своим UTC-часам; при равных метках порядок задаёт id. При нескольких репликах (lab3) часы разных хостов могут расходиться.
  • Нет rate limiting на вход (перебор паролей замедляет только Argon2id). Нет TLS: HTTP только для локального стенда с синтетическими данными.
  • Трек 5 не выполнялся.