TypeScript/Node API на PostgreSQL с сессиями в Valkey (AOF), миграции, compose-стенд, restart hook, тесты уровня 4 и эксперимент трека 2 (планы запроса на 240k сообщений, стоимость записи, backup/restore).
20 KiB
Отчёт — лабораторная 2
- Автор, группа: Морару С.С., БПИ2303
- Целевая оценка: 5, трек 5 — Трек 2. План запроса и восстановление
- Commit/PR: TODO после публикации
- Источники, библиотеки, ИИ: Node.js 24, TypeScript 5.9,
pg8.23 (node-postgres),ioredis5.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 — согласованный снимок на момент старта.
Выводы.
- Гипотеза о чтении подтверждена: V3 читает 51 строку и ~11 буферов независимо от размера чата (60 000 vs 64) и глубины страницы; V1 читает весь чат (60 000 строк, ~25 мс), V0 — всю таблицу. V2 почти так же быстр на этих данных, но только потому, что дубли
created_atредки: при совпадении миллисекунд ему нужна Incremental Sort, а row comparison не становится условием индекса — V3 надёжнее. Переписывание сcreated_at >=V2 не помогло существенно, V3 его не требует. OFFSETдаже с V3 читаетoffset+limitстрок (30 051, 15 мс) — поэтому API использует keyset cursor.- Запись: с fsync на каждом коммите pgbench показывает падение TPS на ~25 % для V3 относительно V0 (2237 → 1659); bulk-вставка в одной транзакции разницы не показала (разброс прогонов больше эффекта — первый вариант пришёлся на «холодный» кэш после генерации). Гипотеза «индекс почти бесплатен» подтверждена лишь частично: цена есть, но на порядок меньше выигрыша чтения.
- 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).