Files
2026-11-13 20:42:10 +03:00

29 KiB
Raw Permalink Blame History

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

  • Автор, группа: Казаков Амин, БВТ2303
  • Целевая оценка: 5, трек 2 «План запроса и восстановление»
  • Commit/PR: ветка solution/bvt2303_kazakov, ссылка на PR — после публикации
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, psycopg 3 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Redis persistence, RFC 7617. Эндпоинты на SQL, кэш сессий, собственные тесты, скрипт EXPLAIN, схема БД, мигратор и скрипт исследования трека 2 писались вместе с ИИ-ассистентом Claude пошагово. Весь код разобран и объясняется на защите.

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

Проверено на: Windows 11, Docker Desktop (Engine 29.8.2, Compose 5.5.1), 12 CPU / 8 GB RAM для Docker; Python 3.14 на хосте для тестов (тестам нужна только стандартная библиотека, скрипту EXPLAIN — psycopg).

Образы: postgres:17.6-alpine, redis:7.4.2-alpine, API собирается из python:3.11.9-slim; версии Python-зависимостей закреплены в requirements.txt.

# 1. локальные настройки (в Git не попадают); задать свой POSTGRES_PASSWORD
cp .env.example .env

# 2. сборка и запуск; миграции применяет само API при старте
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

# 3. дождаться готовности
curl -f http://localhost:8080/health/ready     # {"status":"ok"}

# 4. публичные проверки
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
#    на Windows без make:
#    python tests/smoke.py
#    python tests/resilience.py --mode persistence --action-script scripts/restart.cmd

# 5. собственные проверки уровня 4 (управляют контейнерами через docker compose)
python student-tests/test_auth.py
python student-tests/test_race.py
python student-tests/test_expiry.py
python student-tests/test_outage.py
python student-tests/explain_history.py        # pip install "psycopg[binary]"

# 6. исследование уровня 5, трек 2 (отдельная база track2_lab, рабочая не трогается)
python student-tests/track2_research.py indexes   # 160 000 сообщений, 4 варианта индекса, стоимость записи
python student-tests/track2_research.py backup    # pg_dump -> новый контейнер + пустой volume -> pg_restore -> сверка

Остановка с сохранением данных: docker compose --env-file .env down (volume pgdata остаётся). Намеренное удаление учебных данных: docker compose --env-file .env down -v — удаляет volume с БД безвозвратно.

Бутстрап БД: отдельных действий оператора нет. При старте API берёт pg_advisory_xact_lock, создаёт schema_migrations и применяет в одной транзакции все ещё не применённые migrations/*.sql по порядку имён. Повторный старт ничего не дублирует.

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

клиент ──HTTP──> api (FastAPI, uvicorn, :8080)
                  ├──> postgres:5432  — источник истины: users, chats, chat_members, messages, sessions
                  └──> redis:6379     — только кэш сессий (TTL), без persistence

Из lab1 перенесено: контракт эндпоинтов, формат ошибок с X-Request-Id, keyset-пагинация по (created_at, id), health. Изменено: словари в памяти заменены PostgreSQL; X-User-Id заменён на Bearer-сессии; регистрация требует пароль; добавлены Redis и миграции.

Схема (migrations/001_init.sql): PK у всех таблиц; FK chat_members → chats/users, messages → chats/users, sessions → users; UNIQUE(username) и CHECK по регулярке и длинам; составной PK chat_members(chat_id, user_id) запрещает дубли участников. Индексы: messages(chat_id, created_at, id) — история; chat_members(user_id) — «мои чаты»; sessions(user_id).

Транзакционные границы:

  • Создание чата — одна транзакция: INSERT chats + INSERT chat_members для всех участников. Неизвестный участник даёт FK violation, вся транзакция откатывается, ответ 400.
  • Регистрация — один INSERT. Гонку одинаковых username решает UNIQUE в PostgreSQL: проигравшие получают unique_violation и ответ 409.
  • Остальные записи — одиночные INSERT/UPDATE в autocommit-блоке пула. 201 возвращается только после COMMIT.

Аутентификация: пароль хешируется Argon2id (argon2-cffi, параметры по умолчанию). POST /auth/sessions принимает только Basic. Для несуществующего username тоже выполняется проверка против хеша-заглушки, поэтому время ответа и сам 401 одинаковые. Токен — secrets.token_urlsafe(32) (256 бит). В БД хранится только sha256(token): по дампу БД токенами воспользоваться нельзя. Сессия: expires_at = now() + SESSION_TTL_SECONDS; logout пишет revoked_at. Проверка: revoked_at IS NULL AND expires_at > now(). Сначала проверяется аутентификация (401), затем членство в чате (404 для чужого).

Redis — роль, источник истины, expiry, инвалидация:

  • Источник истины — sessions в PostgreSQL. Redis — read-through кэш session:<sha256> → {user, expires_at}.
  • TTL записи = min(оставшаяся жизнь сессии, SESSION_CACHE_MAX_TTL=60 с), поэтому кэш никогда не продлевает сессию.
  • Logout: сначала revoked_at в PostgreSQL, затем в Redis пишется надгробие revoked. Кэш заполняется через SET NX, поэтому параллельный запрос не перезапишет надгробие.
  • Redis без persistence (--save "" --appendonly no), потому что он не единственное хранилище. После restart или FLUSHALL кэш пуст, сессии читаются из PostgreSQL. Отозванные сессии не «воскресают», это проверено тестом.
  • Redis недоступен: фоновый поток делает PING раз в 2 с. Пока Redis «лежит», запросы идут сразу в PostgreSQL. /health/ready от Redis не зависит.

Пул и таймауты: psycopg_pool.ConnectionPool(min 1, max 10, timeout=5 с, check_connection), connect_timeout=5, statement_timeout=5000 мс. У Redis socket_timeout и connect_timeout по 0,3 с. Все SQL-запросы параметризованы (%s). В f-строки подставляются только константные фрагменты условий, без пользовательских данных.

Readiness: критичная зависимость одна — PostgreSQL (SELECT 1 за ≤2 с, иначе 503). Redis не критичен.

Переменные .env.example → реальная конфигурация:

Логическое имя skeleton Реализация
APP_HOST, APP_PORT 0.0.0.0:8080 в Dockerfile/compose
SESSION_TTL_SECONDS одноимённая переменная, по умолчанию 3600
DATABASE_URL_FILE compose собирает DATABASE_URL из POSTGRES_* в .env; код поддерживает и DATABASE_URL_FILE
SESSION_STORE postgres (источник истины) + redis (кэш)
CACHE_URL_FILE REDIS_URL (поддерживается и REDIS_URL_FILE)

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make check, make test оба PASS evidence/smoke.txt
Данные и сессии переживают рестарт API, PostgreSQL и Redis tests/resilience.py --mode persistence с scripts/restart.cmd; отдельно sh scripts/restart.sh + smoke PASS: тот же токен читает те же данные; StartedAt всех трёх контейнеров изменился, volume pgdata не пересоздавался evidence/persistence.txt
PK/FK, UNIQUE username, миграции с нуля, повторный запуск без дублей migrations/001_init.sql, db.run_migrations на пустом volume создаются 5 таблиц и schema_migrations; повторный старт API ничего не применяет migrations/, db.py
Атомарное создание чата / rollback student-tests/test_race.py чат с неизвестным участником → 400; список чатов не изменился; 0 чатов без участников в БД evidence/test_race.txt
Basic только на POST /auth/sessions, Bearer на остальных, X-User-Id не даёт доступа smoke + student-tests/test_auth.py Basic/X-User-Id/чужой токен на бизнес-эндпоинте → 401 с WWW-Authenticate: Bearer evidence/test_auth.txt
Неверный пароль test_auth.py 401 с WWW-Authenticate: Basic ...; для неизвестного пользователя ответ такой же evidence/test_auth.txt
Logout test_auth.py 204 без тела; тот же токен → 401, хотя он был в кэше; повторный logout → 401 evidence/test_auth.txt
Expiry при коротком TTL student-tests/test_expiry.py (API перезапускается с SESSION_TTL_SECONDS=2) через 3,5 с тот же токен → 401 evidence/test_expiry.txt
Пароли — password KDF app.py: argon2.PasswordHasher (Argon2id) в users.password_hash строка $argon2id$... app.py
Secrets/volumes не в Git .gitignore (.env, backups/, volumes/) git status не показывает .env —
Redis для сессий с TTL; источник истины и инвалидация test_auth.py ключ session:* появляется после запроса; после logout — 401; после FLUSHALL действующая сессия работает, отозванная остаётся отозванной evidence/test_auth.txt, cache.py
Гонка регистрации одинакового username test_race.py 20 параллельных запросов → 201 ×1, 409 ×19 evidence/test_race.txt
Параметризованные запросы, ограниченный пул, таймауты код %s-параметры; пул max 10, timeout 5 с; statement_timeout 5 с db.py, app.py
Индекс истории + EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений student-tests/explain_history.py 25 000 сообщений, чат на 15 000. С индексом keyset-страница: Index Scan, 51 буфер, 0,09 мс. Без индекса: Seq Scan + Sort, 334 буфера, 1,95 мс evidence/explain-history.txt
Пагинация без полного scan там же keyset читает ~51 буфер на любой глубине; OFFSET 10000 при том же индексе читает 10 095 буферов (для сравнения, в API не используется) evidence/explain-history.txt
Недоступность Redis student-tests/test_outage.py docker compose stop redis: вход, чтение, запись и logout работают через PostgreSQL; первый запрос до обнаружения отказа ≈4 с, следующие ≈0,03 с; ready = 200 evidence/test_outage.txt
Недоступность БД test_outage.py docker compose stop postgres: запись → 503 unavailable за ≈5 с; аноним → 401; неизвестный токен → 503, не 200; ready → 503. После start тот же токен работает, история цела evidence/test_outage.txt

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

Стенд: один Docker-хост (Windows 11, Docker Desktop, 12 CPU / 8 GB), все контейнеры без CPU/RAM-лимитов. Исследование уровня 5 — в разделе «Трек 2» ниже.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh: stop api → restart postgres, redis → start api данные и действующий токен сохраняются PASS persistence; smoke после рестарта PASS ~10–15 с до ready; подтверждённых потерь нет
docker compose stop redis обход кэша, без отказа клиентам всё работает через PostgreSQL; ready 200 первый запрос ≈4 с (DNS/таймаут), далее без задержки; после start кэш снова используется через ≤2 с
redis-cli FLUSHALL действующие сессии из БД, отозванные остаются отозванными так и есть мгновенно; потерь нет
docker compose stop postgres ограниченная ошибка 503, без доверия анониму 503 за ≈5 с, аноним 401, ready 503 после start ≈несколько секунд; неподтверждённая запись (503) не появилась, подтверждённые на месте
SESSION_TTL_SECONDS=2 истечение сессии без продления кэшем через 3,5 с → 401 —

Ответы на вопросы защиты:

  • COMMIT гарантирует атомарность и видимость изменений. Durability при сбое ОС/питания зависит от fsync=on и synchronous_commit=on: это значения по умолчанию, они не менялись. С synchronous_commit=off последние подтверждённые транзакции могут потеряться.
  • Сессии: источник истины — PostgreSQL. После flush или restart Redis кэш пуст, сессии подтягиваются из БД, отозванные остаются отозванными.
  • Аутентификация vs доступ: Bearer отвечает на вопрос «кто ты» (иначе 401). Членство в chat_members отвечает на вопрос «можно ли тебе в этот чат» (иначе 404, без раскрытия существования).
  • Хеш пароля vs checksum: Argon2 намеренно медленный и с солью, чтобы перебор паролей был дорогим. sha256 быстрый и подходит для токена: у токена 256 бит случайности, перебирать его бессмысленно, а проверка нужна на каждом запросе.

Трек 2 (оценка 5): план запроса и восстановление

Скрипт: student-tests/track2_research.py. Он работает в отдельной базе track2_lab того же PostgreSQL 17.6, к рабочей базе приложения не прикасается. Сырые результаты лежат в evidence/track2-indexes.txt и evidence/track2-backup-restore.txt.

Гипотеза

  1. Составной индекс (chat_id, created_at, id) даёт постоянную стоимость страницы истории (десятки буферов, доли миллисекунды) независимо от размера чата и глубины страницы. Любая более простая альтернатива деградирует хотя бы на одном профиле чатов: огромном, среднем или маленьком.
  2. Цену за индекс видно в объёме WAL и в размере индекса, а не во времени одиночного INSERT.
  3. pg_dump + pg_restore в новое хранилище возвращают данные бит в бит на момент снимка. Всё, что записано после снимка, теряется (RPO = интервал между бэкапами).

Методика

  • Данные (генерация повторяемая, setseed(0.42)): 160 000 сообщений в 1 055 чатах с сильно неравномерным распределением:

    вид чата чатов сообщений в каждом всего
    huge 1 60 000 60 000
    large 4 10 000 40 000
    medium 50 1 000 50 000
    small 1 000 10 10 000

    Длина текста тоже неравномерна (10 + 1990·random()³): большинство сообщений короткие, максимум ≈2000 символов, в среднем ≈512. Таблица messages — 90,6 MB heap.

  • Варианты индекса (PK по id есть всегда): A (chat_id, created_at, id) — текущий; B (chat_id); C (created_at, id); D без индекса.

  • Чтение: запрос приложения list_messages (LIMIT 51) на чатах huge / medium / small: первая страница, keyset-страница на 90 % глубины, а для huge ещё и OFFSET. EXPLAIN (ANALYZE, BUFFERS), медиана 7 прогонов, тёплый кэш.

  • Запись: (а) INSERT … SELECT на 20 000 строк, разбросанных по всем чатам; (б) 2 000 отдельных INSERT, как делает API. Каждая вставка выполняется в транзакции с ROLLBACK, чтобы данные не менялись между вариантами. Медиана 3 прогонов; WAL меряется через pg_current_wal_insert_lsn().

  • Восстановление: pg_dump -Fc из compose-контейнера → новый контейнер postgres:17.6-alpine с новым пустым volume → pg_restore → сверка количества строк по всем таблицам, md5 по всем сообщениям, md5 распределения по чатам, списка индексов и 7 конкретных сообщений. После дампа в источник пишется 1 сообщение, чтобы показать границу потери.

Результаты: чтение (время, мс / прочитано буферов)

страница A (chat_id, created_at, id) B (chat_id) C (created_at, id) D нет
huge, первая 0,084 / 8 40,1 / 12 509 (Seq Scan + Sort) 0,069 / 51 29,5 / 14 269
huge, keyset после 54 000-го 0,073 / 18 20,7 / 4 410 (Bitmap + Sort 6 000 строк) 0,574 / 1 060 26,0 / 14 211
huge, OFFSET 54000 105,8 / 11 691 (Seq Scan + Sort) 116,6 / 12 509 100,5 / 13 389 97,3 / 14 269
medium (1 000), первая 0,080 / 15 0,875 / 110 3,0 / 5 750 25,5 / 14 269
medium, keyset после 900-го 0,069 / 9 0,769 / 110 7,5 / 2 274 26,1 / 14 211
small (10), первая 0,050 / 5 0,114 / 4 24,9 / 13 389 (Seq Scan) 24,6 / 14 269
small, keyset после 9-го 0,069 / 4 0,114 / 4 6,4 / 2 276 28,6 / 14 181

Результаты: запись

вариант размер индекса построение 20 000 строк одним INSERT WAL, Б/строка 2 000 INSERT по одному WAL, Б/строка
A 9,0 MB 148 мс 1 055 мс (52,8 мкс/стр.) 363 294 мс (146,8 мкс/стр.) 364
B 1,1 MB 99 мс 1 209 мс (60,4) 308 301 мс (150,6) 340
C 6,2 MB 115 мс 1 089 мс (54,4) 334 282 мс (141,0) 367
D — — 1 098 мс (54,9) 227 277 мс (138,3) 257

Результаты: backup и восстановление

этап результат
pg_dump -Fc 2,89 с, файл 9,0 MB (сжатый формат; индексы хранятся как DDL, а не как данные)
старт нового PostgreSQL на пустом volume 4,66 с до готовности по TCP
pg_restore (данные + PK/FK + пересборка индексов) 3,47 с
RTO (хранилище + restore, без доставки файла) ≈8,1 с на 160 000 сообщений
сверка: users / chats / chat_members / messages 200 / 1 055 / 2 110 / 160 000 — совпало
md5 всех сообщений и md5 распределения по чатам совпали
7 выбранных сообщений (5 случайных + 2 последних в huge) совпали поле в поле
индекс истории после restore есть и используется: тот же Index Scan, 18 буферов
сообщение, записанное после дампа отсутствует в восстановленной базе

Выводы

  1. Гипотеза 1 подтвердилась. Только вариант A на всех профилях держит 4–18 буферов и < 0,1 мс. Причина: индекс отсортирован так же, как запрос (chat_id = …, затем ORDER BY created_at, id), поэтому PostgreSQL сразу встаёт на позицию курсора и читает ровно 51 запись.
    • B (chat_id) находит строки чата, но затем должен прочитать и отсортировать все сообщения чата. На огромном чате это 6 000–60 000 строк, в 280–480 раз медленнее, чем A. На маленьком чате B почти не хуже A, то есть проблема видна только при неравномерных данных.
    • C (created_at, id) хорош только для огромного чата: его сообщения составляют 37 % таблицы и быстро встречаются при обходе по времени. Для среднего и маленького чата приходится просматривать тысячи чужих сообщений (5 750 буферов), а для маленького планировщик вообще уходит в Seq Scan (24,9 мс).
    • OFFSET дорог при любом индексе: 54 000 строк всё равно нужно пропустить, и планировщик выбирает Seq Scan + Sort (≈100 мс, ≈12 000 буферов). Поэтому в API используется keyset.
  2. Гипотеза 2 подтвердилась частично. Индекс A стоит 9 MB (≈10 % от heap) и +42–60 % WAL на строку по сравнению с D (364 против 257 Б и 363 против 227 Б). Время вставки на этом объёме различается в пределах шума (±10 %, B оказался медленнее D). Больше времени уходит на FK-проверки, генерацию UUID и сам heap, а 3 повтора не позволяют различить разницу в несколько процентов. Объём WAL — более надёжная метрика: он влияет на репликацию, архивирование и размер бэкапов PITR.
  3. Гипотеза 3 подтвердилась. Восстановление в новое хранилище совпало по всем контрольным суммам, RTO ≈8 с. Сообщение, подтверждённое (COMMIT) после дампа, потеряно: при бэкапе pg_dump раз в N часов теряется до N часов подтверждённых сообщений. Чтобы сократить RPO до секунд, нужен непрерывный архив WAL (archive_mode / pg_basebackup + PITR) или реплика.

Ограничения исследования

  • Один хост, тёплый кэш: все данные помещались в shared_buffers. На холодном диске разница между A и Seq Scan будет ещё больше, но это не измерялось.
  • Время записи меряется с шумом Docker Desktop (WSL2). Для достоверной разницы в единицы процентов нужно больше повторов и изолированный стенд.
  • created_at синтетический (равномерный внутри чата + до 1 минуты разброса). Реальная переписка неравномернее по времени.
  • RTO измерен на 160 000 сообщений (дамп 9 MB). Время pg_restore растёт примерно линейно с объёмом данных плюс пересборка индексов. Для гигабайтов нужен pg_restore -j или физический бэкап.
  • Дамп не шифруется и лежит рядом с проектом (backups/ в .gitignore). В реальной системе его нужно хранить отдельно от хоста БД.

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

  • Один экземпляр PostgreSQL на одном хосте: отказ хоста или диска не переживается. Логический бэкап pg_dump и восстановление проверены в треке 2, но автоматического расписания бэкапов и PITR нет.
  • Если Redis «зависнет», но сохранит данные (сетевой разрыв, а не остановка), logout в этот момент не запишет надгробие. Устаревшая положительная запись кэша тогда проживёт не дольше SESSION_CACHE_MAX_TTL = 60 с. При остановке или рестарте Redis (без persistence) такой проблемы нет.
  • Первый запрос после внезапной остановки Redis ждёт ≈4 с, пока резолвится имя redis (это не покрывает socket_connect_timeout). Дальше фоновый PING отключает кэш.
  • created_at назначает now() PostgreSQL (время начала транзакции). При конкурентных вставках сообщение с меньшим created_at может закоммититься позже чтения страницы и не попасть в уже пройденный курсор. Повторов при обходе неизменной истории нет.
  • Rate limiting, 413/415 не реализованы: они не обязательны для lab2.
  • Порт PostgreSQL проброшен только на 127.0.0.1 (для EXPLAIN-скрипта). Пароль БД передаётся переменной окружения из .env; docker secrets — задача lab7.