Files
mtusi2026lab2/REPORT.md
T
Artu-RitoandClaude Sonnet 5 d12159a8cc Лаба 2: PostgreSQL-хранилище и Redis-сессии (оценка 4)
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>
2026-10-30 00:23:26 +03:00

87 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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`); для воспроизведения нужно сгенерировать их заново по инструкции выше.