Files
mtusi2026lab2/REPORT.md

22 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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 нет намеренно.