Files
mtusi2026lab2/REPORT.md
T
celis cac37bddec ЛР 2 — БПИ2303 — Морару — на 5 (трек 2)
TypeScript/Node API на PostgreSQL с сессиями в Valkey (AOF), миграции,
compose-стенд, restart hook, тесты уровня 4 и эксперимент трека 2
(планы запроса на 240k сообщений, стоимость записи, backup/restore).
2026-10-29 20:58:56 +03:00

20 KiB
Raw Blame History

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

  • Автор, группа: Морару С.С., БПИ2303
  • Целевая оценка: 5, трек 5 — Трек 2. План запроса и восстановление
  • Commit/PR: TODO после публикации
  • Источники, библиотеки, ИИ: Node.js 24, TypeScript 5.9, pg 8.23 (node-postgres), ioredis 5.11; документация PostgreSQL (EXPLAIN, pg_dump), Valkey persistence, RFC 7617. Код и эксперимент подготовлены с помощью ИИ-ассистента (Claude), проверены прогоном всех тестов ниже; решение объясняю и меняю сам.

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

Требования: Docker Engine + Compose v2 (проверено Docker 29.8 / Compose 5.5 на OrbStack, Apple M3 Pro, VM 11 CPU / 9 GiB), Python 3.9+ для тестов. Node.js локально не нужен: сборка TypeScript идёт в Dockerfile.

Образы (закреплены): node:24.11.1-alpine3.22 (build + runtime), postgres:17.6-alpine3.22, valkey/valkey:8.1.4-alpine3.22.

./scripts/init-secrets.sh                  # случайные пароли в ./secrets (git-ignored), значения не печатаются
docker compose up -d --build --wait        # postgres, valkey -> migrate (one-shot) -> api; --wait ждёт healthcheck /health/ready
make test BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
python3 student-tests/test_lab2.py --base-url http://127.0.0.1:8080   # уровень 4 (останавливает/запускает valkey и postgres)
python3 experiments/track2/run.py                                     # трек 2, ~5 мин, результаты в evidence/track2/
docker compose stop                        # безопасная остановка, данные остаются в volumes
docker compose down -v                     # НАМЕРЕННОЕ удаление всех учебных данных

.env не обязателен: compose имеет значения по умолчанию (SESSION_TTL_SECONDS=3600, APP_PORT=8080). API публикуется только на 127.0.0.1:8080. На моей машине IPv6 *:8080 занят посторонним процессом, поэтому localhost попадал не туда — тесты запускаются с BASE_URL=http://127.0.0.1:8080; на чистой машине подходит и значение по умолчанию.

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

клиент ──HTTP──> api (Node, node:http, 1 процесс) ──pool ≤8, timeouts──> postgres (volume pgdata)  — источник истины
                                                   └──ioredis, 1 s timeout──> valkey (volume valkeydata, AOF) — сессии
migrate (тот же образ, one-shot) ──> postgres
Роль Service Health/readiness Volume Порт Credentials
API api (api_short_ttl в profile ttl для теста expiry, порт 8081) /health/ready = SELECT 1 + PING — 127.0.0.1:8080 secrets database_url, cache_url
БД postgres pg_isready pgdata не публикуется secret postgres_password (POSTGRES_PASSWORD_FILE)
Сессии valkey valkey-cli ping с паролем valkeydata не публикуется requirepass из secret valkey_auth.conf (include в infra/valkey.conf)
Миграции migrate exit 0 — — secret database_url

Что перенесено из lab1 / что изменено. Тот же REST-контракт (пользователи, чаты, сообщения, keyset-пагинация, формат ошибок, X-Request-Id). Изменено: in-memory → PostgreSQL; регистрация требует password (scrypt); POST /auth/sessions по Basic выдаёт opaque Bearer-токен; X-User-Id игнорируется.

Схема (migrations/001_init.sql): users (UNIQUE username + CHECK формата), chats, chat_members (PK (chat_id,user_id), FK на оба), messages с составным FK (chat_id, sender_id) → chat_members — БД сама гарантирует, что отправитель — участник. Индексы: chat_members(user_id, chat_id) для списка чатов, messages(chat_id, created_at, id) для истории (обоснование — трек 2). created_at timestamptz(3): миллисекунды точно проходят через JS Date и cursor; порядок (created_at, id), время назначает часы БД (now()), одни для всех реплик.

Миграции — src/migrate.ts: таблица schema_migrations, pg_advisory_lock против параллельного запуска, каждый файл в своей транзакции (DDL в PostgreSQL транзакционен). Повторный запуск: skip 001_init (evidence/check_and_migrations.txt). Seed-данных нет.

Транзакционные границы. Создание чата = одна транзакция INSERT chats + INSERT chat_members SELECT unnest(...); неизвестный участник → FK violation → ROLLBACK → 400. Отправка сообщения — один INSERT; FK violation → 404 (нет чата или не участник, без раскрытия). Гонка регистрации решается UNIQUE-ограничением (23505 → 409). Все запросы параметризованы ($1..$n).

Сессии (роль Valkey). Valkey — единственное хранилище сессий и их источник истины. Ключ session:<sha256(token)> (в Valkey нет пригодного токена; токен 256 бит, поэтому быстрого хэша достаточно — в отличие от пароля, где нужен медленный KDF). Значение {uid, exp}, SET ... PXAT exp — абсолютный срок: рестарт не продлевает TTL. Expiry — TTL ключа + проверка exp в приложении. Инвалидация — DEL при logout (0 удалённых → 401, поэтому двойной logout = 401). Persistence: appendonly yes, appendfsync always — 201 на вход означает, что сессия на диске; поэтому сессии переживают рестарт Valkey.

Отказы. pg Pool max=8, connectionTimeoutMillis=2000, statement_timeout=3000, query_timeout=4000; ioredis commandTimeout=1000, без offline-очереди. Потеря соединения/таймаут → 503 unavailable за ≤2 с; ошибка ограничений → свой код; прочее → 500 internal_error без деталей. Valkey недоступен → защищённые endpoint 503 (запрос не становится анонимным/доверенным), регистрация работает. PostgreSQL недоступен → 503 всё, кроме liveness. Критичные для /health/ready зависимости: PostgreSQL и Valkey.

Пароли: crypto.scrypt N=2^14, r=8, p=1, соль 16 байт, timingSafeEqual; для неизвестного username считается тот же KDF по фиктивному хэшу — одинаковый 401 и сопоставимое время.

Переменные .env.example → реальная конфигурация: APP_HOST/APP_PORT — то же имя; SESSION_TTL_SECONDS — то же; DATABASE_URL_FILE/CACHE_URL_FILE — то же (/run/secrets/...); SESSION_STORE не используется — сессии всегда в Valkey; APP_ENV не используется. Дополнительно DB_POOL_MAX, DB_POOL_TIMEOUT_MS.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS lab2 evidence/smoke.txt
Структура/контракт make check PASS evidence/check_and_migrations.txt
Данные и сессии переживают рестарт API+PG+Valkey make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt всех трёх контейнеров изменился, volumes те же evidence/persistence.txt
PK/FK/UNIQUE, миграции с нуля и повторно docker compose run --rm migrate skip 001_init, без дублей evidence/check_and_migrations.txt
Атомарное создание чата / rollback test_chat_rollback 400, ни строки в chats/chat_members evidence/level4.txt
Basic только на /auth/sessions, Bearer, X-User-Id не даёт доступ, KDF smoke + test_wrong_password_and_logout 401 с правильным WWW-Authenticate evidence/smoke.txt, evidence/level4.txt
Secrets/volumes не в Git git check-ignore secrets/, .env, backups/, dist/ игнорируются evidence/check_and_migrations.txt
Valkey с ролью, TTL, persistence persistence-тест + test_valkey_outage сессия жива после рестарта Valkey (AOF) evidence/persistence.txt, evidence/level4.txt
Гонка регистрации test_registration_race 20 параллельных → 1×201, 19×409, 1 строка evidence/level4.txt
Ограниченный pool 32 клиента tests/load.py максимум 8 соединений API в pg_stat_activity evidence/pool.txt, evidence/load.json
Индекс истории + EXPLAIN на ≥10k, keyset без full scan experiments/track2/run.py 51 строка/11 буферов на странице чата 60k сообщений evidence/track2/results.md, explain_api_middle_page_V3.txt
Expiry при коротком TTL test_expiry (api_short_ttl, TTL=2) 200 → через 3 с 401 на обоих API evidence/level4.txt
Logout, неверный пароль test_wrong_password_and_logout 204, затем 401 ×2; неверный пароль/пользователь — одинаковый 401 evidence/level4.txt
Недоступность Valkey / PostgreSQL test_valkey_outage, test_postgres_outage 503 unavailable за 0.02 с / 2.01 с, аноним 401, восстановление с тем же токеном evidence/level4.txt
Трек 2 experiments/track2/run.py см. ниже evidence/track2/

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

Гипотеза. Для keyset-страницы истории нужен индекс (chat_id, created_at, id): цена страницы ≈ limit строк и не зависит ни от размера чата, ни от глубины страницы; индекс только по chat_id читает весь чат и сортирует, OFFSET растёт с глубиной. Дополнительный индекс заметно не ухудшает запись (её цена определяется fsync коммита). Логический dump восстанавливается в новое хранилище без расхождений; потеря данных ограничена моментом начала dump.

Методика (experiments/track2/run.py, generate.sql, seed фиксирован). 239 717 сообщений: 300 синтетических чатов с размерами round(60000/k^1.2) (60 000 … 64, медиана 146, 10 крупнейших — 62 %), случайный физический порядок за 90 дней, 1000 пользователей без возможности входа. Варианты индекса: V0 только PK, V1 (chat_id), V2 (chat_id, created_at), V3 (chat_id, created_at, id) (индекс миграции, создаётся последним — БД заканчивает в состоянии миграции). Запросы: первая страница и середина чата запросом API (row comparison), тот же с дополнительным created_at >= $ts, и OFFSET; чаты large/medium/small. Каждый запрос — 5 × EXPLAIN (ANALYZE, BUFFERS), медиана. Запись: 3 × bulk INSERT 50k строк в одной транзакции и 3 × pgbench 10 с, 8 клиентов, 1-row INSERT (коммит на каждую строку), после каждого прогона DELETE + VACUUM. Окружение: PostgreSQL 17.6, shared_buffers 128 MB, synchronous_commit on, OrbStack VM 11 CPU / 9 GiB, без CPU-лимитов, прогрев — повторы (горячий кэш).

Результаты чтения (медиана мс / буферы / прочитанные строки, полная таблица — evidence/track2/results.md):

запрос / чат V0 PK V1 chat_id V2 chat_id,created_at V3 chat_id,created_at,id
середина, keyset API / large 60k 25.2 / 9030 / 239 718 24.6 / 9055 / 60 000 0.19 / 21 / 53 0.26 / 11 / 51
середина, keyset API / small 64 21.3 / 9030 / 239 715 0.64 / 72 / 64 0.37 / 44 / 32 0.49 / 35 / 31
середина, OFFSET / large 81.4 / 9088 42.2 / 9055 80.2 / 9088 15.3 / 6145 / 30 051

Планы запроса API для large: V0 Sort > Seq Scan, V1 Sort > Bitmap Heap Scan, V2 Incremental Sort > Index Scan, V3 Limit > Index Scan messages_chat_created_id_idx с Index Cond: chat_id = … AND ROW(created_at, id) > ROW(…) — без сортировки и без полного сканирования истории.

Стоимость записи:

вариант размер индекса bulk 50k, мс pgbench TPS latency, мс
V0 PK — 2158 2237 3.58
V1 1.7 MiB 1174 1820 4.40
V2 9.3 MiB 1748 1338 5.98
V3 13.5 MiB 1062 1659 4.82

Backup → restore → сверка. pg_dump -Fc 3.37 с, 16.1 MB; восстановление в новый контейнер с новым volume без сети: pg_restore -j1 3.76 с, -j4 4.01 с. Отпечатки (count + md5 по всем строкам каждой таблицы, 20 выбранных сообщений) совпали; страница API крупнейшего чата на обеих БД идентична; на восстановленной БД план тот же (Index Scan messages_chat_created_id_idx). Во время dump параллельный писатель закоммитил 13 сообщений — в восстановленной БД из них 1 (закоммиченное до снимка): dump — согласованный снимок на момент старта.

Выводы.

  1. Гипотеза о чтении подтверждена: V3 читает 51 строку и ~11 буферов независимо от размера чата (60 000 vs 64) и глубины страницы; V1 читает весь чат (60 000 строк, ~25 мс), V0 — всю таблицу. V2 почти так же быстр на этих данных, но только потому, что дубли created_at редки: при совпадении миллисекунд ему нужна Incremental Sort, а row comparison не становится условием индекса — V3 надёжнее. Переписывание с created_at >= V2 не помогло существенно, V3 его не требует.
  2. OFFSET даже с V3 читает offset+limit строк (30 051, 15 мс) — поэтому API использует keyset cursor.
  3. Запись: с fsync на каждом коммите pgbench показывает падение TPS на ~25 % для V3 относительно V0 (2237 → 1659); bulk-вставка в одной транзакции разницы не показала (разброс прогонов больше эффекта — первый вариант пришёлся на «холодный» кэш после генерации). Гипотеза «индекс почти бесплатен» подтверждена лишь частично: цена есть, но на порядок меньше выигрыша чтения.
  4. RTO на этом объёме ≈ 4 с восстановления + старт контейнера; -j4 не ускорил (мало таблиц, восстановление ограничено одним крупным индексом/таблицей). RPO логического dump = время с начала последнего dump; всё, что закоммичено после снимка, теряется. Для меньшего RPO нужен pg_basebackup + архив WAL (PITR) — не реализовано. Сессии в dump не входят (Valkey AOF — отдельная резервная копия); при восстановлении PG с тем же содержимым действующие токены продолжают работать, так как ссылаются на те же UUID пользователей.

Ограничения измерения. Один хост, виртуализированный fsync OrbStack — абсолютные TPS не переносимы. Горячий кэш (данные 74 MB < RAM), холодное чтение не измерялось. 5/3 повтора, медианы; разброс записи заметен. Данные синтетические, вставлены SQL-ом в обход API.

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
scripts/restart.sh: stop+start api, postgres, valkey данные и токен сохранены PASS persistence ~5 с, потерь нет
stop valkey 503 на защищённых, регистрация работает 503 за 0.02 с, POST /users 201 после start тот же токен работает
stop postgres 503 за ограниченное время 503 за 2.01 с после start восстановление, токен жив
пишущий клиент во время pg_dump записи после снимка не в backup 13 записано, 1 в restore потеря = записи после старта dump

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

  • Один API-процесс и одна БД/Valkey на одном Docker-хосте: потеря хоста или volume не переживается. HA и балансировка — lab3.
  • appendfsync always замедляет вход (каждая сессия — fsync); при everysec можно потерять до 1 с выданных сессий.
  • HTTP без TLS — только локальный стенд с синтетическими данными. Argon2id и TLS — lab7.
  • Нет CI-job для сборки стенда и make test; проверки запускаются локально командами выше.
  • Нет rate limiting на вход (перебор паролей ограничен только стоимостью scrypt).