# Отчёт — лабораторная 2 - Автор, группа: Саватеев Артём, БВТ2302 - Целевая оценка: **4** (все пункты уровней 3 и 4) - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic, Uvicorn, loguru, asyncpg, redis-py, argon2-cffi; для тестов pytest, httpx; документация PostgreSQL (transactions, EXPLAIN, advisory locks, `uuidv7`) и Valkey ## Запуск из чистого clone Версии: Docker Engine 29.0.1, Docker Compose v2.40.3 (проверено на Docker Desktop, linux/arm64). Образы закреплены явными тегами: `python:3.12.12-slim`, `postgres:18.22`, `valkey/valkey:8.1.4`. Python-зависимости закреплены в `pyproject.toml` (точные версии) и `poetry.lock`. Prerequisites: Docker с Compose, make, curl, Python ≥ 3.9 для публичных тестов. Для собственных тестов дополнительно Python 3.12 и Poetry 2.2.1. ```sh # Запуск cp .env.example .env make up # docker compose up -d --build --wait; миграции API применяет сам при старте # Проверки make check # структура skeleton make test # публичный smoke make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт api, postgres, valkey с сохранением volume make install # dev-окружение Poetry (один раз) make student-test # собственные тесты, одна команда make test-migrations # миграции на пустом volume отдельного compose-проекта make test-expiry # второй API с SESSION_TTL_SECONDS=2 на :8081 make test-failures # останавливает и запускает valkey и postgres make explain # сид ≥10 000 сообщений и планы запроса истории # Безопасная остановка без потери данных make down # = docker compose --profile expiry down ``` Намеренное удаление учебных данных — `make destroy-data` (`docker compose down -v`): volume `postgres_data` будет стёрт. Остальные команды volume не удаляют. Операторских действий кроме создания `.env` не требуется. `make up` ждёт healthcheck всех сервисов, готовность API — `GET /health/ready`. `.env` в образ не копируется (`.dockerignore`), конфигурация передаётся через `env_file` в `compose.yaml`. ## Архитектура и решения ``` Клиент ──HTTP :8080──▶ api (FastAPI, uvicorn) ──asyncpg pool 2..10──▶ postgres источник истины, volume postgres_data │ └──redis-py pool ≤20, timeout 0.5 s──▶ valkey read-through кэш сессий, без persistence сети: default (только api, 127.0.0.1:8080) + backend (internal: api, postgres, valkey) ``` Слои в `src/`: | Каталог | Ответственность | | --- | --- | | `config/` | чтение окружения через envparse, логирование loguru в stdout | | `domain/` | Pydantic-схемы запросов/ответов, сессии и учётные данные, коды и исключения ошибок | | `interfaces/` | ABC-репозитории и кэш сессий: сервисы зависят от абстракций, а не от PostgreSQL/Valkey | | `infrastructure/` | репозитории PostgreSQL, кэш Valkey, сервисы, Argon2id и токены (`security/`), пул БД и кэша, пагинация/cursor, `ServiceCreator` для DI | | `application/api/` | роутеры, Basic/Bearer зависимости, middleware, обработчики ошибок | | `gateway.py` | сборка приложения, lifespan (пул, миграции, кэш), запуск uvicorn | Миграции — нумерованные SQL-файлы в `migrations/`. Роли и сервисы `compose.yaml`: | Роль | Сервис | Версия | Health / readiness | Volume | Сеть / порт | Credentials | | --- | --- | --- | --- | --- | --- | --- | | API | `api` | сборка из `Dockerfile` | `src/healthcheck.py` → `/health/ready` | нет | default + backend, `127.0.0.1:8080` | `DB_*`, `VALKEY_*` из `.env` (env_file) | | PostgreSQL | `postgres` | `postgres:18.2-alpine3.22` | `pg_isready` | `postgres_data:/var/lib/postgresql` | backend (internal), не публикуется | `POSTGRES_PASSWORD` ← `DB_PASS` | | Valkey | `valkey` | `valkey/valkey:8.1.4-alpine3.22` | `valkey-cli ping` | нет (чистый кэш) | backend (internal), не публикуется | `--requirepass` ← `VALKEY_PASS` | | API с коротким TTL | `api-short-ttl` (profile `expiry`) | тот же образ | как у API | нет | `127.0.0.1:8081` | как у API, `SESSION_TTL_SECONDS=2` | **Что перенесено из lab1.** Слои `application/domain/interfaces/infrastructure`, контракт ошибок, `X-Request-Id`, keyset-cursor, graceful shutdown, Dockerfile с пользователем не root. In-memory хранилище удалено, вместо него репозитории `Postgres*Repository` и `ValkeySessionCache` за теми же интерфейсами. **Переходы API по COURSE.md.** Регистрация требует `password` (12–128 code points). Вход только через `POST /api/v1/auth/sessions` с Basic. Все бизнес-endpoint требуют Bearer. Basic на бизнес-endpoint и `X-User-Id` возвращают 401 и не влияют на владельца сессии. **Источник истины** — PostgreSQL. Схема — `migrations/0001_init.sql`: | Таблица | Ключи и ограничения | | --- | --- | | `users` | PK `id uuid DEFAULT uuidv7()`, `UNIQUE (username)`, CHECK формата username и длины display_name, `password_hash` (PHC Argon2id) | | `sessions` | PK `token_hash bytea` (SHA-256 токена, 32 байта), FK `user_id → users`, `expires_at`, `revoked_at`, CHECK `expires_at > created_at` | | `chats` | PK uuid v7, FK `created_by → users`, CHECK длины title | | `chat_members` | PK `(chat_id, user_id)`, FK на chats и users, `position` (порядок `member_ids`), `UNIQUE (chat_id, position)`, индекс `(user_id, chat_id)` | | `messages` | PK uuid v7, FK `(chat_id, sender_id) → chat_members`: отправитель обязан быть участником; CHECK длины text; индекс `(chat_id, created_at, id)` | UUID v7 упорядочен по времени, поэтому вставки в B-tree PK идут в правую часть, как у bigint, а наружу отдаётся UUID, как требует контракт. **Регистрация** — один `INSERT`. Гонку одинаковых username разрешает `UNIQUE`, `UniqueViolationError` превращается в 409. Проверки «сначала SELECT» нет. **Вход.** `SELECT` пользователя, проверка Argon2id в отдельном пуле потоков, затем `INSERT sessions` с `expires_at = clock_timestamp() + TTL` по часам БД. Токен — 32 случайных байта (256 бит), в БД хранится только его SHA-256. Для неизвестного username проверяется dummy-hash, поэтому ответ и время одинаковы. **Создание чата** — `BEGIN` → `INSERT chats` → `INSERT chat_members` (unnest) → `COMMIT`. Неизвестный участник нарушает FK, транзакция откатывается целиком, клиент получает 400. Предварительной проверки участников нет: она была бы гонкой и маскировала бы откат. **Сообщение** — `BEGIN` → `pg_advisory_xact_lock(2, hashtext(chat_id))` → `INSERT … created_at = GREATEST(clock_timestamp(), MAX(created_at) + 1 µs)` → `COMMIT`. Внутри чата `created_at` строго возрастает, и порядок коммитов совпадает с порядком `(created_at, id)`. Поэтому читатель с cursor не пропустит сообщение, вставленное «задним числом» конкурентной транзакцией. Это замена `asyncio.Lock` и `MonotonicClock` из lab1, корректная для нескольких процессов. Записи в один чат сериализуются, записи в разные чаты нет. **Logout** — `UPDATE sessions SET revoked_at` для действующей сессии (0 строк → 401), затем `DEL` ключа в Valkey. **Valkey.** Read-through кэш сессий: ключ `session:`, значение `{user, expires_at}`. При попадании в кэш аутентификация выполняется без SQL. Источник истины — таблица `sessions`, Valkey хранит только копию. TTL записи — `min(остаток жизни сессии, SESSION_CACHE_TTL_SECONDS=60)`, приложение дополнительно сверяет `expires_at`. Logout удаляет ключ после фиксации отзыва в БД; если Valkey в этот момент недоступен, запись может остаться не дольше 60 с, это логируется как warning. **Persistence Valkey выключена** (`--save "" --appendonly no`). Valkey не единственное хранилище сессий: после рестарта или flush кэш пуст и заполняется из PostgreSQL, сессии не теряются. Заодно запись, не удалённая при logout во время сбоя, не «воскресает» после рестарта Valkey. **Отказ Valkey.** Ошибка (таймаут 0.5 с, без встроенных повторов) переводит кэш в режим обхода на `VALKEY_RETRY_AFTER_SEC=5` с: все запросы идут в PostgreSQL без сетевых попыток к Valkey, сервис работает, `/health/ready` = 200. **Readiness.** Критичен только PostgreSQL: `/health/ready` выполняет `SELECT 1`, без него ответ — `503 unavailable` без деталей SQL. Анонимный запрос — 401. Неизвестный токен при недоступной БД — 503, а не 200: доверие без проверки невозможно. Valkey не критичен. **Пул и таймауты.** asyncpg: `min_size=2`, `max_size=10`, connect/acquire timeout 3 с, `command_timeout` 5 с и серверный `statement_timeout` 5 с. Ошибки соединения превращаются в `UnavailableError` (503); первая такая ошибка вызывает `pool.expire_connections()`, чтобы после рестарта PostgreSQL 503 получил один запрос, а не все соединения пула по очереди. Запросы только параметризованные (`$1…$n`), SQL написан в методах репозиториев, значения в текст запроса не подставляются. | Переменная | Где используется | Значение в примере | | --- | --- | --- | | `APP_HOST` | адрес bind uvicorn; в контейнере обязательно `0.0.0.0` | `0.0.0.0` | | `APP_PORT` | порт uvicorn, healthcheck, публикация порта в `compose.yaml` | `8080` | | `APP_ENV` | имя окружения в логе запуска приложения | `lab` | | `LOG_LEVEL` | уровень loguru | `INFO` | | `SHUTDOWN_TIMEOUT_SEC` | `timeout_graceful_shutdown` uvicorn | `5` | | `DB_USER`, `DB_PASS`, `DB_NAME`, `DB_HOST`, `DB_PORT` | подключение asyncpg; учётные данные сервиса `postgres`. В контейнере API `compose.yaml` подставляет `DB_HOST=postgres` | `test`, `test`, `test`, `localhost`, `5432` | | `DB_POOL_MIN_SIZE`, `DB_POOL_MAX_SIZE` | границы пула asyncpg | `2`, `10` | | `DB_CONNECT_TIMEOUT_SEC`, `DB_COMMAND_TIMEOUT_SEC` | таймаут подключения/ожидания соединения и выполнения запроса | `3`, `5` | | `DB_STARTUP_TIMEOUT_SEC` | сколько ждать БД при старте API | `30` | | `VALKEY_HOST`, `VALKEY_PORT`, `VALKEY_PASS` | подключение к Valkey; пароль сервиса `valkey`. В контейнере API `compose.yaml` подставляет `VALKEY_HOST=valkey` | `localhost`, `6379`, `test` | | `VALKEY_POOL_MAX_SIZE`, `VALKEY_TIMEOUT_SEC`, `VALKEY_RETRY_AFTER_SEC` | пул redis-py, таймаут операции, пауза обхода кэша после ошибки | `20`, `0.5`, `5` | | `SESSION_TTL_SECONDS` | срок жизни сессии | `3600` | | `SESSION_CACHE_TTL_SECONDS` | верхняя граница TTL записи в Valkey | `60` | | `PASSWORD_HASH_WORKERS` | потоки Argon2id: ограничение CPU/RAM на одновременные входы | `4` | Переменные skeleton: `DATABASE_URL_FILE` заменён на `DB_*`, `CACHE_URL_FILE` — на `VALKEY_*`; `SESSION_STORE=postgres` соответствует реализации: сессии в PostgreSQL, Valkey — кэш. ## Доказательства критериев Полный вывод команд сохранён в каталоге `evidence/`, имя файла указано в скобках. | Критерий README | Команда/сценарий | Наблюдаемый результат | | --- | --- | --- | | 3: публичный smoke | `make check && make test` | `PASS: lab2 public API scenario` (smoke.txt) | | 3: данные и действующие сессии переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; `StartedAt` у api, postgres, valkey изменился, volume сохранён, токен до рестарта работает после (persistence.txt) | | 3: PK/FK, уникальность username, индексы | `\d+ messages`, `\di` | ограничения и индексы из миграции (migrations.txt) | | 3: миграции с нуля и повторно без дублирования | `make test-migrations` | пустой volume: 0 таблиц → запуск 1 применяет `0001_init` → запуски 2–3 ничего не меняют (migrations_from_zero.txt) | | 3: атомарное создание чата | `test_failed_chat_creation_is_rolled_back` | 400; в БД 0 строк `chats` с этим title и 0 участников-сирот (race_rollback.txt) | | 3: Basic только на `POST /auth/sessions`, Bearer на остальных, X-User-Id не даёт доступа | `test_auth.py`, `test_users.py`, smoke | 401 с `WWW-Authenticate: Basic …` / `Bearer …`; Basic на бизнес-endpoint — 401; `X-User-Id` игнорируется (student_tests.txt) | | 3: KDF паролей | `test_password_is_not_stored_in_plaintext` | в `users.password_hash` строка `$argon2id$…`, пароля нет (student_tests.txt) | | 3: секреты и volumes не в Git | `git check-ignore .env`, `.gitignore` | `.env`, `volumes/`, `data/`, `secrets/` игнорируются | | 4: Valkey реально используется для сессий с TTL | `test_valkey_down_cache_is_bypassed`, раздел «Valkey» | read-through кэш, TTL ≤ min(сессия, 60 с), DEL при logout (dependency_failures.txt) | | 4: параметризованные запросы, ограниченный пул и таймауты | `infrastructure/repositories/*/postgres.py`, `dependencies/database.py`, `dependencies/cache.py` | только `$n`; пул 2..10; таймауты 3/5 с; Valkey ≤20, 0.5 с | | 4: гонка регистрации одинакового username | `test_same_username_race_creates_exactly_one_user` | 20 параллельных запросов → 1×201, 19×409, 1 строка в БД (race_rollback.txt) | | 4: rollback составной операции | `test_failed_chat_creation_is_rolled_back` | откат проверен по содержимому БД, а не только по ответу (race_rollback.txt) | | 4: индекс истории и `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях | `make explain` | 138 769 сообщений, в чате 20 000. Страница из середины: `Index Scan … Index Cond: chat_id AND ROW(created_at,id) > ROW(…)`, 5 буферов, 0.036 мс; generic plan (как в asyncpg) — тот же Index Scan. Без индекса — `Parallel Seq Scan`, 128 768 строк отброшено, 1 792 буфера, 7.28 мс (explain_history.txt) | | 4: expiry при коротком `SESSION_TTL_SECONDS` | `make test-expiry` | токен работает и попадает в кэш, через 3 с — 401 на `/users/me`, `/chats`, logout (expiry.txt) | | 4: logout, неверный пароль | `test_logout_revokes_only_current_session`, `test_wrong_password_and_unknown_user_are_indistinguishable` | 204 без тела → 401 → повторный logout 401; другая сессия жива; неверный пароль и неизвестный логин дают одинаковый 401 (student_tests.txt) | | 4: недоступность Valkey/БД | `make test-failures` | без Valkey вход, запись и logout работают, ответ < 3 с. Без PostgreSQL — `/health/ready` 503, аноним 401, неизвестный токен 503, регистрация/вход 503 без деталей. После рестарта PostgreSQL прежний токен работает (dependency_failures.txt) | Сводка собственных тестов: `make student-test` — 87 passed, 6 skipped (их запускают `make test-expiry` и `make test-failures`). ## Эксперименты и отказы | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `scripts/restart.sh`: рестарт postgres, valkey, api | данные и сессии на месте | PASS, прежний токен читает те же сообщения | ~2 с до ready; потерь нет | | `docker compose stop valkey` | кэш обходится, API работает | вход, Bearer, запись, logout — OK, ready 200; один warning, далее 5 с без попыток | мгновенно; потерь нет (кэш) | | logout при остановленном valkey, затем его старт | отозванный токен не принимается | 401 после подъёма: кэш без persistence пуст | — | | `docker compose stop postgres` | ограниченный 503, без доверия анониму | ready 503, аноним 401, неизвестный токен 503, ответ < 3 с | — | | `docker compose restart postgres` при живом API | API переподключается сам | после ready прежний токен работает | до ~2 с; данные на volume | ## Ограничения и следующие шаги - Один Docker-host: отказ хоста, диска или единственного экземпляра PostgreSQL не переживается, реплик и бэкапов нет. HA для Valkey тоже нет, но он не критичен. - `COMMIT` подтверждается после записи WAL на диск (`synchronous_commit=on`, `fsync=on`); гарантия ограничена честностью fsync в Docker Desktop VM и одним диском. - Если Valkey недоступен ровно в момент logout, но не перезапускался (например, сетевой разрыв), отозванная сессия может приниматься ещё до 60 с. Граница задаётся `SESSION_CACHE_TTL_SECONDS`. - Запись в один чат сериализуется advisory lock: пропускная способность одного «горячего» чата ограничена. Коллизии `hashtext` изредка сериализуют разные чаты. - Символ U+0000 в `text`/`title`/`display_name` отклоняется с 400: тип `text` в PostgreSQL его не хранит. Тест lab1 с `\u0000` заменён на отдельный тест отказа. - Список чатов пользователя сортируется по `(created_at, id)` после соединения `chat_members` → `chats`, отдельного keyset-индекса нет. Для пользователя с тысячами чатов понадобится денормализация `created_at` в `chat_members`. - Устаревшие строки `sessions` не удаляются: фоновой очистки пока нет. - `expire_connections` срабатывает на первой ошибке соединения; запрос, который на неё попал, получает 503 и не повторяется прозрачно — автоматических повторов POST нет намеренно.