FastAPI-сервис с opaque-сессиями (Argon2id, SHA-256 фингерпринт), PostgreSQL как источником истины, Valkey как кэшем сессий, keyset-пагинацией, пулом соединений и таймаутами. Добавлены миграции, compose-стенд, скрипт рестарта, студенческие проверки и evidence.
14 KiB
Отчёт — лабораторная 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) не заявлен и не измерялся.