Files
mtusi2026lab2/REPORT.md
T
Pavel Grigorev cd81572950
Skeleton contracts / contracts (pull_request) Canceled after 0s
Application / stack (pull_request) Canceled after 0s
Проверять аутентификацию раньше валидации тела запроса
2026-10-30 16:50:30 +03:00

30 KiB
Raw Blame History

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

  • Автор, группа: Григорьев Павел, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «План запроса и восстановление»
  • Commit/PR: ветка solution/bpi2302-grigoriev; ссылка на PR — после публикации
  • Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, psycopg 3.3.6 + psycopg-pool 3.3.3, argon2-cffi 25.1.0, redis-py 8.1.0 (полный список — requirements.txt); PostgreSQL 17.11, Valkey 8.1.11; документация PostgreSQL (transactions, EXPLAIN, pg_dump), Valkey (persistence, eviction), RFC 7617, RFC 6750, RFC 9106, OWASP Password Storage Cheat Sheet. При разработке использовался ИИ-ассистент.

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

Требования: Docker Engine 27.x с Compose v2 (проверено: Docker Desktop, Engine 27.2.0, WSL2 на Windows 10); Python 3.9+ только для тестов и скриптов (стандартная библиотека). make необязателен — ниже прямые команды.

Образы закреплены тегом и digest: python:3.12.15-slim-trixie@sha256:a6e34c59…, postgres:17.11-alpine@sha256:266d3c25…, valkey/valkey:8.1.11-alpine@sha256:2602ace2…. Зависимости Python — == для всех пакетов, включая транзитивные.

git clone <URL fork> mtusi2026lab2 && cd mtusi2026lab2
git switch solution/bpi2302-grigoriev
cp .env.example .env                   # несекретная конфигурация
python scripts/init_secrets.py         # secrets/postgres_password, database_url, database_url_restore (вне Git)
docker compose config --quiet
docker compose up -d --build --wait    # postgres, valkey → migrate (exit 0) → api healthy
docker compose ps -a

python tests/smoke.py --base-url http://127.0.0.1:8080                      # make test
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
#   на Windows: --action-script scripts/restart.cmd (Python на Windows не исполняет .sh)
python -m unittest discover -s student-tests -v                             # make student-test
python student-tests/expiry_check.py --ttl 2
python student-tests/failure_check.py

Bootstrap/миграции: одноразовый сервис migrate применяет migrations/*.sql по порядку под pg_advisory_lock, записывая версии в schema_migrations; API стартует только после его успешного завершения. Повтор безопасен: docker compose run --rm migrate → skip 0001_init: already applied.

На Windows используйте 127.0.0.1, а не localhost: Docker Desktop не слушает ::1, и каждый запрос к localhost ждёт ~2 с перед переходом на IPv4.

Остановка без потери данных: docker compose stop (или docker compose down — контейнеры удаляются, volume pgdata остаётся). Намеренное удаление учебных данных: docker compose --profile restore down -v (удаляет grigoriev-lab2_pgdata и grigoriev-lab2_pgdata_restore). Только данные эксперимента трека 2: docker compose exec postgres psql -U messenger -c "DROP DATABASE bench"; дампы — каталог backups/ (в .gitignore).

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

клиент ──HTTP 127.0.0.1:8080──► api (uvicorn + FastAPI, stateless)
                                  │  пул psycopg (1..10, wait 2 s, statement_timeout 5 s)
                                  ├──────────► postgres:17  — источник истины: users, chats, chat_members, messages, sessions
                                  │             volume pgdata
                                  └──────────► valkey:8     — кэш проверки сессии (TTL ≤ 60 s), persistence выключена
migrate (one-shot) ──► postgres          сеть backend: internal, порты БД/кэша не публикуются
Роль Service Версия/digest Health/readiness Volume Сеть/порт Credentials
api api сборка из Dockerfile GET /health/ready (проверяет PostgreSQL) — frontend+backend, 127.0.0.1:8080 secret database_url
миграции migrate тот же образ exit 0 — backend secret database_url
postgres postgres 17.11-alpine@sha256:266d… pg_isready pgdata backend POSTGRES_PASSWORD_FILE (secret)
redis_or_valkey valkey 8.1.11-alpine@sha256:2602… valkey-cli ping — (кэш) backend нет: только внутренняя сеть (учебное упрощение, hardening в lab7)
эксперимент restore postgres-restore, api-restore (profile restore) те же те же pgdata_restore backend, 127.0.0.1:8081 secret database_url_restore

Источник истины — PostgreSQL. Схема (migrations/0001_init.sql):

Таблица Ключи и ограничения Индексы под запросы
users PK id; username UNIQUE + CHECK ^[a-z0-9_]{3,32}$; длина display_name; password_hash (Argon2id) UNIQUE(username) — вход и гонка регистрации
chats PK id; created_by FK → users —
chat_members PK (chat_id, user_id); FK → chats, users; position (порядок member_ids), UNIQUE(chat_id, position) PK — проверка членства; (user_id, chat_id) — список чатов
messages PK id; FK (chat_id, sender_id) → chat_members (отправитель — участник); длина text 1–4000 (chat_id, created_at, id) — история keyset
sessions PK token_hash (sha256, 32 байта); FK user_id; expires_at > created_at (user_id), (expires_at)

id и created_at назначает БД (gen_random_uuid(), clock_timestamp()), сессия БД в UTC.

Транзакционные границы. Регистрация — один INSERT, гонку решает UNIQUE (unique_violation → 409). Вход — удаление истёкших сессий пользователя и вставка новой в одной транзакции. Создание чата — INSERT chats и INSERT chat_members … FROM unnest(...) WITH ORDINALITY в одной явной транзакции; неизвестный участник вызывает foreign_key_violation, откатывается всё (→ 400). Сообщение — один INSERT … SELECT … WHERE EXISTS(членство), проверка доступа и запись атомарны. Чтение истории — проверка членства и keyset-SELECT на одном соединении. Все запросы параметризованы.

Сессии. POST /auth/sessions принимает только Authorization: Basic без тела; username по regex, пароль 12–128 code points, разделение по первому :. Пароль сверяется Argon2id (t=2, m=19 MiB, p=1, параметры OWASP); для несуществующего пользователя вычисляется хеш-пустышка, ответ — одинаковый 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8". Токен — secrets.token_urlsafe(32) (256 бит), в БД хранится только sha256(token) и абсолютный expires_at = now() + SESSION_TTL_SECONDS — рестарт не продлевает TTL. Все остальные endpoint требуют Bearer; нет/истёк/отозван/Basic → 401 с WWW-Authenticate: Bearer realm="messenger"; X-User-Id не читается. Аутентификация проверяется раньше валидации тела: аноним с некорректным JSON на защищённом endpoint получает 401, а не 400. Logout удаляет строку сессии (204), повтор — 401.

Роль Valkey (уровень 4): кэш сессий. Ключ session:<hex sha256>, значение {user, expires_at}. Пишется при входе (write-through) и при промахе (cache-aside). TTL = min(SESSION_CACHE_TTL_SECONDS=60, остаток сессии), при чтении expires_at проверяется повторно — кэш не может продлить сессию. Инвалидация: logout удаляет строку в PostgreSQL, затем DEL в Valkey. Известное окно: гонка «чтение сессии из БД ↔ logout» может вернуть отозванную запись в кэш не дольше 60 с. Flush/restart Valkey — только промахи; persistence не нужна (--save "" --appendonly no), maxmemory 64mb, volatile-ttl. Отказ Valkey: socket timeout 200 мс, после ошибки кэш 5 с не опрашивается (circuit breaker), запросы идут в PostgreSQL. В API dns_opt timeout:1 attempts:1: имя остановленного контейнера пропадает из DNS Docker, и без опции резолв занимал 8 с.

Readiness. Критична только PostgreSQL (SELECT 1 из пула за ≤ 1 с); Valkey некритичен. Отказ БД: OperationalError/PoolTimeout → 503 unavailable за ≤ ~2 с; запрос без проверенной сессии никогда не получает 200.

Перенесено из lab1: middleware X-Request-Id, формат ошибок, pydantic-модели (strict, extra forbid), формат cursor, Dockerfile (non-root, healthcheck, exec CMD), student-tests (переведены на Bearer). Изменено: хранилище in-memory → PostgreSQL, X-User-Id → Basic/Bearer, CreateUser.password, keyset теперь в SQL, монотонные метки времени процесса заменены временем БД (порядок задаёт (created_at, id)).

Соответствие .env.example:

Переменная Где используется По умолчанию
APP_HOST, APP_PORT uvicorn в контейнере 0.0.0.0, 8080
APP_ENV лог старта lab
APP_SHUTDOWN_TIMEOUT graceful shutdown uvicorn 5
SESSION_TTL_SECONDS срок сессии 3600
DATABASE_URL_FILE файл secret с DSN /run/secrets/database_url
CACHE_URL адрес Valkey (пусто — кэш выключен) redis://valkey:6379/0
SESSION_CACHE_TTL_SECONDS верхняя граница TTL кэша 60
DB_POOL_MIN, DB_POOL_MAX, DB_POOL_TIMEOUT_SECONDS, DB_STATEMENT_TIMEOUT_MS пул и таймауты 1, 10, 2, 5000

SESSION_STORE из skeleton не используется: сессии всегда в PostgreSQL.

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

Все файлы — evidence/, получены 2026-10-29 на стенде из раздела «Эксперименты».

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py (make test) PASS: lab2 public API scenario smoke.txt
3: данные и сессии переживают рестарт API и хранилищ без удаления volumes tests/resilience.py --mode persistence с scripts/restart.cmd (= restart.sh) PASS; ps до/после: postgres, valkey, api перезапущены; в логах database system is shut down → ready to accept connections; volumes на месте persistence.txt
3: PostgreSQL с PK/FK, UNIQUE username, миграции с нуля и повторно без дублей migrations/0001_init.sql; test_migrations_are_idempotent повторный migrate → skip … already applied, schema_migrations и данные не изменились student-tests.txt
3: создание чата атомарно test_chat_creation_is_rolled_back в логе PostgreSQL FK-ошибка с UUID несуществующего участника, количество строк chats/chat_members не изменилось student-tests.txt
3: Basic только на входе, Bearer на остальном, X-User-Id не даёт доступ, expiry и logout, KDF test_auth.py, test_db.py Basic/X-User-Id/мусор → 401 Bearer; X-User-Id не подменяет пользователя; logout → 204, повтор 401; password_hash начинается с $argon2id$, в sessions — sha256 токена student-tests.txt
3: secrets/volumes не в Git git status --ignored .env, secrets/, backups/ игнорируются .gitignore
4: Valkey с ролью, TTL, политикой инвалидации раздел «Архитектура»; expiry_check.py TTL ключа сессии в Valkey ≤ TTL сессии expiry.txt
4: параметризованные запросы, ограниченный пул, таймауты src/store.py, src/db.py %s-параметры везде; пул 1..10, wait 2 с, statement_timeout 5 с, connect 3 с код
4: гонка регистрации одного username test_parallel_registration_of_same_username 20 одновременных: 1×201 + 19×409; вход только с паролем победителя student-tests.txt
4: rollback составной операции см. «создание чата атомарно» — student-tests.txt
4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥ 10 000 сообщений, без полного scan python research/track2.py explain 200 000 сообщений; Limit → Index Scan using messages_chat_history_idx, без Sort; 9–13 буферов на первой и на 90%-й странице чата из 100 000 explain-history.txt
4: expiry при коротком SESSION_TTL_SECONDS python student-tests/expiry_check.py --ttl 2 сразу 200, через 3,5 с 401 с Bearer challenge, logout истёкшим → 401 expiry.txt
4: logout, неверный пароль test_auth.py см. выше; неверный пароль и несуществующий логин — одинаковый 401 student-tests.txt
4: недоступность Redis/БД python student-tests/failure_check.py Valkey stop: всё 2xx через PostgreSQL (первый запрос 1,0 с, далее ≤ 0,03 с); PostgreSQL stop: 503 за ≈ 2,0 с, неизвестный токен → 503 (не 200), вход → 503, live 200, ready 503; после старта тот же токен и данные failure.txt
4 (из lab1): SIGTERM student-tests/sigterm_check.py docker stop 0,57 с, exit 0, 5xx — 0 sigterm.txt
5, трек 2 python research/track2.py all см. следующий раздел track2/

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

Стенд: Windows 10 Pro 19045, Docker Desktop (Engine 27.2.0, WSL2), VM Docker: 12 CPU, 1,9 GiB RAM; лимиты контейнерам не заданы; клиент на той же машине. PostgreSQL 17.11, shared_buffers=128MB, остальное по умолчанию, track_io_timing=on.

Нагрузка (python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json, closed loop, POST в один новый чат — история растёт от 0 до ~9 300 сообщений; без прогрева): 9 296 успешных, 0 ошибок, 309 RPS, p50 10,4 / p95 30,8 / p99 34,8 мс. После прогона: api 74 MiB, postgres 35 MiB, valkey 3,6 MiB. Генератор closed-loop (coordinated omission), клиент делит CPU с сервером — это не предел пропускной способности.

Трек 2. План запроса истории и восстановление

Гипотезы.

  1. Запрос страницы истории WHERE chat_id = ? [AND (created_at, id) > cursor] ORDER BY created_at, id LIMIT 51 с индексом (chat_id, created_at, id) читает O(limit) страниц независимо от размера чата и глубины страницы. Индексы (chat_id) или (created_at, id) проигрывают на части чатов из-за неравномерности размеров. OFFSET растёт линейно с глубиной.
  2. Составной индекс увеличивает стоимость записи заметно меньше, чем ускоряет чтение.
  3. pg_dump даёт согласованный снимок на момент начала: восстановление в новое хранилище воспроизводит все данные до снимка (count и контрольные суммы), записи после начала дампа теряются (RPO = момент начала дампа).

Методика (research/track2.py, research/seed.sql, повторяемо: python research/track2.py all).

  • Отдельная БД bench со схемой из тех же миграций. 200 000 сообщений, setseed(0.42): 1 чат × 100 000, 20 × 3 000, 4 000 × 10 (сильный перекос). Длина текста 20–400 символов, времена равномерно за 30 дней, вставка в порядке времени — физический порядок таблицы не совпадает с chat_id, как в реальной переписке. Таблица 96 MB.
  • Варианты индекса истории: pk_only, (chat_id), (created_at, id), (chat_id, created_at, id) (рабочий). Перед каждым вариантом остальные индексы удаляются, затем ANALYZE.
  • Запросы — точная форма из приложения, LIMIT 51: первая страница, keyset и OFFSET на глубине 50% и 90%, для большого, среднего и маленького чата. По 3 прогрева + 15 замеров EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON), медиана и p95 времени, буферы, форма плана.
  • Запись: (а) EXPLAIN ANALYZE INSERT 20 000 строк в транзакции с ROLLBACK после CHECKPOINT, медиана из 5 — время узла Insert (таблица + индексы), время FK-триггера, WAL на строку, без шума commit-fsync; (б) pgbench с одной вставкой на транзакцию, 4 клиента, 10 с × 5 повторов.
  • Восстановление: пустой volume pgdata_restore → pg_dump -Fc БД bench и messenger во время параллельной записи pgbench (маркер during dump) → docker compose cp → pg_restore -j 4 в postgres-restore → ANALYZE → сверка count и md5 (все сообщения по id, первая и 90%-я страница большого чата, весь маленький чат) → api-restore на восстановленной messenger с прежним токеном.

Результаты чтения (медиана, мс; в скобках — буферы shared hit+read). Полностью — evidence/track2/results.md, reads.json.

запрос pk_only (chat_id) (created_at, id) (chat_id, created_at, id)
большой чат, первая страница 31,6 (12 361) 29,1 (12 361) 0,055 (9) 0,057 (9)
большой, keyset 90% 25,1 (12 303) 25,9 (12 303) 0,057 (17) 0,054 (11)
большой, OFFSET 90% 135,5 130,2 41,1 (17 650) 132,1 (12 361) Seq Scan + Sort на диск
средний (3 000), keyset 90% 23,4 3,4 (2 695) 0,354 (314) 0,057 (49)
маленький (10), первая 20,1 0,061 (13) 21,7 (12 361) 0,039 (13)
маленький, keyset 50% 22,9 0,064 24,4 (12 273) 0,050 (8)
  • Рабочий индекс: все страницы всех чатов — 0,04–0,06 мс и 4–13 буферов, план Limit → Index Scan, без Sort. Гипотеза 1 подтверждена.
  • (chat_id): маленький чат быстро, но большой — Seq Scan (индекс невыгоден при 50% таблицы), средний — Bitmap + Sort всех 3 000 строк.
  • (created_at, id): идеален для большого чата (его сообщения — половина таблицы, первые 51 по времени находятся сразу), но для маленького чата пришлось бы пройти весь индекс до 10 нужных строк — планировщик выбирает Seq Scan (21,7 мс). Именно неравномерность размеров отличает эти варианты.
  • OFFSET: даже с рабочим индексом на глубине 90 000 планировщик выбрал Parallel Seq Scan + внешнюю сортировку (15 MB на диск), 120–132 мс против 0,054 мс у keyset — в ~2 400 раз. Доп. замер (planner_random_page_cost_*.json): при random_page_cost=1.1 (значение для SSD вместо HDD-значения 4) план становится Index Scan, 21,3 мс — всё равно в ~400 раз медленнее keyset и линейно растёт с глубиной.

Результаты записи (writes.json):

вариант INSERT, мс/1000 строк FK-проверка, мс/1000 WAL, байт/строку размер индексов, MiB pgbench TPS медиана [min..max]
pk_only 9,80 31,3 2 793 0 784 [529..3 584]
(chat_id) 11,24 30,1 2 951 1,5 3 541 [2 776..3 601]
(created_at, id) 10,85 30,8 2 877 7,8 3 491 [3 477..3 522]
(chat_id, created_at, id) 11,79 31,3 3 036 11,2 3 505 [2 774..3 540]
рабочий + (created_at, id) 12,78 30,8 3 121 ≈ 19 (11,2 + 7,8) 3 553 [783..3 579]
  • Рабочий индекс: +20% времени узла INSERT и +8,7% WAL на строку относительно таблицы без индексов истории, 11,2 MiB на 200 000 строк. Чтение страницы ускоряется в 400–2 400 раз. Гипотеза 2 подтверждена.
  • Неожиданно: ~70% времени вставки — проверка составного FK messages(chat_id, sender_id) → chat_members, а не индексы.
  • pgbench (commit на каждую строку) не различает варианты: пропускная способность упирается в fsync WAL виртуального диска Docker Desktop, у которого время sync при checkpoint скачет 0,01–1,7 с; отдельные прогоны падают до ~500–800 TPS в любом варианте (медиана pk_only — 3 таких прогона из 5). Вывод о стоимости индекса делаем по детерминированному пакетному замеру.

Результаты восстановления (restore.json):

этап с
pg_dump -Fc bench (200 000 сообщений, 13,4 MiB) 1,69
pg_dump -Fc messenger 0,51
копирование дампов через хост 1,52
pg_restore -j 4 bench (данные + индексы + FK) 2,36
pg_restore messenger 0,42
ANALYZE 0,74
запуск и readiness api-restore 6,74
RTO на этом стенде ≈ 14
  • Count всех таблиц и все md5 совпали (mismatches: []). api-restore на восстановленной БД: GET /users/me с прежним токеном → 200, история чата совпадает с исходной.
  • Запись во время дампа: всего закоммичено 11 172 строки-маркера, в backup — 4 482 (закоммиченные до снимка; до старта pg_dump их было ≥ 3 787), 6 690 после начала снимка потеряны при восстановлении из этого дампа. Гипотеза 3 подтверждена: RPO логического backup = момент начала pg_dump.

Обсуждение и ограничения.

  • Все замеры «тёплые» (данные в shared buffers/кэше ОС); холодный кэш на Docker Desktop честно не воспроизводится (кэш ОС VM не сбрасывается). Буферы и форма плана — основная метрика, миллисекунды — ориентир для этого ноутбука.
  • Запросы с литералами; приложение через psycopg после 5 повторов использует prepared statements, и PostgreSQL может выбрать generic plan. Для рабочего индекса он тот же (Index Scan), для OFFSET/перекошенных данных может отличаться.
  • random_page_cost=4 оставлен по умолчанию; рекомендация для SSD — 1.1, но keyset от этого не зависит.
  • RTO растёт примерно линейно с объёмом (restore + построение индексов): при 13 MiB дампа — секунды, на гигабайтах — минуты–часы; ускоряют -j, физический backup (pg_basebackup). RPO логического дампа = период между дампами; для секундного RPO нужен PITR (архив WAL + базовая копия) — не реализован.
  • pg_dump одной БД не содержит роли/глобальные объекты (pg_dumpall --globals-only); у нас роль создаётся образом при init.
  • Backup содержит хеши паролей и хеши действующих сессий — восстановленная копия принимает старые токены; дамп нужно хранить как секрет (backups/ вне Git).
  • Один Docker-host: нет защиты от потери хоста/диска, backup хранится на той же машине.
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
restart api + postgres + valkey (restart.sh) данные и прежний токен сохраняются PASS, тот же токен ≈ 10 с до ready; потерь нет
docker compose stop valkey обход кэша, всё работает 2xx; первый запрос 1,0 с, далее ≤ 0,03 с мгновенно; потерь нет
docker compose stop postgres ограниченный 503, анонимный не проходит 503 за ≈ 2 с, неизвестный токен 503, ready 503, live 200 ready через 13,1 с после stop (включая ~10 с проверок во время отказа); потерь нет
SESSION_TTL_SECONDS=2 истечение сессии 401 через 3,5 с —
SIGTERM api корректная остановка 0,57 с, exit 0 —
backup → restore в новый volume совпадение данных count и md5 совпали, API со старым токеном RTO ≈ 14 с; потеряны записи после начала дампа (6 690)

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

  • Выдерживается: рестарт любого контейнера, отказ Valkey (деградация без ошибок), временный отказ PostgreSQL (503 и восстановление). Не выдерживается: потеря volume/хоста без backup; единственная БД — точка отказа.
  • Окно устаревания кэша сессий при гонке с logout — до 60 с (TTL); закрыть можно tombstone-ключом при logout.
  • Valkey без пароля и TLS — допустимо только во внутренней сети учебного стенда; TLS для внешнего API появится в lab7, Basic по HTTP — только локально.
  • Rate limiting входа (защита от перебора паролей) не реализован.
  • Истёкшие сессии удаляются при следующем входе пользователя; фоновой чистки нет (индекс expires_at готов для неё).
  • Для lab3: API stateless, сессии общие (PostgreSQL), миграции вынесены — готово к нескольким репликам; добавятся Idempotency-Key и X-Instance-Id.