8.2 KiB
Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка: 4 (трек 5 не заявляется)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, psycopg 3, psycopg_pool, redis-py, argon2-cffi, PostgreSQL; помощь ИИ — генерация каркаса кода и текста отчёта, проверка и адаптация вручную.
Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.9+ (для тестов), make.
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться /health/ready (healthcheck в compose)
make test BASE_URL=http://localhost:8080
make test-unit BASE_URL=http://localhost:8080
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
Версии образов закреплены: postgres:16.4-alpine, redis:7.4-alpine, python:3.12-slim. Миграции применяются автоматически при старте API (app/db.py::apply_migrations), идемпотентно через таблицу schema_migrations.
Безопасная остановка: docker compose down (volumes сохраняются). Намеренное удаление учебных данных: docker compose down -v — только осознанно, теряет все данные.
Архитектура и решения
- Процессы:
api(FastAPI/uvicorn),postgres(источник истины),redis(кэш сессий с TTL). - Источник истины: PostgreSQL. Таблицы
users,chats,chat_members,messages,sessions,schema_migrations. PK/FK,UNIQUE(username), составной PK(chat_id, user_id). - Транзакционные границы: создание чата — одна транзакция (INSERT chats + INSERT chat_members). Создание сообщения — одна транзакция. Создание сессии — одна транзакция.
- Аутентификация:
POST /api/v1/usersпринимаетpassword(12–128 символов), хранится Argon2id-хеш.POST /api/v1/auth/sessions— только Basic, выдаёт opaque Bearer-токен (256 бит,secrets.token_urlsafe(32)); в БД хранится SHA-256 от токена.DELETE /api/v1/auth/sessions/currentотзывает сессию.X-User-Idигнорируется. - Сессии: источник истины —
sessionsв PostgreSQL; Redis — кэшsession:<sha256>с TTL = остаток жизни сессии. При недоступности Redis — fallback на БД (не принимаем анонимов). При logout инвалидируется и БД, и кэш. - Пул и таймауты:
psycopg_pool.ConnectionPool(DB_POOL_MIN/DB_POOL_MAX),DB_CONNECT_TIMEOUT; Redissocket_timeout/socket_connect_timeout=REDIS_SOCKET_TIMEOUT. - Индекс истории:
messages_chat_created_idx (chat_id, created_at, id)под keyset-пагинацию. Проверка —scripts/explain_history.sql. - Соответствие
.env.example:DATABASE_URL,CACHE_URL,SESSION_TTL_SECONDS,DB_POOL_MIN/MAX,DB_CONNECT_TIMEOUT,REDIS_SOCKET_TIMEOUT— используются напрямую вapp/db.py,app/sessions.py,app/main.py.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke (уровень 3) | make test |
PASS: lab2 public API scenario | вывод консоли |
| Persistence (уровень 3) | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session | вывод консоли |
| Миграции с нуля | docker compose down -v && docker compose up -d --build |
API стартует, schema_migrations содержит 001/002 |
docker compose exec postgres psql -U messenger -c "select * from schema_migrations" |
| Redis используется для сессий с TTL | docker compose exec redis redis-cli TTL session:<hash> |
TTL > 0, уменьшается | вывод консоли |
| Параметризованные запросы | код app/store.py, app/sessions.py |
все запросы через %s |
исходники |
| Ограниченный пул и таймауты | app/db.py, app/main.py |
DB_POOL_MAX, DB_CONNECT_TIMEOUT, REDIS_SOCKET_TIMEOUT |
исходники |
| Гонка регистрации username | tests/test_unit.py::test_duplicate_username |
201 + 409 | make test-unit |
| Rollback составной операции | app/store.py::create_chat — conn.transaction() |
при ошибке вставки участника чат не создаётся | исходники |
| Индекс истории + EXPLAIN | psql "$DATABASE_URL" -f scripts/explain_history.sql |
Index Scan по messages_chat_created_idx |
вывод EXPLAIN |
| Expiry при коротком TTL | SESSION_TTL_SECONDS=2 docker compose up -d api + make test-unit |
401 после истечения | вывод консоли |
| Logout | tests/test_unit.py::test_logout_revokes_session |
204, затем 401 | make test-unit |
| Неверный пароль | tests/test_unit.py::test_wrong_password_returns_401 |
401 | make test-unit |
| Недоступность Redis | docker compose stop redis + make test |
smoke проходит (fallback на БД) | вывод консоли |
| Недоступность БД | docker compose stop postgres + curl /health/ready |
503 unavailable |
вывод консоли |
Эксперименты и отказы
Гипотеза: при остановке Redis API продолжает обслуживать запросы (кэш — не источник истины); при остановке PostgreSQL /health/ready возвращает 503, бизнес-запросы — 500/503 без утечки деталей.
Hardware: локальная машина разработчика (Windows 11, Docker Desktop). Объём данных: синтетические пользователи/чаты/сообщения из тестов. Профиль нагрузки: tests/load.py --duration 30 --concurrency 4 (closed-loop, ограничен клиентом).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose restart api postgres redis (volumes сохранены) |
данные и сессии сохранены | PASS persistence | ~5–10 с, потерь нет |
docker compose stop redis |
API работает, сессии из БД | smoke PASS | восстановление после start redis |
docker compose stop postgres |
/health/ready → 503 |
503 unavailable |
после start postgres — 200 |
SESSION_TTL_SECONDS=2 |
сессия истекает | 401 после истечения | — |
Ограничения и следующие шаги
- Redis — кэш, не источник истины; при его недоступности latency сессий растёт (каждый запрос идёт в БД).
- Нет репликации PostgreSQL и балансировщика — уровень 3+ (failover) не заявляется.
- Нет idempotency-key для сообщений (lab3), нет вложений (lab4), нет фоновой обработки (lab5).
tests/load.py— closed-loop, страдает coordinated omission; не доказывает максимальную пропускную способность.- Трек 5 не выполнялся.