Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: TODO
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, asyncpg, redis-py (клиент к Valkey), argon2-cffi; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617. Код lab1 перенесён из собственного решения. При переносе на PostgreSQL, написании тестов и отчёта использовался ИИ-ассистент Claude (Anthropic); решения проверены и объяснимы автором.

Запуск из чистого clone

Требования: Docker Engine с Compose v2 (проверено: Docker 28.0.1, Compose 2.33.1), Python 3.9+ для тестов (проверено на 3.14), make.

Роль Образ Версия
api / migrate mtusi-messenger:lab2, сборка из Dockerfile python:3.12.8-slim-bookworm, зависимости закреплены в requirements.txt
postgres postgres:17.6-alpine3.22 PostgreSQL 17.6
valkey valkey/valkey:8.1.4-alpine3.22 Valkey 8.1.4
cp .env.example .env              # при занятом 8080 поменять APP_PORT
make secrets                      # scripts/init-secrets.sh: случайные пароли в ./secrets (в .gitignore)
docker compose --env-file .env config --quiet
make up                           # docker compose up -d --build --wait: postgres -> migrate -> api; ждёт healthcheck /health/ready
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
make test-student BASE_URL=http://localhost:8080      # собственные тесты; останавливает/запускает контейнеры
make explain                                          # засев 70 000 синтетических сообщений + EXPLAIN
  • Миграции: отдельный одноразовый сервис migrate (python -m app.migrate). API стартует только после его успешного завершения. Повторный запуск безопасен (schema_migrations + pg_advisory_lock).
  • Безопасная остановка без потери данных: make down (= docker compose --profile ttl-test down, volume pgdata сохраняется).
  • Намеренное удаление учебных данных: docker compose --profile ttl-test down -v (удаляет volume messenger-lab2_pgdata; необратимо).
  • Действия оператора: только make secrets перед первым запуском. Секреты в образ и Git не попадают.

Архитектура и решения

клиент ──HTTP──> api (FastAPI/uvicorn, 1 процесс)
                  ├──> postgres  : источник истины — users, chats, chat_members, messages, sessions
                  └──> valkey    : кэш поиска сессии (только ускорение, может пропасть в любой момент)
migrate (one-shot) ──> postgres  : применение migrations/*.sql

Перенесено из lab1: модели pydantic, формат ошибок и X-Request-Id, keyset-курсор, привязанный к ресурсу, проверки контракта (пустой текст, дубликаты участников, 404 на чужой чат), Dockerfile (non-root, graceful SIGTERM). In-memory Store заменён на репозиторий PostgreSQL (app/storage.py).

Изменено по контракту lab2: password при регистрации, POST /auth/sessions через Basic, Bearer на всех бизнес-endpoint, DELETE /auth/sessions/current. X-User-Id не читается вообще.

Схема БД (migrations/0001_init.sql)

Таблица Ключи и ограничения Индексы
users PK id; UNIQUE(username); CHECK формата username и длины display_name уникальный по username
chats PK id; CHECK длины title —
chat_members PK (chat_id, user_id); FK на chats и users; position хранит порядок member_ids (user_id, chat_id) для списка чатов пользователя
messages PK id; FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником на уровне БД; CHECK длины текста (chat_id, created_at, id) для истории
sessions PK token_hash (sha256 токена, сам токен не хранится); FK user_id; expires_at, revoked_at (expires_at)

Время (created_at, expires_at) назначает PostgreSQL (clock_timestamp()), в API выдаётся RFC 3339 UTC с микросекундами. Порядок (created_at, id); сравнение uuid в PostgreSQL побайтовое и совпадает с порядком UUID-int в тестах.

Транзакционные границы

  • Создание чата — одна транзакция: INSERT chats + INSERT chat_members … FROM unnest($2::uuid[]). Неизвестный участник отлавливает FK внутри транзакции → ROLLBACK → 400. Предварительного SELECT нет, поэтому откат реально выполняется (тест db_integrity_test.py).
  • Регистрация — один INSERT; гонку одинаковых username решает UNIQUE (UniqueViolationError → 409), а не проверка «SELECT, потом INSERT».
  • Отправка сообщения — одна инструкция INSERT … SELECT … WHERE EXISTS(участник): проверка доступа и запись атомарны.
  • Logout — UPDATE sessions SET revoked_at (истина), затем надгробие в Valkey.
  • COMMIT подтверждает запись в WAL; при настройках по умолчанию (fsync=on, synchronous_commit=on) подтверждённое сообщение переживает падение процесса PostgreSQL. Ответ 201 отправляется только после COMMIT.

Аутентификация и сессии

  • Пароль: Argon2id (argon2-cffi, профиль RFC 9106 low-memory: t=3, m=64 MiB, p=4). Хеширование в thread pool, не более 4 одновременно (PASSWORD_HASH_CONCURRENCY), чтобы ограничить RAM. Для несуществующего username проверяется фиктивный хеш, поэтому время ответа одинаковое.
  • Basic разбирается строго: base64 → UTF-8 → разделение по первому : (двоеточие в пароле допустимо), username только ASCII, пароль 12–128 code points. Любая ошибка даёт одинаковый 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8".
  • Токен — secrets.token_urlsafe(32) (256 бит). В БД и кэше хранится только sha256(token). Быстрый хеш здесь уместен: токен случайный, перебирать его бессмысленно, в отличие от человеческого пароля, которому нужен медленный KDF.
  • Срок жизни SESSION_TTL_SECONDS (по умолчанию 3600) задаётся в БД как expires_at, поэтому рестарт его не продлевает.

Роль Valkey (уровень 4): кэш сессий

  • Источник истины — PostgreSQL. Valkey хранит session:<sha256 hex> → {user, expires_at}, чтобы не ходить в БД на каждом запросе; /users/me обслуживается вообще без БД.
  • Expiry: TTL записи = min(остаток сессии, SESSION_CACHE_MAX_SECONDS=300), плюс при чтении из кэша сравнивается expires_at. Просроченная сессия не принимается ни из кэша, ни из БД.
  • Инвалидация: при logout сначала revoked_at в PostgreSQL, затем в Valkey пишется надгробие revoked (а не DEL). Заполнение кэша идёт через SET NX, поэтому параллельный запрос, прочитавший БД до отзыва, не сможет вернуть сессию в кэш.
  • Сбой записи tombstone (исправлено по замечанию к PR): раньше ошибка записи в Valkey проглатывалась и logout отвечал 204, хотя в кэше оставалась действующая запись сессии; после восстановления Valkey отозванный токен снова получал 200 до 5 минут. Теперь:
    • logout отвечает 503 («не подтверждён»), если tombstone не записан; сессия в PostgreSQL при этом уже отозвана;
    • хеш токена запоминается в процессе как «отзыв ожидает записи», и запись из кэша для него игнорируется: проверка идёт в PostgreSQL → 401;
    • фоновая задача раз в секунду повторяет запись tombstone, пока Valkey не ответит, но не дольше SESSION_CACHE_MAX_SECONDS (за это время устаревшая запись истекла бы сама).
  • Persistence не нужна и выключена (save "", appendonly no): после flush или рестарта Valkey первая проверка идёт в PostgreSQL. Потеря кэша ничего не ломает, это подтверждает тест сохранности, где Valkey тоже перезапускается.
  • Отказ Valkey: таймаут 0.3 с, затем circuit breaker на 5 с, в течение которых кэш не используется. Readiness при этом остаётся 200: Valkey не критичен.
  • Конфигурация с requirepass лежит в секрете secrets/valkey.conf, порт наружу не публикуется.

Устойчивость к отказам

  • asyncpg pool: max_size=10, таймауты подключения 3 с, захвата соединения 3 с, команды 5 с. min_size=0 позволяет API стартовать при недоступной БД (тогда readiness = 503).
  • Недоступность или рестарт PostgreSQL (OSError, PostgresConnectionError, InterfaceError, TooManyConnections, admin shutdown, statement timeout) превращается в 503 unavailable без деталей. Без токена по-прежнему 401. Токен, который нельзя проверить (нет в кэше, БД недоступна), получает 503 и никогда не считается аутентифицированным.
  • Readiness: 200 только при успешном SELECT 1 в PostgreSQL. Liveness всегда 200.
  • Все SQL-запросы параметризованы ($1…), строк, склеенных из пользовательского ввода, нет.

Переменные .env.example → реальная конфигурация

Переменная Где используется
APP_HOST / APP_PORT uvicorn внутри контейнера слушает 0.0.0.0:8080; APP_PORT в .env — порт хоста (127.0.0.1:${APP_PORT})
APP_ENV передаётся в контейнер, логики не меняет
SESSION_TTL_SECONDS срок сессии; у api-short-ttl = 2
DATABASE_URL_FILE /run/secrets/database_url (compose secret из secrets/database_url)
SESSION_STORE=postgres сессии хранятся в PostgreSQL
CACHE_URL_FILE /run/secrets/cache_url, URL Valkey; без него кэш отключён
SESSION_CACHE_MAX_SECONDS, DB_POOL_MAX, SHORT_TTL_PORT добавлены этой работой (см. выше)

Доказательства критериев

Файлы в evidence/ сняты 2026-10-07 (explain_history), 2026-10-08 UTC (основные) и 2026-10-15 UTC (logout_cache_failure, на отдельном стенде с портом 18280) на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose).

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make check, make test PASS обоих evidence/smoke.txt
3: данные и сессии переживают рестарт API и хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt api/postgres/valkey изменились, volume тот же, тот же токен читает данные evidence/persistence.txt
3: миграции с нуля и повторно docker compose -p lab2-clean up на пустом volume, затем ещё run migrate 1 applied now, 0 before, затем 0 applied now, 1 before; smoke PASS на новом стенде evidence/fresh_migrations.txt
3: PK/FK, UNIQUE username, атомарное создание чата student-tests/db_integrity_test.py чат с неизвестным участником → 400, в chats 0 строк с этим title и 0 чатов без участников evidence/student_tests.txt
3: Basic только на /auth/sessions, Bearer, X-User-Id игнорируется, logout, KDF auth_test.py, smoke, db_integrity_test.py Basic/X-User-Id на бизнес-endpoint → 401; повторный logout → 401; hash начинается с $argon2id$ evidence/student_tests.txt
3: secrets/volumes не в Git git status, .gitignore (secrets/, .env) секреты только в ./secrets, в репозитории нет .gitignore
4: Valkey реально используется, TTL, инвалидация dependency_test.py ключи session:* с TTL ≤ 300, после logout значение revoked evidence/student_tests.txt
4: параметризованные запросы, ограниченный pool, таймауты код app/storage.py, app/config.py $n-параметры, max_size=10, таймауты 3/3/5 с —
4: гонка регистрации db_integrity_test.py 20 параллельных запросов → 1×201, 19×409, 1 строка evidence/student_tests.txt
4: rollback составной операции db_integrity_test.py см. строку «атомарное создание чата» evidence/student_tests.txt
4: индекс истории + EXPLAIN на ≥10 000 make explain 70 000 сообщений, в чате 20 000; с индексом Index Scan, 4 буфера, 0.03 мс на первой и глубокой (#15000) странице; без индекса Seq Scan + Sort, 940 буферов, 3–4 мс evidence/explain_history.txt
4: expiry при коротком TTL auth_test.py против api-short-ttl (TTL=2) через 3 с → 401 (и из кэша) evidence/student_tests.txt
4: logout, неверный пароль auth_test.py неверный пароль и неизвестный user дают одинаковый 401 evidence/student_tests.txt
4: logout при сбое записи в кэш dependency_test.py (docker compose pause valkey во время logout) до исправления: 204 и отозванный токен → 200 из кэша; после: 503, токен → 401, tombstone дописан после unpause evidence/logout_cache_failure.txt
4: недоступность Redis/БД dependency_test.py Valkey stop: ready=200, запросы ~4 мс; PostgreSQL stop: live=200, ready и бизнес-запросы 503 мгновенно, непроверенный токен → 503, без токена 401; после start всё восстанавливается без рестарта API evidence/student_tests.txt
Graceful shutdown (из lab1) sigterm_test.sh docker compose stop api → exit 0 за < 1 с evidence/student_tests.txt

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh: stop api, valkey, postgres → up данные и сессия на месте, токен тот же PASS, кэш пустой, сессии берутся из PostgreSQL ~11 с весь hook / потерь нет
docker compose stop valkey API работает без кэша 200, ~4 мс на запрос (breaker), revoked-токен 401 мгновенно / потерь нет (кэш)
docker compose pause valkey во время logout logout не сообщает об успехе, отозванный токен не принимается 503; после unpause токен → 401, tombstone записан фоновой задачей ~1 с после восстановления Valkey / потерь нет
docker compose stop postgres 503 без зависаний, анонимный доступ не появляется ready 503, бизнес 503, live 200, всё за < 0.1 с API восстанавливается сам после start postgres, без своего рестарта; подтверждённые данные целы
SIGTERM api graceful exit 0 exit 0, «Application shutdown complete» docker compose up -d --wait api

Ограничения и следующие шаги

  • Один Docker-host, по одному PostgreSQL и Valkey, без репликации: потеря host или диска = потеря сервиса (бэкапы не настроены, это трек 2 пятёрки).
  • Защита от устаревшей записи после неудачного logout живёт в памяти процесса API. Если сам API перезапустится до того, как Valkey снова станет доступен, или (с lab3) запрос придёт на другую реплику, устаревшая запись может приниматься до SESSION_CACHE_MAX_SECONDS (≤ 5 мин). Клиент при этом получил 503, а не 204. Для нескольких реплик нужен общий механизм, например версия сессии в кэше или pub/sub-инвалидация.
  • Просроченные строки sessions не удаляются автоматически (есть индекс expires_at для будущей периодической очистки).
  • /health/ready не проверяет Valkey намеренно.
  • Тело запроса проверяется до аутентификации: на неавторизованный запрос с битым JSON вернётся 400, а не 401 (особенность FastAPI). Это не раскрывает данных.
  • make test создаёт синтетических пользователей при каждом запуске; удаления в API нет.
  • Нагрузочное измерение (make load) не делалось: для уровня 4 не требуется.