22 KiB
Отчёт — лабораторная 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.
# Запуск
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:<sha256(token) hex>, значение {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 нет намеренно.