Files
mtusi2026lab2/REPORT.md
T

24 KiB
Raw Blame History

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

  • Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «План запроса и восстановление»
  • Commit/PR: ветка solution/bpi2302-kushnarenko; коммит реализации 078c9f5 (078c9f5f789fe2f4ab994c9ee659c6d4ac37c06a); PR — mtusi2026/mtusi2026lab2#121
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg (PostgreSQL), redis-py (клиент Valkey), argon2-cffi (Argon2id); документация PostgreSQL (EXPLAIN, pg_dump), Valkey. Код lab1 перенесён (HTTP-слой, валидация, формат ошибок, лимиты). Использование ИИ: Codex был использован для помощи с написанием кода, выполнением некоторых заданий, и проверки качества.

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

Prerequisites: Docker Compose v2, Python ≥ 3.9 (публичные тесты), bash (Git Bash на Windows) для init-secrets.sh. Версии: python:3.12.12-slim-bookworm@sha256:593bd06e…, postgres:17.11-alpine@sha256:b0f9560a…, valkey/valkey:8.1.10-alpine@sha256:081c2f5c…, зависимости — requirements.txt (все версии закреплены).

sh scripts/init-secrets.sh                 # создаёт secrets/postgres_password и secrets/database_url (в Git не попадают)
cp .env.example .env                       # необязательные настройки (TTL сессии и т. д.)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться готовности (migrate выполняется один раз и завершается, api стартует после него):
curl http://127.0.0.1:8080/health/ready    # {"status":"ok"}
python3 tests/smoke.py --base-url http://127.0.0.1:8080          # make test
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080

На Windows (CreateProcess не запускает .sh) используйте scripts/restart.cmd — тот же docker compose restart. Остановка с сохранением данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v (удаляет volumes pgdata и valkeydata).

Миграции: сервис migrate (тот же образ, python -m app.migrate) выполняется до старта api, повторный запуск безопасен (таблица schema_migrations, контрольные суммы, advisory lock). Ручной запуск: docker compose --env-file .env run --rm migrate.

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

Клиент ─HTTP─▶ API (uvicorn, 1 процесс) ──asyncpg (пул ≤10)──▶ PostgreSQL 17  [volume pgdata] ← источник истины
                                         └─redis-py (timeout 0.2 c)──▶ Valkey 8   [volume valkeydata] ← кэш сессий
Роль Сервис compose Версия/digest Health/readiness Volume Сеть/порт Credentials
api api собирается из Dockerfile /health/ready (HEALTHCHECK), PostgreSQL критичен, Valkey — нет — 127.0.0.1:8080 DATABASE_URL_FILE → docker secret
postgres postgres 17.11-alpine@sha256:b0f9560a… pg_isready pgdata только сеть backend POSTGRES_PASSWORD_FILE → secret
valkey valkey 8.1.10-alpine@sha256:081c2f5c… valkey-cli ping valkeydata только сеть backend без пароля, не опубликован
миграции migrate (one-shot) образ api завершается кодом 0 — backend secret database_url
  • Источник истины — PostgreSQL: пользователи, чаты, участники, сообщения и сессии. Схема — migrations/0001_init.sql: PK/FK, UNIQUE(username), CHECK-ограничения, индексы messages(chat_id, created_at, id), chat_members(user_id, chat_created_at, chat_id). Создание чата — одна транзакция (чат + участники); неизвестный участник нарушает FK и откатывает всё.
  • Пароли: Argon2id (m=19 МиБ, t=2, p=1) в отдельном пуле потоков, не блокируя event loop; для неизвестного username проверяется фиктивный хеш (одинаковые ответ и время).
  • Сессии: токен — 256 бит (secrets.token_urlsafe(32)), в БД и в кэше хранится только SHA-256. TTL — SESSION_TTL_SECONDS (по умолчанию 3600), срок считается по часам БД (now() + интервал), использование токена срок не продлевает. Logout — revoked_at в БД + удаление ключа в Valkey.
  • Роль Valkey — read-through кэш сессий: ключ s:<sha256> → user_id|expires_ms, TTL = min(остаток жизни, SESSION_CACHE_TTL_SECONDS=60 с). Экономит один SELECT на каждый защищённый запрос. Политика expiry: TTL ключа + проверка expires_ms; инвалидация: logout/DEL. При недоступном Valkey кэш обходится (чтение из БД), circuit breaker на 5 с исключает ожидание таймаута; анонимный запрос никогда не считается доверенным. Окно устаревания: если Valkey был недоступен именно во время logout, ключ может прожить ≤ 60 с (после возврата сервиса). Valkey запущен с AOF (everysec) и maxmemory 64mb, чтобы тёплый кэш переживал рестарт, но корректность от этого не зависит — после потери кэша всё читается из PostgreSQL.
  • Пул соединений и таймауты: asyncpg pool max_size=10, ожидание соединения 2 с, command_timeout=5 с, connect timeout=2 с; все запросы параметризованы ($1…), конкатенации SQL нет. Сбои зависимости → 503 unavailable + Retry-After; для чтений один повтор при разорванном соединении пула (после рестарта БД).
  • Readiness: /health/ready = SELECT 1 к PostgreSQL (таймаут 1 с). Недоступность Valkey не останавливает API.
  • История и конкурентные вставки: created_at = clock_timestamp() БД (микросекунды), порядок (created_at, id). Две транзакции в одном чате могут зафиксироваться не в порядке created_at; читатель, уже прошедший позицию, может не увидеть позднее зафиксированное сообщение с меньшей меткой (snapshot между HTTP-запросами не гарантируется контрактом). Допущение документировано.
  • Лимиты lab1 сохранены: тело ≤ 64 КиБ (413), MAX_INFLIGHT → 429, потолок соединений → 503 JSON.
  • Соответствие переменных из .env.example: APP_*, SESSION_TTL_SECONDS, DATABASE_URL_FILE, SESSION_CACHE_TTL_SECONDS, DB_POOL_MAX используются как есть; VALKEY_URL задаётся в compose.yaml.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python3 tests/smoke.py … PASS evidence/checks.txt
Persistence: API и ВСЕ хранилища перезапущены, volumes сохранены, прежний токен работает tests/resilience.py --mode persistence --action-script scripts/restart.sh PASS; StartedAt postgres/valkey/api изменился, volumes на месте evidence/persistence_containers.txt
Миграции с нуля и повторно без дублирования docker compose up (первый запуск) и docker compose run --rm migrate первый запуск: migration_applied, повтор: applied=0 evidence/migrations.txt
Basic только на POST /auth/sessions, Bearer на остальных, X-User-Id игнорируется, expiry, logout student-tests/test_api.py 12 тестов OK evidence/checks.txt
Пароли хешируются KDF test_password_is_not_exposed_or_stored_plain в БД $argon2id$…, пароль не найден evidence/checks.txt
Роль Valkey, TTL, инвалидация, обход при отказе описание выше + test_dependencies.py::test_valkey_down_is_bypassed API работает без Valkey, logout виден без кэша evidence/checks.txt
Параметризованные запросы, пул, таймауты; гонка username; rollback test_concurrent_registration_of_same_username, test_chat_creation_is_atomic из 12 параллельных регистраций — 1×201 и 11×409; после неудачного создания чата числа строк в chats/chat_members не изменились evidence/checks.txt
Индекс истории и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений research/track2_plans_backup.py (105 000 сообщений) keyset-запрос: Index Scan, 6 буферов, 0.07 мс против Seq Scan + Sort, 2 632 буфера, 10 мс без индекса evidence/track2_explain_plans.txt
Expiry при коротком TTL student-tests/test_expiry.py (SESSION_TTL_SECONDS=2) через 3.5 с токен → 401 (кэш и БД), TTL не продлевается использованием evidence/checks.txt
Недоступность БД/кэша student-tests/test_dependencies.py PostgreSQL остановлен → 503 JSON + Retry-After, /health/ready 503, без токена 401; после старта БД API восстановился сам и сессия действует evidence/checks.txt
Нагрузочный профиль tests/load.py --duration 20 --concurrency 8 0 ошибок, ≈960 успешных RPS (урезан клиентом на urllib), p95 ≈ 16 мс evidence/load.json
Трек 2 research/track2_plans_backup.py см. ниже evidence/track2_results.json, track2_explain_plans.txt

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

Гипотеза. Составной индекс (chat_id, created_at, id) превращает страницу истории в чтение ~50 строк по индексу независимо от размера чата и позиции в нём, а цена — рост индекса и небольшое замедление записи. Логический backup pg_dump -Fc позволяет восстановить полное состояние в новом хранилище, граница потери данных — момент backup.

Методика (research/track2_plans_backup.py; PostgreSQL 17.11 в Docker, 1 CPU, shared_buffers=128MB; отдельная БД research, данные синтетические). Набор: 105 000 сообщений в 1 106 чатах неравномерного размера (1 × 60 000, 5 × 5 000, 100 × 100, 1 000 × 10), 200 пользователей. 4 варианта индексов × 4 запроса; EXPLAIN (ANALYZE, BUFFERS), медиана 9 прогонов (прогретый кэш). Стоимость записи: bulk INSERT … SELECT всех строк в пустую копию и 5 000 одиночных INSERT с тем же набором индексов.

Вариант индексов keyset, середина большого чата (50 строк) первая страница, большой чат OFFSET 30 000 первая страница, малый чат (10 сообщений) bulk-вставка 105 000 размер индексов
V0: только PK 10.20 мс (Seq Scan + Sort, 2 632 буфера) 9.15 мс 23.9 мс 5.79 мс 0.42 с 4.3 МБ
V1: (chat_id) 8.19 мс (Sort) 8.78 мс 22.7 мс 0.063 мс 0.49 с 5.2 МБ
V2: (chat_id, created_at, id) — выбран 0.076 мс (Index Scan, 6 буферов) 0.043 мс 3.49 мс 0.070 мс 0.53 с 12 МБ
V3: V2 + INCLUDE (sender_id) 0.068 мс 0.042 мс 3.59 мс 0.075 мс 0.50 с 15 МБ

Выводы: keyset-запрос на V2 в ≈130 раз быстрее V0 и V1 и читает 6 страниц вместо 2 632; глубокий OFFSET остаётся ≈50× медленнее keyset (нужно пройти 30 000 записей индекса) — поэтому API использует cursor. Стоимость индекса V2: +25 % времени bulk-вставки относительно V0 и +8 МБ на 105 000 строк; одиночные вставки различаются на уровне шума (30–38 мс на 5 000 строк — различие в пределах погрешности одного прогона). INCLUDE почти не даёт выигрыша (index-only scan невозможен, т. к. запрос читает text) и увеличивает индекс — отвергнут. Для малого чата индекс по chat_id достаточен.

Backup → восстановление в новое хранилище → сверка. pg_dump -Fc БД research → отдельный контейнер postgres:17.11-alpine с новым volume → pg_restore:

Показатель Результат
Размер дампа 7 765 134 байт (7.4 МБ, 105 000 сообщений)
Время backup / restore (RTO для этого объёма) 1.15 с / 0.85 с
Строки (users/chats/members) 200 / 1 106 / 1 106 — совпадают
Контрольная сумма всех сообщений (md5 по id, chat_id, sender_id, text, created_at) совпадает: 105000 105f3be9…
Выборочная страница истории (100 сообщений с позиции 30 000) md5 совпадает
Индексы восстановлены (ix_hist, messages_pkey)
25 сообщений, записанных после backup в восстановленной копии отсутствуют

Границы. RPO логического backup — интервал между дампами: всё записанное после него теряется (подтверждено 25 строками). Для меньшего RPO нужен непрерывный архив WAL / PITR — не реализован. RTO на 7 МБ ≈ 1 с — на промышленных объёмах растёт линейно с размером данных и перестройкой индексов; восстановление также требует остановки записи в старое хранилище. Измерения проведены на одном ноутбуке без конкурирующей нагрузки; абсолютные миллисекунды не переносимы, соотношения (Seq Scan/Sort против Index Scan) — переносимы.

Отказы (уровень 4)

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Рестарт API, PostgreSQL и Valkey с volumes прежний токен работает, данные на месте tests/resilience.py PASS готовность < 90 с; потери нет
Остановка Valkey кэш обходится, API работает 5 запросов с токеном — 200, быстрее 3 с; login/logout работают мгновенно; потери нет
Остановка PostgreSQL 503 вместо 500/анонимного доступа все защищённые запросы и login → 503 + Retry-After; ready=503; без токена 401 после запуска БД API восстанавливается сам; потери нет
TTL=2 с токен отвергается после срока 401 + WWW-Authenticate: Bearer —

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

  • Выдерживается: рестарт всех компонентов с сохранёнными volumes, отказ Valkey, кратковременная потеря PostgreSQL. Не выдерживается: потеря volume pgdata (нужен backup), отказ хоста Docker; PostgreSQL одиночный (SPOF), репликации нет.
  • Один API-процесс; нет балансировщика и идемпотентности отправки (lab3).
  • Окно инвалидации кэша (≤ 60 с) при недоступном Valkey в момент logout; создание сессии не ограничено rate limit (429 в контракте допустим, но не реализован).
  • Подтверждено экспериментами: выбор индекса, корректность backup/restore на 105 000 сообщений, поведение при отказах. Гипотеза без доказательства: поведение индексов на данных, значительно превышающих память.