forked from mtusi2026/mtusi2026lab2
FastAPI + asyncpg + Redis/argon2id. Пользователи/чаты/участники/сообщения в Postgres с версионируемой миграцией и keyset-пагинацией. Basic-вход, Bearer-сессии в Redis с TTL и AOF-персистентностью. make check/test/ test-persistence/validate зелёные; evidence по EXPLAIN ANALYZE, короткому TTL и падению Redis приложены в REPORT.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
87 lines
11 KiB
Markdown
87 lines
11 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Сарибекян, БПИ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: см. ветку `solution/БПИ2303-Сарибекян`
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI, asyncpg, redis-py, argon2-cffi (Argon2id через `argon2.PasswordHasher`). Реализация подготовлена с помощью AI-ассистента (Claude Code) по заданному контракту `contracts/openapi.json`; код и инфраструктура проверены локальным запуском `make check/test/test-persistence/validate`.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии: Python 3.12.7 (образ `python:3.12.7-slim`), PostgreSQL 16.4, Redis 7.4.1. Docker Engine + Compose v2 на хосте.
|
||
|
||
```sh
|
||
git clone <ваш форк>
|
||
cd mtusi2026lab2
|
||
mkdir -p secrets
|
||
openssl rand -hex 20 > secrets/postgres_password.txt
|
||
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
|
||
printf 'redis://redis:6379/0' > secrets/cache_url.txt
|
||
chmod 600 secrets/*.txt
|
||
printf 'SESSION_TTL_SECONDS=3600\n' > .env
|
||
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
# дождаться 200 на /health/ready
|
||
curl -s localhost:8080/health/ready
|
||
|
||
make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Остановка без потери данных: `docker compose stop`. Полное уничтожение учебных данных (намеренное): `docker compose down -v` — удаляет `pgdata`/`redisdata`.
|
||
|
||
## Архитектура и решения
|
||
|
||
Клиент → API (FastAPI/uvicorn, порт 8080) → PostgreSQL (учёт пользователей/чатов/участников/сообщений) и Redis (сессии). Схема:
|
||
|
||
- `users(id, username UNIQUE, display_name, password_hash, created_at)`
|
||
- `chats(id, title, created_at)`
|
||
- `chat_members(chat_id, user_id)` — составной PK, индекс по `user_id` для списка чатов пользователя
|
||
- `messages(id, chat_id, sender_id, text, created_at)` — композитный индекс `(chat_id, created_at, id)` под keyset-пагинацию
|
||
|
||
Миграции — файлы в `migrations/*.sql`, применяются по порядку при старте приложения (`app/db.py`), версия фиксируется в таблице `schema_migrations`; повторный запуск не дублирует данные (идемпотентно — проверено перезапуском).
|
||
|
||
Источник истины для сессий — Redis (`SESSION_STORE` фактически = redis, см. ниже про `.env.example`): ключ `session:<opaque-token>` → JSON `{user_id, expires_at}`, TTL = `SESSION_TTL_SECONDS`. Redis запущен с `--appendonly yes --appendfsync everysec` и volume `redisdata`, поэтому действующие сессии переживают перезапуск Redis (проверено `make test-persistence`). Токен — `secrets.token_urlsafe(32)` (256 бит энтропии), непрозрачный, не username/UUID.
|
||
|
||
Пароли хешируются Argon2id (`argon2-cffi`), сравнение — через `PasswordHasher.verify`, без plaintext/SHA-256.
|
||
|
||
Создание чата — одна транзакция `asyncpg` (`conn.transaction()`): проверка существования всех `member_ids`, вставка чата и участников атомарно; откат при неизвестном участнике.
|
||
|
||
Соответствие `.env.example` → реальной конфигурации: `APP_HOST/APP_PORT` зашиты в Dockerfile/uvicorn (`0.0.0.0:8080`), `SESSION_TTL_SECONDS` передаётся как обычная переменная окружения, `DATABASE_URL_FILE`/`CACHE_URL_FILE` — через Docker secrets (файлы в `secrets/`, не коммитятся), `SESSION_STORE` фактически зафиксирован как Redis (не параметризуется, т.к. лаба тестирует именно Redis-ветку оценки 4).
|
||
|
||
Переход от lab1: `X-User-Id` больше не определяет личность вызывающего (игнорируется, проверено в smoke: `X-User-Id` чужого пользователя не переопределяет Bearer-сессию). Регистрация теперь требует `password`; вход — только через `Basic` на `POST /auth/sessions`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | `PASS: lab2 public API scenario...` | вывод команды, стенд поднят `docker compose up -d --build` |
|
||
| Персистентность (3) | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session.` | вывод команды |
|
||
| Атомарность создания чата (3) | транзакция в `create_chat`, проверено unknown member → 400 без побочной вставки | откат подтверждён ручным вызовом с несуществующим UUID в `member_ids` → `400 invalid_request`, чат не создан | `app/main.py::create_chat` |
|
||
| Redis с TTL (4) | логин с `SESSION_TTL_SECONDS=2`, ожидание 3с, `GET /users/me` | `200` → `401 unauthorized` после истечения | см. раздел «Эксперименты» |
|
||
| Устойчивость к падению Redis (4) | `docker compose stop redis`, запрос с валидным токеном | `503 unavailable` (не анонимный доступ, не 401) | см. «Эксперименты» |
|
||
| EXPLAIN ANALYZE на 10 000+ сообщениях (4) | 12 000 строк, keyset-запрос с `LIMIT 51` | до `ANALYZE`: Bitmap Heap Scan, 12000 просмотренных строк, 5.05 ms; после `ANALYZE`: `Index Scan` по `messages_chat_keyset_idx`, 0.31 ms | `evidence/explain_analyze_messages.txt` |
|
||
| Параметризованные запросы/pool/timeouts (4) | весь SQL через `asyncpg` с `$1,$2,...`; пул `min_size=2,max_size=10,timeout=5,command_timeout=5` | код ревью | `app/db.py` |
|
||
| Гонка регистрации одинакового username (4) | уникальный индекс `users.username` + обработка `UniqueViolationError` → `409` | повторная регистрация того же username в smoke даёт `409` | `tests/smoke.py` строка с повторной регистрацией `alice` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
**TTL expiry.** Пользователь `ttltest`, `SESSION_TTL_SECONDS=2`. Сразу после логина `GET /users/me` → `200`. Через 3 секунды тот же токен → `401 {"code":"unauthorized"}`. Ограничение: проверка ручная (curl), не автоматизирована в CI для этой лабы.
|
||
|
||
**Недоступность Redis.** Активная сессия, затем `docker compose stop redis`. `GET /users/me` с валидным токеном → `503 unavailable` (не 401, не пропущен как анонимный — зависимость от Redis для аутентификации явная). `GET /health/ready` также `503`. После `docker compose start redis` сервис восстанавливается без потери данных Postgres (не затронут).
|
||
|
||
**EXPLAIN ANALYZE, 12 000 сообщений в одном чате.** Запрос keyset-пагинации `WHERE chat_id=... ORDER BY created_at,id LIMIT 51`. До `ANALYZE` планировщик недооценил избирательность и выбрал Bitmap Heap Scan (просмотр всех 12000 строк чата, 5.05 ms). После `ANALYZE messages` — `Index Scan` непосредственно по композитному индексу `(chat_id, created_at, id)` с остановкой на 51-й строке, 0.31 ms. Вывод: сам индекс недостаточен без актуальной статистики; `autovacuum` обычно обновит её сам, здесь продемонстрировано явно.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose restart postgres redis api` | Сообщения и активная сессия сохраняются | Подтверждено `make test-persistence`: тот же Bearer-токен читает те же данные после рестарта | восстановление API < 90s (тест ждёт готовности), потери данных нет |
|
||
| `docker compose stop redis` (без restart) | Бизнес-эндпойнты не считают запрос анонимным | `503 unavailable`, не 401/200 | сервис восстанавливается сразу после `start redis`, активные токены не теряются (данные в volume) |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Трек исследования уровня 5 не реализован (цель — оценка 4).
|
||
- Rate limiting (`429`) не реализован — контракт делает его опциональным, тесты его не требуют.
|
||
- Нет собственного теста на конкурентную гонку создания чата с частично несуществующими участниками под параллельной нагрузкой — проверено только последовательно.
|
||
- `evidence/explain_analyze_messages.txt` содержит план на синтетических данных одного чата (12 000 строк); неравномерное распределение размеров чатов (трек 5.2) не исследовано.
|
||
- Secrets-файлы и `.env` не коммитятся (см. `.gitignore`); для воспроизведения нужно сгенерировать их заново по инструкции выше.
|