30 KiB
Отчёт — лабораторная 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. План запроса истории и восстановление
Гипотезы.
- Запрос страницы истории
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 растёт линейно с глубиной. - Составной индекс увеличивает стоимость записи заметно меньше, чем ускоряет чтение.
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 INSERT20 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.