Files
mtusi2026lab2/REPORT.md
T
Sh1pYe 41e8d67a1a
Application (lab2) / app (pull_request) Failing after 36s
Skeleton contracts / contracts (pull_request) Failing after 29s
Lab2- оценка 5
2026-10-08 14:14:20 +03:00

23 KiB
Raw Blame History

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

  • Автор, группа: Кораблев Петр, БВТ2304
  • Целевая оценка: 5
  • Выбранный трек 5: трек 2 — план запроса и восстановление
  • Commit/PR: solution/BVT2304-korablev
  • Использованные библиотеки: pgx/v5 (pgxpool) — PostgreSQL, go-redis/v9 — Valkey, golang.org/x/crypto/argon2 — хеширование паролей, google/uuid; логирование — стандартный log/slog.
  • Помощь ИИ использовалась для создания отчета.

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

Требования: Docker 26+ с Compose v2, Python 3.9+ (тесты и генерация секретов), make — по желанию. Go локально не нужен: приложение собирается в Docker (golang:1.23.4-alpine3.21 → alpine:3.21.2, non-root). Версии образов зафиксированы: postgres:17.2-alpine3.21, valkey/valkey:8.0.2-alpine3.21.

make secrets   # python scripts/init_secrets.py — secrets/* со случайными паролями и .env из .env.example
make up        # docker compose up -d --build --wait api

Порядок старта: postgres → migrate (одноразовый bootstrap: версионируемые миграции, advisory lock, повторный запуск безопасен) → valkey → api. API слушает только 127.0.0.1:8080; порты PostgreSQL и Valkey наружу не публикуются.

Проверки:

make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-student   # собственные тесты уровня 4; останавливают и запускают postgres/valkey
make track2         # эксперимент трека 2 (--repeat 21) в отдельных контейнерах профиля research

Без make — те же команды через python: scripts/check_contract.py, tests/smoke.py, tests/resilience.py --mode persistence --action-script scripts/restart.sh, student-tests/run_tests.py, scripts/track2/run_track2.py.

На Windows Python не умеет запускать .sh через subprocess, поэтому рядом лежит scripts/restart.cmd с теми же командами Compose; на машине автора тест сохранности запускался с ним, а сам restart.sh проверен из Git Bash (rc=0).

Безопасная остановка: make down (docker compose stop) — данные остаются в volume mtusi-lab2_pgdata. Намеренное удаление всех учебных данных:

docker compose --profile ttl --profile research down -v

Секреты (secrets/, .env) создаются локально, исключены из Git и из Docker build context и передаются контейнерам как Compose secrets (/run/secrets/...). Приложение читает DATABASE_URL_FILE / CACHE_URL_FILE и не логирует их значения.

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

Клиент → HTTP (net/http) → обработчики → Store на PostgreSQL (pgxpool, не более 10 соединений). Сессии: PostgreSQL как источник истины, Valkey как кэш перед ним. Из lab1 перенесены HTTP-слой, формат ошибок, request-id, валидация, keyset-курсоры (created_at, id) и graceful shutdown. In-memory Store заменён на PostgreSQL с теми же операциями, X-User-Id — на Bearer-сессии.

Схема (src/internal/db/migrations/0001_init.sql): users (UNIQUE username, CHECK формата), chats, chat_members (PK (chat_id, user_id), position хранит порядок member_ids), messages, sessions. В messages стоит составной FK (chat_id, sender_id) → chat_members: база сама гарантирует, что автор сообщения — участник чата. История читается по индексу (chat_id, created_at, id). Время назначает PostgreSQL с точностью до миллисекунд, так что все реплики используют одни часы.

Создание чата атомарно: INSERT chats и INSERT chat_members идут в одной транзакции. Неизвестный участник нарушает FK, транзакция откатывается целиком, клиент получает 400. Гонку регистрации одинакового username решает UNIQUE (23505 → 409), а не связка «SELECT, потом INSERT». Все SQL параметризованы ($1…). У пула есть ConnectTimeout 3 с; на сервере заданы statement_timeout 5 с, lock_timeout 2 с и idle_in_transaction_session_timeout 10 с. Каждый HTTP-запрос ограничен контекстом в 8 с.

Пароли хешируются Argon2id (m=19 MiB, t=2, p=1, соль 16 байт). Одновременно считается не больше 4 хешей, чтобы ограничить память. Для неизвестного username считается dummy-hash, поэтому ответ — тот же 401 за сопоставимое время. Токен состоит из 32 случайных байт (256 бит) в base64url. В БД и в ключах Valkey хранится только его SHA-256. Быстрый хеш здесь уместен: перебирать 256 бит бессмысленно, а у пароля энтропия низкая, поэтому для него нужен медленный KDF. expires_at = момент входа + SESSION_TTL_SECONDS; ни запросы, ни рестарт этот срок не продлевают.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab2 public API scenario evidence/smoke.txt
Контракт и структура make check PASS evidence/check.txt
Полная валидация OpenAPI make validate (venv с requirements-dev.txt) PASS: full OpenAPI 3.1 and JSON Schema validation evidence/validate.txt
gofmt, vet, build gofmt -l, go vet ./..., go build ./... PASS evidence/quality.txt
Docker build/run/health make up, curl /health/* 3 сервиса healthy, образ 7.5 MB, user=app evidence/docker.txt
Рестарт API и всех хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt у api/postgres/valkey до и после разный, volume тот же evidence/persistence.txt
Миграции с нуля и повторно docker compose run --rm migrate migrations up to date, в schema_migrations одна строка evidence/migrations.txt
Durability COMMIT SHOW на работающем стенде fsync=on, synchronous_commit=on, full_page_writes=on evidence/durability.txt
Basic только на /auth/sessions, X-User-Id не даёт доступа smoke + student-tests Basic на /users/me → 401; X-User-Id без Bearer → 401 evidence/smoke.txt
Пароль — KDF, токен не хранится student-test $argon2id$v=19$m=19456,t=2,p=1$…; сырого токена в БД нет evidence/student-tests.txt
Expiry при коротком TTL student-test, api-short-ttl с TTL=2 через 2.5 с 401 и на :8081, и на основном API (кэш не продлил) evidence/student-tests.txt
Logout и неверный пароль student-tests 204 → 401 → 401; неверный пароль и неизвестный пользователь получают одинаковый 401 за 37–47 мс evidence/student-tests.txt
Гонка регистрации 20 потоков с барьером 1×201, 19×409, в БД одна строка evidence/student-tests.txt
Rollback создания чата неизвестный member 400; строки чата нет, xact_rollback вырос evidence/student-tests.txt
Отказ Valkey / PostgreSQL docker compose stop valkey / postgres см. раздел «Деградация» evidence/student-tests.txt
Ограниченный пул tests/load.py --concurrency 32 + pg_stat_activity 10 соединений при 32 клиентах; 1110 RPS, 0 ошибок evidence/load-32.json
Публичная нагрузка python tests/load.py --duration 30 --concurrency 4 11 007 POST за 30 с, 366 RPS, 0 ошибок, p50/p95/p99 = 5.5/28.8/31.7 мс evidence/load.json
EXPLAIN на ≥10 000 сообщений трек 2, 110 025 сообщений Index Scan using messages_chat_history_idx, 0.11 мс в одиночном прогоне (медиана 0.044 мс) evidence/track2/explain_production_deep_keyset.txt
Трек 2 make track2 (--repeat 21) сравнение 4 индексов и 2 видов пагинации; backup → restore → сверка evidence/track2/results.json

Кэш Valkey (оценка 4)

Источник истины и роль Valkey

PostgreSQL — источник истины для пользователей, чатов, членства, сообщений и сессий. Valkey 8.0 — вспомогательный кэш сессий (cache-aside). Resolve сначала читает sess:<sha256(token)> из Valkey. При промахе или ошибке он идёт в PostgreSQL (sessions JOIN users WHERE revoked_at IS NULL AND expires_at > now()) и заполняет кэш на min(остаток TTL сессии, SESSION_CACHE_MAX_TTL_SECONDS). В записи кэша хранится expires_at, и приложение проверяет его даже при попадании, поэтому кэш никогда не продлевает сессию.

Реализация: internal/auth/sessions.go (логика) и internal/cache/valkey.go (клиент).

Конфигурация и отключение

  • SESSION_STORE=postgres — Valkey не подключается, сессии читаются только из PostgreSQL; SESSION_STORE=valkey (по умолчанию в compose) — PostgreSQL + кэш.
  • SESSION_CACHE_MAX_TTL_SECONDS (по умолчанию 60) — максимальный TTL записи в кэше; ограничивает окно устаревания при сбое eviction во время logout.
  • SESSION_TTL_SECONDS (3600) — срок жизни самой сессии; DB_MAX_CONNS (10) — размер пула.
  • Persistence Valkey выключена (save "", appendonly no, infra/valkey/valkey.conf). Valkey не единственное хранилище сессий, поэтому после restart или FLUSHALL кэш просто пуст, а сессии читаются из PostgreSQL. Проверено тестом: после FLUSHALL токен работает, кэш заполняется снова.
  • maxmemory 64mb, volatile-ttl; пароль Valkey передаётся через Docker secret.

Инвалидация

Logout выполняет три шага: DEL в Valkey → UPDATE sessions SET revoked_at → повторный DEL. Второй DEL закрывает гонку с параллельным Resolve, который мог заново положить запись между первым DEL и COMMIT. Если Valkey недоступен, logout отвечает 503 ещё до изменения БД, иначе отозванный токен мог бы остаться в кэше. Худший случай — Valkey упал между COMMIT и вторым DEL — ограничен TTL записи, то есть не больше 60 с.

Деградация при потере зависимостей

  • Valkey недоступен. Resolve читает из PostgreSQL, и запрос обслуживается. Таймауты клиента 0.3–0.5 с, повторов нет. Circuit breaker на 2 с: после первой ошибки следующие запросы сразу идут в БД, не дожидаясь таймаута. В тесте 8 запросов в режиме деградации заняли около 1.2 с суммарно. Readiness остаётся 200, регистрация, вход и отправка сообщений работают, logout возвращает 503. После start valkey logout снова отвечает 204.
  • PostgreSQL недоступен. /health/live 200, /health/ready 503, бизнес-запросы 503. Без токена — 401. Неизвестный токен получает 503, а не 200: проверить его нельзя, доверять тоже. После start postgres данные на месте.
  • GET /health/ready проверяет только PostgreSQL; Valkey некритичен.
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Рестарт API + PostgreSQL + Valkey (volumes сохранены) данные и действующая сессия сохраняются PASS публичного теста, тот же токен, история без дублей ~6.6 с на сценарий, потерь нет
stop valkey обход кэша, logout отказывает безопасно 2xx на чтение и запись, logout 503 сразу после start, потерь нет
FLUSHALL никто не разлогинен токен работает, кэш перезаполнен мгновенно
stop postgres ready 503, бизнес 503, анонимы не проходят так и есть 2–5 с после start, подтверждённые данные целы

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

Гипотеза. Для запроса истории WHERE chat_id=$1 AND (created_at,id) > cursor ORDER BY created_at, id LIMIT 51 составной индекс (chat_id, created_at, id) даёт постоянную стоимость для любого чата и любой глубины. Короткие индексы хороши только на части распределения размеров чатов. OFFSET-пагинация деградирует линейно при любом индексе.

Методика. scripts/track2/run_track2.py работает в отдельном контейнере pg-research со свежим volume; рабочая БД стенда не затрагивается. Схема берётся из того же файла миграции, что использует приложение.

  • Данные. Детерминированный сид scripts/track2/seed.sql (setseed, md5-UUID): 110 025 сообщений в 2 021 чате.
    • Один чат на 60 000 сообщений — 55 % всех данных.
    • 20 чатов по 1 500 сообщений и 2 000 чатов по 1–19 (медиана 10).
    • Средний текст — 421 символ, таблица — 64.7 MB.
  • Перебор индексов. Вторичные индексы messages пересоздаются в 4 вариантах, после каждого — ANALYZE.
  • Чтение. Пять запросов, каждый через EXPLAIN (ANALYZE, BUFFERS) 21 раз (--repeat 21). Первый прогон — прогрев, в таблицу идёт медиана остальных 20.
  • Запись. BEGIN; EXPLAIN (ANALYZE, WAL) INSERT 20 000; ROLLBACK, 10 прогонов, медиана 9.
  • Окружение. PostgreSQL 17.2 с настройками по умолчанию, Docker Desktop: 22 vCPU, 15.4 GiB.

Чтение (медиана, мс / буферы):

Индекс big: 1-я стр. big: keyset после 55 000 big: OFFSET 55 000 medium (1 500) small (≈10)
только PK 11.87 / 6826 9.50 / 6768 48.70 / 6826 9.69 / 6738 9.67 / 6738
(chat_id) 13.73 / 9900 9.32 / 3733 50.23 / 9900 0.42 / 129 0.042 / 5
(created_at, id) 0.045 / 29 0.064 / 70 51.12 / 12977 0.37 / 1336 17.53 / 12889
(chat_id, created_at, id) 0.041 / 8 0.044 / 9 54.47 / 16054 0.046 / 9 0.036 / 6

Запись (INSERT 20 000 строк в большой чат):

Индекс Время, мс WAL, MB Размер индекса, MB
только PK 421 4.32 0
(chat_id) 483 5.71 0.82
(created_at, id) 498 5.95 4.27
(chat_id, created_at, id) 503 6.27 6.20

Выводы.

  • Production-индекс — единственный вариант, где все сценарии укладываются меньше чем в 0.05 мс и ≤ 10 буферов. Глубина страницы почти не влияет: 0.041 мс на первой странице и 0.044 мс после 55 000 сообщений. План — Limit -> Index Scan using messages_chat_history_idx, без Sort.
  • Неравномерность размеров ломает короткие индексы.
    • (chat_id) хорош для маленьких чатов, но на большом даёт Bitmap Scan + Sort — примерно в 200 раз медленнее.
    • (created_at, id) — наоборот: для чата из 10 сообщений планировщик уходит в Seq Scan (17.5 мс, 12 889 буферов).
    • На средних значениях этого не видно.
  • OFFSET не спасает ни один индекс. Пропущенные 55 000 строк всё равно читаются, и keyset больше чем в 1000 раз быстрее (0.044 против 54.47 мс). Поэтому API использует курсор (created_at, id).
  • Цена записи. Устойчиво измеряется объёмом WAL и размером индекса: составной индекс даёт +46 % WAL на вставку (6.27 против 4.32 MB на 20 000 строк) и весит 6.2 MB, около 10 % размера таблицы. Время пакетной вставки ненадёжно: в последнем прогоне оно росло вместе с числом индексов (421 → 503 мс, +20 %), но в предыдущих прогонах на той же машине порядок вариантов был другим, а абсолютные значения отличались почти вдвое (855–1010 мс). Поэтому разницу во времени я не считаю доказанной. Отдельный индекс (chat_id) становится лишним: составной покрывает его как префикс.

Backup → восстановление в новое хранилище → сверка:

Этап Время, с
pg_dump -Fc (дамп 6.9 MB) 0.85
копирование дампа на хост (backups/, в .gitignore) 0.22
новый контейнер pg-restore с пустым volume, копирование дампа внутрь 0.69
pg_restore -j 4 --exit-on-error (данные, ключи, индексы) 1.03
ANALYZE 0.50
Итого RTO после появления пустого сервера 2.21

Сверка «источник на момент бэкапа» против восстановленной копии — 12 из 12 проверок совпали:

  • количество строк во всех таблицах и schema_migrations;
  • порядконезависимая контрольная сумма всех 110 025 сообщений;
  • md5 счётчиков по каждому чату;
  • md5 полной истории большого, среднего и маленького чата;
  • md5 выборки из 200 сообщений;
  • список индексов.

После восстановления запрос истории снова идёт через messages_chat_history_idx.

Граница потери данных. Сразу после дампа в источник записывается ещё одно сообщение, и в восстановленной копии его нет. pg_dump фиксирует снимок на момент старта, поэтому RPO равен интервалу между бэкапами. Уменьшить его можно только архивацией WAL (PITR) или репликой; в стенде это не реализовано.

Ограничения

  • Logout зависит от Valkey. При недоступном Valkey возвращается 503 — сознательный выбор безопасности.
  • Окно устаревания кэша. Если Valkey упал между COMMIT отзыва и вторым DEL, токен может приниматься до SESSION_CACHE_MAX_TTL_SECONDS (60 с).
  • Кэшируются только сессии. Списки чатов и история всегда читаются из PostgreSQL; кэш истории потребовал бы инвалидации на каждую запись.
  • Измерения трека 2 сделаны на тёплом кэше. Таблица помещается в shared_buffers, замер в одном окружении и без параллельной нагрузки. Холодное чтение увеличит разрыв между Seq Scan и Index Scan.
  • Размер дампа занижен. Синтетический текст из повторов md5 хорошо сжимается: 64.7 MB → 6.9 MB. На реальных текстах дамп и время восстановления будут больше.
  • Бэкап только логический (pg_dump). Нет WAL-архива и расписания бэкапов.
  • Нет rate limiting на POST /auth/sessions. Argon2id замедляет подбор пароля, но не заменяет лимит попыток.
  • HTTP без TLS. Допустимо только для локального изолированного стенда: Basic — это кодирование, а не шифрование.
  • COMMIT гарантирует сохранность только на одном диске. При fsync=on и synchronous_commit=on ответ 201 отправляется после записи WAL на диск volume; в Docker Desktop это виртуальный диск VM.