27 KiB
Отчёт — лабораторная 2
- Автор, группа: Никифорова Екатерина, БВТ2301
- Целевая оценка: 5, выбранный трек 5: Трек 2 «План запроса и восстановление» (уровни 3 и 4 тоже выполнены)
- Commit/PR: #64
- Источники, библиотеки и помощь ИИ: FastAPI 0.115 + Uvicorn 0.30 (как в lab1), psycopg 3.2 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617.
Запуск из чистого clone
Требования: Docker Engine ≥ 24 с Compose v2, Python ≥ 3.9 (для тестов), sh (Git Bash на Windows).
sh scripts/init-secrets.sh # случайные пароли -> secrets/*, копия .env.example -> .env (всё в .gitignore)
docker compose --env-file .env config --quiet # проверка конфигурации
docker compose --env-file .env up -d --build # postgres -> migrate (одноразово) -> valkey -> api
until curl -fs localhost:8080/health/ready; do sleep 1; done
python tests/smoke.py --base-url http://localhost:8080 # публичный smoke
cd tests_student && python test_integration.py && python test_dependencies.py && cd .. # расширенные тесты API (11 + зависимости)
python scripts/track2_indexes.py --out evidence/track2-indexes.json # трек 2: замеры индексов
python scripts/track2_restore.py --src-url "$DATABASE_URL" --dst-admin-url "$DST_URL" --out evidence/track2-restore.json
Оператору больше ничего делать не нужно. Миграции применяет сервис migrate (идемпотентно, под advisory-lock).
Безопасная остановка: docker compose --env-file .env stop (данные и тома целы). Намеренное удаление учебных данных:
docker compose --env-file .env down -v && rm -rf secrets — только это стирает тома; в restart.sh и тестах -v не используется.
Архитектура и решения
Клиент ──HTTP──> api (FastAPI, Uvicorn) ──> PostgreSQL 17 (источник истины, том pgdata)
└──────────────> Valkey 8 (кэш сессий, AOF, том valkeydata)
migrate (одноразово) ──> PostgreSQL
| Роль | Service | Образ (зафиксирован) | Health | Том | Сеть/порт | Credentials |
|---|---|---|---|---|---|---|
| api | api |
сборка из Dockerfile, база python:3.11.9-slim (как в lab1), зависимости из requirements.txt |
/health/ready (API + PostgreSQL) |
нет (stateless, read-only rootfs) | 127.0.0.1:8080 |
secrets-файлы database_url, cache_url |
| postgres | postgres |
postgres:17.6-alpine |
pg_isready |
pgdata |
только внутренняя сеть | POSTGRES_PASSWORD_FILE |
| valkey | valkey |
valkey/valkey:8.1.3-alpine |
valkey-cli ping |
valkeydata |
только внутренняя сеть | --requirepass из secrets-файла |
| migrate | migrate |
образ api | — (завершается) | — | внутренняя | database_url |
Источник истины. Пользователи, чаты, участники, сообщения и сессии — в PostgreSQL. Valkey хранит только производные данные (кэш сессий) и может быть потерян без потери данных.
Схема (app/migrations/). users (UNIQUE username + CHECK формата), chats, chat_members (PK (chat_id,user_id)),
messages (композитный FK (chat_id,sender_id) -> chat_members: в чат пишет только участник — инвариант в БД, а не только в коде),
sessions (PK = SHA-256 токена). Индексы: messages(chat_id, created_at, id) — история; chats(created_at,id);
chat_members(user_id, chat_id); sessions(expires_at).
Транзакционные границы. (1) Регистрация: Argon2id считается до транзакции (без удержания соединения), затем один INSERT;
гонку одинаковых username решает UNIQUE → 409. (2) Создание чата: проверка участников + INSERT chats + INSERT chat_members
в одной транзакции; любая ошибка → ROLLBACK. (3) Сообщение: один INSERT; COMMIT происходит до ответа 201.
(4) Логин: проверка пароля → INSERT sessions в транзакции → после COMMIT прогрев кэша.
Сессии и кэш (уровень 4).
- Источник истины — таблица
sessions(в БД хранится SHA-256 токена, не сам токен). Токен —secrets.token_urlsafe(32)(256 бит). - Кэш: cache-aside
sess:v1:<sha256(token)>→{user, exp}. Чтение: Valkey → при промахе PostgreSQL →SET NX PX. - Expiry:
expires_atв PostgreSQL; в кэше TTL =min(SESSION_CACHE_TTL_SECONDS, остаток жизни)иexpпроверяется в самой записи — срок не зависит от точности TTL ключа. TTL не продлевается ни обращениями, ни рестартом. - Инвалидация: logout =
DELETEв PostgreSQL → после COMMITSET sess:v1:… "revoked"(tombstone, TTL = cache TTL). Заполнение кэша —SET NX, поэтому медленный параллельный читатель не «воскресит» отозванную сессию поверх tombstone. Негативные результаты не кэшируются (защита от забивания кэша мусорными токенами). Пользователи в этом API неизменяемы, поэтому инвалидации данных пользователя не требуется. - Persistence Valkey: AOF
everysec+ том. Строго она не обязательна (истина в PostgreSQL), но стенд подтверждает рестарт всех хранилищ. - Известная граница: если logout выполнен, пока Valkey недоступен, tombstone не записывается, и после возврата Valkey (AOF сохраняет TTL) отозванная сессия может
ещё ≤
SESSION_CACHE_TTL_SECONDS(60 с) приниматься из кэша. Это осознанный компромисс; снижается уменьшением TTL кэша.
Пул, таймауты, ошибки. psycopg_pool: max_size=16 на процесс (2 процесса uvicorn = 32 из 100 соединений PostgreSQL), потоков sync-обработчиков 24, ожидание соединения 3 с, connect_timeout=3, statement_timeout=5 s, lock_timeout=3 s,
idle_in_transaction_session_timeout=10 s, check_connection при выдаче (после рестарта PostgreSQL мёртвые соединения отбрасываются). Valkey: таймаут 0,25 с +
circuit breaker 2 с. Все запросы параметризованы (psycopg передаёт параметры отдельно от SQL; конкатенации SQL нет). Недоступность БД → 503 unavailable
без деталей; неожиданное исключение → 500 internal_error, стек — только в серверный лог.
Критичные зависимости readiness. PostgreSQL — критична (/health/ready = 503 без неё). Valkey — нет (ready остаётся 200, кэш обходится).
Что перенесено из lab1 и что изменено. Приложение — прямое развитие main.py из lab1 (FastAPI/Uvicorn, тот же Dockerfile-подход).
- Сохранено без изменений по поведению: маршруты и коды ответов; формат ошибки
{"error":{code,message,request_id}}; middlewareX-Request-Id(входящее значение теперь принимается только если оно безопасно:[A-Za-z0-9._-]{1,64}, иначе генерируется новое; заголовок есть и в ответах 500/503); keyset-пагинация с курсором, привязанным к ресурсу (messages/chats+ id) и порядком(created_at, id); строгая валидация (лишние поля → 400, неверный Content-Type → 415, пустой/пробельный текст → 400); 404 вместо 403 для чужого чата;/health/liveи/health/ready;--timeout-graceful-shutdown 5; тесты lab1 (tests/test_own.py,tests/test_race.py, 8+1 сценариев) перенесены на Bearer. - Изменено (объявленные переходы lab2): добавлен
passwordпри регистрации (Argon2id);POST /auth/sessionsс Basic;Authorization: BearerвместоX-User-Id(заголовок игнорируется); словари подRLockзаменены PostgreSQL;threading.RLockбольше не нужен — согласованность обеспечивают транзакции и ограничения БД;/health/readyпроверяет PostgreSQL. - Заменено осознанно: pydantic-модели lab1 (
extra="forbid") заменены строгим разбором JSON (app/validation.py): он отвергает дубли ключей,NaN, NUL и одиночные суррогаты (после них PostgreSQL возвращал бы 500), а проверка доступа (404) выполняется до валидации тела; автодокументация FastAPI (/docs) отключена — контракт вcontracts/openapi.json. - Исправлено по сравнению с lab1: регулярка
^…$пропускала username с завершающим\n(в Python$совпадает перед\n) — теперьfullmatch;len(display_name)считался до проверки типов — теперь тип проверяется первым.
Переменные .env.example → код. APP_HOST/APP_PORT — как в lab1, совпадают с CMD uvicorn main:app --host 0.0.0.0 --port 8080; число процессов — WEB_CONCURRENCY (читает сам uvicorn); SESSION_TTL_SECONDS → app/config.py (срок сессии);
DATABASE_URL_FILE, CACHE_URL_FILE → пути к secrets-файлам; SESSION_STORE = postgres | postgres+cache; SESSION_CACHE_TTL_SECONDS — TTL записи кэша.
Доказательства критериев
Основные замеры выполнены в песочнице (без Docker, PostgreSQL 16.15, Redis 7). Дополнительно всё проверено на реальном Docker Compose-стенде (Windows 11 + Docker Desktop, PostgreSQL 17.6, Valkey 8.1.3):
sh scripts/init-secrets.sh— 4 секрета вsecrets/,.envdocker compose --env-file .env up -d --build— postgres/migrate/valkey/api, api healthypython tests/smoke.py --base-url http://localhost:8080→ PASS- Persistence: полный рестарт api+valkey+postgres тем же Bearer-токеном → 200 (
evidence/persistence-my.txt) - Миграции идемпотентны:
migrateповторно → «nothing to do» (evidence/migrations-my.txt) - Свои тесты: 11/11 passed (
evidence/tests-my.txt) - Тесты зависимостей (
evidence/tests-deps-my.txt) - Трек 2 — индексы (2 прохода):
evidence/track2-indexes-my.json,evidence/track2-indexes-pass2-my.json - Трек 2 — backup/restore со сверкой md5:
evidence/track2-restore-my.txt(SRC=DST: users 1, chats 563, messages 102000, sessions 1; md5 совпал) - Теги
postgres:17.6-alpineиvalkey/valkey:8.1.3-alpineпроверены черезdocker pull
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Тесты lab1 в новой аутентификации + гонка регистрации | pytest tests/test_own.py tests/test_race.py -v |
15 passed | test-results.txt |
| Публичный smoke | python tests/smoke.py |
PASS: lab2 public API scenario |
test-results.txt, smoke_docker.txt |
| Контракт offline | python scripts/check_contract.py |
PASS: offline skeleton structure… |
test-results.txt |
| PostgreSQL: таблицы, PK/FK, UNIQUE, миграции с нуля | python -m app.migrate ×2 |
1-й запуск: применены 0001, 0002; 2-й: «nothing to do» | migrations.txt, migrations-my.txt |
| Атомарное создание чата | tests_student/test_db_rollback.py |
FK-ошибка после INSERT chats → 0 строк остаётся |
test-results.txt |
Basic только на /auth/sessions, Bearer везде, X-User-Id игнорируется |
smoke + test_integration.py |
401 с корректными WWW-Authenticate |
test-results.txt |
| Пароли — KDF | код app/security.py |
Argon2id (m=19 MiB, t=2, p=1), соль на пароль, rehash при смене параметров | — |
| Рестарт API и хранилищ, сессии живы | docker compose stop api valkey postgres && up -d |
тот же токен работает после рестарта | persistence-restart.txt, persistence-my.txt |
| Secrets/volumes не в Git | .gitignore, .dockerignore |
secrets/, .env исключены; в образ не копируются |
— |
| 4: Valkey реально используется | evidence/cache-role.txt |
ключи sess:v1:<sha256>, PTTL ≤ 60 000 мс; tombstone после logout; сессия переживает FLUSHALL |
cache-role.txt |
| 4: параметризованные запросы, пул, таймауты | код app/db.py, app/repo.py |
см. «Пул, таймауты» | — |
| 4: гонка регистрации | test_integration.py::registration_race_same_username |
16 параллельных → ровно один 201, 15×409 | test-results.txt |
| 4: индекс истории, EXPLAIN на ≥10 000 | scripts/explain_history.py (100 000 строк) |
keyset с индексом: Index Scan, 4 буфера, 0,03–0,04 мс; без индекса: Seq Scan 1235 буферов, ~8–9 мс | explain-history.txt |
| 4: expiry (короткий TTL) | tests_student/test_expiry.py 2 |
после 3,5 с: 401 на users/me, chats, logout |
test-results.txt |
| 4: logout, неверный пароль | smoke + logout_revokes_only_that_session |
204; повтор 401; неверный пароль 401 | test-results.txt |
| 5 (трек 2): ≥100 000 сообщений, ≥2 индекса/запроса, цена записи | scripts/track2_indexes.py (2 прохода, Windows + Docker) |
см. раздел «Трек 5.2» | track2-indexes*.json, track2-indexes-my.json, track2-indexes-pass2-my.json |
| 5 (трек 2): backup → восстановление → сверка | docker exec pg_dump/pg_restore + md5 |
counts SRC=DST (users 1, chats 563, messages 102000, sessions 1), md5 совпал | track2-restore-my.txt |
| 4: недоступность Valkey/БД | tests_student/test_dependencies.py |
Valkey off/flush → 200; PostgreSQL off → ready=503; после старта токен целы |
dependency-failure.txt, tests-deps-my.txt |
Пагинация: pagination_walk_and_cursor_binding — 250 сообщений от 8 параллельных писателей, обход страницами 100/37, нет потерь/дублей/перестановок; курсор чужого чата → 400.
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Полный рестарт API + PostgreSQL + Valkey, тома сохранены | сессии и данные целы, прежний токен работает | PASS (persistence-restart.txt, persistence-my.txt) |
потерь нет |
| Остановка Valkey | API работает через PostgreSQL | все запросы 200, ready 200, задержка < 2,5 с (circuit breaker) |
мгновенно; потерь нет |
FLUSHALL Valkey |
сессии берутся из PostgreSQL, кэш наполняется заново | токены работают | мгновенно |
| Остановка PostgreSQL | 503, никакого доверия анониму | ready/бизнес 503 (unavailable), без токена 401 |
после старта БД API восстановился автоматически; потерь нет |
| Короткий TTL (2 с) | сессия перестаёт действовать | 401 после истечения | — |
Методика EXPLAIN: PostgreSQL 16.15 (песочница) и 17.6 (Docker Windows), 100 000 строк (1 чат 20 000 + 4 чата-шума по 20 000), VACUUM ANALYZE,
сравнение «без индекса» выполнено удалением индекса в откатываемой транзакции.
Трек 5.2. План запроса и восстановление
Гипотезы
- H1. Составной индекс
(chat_id, created_at, id)даёт страницу истории за O(размер страницы) для чата любого размера и любой глубины; индекс только поchat_idи «глобальный»(created_at, id)— нет. - H2. Дополнительный индекс удорожает запись; цена растёт с шириной индекса (покрывающий
INCLUDE (sender_id, text)дороже всех). - H3. Логический backup (
pg_dump -Fc) восстанавливается в новый сервер без потери данных на момент снапшота; всё записанное после начала дампа теряется (RPO = возраст бэкапа).
Методика (повторяемая: scripts/track2_indexes.py, scripts/track2_restore.py)
- Данные: 100 000 сообщений в 563 чатах с неравномерными размерами: 1×50 000, 1×20 000, 1×10 000, 10×1 000, 50×100, 500×10; текст 10–400 символов; плюс 2 000 одиночных вставок в процессе замера записи (итого ≈102 000).
- Конфигурации (5): C0 только PK · C1
(chat_id)· C2(chat_id, created_at, id)· C3 то жеINCLUDE (sender_id, text)· C4(created_at, id). - Запросы: Q1 первая страница гиганта (50 000) · Q2 keyset на глубине 40 000 · Q3 первая страница чата из 10 сообщений · Q4 keyset в середине чата из 1 000 · Q5
OFFSET 40000(антипример). Страница = 50 (+1) строк. - Чтение: 20 прогревочных + 300 замеров на запрос, p50/p95 клиентской латентности, плюс
EXPLAIN (ANALYZE, BUFFERS). - Запись: (а)
INSERT … SELECT100 000 строк, 3 повтора, медиана; (б) 2 000 одиночныхINSERTс коммитом. - Повторяемость: два прохода, второй — в обратном порядке конфигураций.
Результаты — собственные замеры (Windows 11 + Docker Desktop, PostgreSQL 17.6)
Проход 1 (evidence/track2-indexes-my.json):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
|---|---|---|---|---|---|---|
| C0 (PK only) | 3.00 | 1.770 | 0.0 | 20.143 | 14.824 | 14.878 |
C1 (chat_id) |
3.06 | 1.787 | 0.9 | 14.884 | 14.300 | 0.957 |
C2 (chat_id, created_at, id) |
3.11 | 1.733 | 6.9 | 1.219 | 1.196 | 0.932 |
C3 + INCLUDE |
3.79 | 1.741 | 35.6 | 1.184 | 1.221 | 1.050 |
C4 (created_at, id) |
3.26 | 1.904 | 5.0 | 3.453 | 1.492 | 32.912 |
Проход 2 (evidence/track2-indexes-pass2-my.json, обратный порядок):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
|---|---|---|---|---|---|---|
| C4 | 3.38 | 1.714 | 5.0 | 3.433 | 1.418 | 15.920 |
| C3 | 5.17 | 2.267 | 35.5 | 2.224 | 1.837 | 1.347 |
| C2 | 3.62 | 1.847 | 6.9 | 1.327 | 1.861 | 1.095 |
| C1 | 3.86 | 2.258 | 0.9 | 17.321 | 16.562 | 1.417 |
| C0 | 3.65 | 1.822 | 0.0 | 18.452 | 18.306 | 14.635 |
Выводы по гипотезам
- H1 подтверждена для C2: 1.2–1.9 мс на любой странице любого чата (от 10 до 50 000 сообщений). C1 деградирует на гиганте (14.9–17.3 мс), C0 — везде 14–20 мс. C4 хуже всего для маленького чата (15.9–32.9 мс): планировщик не может эффективно отфильтровать крошечный чат по глобальному порядку.
- Покрывающий C3 не оправдан: Q1–Q3 того же порядка, что C2, но индекс в 5 раз больше (35.6 МиБ против 6.9 МиБ) и bulk-загрузка дороже (3.79 с и 5.17 с против 3.11 с и 3.62 с у C2).
- Решение: оставлен C2 (он же в миграции
0001_core.sql).
Backup → восстановление в новое хранилище → сверка (evidence/track2-restore-my.txt)
- Backup:
docker exec messenger-lab2-postgres-1 pg_dump -U messenger -d messenger -Fc --no-owner -f /tmp/dump.dump→ 3.62 МБ. - Новое хранилище: отдельный контейнер
pg-restore-target(PostgreSQL 17.6, порт 5434).docker exec pg_restore --no-owner --exit-on-error— без ошибок. ЗатемANALYZE. - Сверка (совпала с источником):
| Таблица | SRC | DST |
|---|---|---|
| users | 1 | 1 |
| chats | 563 | 563 |
| messages | 102000 | 102000 |
| sessions | 1 | 1 |
| md5 всех сообщений | 440f9224c9a3e355f7fbd551e2a078eb |
440f9224c9a3e355f7fbd551e2a078eb |
- Работоспособность копии: публичный smoke и 11 собственных тестов прошли на API, подключённом к восстановленной БД.
Время восстановления (RTO) и границы потери данных (RPO)
- Измерено (102 тыс. строк, ~65 МиБ): dump ≈0,8 с + restore ≈1,3 с + analyze ≈0,2 с ≈ 2,3 с. Это не оценка для продакшена; на 100× больших данных восстановление займёт минуты.
- RPO у логического дампа = возраст дампа. После дампа записано 500 сообщений — в копии их нет (102 000 против 102 500 в источнике). Для сокращения RPO нужны WAL-архивация +
pg_basebackup(PITR) или синхронная репликация — в работе не реализованы. - Безопасность при восстановлении: отозванная после дампа сессия в копии «воскресла». Практика: после восстановления из бэкапа очистить
sessions. - Что не проверялось: восстановление в другую мажорную версию PostgreSQL, повреждённый дамп, шифрование бэкапа.
Ограничения методики
- 1 CPU, клиент на той же машине, 2 прохода (не повторы с доверительными интервалами); p95 одиночных вставок шумит.
- Данные синтетические; реальные распределения могут сместить цифры.
- Горячий кэш: все данные поместились в
shared_buffers/page cache; на «холодном» диске разрыв между Seq Scan и индексом был бы больше.
Ограничения проверки
- Основные замеры трека 2 сделаны в песочнице Claude (без Docker, PostgreSQL 16.15). Дополнительно проверено на Windows 11 + Docker Desktop (PostgreSQL 17.6, Valkey 8.1.3): init-secrets.sh, docker compose up -d --build, smoke PASS, persistence, миграции, трек 2 (индексы + backup/restore). См.
evidence/*-my.*. - Теги образов проверены:
docker pull postgres:17.6-alpineиdocker pull valkey/valkey:8.1.3-alpine— оба существуют. - В evidence использованы PostgreSQL 16 и Redis 7 (песочница) и 17.6/Valkey 8.1.3 (Docker Windows); на проверяемые свойства это не влияет.
- Нагрузочный профиль (
make load) не снимался — для уровня 4 не требуется.
Ограничения и следующие шаги
- Выдерживается: рестарт API/PostgreSQL/Valkey с томами; потеря/сброс/недоступность Valkey; кратковременная недоступность PostgreSQL (503 → автоматическое восстановление).
- Не выдерживается: потеря тома PostgreSQL без свежего бэкапа (логический backup делается вручную, расписания и PITR нет); отказ единственного хоста.
- Семантика конкурентных вставок:
created_atставитсяclock_timestamp()в момент вставки, а не COMMIT. Для точной гарантии нужна монотонная последовательность (bigserial/outbox) — следующий шаг. - Кэш истории сообщений не делался (трек 1 не заявлен): сейчас кэшируются только сессии.
- HTTP без TLS допустим только для локального стенда с синтетическими данными (Basic — кодирование, а не шифрование).