11 KiB
Отчёт — лабораторная 2
- Автор, группа: Bulatsev, БПИ2301 (ветка
solution/bpi2301-Bulatsev) - Целевая оценка; выбранный трек 5: 5, трек 1 — согласованность кэша
- Commit/PR: после push ветки
solution/bpi2301-Bulatsev - Источники: контракт lab2, PostgreSQL EXPLAIN, Redis AOF; код API перенесён из lab1 (Starlette/Uvicorn, валидация, cursor, graceful shutdown). Помощь ИИ — структура store/кэша и формулировки отчёта.
Запуск из чистого clone
Prerequisites: Docker 24+, Docker Compose v2, Python 3.9+ (локальные проверки), Git.
Образы: python:3.12.8-slim-bookworm (API), postgres:16.6-alpine, redis:7.4.2-alpine. Лимиты compose: API 1 CPU / 512 MiB, PostgreSQL 1 CPU / 512 MiB, Redis 0.5 CPU / 128 MiB.
git clone <fork-url>
cd mtusi2026lab2
git checkout solution/bpi2301-Bulatsev
cp .env.example .env
# при необходимости замените POSTGRES_PASSWORD в .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
Готовность: GET http://127.0.0.1:8080/health/ready → 200 {"status":"ok"}. Документация: /docs.
Проверки (другой терминал, Windows: PYTHON=python и -X utf8 уже в Makefile):
make check
make test BASE_URL=http://127.0.0.1:8080 PYTHON=python
python -m pip install -r requirements-test.txt
make test-student PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python
# Windows без Git Bash:
python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://127.0.0.1:8080
RUN_INFRA=1 python -m pytest student_tests/test_infra.py -q
python scripts/run_expiry.py
docker compose --env-file .env exec -T api python -m app.tools.explain
Миграции применяются при старте API (schema_migrations). Повторный старт не дублирует таблицы/данные.
Остановка: docker compose --env-file .env stop — volumes сохраняются.
Удаление учебных данных: docker compose --env-file .env down -v (уничтожит pg_data и redis_data).
Секреты только в локальном .env (gitignored). В Git нет tokens и паролей стенда, кроме синтетического примера в .env.example.
Архитектура и решения
Клиент ──HTTP JSON──► Starlette (lab1) ──asyncpg pool──► PostgreSQL 16
│
└── redis.asyncio ──► Redis 7 (AOF + RDB)
сессии sess:<sha256(token)> TTL
кэш hist:<chat>:<ver>:<cursor>:<limit>
Перенесено из lab1: пакет app/ на Starlette, middleware X-Request-Id, валидация JSON/Unicode, opaque cursor, Dockerfile non-root app, SIGTERM/shutting_down → 503, healthcheck.
Изменено в lab2:
| Lab1 | Lab2 |
|---|---|
InMemoryStore |
PostgreSQL: users, chats, chat_members, messages |
X-User-Id |
Authorization: Bearer (opaque token ≥256 бит) |
| регистрация без пароля | password + Argon2id |
| нет сессий | POST /api/v1/auth/sessions (Basic), DELETE .../current |
| состояние умирает с процессом | named volumes + Redis AOF |
Источник истины: PostgreSQL. Сессии — Redis с AOF (appendonly yes, appendfsync everysec) и save 60 1; TTL ключа = SESSION_TTL_SECONDS (по умолчанию 3600, в smoke ≥300). Рестарт Redis не продлевает TTL. Кэш истории — производный: версия histver:<chat_id> увеличивается после INSERT сообщения.
Транзакции: создание чата — один transaction: проверка участников + INSERT chat + INSERT members. Неизвестный UUID → 400, чат не появляется в списке.
Пул и таймауты: asyncpg min 1 / max 10, command_timeout=5, timeout=5; Redis socket timeout 2 с. Запросы параметризованные ($1…).
Соответствие .env.example: DATABASE_URL / DATABASE_URL_FILE → DSN Postgres; REDIS_URL / CACHE_URL_FILE по смыслу — Redis; SESSION_STORE=redis; SESSION_TTL_SECONDS читается приложением.
Готовность: /health/live — только процесс; /health/ready — ping Postgres и Redis. Недоступность Redis на Bearer → 503, не анонимный доступ.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS: lab2 public API scenario |
stdout |
| Данные и сессия после рестарта | python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://127.0.0.1:8080 |
PASS: persistence preserved confirmed data and existing session |
evidence/compose_before_restart.txt, evidence/compose_after_restart.txt (hook: docker compose restart postgres redis api, volumes не удалялись) |
| Миграции с нуля / повторно | повторный up API |
schema_migrations пропускает 001_init.sql |
migrations/001_init.sql, логи старта |
| Basic только на login; Bearer; X-User-Id игнорируется | smoke + pytest student_tests/test_api.py |
401 на Basic/me и на X-User-Id; logout 204 затем 401 |
student_tests/test_api.py |
| Password KDF | регистрация | Argon2id (argon2-cffi) |
app/passwords.py |
| Гонка username | test_register_race |
ровно один 201 и пятнадцать 409 | student_tests/test_grade4.py |
| Rollback чата | test_chat_rollback |
400, лишний чат не виден | student_tests/test_grade4.py |
| Индекс истории ≥10k | docker compose exec api python -m app.tools.explain |
Index Scan, 0.061 ms vs Seq Scan 2.081 ms на 10000 сообщений | evidence/explain-history.txt |
| Expiry при TTL=2 | python scripts/run_expiry.py |
1 passed (me → 401 после TTL+1.5 с) | stdout |
| Redis/БД down | RUN_INFRA=1 pytest student_tests/test_infra.py |
live 200, ready 503; me при Redis down 503 | 2 passed |
| Трек 1 stampede | test_stampede_singleflight_reduces_sql |
SQL history: 24 без singleflight, 1 с (24 waiter, delay 250 ms) | evidence/stampede.json |
| Трек 1 read-after-write | test_read_after_write |
новое сообщение сразу в GET | pytest |
| Трек 1 stale без invalidate | test_stale_without_invalidation_then_fixed |
GET без новой строки, после включения invalidate — строка есть | pytest |
| Трек 1 рестарт кэша | test_redis_restart_keeps_session_and_history |
тот же Bearer и то же сообщение после compose restart redis |
pytest infra |
| Нагрузка (закрытый цикл) | python -X utf8 tests/load.py --duration 15 --concurrency 4 --output evidence/load.json |
337.3 successful RPS, ошибки 0, p50 9.7 / p95 27.4 / p99 33.3 ms | evidence/load.json |
make check |
python scripts/check_contract.py |
PASS: offline skeleton structure |
stdout |
Собственные тесты (без infra/expiry): 15 passed за 4.37 с.
Эксперименты и отказы
Гипотеза трека 1. Параллельные GET одной страницы истории после cache miss без координации порождают N одинаковых SQL; in-process singleflight оставляет один load. Инвалидация версией ключа обеспечивает read-after-write; без неё кэш отдаёт stale. После рестарта Redis сессия живёт за счёт AOF, страницы кэша восстанавливаются из PostgreSQL.
Методика. 24 потока, threading.Barrier, искусственная задержка load 250 ms (только APP_ENV=lab через POST /api/v1/_lab/flags), счётчик metrics:sql:messages_select. Сравнение cfg:singleflight=0/1. Отдельно: выключение cfg:invalidate, POST, GET; затем включение и повтор. Затем docker compose restart redis.
Результаты. 24 SQL → 1 SQL. Stale подтверждён при выключенной инвалидации. После рестарта Redis прежний token читает /users/me и историю.
Hardware: Windows 10, Docker Desktop, один host. Измерения — учебные, closed-loop tests/load.py страдает coordinated omission.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
compose restart postgres redis api |
тот же token, то же сообщение | persistence PASS | секунды, volumes целы |
compose stop redis |
ready 503, Bearer не становится анонимом | 503 на /users/me |
после start redis — ready |
compose stop postgres |
ready 503 | 503 | после start — ready |
compose restart redis |
сессия из AOF, история из PG | token и message на месте | готовность API ≤ десятка секунд |
| TTL=2 с | 401 после истечения | pytest expiry PASS | нет потери бизнес-данных |
Ограничения и следующие шаги
- Один Docker-host: отказ машины теряет всё. Redis AOF
everysecдопускает потерю <1 с сессий при crash. - Singleflight — внутри одного процесса API (lab2: одна реплика). С lab3 нужен распределённый lock.
- Задержка 250 ms в эксперименте stampede нужна, чтобы 24 HTTP-клиента успели попасть в окно miss; без неё на localhost первый GET заполняет кэш раньше остальных.
- Argon2id с
memory_cost=8192— учебный компромисс для гонки регистрации, не production-параметры lab7. - Не выдерживается: потеря volume, повреждение AOF, сеть между API и Postgres.
- Улучшение stampede (24→1 SQL) подтверждено измерением. Линейная масштабируемость кэша на нескольких репликах — пока гипотеза.