18 KiB
Отчёт — лабораторная 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
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 сначала ставит
revoked_atв PostgreSQL, затем удаляет ключ из Redis. - 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 |
| 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 |
— |
Ограничения и следующие шаги
- Если при logout Redis недоступен, а потом вернулся с сохранёнными данными, ключ отозванной сессии может прожить до
SESSION_CACHE_TTL_SECONDS(60 c). В нашей конфигурации Redis без persistence, поэтому после его рестарта кэш пуст; окно до 60 с остаётся только при сетевом разрыве — осознанный компромисс. - При недоступном PostgreSQL сессия из кэша ещё распознаётся, но любое действие с данными получает 503.
- Durability: ответ 201 означает COMMIT в PostgreSQL с настройками по умолчанию (
synchronous_commit=on, fsync). Реплик и бэкапов нет — отказ диска с volume означает потерю данных. created_atназначает API по своим UTC-часам; при равных метках порядок задаётid. При нескольких репликах (lab3) часы разных хостов могут расходиться.- Нет rate limiting на вход (перебор паролей замедляет только Argon2id). Нет TLS: HTTP только для локального стенда с синтетическими данными.
- Трек 5 не выполнялся.