9.6 KiB
Отчёт — лабораторная 2
- Автор, группа: Козырев Матвей БВТ2301
- Целевая оценка: 5; трек 1 — согласованность кэша
- Commit/PR: TODO после публикации
- Использованные библиотеки: FastAPI 0.141.1, Uvicorn 0.40.0, asyncpg 0.31.0, argon2-cffi 25.1.0, redis 5.0.8; зафиксированы в
pyproject.tomlиuv.lock.
Запуск из чистого clone
Нужны Docker Engine с Docker Compose v2 и OpenSSL. Создайте только локальные секреты — они исключены из Git:
mkdir -p secrets
openssl rand -hex 32 -out secrets/postgres_password
awk '{printf "postgresql://messenger:%s@postgres:5432/messenger\\n", $0}' \
secrets/postgres_password > secrets/database_url
chmod 700 secrets
chmod 600 secrets/postgres_password secrets/database_url
docker compose --env-file .env.example config --quiet
docker compose --env-file .env.example up -d --build
API публикуется на http://localhost:8080. Миграции запускаются API при
старте; таблица schema_migrations не применяет уже записанную миграцию
повторно. Проверка готовности:
curl -fsS http://localhost:8080/health/ready
make test
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-grade4
Для проверки короткого TTL временно пересоздайте только API:
SESSION_TTL_SECONDS=2 docker compose --env-file .env.example up -d --force-recreate api
docker compose --env-file .env.example up -d --wait api
python3 student-tests/session_expiry.py
SESSION_TTL_SECONDS=3600 docker compose --env-file .env.example up -d --force-recreate api
План запроса истории создаётся на 10 000 синтетических сообщениях:
./scripts/explain_history.sh | tee evidence/explain-history-local.txt
Обычная остановка сохраняет учебные данные:
docker compose down
Намеренно удалить учебные данные можно только отдельной командой
docker compose down -v; она не входит в restart hook.
Архитектура и решения
HTTP-клиент → FastAPI API → asyncpg pool (1..10 соединений) → PostgreSQL
└→ миграции SQL при старте
└→ Redis cache истории (pool до 50 соединений)
PostgreSQL — источник истины для users, chats, chat_members,
messages и sessions. Named volume postgres_data хранит каталог БД.
Токен сессии создаётся через secrets.token_urlsafe(32); в БД лежит только
SHA-256 токена и время истечения. Пароли хешируются Argon2 через
argon2-cffi; plaintext и hash не попадают в API-ответы.
POST /api/v1/users требует password. POST /api/v1/auth/sessions
принимает только Basic и выдаёт opaque Bearer token. Все бизнес-endpoint
определяют пользователя только по Bearer; X-User-Id игнорируется.
Logout удаляет текущую серверную сессию. Срок действия фиксируется при
создании и задаётся SESSION_TTL_SECONDS (3600 по умолчанию).
Создание чата — одна транзакция: проверка состава пользователей, запись чата и
всех участников. Внешние ключи и уникальность username заданы миграцией.
История выбирается keyset-запросом по (created_at, id); индекс
messages_chat_created_id_idx соответствует этому запросу.
Redis кэширует только первую страницу истории. Ключ включает chat_id,
limit и history_version из PostgreSQL. В той же транзакции, что и
вставка сообщения, PostgreSQL увеличивает history_version; старый ключ
поэтому больше не читается. Redis не источник истины: при его отказе кэш
отключается в процессе API, а чтение продолжает PostgreSQL. Redis использует
AOF и named volume redis_data.
Доказательства критериев
| Критерий | Команда | Наблюдаемый результат | Статус |
|---|---|---|---|
| Контракт и синтаксис | make check |
PASS | выполнено |
| Импорт приложения и Basic parser | uv run --frozen python … |
PASS | выполнено |
| Согласованность lock-файла | uv lock --check |
PASS | выполнено |
| Публичный smoke | make test |
PASS: lab2 public API scenario |
evidence/smoke-2026-10-08.txt |
| Persistence | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session |
evidence/persistence-2026-10-08.txt |
| Redis cache | make test-grade4; redis-cli --scan |
read-after-write без stale read; создан ключ history:first:… |
evidence/redis-cache-2026-10-08.txt |
| Гонка и rollback | make test-grade4 |
Ровно одна регистрация успешна; неуспешный чат не виден | evidence/grade4-checks-2026-10-08.txt |
| TTL и зависимости | make test-grade4; TTL=2 |
Expired session → 401; Redis fallback проходит smoke; DB readiness → 503 | evidence/grade4-checks-2026-10-08.txt |
| Индекс истории | ./scripts/explain_history.sh |
Index Scan, 50 строк, shared hit=3 | evidence/explain-history-2026-10-08.txt |
| Трек 5: stampede | student-tests/cache_stampede.py |
20 SQL-загрузок → 1 при 20 читателях | evidence/track1-cache-stampede-2026-10-08.txt |
| Трек 5: restart cache | student-tests/cache_recovery.py |
История не изменилась после restart Redis | evidence/track1-cache-stampede-2026-10-08.txt |
Трек 5 — согласованность кэша
Гипотеза. При холодном ключе 20 одновременных запросов первой страницы
истории создают 20 SQL-загрузок без координации. Redis-lock SET NX EX 2
оставит одну загрузку; остальные запросы ждут заполнения ключа до 1 секунды.
Методика. Для каждой точки API запускался с одним и тем же Compose-стендом:
PostgreSQL 17.6, Redis 7.4.2, Python 3.12.12, Docker Engine 29.8.0, 10 CPU и
16 GiB RAM. student-tests/cache_stampede.py создаёт новый чат с одним
сообщением и одновременно запускает 20 GET первой страницы. SQL-загрузка
считается по записи history_sql_page_load в журнале API. Baseline запускает
API с CACHE_STAMPEDE_PROTECTION=false; затем тот же сценарий повторяется с
true. Данные, чат и ключ каждый раз новые.
| Точка | Успешных чтений | SQL-загрузок | p50 / p95 / max latency |
|---|---|---|---|
| Без координации | 20 | 20 | 111.620 / 113.364 / 113.603 ms |
| Redis-lock | 20 | 1 | 157.831 / 159.477 / 159.549 ms |
Число SQL-загрузок уменьшилось на (20 − 1) / 20 × 100 = 95%. В этой
единственной точке p50 вырос на 157.831 − 111.620 = 46.211 ms, поскольку
ожидающие запросы опрашивают кэш с интервалом 50 ms. Это не оценка
производительности системы в целом: измерение одноразовое, closed-loop,
включает HTTP-клиент и не отделяет влияние Docker Desktop.
read-after-write проверяет student-tests/lab4_checks.py: страница сначала
кэшируется, затем создаётся сообщение, и следующий GET содержит оба сообщения.
student-tests/cache_recovery.py заполняет кэш, перезапускает Redis и
проверяет неизменность ответа. Raw results и команды сохранены в evidence.
Ограничения и следующие шаги
Результат трека относится к одному локальному прогону с 20 читателями; для
обобщения нужны повторы, нагрузка других размеров и измерение CPU/RAM
контейнеров. Redis-lock не заменяет PostgreSQL: при недоступности Redis API
безопасно обходит кэш, а при недоступности PostgreSQL readiness возвращает 503.
Публичные smoke и persistence выполнены на локальном Compose-стенде 2026-10-08.
При фиксации работы в PR сохраните их stdout в evidence/ без токенов и
паролей.