Files
2026-10-16 19:53:27 +03:00

27 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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 → после COMMIT SET 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}}; middleware X-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/, .env
  • docker compose --env-file .env up -d --build — postgres/migrate/valkey/api, api healthy
  • python 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 … SELECT 100 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 — кодирование, а не шифрование).