# Отчёт — лабораторная 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:` → 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`); для воспроизведения нужно сгенерировать их заново по инструкции выше.