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