Files
mtusi2026lab2/REPORT.md
T
drunkdiente 0dd3ecfb7c Реализовать лабораторную 2: API мессенджера с PostgreSQL и кэшем сессий
FastAPI-сервис с opaque-сессиями (Argon2id, SHA-256 фингерпринт), PostgreSQL как источником истины, Valkey как кэшем сессий, keyset-пагинацией, пулом соединений и таймаутами. Добавлены миграции, compose-стенд, скрипт рестарта, студенческие проверки и evidence.
2026-10-23 12:17:00 +03:00

166 lines
14 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
- Автор, группа: Ким Владимир, БВТ2302
- Целевая оценка; 3
(Redis/Valkey как кэш сессий, параметризованные запросы и пул, индекс истории с EXPLAIN на 10 000
сообщениях, автоматические проверки expiry/logout/гонки/отказа).
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки: FastAPI 0.115.6, Uvicorn 0.34.0,
psycopg2-binary 2.9.10, redis 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16.4, Valkey 7.2.6.
Все решения проверены запуском стенда. Первичные материалы: см. README курса.
## Запуск из чистого clone
Prerequisites: Docker Engine/Desktop с Compose v2 и доступом к сети для сборки образа.
Версии зафиксированы: Python 3.12.7-slim (образ `python:3.12.7-slim`), `postgres:16.4`,
`valkey/valkey:7.2.6`. Никаких хостовых БД/Redis не требуется.
```sh
# 1. Локальные синтетические секреты (файл в .gitignore, в Git не попадает)
cp .env.example .env
# заполните как минимум POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB,
# APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/SESSION_STORE, DB_POOL_MIN/DB_POOL_MAX
# 2. Проверка конфигурации и сборка
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# 3. Дождаться готовности (миграции применяются автоматически при старте API)
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
# 4. Проверки
python scripts/check_contract.py # = make check
python tests/smoke.py --base-url http://localhost:8080 # = make test
python tests/resilience.py --mode persistence --action-script scripts/restart.sh \
--base-url http://localhost:8080 # = make test-persistence
python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
# 5. Безопасная остановка (volumes сохраняются)
docker compose --env-file .env stop
# 6. Намеренное удаление только учебных данных
docker compose --env-file .env down -v
```
На Windows хук `scripts/restart.sh` (POSIX) запускается через `scripts/restart.cmd`
(та же команда `docker compose restart`); проверка сохранности при этом эквивалентна.
`make` в среде разработки отсутствовал, поэтому в отчёте приведены эквивалентные python-команды.
## Архитектура и решения
```
Клиент --HTTP--> API (FastAPI/Uvicorn, python:3.12.7-slim, non-root)
| psycopg2 pool (bounded, statement_timeout)
v
PostgreSQL 16.4 <-- источник истины: users, chats, chat_members,
(named volume pgdata) messages, sessions, schema_migrations
^
| cache-aside (TTL = остаток жизни сессии)
Valkey 7.2.6 (named volume valkeydata, AOF) <-- кэш сессий
```
- **Источник истины** — PostgreSQL. Пользователи, чаты, членство, сообщения и **сессии**
хранятся в БД, поэтому данные и действующие сессии переживают рестарт API и хранилищ.
- **Сессии**: opaque-токен (`secrets.token_urlsafe(32)`, ≥256 бит). В БД пишется только
SHA-256-фингерпринт токена (сам токен не хранится). Срок жизни задаёт `SESSION_TTL_SECONDS`
(по умолчанию 3600). Отзыв — `revoked_at` + удаление ключа из кэша.
- **Пароли**: Argon2id (`argon2-cffi`). Пароль никогда не возвращается в `User`.
- **Valkey/Redis — кэш, а не источник истины.** При каждом аутентифицированном запросе сначала
проверяется кэш (`sess:<sha256>`); промах или недоступность кэша → запрос к PostgreSQL.
TTL кэша равен остатку жизни сессии, инвалидация — при logout/отзыве. Так как истина в БД,
потеря кэша не приводит к потере данных, а анонимный запрос не принимается доверенным.
- **Транзакционные границы**: регистрация пользователя и создание сессии — одиночные INSERT;
создание чата — одна транзакция (проверка существования участников + INSERT чата +
INSERT участников); отправка сообщения — проверка членства и INSERT в одной транзакции.
Гонка регистрации одинакового username разрешается уникальным ограничением `users.username`,
нарушение перехватывается и превращается в `409 conflict`.
- **Ограничения и валидация**: длина и формат полей проверяются приложением (код-поинты) и
дублируются CHECK-ограничениями БД; лишние поля и неверные типы → `400`; `additionalProperties:false`
соблюдается для всех ответов.
- **Пагинация истории** — keyset по `(created_at, id)` по возрастанию, курсор непрозрачный и
привязан к ресурсу (`chat_id`/`user_id`); выборка `LIMIT n+1` определяет `next_cursor` без
полного сканирования истории.
### Соответствие `.env.example` реальной конфигурации
| `.env.example` | Реальная переменная | Смысл |
| --- | --- | --- |
| `APP_HOST` / `APP_PORT` | то же | bind-адрес/порт Uvicorn |
| `APP_ENV` | то же | метка окружения (лог) |
| `SESSION_TTL_SECONDS` | то же | TTL сессии, по умолчанию 3600 |
| `SESSION_STORE` | то же | `postgres` или `postgres+redis` |
| `DATABASE_URL_FILE` | `DATABASE_URL` **или** `DATABASE_URL_FILE` | DSN PostgreSQL (поддержаны оба способа) |
| `CACHE_URL_FILE` | `CACHE_URL` **или** `CACHE_URL_FILE` | DSN Valkey/Redis (кэш) |
| — | `DB_POOL_MIN` / `DB_POOL_MAX` | границы пула соединений |
Приложение читает значение напрямую из переменной, а при её отсутствии — из файла,
указанного в `*_FILE` (совместимо с Docker secrets). Секретов в Git нет: `.env` в `.gitignore`.
### Роли инфраструктуры
| Роль | service | Образ (пиннинг) | healthcheck | volume | сеть | credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | сборка из `Dockerfile` (python:3.12.7-slim) | `HEALTHCHECK` + `/health/live` | — | `backend` | env из `.env` |
| postgres | `postgres` | `postgres:16.4` | `pg_isready` | `pgdata` | `backend` | `POSTGRES_*` из `.env` |
| cache | `valkey` | `valkey/valkey:7.2.6` | `valkey-cli ping` | `valkeydata` (AOF) | `backend` | `CACHE_URL` из `.env` |
Bootstrap: миграции `migrations/*.sql` применяются самим API при старте (таблица
`schema_migrations`, advisory lock). Повторный запуск не дублирует данные.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Структура skeleton | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | `evidence/check.txt` |
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario` | `evidence/smoke.txt` |
| Данные и сессия переживают рестарт | `python tests/resilience.py --mode persistence --action-script scripts/restart.sh ...` | `PASS: persistence preserved confirmed data and existing session`; StartedAt всех контейнеров изменился, volumes сохранены | `evidence/persistence.txt` |
| PostgreSQL = источник истины, ключи, уникальность, миграции с нуля | миграция `migrations/0001_init.sql` + лог старта API | `applied migration 0001_init`; таблицы/индексы создаются на пустом volume | `evidence/persistence.txt` |
| Атомарное создание чата | код `store.create_chat` + одна транзакция | rollback при неизвестном участнике; гонка username → `409` | `student-tests/test_lab2.py` |
| Basic только на `POST /auth/sessions`, остальное — Bearer, expiry и отзыв | `student-tests/test_lab2.py` | wrong password `401` (Basic), `X-User-Id` не работает, logout `204`→`401` (Bearer) | `evidence/cache_outage.txt` |
| Истечение сессии при коротком TTL | `--expiry` c `SESSION_TTL_SECONDS=2` | `PASS: session expired after 2s TTL` | `evidence/expiry_check.txt` |
| Параметризованные запросы, пул, таймауты (уровень 4) | код `db.py`/`store.py` | пул `ThreadedConnectionPool`, `statement_timeout`, все SQL параметризованы | код |
| Индекс истории обоснован EXPLAIN на ≥10 000 сообщений (уровень 4) | `student-tests/perf_explain.sql` | `Index Scan using messages_chat_created_id_idx`, 5 буферов, 0.028 ms против Seq Scan 361 буфер, 2.550 ms | `evidence/explain.txt`, `evidence/explain_no_index.txt` |
| Отказ Redis/БД (уровень 4) | `--cache-check` и `stop postgres` | аутентификация живёт без кэша; `/health/ready` и аутентифицированные запросы → `503 unavailable` при недоступной БД, `/health/live` → `200` | `evidence/cache_outage.txt`, `evidence/dependency_outage.txt` |
## Эксперименты и отказы
Оборудование: один Docker-host (Windows, Docker Desktop 29.4.3, Linux engine), образы без
явных CPU/RAM-лимитов. Прогрев не выделялся; данные синтетические.
Нагрузка (closed-loop POST сообщений, `tests/load.py`, см. `evidence/load.json`):
| Профиль | Длительность | Concurrency | Успешные RPS | Ошибки | p50 | p95 | p99 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 4 воркера | 15 с | 4 | 236.6 | 0 (0.0) | 16.0 ms | 32.0 ms | 47.0 ms |
Ограничения измерения: генератор закрытого контура ограничен клиентом и подвержен coordinated
omission; latency только по успешным запросам; это пропускная способность HTTP-подтверждений, а
не счётчик COMMIT.
План запроса (10 000 сообщений в чате, keyset-страница):
| Вариант | План | Buffers | Execution |
| --- | --- | --- | --- |
| С индексом | `Index Scan using messages_chat_created_id_idx` | shared hit=5 | 0.028 ms |
| Без индекса (indexscan off) | `Seq Scan` + `Sort` | shared hit=361 | 2.550 ms |
Отказы:
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker compose restart` (api+postgres+valkey, volumes сохранены) | данные и прежний токен доступны | те же чат/сообщение по прежнему токену | рестарт всех контейнеров; потерь нет |
| Остановка Valkey (кэш) | аутентификация продолжает работать через БД | `/users/me` по прежнему токену → `200` | кэш пересоберётся сам; потерь нет |
| Остановка PostgreSQL | `/health/ready` деградирует | `/health/ready` → `503 unavailable`, аутентифицированный запрос → `503 unavailable`, `/health/live` → `200` | `200` после старта БД; потерь нет |
## Ограничения и следующие шаги
- Учебное упрощение: один Docker-host; эксперимент **не** даёт отказоустойчивости к потере
самого host, а единственная БД и отсутствие LB/реплик не делают стенд HA. Redis выбран как
кэш, а не единственное хранилище сессий, поэтому его потеря безопасна.
- Durability PostgreSQL определяется настройками по умолчанию образа; отдельно проверялось
сохранение при рестарте контейнеров с сохранением volume, а не при потере диска.
- Не реализовано (вне минимума этой лабы): изменение участников/удаление сообщений, rate limiting,
идемпотентность отправки (`Idempotency-Key`) и `X-Instance-Id` — это переходы lab3+.
- Уровень 4 подтверждён частично: кэш сессий, пул/таймауты, индекс и отказы проверены; отдельный
«трек 5» (согласованность кэша или backup/restore) не заявлен и не измерялся.