16 Commits
Author SHA1 Message Date
ilya.tyunin 91de084d7a lab3: доказательства уровня 4 и контроль пробы на финальной сборке, документация 2026-10-16 22:44:22 +03:00
ilya.tyunin 1b4aac7587 lab3: e2e ждёт DOWN слотов, а не любое состояние кроме UP 2026-10-16 22:18:08 +03:00
ilya.tyunin 46d84ab0aa lab3: проба готовности на отдельном соединении, серия роста на блоке why# 2026-10-16 22:09:31 +03:00
ilya.tyunin e42f02c016 lab3: итог 2026-10-16 16:18:15 +03:00
ilya.tyunin 6cced49486 Обновить отметку пересборки в вердикте A/B 2026-10-16 03:01:48 +03:00
ilya.tyunin 8e2d20cf2f Отметить коммиты ветки в отчёте 2026-10-16 03:01:25 +03:00
ilya.tyunin b7cf7b2d3f Дополнить доказательства трека 1 по замечаниям ревью
Измерения (raw-файлы, сводки, отчёт):
- контрольный A/B на бюджете по умолчанию (`abdiag`, 3+3 повтора): A упирается в
  250 req/s и отдаёт 503 `unavailable` (4/894/2813 на 300/350/400), B держит
  398.7 req/s без единого 5xx;
- блок «почему» на одном темпе (900 и 1500 req/s, 2 повтора x 5 конфигураций):
  перераспределение того же бюджета не меняет потолок (820–854 req/s), разделение
  бюджета между репликами поднимает время горячего оператора с 1.56 до 17.3–17.9 ms,
  ожидания `LWLock:WALWrite`/`Lock:transactionid` общие для всех реплик;
- колено текущей сборки (900–2200 req/s, N=1 и N=4): ≈1200 req/s против ≈700 у
  серии A, за коленом одна реплика с полным бюджетом не хуже четырёх;
- пара прогонов HAProxy 0.25 против 1.0 CPU на 1500 req/s: результат одинаков,
  при квоте 1.0 балансировщик использует те же 25 % ядра.

Харнесс `scripts/lab3/lab3.py`:
- `--loadgen-memory` для подкоманды `run` (прогон колена падал на разборе аргументов);
- суффикс вывода A/B для контрольной серии (`summary-ab-abdiag.md`, `ab-verdict-abdiag.json`);
- исправлено затенение `header()` локальной переменной в `cmd_check`, из-за которого
  падала проверка `check spread`;
- сэмплер: классы ответов LB (`hrsp_*`), ожидания сессий PostgreSQL (`wait_event`),
  операторы `idempotency_keys` в дельтах `pg_stat_statements`.

Доказательства и документы: пересняты `evidence/level3/{smoke,persistence}` и
`evidence/level4/{dependency-faults,spread,idempotency-concurrency}`, обновлены
сводки и графики `evidence/track1/*`, `evidence/README.md` (метки и состав сводок),
`REPORT.md` (разбор отказов стороны A, бюджет серии, оговорки о валидности данных,
точные команды воспроизведения, «почему» закрыто измерением).
2026-10-16 03:01:14 +03:00
ilya.tyunin e38795d0a3 lab3: уточнение статуса гипотез в отчёте
H1 подтверждена только в части «рост реплик при фиксированном бюджете не даёт
роста»: удвоение CPU PostgreSQL потолок не поднимает, поэтому ограничитель —
связка «квота CPU на реплику + общий PostgreSQL + сериализация на строке чата»,
а не один PostgreSQL.
2026-10-15 23:26:07 +03:00
ilya.tyunin 1802ca12d4 lab3: доказательство операторского GC журнала идемпотентности
Вставлены просроченная и свежая записи, выполнен npm/CLI-прогон GC внутри
контейнера API: удалена ровно просроченная (expired_left=0), свежая осталась.
Файл evidence/level4/idempotency-gc.txt добавлен в отчёт и индекс доказательств.
2026-10-15 23:25:08 +03:00
ilya.tyunin 06431d824b lab3: доказательства уровня 4 пересняты на финальной сборке
check spread, make test-dependencies, failover каждой реплики под нагрузкой и
rolling update прогнаны заново на сборке с однократным путём записи (C2):
в evidence/level4 обновлены spread.json, dependency-faults.txt, failover-sweep.*,
rolling-update.*; числа в REPORT.md приведены в соответствие (0 ошибок и 0 дублей
в отказе каждой реплики, 0 ответов 5xx из 884 попыток при rolling update).
2026-10-15 23:24:52 +03:00
ilya.tyunin eabb1d2909 lab3: результат проверки из чистого clone и уточнение хешей в отчёте
Проверка воспроизводимости: клон ветки lab3, собственные credentials в .env,
чистые тома (down -v), далее make stand-up (миграции с нуля), make wait-ready,
make test, make test-persistence с scripts/restart.sh и make test-failover с
scripts/stop-one.sh — все PASS (evidence/level3/clean-clone.txt).

В REPORT.md добавлена строка доказательства для этой проверки и подставлены
хеши коммитов C1..C5; в evidence/README.md — описание файла с проверкой.
2026-10-15 23:17:36 +03:00
ilya.tyunin 2950b77967 lab3: evidence, отчёт и документация (C5)
- REPORT.md: запуск из чистого clone, архитектура и решения, таблица доказательств
  по каждому заявленному критерию, методика экспериментов, гипотезы H1–H5,
  результаты серии A (1/2/4 реплики), диагностики горячего чата и пути чтения,
  серии роста ресурсов, A/B улучшения и таблица отказов, ограничения и следующие шаги.
- evidence/: индекс (README.md), level3 (smoke, persistence, failover по каждой
  реплике с переходами статусов LB) и level4 (spread, идемпотентность, failover
  каждой реплики под нагрузкой, rolling update, отказы зависимостей, лимиты и
  порты) плюс raw-данные трека 1: сводки k6, сжатые потоки сэмплера, манифесты
  условий измерения, таблицы и графики.
- app/README.md и infra/README.md: LB и реплики, семантика Idempotency-Key,
  /internal/lb-check, переменные окружения, дрейн по SIGTERM, харнесс.
- .env.example приведён к реальной конфигурации (убраны SESSION_STORE/CACHE_URL_FILE,
  добавлены DATABASE_URL/REDIS_URL/лимиты стенда/BUILD_ID и т.д.);
  .lab3-quiesce.json добавлен в .gitignore.
2026-10-15 23:14:20 +03:00
ilya.tyunin 5a5a8fe5cb lab3: путь записи сообщения одним оператором (C2)
Владелец ключа идемпотентности больше не оркестрируется в приложении: проверка
членства, заявка ключа, вставка сообщения, инкремент версии чата (якорь
инвалидации кэша) и сохранение тела ответа выполняются одним оператором SQL,
атомарность которого обеспечивает сам оператор.

- messages.repository: createOnce() одним запросом вместо трёх (проверка
  членства + INSERT + UPDATE version) и явной транзакции; тело ответа строится
  в SQL и служит источником истины и для первого ответа, и для повторов.
- idempotency.repository: read() читает сохранённый ответ вместе с повторной
  проверкой доступа, delete/purge не изменились; claim/store внутри транзакции
  больше не нужны.
- messages.service: без DatabaseClient и без предварительного chatsService.
  getForUser в пути записи; ключ обязателен, тело проверяется до обращения к БД,
  просроченный ключ освобождается и занимается заново.

Итог: 1 round trip на запись вместо 8 и 2 вместо 3 на повтор; короче удержание
блокировки строки chats, что и проверяется A/B на профиле горячего чата.

Проверено: npm run build, tsc, unit-тесты, lint, публичный smoke и black-box
набор приложения (включая конкурентный повтор с одним ключом) на стенде с
образом mtusi-messenger:lab3-after.
2026-10-15 22:48:22 +03:00
ilya.tyunin 410e1ea3ad lab3: харнесс экспериментов (k6, сэмплер, анализ) и операторские цели Makefile
- scripts/load/common.js + write-ladder.js + write-steady.js: лестница плоских
  полок constant-arrival-rate, пошаговые счётчики/тренды (k6 не создаёт
  подметрики произвольных тегов), подготовка синтетических пользователей и
  чатов, сводка JSON в stdout без файлов из контейнера; MODE=write|read.
- scripts/lab3/lab3.py (stdlib): stand, check (spread/instances/idempotency),
  run, sweep, growth, failover, rolling-update, ab, analyze, quiesce, track1.
  Сэмплер: docker stats (--no-stream, поток склеивает JSON и печатает ANSI),
  HAProxy stats CSV (заголовок помечен '#'), /internal/metrics каждой реплики,
  pg_stat_database/pg_stat_activity/pg_stat_statements, фон хоста. raw:
  <label>.k6.json, <label>.samples.jsonl.gz, <label>.manifest.json.
- Анализ: таблицы по каждому прогону, серия A, диагностика, рост, A/B и
  графики (throughput, latency/errors, VU генератора, CPU контейнеров во
  времени, распределение по слотам LB, рост, A/B с min..max).

Проверено: analyze на пустом каталоге не падает; повторный analyze даёт те же
числа; прогон run --label smoke-p-a (30 s, 100 req/s) — 100.03 достигнутых
req/s, 0 ошибок, 795 сэмплов, графики и таблицы непустые.
2026-10-15 21:25:03 +03:00
ilya.tyunin 917ed1a734 lab3: стенд HAProxy + реплики под compose, лимиты, хуки остановки и квиесценции
- compose.yaml: проект mtusi-lab3, HAProxy как единственная точка входа,
  deploy.replicas ${API_REPLICAS:-2}, CPU/RAM-лимиты на каждый сервис,
  stop_grace_period 20s, лимиты из переменных (API_CPUS_PER_REPLICA и т.д.),
  loopback-порты PostgreSQL/Redis только для операторских проверок; у API
  портов нет; container_name нигде не задан.
- infra/haproxy/haproxy.cfg: проба GET /internal/lb-check, inter 500ms/fall 2
  (~1s обнаружение), server-template + DNS Docker вместо статического списка,
  stats на 127.0.0.1:8404.
- Дрейн: SIGTERM -> реплика сразу перестаёт проходить пробу LB -> пауза
  DRAIN_DELAY_MS -> закрытие сервера и пулов. Nest уничтожает провайдеров
  раньше beforeApplicationShutdown, поэтому последовательность вынесена в
  main.ts, а HealthService отвечает только за флаг not-ready.
- scripts/stop-one.sh (остановка ровно одной реплики по X-Instance-Id),
  scripts/start-replica.sh (восстановление до API_REPLICAS), scripts/quiesce.sh
  (остановка/возврат посторонних контейнеров хоста), restart.sh перезапускает
  и LB, scripts/app-e2e.sh (host-side e2e через loopback-порты).
- Makefile: stand-up/down/status, stand-replica, wait-ready, quiesce-up/down,
  test-e2e, test-failover-all, rolling-update, track1, evidence.
- Dockerfile: ARG/ENV BUILD_ID для доказательства rolling update.

Проверено: make test, make test-e2e, make test-persistence (restart.sh),
make test-failover (stop-one.sh, восстановление через start-replica.sh),
make test-dependencies; docker inspect подтверждает NanoCpus/Memory и
отсутствие опубликованных портов у api.
2026-10-15 21:14:17 +03:00
ilya.tyunin e9cd28d6ba lab3: идентичность реплики, LB-проверка и общая идемпотентность отправки
Этот коммит впервые фиксирует порт lab2 (приложение NestJS+Fastify, Dockerfile,
одноservice-стенд compose, restart hook) и добавляет уровень 3/4 по lab3:

- X-Instance-Id = INSTANCE_ID либо hostname контейнера (стабилен для процесса),
  добавляется и в ответах об ошибках, которые формируются до интерсептора.
- /internal/lb-check: проба LB, намеренно не зависящая от PostgreSQL и Redis
  (отказ общей БД нельзя лечить выводом реплик из ротации); /health/ready
  остаётся операторским сигналом. /internal/metrics отдаёт instance_id и build_id.
- Общая идемпотентность POST сообщения: таблица idempotency_keys, область
  (user, method, path, key), канонический отпечаток тела, заявка+результат в
  одной транзакции, повтор возвращает сохранённый ответ, другое тело — 409,
  отсутствие/неверный ключ — 400, просрочка по IDEMPOTENCY_TTL_SECONDS.
- Транзиентные коды PostgreSQL (57014/40001/40P01) отображаются в 503, чтобы
  прерывание не фиксировалось идемпотентной записью как окончательный результат.
- Миграции 003 (идемпотентность) и 004 (pg_stat_statements для трека 1),
  операторский прогон GC: npm run idempotency:gc.
2026-10-15 21:09:23 +03:00
309 changed files with 34717 additions and 47 deletions
+56 -7
View File
@@ -1,13 +1,62 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
# Полный список переменных, которые читают приложение и стенд; значения-образцы
# не являются секретами. Соответствие «переменная -> фактическая конфигурация»
# описано в REPORT.md.
#
# Приложение (проверяется zod-схемой app/src/config/app-config.schema.ts):
APP_HOST=0.0.0.0
APP_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2
DATABASE_URL=postgresql://messenger:change-me@postgres:5432/messenger
REDIS_URL=redis://redis:6379
DATABASE_POOL_MAX=10
DATABASE_CONNECTION_TIMEOUT_MS=5000
DATABASE_STATEMENT_TIMEOUT_MS=5000
CACHE_TTL_SECONDS=30
CACHE_MODE=protected
CACHE_LOCK_TTL_MS=1000
CACHE_MISS_DELAY_MS=0
# Бюджет проверки зависимостей в /health/ready: LB пробует ту же ручку
# (timeout check 500 ms), поэтому проба обязана уложиться заметно раньше.
HEALTH_TIMEOUT_MS=400
# Токен доступа к /internal/metrics; сгенерируйте свой.
METRICS_TOKEN=change-me
# Дрейн перед выходом по SIGTERM: реплика перестаёт проходить пробу LB,
# ждёт DRAIN_DELAY_MS (длиннее обнаружения отказа ~1 s) и только потом закрывается.
DRAIN_DELAY_MS=3000
# Переопределяет X-Instance-Id; по умолчанию это hostname контейнера
# (= короткий ID контейнера, по нему работает scripts/stop-one.sh).
# INSTANCE_ID=api-1
IDEMPOTENCY_TTL_SECONDS=86400
# Стенд (compose.yaml и scripts/):
# Суммарный бюджет серии трека 1: API_TOTAL_CPUS / API_TOTAL_MEMORY_MB делятся
# на API_REPLICAS, поэтому лимит реплики меняется вместе с их числом.
API_TOTAL_CPUS=3.0
API_TOTAL_MEMORY_MB=1536
API_REPLICAS=2
API_CPUS_PER_REPLICA=1.5
API_MEMORY_PER_REPLICA=768m
PG_CPUS=1.5
PG_MEMORY=512m
REDIS_CPUS=0.25
REDIS_MEMORY=128m
LB_CPUS=0.25
LB_MEMORY=128m
LOADGEN_CPUS=1.5
LOADGEN_MEMORY=256m
# Тег образа API; BUILD_ID отличает сборки при rolling update.
API_IMAGE=mtusi-messenger:lab3
BUILD_ID=local
APP_PUBLIC_PORT=8080
LB_STATS_PORT=8404
# Loopback-порты PostgreSQL/Redis нужны только операторским проверкам с хоста
# (make test-e2e, psql). API-реплики портов не публикуют.
POSTGRES_PUBLISHED_PORT=5432
REDIS_PUBLISHED_PORT=6379
# PostgreSQL (пароль подставьте свой; тот же, что в DATABASE_URL):
POSTGRES_DB=messenger
POSTGRES_USER=messenger
POSTGRES_PASSWORD=change-me
+32 -14
View File
@@ -1,18 +1,36 @@
## Лабораторная 3
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Илья Тюнин; группа — БВТ2303
Целевая оценка (3/4/5): 5
Трек: 1 «Цена масштабирования»
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
Что реализовано и что перенесено: Стенд целиком в `compose.yaml`: HAProxy 3.2 (server-template + Docker DNS, проба готовности `/health/ready` с `timeout check 500ms`, roundrobin), API × N без публикации портов, общие PostgreSQL 16.4 и Redis 7.4 (сессии + AOF), миграции отдельным сервисом `migrate`, лимиты CPU/RAM у всех сервисов, `container_name` не задан нигде. Из lab2 перенесены без изменений: регистрация с Argon2id, Basic→Bearer-сессии в общем Redis, чаты с атомарным созданием, keyset-пагинация `(created_at, id)`, версионированный кэш истории, `/health/live`, `/health/ready`, `/internal/metrics`, `X-Request-Id`. Добавлено в lab3: `X-Instance-Id` = hostname реплики (в успешных ответах и в ошибках), проба LB `/health/ready`: PostgreSQL проверяется по отдельному соединению (занятый пул не делает реплику неготовой), весь ответ ограничен общим дедлайном `HEALTH_TIMEOUT_MS=400`, Redis — обязательная зависимость готовности; общая идемпотентность `POST /chats/{id}/messages` (обязательный `Idempotency-Key`, сквозь реплики, атомарная заявка и тело ответа одним оператором, TTL и фоновый GC), дрейн по SIGTERM до закрытия пулов, транзиентные коды PostgreSQL → `503 unavailable`. Инструменты: `scripts/lab3/lab3.py` (стенд, прогоны, отказы, rolling update, анализ, графики), профили k6 в `scripts/load/`, хуки `scripts/stop-one.sh`, `scripts/start-replica.sh`, `scripts/restart.sh`, `scripts/quiesce.sh`. Трек 1: серия A (1/2/4 реплики при фиксированном бюджете), VU-своп, блок «почему» на 1500 req/s (он же серия роста ресурсов, контроль `why#n4`, точки сопоставлены по манифестам, фактические квоты проверены через `docker inspect`), A/B до/после оптимизации пути записи и контрольная серия на бюджете по умолчанию; доказательства, сводки и графики — в `evidence/track1/`.
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
Команды запуска из чистого clone:
```sh
git clone -b lab3 <origin> lab3 && cd lab3
cp .env.example .env # свои POSTGRES_PASSWORD, DATABASE_URL, METRICS_TOKEN
make stand-up # docker compose up -d --build --wait
make wait-ready && make test && make test-e2e
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && scripts/start-replica.sh
make test-dependencies
# трек 1 (полный список команд — REPORT.md, раздел «Воспроизводимость прогонов трека»):
python3 scripts/lab3/lab3.py track1 --reps 2
python3 scripts/lab3/lab3.py track1-extras --part all --reps 2 --rate 1500 --max-vus 900 --loadgen-memory 1024m --ab-reps 3
python3 scripts/lab3/lab3.py analyze
```
Результаты проверок и ссылка на REPORT.md: `make check` — PASS, `make test` — PASS через LB, `make test-e2e` — 14 passed / 3 skipped, `test-persistence` и `test-failover` — PASS, `test-dependencies` — PASS; доказательства уровня 3/4 — `evidence/level3/`, `evidence/level4/`, трека 1 — `evidence/track1/` (raw + сводки + графики). Полные таблицы, гипотезы, статус гипотез и ограничения — в `REPORT.md`.
Ограничения / известные ошибки: один docker-хост; PostgreSQL, Redis и HAProxy не реплицированы (трек 2 не заявлен), бэкапа тома PostgreSQL нет; путь чтения измерялся с `MAX_VUS=200`, поэтому его потолок — нижняя оценка; абсолютные значения трека сравнимы только внутри серии/блока (разные сборки и растущий датасет); серии трека, где меняются лимиты (серия роста = блок 1500, VU-своп), сняты по одному прогону на точку с проверкой квот через `docker inspect`; серии трека 1 сняты с пробой LB, проверявшей только процесс и флаг дрейна, а контрольный прогон 1500 req/s на финальной сборке показал слоты LB всё время `UP`.
Источники: контракт `contracts/openapi.json` и `contracts/README.md`, публичные проверки `tests/`, документация HAProxy 3.2, Docker Compose, k6 0.54, NestJS/Fastify, `pg` и `redis`. Все числа в отчёте получены прогонами на описанном стенде и лежат в `evidence/`.
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены.
- [x] make check и make test выполнены; приложен реальный вывод.
- [x] Сценарии отказов/безопасности своего уровня воспроизведены.
- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
+1
View File
@@ -30,3 +30,4 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
.lab3-quiesce.json
+38
View File
@@ -0,0 +1,38 @@
FROM node:25.7.0-slim AS build
WORKDIR /usr/src/app
RUN apt-get update \
&& apt-get install -y --no-install-recommends python3 make g++ \
&& rm -rf /var/lib/apt/lists/*
COPY app/package.json app/package-lock.json ./
RUN npm ci
COPY app/ ./
RUN npm run build && npm prune --omit=dev
FROM node:25.7.0-slim AS runtime
WORKDIR /usr/src/app
# BUILD_ID доказывается через GET /internal/metrics и меняется при rolling
# update: он показывает, какая именно сборка отвечает на запрос.
ARG BUILD_ID=unknown
ENV BUILD_ID=$BUILD_ID
ENV NODE_ENV=production
ENV APP_PORT=8080
ENV DRAIN_DELAY_MS=5000
COPY --from=build /usr/src/app/package.json /usr/src/app/package-lock.json ./
COPY --from=build /usr/src/app/node_modules ./node_modules
COPY --from=build /usr/src/app/dist ./dist
USER node
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
CMD node -e "const port=process.env.APP_PORT||'8080'; fetch('http://127.0.0.1:'+port+'/health/ready').then((response) => { if (!response.ok) process.exit(1); }).catch(() => process.exit(1))"
CMD ["node", "dist/main.js"]
+78 -2
View File
@@ -3,15 +3,33 @@ BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
COMPOSE_ENV_FILE ?= .env
COMPOSE = docker compose --env-file $(COMPOSE_ENV_FILE)
LAB3 = $(PYTHON) scripts/lab3/lab3.py
FAILOVER_RUNS ?= 3
RATE ?= 200
TRACK1_ARGS ?=
.PHONY: help check validate test load test-persistence test-failover
.PHONY: help check test-analytics validate test load test-persistence test-failover test-dependencies lab3-before-image \
stand-up stand-down stand-status stand-replica wait-ready quiesce-up quiesce-down \
test-e2e test-failover-all rolling-update track1 evidence
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; test-analytics: offline analytics regression (no stand); validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; test-dependencies: stops/restarts Redis and PostgreSQL"
@echo "stand-up/stand-down/stand-status: HAProxy + API x API_REPLICAS over shared PostgreSQL and Redis"
@echo "stand-replica: restore one missing API replica; wait-ready: wait for /health/ready"
@echo "quiesce-up/quiesce-down: stop and restore unrelated background containers of the host"
@echo "test-e2e: app black-box suite against the stand; test-failover-all: failover for every replica in turn"
@echo "rolling-update: replace replicas one by one under load; track1: full scaling-price series; evidence: rebuild aggregates and graphs"
check:
$(PYTHON) scripts/check_contract.py
# Регрессия аналитики трека 1: успешный RPS отделён от частоты ответов, рост
# сравнивается только внутри одного темпа. Оффлайн: сырые сводки — фикстуры.
test-analytics:
$(PYTHON) -m unittest discover -s tests -p 'test_*.py' -v
validate:
$(PYTHON) scripts/validate_openapi.py
@@ -28,3 +46,61 @@ test-persistence:
test-failover:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2)
$(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
test-dependencies:
cd app && E2E_COMPOSE_DIR="$(CURDIR)" E2E_COMPOSE_ENV_FILE="$(COMPOSE_ENV_FILE)" npm run test:dependencies
stand-up:
$(COMPOSE) up -d --build --wait
stand-down:
$(COMPOSE) down
stand-status:
$(COMPOSE) ps
stand-replica:
scripts/start-replica.sh
wait-ready:
@for attempt in $$(seq 1 60); do \
if curl -fsS "$(BASE_URL)/health/ready" >/dev/null 2>&1; then \
echo "stand is ready ($(BASE_URL))"; exit 0; \
fi; \
sleep 1; \
done; \
echo "stand did not become ready within 60s" >&2; exit 1
quiesce-up:
scripts/quiesce.sh up
quiesce-down:
scripts/quiesce.sh down
test-e2e:
scripts/app-e2e.sh
test-failover-all:
@for run in $$(seq 1 $(FAILOVER_RUNS)); do \
echo "=== failover run $$run of $(FAILOVER_RUNS)"; \
$(MAKE) test-failover ACTION_SCRIPT=scripts/stop-one.sh || exit 1; \
scripts/start-replica.sh; \
$(MAKE) wait-ready; \
done
rolling-update:
$(LAB3) rolling-update --under-load --rate $(RATE)
track1:
$(LAB3) track1 $(TRACK1_ARGS)
# Образ «до» для A/B: дерево коммита C1 (путь записи из 8 обращений) с тем же
# Dockerfile. После сборки: $(LAB3) ab --before mtusi-messenger:lab3-before --after <образ C2>
C1_COMMIT ?= e9cd28d
lab3-before-image:
rm -rf /tmp/lab3-before && mkdir -p /tmp/lab3-before
git archive $(C1_COMMIT) | tar -x -C /tmp/lab3-before
docker build --build-arg BUILD_ID=before -t mtusi-messenger:lab3-before /tmp/lab3-before
evidence:
$(LAB3) analyze
+703 -19
View File
@@ -1,37 +1,721 @@
# Отчёт — лабораторная 3
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- **Автор, группа:** Илья Тюнин; группа — БВТ2303
- **Целевая оценка:** 5 + трек 1 «Цена масштабирования»
- **Commit/PR:** ветка `lab3`; коммиты: `e9cd28d` (идентичность реплики, LB-проверка,
идемпотентность), `917ed1a` (стенд HAProxy + реплики, лимиты, хуки), `410e1ea`
(харнесс экспериментов), `5a5a8fe` (оптимизация пути записи, C2), `2950b77`
(evidence, этот отчёт, документация), `eabb1d2` (проверка из чистого clone),
`06431d8`, `1802ca1`, `e38795d`, `b7cf7b2` (доказательства уровня 4 и серии
трека 1: `abdiag`, блок «почему», колено, LB). PR — после пуша ветки в origin.
- **Источники, библиотеки и помощь ИИ:** контракт `contracts/openapi.json`,
`contracts/README.md`, `tests/README.md`, документация HAProxy 3.2, Docker
Compose, k6 0.54, докуменация NestJS/Fastify/pg/redis. Код и эксперименты
подготовлены с использованием ИИ-ассистента; все числа в отчёте получены
прогонами на описанном стенде и лежат в `evidence/`.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Версии: Docker 29.9.0, Docker Compose v5.6.0, Node.js 25.7.0, Python 3.14 (для
проверок и харнесса; публичные тесты требуют 3.9+), образы `postgres:16.4-alpine`,
`redis:7.4.2-alpine`, `haproxy:3.2-alpine`, `grafana/k6:0.54.0`,
`node:25.7.0-slim` (сборка API). Хост — Fedora, 8 логических CPU, 16 GiB RAM.
```sh
git clone <origin> lab3 && cd lab3
cp .env.example .env
password=$(openssl rand -hex 32)
sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$password/" .env
sed -i "s|^DATABASE_URL=.*|DATABASE_URL=postgresql://messenger:$password@postgres:5432/messenger|" .env
sed -i "s/^METRICS_TOKEN=.*/METRICS_TOKEN=$(openssl rand -hex 16)/" .env
make stand-up # docker compose up -d --build --wait: postgres, redis, migrate, api x API_REPLICAS, haproxy
make wait-ready # GET /health/ready через LB
make test # публичный smoke lab3 (через LB, BASE_URL=http://localhost:8080)
make test-e2e # black-box набор приложения (нужны loopback-порты PG/Redis из compose.yaml)
make test-analytics # регрессия аналитики трека 1: оффлайн, без стенда
```
Проверки отказов и сохранности (требуют управления контейнерами):
```sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && scripts/start-replica.sh
make test-dependencies
```
Эксперименты трека 1 (останавливают посторонние контейнеры хоста и возвращают их):
```sh
docker pull haproxy:3.2-alpine grafana/k6:0.54.0 postgres:16.4-alpine redis:7.4.2-alpine
python3 scripts/lab3/lab3.py track1 # серия A/B/C и рост ресурсов; фон хоста глушится сам
python3 scripts/lab3/lab3.py analyze # таблицы и графики из raw
```
Безопасная остановка стенда: `make stand-down` (`docker compose down`) — тома
`postgres-data` и `redis-data` **сохраняются**, поэтому данные и сессии остаются
на месте. Намеренное удаление учебных данных: `docker compose down -v` (удаляет
оба тома; после этого следующий `make stand-up` создаёт пустую схему и применяет
миграции заново).
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
клиент ──► HAProxy :8080 ──► api-1 ─┐
(проба /health/ready) ├──► PostgreSQL (источник истины)
api-2 ─┘ └──► Redis (сессии, кэш истории)
api-N
```
| Роль | Service | Образ | Готовность | Тома/порты |
| ------------- | ---------- | ------------------------------------ | ------------------------------------------------ | ----------------------------------- |
| Балансировщик | `haproxy` | `haproxy:3.2-alpine` | проба backend `GET /health/ready`, `timeout check 500ms` | `8080`, статистика `127.0.0.1:8404` |
| API ×N | `api` | сборка `Dockerfile` (`${API_IMAGE}`) | `/health/ready` (healthcheck контейнера) | портов нет |
| Миграции | `migrate` | тот же образ | `service_completed_successfully` | — |
| PostgreSQL | `postgres` | `postgres:16.4-alpine` | `pg_isready` | `postgres-data`, loopback:5432 |
| Redis | `redis` | `redis:7.4.2-alpine` | `redis-cli ping` | `redis-data`, loopback:6379 |
**Источник истины и транзакционные границы.** Пользователи, чаты, членство,
сообщения и журнал идемпотентности живут в PostgreSQL. Redis хранит сессии
(durability обеспечена AOF, поэтому сессии переживают рестарт) и кэш страниц
истории — производное состояние, которое всегда восстанавливается из БД: кэш
версионирован (`chats.message_version`, растёт в той же транзакции, что и вставка
сообщения), поэтому устаревшая страница не отдаётся. Локального состояния,
влияющего на корректность, у реплики нет — только счётчики метрик, они не
являются источником истины.
**Что перенесено из lab2 и что изменено.** Из lab2 без изменений: регистрация с
Argon2id, Basic→Bearer-сессии в общем Redis, чаты, keyset-пагинация `(created_at, id)`,
версионированный кэш истории с lock'ом на страницу, `X-Request-Id`,
`/health/live`, `/health/ready`, `/internal/metrics`, ограниченные `503` при
отказе зависимостей, миграции отдельным сервисом. Изменено: (1) `X-Instance-Id`
больше не случайный UUID, а `INSTANCE_ID`/hostname — по нему реплика
сопоставляется контейнеру; он же ставится в ответах об ошибках, которые
формируются фильтром раньше интерсептора; (2) **проба LB — та же
`/health/ready`**, что и healthcheck контейнера: реплика, потерявшая свой путь к
общей БД или Redis, выходит из ротации, а не отвечает клиенту `503`, оставаясь в
ней. Проверка PostgreSQL идёт по отдельному соединению (пул из одного клиента), а не
из общего пула, поэтому занятый пул не делает реплику неготовой; весь ответ
ограничен общим дедлайном `HEALTH_TIMEOUT_MS=400` (меньше `timeout check 500ms`);
(3) добавлена общая
идемпотентность отправки сообщения (таблица `idempotency_keys`, миграция 003);
(4) порядок остановки по `SIGTERM` вынесен в `main.ts`: дрейн → закрытие
сервера и пулов (стандартный порядок Nest закрывает пулы раньше дрейна);
(5) транзиентные коды PostgreSQL (`57014`, `40001`, `40P01`) отдаются как
`503 unavailable`, чтобы клиент мог безопасно повторить запрос с тем же ключом;
(6) `metrics` отдаёт `instance_id` и `build_id`. Деление суммарного бюджета API на реплики выполняет **харнесс** (`render_stand_env` в `scripts/lab3/lab3.py`): он пишет `.env.stand` с готовыми `API_CPUS_PER_REPLICA`/`API_MEMORY_PER_REPLICA`, которые читает `compose.yaml`; при ручном `docker compose up` правка `API_TOTAL_*` в `.env` ни на что не влияет — задавайте лимиты на реплику напрямую.
**Идемпотентность.** Ключ обязателен, область — пользователь + метод + путь чата
- ключ; заявка и тело ответа записываются одной транзакцией, повтор возвращает
сохранённый ответ, другое тело — `409`, отсутствие/неверный ключ — `400`,
просроченные записи (> `IDEMPOTENCY_TTL_SECONDS`, по умолчанию 24 ч) удаляются
фоновым проходом под advisory-локом и вручную (`npm run idempotency:gc`).
Семантика и ветки описаны в `app/README.md`.
**Соответствие `.env.example` ↔ фактическая конфигурация.** Приложение читает
`APP_*`, `SESSION_TTL_SECONDS`, `DATABASE_*`, `REDIS_URL`, `CACHE_*`,
`METRICS_TOKEN`, `HEALTH_TIMEOUT_MS` (бюджет пробы зависимостей в
`/health/ready`), `DRAIN_DELAY_MS`, `INSTANCE_ID`, `IDEMPOTENCY_TTL_SECONDS`
(`app/src/config/app-config.schema.ts`); стенд читает `API_TOTAL_CPUS`,
`API_TOTAL_MEMORY_MB` (делятся на `API_REPLICAS` → `API_CPUS_PER_REPLICA` /
`API_MEMORY_PER_REPLICA`), `PG_*`, `REDIS_*`, `LB_*`, `LOADGEN_*`, `API_IMAGE`,
`BUILD_ID`, `APP_PUBLIC_PORT`, `LB_STATS_PORT`, `POSTGRES_PUBLISHED_PORT`,
`REDIS_PUBLISHED_PORT`, `POSTGRES_DB/USER/PASSWORD`. Из скелетного
`.env.example` удалены неиспользуемые `SESSION_STORE` и `CACHE_URL_FILE`: в lab3
источник сессий один (Redis по `REDIS_URL`), выбор хранилища сессий больше не
конфигурируется, а секреты передаются через `DATABASE_URL`/`REDIS_URL` или
`*_FILE` (docker secrets). Публикуются только `8080` (LB), `127.0.0.1:8404`
(статистика LB) и loopback-порты PostgreSQL/Redis — исключительно для
операторских проверок с хоста (`make test-e2e`, `psql`); **у реплик API портов
нет**, `container_name` не задан нигде (`evidence/level4/limits-and-ports.txt`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` (через LB; повтор с тем же ключом → тот же JSON, другое тело → 409, без ключа → 400) | `evidence/level3/smoke.txt` |
| ≥2 реплики, одна точка входа, разные реплики с одной сессией | `python3 scripts/lab3/lab3.py check spread --requests 40` | 40 запросов с одним токеном → 2 разных `X-Instance-Id` (20/20), каждый сопоставлен контейнеру | `evidence/level4/spread.json` |
| Остановка любой одной реплики; записи продолжаются | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (по разу на реплику) | `observed_instances_before=2`, 130 успешных записей во время отказа, 0 потерянных подтверждений, `first_recovery_seconds≈3.3`, остановленный контейнер виден в `docker ps` до/после, HAProxy помечает слот `DOWN` (L7STS) через ≈1 s | `evidence/level3/failover-mtusi-lab3-api-1.txt`, `…-api-2.txt` |
| Сохранность данных и сессии при рестарте | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; перезапущены postgres, redis, api ×2, haproxy (StartedAt до/после), токен и подтверждённые сообщения живы | `evidence/level3/persistence.txt` |
| Идемпотентность, в том числе конкурентная | `python3 scripts/lab3/lab3.py check idempotency` | 4/4 теста: неверный/отсутствующий ключ → 400; повтор → тот же JSON; другое тело → 409; 8 параллельных POST с одним ключом → ровно одно сообщение; ключ не конфликтует между пользователями и чатами | `evidence/level4/idempotency-concurrency.txt` |
| Health/readiness, LB исключает недоступный backend | `python3 scripts/lab3/lab3.py watch` во время failover | HAProxy: `apiN UP → UP 1/2 (L7STS) → DOWN → MAINT (resolution)` ≈1 s после того, как дреин сделал пробу `/health/ready` неуспешной; период проверки 500 ms, `fall 2` ⇒ обнаружение 1–2 s (api-1 — 1 s, api-2 — 2 s) ≪ дрейн 3 s. Ту же ручку использует контейнерный healthcheck. Под насыщением пула слоты остаются `UP` (e2e-тест; контрольный прогон 1500 req/s — `evidence/track1/summary-probe-check.md`) | `evidence/level3/failover-*.txt` |
| Последовательная остановка каждой реплики под нагрузкой: RPS, ошибки, восстановление | `python3 scripts/lab3/lab3.py failover --replicas all --rate 200 --duration 60` | по каждой реплике: 0 ошибок у клиента и 0 ошибок уровня LB (`ereq`/`dresp`), 0 дублей и 0 потерь, реплика возвращается за 3.4–3.9 s; k6 держит 200 req/s без dropped. Оговорка: `ereq` — это ошибки обработки запроса балансировщиком, они не считают ответы 5xx приложения; чтобы такие ответы были видны, сэмплер теперь пишет `hrsp_2xx/4xx/5xx` и `dresp` по каждому слоту, а профиль k6 — классы ответов по каждому шагу (`summary-mechanism.md`) | `evidence/level4/failover-sweep.json`, `.md` |
| Лимиты CPU/RAM, отсутствие портов API, отсутствие `container_name`, секреты | `docker inspect`, `docker compose ps/config` | у api `NanoCpus`/`Memory` = лимитам конфигурации, `bindings=map[]`; суммарные лимиты стенда 2304 MiB; `container_name` отсутствует; пароль БД и токен метрик в трекаемых файлах не встречаются | `evidence/level4/limits-and-ports.txt` |
| Rolling update под нагрузкой, миграции однократно (совместимость DDL с работающей версией — ограничение в разделе «Ограничения») | `python3 scripts/lab3/lab3.py rolling-update --under-load --rate 200 --build-id …` | реплики заменяются по одной, `BUILD_ID` и image id меняются, 0 ответов 5xx из 884 попыток, `migrate` не перезапускался | `evidence/level4/rolling-update.json`, `.md` |
| Идемпотентность: удаление просроченных ключей | `docker compose --env-file .env exec -T api node dist/messages/idempotency/idempotency-gc.cli.js` (или `npm run idempotency:gc`) | GC удаляет ровно просроченную запись (created_at = now() − 2 суток): `Purged 1`, `expired_left=0`, свежая запись не тронута (`fresh_left=1`) | `evidence/level4/idempotency-gc.txt` |
| Отказы зависимостей | `make test-dependencies` | 4/4: (1) отказ Redis и (2) отказ PostgreSQL — реплика отвечает ограниченным `503 unavailable` с `request_id`, неготовыми становятся все реплики, HAProxy выводит их из ротации и отвечает своим `503`, запрос без сессии остаётся `401`; (3) локальный отказ БД у одной реплики — из ротации уходит только она, здоровая обслуживает 16/16 чтений; (4) насыщение пула (60 параллельных записей в заблокированный чат) — слоты остаются `UP`, все записи `201`; после возврата зависимости данные и сессия целы | `evidence/level4/dependency-faults.txt` |
| Трек 1: цена масштабирования | `python3 scripts/lab3/lab3.py sweep/track1-extras/ab/analyze` | серия 1/2/4 реплики, точки сатурации, серия роста ресурсов, подтверждённое улучшение | `evidence/track1/summary-*.md`, `evidence/track1/graphs/*.png`, `evidence/track1/raw/` |
| Воспроизводимость с чистого clone | `git clone -b lab3 … /tmp/lab3-clean` → `cp .env.example .env` → `docker compose down -v` → `make stand-up && make test && make test-persistence && make test-failover` | `PASS`: миграции применяются с пустого тома, smoke, сохранность и отказ реплики проходят без правок репозитория | `evidence/level3/clean-clone.txt` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Гипотезы (зафиксированы до прогонов)
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
- **H1.** При фиксированном суммарном бюджете API (3.0 CPU / 1.5 GiB) пропускная
способность растёт с числом реплик сублинейно и упирается в общий PostgreSQL
(1.5 CPU): серия A показывает knee, серия роста ресурсов подтверждает, что
именно БД, а не API, является ограничителем.
- **H2.** Запись в один «горячий» чат сериализуется на строке `chats`
(`UPDATE chats SET message_version = message_version + 1` держит блокировку до
COMMIT — это якорь инвалидации кэша), поэтому добавление реплик в этом профиле
не помогает: p-b упирается раньше p-a и не растёт с N.
- **H3.** Балансировщик (0.25 CPU) ограничивает путь чтения: два диагностических
прогона p-c при `LB_CPUS=0.25` и `LB_CPUS=1.0` показывают, что потолок
сдвигается вверх вместе с лимитом LB.
- **H4.** Число соединений с БД растёт как `N × DATABASE_POOL_MAX`, поэтому
размер пула влияет на потолок и на ожидания в БД (свип пула 5/10/20).
- **H5 (улучшение).** Сокращение пути записи с 8 SQL-обращений (проверка чата,
BEGIN, claim, проверка членства, INSERT, UPDATE версии, store, COMMIT) до одного
оператора уменьшает время удержания блокировки строки чата и число round trip'ов
и поднимает потолок при тех же лимитах. Проверяется A/B по правилу «медиана ≥5 %
и диапазоны min/max повторов не перекрываются».
### Методика
Метрики снимаются генератором k6 (`constant-arrival-rate`, плоские полки) и
сэмплером харнесса: `docker stats` (CPU/RAM контейнеров, 1.5 s),
статистика HAProxy (0.5 s), `/internal/metrics` каждой реплики (2 s),
`pg_stat_database`/`pg_stat_activity`/`pg_stat_statements` (2 s / 10 s) и фон
хоста. Профиль k6 считает классы ответов по каждому шагу, а сводка публикует две
частоты: **успешную** (`successful_rps`, ответы ожидаемого класса — рабочая
величина) и **частоту ответов** (`attempted_rps`, все полученные ответы —
диагностика); сатурация, потолок, Δ A/B и сравнение роста считаются только по
успешной. Профили: p-a (spread, POST) 100…1100 req/s, p-b (hot, один чат) 50…400
req/s, p-c (read, GET истории limit=50) 200…3000 req/s; шаг 15 s, прогрев — отдельный
прогон 30 s на первом темпе (в анализ не входит). Перед серией посторонние
контейнеры хоста останавливаются (`scripts/quiesce.sh`, состояние фиксируется в
манифестах), после — возвращаются. Конфигурации интерливятся по повторам, чтобы
дрейф частот и фоновой нагрузки ложился на все точки одинаково.
Бюджет серии одинаков для всех конфигураций: API total 3.0 CPU / 1536 MiB
(⇒ 3/N CPU и 1536/N MiB на реплику), PostgreSQL 1.5 CPU / 512 MiB,
Redis 0.25 CPU / 128 MiB, HAProxy 0.25 CPU / 128 MiB, генератор 1.5 CPU / 256 MiB.
Суммарный лимит RAM стенда — 2304 MiB постоянно (бюджет API 1536 MiB делится между
репликами, PostgreSQL 512, Redis 128, LB 128); запущенный генератор добавляет 256 MiB,
host на момент серии — 8 логических CPU, ≈6.6 GiB доступной памяти, background
остановлен.
### Серия A: 1 / 2 / 4 реплики
Бюджет серии одинаков для всех конфигураций (API total 3.0 CPU / 1536 MiB, PostgreSQL
1.5 CPU, LB 0.25 CPU, генератор 1.5 CPU), поэтому реплика получает 3/N CPU и 1536/N MiB.
Профиль p-a (24 чата, POST), 7 прогонов: N=1 и N=4 по два повтора, N=2 — три.
| темп, req/s | N=1: успешный RPS (2 повтора) | N=2: успешный RPS (3 повтора) | N=4: успешный RPS (2 повтора) |
| ----------- | -------------------------------- | -------------------------------------------- | -------------------------------- |
| 100 | 100 / 100 | 100 / 100 / 100 | 100 / 100 |
| 200 | 200 / 200 | 200 / 200 / 200 | 200 / 200 |
| 300 | 300 / 300 | 300 / 300 / 300 | 300 / 300 |
| 400 | 400 / 400 | 400 / 400 / 400 | 399 / 400 |
| 550 | 550 / 550 | 550 / 550 / 550 | 541 / 550 |
| 700 | 700 / 700 | 700 / 690 / 692 | 696 / 653 |
| 900 | **754 / 807** (p95 432 / 360 ms) | **650 / 538 / 614** (p95 474 / 693 / 502 ms) | **637 / 587** (p95 964 / 851 ms) |
| 1100 | **761 / 680** (p95 360 / 515 ms) | **532 / 578 / 590** (p95 604 / 609 / 566 ms) | **610 / 567** (p95 866 / 992 ms) |
Наблюдения:
- Точка сатурации у всех конфигураций — между 700 и 900 req/s, но **потолок не
растёт с числом реплик**: N=1 держит ≈750–800 req/s, N=2 ≈540–650, N=4 ≈570–640.
При фиксированном суммарном CPU выигрыша от реплик нет, а лучший результат даёт
одна реплика с полным бюджетом.
- Общий PostgreSQL при этом насыщен во всех конфигурациях: его пиковый CPU
153–156 % при лимите 1.5 CPU (150 %), `xact/s` 1224–1443, ожидания блокировок
до 16, hit ratio 0.95. То есть ограничитель один и тот же, и добавление
API-реплик его не расширяет (H1 подтверждена; блок 1500 ниже показывает прямым
тестом, что потолок задаёт именно квота CPU PostgreSQL).
- Реплики добавляют собственную накладную нагрузку: при N=4 квота 0.75 CPU на
реплику удерживает p95 в районе 850–990 ms там, где N=1 с квотой 3.0 CPU даёт
360–515 ms при большем успешном RPS. Это и есть «цена масштабирования»:
сублинейный (здесь — отрицательный) эффект при неизменном бюджете.
- Генератор в серии A загружен умеренно (средняя 26–31 % ядра, пики 45–123 % при
квоте 150 %), но на верхних шагах упирается в свой пул VU (200, `Insufficient VUs`
на 900/1100 req/s), поэтому приведённые потолки — нижние оценки. VU-своп ниже
показывает, что на текущем датасете тот же профиль даёт 946 → 1034 req/s (N=1)
при 200 → 2000 VU: измеренный потолок базовой конфигурации — ≈1030 req/s.
### Ограничения серии A
Серия A снята на **сборке C1** (путь записи из 8 обращений), на датасете, который
рос от 0.3 до 1.5 млн сообщений, и с `MAX_VUS=200` — на верхних шагах k6 упирался
в пул VU. Поэтому её абсолютные значения — нижние оценки для той конфигурации, а
сравнивать их с прогонами на сборке C2 и другом объёме данных нельзя. Что из
серии A остаётся в силе: (а) форма кривой и knee (100–700 req/s держатся ровно,
дальше рост прекращается), (б) PostgreSQL во всех конфигурациях у квоты при
неполной загрузке API, (в) направление «N реплик при фиксированном бюджете не
быстрее одной» — оно воспроизведено ниже на сборке C2 с достаточным пулом VU.
### VU-своп: потолок сервера или потолок генератора?
В прогонах серии A на верхних шагах k6 упирался в свой пул VU (200,
`Insufficient VUs`), поэтому «потолки» 754–807 / 538–650 / 587–637 req/s —
нижние оценки. Чистый VU-своп — одна и та же конфигурация (API 3.0 CPU всего,
PG 1.5, пул 10, LB 0.25, генератор 1.5 CPU), меняется только `MAX_VUS`; лестница
700/900/1100 req/s, по одному прогону на точку:
| `MAX_VUS` | N=1: успешный RPS при 900 / 1100 | N=4: успешный RPS при 900 / 1100 |
| --------- | ------------------------------ | ------------------------------ |
| 200 | 892.3 / 946.1 | 890.5 / 927.2 |
| 900 | 895.1 / 1009.9 | 893.2 / 953.1 |
| 2000 | 893.1 / 1034.4 | 897.1 / 971.7 |
Выводы:
- **На 1100 req/s пул VU всё ещё ограничивает**: N=1 растёт 946 → 1010 → 1034
(+9 %), N=4 — 927 → 953 → 972 (+5 %). То есть «потолки» серии A (754–807) были
занижены генератором, и на сегодняшнем датасете потолок базовой конфигурации —
≈1030 req/s (N=1) и ≈970 (N=4), а не 750–800.
- **На 900 req/s пул VU не влияет** (890–897 при всех значениях) — колено лежит
между 900 и 1100, что согласуется с блоком 1500 ниже.
- Порядок «одна реплика с полным бюджетом не хуже четырёх с четвертью»
сохраняется при каждом пуле VU: 1034 против 972 при 1100 req/s.
- **Абсолютные числа несравнимы с серией A**: та серия снята на сборке C1 (до
оптимизации пути записи) и с `MAX_VUS=200`; VU-своп, серия роста и блок 1500 — на
сборке C2, с `MAX_VUS≥900` и на большем объёме данных. Сравнивать корректно
внутри одной серии/блока (это и сделано везде), а направление эффекта (реплики при
фиксированном бюджете не увеличивают пропускную способность) воспроизводится на
обеих сборках.
### Диагностика: горячий чат и путь чтения
**Горячий чат (p-b, N=4, все записи в один чат).** Потолок наступает раньше и
падает: до 200 req/s успешный RPS равен предложенному (p95 9–14 ms), на 250
— 189 req/s (p95 2.2 s), на 300–400 — 79–104 req/s при p95 3.3–4.3 s, генератор
упирается в свои 200 VU, а сервер стоит в очереди за строкой чата. PostgreSQL в
этом прогоне: 39 ожидающих блокировку сессий (в серии A пик 2–18 в зависимости от
конфигурации и шага),
41 активная сессия, 356 xact/s (против 1224), hit ratio 0.85 (против 0.95),
CPU БД 156 % (квота исчерпана), при этом API-реплики загружены на 29–40 % —
они ждут блокировку, а не работают. Причина — якорь инвалидации кэша:
`UPDATE chats SET message_version = message_version + 1` в той же транзакции,
что и вставка сообщения, сериализует всех писателей одного чата до COMMIT.
Поэтому в профиле «один чат» добавление реплик не помогает вообще: H2 подтверждена,
и именно этот профиль выбран для A/B улучшения.
**Путь чтения (p-c, N=4, GET истории limit=50).** Потолок ≈1300–1400 req/s,
knee на 1500 req/s, p95 растёт с 24 ms (1000 req/s) до 241–399 ms; HAProxy за
прогон использует 8.3 % CPU в среднем и 13 % в пике, то есть около половины своей
квоты 0.25 CPU: **H3 отклонена — балансировщик в этом стенде не является
ограничителем пути чтения**. Ограничения этого пункта: прогоны снимались с
`MAX_VUS=200`, поэтому на шагах ≥1500 req/s k6 упирался в пул VU и измеренный
потолок 1300–1400 req/s — нижняя оценка; вывод про LB опирается на фактическую
загрузку HAProxy, а не на сравнение квот (квота LB проверяется отдельно на пути
записи, блок 1500 ниже). Ограничителями по фактическим наблюдениям были общие
компоненты: CPU PostgreSQL 155 % (квота 150 %) и генератор, чей пик 144 % при
квоте 1.5 CPU (контингенция плана: `p-c#gen2.0` — повтор с поднятой квотой
генератора).
### Серия роста ресурсов
Серия роста — блок `why#` на **1500 req/s** (за коленом): одно временное окно, один
коммит (`6cced49`), `MAX_VUS=900`, генератор 1.5 CPU / 1 GiB. Контроль — `why#n4`
(N=4: API total 3.0 CPU — 0.75 CPU на реплику, PostgreSQL 1.5 CPU, пул 10, LB
0.25 CPU). Каждая точка отличается от контроля одним ключом бюджета; сопоставимость
проверена по манифестам прогонов (темп, профиль, режим, коммит, образ, параметры
генератора и остальные ключи бюджета), фактические квоты сверены с `docker inspect`.
Точки — одиночные прогоны: различия меньше ±8 % не интерпретируются. Таблица
построена `analyse_growth` (`evidence/track1/summary-growth.md`, `growth.png`).
| Точка | Что изменено | успешный RPS | Δ к контролю, % | p95, ms | 5xx | dropped | VU пик / бюджет | CPU API: пик реплики, % её квоты | CPU PG пик, % ядра | вывод |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| why#n4 | контроль N=4 | 943.02 | — | 1196 | 0 | 33 420 | 900 / 900 | 74 % от 0.75 | 152 | контроль |
| why#n4-api6 | API ×2 (6.0 CPU) | 891.38 | −5.5 | 1363 | 0 | 36 519 | 900 / 900 | 48 % от 1.5 | 155 | в пределах разброса |
| why#n4-pg3 | PostgreSQL ×2 (3.0 CPU) | **1480.45** | **+57.0** | **291** | 0 | 1 174 | 516 / 900 | 83 % от 0.75 | **261** | рычаг поднимает потолок |
| why#n4-pool20 | пул 20 | 852.68 | −9.6 | 1321 | 0 | 38 839 | 900 / 900 | 75 % от 0.75 | 155 | ухудшает |
| why#n4-lb1 | LB ×4 (1.0 CPU) | 922.25 | −2.2 | 1196 | 0 | 34 667 | 900 / 900 | 64 % от 0.75 | 153 | в пределах разброса |
Пул 5 на этом темпе не снимался (`why#n4-pool5` в разделе «Вне сравнения» таблицы
`summary-growth.md`); точек, исключённых проверкой сопоставимости, нет.
Выводы — только из колонки «вывод»:
- **PostgreSQL ×2 — единственный рычаг, поднимающий потолок**: +57.0 % (1480.45 из
1500 предложенных), p95 291 против 1196 ms, PostgreSQL использует 261 % ядра.
- **API ×2 (−5.5 %) и LB ×4 (−2.2 %) — в пределах разброса**: пропускную
способность не меняют.
- **Пул 20 ухудшает** (−9.6 %, p95 1321 ms): больше соединений — больше конкуренции за
строку чата (механизм — блок 1500 ниже: 55 ожидающих лок против 21).
- **H4 (пул) отклонена в первоначальном виде**: рост пула не помогает, а за коленом
измеримо вредит; уменьшение пула в серии не проверялось.
### Почему рост реплик перестаёт помогать: разрез по времени выполнения
Ниже — измерение на одном темпе (1500 req/s), в одном временном окне, с
одинаковым пулом VU (900): конфигурации различаются только распределением
ресурсов, а каждая точка проверена по фактическим квотам (`docker inspect`). Сэмплер в этих прогонах дополнительно пишет
распределение ожиданий сессий PostgreSQL (`wait_event_type:wait_event`), дельты
`pg_stat_statements` по операторам, коды ответов LB (`hrsp_2xx..5xx`, `dresp`) и
классы ответов клиента (2xx/4xx/5xx); подробные таблицы — в
`evidence/track1/summary-mechanism.md`.
**Контроль вблизи колена (900 req/s, 2 повтора).** Блок из трёх конфигураций
(N=1, N=4, N=4 + API ×2) держит 94.8–99.6 % предложенного темпа, 0 ответов 5xx,
887–894 req/s при p95 240–664 ms, то есть у колена ни одна из них не насыщена;
N=4 (`block#n4`) — контроль только этого блока. Рычаги PG и пула проверяются в блоке
1500 (он же серия роста). Искать ограничитель нужно выше по темпу — это и делает блок 1500.
**Блок 1500 req/s (по 1 прогону на конфигурацию, 900 VU, 0 ответов 5xx).**
Здесь система насыщена, и ограничитель виден напрямую:
| конфигурация | RPS | p95, ms | Lock-ожиданий пик | горячий оператор, ms | CPU API: пик реплики, % её квоты | CPU PG пик, % ядра | dropped / VU |
| ------------ | ---------- | ------- | ----------------- | -------------------- | -------------------------------- | ------------------------------ | ------------ |
| N=1 | 1035.4 | 1091 | 2 | **1.19** | 35 % от 3.0 | 151 | 27 877 / 900 |
| N=4 | 943.0 | 1196 | 21 | 15.28 | 74 % от 0.75 | 152 | 33 420 / 900 |
| N=4, API ×2 | 891.4 | 1363 | 19 | 16.41 | 48 % от 1.5 | 155 | 36 519 / 900 |
| N=4, PG ×2 | **1480.5** | **291** | 17 | 5.55 | 83 % от 0.75 | **261 (квота 3.0 → 2.6 ядра)** | 1 174 / 516 |
| N=4, пул 20 | 852.7 | 1321 | 55 | **52.8** | 75 % от 0.75 | 155 | 38 839 / 900 |
| N=4, LB 1.0 | 922.3 | 1196 | 21 | 15.26 | 64 % от 0.75 | 153 | 34 667 / 900 |
Что здесь видно:
- **Ограничитель — CPU общего PostgreSQL.** Во всех конфигурациях, кроме PG ×2,
PostgreSQL стоит у своей квоты 1.5 CPU (151–155 % ядра), а система держит
≈950–1030 req/s. Удвоение квоты PG снимает насыщение: 1480 из 1500 предложенных
при p95 291 ms, PostgreSQL впервые реально потребляет ~2.6 ядра (261 %), а
отброшенные итерации падают с 33–39 тыс. до 1.2 тыс. Это прямой тест рычага.
- **CPU API — не ограничитель**: удвоение бюджета API ничего не даёт (891 против
943), при PG ×2 реплики доходят лишь до 83 % своей квоты.
- **Пул 20 вредит**: 853 req/s, 55 ожидающих блокировку сессий и 52.8 ms на горячем
операторе против 21 и 15.3 ms у базовой N=4 — больше соединений конкурируют за
одну и ту же строку чата.
- **Разделение бюджета делает работу дороже.** Один и тот же составной оператор
выполняется за **1.19 ms на одной реплике и 15.3 ms на четырёх**; разница — в
ожидании строки: пик `Lock:transactionid` 2 против 21. Порядок «одна реплика с
полным бюджетом не хуже четырёх» сохраняется: 1035 против 943.
- **Ожидания общие для всех реплик**: `LWLock:WALWrite` 17–20,
`Lock:transactionid` 16–18, `LWLock:BufferContent` 5–9 — очередь на фиксацию WAL
и на строку чата, а не дефицит CPU у отдельной реплики.
- **Балансировщик не ограничитель, но его квота почти выбирается.** Проверено с
фактическим применением квоты (`docker inspect`: 1.0 CPU): при 0.25 CPU HAProxy
использует 0.21 ядра в среднем и 0.25 в пике (у квоты), при 1.0 CPU — 0.27 ядра,
результат в пределах разброса (922 против 943; оба прогона упираются в 900 VU и в
PG). То есть 0.25 ядра — это столько, сколько HAProxy нужно на ≈950 req/s этого
профиля, а не искусственное ограничение.
Итог: «почему» закрыто прямым измерением — на этом профиле потолок задаёт **CPU
общего PostgreSQL** (и очередь на строку чата/WAL внутри него), а не распределение
бюджета между репликами: удвоение квоты PG поднимает потолок с ≈950–1030 до 1480
req/s, тогда как удвоение CPU API, четырёхкратная квота LB и увеличение пула не
дают ничего (пул 20 — вредит).
**Балансировщик — не ограничитель, и его квота проверена отдельно.** Плечо
`N=4, LB 1.0` (см. таблицу выше) отличается от базовой конфигурации только квотой
LB, применённой фактически (`docker inspect`: 1.0 CPU). HAProxy использует 0.21–0.27
ядра, четырёхкратный лимит не меняет результат (922 против 943 в пределах разброса;
оба прогона ограничены PG и пулом VU). В серии чтения `p-c` вывод про LB опирается
на его загрузку: 8.3 % ядра в среднем, 13 % в пике при квоте 0.25.
**Колено на текущей сборке.** Тот же профиль p-a, но лестница 900→2200 req/s
(900 VU, генератор 1 GiB, `knee#n1` / `knee#n4`): N=1 — 890 / 1106 / 1036 / 1004 /
991 req/s (p95 74 / 471 / 1285 / 1196 / 1248 ms), N=4 — 887 / 1055 / 903 / 929 /
965 req/s (p95 125 / 873 / 1420 / 1302 / 1235 ms). Колено сместилось с ≈700 req/s
(серия A на сборке C1) до ≈1200 req/s, а за коленом пропускная способность снова
перестаёт зависеть от числа реплик: одна реплика с полным бюджетом держит даже
немного больше (991–1036 против 903–965). То есть вывод «реплики не поднимают
потолок, пока узкое место — общий PostgreSQL и очередь на строку чата»
воспроизводится и на улучшенной сборке; он же объясняет, почему потолок сдвигает
только удвоение квоты PG (блок 1500 выше), а не перераспределение бюджета API.
### A/B улучшения
Профиль p-b (все записи в один чат), N=4; A — сборка из коммита **C1 = `e9cd28d`**
(8 SQL-обращений на путь записи, явная транзакция), B — **C2 = `5a5a8fe`** (один
оператор). Прогоны интерливились: A,B,A,B,A,B — по три повтора на сторону; между
сторонами менялся только образ API.
**Бюджет серии (по манифестам прогонов, `evidence/track1/raw/ab#*.manifest.json`):**
API total 6.0 CPU на 4 реплики, PostgreSQL 3.0 CPU, пул 20, LB 0.25 CPU, генератор
2.0 CPU и 512 MiB (повторы 1–2) / 1024 MiB (повтор 3), `MAX_VUS=1200`; датасет
1.38–1.52 млн сообщений. Это **не** бюджет по умолчанию (3.0/1.5/пул 10), поэтому
числа `ab#*` сравнимы **внутри серии** (обе стороны в идентичных условиях) и не
сравнимы напрямую с `p-b#n4` (потолок ≈200 req/s на бюджете по умолчанию). `cmd_ab`
фиксирует бюджет явно и печатает его в лог и в `ab-verdict.json`; контрольная серия
`abdiag` ниже повторяет сравнение на лимитах по умолчанию. Память генератора — 1 GiB:
на стороне A очередь за строкой чата раздувает число одновременных запросов, и при
512 MiB k6 убивался OOM (exit 137, зафиксировано в манифестах). Образ «до»
собирается одной командой: `make lab3-before-image` (архив дерева `e9cd28d` +
тот же Dockerfile, тег `mtusi-messenger:lab3-before`).
| темп, req/s | A: успешный RPS (min..max) | A: ответов RPS | p95 A, ms | B: успешный RPS (min..max) | p95 B, ms | Δ успешных, % | вывод |
| ----------- | -------------------------- | -------------- | ----------- | -------------------------- | --------- | ------------- | --------------- |
| 50 | 50.0 (50.0..50.07) | 50.0 | 9.5 | 50.07 (50.0..50.07) | 7.9 | +0.1 | не подтверждено |
| 100 | 100.07 (100.0..100.07) | 100.07 | 9.4 | 100.0 (100.0..100.07) | 6.7 | −0.1 | не подтверждено |
| 150 | 150.07 (150.07..150.07) | 150.07 | 10.1 | 150.07 (150.0..150.07) | 7.1 | 0.0 | не подтверждено |
| 200 | 200.07 (200.07..200.07) | 200.07 | 9.7 | 200.0 (198.93..200.07) | 7.8 | −0.0 | не подтверждено |
| 250 | 250.07 (250.07..250.07) | 250.07 | 11.2 | 250.07 (250.0..250.07) | 7.5 | 0.0 | не подтверждено |
| 300 | 257.8 (243.87..261.87) | 257.8 | **5200.9** | 300.07 (300.07..300.07) | 8.2 | **+16.4** | подтверждено |
| 350 | 127.4 (98.8..182.07) | **188.33** | **10 991.9** | 348.6 (348.13..350.07) | 29.3 | **+173.6** | подтверждено |
| 400 | 106.53 (102.27..124.4) | **171.73** | **10 816.3** | 400.07 (399.93..400.07) | 24.4 | **+275.6** | подтверждено |
**Потолок: A ≈ 258 req/s, B ≥ 400 req/s** (правило подтверждения: медиана
успешного RPS меняется ≥5 % и диапазоны min/max повторов не перекрываются; ниже
300 req/s обе стороны работают без насыщения, поэтому различие там и не должно
было проявиться). Все числа таблицы — **успешные ответы** (`201`); колонка
«ответов RPS» показывает, сколько запросов сторона A вообще довела до ответа: на
350/400 req/s это 188.33/171.73 при полезных 127.4/106.53 — разница и есть
клиентские отказы (таблица ниже).
**Уровень SQL подтверждает механизм.** Среднее время горячего оператора в
`pg_stat_statements` при одном и том же предложенном темпе: у A `UPDATE chats` —
**95.0 ms** (это и есть ожидание строки чата; в тот же момент 38 сессий стояли в
`Lock:transactionid`), у B составной оператор — **2.34–3.16 ms**. Разница в 30–40
раз и есть цена «8 обращений + явная транзакция» против «одного оператора».
До насыщения обе версии одинаковы (различие ≤0.1 %): один оператор не меняет
семантику, он меняет только время удержания блокировки строки чата и число круглых
поездок. После насыщения разница радикальна: у A очередь за строкой чата даёт p95
5–11 секунд и падение успешной пропускной способности до 106.5 req/s на 400 req/s
предложенных (при 171.7 доведённых до ответа — остальное отказы 503),
у B на 400 req/s p95 равен 24 ms, а отброшенных итераций 29 на 18 000. Это и есть
подтверждённое улучшение трека 1: сокращение критической секции (вместо проверки
чата, BEGIN, claim, проверки членства, INSERT, UPDATE версии, store и COMMIT —
один оператор, который делает всё то же самое атомарно).
Расширенная лестница для стороны B (400, 500, 600, 800 req/s, прогрев 30 s)
показывает новый потолок горячего чата: 400→400 (p95 65 ms), 500→495 (p95 276 ms),
600→559 (p95 1205 ms), 800→529 (p95 3113 ms), то есть **≈560–600 req/s против
≈258 req/s у A — рост более чем в 2 раза** при том же бюджете ресурсов
(`evidence/track1/raw/p-b#after-ext.*`).
**Контрольная серия `abdiag` (бюджет по умолчанию, 3+3 повтора, 900 VU).**
Бюджет первой серии A/B унаследован (6.0 CPU API, PG 3.0, пул 20, генератор 2.0),
поэтому её числа сравнимы только внутри себя; `abdiag` повторяет то же сравнение на
лимитах по умолчанию (API 3.0 CPU на 4 реплики, PG 1.5, пул 10, LB 0.25, генератор
1.5 CPU / 1 GiB), профиль тот же (p-b, горячий чат). Профиль k6 пишет классы ответов,
а сэмплер — `hrsp_*`/`dresp` каждого backend-слота.
| темп, req/s | A: успешный RPS (min..max) | A: ответов RPS | p95 A, ms | 5xx A за 3 повтора | B: успешный RPS (min..max) | p95 B, ms | 5xx B | Δ успешных, % | вывод |
| ----------- | -------------------------- | -------------- | ------------ | ------------------ | -------------------------- | --------- | ----- | ------------- | --------------- |
| 50 | 50.07 (50.07..50.07) | 50.07 | 9.3 | 0 | 50.07 (50.07..50.07) | 7.2 | 0 | 0.0 | не подтверждено |
| 100 | 100.07 (100.07..100.07) | 100.07 | 7.9 | 0 | 100.07 (100.07..100.07) | 6.6 | 0 | 0.0 | не подтверждено |
| 150 | 150.07 (150.07..150.07) | 150.07 | 11.0 | 0 | 150.07 (150.07..150.07) | 5.5 | 0 | 0.0 | не подтверждено |
| 200 | 200.07 (200.07..200.07) | 200.07 | 9.2 | 0 | 200.07 (200.07..200.07) | 6.6 | 0 | 0.0 | не подтверждено |
| 250 | 250.0 (249.2..250.07) | 250.0 | 11.0 | 0 | 250.07 (250.07..250.07) | 7.0 | 0 | 0.03 | не подтверждено |
| 300 | 231.5 (228.3..244.5) | 231.5 | **7272.7** | 4 | 300.0 (299.4..300.07) | 7.6 | 0 | **+29.6** | подтверждено |
| 350 | 86.7 (85.0..93.3) | **108.5** | **12 121.9** | 894 | 349.8 (348.7..350.07) | 21.8 | 0 | **+303.3** | подтверждено |
| 400 | 68.3 (56.9..100.4) | **132.7** | **12 234.0** | 2813 | 398.7 (397.6..400.07) | 59.7 | 0 | **+484.0** | подтверждено |
**Потолок: A 250 req/s (249.2..250.07), B 398.7 req/s (397.6..400.07)** — на бюджете
по умолчанию разрыв ещё больше, чем в первой серии (там A доходил до 258 при
удвоенных ресурсах). Разбор отказов: у A на 300/350/400 req/s клиент получил (суммарно по трём
повторам) 4, 894 и 2813 ответов класса 5xx (все — `503 unavailable`: срабатывает
`statement_timeout` 5 s, код `57014` переводится фильтром в ограниченный 503, а не
в 500), у B — ни одного 5xx и ни одного 4xx. Полезная работа стороны A при этом
падает сильнее, чем частота ответов: на 400 req/s из 132.7 ответов в секунду
успешны 68.3 (56.9–100.4 по повторам) — сравнение по частоте ответов показало бы
+200 %, по выполненной работе — **+484 %**. То есть выигрыш C2 не только в
пропускной способности: при том же бюджете версия C1 под затором на строке чата
начинает отказывать, а C2 держит темп. Сводка и вердикт —
`evidence/track1/summary-ab-abdiag.md`, `ab-verdict-abdiag.json`; классы ответов
по каждому шагу — в `evidence/track1/raw/abdiag#*.k6.json` и в
`summary-mechanism.md`.
**Что именно изменилось в SQL — по снятым данным, а не по коду.** Сэмплер пишет
`pg_stat_statements` каждые 10 s, поэтому по прогонам A и B считаются дельта вызовов
и времени по каждому оператору (`evidence/track1/statement-deltas.md`):
| сторона | оператор (начало) | вызовов | суммарно, ms | среднее |
| ------- | ----------------------------------------------- | ------- | ------------ | ----------- |
| A (C1) | `UPDATE chats SET message_version = …` | 18 629 | 1 773 086 | **95.2 ms** |
| A (C1) | `SELECT … chats …` (проверка чата) | 18 629 | 73 121 | 3.9 ms |
| A (C1) | `INSERT INTO messages …` | 18 629 | 59 479 | 3.2 ms |
| B (C2) | `WITH claim AS (INSERT INTO idempotency_keys …` | 28 515 | 66 939 | **2.35 ms** |
У C1 три видимых оператора выполняются ровно по разу на запись (18 629 = число
подтверждённых записей), и только они дают **≈102 ms SQL на запись**, из которых
95 ms — ожидание в `UPDATE chats` под блокировкой строки чата; у C2 путь записи —
один оператор со средним **2.35 ms**, отдельных `SELECT`/`INSERT`/`UPDATE` в
статистике нет (они вошли в составной оператор). Остальные обращения C1 (BEGIN,
claim, проверка членства, store, COMMIT) в выборку top-10 по суммарному времени не
попали — они дешевле перечисленных, поэтому «8 обращений» подтверждается кодом
(diff `410e1ea`→`5a5a8fe`) и структурой статистики, а измеримая разница — это
102 ms против 2.35 ms на запись.
**Ответы стороны A, а не только их количество.** На 350/400 req/s клиент A насчитал
2671 и 3485 ответов «не 201» (в абсолюте за 3 повтора). Профиль k6 считает классы
`2xx/4xx/5xx/other` по каждому шагу, а сэмплер пишет `hrsp_1xx..5xx` и `dresp`
каждого backend-слота; в контрольной серии `abdiag` (тот же профиль, бюджет по
умолчанию, 3+3 повтора) по ним видно, что все отказы стороны A — это
`503 unavailable` (раздел ниже). Публикуемая пропускная способность сведена к
**успешным** ответам: `summaryJson` пишет `successful_rps` (ответы ожидаемого
класса) и `attempted_rps` (все ответы), а сатурация, потолок и Δ A/B считаются
только по успешным; частота ответов остаётся отдельной диагностической колонкой.
### Воспроизводимость прогонов трека
Параметры пула передаются API (объявлены в `environment`), лимиты PostgreSQL/HAProxy
применяются пересозданием соответствующих сервисов, а фактическая конфигурация
каждого прогона проверяется через `docker inspect` и пишется в манифест
(`observed_stand`). Профиль p-c готовит по 50 сообщений на чат до начала нагрузки;
активные VU фиксируются и на успешных ответах; CPU API в сводках — пик отдельной
реплики в процентах её квоты; периодический подсчёт messages заменён оценкой
`pg_class.reltuples`.
**Корректность идемпотентности.** Удаление истёкшей записи условное: TTL
проверяется в самом `DELETE`, поэтому параллельная реплика не может удалить свежую
замену после устаревшего чтения. Покрыто targeted-тестами
`app/src/messages/idempotency/idempotency.repository.spec.ts` и
`app/src/messages/messages.service.spec.ts`.
Все серии воспроизводятся из репозитория (все параметры — в манифестах `raw/*.manifest.json`):
```sh
# базовая серия: 1/2/4 реплики, профиль p-a (7 прогонов)
python3 scripts/lab3/lab3.py track1 --reps 2 # серии A/B/C и рост ресурсов + analyze
# догоняющие серии (VU-своп, блоки «почему», контрольный A/B на бюджете по умолчанию)
python3 scripts/lab3/lab3.py track1-extras --part all --reps 2 --rate 1500 --max-vus 900 \
--loadgen-memory 1024m --ab-reps 3
# отдельные блоки (если нужен только один)
python3 scripts/lab3/lab3.py track1-extras --part vuswap
python3 scripts/lab3/lab3.py track1-extras --part why --rate 900 --prefix block --max-vus 900 --loadgen-memory 1024m
python3 scripts/lab3/lab3.py track1-extras --part abdiag --ab-reps 3 --loadgen-memory 1024m
# колено на текущей сборке и точки роста
python3 scripts/lab3/lab3.py run --no-warmup --profile p-a --replicas 1 --ladder 900,1200,1500,1800,2200 \
--label knee#n1 --max-vus 900 --loadgen-memory 1024m
python3 scripts/lab3/lab3.py track1-extras --part why --loadgen-memory 1024m # блок 1500 req/s = серия роста
python3 scripts/lab3/lab3.py run --label 'probecheck#n4#rep1' --profile p-a --peak 1500 --duration 60 \
--replicas 4 --api-total-cpus 3.0 --pg-cpus 1.5 --pool 10 --lb-cpus 0.25 \
--loadgen-cpus 1.5 --loadgen-memory 1024m --max-vus 900 --pre-vus 60 --no-warmup
# агрегаты и графики
python3 scripts/lab3/lab3.py analyze
```
Образ «до» для A/B собирается `make lab3-before-image` (дерево коммита `C1 = e9cd28d`
плюс тот же Dockerfile), образ «после» — обычная сборка текущего дерева.
### Таблица отказов
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `SIGTERM` одной API-реплике (`scripts/stop-one.sh`, `docker stop --time 10`) | LB исключает узел, клиент продолжает работать; подтверждённые записи целы | HAProxy: `UP → 1/2 → DOWN (L7STS) → MAINT (resolution)` ≈1 s после начала остановки; k6 держит 200 req/s без dropped и ошибок; проба клиента: 0 ошибок, 0 дублей, 0 потерь (295/295 и 294/294 подтверждены); в окне остановки и дрейна (3.25–3.3 s) клиент держал ≈4.9–5.0 req/s и не получил ни одной ошибки | реплика возвращается за 3.4–3.9 s (`scripts/start-replica.sh`); потерь нет |
| Рестарт всего стенда (`scripts/restart.sh`) | данные и сессии сохраняются, повторный вход не нужен | `make test-persistence` PASS; StartedAt всех контейнеровобновились, токен и сообщения живы | ≈8 s до `/health/ready`; потерь нет |
| Rolling update под нагрузкой (замена реплик по одной) | нет 5xx, миграции не перезапускаются | 0 ответов 5xx из 884 попыток при 200 req/s; `BUILD_ID` меняется по шагам (`final-1b4aac7`); `migrate` StartedAt не изменился | замена реплики занимает 9.75–9.76 s (`docker stop` → `rm` → создание → healthy, измерено харнессом), стенд не теряет запросы |
| Отказ Redis (`docker compose stop redis`) | реплики становятся неготовыми, LB исключает все backend, клиент не получает успешных ответов; анонимный запрос остаётся 401 | `make test-dependencies` PASS (4/4 теста); `/health/live` реплики `200`, `/health/ready` и бизнес-запросы — ограниченный `503 unavailable` с `request_id`, после дрейна всех слотов LB отвечает своим `503` | зависимость возвращается за ≈2 s, сессия сохраняется (AOF) |
| Отказ PostgreSQL (`docker compose stop postgres`) | то же; после возврата данные целы | PASS, подтверждённые сообщения и сессия на месте | ≈6 s до `/health/ready` |
| Локальный отказ PostgreSQL у одной реплики (reject в `pg_hba.conf` для её адреса + разрыв соединений) | из ротации уходит только затронутая реплика, здоровая продолжает обслуживать | выбранная реплика: `/health/ready=503` (ограниченное тело с `request_id`), её слот HAProxy `UP → UP 1/2 (L7STS) → DOWN`; здоровая: `200` и `UP`; 16 чтений через LB — все `200`, ни одно не обслужено выбранной репликой; время до `DOWN` — менее 3 s (проверяется e2e-тестом; 0.66 s при ручной проверке); до `DOWN` выбранная реплика ещё получает запросы и отвечает ограниченным `503` — это окно `fall 2`; после восстановления `pg_hba.conf` (в `finally`) реплика возвращается в ротацию и снова получает запросы | правило снимается в `finally`; потерь данных нет |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
**Что стенд выдерживает (проверено, evidence/level3 и evidence/level4):**
- Остановку любой одной API-реплики: LB исключает её за ≈1 s (проб 500 ms, `fall 2`),
клиент продолжает работу без ошибок, дублей и потерь; окно дреина (3 s) длиннее
обнаружения, поэтому начатые запросы успевают завершиться.
- Рестарт всего стенда: данные PostgreSQL и сессии в Redis (AOF) сохраняются,
повторный вход не нужен.
- Rolling update: поочерёдная замена реплик под нагрузкой без ответов 5xx.
- Отказ Redis и PostgreSQL: реплика отвечает ограниченным `503 unavailable` с
`request_id`, без `500` и без деталей драйвера (проверяется изнутри реплики);
анонимный запрос остаётся `401`; после возврата зависимости подтверждённые данные
и сессия целы.
- Отказ общей зависимости для всех реплик: каждая становится неготовой, LB выводит
их из ротации и отвечает **своим** `503` (без тела API и `request_id`) — это
сознательный выбор в пользу честного «готовых узлов нет» вместо реплик в ротации,
которые не могут обслужить запрос. `/health/live` при этом отвечает `200`, то есть
процесс виден и отличим от «все backends мертвы». Локальный отказ зависимости у
одной реплики (её адрес отвергается в `pg_hba.conf`) выводит из ротации только её:
16/16 чтений через LB обслужила здоровая реплика. Redis — обязательная зависимость
готовности: Bearer-сессии хранятся только в Redis, без него аутентифицированный
запрос невозможен; кэш истории деградирует на PostgreSQL, но это не спасает
аутентификацию.
**Чего доказательство не покрывает:** «миграции однократны» проверено (отдельный сервис
`migrate` + `service_completed_successfully`, при rolling update контейнер миграций не
перезапускался), но **совместимость схемы с работающей версией** — нет: rolling
заменял сборки одного коммита, схема между ними не менялась. По устройству миграции
аддитивны (`CREATE TABLE IF NOT EXISTS`, `CREATE INDEX`, `DO $$ … EXCEPTION`), а
работающий код новых объектов не читает, поэтому старый процесс переживёт применение
003/004; но это аргумент от кода, а не изменение схемы под нагрузкой.
**Что не выдерживает:**
- Отказ docker-хоста целиком: узел один (это трек 2).
- Потерю единственного экземпляра PostgreSQL, Redis или балансировщика: они не
реплицированы, у LB нет второго экземпляра — падение БД означает отказ записи и
чтения истории, падение LB — потерю точки входа.
- Потерю тома PostgreSQL: резервных копий в стенде нет.
**Границы измерения:**
- Один хост (8 логических CPU, ≈6.6 GiB свободной памяти на момент серии).
Конфигурации интерливятся по повторам, посторонние контейнеры остановлены
(`scripts/quiesce.sh`), но разброс повторов на насыщении достигает ±5–8 %
(в отчёте публикуются min/max). Поэтому однократные точки роста за плато не
доказывают различия меньше этого разброса — это прямо отражено в выводах.
- Путь чтения: генератор упирался в свой пул VU (200) на шагах ≥1500 req/s
(`Insufficient VUs`), поэтому измеренный потолок 1300–1400 req/s — нижняя оценка;
вопрос «кто ограничивает чтение» отдельным экспериментом не закрыт (LB проверен
и отклонён как ограничитель).
- Серверные перцентили берутся из `/internal/metrics` (буфер 4096 последних
запросов на процесс), клиентские — из k6; при N реплик счётчики суммируются, а
перцентили снимаются по репликам.
- Redis работает с `maxmemory 96mb` и `volatile-lru`: при исчерпании памяти
теоретически возможно вытеснение наименее используемой сессии (учебное
упрощение); в измеренных профилях объём ключей на порядки меньше лимита.
- Генератор нагрузки ограничен контейнером (CPU/RAM/VU). Из-за этого отдельно
проведён **VU-своп** (одна конфигурация, меняется только `MAX_VUS`) и контрольные
блоки с `MAX_VUS=900`; память генератора в них поднята до 1 GiB (при 256 MiB k6
убивался OOM на медленной стороне A — зафиксировано в журнале ядра и в манифестах).
- Датасет растёт в течение сессии: к концу серии `messages` — 3.52 млн строк,
`idempotency_keys` — столько же строк (каждая итерация генератора пишет новый
ключ). Поэтому прогоны одной и той же конфигурации, снятые в разное время, не
сравнимы напрямую, и внутри блока все конфигурации измеряются в одном временном
окне с интерливингом повторов, чтобы различия относились к ресурсам, а не к
дрейфу объёма данных.
- **Серии сняты на разных сборках**: серия A и первая серия A/B — на сборке C1 (путь
записи из 8 обращений); серия роста, VU-своп, `knee` и `abdiag` — на сборке C2.
Абсолютные значения между группами несравнимы; все сравнения в отчёте делаются
внутри одной серии/блока.
- Первая серия A/B шла на унаследованном бюджете (API 6.0 CPU, PG 3.0, пул 20,
генератор 2.0); её числа сравнимы только внутри себя. Контрольная серия `abdiag`
повторяет сравнение на бюджете по умолчанию — см. раздел «A/B улучшения».
- **Метрика трека 1 — успешный RPS.** `summaryJson` считает `successful_rps`
(ответы ожидаемого класса) и `attempted_rps` (все ответы); сатурация, потолок,
Δ A/B и сравнение роста используют только успешный RPS, иначе отказы под нагрузкой
выглядят как выполненная работа (пример: `abdiag#A` на 400 req/s — 68.3 успешных
против 132.7 полученных ответов в секунду). В сводках, снятых до введения полей,
`successful_rps`/`attempted_rps` вычислены из счётчиков той же сводки
(`status.ok`, `requests`, длительность ступени); новые прогоны пишут их сразу.
Инвариант закреплён тестом `tests/test_lab3_analytics.py` (`make test-analytics`).
- **Проба LB в сериях трека 1.** Серии трека 1 (A, p-b, p-c, VU-своп, knee, блоки
block#/why#, ab, abdiag) сняты с пробой LB, проверявшей только процесс и флаг
дреина (коммиты `e38795d`, `6cced49`). Текущая проба тоже не зависит от нагрузки
(отдельное соединение, общий дедлайн). Контрольный прогон на `1b4aac7` при
1500 req/s: слоты всё время `UP`, 0 ответов 5xx, Δ −7.1 % к why#n4 (в пределах
разброса ±8 %; в БД 3.63 млн сообщений против 2.64 млн у why#n4) —
`evidence/track1/summary-probe-check.md`. Уровень 4 переснят на `1b4aac7`.
**Что подтверждено измерением:** сокращение пути записи до одного оператора (коммит C2) поднимает потолок горячего чата с ≈258 до ≥400 req/s и снижает p95 с 5–11 s до 8–29 ms при том же бюджете ресурсов (A/B, 3+3 повтора, `evidence/track1/summary-ab.md`). Статус гипотез:
- **H1 подтверждена**: (а) рост числа реплик при фиксированном бюджете не увеличивает
пропускную способность (N=1 1035 против N=4 943 при 1500 req/s; 1034 против 972 в
VU-свопе), и (б) ограничитель — именно PostgreSQL: удвоение его квоты поднимает
потолок с ≈950–1030 до 1480 req/s при p95 291 ms.
- **H2 подтверждена**: горячий чат — 39 ожидающих блокировку сессий, API-реплики
простаивают (раздел «Диагностика»).
- **H3 отклонена**: квота LB проверена фактически (0.25 и 1.0 CPU), HAProxy использует
0.21–0.27 ядра, результат не меняется (922 против 943 в пределах разброса). На пути
чтения прогоны упирались в пул VU, поэтому там вывод опирается на загрузку HAProxy.
- **H4 отклонена (в обратную сторону)**: рост пула не помогает, а вредит — пул 20 даёт
853 req/s, 55 ожидающих лок и 52.8 ms на горячем операторе против 943, 21 и 15.3 ms
у базовой N=4.
- **H5 подтверждена**: A/B (C1 против C2) — потолок горячего чата 258 → ≥400 req/s,
p95 5–11 s → 8–29 ms; на 400 req/s сторона A обслуживала успешно 106.5 req/s из
171.7 полученных ответов, сторона B — 400.07. Контрольная серия `abdiag` на бюджете
по умолчанию подтверждает разрыв (A 250, B 398.7 успешных req/s).
**Что подтверждено отдельным экспериментом (механизм):** блок 1500 req/s (один темп,
одно временное окно, одинаковый пул VU = 900) показывает, что удвоение CPU API не
даёт ничего (891 против 943), четырёхкратная квота LB — тоже (922 против 943), пул 20
вредит (853), а удвоение CPU PostgreSQL снимает насыщение (1480 req/s, p95 291 ms).
Разделение бюджета между репликами увеличивает среднее время горячего оператора с
1.19 до 15.3 ms и число ожидающих строку сессий с 2 до 21. Ожидания —
`LWLock:WALWrite` (17–20), `Lock:transactionid` (16–18), `LWLock:BufferContent` (5–9) —
общие для всех реплик, то есть узкое место — общий PostgreSQL. Остаётся гипотезой
разделение вклада WAL/диска и строки чата внутри этого общего пути: чтобы их
разъединить, PostgreSQL нужно вынести на отдельный узел (трек 2) или сменить диск.
**Следующие шаги:** (1) повторить серию A с ≥3 повторами и прогревом 60 s, чтобы
различать эффекты меньше 8 %; (2) повторить путь чтения с большим пулом VU
генератора; (3) вынести PostgreSQL и LB на отдельные узлы и проверить перенос
(трек 2); (4) добавить бэкап тома PostgreSQL и проверку восстановления.
+59
View File
@@ -0,0 +1,59 @@
# compiled output
/dist
/node_modules
/build
# TypeScript build cache
*.tsbuildinfo
# Logs
logs
*.log
npm-debug.log*
pnpm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
# OS
.DS_Store
# Tests
/coverage
/.nyc_output
# IDEs and editors
/.idea
.project
.classpath
.c9/
*.launch
.settings/
*.sublime-workspace
# IDE - VSCode
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
# temp directory
.temp
.tmp
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+6
View File
@@ -0,0 +1,6 @@
{
"singleQuote": true,
"trailingComma": "all",
"tabWidth": 4,
"useTabs": true
}
+314
View File
@@ -0,0 +1,314 @@
# app — API мессенджера
NestJS 12 + Fastify, ESM TypeScript. PostgreSQL — источник истины бизнес-данных,
Redis — серверные Bearer-сессии и производный кэш истории сообщений.
Общая документация (в корне репозитория):
| Документ | Что содержит |
|---|---|
| [`../REPORT.md`](../REPORT.md) | архитектура, схема данных, транзакции, политика кэша, команды, результаты проверок и трека 1 |
| [`../evidence/README.md`](../evidence/README.md) | индекс доказательств: что подтверждено и как это воспроизвести |
| [`../contracts/openapi.json`](../contracts/openapi.json) | нормативный контракт API |
| [`../tests/README.md`](../tests/README.md) | публичные проверки репозитория (`make check`, `make test`, persistence) |
## Что внутри
```text
src/
main.ts bootstrap: Fastify, ValidationPipe, shutdown hooks
app.module.ts сборка модулей приложения
config/ Zod-схема env + глобальный ConfigModule
database/ pg.Pool, транзакции, миграции (001..004)
redis/ клиент Redis (AOF-совместимый, без offline queue)
auth/ Basic-вход, Redis-сессии, logout
users/ регистрация (Argon2id), профиль
chats/ создание чата в транзакции, список и чтение
messages/ отправка сообщения, keyset-история
cache/ версионированный кэш истории + lock на страницу
idempotency/ журнал Idempotency-Key (claim/read/store/forget/GC)
metrics/ /internal/metrics и /internal/metrics/reset
health/ liveness/readiness с проверкой зависимостей (readiness — проба LB)
common/
http/ cursor (формат+календарь), page (конверт {items,next_cursor}), request-id
errors/ exception filter и тип тела ошибки ApiErrorBody
validation/ декоратор CodePointLength (длины в Unicode code points)
auth/ guard и декоратор текущего пользователя
test/
app.e2e-spec.ts black-box набор против запущенного API (PG + Redis)
scripts/
graph-modules.ts генератор графа зависимостей (nestjs-spelunker)
```
Принципы: raw `pg.Pool` без ORM, параметризованные запросы, никаких in-memory
хранилищ в боевых путях; кэш — производное состояние и всегда допускает
восстановление из PostgreSQL; отказ зависимости даёт ограниченную ошибку
(`503`), а не аварийное завершение процесса; длины строк проверяются в Unicode
code points (свой декоратор `@CodePointLength`), как в JSON Schema, а не в
UTF-16-единицах; состояние, от которого зависит корректность (сессии, журнал
идемпотентности), живёт только в общих PostgreSQL/Redis — локальных сессий и
файлов на диске реплики нет, поэтому `N` взаимозаменяемых реплик за одним LB
дают один и тот же результат.
## Быстрый старт
Рекомендуемый путь — весь стенд из корня репозитория (PostgreSQL, Redis, миграции, API):
```sh
cd ..
cp .env.example .env
password=$(openssl rand -hex 32)
sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$password/" .env
sed -i "s|^DATABASE_URL=.*|DATABASE_URL=postgresql://messenger:$password@postgres:5432/messenger|" .env
sed -i "s/^METRICS_TOKEN=.*/METRICS_TOKEN=$(openssl rand -hex 16)/" .env
make stand-up # сборка + up -d --wait: migrate -> api x API_REPLICAS -> haproxy
make wait-ready
curl -fsS http://localhost:8080/health/ready
for i in 1 2 3 4; do curl -sD- -o /dev/null localhost:8080/health/live | grep -i x-instance-id; done
```
Публичной точкой входа служит HAProxy (`compose.yaml`): реплики API портов не
публикуют. `API_REPLICAS` задаёт их число, `API_TOTAL_CPUS` / `API_TOTAL_MEMORY_MB`
делятся между ними — это бюджет серии трека 1 (`../REPORT.md`).
Локальный запуск без Docker (нужны доступные PostgreSQL и Redis):
```sh
cd app
npm ci
npm run build
export DATABASE_URL=postgresql://messenger:<password>@127.0.0.1:5432/messenger
export REDIS_URL=redis://127.0.0.1:6379
export APP_PORT=8080
node dist/database/migration.runner.js # применяет миграции из dist/database/migrations
npm run start:dev # или npm run start:prod после build
```
## Переменные окружения
Читаются только через конфигурационный слой (`src/config`), типы и диапазоны
проверяет Zod-схема на старте — при некорректном значении приложение падает
с понятной ошибкой.
| Переменная | По умолчанию | Назначение |
|---|---|---|
| `APP_HOST` / `APP_PORT` | `0.0.0.0` / `8080` | адрес прослушивания |
| `APP_ENV` | `lab` | метка окружения |
| `DATABASE_URL` | — (обязательна) | строка подключения PostgreSQL |
| `REDIS_URL` | — (обязательна) | строка подключения Redis |
| `DATABASE_POOL_MAX` | `10` | размер пула соединений |
| `DATABASE_CONNECTION_TIMEOUT_MS` | `5000` | таймаут установки соединения |
| `DATABASE_STATEMENT_TIMEOUT_MS` | `5000` | таймаут SQL-запроса |
| `SESSION_TTL_SECONDS` | `3600` | TTL сессии (минимум 2) |
| `HEALTH_TIMEOUT_MS` | `400` | бюджет проверки PostgreSQL/Redis внутри `/health/ready`; меньше `timeout check` HAProxy (500 ms) и `DATABASE_STATEMENT_TIMEOUT_MS` |
| `CACHE_TTL_SECONDS` | `30` | TTL страницы истории в Redis |
| `CACHE_MODE` | `protected` | `protected` (lock на страницу) или `naive` (только для эксперимента) |
| `CACHE_LOCK_TTL_MS` | `1000` | TTL lock-а страницы |
| `CACHE_MISS_DELAY_MS` | `0` | искусственная пауза на промахе; влияет только на `naive` |
| `METRICS_TOKEN` | — (необязательна) | токен доступа к `/internal/metrics*`; без него endpoint закрыт |
| `DRAIN_DELAY_MS` | `5000` (в стенде `3000`) | окно дрейна при `SIGTERM`: реплика сразу перестаёт проходить пробу LB, ждёт этот интервал и только затем закрывает сервер и пулы |
| `INSTANCE_ID` | hostname контейнера | значение `X-Instance-Id`; в Docker hostname = короткий ID контейнера, поэтому `scripts/stop-one.sh` находит реплику по нему |
| `IDEMPOTENCY_TTL_SECONDS` | `86400` | срок хранения журнала Idempotency-Key (минимум 60) |
Поддерживаются также `DATABASE_URL_FILE` / `REDIS_URL_FILE`: если заданы, значение
читается из файла (docker secrets / Swarm). Подробности и компромиссы —
[`../REPORT.md`](../REPORT.md), раздел «Конфигурация и секреты».
## Эндпоинты
Публичный контракт — [`../contracts/openapi.json`](../contracts/openapi.json).
| Метод и путь | Аутентификация | Назначение |
|---|---|---|
| `GET /health/live` | нет | процесс жив; не обращается к зависимостям, поэтому отвечает `200` и при их отказе |
| `GET /health/ready` | нет | готовность реплики: флаг дреина + PostgreSQL и Redis (бюджет `HEALTH_TIMEOUT_MS`), иначе `503`; эту же ручку пробует HAProxy |
| `POST /api/v1/users` | нет | регистрация с паролем (Argon2id) |
| `POST /api/v1/auth/sessions` | `Basic` | вход, выдаёт opaque Bearer-токен |
| `DELETE /api/v1/auth/sessions/current` | `Bearer` | отзыв текущей сессии, `204` |
| `GET /api/v1/users/me` | `Bearer` | текущий пользователь |
| `POST /api/v1/chats` | `Bearer` | создание чата (транзакция) |
| `GET /api/v1/chats` | `Bearer` | список доступных чатов |
| `GET /api/v1/chats/:chatId` | `Bearer` | чат по id (чужой — `404`) |
| `POST /api/v1/chats/:chatId/messages` | `Bearer` + обязательный `Idempotency-Key` | отправка сообщения (см. ниже) |
| `GET /api/v1/chats/:chatId/messages` | `Bearer` | история, keyset-пагинация `(created_at, id)` |
| `GET /internal/metrics` | `Bearer METRICS_TOKEN` | счётчики и агрегаты латентности |
| `POST /internal/metrics/reset` | `Bearer METRICS_TOKEN` | сброс счётчиков (`200`) |
Правила: `Basic` принимается только на создании сессии, бизнес-запросы — только
`Bearer`; заголовок `X-User-Id` не аутентифицирует и не подменяет владельца
сессии; истёкший, отозванный или неизвестный токен — `401` с соответствующим
`WWW-Authenticate`.
## npm-скрипты
| Команда | Что делает |
|---|---|
| `npm run build` | сборка в `dist/` |
| `npm run start:dev` | watch-режим |
| `npm run start:prod` | запуск собранного приложения (`node dist/main`) |
| `npm test` / `npm run test:unit` | unit-тесты (vitest) |
| `npm run test:e2e` | black-box набор против запущенного API (см. ниже) |
| `npm run test:dependencies` | автоматическая проверка отказов Redis/PostgreSQL: останавливает и поднимает контейнеры Compose-стенда |
| `npm run idempotency:gc` | ручной прогон удаления просроченных записей Idempotency-Key |
| `npm run lint` | oxlint по `src/` и `test/` |
| `npm run format` | prettier |
| `npm run graph` | граф модулей и провайдеров через nestjs-spelunker (пишет `../docs/architecture/`) |
## Тесты
Unit-тесты не требуют инфраструктуры:
```sh
npm test
```
Интеграционный набор работает по HTTP против запущенного стенда и дополнительно
подключается к PostgreSQL (очистка тестовых данных) и Redis:
```sh
export API_BASE_URL=http://localhost:8080
export DATABASE_URL=postgresql://messenger:<password>@<pg-host>:5432/messenger
export REDIS_URL=redis://<redis-host>:6379
npm run test:e2e
```
Название `API_BASE_URL` (а не `BASE_URL`) выбрано потому, что Vitest сам
устанавливает `process.env.BASE_URL` в значение Vite base. Кейс истечения сессии
включается переменной `SESSION_TTL_SECONDS=2` и у запущенного API, и у набора.
## Отказы зависимостей
Отдельный набор останавливает и поднимает контейнеры Compose-стенда и проверяет
ограниченные ошибки вместо 500:
```sh
cd .. # из корня репозитория, стенд поднят через docker compose
make test-dependencies
```
Он включён по флагу `E2E_DEPENDENCY_FAULTS=1` (им же управляет цель Makefile),
потому что требует прав на управление Docker Compose-проектом; остальные
переменные — `E2E_COMPOSE_DIR`, `E2E_COMPOSE_ENV_FILE`, `E2E_REDIS_SERVICE`,
`E2E_POSTGRES_SERVICE`, `E2E_API_SERVICE`, `E2E_LB_STATS_URL`,
`E2E_POSTGRES_USER`, `E2E_POSTGRES_DB`, `E2E_PG_HBA_PATH`.
Проверяются три топологии отказа:
1. **Отказ Redis** (общая зависимость): `/health/live` реплики остаётся `200`,
`/health/ready` и бизнес-запросы — `503 unavailable` с `request_id` из
`X-Request-Id` и без деталей драйвера, запрос без сессии — по-прежнему `401`.
Неготовыми становятся все реплики, HAProxy исключает их из ротации и
отвечает собственным `503`; после старта Redis сессия и подтверждённое
сообщение живы.
2. **Отказ PostgreSQL** (общая зависимость): то же плюс проверка, что после
возврата зависимости данные на месте и новая запись проходит.
3. **Отказ PostgreSQL у одной реплики** (локальный путь к БД): для адреса
выбранной реплики временно ставится `reject`-строка в `pg_hba.conf` (первое
совпадение) и обрываются её соединения. Выбранная реплика отвечает `503` и её
слот уходит в `DOWN`, здоровая продолжает `200`/`UP` и обслуживает все чтения
через LB; `pg_hba.conf` восстанавливается в `finally`, после чего реплика
возвращается в ротацию и снова получает запросы.
Реплики API портов не публикуют, поэтому отдельная реплика опрашивается изнутри
своего контейнера (loopback), а состояние слотов — из `stats;csv` HAProxy
(`127.0.0.1:8404`). Каждый запрос к остановленной БД ждёт
`DATABASE_CONNECTION_TIMEOUT_MS`, поэтому набор идёт около минуты.
## Реплики, балансировка и остановка реплики
Все реплики запускаются из одного образа и одного `compose.yaml`; API портов не
публикует, трафик идёт только через HAProxy. Состояние, от которого зависит
корректность, лежит в общих PostgreSQL и Redis, поэтому клиент с одним
Bearer-токеном обслуживается любой репликой:
```sh
make test BASE_URL=http://localhost:8080 # сквозной сценарий через LB
python3 scripts/lab3/lab3.py check spread # распределение X-Instance-Id
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # отказ одной реплики
scripts/start-replica.sh # вернуть остановленную реплику
```
- `X-Instance-Id` = `INSTANCE_ID` или hostname процесса, стабилен для процесса;
в Docker hostname контейнера — короткий ID, поэтому `scripts/stop-one.sh`
останавливает ровно ту реплику, которую обслужил запрос теста. Тот же заголовок
добавляется к ответам об ошибках, которые формируются фильтром до интерсептора.
- **Остановка (`SIGTERM`)** идёт в порядке «сначала дрейн, потом разбор ресурсов»:
реплика помечается not-ready (проба LB и `/health/ready` начинают отвечать
`503`), `DRAIN_DELAY_MS` ждёт, пока LB её исключит (обнаружение ≈1 s), и лишь
затем закрываются HTTP-сервер, пул PostgreSQL и соединение Redis. Если
полагаться на стандартный порядок Nest (`onModuleDestroy` вызывает закрытие
пулов раньше `beforeApplicationShutdown`), реплика какое-то время остаётся в
ротации уже без ресурсов — это и было причиной явной последовательности в
`src/main.ts`.
- **Проба LB — тот же `/health/ready`**, что и healthcheck контейнера: реплика,
потерявшая обязательную зависимость (свой путь к PostgreSQL или Redis),
выходит из ротации, и трафик уходит на здоровые реплики. Проба с зависимостями
ограничена общим дедлайном `HEALTH_TIMEOUT_MS=400` на реплику; проверка
PostgreSQL (`SELECT 1`) идёт по отдельному соединению, а не из общего пула
бизнес-запросов, а для `PING` Redis стоит `AbortSignal.timeout`, поэтому проба
укладывается в `timeout check 500ms` HAProxy и не реагирует на перегрузку.
Когда недоступна общая для всех зависимость,
неготовыми становятся все реплики, и клиент получает `503` от самого LB: это
честный ответ «готовых узлов нет» вместо маскировки отказа.
- `/health/live` зависимостей не касается: он отвечает `200`, пока жив процесс,
и по нему проверяют, что реплика не упала (в том числе при отказе PG/Redis).
## Идемпотентность отправки сообщения
`POST /api/v1/chats/{chatId}/messages` требует заголовок `Idempotency-Key`
(ASCII `[A-Za-z0-9._:-]{1,128}`). Область уникальности — пользователь + метод +
путь чата + ключ, поэтому одинаковый ключ у разных пользователей или в разных
чатах не конфликтует. Журнал — таблица `idempotency_keys` (миграция 003), то
есть общая для всех реплик.
| Ситуация | Ответ |
|---|---|
| Заголовок отсутствует, пуст или не подходит под шаблон | `400 invalid_request` (до обращения к БД) |
| Первый запрос с ключом | `201` и сообщение; заявка, вставка сообщения, инкремент версии чата и тело ответа записываются **одним оператором SQL** (атомарность обеспечивает сам оператор) |
| Повтор того же тела с тем же ключом | тот же `201` и тот же JSON (включая `id` и `created_at`), новое сообщение не создаётся |
| Другое тело с тем же ключом | `409 conflict` |
| Повтор после `404` (нет доступа к чату) | `404`, ключ не занят: оператор вставляет заявку только при наличии членства, иначе не создаётся ничего |
| Ключ старше `IDEMPOTENCY_TTL_SECONDS` | запись удаляется, ключ считается свободным |
| Одновременные повторы через разные реплики | ровно одно сообщение: заявка берётся `INSERT ... ON CONFLICT DO NOTHING`, повтор читает сохранённый ответ |
Путь записи — один round trip: `messages.createIdempotent` проверяет членство,
занимает ключ (`INSERT ... ON CONFLICT DO NOTHING`), вставляет сообщение, поднимает
`chats.message_version` и сохраняет тело ответа, а повтор читает сохранённый ответ
вместе с повторной проверкой доступа (`idempotency.read`). До оптимизации это были
8 обращений к БД в явной транзакции (см. REPORT.md, раздел «A/B улучшения»).
Отпечаток тела считается по валидированному DTO с фиксированным порядком полей,
поэтому порядок ключей в JSON не влияет на результат. Транзиентные сбои
PostgreSQL (`57014`, `40001`, `40P01`) и обрывы соединения отдаются как
`503 unavailable` и не фиксируются как окончательный результат: клиент может
безопасно повторить запрос с тем же ключом. Просроченные записи удаляются
фоновым проходом (`idempotency.purged` в метриках) под
`pg_try_advisory_xact_lock`, а также вручную: `npm run idempotency:gc`.
## Харнесс экспериментов
Уровни 3/4 и трек 1 обслуживает `../scripts/lab3/lab3.py` (только stdlib) и
профили k6 в `../scripts/load/`: `run`, `sweep`, `track1-extras`, `failover`,
`rolling-update`, `ab`, `analyze`, `watch`, `check`, `quiesce`, `track1`.
Сырые результаты прогонов, манифесты условий измерения и графики складываются в
`../evidence/track1/`. Подробности — в `../REPORT.md` и
`../evidence/README.md`.
## Метрики
`GET /internal/metrics` возвращает `{counters, latency_ms, instance_id, build_id}`: именованные SQL-метки,
операции Redis, `cache_hit`/`cache_miss`/`cache_lock_wait`, `session_get/set/del`,
`request_count` и процентили латентности (буфер ограничен). Деградации
наблюдаемы отдельными счётчиками: `cache_fallback`, `cache_write_error`,
`cache_unlock_error`, `cache_lock_timeout`, `cache_corrupt_entry`,
`database.pool_error`, `database.rollback_error`, `redis.error`, а также
идемпотентность: `idempotency.claim`, `idempotency.replay`, `idempotency.conflict`,
`idempotency.claim_lost`, `idempotency.released`, `idempotency.purged`,
`idempotency.purge_error`, `messages.write`.
Счётчики локальны процессу: при нескольких репликах их нельзя суммировать как
распределённый снимок, а рестарт API обнуляет их (данные PostgreSQL и Redis при
этом не затрагиваются). `instance_id` и `build_id` позволяют сопоставить ответ
конкретной реплике и сборке — этим пользуются rolling update и эксперименты.
+15
View File
@@ -0,0 +1,15 @@
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true,
"assets": [
{
"include": "database/migrations/*.sql",
"outDir": "dist"
}
],
"watchAssets": true
}
}
+10
View File
@@ -0,0 +1,10 @@
{
"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/crates/oxc_linter/src/rules.rs",
"rules": {
"@typescript-eslint/no-explicit-any": "off",
"@typescript-eslint/no-floating-promises": "warn"
},
"env": {
"node": true
}
}
+7401
View File
File diff suppressed because it is too large Load Diff
+66
View File
@@ -0,0 +1,66 @@
{
"name": "app",
"version": "0.0.1",
"description": "",
"author": "",
"private": true,
"license": "UNLICENSED",
"type": "module",
"scripts": {
"build": "nest build",
"deploy": "nest deploy",
"format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
"start": "nest start",
"start:dev": "nest start --watch",
"start:debug": "nest start --debug --watch",
"start:prod": "node dist/main",
"lint": "oxlint src/ test/",
"test": "vitest run",
"test:unit": "vitest run --include 'src/**/*.spec.ts'",
"test:watch": "vitest",
"test:cov": "vitest run --coverage",
"test:debug": "vitest --inspect-brk --no-file-parallelism",
"graph": "npm run build && DATABASE_URL=postgresql://graph-only.invalid/messenger REDIS_URL=redis://graph-only.invalid:6379 tsx scripts/graph-modules.ts",
"test:e2e": "vitest run --config ./vitest.config.e2e.ts",
"test:dependencies": "E2E_DEPENDENCY_FAULTS=1 vitest run --config ./vitest.config.e2e.ts dependency-failures",
"idempotency:gc": "tsx src/messages/idempotency/idempotency-gc.cli.ts"
},
"dependencies": {
"@nestjs/common": "^12.0.1",
"@nestjs/config": "^12.0.0",
"@nestjs/core": "^12.0.1",
"@nestjs/platform-express": "^12.0.1",
"@nestjs/platform-fastify": "^12.0.3",
"argon2": "^0.45.1",
"class-transformer": "^0.5.1",
"class-validator": "^0.15.1",
"date-fns": "^4.4.0",
"fastify": "^5.12.5",
"pg": "^8.23.1",
"redis": "^6.3.0",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"zod": "^4.6.5"
},
"devDependencies": {
"@nestjs/cli": "^12.0.0",
"@nestjs/mau": "^0.2.6",
"@nestjs/schematics": "^12.0.0",
"@nestjs/testing": "^12.0.1",
"@types/express": "^5.0.0",
"@types/node": "^24.0.0",
"@types/pg": "^8.23.1",
"@types/supertest": "^7.0.0",
"@vitest/coverage-v8": "^4.1.2",
"dotenv": "^18.0.5",
"nestjs-spelunker": "^1.3.2",
"oxlint": "^1.58.0",
"prettier": "^3.4.2",
"source-map-support": "^0.5.21",
"supertest": "^7.2.2",
"tsx": "^4.23.15",
"typescript": "^6.0.3",
"vite-tsconfig-paths": "^5.1.4",
"vitest": "^4.1.2"
}
}
+123
View File
@@ -0,0 +1,123 @@
import { mkdir, writeFile } from 'node:fs/promises';
import 'reflect-metadata';
import { SpelunkerModule, type DebuggedTree } from 'nestjs-spelunker';
import { AppModule } from '../dist/app.module.js';
function mermaidId(name: string): string {
return name.replace(/[^a-zA-Z0-9_]/gu, '_');
}
function findDependencyModule(
tree: DebuggedTree[],
dependency: string,
): DebuggedTree | undefined {
return tree.find(
(candidate) =>
candidate.providers.some((item) => item.name === dependency) ||
candidate.controllers.some((item) => item.name === dependency),
);
}
function renderMermaid(tree: DebuggedTree[]): string {
const lines = [
'flowchart LR',
' %% Generated by scripts/graph-modules.ts',
' %% Solid arrows: module imports; dotted arrows: constructor dependencies',
];
const moduleNames = tree.map((module) => module.name);
for (const module of tree) {
const moduleId = mermaidId(module.name);
lines.push(` subgraph ${moduleId}["${module.name}"]`);
for (const provider of module.providers) {
lines.push(
` ${moduleId}_${mermaidId(provider.name)}["provider: ${provider.name}"]`,
);
}
for (const controller of module.controllers) {
lines.push(
` ${moduleId}_${mermaidId(controller.name)}["controller: ${controller.name}"]`,
);
}
lines.push(' end');
}
for (const module of tree) {
for (const imported of module.imports) {
if (moduleNames.includes(imported)) {
lines.push(
` ${mermaidId(module.name)} -->|imports| ${mermaidId(imported)}`,
);
}
}
for (const item of [...module.providers, ...module.controllers]) {
for (const dependency of item.dependencies) {
const targetModule = findDependencyModule(tree, dependency);
if (targetModule) {
const source = `${mermaidId(module.name)}_${mermaidId(item.name)}`;
const target = `${mermaidId(targetModule.name)}_${mermaidId(dependency)}`;
lines.push(` ${source} -.->|injects| ${target}`);
}
}
}
}
return `${lines.join('\n')}\n`;
}
function renderMarkdown(tree: DebuggedTree[], mermaid: string): string {
const lines = [
'# NestJS dependency graph',
'',
'Generated from `AppModule` with `nestjs-spelunker` static module debugging.',
'',
'- Solid arrows: module imports.',
'- Dotted arrows: constructor dependencies.',
'- The generator does not boot PostgreSQL or Redis.',
'',
'```mermaid',
mermaid.trim(),
'```',
'',
'## Module details',
'',
];
for (const module of tree) {
lines.push(
`### ${module.name}`,
'',
`- Imports: ${module.imports.join(', ') || 'none'}`,
);
lines.push(
`- Exports: ${module.exports.map((item) => `${item.name} (${item.type})`).join(', ') || 'none'}`,
);
lines.push('', '| Kind | Name | Dependencies |', '| --- | --- | --- |');
for (const provider of module.providers) {
lines.push(
`| provider | ${provider.name} | ${provider.dependencies.join(', ') || 'none'} |`,
);
}
for (const controller of module.controllers) {
lines.push(
`| controller | ${controller.name} | ${controller.dependencies.join(', ') || 'none'} |`,
);
}
lines.push('');
}
return lines.join('\n');
}
const tree = await SpelunkerModule.debug(AppModule);
const mermaid = renderMermaid(tree);
await mkdir('../docs/architecture', { recursive: true });
await writeFile(
'../docs/architecture/nest-module-details.json',
JSON.stringify(tree, null, 2),
);
await writeFile('../docs/architecture/nest-module-graph.mmd', mermaid);
await writeFile(
'../docs/architecture/nest-dependency-graph.md',
renderMarkdown(tree, mermaid),
);
+33
View File
@@ -0,0 +1,33 @@
import { Module } from '@nestjs/common';
import { AppConfigModule } from './config/app-config.module.js';
import { DatabaseModule } from './database/database.module.js';
import { RedisModule } from './redis/redis.module.js';
import { AuthModule } from './auth/auth.module.js';
import { ChatsModule } from './chats/chats.module.js';
import { HealthModule } from './health/health.module.js';
import { MessagesModule } from './messages/messages.module.js';
import { MetricsModule } from './metrics/metrics.module.js';
import { UsersModule } from './users/users.module.js';
import { APP_FILTER } from '@nestjs/core';
import { ApiExceptionFilter } from './common/errors/api-exception.filter.js';
@Module({
imports: [
AppConfigModule,
DatabaseModule,
RedisModule,
UsersModule,
AuthModule,
HealthModule,
ChatsModule,
MessagesModule,
MetricsModule,
],
providers: [
{
provide: APP_FILTER,
useClass: ApiExceptionFilter,
},
],
})
export class AppModule {}
+79
View File
@@ -0,0 +1,79 @@
import {
BadRequestException,
Body,
Controller,
Delete,
Headers,
HttpCode,
HttpStatus,
Post,
UnauthorizedException,
UseGuards,
} from '@nestjs/common';
import { TextDecoder } from 'node:util';
import { AuthService } from './auth.service.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
const BASE64 =
/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
const BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"';
function basicUnauthorized(): UnauthorizedException {
return new UnauthorizedException({
message: 'Unauthorized',
challenge: BASIC_CHALLENGE,
});
}
function bearerUnauthorized(): UnauthorizedException {
return new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
function parseBasic(value: string | undefined): [string, string] {
if (typeof value !== 'string') throw basicUnauthorized();
const match = /^Basic[ \t]+([^ \t]+)$/iu.exec(value);
if (!match || !BASE64.test(match[1])) throw basicUnauthorized();
const bytes = Buffer.from(match[1], 'base64');
if (bytes.toString('base64') !== match[1]) throw basicUnauthorized();
let decoded: string;
try {
decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
} catch {
throw basicUnauthorized();
}
const separator = decoded.indexOf(':');
if (separator < 1) throw basicUnauthorized();
return [decoded.slice(0, separator), decoded.slice(separator + 1)];
}
@Controller('api/v1/auth/sessions')
export class AuthController {
constructor(private readonly auth: AuthService) {}
@Post()
create(
@Headers('authorization') authorization: string | undefined,
@Body() body: unknown,
) {
const [username, password] = parseBasic(authorization);
if (body !== undefined)
throw new BadRequestException(
'Session creation does not accept a body',
);
return this.auth.createSession(username, password);
}
@Delete('current')
@UseGuards(CurrentUserGuard)
@HttpCode(HttpStatus.NO_CONTENT)
async delete(
@Headers('authorization') authorization: string | undefined,
): Promise<void> {
if (!authorization || !/^Bearer\s+[^\s]+$/iu.test(authorization))
throw bearerUnauthorized();
await this.auth.deleteSession(authorization.slice(7).trim());
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { UsersModule } from '../users/users.module.js';
import { AuthController } from './auth.controller.js';
import { AuthService } from './auth.service.js';
import { SessionRepository } from './session.repository.js';
import { MetricsModule } from '../metrics/metrics.module.js';
@Module({
imports: [UsersModule, DatabaseModule, RedisModule, MetricsModule],
controllers: [AuthController],
providers: [AuthService, SessionRepository],
exports: [AuthService, SessionRepository],
})
export class AuthModule {}
+63
View File
@@ -0,0 +1,63 @@
import {
Injectable,
ServiceUnavailableException,
UnauthorizedException,
} from '@nestjs/common';
import argon2 from 'argon2';
import type { User } from '../users/user.js';
import { UsersService } from '../users/users.service.js';
import { SessionRepository } from './session.repository.js';
export type SessionResponse = {
token: string;
token_type: 'Bearer';
expires_at: string;
user: User;
};
@Injectable()
export class AuthService {
constructor(
private readonly users: UsersService,
private readonly sessions: SessionRepository,
) {}
async createSession(
username: string,
password: string,
): Promise<SessionResponse> {
const storedUser = await this.users.findByUsername(username);
if (
!storedUser ||
!(await argon2.verify(storedUser.password_hash, password))
) {
throw new UnauthorizedException();
}
const user: User = {
id: storedUser.id,
username: storedUser.username,
display_name: storedUser.display_name,
created_at: storedUser.created_at,
};
let session: { token: string; expiresAt: string };
try {
session = await this.sessions.create(user.id);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
return {
token: session.token,
token_type: 'Bearer',
expires_at: session.expiresAt,
user,
};
}
async deleteSession(token: string): Promise<void> {
try {
await this.sessions.delete(token);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
}
}
+35
View File
@@ -0,0 +1,35 @@
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { randomBytes } from 'node:crypto';
import type { AppConfig } from '../config/app-config.schema.js';
import { RedisClient } from '../redis/redis.client.js';
import { MetricsService } from '../metrics/metrics.service.js';
@Injectable()
export class SessionRepository {
constructor(
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
async create(
userId: string,
): Promise<{ token: string; expiresAt: string }> {
const token = randomBytes(32).toString('base64url');
const ttl = this.config.getOrThrow('SESSION_TTL_SECONDS');
const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
this.metrics.increment('session_set');
await this.redis.set(
`session:${token}`,
JSON.stringify({ user_id: userId, expires_at: expiresAt }),
{ EX: ttl },
);
return { token, expiresAt };
}
delete(token: string): Promise<number> {
this.metrics.increment('session_del');
return this.redis.del(`session:${token}`);
}
}
+6
View File
@@ -0,0 +1,6 @@
export type Chat = {
id: string;
title: string;
member_ids: string[];
created_at: string;
};
+49
View File
@@ -0,0 +1,49 @@
import {
BadRequestException,
Body,
Controller,
DefaultValuePipe,
Get,
Param,
ParseIntPipe,
ParseUUIDPipe,
Post,
Query,
UseGuards,
} from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import { ChatsService } from './chats.service.js';
import { CreateChatDto } from './dto/create-chat.dto.js';
import type { User } from '../users/user.js';
@Controller('api/v1/chats')
@UseGuards(CurrentUserGuard)
export class ChatsController {
constructor(private readonly chatsService: ChatsService) {}
@Post()
create(@Body() body: CreateChatDto, @CurrentUser() currentUser: User) {
return this.chatsService.create(body, currentUser);
}
@Get()
list(
@CurrentUser() currentUser: User,
@Query('limit', new DefaultValuePipe(50), new ParseIntPipe())
limit: number,
@Query('cursor') cursor?: string,
) {
if (limit < 1 || limit > 100)
throw new BadRequestException('limit must be between 1 and 100');
return this.chatsService.listForUser(currentUser, limit, cursor);
}
@Get(':chatId')
get(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@CurrentUser() currentUser: User,
) {
return this.chatsService.getForUser(chatId, currentUser);
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
import { UsersModule } from '../users/users.module.js';
import { ChatsController } from './chats.controller.js';
import { ChatsRepository } from './chats.repository.js';
import { ChatsService } from './chats.service.js';
@Module({
imports: [UsersModule, DatabaseModule, RedisModule, MetricsModule],
controllers: [ChatsController],
providers: [ChatsRepository, ChatsService],
exports: [ChatsService],
})
export class ChatsModule {}
+109
View File
@@ -0,0 +1,109 @@
import { BadRequestException, Injectable } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { DatabaseClient } from '../database/database.client.js';
import type { Cursor } from '../common/http/cursor.js';
import type { User } from '../users/user.js';
import type { Chat } from './chat.js';
type ChatRow = {
id: string;
title: string;
created_at: Date | string;
member_ids: string[];
};
function toChat(row: ChatRow): Chat {
return {
id: row.id,
title: row.title,
created_at: new Date(row.created_at).toISOString(),
member_ids: row.member_ids,
};
}
@Injectable()
export class ChatsRepository {
constructor(private readonly database: DatabaseClient) {}
async create(title: string, memberIds: string[]): Promise<Chat> {
const id = randomUUID();
return this.database.withTransaction(async (client) => {
const users = await client.query<{ id: string }>({
name: 'chats.validateMembers',
text: 'SELECT id FROM users WHERE id = ANY($1::uuid[])',
values: [memberIds],
});
if (users.rowCount !== memberIds.length)
throw new BadRequestException('Chat member does not exist');
const inserted = await client.query<ChatRow>({
name: 'chats.insert',
text: 'INSERT INTO chats (id, title) VALUES ($1, $2) RETURNING id, title, created_at',
values: [id, title],
});
for (const memberId of memberIds) {
await client.query({
name: 'chats.insertMember',
text: 'INSERT INTO chat_members (chat_id, user_id) VALUES ($1, $2)',
values: [id, memberId],
});
}
return {
...toChat({ ...inserted.rows[0], member_ids: memberIds }),
member_ids: memberIds,
};
});
}
async findForUser(id: string, user: User): Promise<Chat | undefined> {
const result = await this.database.query<ChatRow>(
'chats.findForUser',
`SELECT c.id, c.title, c.created_at,
COALESCE(array_agg(cm.user_id ORDER BY cm.user_id)
FILTER (WHERE cm.user_id IS NOT NULL), '{}') AS member_ids
FROM chats c
LEFT JOIN chat_members cm ON cm.chat_id = c.id
WHERE c.id = $1
AND EXISTS (
SELECT 1 FROM chat_members own
WHERE own.chat_id = c.id AND own.user_id = $2
)
GROUP BY c.id`,
[id, user.id],
);
return result.rows[0] ? toChat(result.rows[0]) : undefined;
}
async findPageForUser(
user: User,
limit: number,
cursor?: Cursor,
): Promise<{ items: Chat[]; hasMore: boolean }> {
const values: unknown[] = [user.id];
let predicate = '';
if (cursor) {
values.push(cursor.created_at, cursor.id);
predicate =
'AND (c.created_at, c.id) > ($2::timestamptz, $3::uuid)';
}
values.push(limit + 1);
const result = await this.database.query<ChatRow>(
'chats.listForUser',
`SELECT c.id, c.title, c.created_at,
COALESCE(array_agg(cm.user_id ORDER BY cm.user_id)
FILTER (WHERE cm.user_id IS NOT NULL), '{}') AS member_ids
FROM chats c
LEFT JOIN chat_members cm ON cm.chat_id = c.id
WHERE EXISTS (
SELECT 1 FROM chat_members own
WHERE own.chat_id = c.id AND own.user_id = $1
)
${predicate}
GROUP BY c.id ORDER BY c.created_at, c.id LIMIT $${values.length}`,
values,
);
return {
items: result.rows.slice(0, limit).map(toChat),
hasMore: result.rows.length > limit,
};
}
}
+61
View File
@@ -0,0 +1,61 @@
import {
BadRequestException,
Injectable,
NotFoundException,
} from '@nestjs/common';
import { encodeCursor, decodeCursor } from '../common/http/cursor.js';
import type { Page } from '../common/http/page.js';
import type { User } from '../users/user.js';
import type { CreateChatDto } from './dto/create-chat.dto.js';
import type { Chat } from './chat.js';
import { ChatsRepository } from './chats.repository.js';
@Injectable()
export class ChatsService {
constructor(private readonly chatsRepository: ChatsRepository) {}
create(input: CreateChatDto, currentUser: User): Promise<Chat> {
if (!input.member_ids.includes(currentUser.id))
throw new BadRequestException('Current user must be a chat member');
if (new Set(input.member_ids).size !== input.member_ids.length)
throw new BadRequestException('Duplicate chat member');
return this.chatsRepository.create(input.title, input.member_ids);
}
async getForUser(chatId: string, currentUser: User): Promise<Chat> {
const chat = await this.chatsRepository.findForUser(
chatId,
currentUser,
);
if (!chat) throw new NotFoundException();
return chat;
}
async listForUser(
currentUser: User,
limit: number,
cursorValue?: string,
): Promise<Page<Chat>> {
const scope = `chats:${currentUser.id}`;
const cursor = cursorValue
? decodeCursor(cursorValue, scope)
: undefined;
const page = await this.chatsRepository.findPageForUser(
currentUser,
limit,
cursor,
);
const last = page.items.at(-1);
return {
items: page.items,
next_cursor:
page.hasMore && last
? encodeCursor({
scope,
created_at: last.created_at,
id: last.id,
})
: null,
};
}
}
+26
View File
@@ -0,0 +1,26 @@
import {
ArrayMaxSize,
ArrayMinSize,
ArrayUnique,
IsArray,
IsString,
IsUUID,
Matches,
} from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateChatDto {
@IsString()
@CodePointLength(1, 100)
@Matches(/\S/, {
message: 'title must contain a non-whitespace character',
})
title: string;
@IsArray()
@ArrayMinSize(1)
@ArrayMaxSize(100)
@ArrayUnique()
@IsUUID('4', { each: true })
member_ids: string[];
}
@@ -0,0 +1,10 @@
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import type { User } from '../../users/user.js';
import { FastifyRequest } from 'fastify';
export const CurrentUser = createParamDecorator(
(_data: unknown, context: ExecutionContext): User => {
const request = context.switchToHttp().getRequest<FastifyRequest>();
return request.currentUser!;
},
);
+85
View File
@@ -0,0 +1,85 @@
import {
CanActivate,
ExecutionContext,
Injectable,
ServiceUnavailableException,
UnauthorizedException,
} from '@nestjs/common';
import type { FastifyRequest } from 'fastify';
import type { User } from '../../users/user.js';
import { RedisClient } from '../../redis/redis.client.js';
import { UsersService } from '../../users/users.service.js';
import { MetricsService } from '../../metrics/metrics.service.js';
@Injectable()
export class CurrentUserGuard implements CanActivate {
constructor(
private readonly redis: RedisClient,
private readonly users: UsersService,
private readonly metrics: MetricsService,
) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest<FastifyRequest>();
const authorization = request.headers.authorization;
if (
typeof authorization !== 'string' ||
!/^Bearer\s+[^\s]+$/u.test(authorization)
) {
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
let session: string | null;
try {
this.metrics.increment('session_get');
session = await this.redis.get(
`session:${authorization.slice(7).trim()}`,
);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
if (!session)
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
let userId: string;
try {
const parsed: unknown = JSON.parse(session);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('user_id' in parsed) ||
typeof parsed.user_id !== 'string' ||
!('expires_at' in parsed) ||
typeof parsed.expires_at !== 'string' ||
!/^(?:\d{4})-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u.test(
parsed.expires_at,
)
)
throw new Error('invalid session');
const expiresAt = Date.parse(parsed.expires_at);
if (!Number.isFinite(expiresAt) || Date.now() >= expiresAt)
throw new Error('expired session');
userId = parsed.user_id;
} catch {
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
let user: User | undefined;
try {
user = await this.users.findById(userId);
} catch {
throw new ServiceUnavailableException(
'Authentication service unavailable',
);
}
if (!user) throw new UnauthorizedException();
request.currentUser = user;
return true;
}
}
+7
View File
@@ -0,0 +1,7 @@
export type ApiErrorBody = {
error: {
code: string;
message: string;
request_id: string;
};
};
@@ -0,0 +1,168 @@
import {
ArgumentsHost,
Catch,
ExceptionFilter,
HttpException,
HttpStatus,
Logger,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { randomUUID } from 'node:crypto';
import type { AppConfig } from '../../config/app-config.schema.js';
import { resolveInstanceId } from '../../config/instance-id.js';
import type { ApiErrorBody } from './api-error.js';
type RequestWithId = { requestId?: string; method?: string; url?: string };
type ExceptionBody = { message?: unknown; challenge?: unknown };
// Connection/session loss codes reported by node-postgres and the network layer.
const UNAVAILABLE_ERROR_CODES: Record<string, true> = {
ECONNREFUSED: true,
ECONNRESET: true,
ENOTFOUND: true,
ETIMEDOUT: true,
EPIPE: true,
'08000': true,
'08001': true,
'08003': true,
'08004': true,
'08006': true,
'57P01': true,
'57P02': true,
'57P03': true,
'53300': true,
// Transient aborts: the statement was cancelled by statement_timeout, the
// transaction was rolled back by a serialization failure or a deadlock. The
// work was never confirmed, so callers see a retryable 503 instead of an
// internal error. Without this, such an abort would be recorded as the final
// result of an idempotent operation.
'57014': true,
'40001': true,
'40P01': true,
};
// Some driver failures carry no `code` at all: node-postgres raises plain errors
// when a connection dies or its pool attempt times out, and node-redis reports a
// closed socket the same way. Without these patterns a stopped database would
// surface as an internal fault instead of a bounded outage.
const UNAVAILABLE_ERROR_MESSAGES = [
'Connection terminated unexpectedly',
'Connection terminated due to connection timeout',
'timeout exceeded when trying to connect',
'Client has encountered a connection error and is not queryable',
'Socket closed unexpectedly',
'Connection is closed',
];
function isDependencyOutage(exception: unknown): boolean {
if (typeof exception !== 'object' || exception === null) return false;
const code = (exception as { code?: unknown }).code;
if (typeof code === 'string' && UNAVAILABLE_ERROR_CODES[code] === true)
return true;
const message = (exception as { message?: unknown }).message;
return (
typeof message === 'string' &&
UNAVAILABLE_ERROR_MESSAGES.some((pattern) => message.includes(pattern))
);
}
function errorCodeForStatus(status: number): string {
const codes: Record<number, string> = {
[HttpStatus.BAD_REQUEST]: 'invalid_request',
[HttpStatus.UNAUTHORIZED]: 'unauthorized',
[HttpStatus.NOT_FOUND]: 'not_found',
[HttpStatus.CONFLICT]: 'conflict',
[HttpStatus.PAYLOAD_TOO_LARGE]: 'payload_too_large',
[HttpStatus.UNSUPPORTED_MEDIA_TYPE]: 'unsupported_media_type',
[HttpStatus.TOO_MANY_REQUESTS]: 'rate_limited',
[HttpStatus.SERVICE_UNAVAILABLE]: 'unavailable',
};
return codes[status] ?? 'internal_error';
}
@Catch()
export class ApiExceptionFilter implements ExceptionFilter {
private readonly logger = new Logger(ApiExceptionFilter.name);
// Guards and pipes run before interceptors, so an error response may be the
// first thing the filter writes: it must carry the replica identity too.
private readonly instanceId: string;
constructor(
private readonly adapterHost: HttpAdapterHost,
config: ConfigService<AppConfig>,
) {
this.instanceId = resolveInstanceId(config);
}
catch(exception: unknown, host: ArgumentsHost): void {
const http = host.switchToHttp();
const request = http.getRequest<RequestWithId>();
const response = http.getResponse<unknown>();
const adapter = this.adapterHost.httpAdapter;
const requestId = request.requestId ?? randomUUID();
request.requestId = requestId;
let status = HttpStatus.INTERNAL_SERVER_ERROR;
let message = 'Internal server error';
let challenge: string | undefined;
if (exception instanceof HttpException) {
status = exception.getStatus();
const body = exception.getResponse();
const details: ExceptionBody =
typeof body === 'object' && body !== null
? (body as ExceptionBody)
: {};
const rawMessage =
'message' in details ? details.message : undefined;
challenge =
typeof details.challenge === 'string'
? details.challenge
: undefined;
message = Array.isArray(rawMessage)
? rawMessage.join('; ')
: typeof rawMessage === 'string'
? rawMessage
: 'Request failed';
if (status === HttpStatus.NOT_FOUND) message = 'Resource not found';
if (status >= HttpStatus.INTERNAL_SERVER_ERROR)
message =
status === HttpStatus.SERVICE_UNAVAILABLE
? 'Service unavailable'
: 'Internal server error';
} else if (isDependencyOutage(exception)) {
// A dropped dependency is a bounded outage, not an internal fault.
status = HttpStatus.SERVICE_UNAVAILABLE;
message = 'Service unavailable';
this.logger.warn(
`Dependency outage on ${request.method ?? ''} ${request.url ?? ''}: ${exception instanceof Error ? exception.message : 'unknown error'}`,
);
} else {
this.logger.error(
`Unhandled exception on ${request.method ?? ''} ${request.url ?? ''}`,
exception instanceof Error
? exception.stack
: String(exception),
);
}
if (status === HttpStatus.UNAUTHORIZED) {
const authChallenge =
challenge ??
(request.method === 'POST' &&
request.url?.startsWith('/api/v1/auth/sessions')
? 'Basic realm="messenger", charset="UTF-8"'
: 'Bearer realm="messenger"');
adapter.setHeader(response, 'WWW-Authenticate', authChallenge);
}
adapter.setHeader(response, 'X-Request-Id', requestId);
adapter.setHeader(response, 'X-Instance-Id', this.instanceId);
const payload: ApiErrorBody = {
error: {
code: errorCodeForStatus(status),
message,
request_id: requestId,
},
};
adapter.reply(response, payload, status);
}
}
+85
View File
@@ -0,0 +1,85 @@
import { BadRequestException } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { describe, expect, it } from 'vitest';
import { decodeCursor, encodeCursor } from './cursor.js';
const scope = 'messages:6f1c2a3e-1111-4222-8333-444455556666';
function encode(createdAt: string, cursorScope = scope): string {
return encodeCursor({
scope: cursorScope,
created_at: createdAt,
id: randomUUID(),
});
}
describe('decodeCursor', () => {
it('accepts valid instants and normalizes them to canonical milliseconds', () => {
const accepted: Array<[string, string]> = [
['2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z'],
['2026-01-01T00:00:00Z', '2026-01-01T00:00:00.000Z'],
['2026-01-01T00:00:00.999999Z', '2026-01-01T00:00:00.999Z'],
['2024-02-29T23:59:59.000Z', '2024-02-29T23:59:59.000Z'],
['2026-12-31T23:59:59.999Z', '2026-12-31T23:59:59.999Z'],
];
for (const [createdAt, expected] of accepted) {
const decoded = decodeCursor(encode(createdAt), scope);
expect(decoded.created_at).toBe(expected);
expect(decoded.scope).toBe(scope);
}
});
it('rejects calendar dates that the platform parser rolls over', () => {
// 2026-02-31 would silently become 2026-03-03 and then fail inside SQL.
for (const createdAt of [
'2026-02-31T00:00:00.000Z',
'2025-02-29T00:00:00.000Z',
'2026-04-31T00:00:00.000Z',
'2026-06-31T12:00:00.000Z',
]) {
expect(() => decodeCursor(encode(createdAt), scope)).toThrow(
BadRequestException,
);
}
});
it('rejects out-of-range and malformed timestamps', () => {
for (const createdAt of [
'2026-01-01T24:00:00.000Z',
'2026-01-01T00:00:60.000Z',
'2026-13-01T00:00:00.000Z',
'2026-00-01T00:00:00.000Z',
'2026-01-01T00:00:00',
'2026-01-01T00:00:00+02:00',
'2026-1-1T00:00:00.000Z',
'2026-01-01',
'not-a-timestamp',
]) {
expect(() => decodeCursor(encode(createdAt), scope)).toThrow(
BadRequestException,
);
}
});
it('rejects a cursor from another scope, a malformed id, and non-cursor input', () => {
expect(() =>
decodeCursor(
encode('2026-01-01T00:00:00.000Z', 'messages:other'),
scope,
),
).toThrow(BadRequestException);
expect(() =>
decodeCursor(
encodeCursor({
scope,
created_at: '2026-01-01T00:00:00.000Z',
id: 'not-a-uuid',
}),
scope,
),
).toThrow(BadRequestException);
expect(() => decodeCursor('not-a-cursor', scope)).toThrow(
BadRequestException,
);
});
});
+54
View File
@@ -0,0 +1,54 @@
import { BadRequestException } from '@nestjs/common';
import { isValid, parseISO } from 'date-fns';
export type Cursor = {
scope: string;
created_at: string;
id: string;
};
// Format check for the canonical API shape: `Date.prototype.toISOString()` with
// optional fractional seconds. Explicit ranges reject values such as 24:00:00.
// Calendar validity (2026-02-31, 2025-02-29, 2026-04-31) is checked by
// date-fns `parseISO`, which refuses impossible dates that the platform parser
// would silently roll over into another day.
const CURSOR_TIMESTAMP =
/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?Z$/u;
export function encodeCursor(cursor: Cursor): string {
return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
}
export function decodeCursor(value: string, expectedScope: string): Cursor {
try {
const parsed: unknown = JSON.parse(
Buffer.from(value, 'base64url').toString('utf8'),
);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('scope' in parsed) ||
!('created_at' in parsed) ||
!('id' in parsed) ||
typeof parsed.scope !== 'string' ||
typeof parsed.created_at !== 'string' ||
typeof parsed.id !== 'string' ||
parsed.scope !== expectedScope ||
!/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu.test(
parsed.id,
) ||
!CURSOR_TIMESTAMP.test(parsed.created_at)
)
throw new Error('invalid cursor');
const instant = parseISO(parsed.created_at);
if (!isValid(instant)) throw new Error('invalid cursor');
return {
scope: parsed.scope,
created_at: instant.toISOString(),
id: parsed.id,
};
} catch {
throw new BadRequestException('Invalid cursor');
}
}
+4
View File
@@ -0,0 +1,4 @@
export type Page<T> = {
items: T[];
next_cursor: string | null;
};
@@ -0,0 +1,59 @@
import {
CallHandler,
ExecutionContext,
Injectable,
NestInterceptor,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { HttpAdapterHost } from '@nestjs/core';
import { randomUUID } from 'node:crypto';
import { finalize, Observable } from 'rxjs';
import type { AppConfig } from '../../config/app-config.schema.js';
import { resolveInstanceId } from '../../config/instance-id.js';
import { MetricsService } from '../../metrics/metrics.service.js';
type RequestWithId = { requestId?: string };
@Injectable()
export class RequestIdInterceptor implements NestInterceptor {
// Resolved once: the identity must be stable for the whole process lifetime,
// otherwise a client cannot tell whether it moved to another replica.
private readonly instanceId: string;
constructor(
private readonly adapterHost: HttpAdapterHost,
private readonly metrics: MetricsService,
config: ConfigService<AppConfig>,
) {
this.instanceId = resolveInstanceId(config);
}
intercept(
context: ExecutionContext,
next: CallHandler,
): Observable<unknown> {
const request = context.switchToHttp().getRequest<RequestWithId>();
const response = context.switchToHttp().getResponse<unknown>();
const requestId = randomUUID();
const startedAt = performance.now();
request.requestId = requestId;
this.adapterHost.httpAdapter.setHeader(
response,
'X-Request-Id',
requestId,
);
this.adapterHost.httpAdapter.setHeader(
response,
'X-Instance-Id',
this.instanceId,
);
this.metrics.increment('request_count');
return next
.handle()
.pipe(
finalize(() =>
this.metrics.observeLatency(performance.now() - startedAt),
),
);
}
}
@@ -0,0 +1,43 @@
import { validate } from 'class-validator';
import { describe, expect, it } from 'vitest';
import { CodePointLength } from './code-point-length.js';
class Sample {
@CodePointLength(3, 5)
value!: string;
}
async function fails(value: unknown): Promise<boolean> {
const sample = new Sample();
(sample as { value: unknown }).value = value;
const errors = await validate(sample);
return errors.length > 0;
}
describe('CodePointLength', () => {
it('counts Unicode code points instead of UTF-16 units', async () => {
// '🔐' is one code point but two UTF-16 units.
expect(await fails('🔐🔐')).toBe(true);
expect(await fails('🔐🔐🔐')).toBe(false);
expect(await fails('🔐🔐🔐🔐🔐')).toBe(false);
expect(await fails('🔐🔐🔐🔐🔐🔐')).toBe(true);
// Combining marks are separate code points, not grapheme clusters:
// three 'é' sequences are six code points and exceed the maximum.
expect(await fails('e\u0301e\u0301')).toBe(false);
expect(await fails('e\u0301e\u0301e\u0301')).toBe(true);
});
it('applies to BMP text boundaries', async () => {
expect(await fails('ab')).toBe(true);
expect(await fails('abc')).toBe(false);
expect(await fails('abcde')).toBe(false);
expect(await fails('abcdef')).toBe(true);
});
it('rejects empty and non-string values', async () => {
expect(await fails('')).toBe(true);
expect(await fails(undefined)).toBe(true);
expect(await fails(12345)).toBe(true);
expect(await fails(['a', 'b', 'c'])).toBe(true);
});
});
@@ -0,0 +1,38 @@
import {
registerDecorator,
ValidatorConstraint,
type ValidationArguments,
type ValidatorConstraintInterface,
} from 'class-validator';
// JSON Schema (and the course contract) measure string lengths in Unicode code
// points, while String.prototype.length counts UTF-16 units: one emoji outside
// the BMP is two units. `@Length` therefore accepted an 11-emoji password
// (22 units) and rejected 4000 emoji (8000 units), so these fields use an
// explicit code-point validator instead.
@ValidatorConstraint({ name: 'codePointLength', async: false })
class CodePointLengthConstraint implements ValidatorConstraintInterface {
validate(value: unknown, args: ValidationArguments): boolean {
const [min, max] = args.constraints as [number, number];
if (typeof value !== 'string') return false;
const length = [...value].length;
return length >= min && length <= max;
}
defaultMessage(args: ValidationArguments): string {
const [min, max] = args.constraints as [number, number];
return `${args.property} must be between ${min} and ${max} code points`;
}
}
export function CodePointLength(min: number, max: number): PropertyDecorator {
return (target, propertyKey) => {
registerDecorator({
name: 'codePointLength',
target: target.constructor,
propertyName: String(propertyKey),
constraints: [min, max],
validator: CodePointLengthConstraint,
});
};
}
+16
View File
@@ -0,0 +1,16 @@
import { Global, Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { parseAppConfig } from './app-config.schema.js';
@Global()
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
cache: true,
validate: parseAppConfig,
}),
],
exports: [ConfigModule],
})
export class AppConfigModule {}
+101
View File
@@ -0,0 +1,101 @@
import { readFileSync } from 'node:fs';
import { z } from 'zod';
function numeric(
name: string,
minimum: number,
maximum: number | undefined,
fallback: number,
) {
let schema = z
.number({ message: `${name} must be a number` })
.int()
.min(minimum);
if (maximum !== undefined) schema = schema.max(maximum);
return z.preprocess(
(value) =>
typeof value === 'string' && value.trim() !== ''
? Number(value)
: value,
schema.default(fallback),
);
}
function requiredString(name: string) {
return z
.string({ message: `${name} is required` })
.min(1, `${name} is required`);
}
export const appConfigSchema = z
.object({
APP_HOST: z.string().min(1).default('0.0.0.0'),
APP_PORT: numeric('APP_PORT', 1, 65535, 8080),
APP_ENV: z.string().min(1).default('lab'),
SESSION_TTL_SECONDS: numeric('SESSION_TTL_SECONDS', 2, undefined, 3600),
DATABASE_URL: requiredString('DATABASE_URL'),
REDIS_URL: requiredString('REDIS_URL'),
DATABASE_POOL_MAX: numeric('DATABASE_POOL_MAX', 1, 100, 10),
DATABASE_CONNECTION_TIMEOUT_MS: numeric(
'DATABASE_CONNECTION_TIMEOUT_MS',
1,
undefined,
5000,
),
DATABASE_STATEMENT_TIMEOUT_MS: numeric(
'DATABASE_STATEMENT_TIMEOUT_MS',
1,
undefined,
5000,
),
// Бюджет зависимостей в /health/ready: LB проверяет ту же ручку, поэтому
// проба готовности обязана уложиться в timeout check HAProxy (500 ms).
HEALTH_TIMEOUT_MS: numeric('HEALTH_TIMEOUT_MS', 1, undefined, 400),
CACHE_TTL_SECONDS: numeric('CACHE_TTL_SECONDS', 1, undefined, 30),
CACHE_MODE: z.enum(['protected', 'naive']).default('protected'),
CACHE_LOCK_TTL_MS: numeric('CACHE_LOCK_TTL_MS', 1, undefined, 1000),
CACHE_MISS_DELAY_MS: numeric('CACHE_MISS_DELAY_MS', 0, undefined, 0),
METRICS_TOKEN: z.string().min(1).optional(),
DRAIN_DELAY_MS: numeric('DRAIN_DELAY_MS', 0, undefined, 5000),
INSTANCE_ID: z.string().min(1).optional(),
IDEMPOTENCY_TTL_SECONDS: numeric(
'IDEMPOTENCY_TTL_SECONDS',
60,
undefined,
86400,
),
})
.strip();
export type AppConfig = z.infer<typeof appConfigSchema>;
export type AppConfigKey = keyof AppConfig;
function resolveSecret(
raw: Record<string, unknown>,
key: 'DATABASE_URL' | 'REDIS_URL',
): unknown {
const fileKey = `${key}_FILE`;
const path = raw[fileKey];
if (typeof path !== 'string' || path.length === 0) return raw[key];
try {
const value = readFileSync(path, 'utf8').trim();
if (value.length === 0)
throw new Error(`${fileKey} contains an empty value`);
return value;
} catch (error) {
if (
error instanceof Error &&
error.message.includes('contains an empty value')
)
throw error;
throw new Error(`${fileKey} could not be read`);
}
}
export function parseAppConfig(raw: Record<string, unknown>): AppConfig {
return appConfigSchema.parse({
...raw,
DATABASE_URL: resolveSecret(raw, 'DATABASE_URL'),
REDIS_URL: resolveSecret(raw, 'REDIS_URL'),
});
}
+14
View File
@@ -0,0 +1,14 @@
import { randomUUID } from 'node:crypto';
import { hostname } from 'node:os';
import type { ConfigService } from '@nestjs/config';
import type { AppConfig } from './app-config.schema.js';
// A replica must be identifiable from the outside. Inside Docker the hostname is
// the short container ID, so X-Instance-Id can be mapped back to exactly one
// container; INSTANCE_ID exists for platforms where that mapping is not useful.
export function resolveInstanceId(config: ConfigService<AppConfig>): string {
const configured = config.get('INSTANCE_ID');
if (configured) return configured;
const host = hostname();
return host.length > 0 ? host : randomUUID();
}
+90
View File
@@ -0,0 +1,90 @@
import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import pg from 'pg';
import { MetricsService } from '../metrics/metrics.service.js';
import type { AppConfig } from '../config/app-config.schema.js';
@Injectable()
export class DatabaseClient implements OnModuleDestroy {
readonly pool: pg.Pool;
private readonly healthPool: pg.Pool;
private readonly logger = new Logger(DatabaseClient.name);
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {
this.pool = new pg.Pool({
connectionString: this.config.getOrThrow('DATABASE_URL'),
max: this.config.getOrThrow('DATABASE_POOL_MAX'),
connectionTimeoutMillis: this.config.getOrThrow(
'DATABASE_CONNECTION_TIMEOUT_MS',
),
statement_timeout: this.config.getOrThrow(
'DATABASE_STATEMENT_TIMEOUT_MS',
),
});
// Idle clients emit 'error' on the pool when the database drops; without a
// listener Node treats it as uncaught and terminates the process.
this.pool.on('error', (error: Error) => {
this.metrics.increment('database.pool_error');
this.logger.warn(`PostgreSQL pool error: ${error.message}`);
});
// Проба готовности не должна стоять в очереди за бизнес-запросами: занятый
// общий пул — это перегрузка, а не потеря зависимости.
this.healthPool = new pg.Pool({
connectionString: this.config.getOrThrow('DATABASE_URL'),
max: 1,
idleTimeoutMillis: 0,
connectionTimeoutMillis: this.config.getOrThrow('HEALTH_TIMEOUT_MS'),
query_timeout: this.config.getOrThrow('HEALTH_TIMEOUT_MS'),
});
this.healthPool.on('error', (error: Error) => {
this.metrics.increment('database.health_pool_error');
this.logger.warn(`PostgreSQL health connection error: ${error.message}`);
});
}
query<T extends pg.QueryResultRow = pg.QueryResultRow>(
label: string,
text: string,
values: readonly unknown[] = [],
): Promise<pg.QueryResult<T>> {
this.metrics.increment(label);
return this.pool.query<T>({ text, values: [...values] });
}
async health(): Promise<void> {
this.metrics.increment('health.database');
await this.healthPool.query('SELECT 1');
}
async withTransaction<T>(
work: (client: pg.PoolClient) => Promise<T>,
): Promise<T> {
const client = await this.pool.connect();
try {
await client.query('BEGIN');
const result = await work(client);
await client.query('COMMIT');
return result;
} catch (error) {
try {
await client.query('ROLLBACK');
} catch (rollbackError) {
this.metrics.increment('database.rollback_error');
this.logger.warn(
`Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : 'unknown error'}`,
);
}
// Callers must see the operation error, not the rollback error.
throw error;
} finally {
client.release();
}
}
async onModuleDestroy(): Promise<void> {
await Promise.all([this.pool.end(), this.healthPool.end()]);
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsModule } from '../metrics/metrics.module.js';
import { DatabaseClient } from './database.client.js';
@Module({
imports: [MetricsModule],
providers: [DatabaseClient],
exports: [DatabaseClient],
})
export class DatabaseModule {}
+63
View File
@@ -0,0 +1,63 @@
import { readdir, readFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { DatabaseClient } from './database.client.js';
import { MetricsService } from '../metrics/metrics.service.js';
import { parseAppConfig } from '../config/app-config.schema.js';
const migrationsDirectory = join(
dirname(fileURLToPath(import.meta.url)),
'migrations',
);
async function migrationFiles(): Promise<string[]> {
const files = await readdir(migrationsDirectory);
return files.filter((file) => /^\d+_.+\.sql$/u.test(file)).sort();
}
export async function runMigrations(database: DatabaseClient): Promise<void> {
await database.query(
'migrations.ensure_table',
`CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
)`,
);
for (const version of await migrationFiles()) {
await database.withTransaction(async (client) => {
const applied = await client.query({
text: 'SELECT version FROM schema_migrations WHERE version = $1',
values: [version],
});
if (applied.rowCount) return;
const sql = await readFile(
join(migrationsDirectory, version),
'utf8',
);
await client.query(sql);
await client.query({
text: 'INSERT INTO schema_migrations (version) VALUES ($1)',
values: [version],
});
});
}
}
async function main(): Promise<void> {
const config = parseAppConfig(process.env as Record<string, unknown>);
const database = new DatabaseClient(
{
getOrThrow: (key: keyof typeof config) => config[key],
} as never,
new MetricsService(),
);
try {
await runMigrations(database);
} finally {
await database.onModuleDestroy();
}
}
if (process.argv[1] === fileURLToPath(import.meta.url)) await main();
@@ -0,0 +1,41 @@
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS users (
id uuid PRIMARY KEY,
username text NOT NULL UNIQUE,
display_name text NOT NULL,
password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS chats (
id uuid PRIMARY KEY,
title text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
message_version bigint NOT NULL DEFAULT 0
);
CREATE TABLE IF NOT EXISTS chat_members (
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
PRIMARY KEY (chat_id, user_id)
);
CREATE TABLE IF NOT EXISTS messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
sender_id uuid NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
text text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT messages_sender_member_fk
FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
ON DELETE RESTRICT
);
CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx
ON messages (chat_id, created_at, id);
CREATE INDEX IF NOT EXISTS chat_members_user_chat_idx
ON chat_members (user_id, chat_id);
@@ -0,0 +1,5 @@
-- HTTP timestamps and keyset cursors use JavaScript millisecond precision.
-- Store the same precision so a returned cursor cannot point before its own row.
ALTER TABLE users ALTER COLUMN created_at TYPE timestamptz(3);
ALTER TABLE chats ALTER COLUMN created_at TYPE timestamptz(3);
ALTER TABLE messages ALTER COLUMN created_at TYPE timestamptz(3);
@@ -0,0 +1,20 @@
-- Shared idempotency ledger for POST /api/v1/chats/{id}/messages.
-- The key scope is (user, method, path, key): the same key from another user or
-- another chat is independent, as the contract requires.
-- claim + response are committed in one transaction, so a committed row always
-- carries status_code and response_body (there is no "poisoned" intermediate state).
CREATE TABLE IF NOT EXISTS idempotency_keys (
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
method text NOT NULL,
path text NOT NULL,
key text NOT NULL,
request_fingerprint text NOT NULL,
status_code integer,
response_body jsonb,
message_id uuid,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (user_id, method, path, key)
);
CREATE INDEX IF NOT EXISTS idempotency_keys_created_at_idx
ON idempotency_keys (created_at);
@@ -0,0 +1,9 @@
-- Instrumentation for the scaling experiments. pg_stat_statements only works
-- when the server is started with shared_preload_libraries=pg_stat_statements
-- (compose.yaml does that); without the preload the CREATE fails with a plain
-- notice, so a database started without the preload still migrates cleanly.
DO $$ BEGIN
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
EXCEPTION WHEN OTHERS THEN
RAISE NOTICE 'pg_stat_statements unavailable: %', SQLERRM;
END $$;
+17
View File
@@ -0,0 +1,17 @@
import { Controller, Get } from '@nestjs/common';
import { HealthService } from './health.service.js';
@Controller('health')
export class HealthController {
constructor(private readonly healthService: HealthService) {}
@Get('live')
getLive() {
return this.healthService.getLiveness();
}
@Get('ready')
async getReady() {
return this.healthService.getReadiness();
}
}
+12
View File
@@ -0,0 +1,12 @@
import { Module } from '@nestjs/common';
import { HealthController } from './health.controller.js';
import { HealthService } from './health.service.js';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
@Module({
imports: [DatabaseModule, RedisModule],
controllers: [HealthController],
providers: [HealthService],
})
export class HealthModule {}
+91
View File
@@ -0,0 +1,91 @@
import { describe, expect, it, vi } from 'vitest';
import { ServiceUnavailableException } from '@nestjs/common';
import { HealthService } from './health.service.js';
describe('HealthService', () => {
it('reports liveness and readiness when dependencies are healthy', async () => {
const database = { health: vi.fn().mockResolvedValue(undefined) };
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const service = new HealthService(
database as never,
redis as never,
{ getOrThrow: () => 50 } as never,
);
expect(service.getLiveness()).toEqual({ status: 'ok' });
await expect(service.getReadiness()).resolves.toEqual({ status: 'ok' });
});
it('rejects readiness when a dependency is unavailable', async () => {
const database = {
health: vi.fn().mockRejectedValue(new Error('down')),
};
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const service = new HealthService(
database as never,
redis as never,
{ getOrThrow: () => 50 } as never,
);
await expect(service.getReadiness()).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
});
it('rejects readiness when Redis alone is unavailable', async () => {
const database = { health: vi.fn().mockResolvedValue(undefined) };
const redis = {
health: vi.fn().mockRejectedValue(new Error('down')),
};
const service = new HealthService(
database as never,
redis as never,
{ getOrThrow: () => 50 } as never,
);
await expect(service.getReadiness()).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
});
it('keeps liveness healthy while draining', async () => {
const service = new HealthService(
{ health: vi.fn() } as never,
{ health: vi.fn() } as never,
{ getOrThrow: () => 50 } as never,
);
service.setDraining();
expect(service.getLiveness()).toEqual({ status: 'ok' });
await expect(service.getReadiness()).rejects.toThrow(
'Service is shutting down',
);
});
it('answers not-ready during drain without probing dependencies', async () => {
const database = { health: vi.fn().mockResolvedValue(undefined) };
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const service = new HealthService(
database as never,
redis as never,
{ getOrThrow: () => 50 } as never,
);
service.setDraining();
await expect(service.getReadiness()).rejects.toThrow(
'Service is shutting down',
);
// Дрейн обязан отвечать сразу: проба LB не должна ждать зависимости,
// когда реплика уже выходит из ротации.
expect(database.health).not.toHaveBeenCalled();
expect(redis.health).not.toHaveBeenCalled();
});
it('fails readiness within the budget when a dependency hangs', async () => {
const database = { health: vi.fn(() => new Promise<void>(() => {})) };
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const service = new HealthService(
database as never,
redis as never,
{ getOrThrow: () => 20 } as never,
);
await expect(service.getReadiness()).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
});
});
+60
View File
@@ -0,0 +1,60 @@
import {
Global,
Injectable,
Module,
ServiceUnavailableException,
} from '@nestjs/common';
import { DatabaseClient } from '../database/database.client.js';
import { RedisClient } from '../redis/redis.client.js';
import { ConfigService } from '@nestjs/config';
import type { AppConfig } from '../config/app-config.schema.js';
@Injectable()
export class HealthService {
private ready = true;
constructor(
private readonly database: DatabaseClient,
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
) {}
getLiveness() {
return { status: 'ok' as const };
}
async getReadiness() {
if (!this.ready)
throw new ServiceUnavailableException('Service is shutting down');
const dependencies = Promise.all([
this.database.health(),
this.redis.health(),
]);
// Поздний отказ после дедлайна не должен стать unhandled rejection.
dependencies.catch(() => undefined);
let timer: NodeJS.Timeout | undefined;
const deadline = new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new Error('readiness budget exceeded')),
this.config.getOrThrow('HEALTH_TIMEOUT_MS'),
);
});
try {
await Promise.race([dependencies, deadline]);
} catch {
throw new ServiceUnavailableException('Dependencies unavailable');
} finally {
clearTimeout(timer);
}
return { status: 'ok' as const };
}
// Called on SIGTERM before the drain delay: the replica turns not-ready while
// it finishes in-flight requests, so the load balancer stops probing it
// successfully and removes it from rotation. The delay itself lives in
// main.ts, because Nest destroys providers (closing the pools) before this
// class could serve anyone.
setDraining() {
this.ready = false;
}
}
@Global()
@Module({ providers: [HealthService], exports: [HealthService] })
export class HealthServiceModule {}
+63
View File
@@ -0,0 +1,63 @@
import { NestFactory } from '@nestjs/core';
import { HttpAdapterHost } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { ValidationPipe } from '@nestjs/common';
import {
FastifyAdapter,
NestFastifyApplication,
} from '@nestjs/platform-fastify';
import { AppModule } from './app.module.js';
import { HealthService } from './health/health.service.js';
import { MetricsService } from './metrics/metrics.service.js';
import { RequestIdInterceptor } from './common/http/request-id.interceptor.js';
async function bootstrap(): Promise<void> {
const app = await NestFactory.create<NestFastifyApplication>(
AppModule,
new FastifyAdapter({ logger: true }),
);
app.useGlobalInterceptors(
new RequestIdInterceptor(
app.get(HttpAdapterHost),
app.get(MetricsService),
app.get(ConfigService),
),
);
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
}),
);
const config = app.get(ConfigService);
const port = config.getOrThrow<number>('APP_PORT');
const host = config.getOrThrow<string>('APP_HOST');
await app.listen(port, host);
// Drain before teardown. Nest's own shutdown sequence destroys providers
// (closing the database pool and Redis) before `beforeApplicationShutdown`
// runs, so relying on it would keep the replica listed in the load balancer
// while it can no longer serve: SIGTERM must first turn the replica
// not-ready for the LB probe, then wait DRAIN_DELAY_MS, and only then close
// the server and the pools.
const health = app.get(HealthService);
const drainDelayMs = config.getOrThrow<number>('DRAIN_DELAY_MS');
let shuttingDown = false;
const shutdown = async (): Promise<void> => {
if (shuttingDown) return;
shuttingDown = true;
health.setDraining();
if (drainDelayMs > 0)
await new Promise<void>((resolve) => setTimeout(resolve, drainDelayMs));
await app.close();
process.exit(0);
};
for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const)
process.once(signal, () => {
void shutdown();
});
}
await bootstrap();
+37
View File
@@ -0,0 +1,37 @@
import { ConfigService } from '@nestjs/config';
import { describe, expect, it, vi } from 'vitest';
import { MetricsService } from '../../metrics/metrics.service.js';
import { MessagesCacheService } from './messages-cache.service.js';
describe('MessagesCacheService metrics', () => {
it('records a miss and a hit for a protected page fill', async () => {
const metrics = new MetricsService();
const page = { items: [], next_cursor: null };
const redis = {
get: vi
.fn()
.mockResolvedValueOnce(null)
.mockResolvedValueOnce(null)
.mockResolvedValue(JSON.stringify(page)),
setNxPx: vi.fn().mockResolvedValue(true),
set: vi.fn().mockResolvedValue('OK'),
unlock: vi.fn().mockResolvedValue(1),
};
const config = new ConfigService({
CACHE_MODE: 'protected',
CACHE_LOCK_TTL_MS: 1000,
CACHE_TTL_SECONDS: 30,
});
const service = new MessagesCacheService(
redis as never,
config,
metrics,
);
await service.getOrLoad('chat', 1n, undefined, 50, async () => page);
await service.getOrLoad('chat', 1n, undefined, 50, async () => page);
expect(metrics.snapshot().counters).toMatchObject({
cache_miss: 1,
cache_hit: 1,
});
});
});
+11
View File
@@ -0,0 +1,11 @@
import { Module } from '@nestjs/common';
import { MessagesCacheService } from './messages-cache.service.js';
import { MetricsModule } from '../../metrics/metrics.module.js';
import { RedisModule } from '../../redis/redis.module.js';
@Module({
imports: [RedisModule, MetricsModule],
providers: [MessagesCacheService],
exports: [MessagesCacheService],
})
export class MessagesCacheModule {}
+72
View File
@@ -0,0 +1,72 @@
import { ConfigService } from '@nestjs/config';
import { describe, expect, it, vi } from 'vitest';
import type { AppConfig } from '../../config/app-config.schema.js';
import type { RedisClient } from '../../redis/redis.client.js';
import { MessagesCacheService } from './messages-cache.service.js';
import { MetricsService } from '../../metrics/metrics.service.js';
function serviceWithRedis(redis: Partial<RedisClient>): MessagesCacheService {
const config = new ConfigService<AppConfig>({
CACHE_MODE: 'protected',
CACHE_LOCK_TTL_MS: 1000,
CACHE_TTL_SECONDS: 30,
CACHE_MISS_DELAY_MS: 0,
});
return new MessagesCacheService(
redis as RedisClient,
config,
new MetricsService(),
);
}
describe('MessagesCacheService fallback', () => {
it('loads from the authoritative source when Redis read fails', async () => {
const load = vi
.fn()
.mockResolvedValue({ items: [{ id: 'db' }], next_cursor: null });
const service = serviceWithRedis({
get: vi.fn().mockRejectedValue(new Error('redis down')),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual({
items: [{ id: 'db' }],
next_cursor: null,
});
expect(load).toHaveBeenCalledOnce();
});
it('falls back after bounded lock contention', async () => {
const load = vi
.fn()
.mockResolvedValue({ items: [{ id: 'db' }], next_cursor: null });
const service = serviceWithRedis({
get: vi.fn().mockResolvedValue(null),
setNxPx: vi.fn().mockResolvedValue(false),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual({
items: [{ id: 'db' }],
next_cursor: null,
});
expect(load).toHaveBeenCalledOnce();
});
it('returns the authoritative page when cache write fails', async () => {
const page = { items: [{ id: 'db' }], next_cursor: null };
const load = vi.fn().mockResolvedValue(page);
const service = serviceWithRedis({
get: vi.fn().mockResolvedValue(null),
setNxPx: vi.fn().mockResolvedValue(true),
set: vi.fn().mockRejectedValue(new Error('redis down')),
unlock: vi.fn().mockResolvedValue(1),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual(page);
});
});
+205
View File
@@ -0,0 +1,205 @@
import { Injectable, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { setTimeout as delay } from 'node:timers/promises';
import type { AppConfig } from '../../config/app-config.schema.js';
import { RedisClient } from '../../redis/redis.client.js';
import type { Page } from '../../common/http/page.js';
import { MetricsService } from '../../metrics/metrics.service.js';
const LOCK_RETRY_COUNT = 4;
const LOCK_RETRY_DELAY_MS = 25;
export type CachePage = Page<unknown>;
@Injectable()
export class MessagesCacheService {
private readonly logger = new Logger(MessagesCacheService.name);
constructor(
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
async getOrLoad(
chatId: string,
version: bigint,
cursor: string | undefined,
limit: number,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
const key = this.cacheKey(chatId, version, cursor, limit);
if (this.config.getOrThrow('CACHE_MODE') === 'naive') {
return this.loadNaively(key, loader);
}
let cached: string | null;
try {
cached = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('read', error, loader);
}
const cachedPage = this.parsePage(cached);
if (cachedPage) {
this.metrics.increment('cache_hit');
return cachedPage;
}
this.metrics.increment('cache_miss');
const lockKey = `lock:${key}`;
const owner = `${process.pid}:${Math.random().toString(36).slice(2)}`;
for (let attempt = 0; attempt < LOCK_RETRY_COUNT; attempt += 1) {
let locked: boolean;
try {
locked = await this.redis.setNxPx(
lockKey,
owner,
this.config.getOrThrow('CACHE_LOCK_TTL_MS'),
);
} catch (error) {
return this.fallbackToDatabase('lock', error, loader);
}
if (locked) return this.fillLocked(key, lockKey, owner, loader);
if (attempt === 0) this.metrics.increment('cache_lock_wait');
try {
const waitedPage = this.parsePage(await this.redis.get(key));
if (waitedPage) {
this.metrics.increment('cache_hit');
return waitedPage;
}
} catch (error) {
return this.fallbackToDatabase('waiting read', error, loader);
}
await delay(LOCK_RETRY_DELAY_MS);
}
// The owner did not publish the page within the bounded wait: serve the
// authoritative result instead of blocking the request further.
this.metrics.increment('cache_lock_timeout');
return loader();
}
private async fillLocked(
key: string,
lockKey: string,
owner: string,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
try {
let secondCheck: string | null;
try {
secondCheck = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('double-check', error, loader);
}
const secondPage = this.parsePage(secondCheck);
if (secondPage) {
this.metrics.increment('cache_hit');
return secondPage;
}
const page = await loader();
try {
await this.redis.set(key, JSON.stringify(page), {
EX: this.config.getOrThrow('CACHE_TTL_SECONDS'),
});
} catch (error) {
// Redis is derived state: the page is still valid for this response,
// but the failure must stay visible in metrics and logs.
this.metrics.increment('cache_write_error');
this.logger.warn(
`Cache fill failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
return page;
} finally {
try {
await this.redis.unlock(lockKey, owner);
} catch (error) {
// The lock has a TTL, so a stale lock expires on its own; a successful
// response must not be replaced by an unlock failure.
this.metrics.increment('cache_unlock_error');
this.logger.warn(
`Cache unlock failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
}
}
private cacheKey(
chatId: string,
version: bigint,
cursor: string | undefined,
limit: number,
): string {
return `messages:${chatId}:v${version.toString()}:c${cursor ?? 'start'}:l${limit}`;
}
private async loadNaively(
key: string,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
let cached: string | null;
try {
cached = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('naive read', error, loader);
}
const cachedPage = this.parsePage(cached);
if (cachedPage) {
this.metrics.increment('cache_hit');
return cachedPage;
}
this.metrics.increment('cache_miss');
const cacheMissDelay = this.config.getOrThrow('CACHE_MISS_DELAY_MS');
if (cacheMissDelay > 0) await delay(cacheMissDelay);
const page = await loader();
try {
await this.redis.set(key, JSON.stringify(page), {
EX: this.config.getOrThrow('CACHE_TTL_SECONDS'),
});
} catch (error) {
this.metrics.increment('cache_write_error');
this.logger.warn(
`Cache fill failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
return page;
}
private async fallbackToDatabase(
stage: string,
error: unknown,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
this.metrics.increment('cache_fallback');
this.logger.warn(
`Cache ${stage} failed, serving PostgreSQL: ${error instanceof Error ? error.message : 'unknown error'}`,
);
return loader();
}
private parsePage(value: string | null): CachePage | undefined {
if (!value) return undefined;
try {
const parsed: unknown = JSON.parse(value);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('items' in parsed) ||
!('next_cursor' in parsed) ||
!Array.isArray(parsed.items) ||
(parsed.next_cursor !== null &&
typeof parsed.next_cursor !== 'string')
)
return undefined;
return { items: parsed.items, next_cursor: parsed.next_cursor };
} catch {
// A malformed entry is treated as a miss and overwritten by the owner fill.
this.metrics.increment('cache_corrupt_entry');
return undefined;
}
}
}
@@ -0,0 +1,8 @@
import { IsString } from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateMessageDto {
@IsString()
@CodePointLength(1, 4000)
text!: string;
}
@@ -0,0 +1,33 @@
import { fileURLToPath } from 'node:url';
import { parseAppConfig } from '../../config/app-config.schema.js';
import { DatabaseClient } from '../../database/database.client.js';
import { MetricsService } from '../../metrics/metrics.service.js';
import { IdempotencyRepository } from './idempotency.repository.js';
// Manual operator pass over the idempotency ledger: the API also purges expired
// claims in the background, but an operator must be able to reclaim space
// without waiting for traffic. It never touches unexpired claims.
// in the stand: docker compose exec api node dist/messages/idempotency/idempotency-gc.cli.js
// on the host: npm run idempotency:gc (needs a reachable DATABASE_URL)
async function main(): Promise<void> {
const config = parseAppConfig(process.env as Record<string, unknown>);
const database = new DatabaseClient(
{
getOrThrow: (key: keyof typeof config) => config[key],
} as never,
new MetricsService(),
);
try {
const repository = new IdempotencyRepository(database);
const purged = await repository.purgeExpired(
config.IDEMPOTENCY_TTL_SECONDS,
);
process.stdout.write(
`Purged ${purged} idempotency key(s) older than ${config.IDEMPOTENCY_TTL_SECONDS} seconds\n`,
);
} finally {
await database.onModuleDestroy();
}
}
if (process.argv[1] === fileURLToPath(import.meta.url)) await main();
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../../database/database.module.js';
import { IdempotencyRepository } from './idempotency.repository.js';
@Module({
imports: [DatabaseModule],
providers: [IdempotencyRepository],
exports: [IdempotencyRepository],
})
export class IdempotencyModule {}
@@ -0,0 +1,19 @@
import { describe, expect, it, vi } from 'vitest';
import { IdempotencyRepository } from './idempotency.repository.js';
describe('IdempotencyRepository expired-key cleanup', () => {
it('deletes only rows older than the configured TTL', async () => {
const query = vi.fn().mockResolvedValue({ rowCount: 0, rows: [] });
const repository = new IdempotencyRepository({ query } as never);
await repository.forget('user', '/api/v1/chats/chat/messages', 'key', 86400);
expect(query).toHaveBeenCalledWith(
'idempotency.forget',
expect.stringContaining(
'created_at < now() - make_interval(secs => $4::double precision)',
),
['user', '/api/v1/chats/chat/messages', 'key', 86400],
);
});
});
@@ -0,0 +1,119 @@
import { Injectable } from '@nestjs/common';
import pg from 'pg';
import { DatabaseClient } from '../../database/database.client.js';
import type { Message } from '../message.js';
// A committed row always carries the response: the claim and the stored response
// are written by one statement, so there is no poisoned intermediate state to
// re-check at replay time.
export type IdempotencyRecord = {
request_fingerprint: string;
status_code: number;
response_body: Message;
created_at: Date | string;
expired: boolean;
is_member: boolean;
};
const PURGE_BATCH_LIMIT = 1000;
const PURGE_BATCHES = 10;
@Injectable()
export class IdempotencyRepository {
constructor(private readonly database: DatabaseClient) {}
/**
* Reads the stored result and re-checks access in the same round trip: a
* replay must still prove that the caller may read this chat.
*/
async read(
userId: string,
path: string,
key: string,
chatId: string,
ttlSeconds: number,
): Promise<IdempotencyRecord | undefined> {
const result = await this.database.query<IdempotencyRecord>(
'idempotency.read',
`SELECT k.request_fingerprint, k.status_code, k.response_body, k.created_at,
k.created_at < now() - make_interval(secs => $4::double precision) AS expired,
EXISTS (
SELECT 1 FROM chat_members WHERE chat_id = $5 AND user_id = $1
) AS is_member
FROM idempotency_keys k
WHERE k.user_id = $1 AND k.method = 'POST' AND k.path = $2 AND k.key = $3`,
[userId, path, key, ttlSeconds, chatId],
);
return result.rows[0];
}
async forget(
userId: string,
path: string,
key: string,
ttlSeconds: number,
): Promise<void> {
await this.database.query(
'idempotency.forget',
`DELETE FROM idempotency_keys
WHERE user_id = $1 AND method = 'POST' AND path = $2 AND key = $3
AND created_at < now() - make_interval(secs => $4::double precision)`,
[userId, path, key, ttlSeconds],
);
}
async isMember(chatId: string, userId: string): Promise<boolean> {
const result = await this.database.query<{ is_member: boolean }>(
'messages.checkMembership',
`SELECT EXISTS (
SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2
) AS is_member`,
[chatId, userId],
);
return result.rows[0]?.is_member === true;
}
/**
* Deletes expired claims in bounded batches. The transaction-scoped advisory
* lock makes the pass single-flight across replicas without risking a lock
* leaking back into the pool with a released connection. Returns the number
* of deleted rows (0 when another replica is purging).
*/
async purgeExpired(ttlSeconds: number): Promise<number> {
const client: pg.PoolClient = await this.database.pool.connect();
try {
await client.query('BEGIN');
try {
const lock = await client.query<{ locked: boolean }>(
"SELECT pg_try_advisory_xact_lock(hashtext('idempotency_gc')) AS locked",
);
if (lock.rows[0]?.locked !== true) {
await client.query('ROLLBACK');
return 0;
}
let purged = 0;
for (let batch = 0; batch < PURGE_BATCHES; batch += 1) {
const result = await client.query(
`DELETE FROM idempotency_keys
WHERE ctid IN (
SELECT ctid FROM idempotency_keys
WHERE created_at < now() - make_interval(secs => $1::double precision)
LIMIT ${PURGE_BATCH_LIMIT}
)`,
[ttlSeconds],
);
const deleted = result.rowCount ?? 0;
purged += deleted;
if (deleted < PURGE_BATCH_LIMIT) break;
}
await client.query('COMMIT');
return purged;
} catch (error) {
await client.query('ROLLBACK').catch(() => undefined);
throw error;
}
} finally {
client.release();
}
}
}
@@ -0,0 +1,18 @@
import { createHash } from 'node:crypto';
import type { CreateMessageDto } from '../dto/create-message.dto.js';
// Contract: ASCII [A-Za-z0-9._:-]{1,128}. Anything else (including a duplicated
// header, which Fastify joins with ", ") is rejected as a client error.
export const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
export function messagesPath(chatId: string): string {
return `/api/v1/chats/${chatId}/messages`;
}
// The fingerprint is derived from the validated payload with a fixed field
// order, so neither JSON key order nor an absent optional field can change it.
export function idempotencyFingerprint(input: CreateMessageDto): string {
return createHash('sha256')
.update(JSON.stringify({ text: input.text }))
.digest('hex');
}
+7
View File
@@ -0,0 +1,7 @@
export type Message = {
id: string;
chat_id: string;
sender_id: string;
text: string;
created_at: string;
};
+53
View File
@@ -0,0 +1,53 @@
import {
BadRequestException,
Body,
Controller,
DefaultValuePipe,
Get,
Headers,
Param,
ParseIntPipe,
ParseUUIDPipe,
Post,
Query,
UseGuards,
} from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import type { User } from '../users/user.js';
import { CreateMessageDto } from './dto/create-message.dto.js';
import { MessagesService } from './messages.service.js';
@Controller('api/v1/chats/:chatId/messages')
@UseGuards(CurrentUserGuard)
export class MessagesController {
constructor(private readonly messagesService: MessagesService) {}
@Post()
create(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@Body() body: CreateMessageDto,
@CurrentUser() currentUser: User,
@Headers('idempotency-key') idempotencyKey?: string | string[],
) {
return this.messagesService.create(
chatId,
body,
currentUser,
idempotencyKey,
);
}
@Get()
list(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@CurrentUser() currentUser: User,
@Query('limit', new DefaultValuePipe(50), new ParseIntPipe())
limit: number,
@Query('cursor') cursor?: string,
) {
if (limit < 1 || limit > 100)
throw new BadRequestException('limit must be between 1 and 100');
return this.messagesService.list(chatId, currentUser, limit, cursor);
}
}
+26
View File
@@ -0,0 +1,26 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { ChatsModule } from '../chats/chats.module.js';
import { MessagesController } from './messages.controller.js';
import { MessagesRepository } from './messages.repository.js';
import { MessagesService } from './messages.service.js';
import { MessagesCacheModule } from './cache/messages-cache.module.js';
import { IdempotencyModule } from './idempotency/idempotency.module.js';
import { UsersModule } from '../users/users.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
@Module({
imports: [
ChatsModule,
MessagesCacheModule,
IdempotencyModule,
DatabaseModule,
UsersModule,
RedisModule,
MetricsModule,
],
controllers: [MessagesController],
providers: [MessagesRepository, MessagesService],
})
export class MessagesModule {}
@@ -0,0 +1,47 @@
import { describe, expect, it, vi } from 'vitest';
import type { Cursor } from '../common/http/cursor.js';
import type { Message } from './message.js';
import { MessagesRepository } from './messages.repository.js';
const message = (id: string, created_at: string): Message => ({
id,
chat_id: 'chat',
sender_id: 'sender',
text: id,
created_at,
});
describe('MessagesRepository', () => {
it('uses named SQL history and a keyset cursor', async () => {
const query = vi.fn().mockResolvedValue({ rows: [], rowCount: 0 });
const repository = new MessagesRepository({
query,
withTransaction: vi.fn(),
} as never);
const cursor: Cursor = {
scope: 'messages:chat',
created_at: '2026-01-01T00:00:01.000Z',
id: '1',
};
await repository.findPage('chat', 10, cursor);
expect(query).toHaveBeenCalledWith(
'messages.history',
expect.stringContaining('(created_at, id) >'),
expect.arrayContaining(['chat', cursor.created_at, cursor.id, 11]),
);
});
it('returns rows in response shape', async () => {
const query = vi
.fn()
.mockResolvedValue({
rows: [message('1', '2026-01-01T00:00:00.000Z')],
rowCount: 1,
});
const repository = new MessagesRepository({ query } as never);
await expect(repository.findPage('chat', 1)).resolves.toEqual({
items: [message('1', '2026-01-01T00:00:00.000Z')],
hasMore: false,
});
});
});
+131
View File
@@ -0,0 +1,131 @@
import {
Injectable,
NotFoundException,
} from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { DatabaseClient } from '../database/database.client.js';
import type { Cursor } from '../common/http/cursor.js';
import type { Message } from './message.js';
type MessageRow = {
id: string;
chat_id: string;
sender_id: string;
text: string;
created_at: Date | string;
};
export type CreateOnceRequest = {
userId: string;
chatId: string;
path: string;
key: string;
fingerprint: string;
text: string;
};
function toMessage(row: MessageRow): Message {
return {
id: row.id,
chat_id: row.chat_id,
sender_id: row.sender_id,
text: row.text,
created_at: new Date(row.created_at).toISOString(),
};
}
// Один оператор делает всё, что нужно пути записи: проверяет членство, занимает
// ключ идемпотентности, вставляет сообщение, увеличивает версию чата (якорь
// инвалидации кэша истории) и сохраняет тело ответа. Атомарность даёт сам
// оператор, поэтому явная транзакция и отдельные round trip'ы не нужны; тело
// ответа строится в SQL и служит единственным источником истины и для первого
// ответа, и для повторов.
//
// Зависимости CTE задают порядок выполнения: claim -> inserted -> bumped.
const CREATE_ONCE_SQL = `
WITH claim AS (
INSERT INTO idempotency_keys (user_id, method, path, key, request_fingerprint,
status_code, response_body, message_id)
SELECT $1, 'POST', $2, $3, $4, 201,
jsonb_build_object(
'id', $5::uuid,
'chat_id', $7::uuid,
'sender_id', $1::uuid,
'text', $6::text,
'created_at', to_char(date_trunc('milliseconds', now()) AT TIME ZONE 'UTC',
'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
$5::uuid
WHERE EXISTS (
SELECT 1 FROM chat_members WHERE chat_id = $7::uuid AND user_id = $1
)
ON CONFLICT DO NOTHING
RETURNING response_body
), inserted AS (
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
SELECT $5::uuid, $7::uuid, $1::uuid, $6::text, date_trunc('milliseconds', now())
FROM claim
RETURNING id
), bumped AS (
UPDATE chats SET message_version = message_version + 1
WHERE id = $7::uuid AND EXISTS (SELECT 1 FROM inserted)
)
SELECT response_body FROM claim`;
@Injectable()
export class MessagesRepository {
constructor(private readonly database: DatabaseClient) {}
/**
* Returns the created message, or undefined when the key is already taken or
* the caller is not a member of the chat (both leave no side effect).
*/
async createOnce(request: CreateOnceRequest): Promise<Message | undefined> {
const result = await this.database.query<{ response_body: Message }>(
'messages.createIdempotent',
CREATE_ONCE_SQL,
[
request.userId,
request.path,
request.key,
request.fingerprint,
randomUUID(),
request.text,
request.chatId,
],
);
return result.rows[0]?.response_body;
}
async getVersion(chatId: string, userId: string): Promise<bigint> {
const result = await this.database.query<{ message_version: string }>(
'messages.version',
'SELECT c.message_version FROM chats c WHERE c.id = $1 AND EXISTS (SELECT 1 FROM chat_members WHERE chat_id = c.id AND user_id = $2)',
[chatId, userId],
);
if (!result.rows[0]) throw new NotFoundException();
return BigInt(result.rows[0].message_version);
}
async findPage(
chatId: string,
limit: number,
cursor?: Cursor,
): Promise<{ items: Message[]; hasMore: boolean }> {
const values: unknown[] = [chatId];
let predicate = '';
if (cursor) {
values.push(cursor.created_at, cursor.id);
predicate = 'AND (created_at, id) > ($2::timestamptz, $3::uuid)';
}
values.push(limit + 1);
const result = await this.database.query<MessageRow>(
'messages.history',
`SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = $1 ${predicate} ORDER BY created_at, id LIMIT $${values.length}`,
values,
);
return {
items: result.rows.slice(0, limit).map(toMessage),
hasMore: result.rows.length > limit,
};
}
}
+115
View File
@@ -0,0 +1,115 @@
import { describe, expect, it, vi } from 'vitest';
import { MessagesService } from './messages.service.js';
import { idempotencyFingerprint } from './idempotency/idempotency.js';
import type { Message } from './message.js';
type StoredRow = {
request_fingerprint: string;
response_body: Message;
created_at: Date;
expired: boolean;
is_member: boolean;
};
function deferred(): { promise: Promise<void>; resolve: () => void } {
let resolve!: () => void;
const promise = new Promise<void>((done) => {
resolve = done;
});
return { promise, resolve };
}
describe('MessagesService idempotency expiry race', () => {
it('does not let a stale expiry decision delete a replacement claim', async () => {
const oldCreatedAt = new Date('2020-01-01T00:00:00.000Z');
const newMessage: Message = {
id: 'message-new',
chat_id: 'chat',
sender_id: 'user',
text: 'hello',
created_at: '2026-01-01T00:00:00.000Z',
};
let row: StoredRow | undefined = {
request_fingerprint: idempotencyFingerprint({ text: 'hello' }),
response_body: {
...newMessage,
id: 'message-old',
text: 'old',
},
created_at: oldCreatedAt,
expired: true,
is_member: true,
};
let createCalls = 0;
let readCalls = 0;
let forgetCalls = 0;
let messageWrites = 0;
const bothInitialClaims = deferred();
const bothInitialReads = deferred();
const replacementCreated = deferred();
const messagesRepository = {
createOnce: vi.fn(async () => {
createCalls += 1;
if (createCalls === 2) bothInitialClaims.resolve();
if (createCalls <= 2) {
await bothInitialClaims.promise;
return undefined;
}
if (row) return undefined;
messageWrites += 1;
row = {
request_fingerprint: idempotencyFingerprint({ text: 'hello' }),
response_body: newMessage,
created_at: new Date('2026-01-01T00:00:00.000Z'),
expired: false,
is_member: true,
};
replacementCreated.resolve();
return newMessage;
}),
};
const idempotency = {
read: vi.fn(async () => {
readCalls += 1;
if (readCalls === 2) bothInitialReads.resolve();
if (readCalls <= 2) await bothInitialReads.promise;
return row;
}),
forget: vi.fn(async (...args: unknown[]) => {
forgetCalls += 1;
if (args.length !== 4) {
row = undefined;
return;
}
if (forgetCalls === 2) await replacementCreated.promise;
if (!row || row.created_at >= new Date('2026-01-01T00:00:00.000Z')) return;
row = undefined;
}),
isMember: vi.fn().mockResolvedValue(true),
};
const makeService = () =>
new MessagesService(
messagesRepository as never,
{} as never,
{} as never,
idempotency as never,
{ getOrThrow: vi.fn().mockReturnValue(60) } as never,
{ increment: vi.fn() } as never,
);
const input = { text: 'hello' } as never;
const user = { id: 'user' } as never;
const results = await Promise.all([
makeService().create('chat', input, user, 'same-key'),
makeService().create('chat', input, user, 'same-key'),
]);
expect(results).toEqual([newMessage, newMessage]);
expect(new Set(results.map((message) => message.id))).toEqual(
new Set(['message-new']),
);
expect(messageWrites).toBe(1);
expect(forgetCalls).toBe(2);
});
});
+186
View File
@@ -0,0 +1,186 @@
import {
BadRequestException,
ConflictException,
Injectable,
Logger,
NotFoundException,
ServiceUnavailableException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { decodeCursor, encodeCursor } from '../common/http/cursor.js';
import type { Page } from '../common/http/page.js';
import type { AppConfig } from '../config/app-config.schema.js';
import type { User } from '../users/user.js';
import { ChatsService } from '../chats/chats.service.js';
import { MetricsService } from '../metrics/metrics.service.js';
import type { CreateMessageDto } from './dto/create-message.dto.js';
import type { Message } from './message.js';
import { MessagesRepository } from './messages.repository.js';
import { MessagesCacheService } from './cache/messages-cache.service.js';
import {
IDEMPOTENCY_KEY_PATTERN,
idempotencyFingerprint,
messagesPath,
} from './idempotency/idempotency.js';
import { IdempotencyRepository } from './idempotency/idempotency.repository.js';
// Один повтор нужен только для просроченного ключа: запись удаляется, и тот же
// оператор занимает ключ заново. Больше трёх кругов означает, что ключ
// перехватывают параллельные запросы, и честнее вернуть 503, чем крутиться.
const MAX_CLAIM_ATTEMPTS = 3;
const PURGE_EVERY_REQUESTS = 512;
@Injectable()
export class MessagesService {
private readonly logger = new Logger(MessagesService.name);
private requestsSincePurge = 0;
constructor(
private readonly messagesRepository: MessagesRepository,
private readonly chatsService: ChatsService,
private readonly cache: MessagesCacheService,
private readonly idempotency: IdempotencyRepository,
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
async create(
chatId: string,
input: CreateMessageDto,
currentUser: User,
rawKey: string | string[] | undefined,
): Promise<Message> {
// Ключ и тело проверяются до обращения к БД: клиентская ошибка не должна
// создавать заявку и не должна зависеть от состояния хранилища.
if (typeof rawKey !== 'string' || !IDEMPOTENCY_KEY_PATTERN.test(rawKey))
throw new BadRequestException(
'Idempotency-Key header is required',
);
if ([...input.text].every((character) => /\s/u.test(character)))
throw new BadRequestException('Message text cannot be blank');
const path = messagesPath(chatId);
const fingerprint = idempotencyFingerprint(input);
const ttl = this.config.getOrThrow('IDEMPOTENCY_TTL_SECONDS');
for (let attempt = 1; attempt <= MAX_CLAIM_ATTEMPTS; attempt += 1) {
const created = await this.messagesRepository.createOnce({
userId: currentUser.id,
chatId,
path,
key: rawKey,
fingerprint,
text: input.text,
});
if (created) {
this.metrics.increment('idempotency.claim');
this.metrics.increment('messages.write');
this.scheduleExpiredPurge();
return created;
}
const stored = await this.idempotency.read(
currentUser.id,
path,
rawKey,
chatId,
ttl,
);
if (!stored) {
// Заявки нет: либо запрос не имеет доступа к чату (404), либо
// чужую заявку сняли между нашими двумя запросами (503).
if (!(await this.idempotency.isMember(chatId, currentUser.id)))
throw new NotFoundException();
this.metrics.increment('idempotency.claim_lost');
throw new ServiceUnavailableException(
'Idempotency key could not be claimed',
);
}
if (stored.expired) {
this.metrics.increment('idempotency.released');
await this.idempotency.forget(
currentUser.id,
path,
rawKey,
ttl,
);
continue;
}
if (stored.request_fingerprint !== fingerprint) {
this.metrics.increment('idempotency.conflict');
throw new ConflictException(
'Idempotency key reused with a different body',
);
}
if (!stored.is_member) throw new NotFoundException();
this.metrics.increment('idempotency.replay');
return stored.response_body;
}
throw new ServiceUnavailableException(
'Idempotency key could not be claimed',
);
}
// Expired claims are storage hygiene, not part of the request: the pass runs
// outside the request path, at most once per PURGE_EVERY_REQUESTS successful
// writes, and its failure never changes the client's result.
private scheduleExpiredPurge(): void {
this.requestsSincePurge += 1;
if (this.requestsSincePurge < PURGE_EVERY_REQUESTS) return;
this.requestsSincePurge = 0;
const ttl = this.config.getOrThrow('IDEMPOTENCY_TTL_SECONDS');
void this.idempotency
.purgeExpired(ttl)
.then((purged) => {
if (purged > 0) this.metrics.increment('idempotency.purged');
})
.catch((error: unknown) => {
this.metrics.increment('idempotency.purge_error');
this.logger.warn(
`Idempotency purge failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
});
}
async list(
chatId: string,
currentUser: User,
limit: number,
cursorValue?: string,
): Promise<Page<Message>> {
await this.chatsService.getForUser(chatId, currentUser);
const scope = `messages:${chatId}`;
const cursor = cursorValue
? decodeCursor(cursorValue, scope)
: undefined;
const version = await this.messagesRepository.getVersion(
chatId,
currentUser.id,
);
const page = await this.cache.getOrLoad(
chatId,
version,
cursorValue,
limit,
async () => {
const loaded = await this.messagesRepository.findPage(
chatId,
limit,
cursor,
);
const lastLoaded = loaded.items.at(-1);
return {
items: loaded.items,
next_cursor:
loaded.hasMore && lastLoaded
? encodeCursor({
scope,
created_at: lastLoaded.created_at,
id: lastLoaded.id,
})
: null,
};
},
);
return page as Page<Message>;
}
}
+54
View File
@@ -0,0 +1,54 @@
import {
Controller,
Get,
Headers,
HttpCode,
HttpStatus,
Post,
UnauthorizedException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import type { AppConfig } from '../config/app-config.schema.js';
import { resolveInstanceId } from '../config/instance-id.js';
import { MetricsService } from './metrics.service.js';
@Controller('internal')
export class MetricsController {
private readonly instanceId: string;
private readonly buildId: string;
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {
this.instanceId = resolveInstanceId(config);
this.buildId = process.env.BUILD_ID ?? 'unknown';
}
@Get('metrics')
get(@Headers('authorization') authorization?: string) {
this.requireToken(authorization);
return {
...this.metrics.snapshot(),
instance_id: this.instanceId,
build_id: this.buildId,
};
}
@Post('metrics/reset')
@HttpCode(HttpStatus.OK)
reset(@Headers('authorization') authorization?: string): { status: 'ok' } {
this.requireToken(authorization);
this.metrics.reset();
return { status: 'ok' };
}
private requireToken(authorization?: string): void {
const token = this.config.get<string>('METRICS_TOKEN');
if (!token || authorization !== `Bearer ${token}`)
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="metrics"',
});
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsController } from './metrics.controller.js';
import { MetricsService } from './metrics.service.js';
@Module({
controllers: [MetricsController],
providers: [MetricsService],
exports: [MetricsService],
})
export class MetricsModule {}
+62
View File
@@ -0,0 +1,62 @@
import { describe, expect, it } from 'vitest';
import { MetricsService } from './metrics.service.js';
describe('MetricsService', () => {
it('computes nearest-rank percentiles from observed latencies', () => {
const metrics = new MetricsService();
metrics.increment('cache_hit');
metrics.increment('cache_hit');
metrics.observeLatency(30);
metrics.observeLatency(10);
metrics.observeLatency(20);
expect(metrics.snapshot()).toEqual({
counters: { cache_hit: 2 },
latency_ms: {
count: 3,
sample_count: 3,
p50: 20,
p95: 30,
p99: 30,
max: 30,
},
});
});
it('keeps snapshots isolated from callers and later observations', () => {
const metrics = new MetricsService();
metrics.increment('cache_hit');
const snapshot = metrics.snapshot();
snapshot.counters.cache_hit = 99;
metrics.increment('cache_hit');
expect(metrics.snapshot().counters.cache_hit).toBe(2);
expect(snapshot.latency_ms.count).toBe(0);
});
it('bounds retained samples but keeps cumulative count and maximum', () => {
const metrics = new MetricsService();
metrics.observeLatency(9000);
for (let index = 0; index < 4096; index += 1)
metrics.observeLatency(10);
expect(metrics.snapshot().latency_ms).toEqual({
count: 4097,
sample_count: 4096,
p50: 10,
p95: 10,
p99: 10,
max: 9000,
});
});
it('ignores invalid latency observations', () => {
const metrics = new MetricsService();
for (const value of [-1, NaN, Infinity]) metrics.observeLatency(value);
expect(metrics.snapshot().latency_ms).toEqual({
count: 0,
sample_count: 0,
p50: 0,
p95: 0,
p99: 0,
max: 0,
});
});
});
+69
View File
@@ -0,0 +1,69 @@
import { Injectable } from '@nestjs/common';
const LATENCY_SAMPLE_CAPACITY = 4096;
type LatencySnapshot = {
count: number;
sample_count: number;
p50: number;
p95: number;
p99: number;
max: number;
};
@Injectable()
export class MetricsService {
private readonly counters: Record<string, number> = {};
private readonly latencies: number[] = [];
private latencyCount = 0;
private maximumLatency = 0;
private nextSample = 0;
increment(name: string): void {
this.counters[name] = (this.counters[name] ?? 0) + 1;
}
observeLatency(milliseconds: number): void {
if (!Number.isFinite(milliseconds) || milliseconds < 0) return;
this.latencyCount += 1;
this.maximumLatency = Math.max(this.maximumLatency, milliseconds);
this.latencies[this.nextSample] = milliseconds;
this.nextSample = (this.nextSample + 1) % LATENCY_SAMPLE_CAPACITY;
}
snapshot(): {
counters: Record<string, number>;
latency_ms: LatencySnapshot;
} {
const sorted = [...this.latencies].sort((left, right) => left - right);
return {
counters: { ...this.counters },
latency_ms: {
count: this.latencyCount,
sample_count: sorted.length,
p50: this.percentile(sorted, 0.5),
p95: this.percentile(sorted, 0.95),
p99: this.percentile(sorted, 0.99),
max: this.maximumLatency,
},
};
}
reset(): void {
for (const name of Object.keys(this.counters))
delete this.counters[name];
this.latencies.length = 0;
this.latencyCount = 0;
this.maximumLatency = 0;
this.nextSample = 0;
}
private percentile(sorted: number[], percentile: number): number {
if (sorted.length === 0) return 0;
const index = Math.min(
sorted.length - 1,
Math.ceil(sorted.length * percentile) - 1,
);
return sorted[index];
}
}
+145
View File
@@ -0,0 +1,145 @@
import {
Injectable,
Logger,
OnModuleDestroy,
OnModuleInit,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { createClient, type RedisClientType } from 'redis';
import type { AppConfig } from '../config/app-config.schema.js';
import { MetricsService } from '../metrics/metrics.service.js';
const UNLOCK_SCRIPT =
'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end';
type Client = RedisClientType;
@Injectable()
export class RedisClient implements OnModuleInit, OnModuleDestroy {
readonly client: Client;
private readonly logger = new Logger(RedisClient.name);
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {
this.client = createClient({
url: this.config.getOrThrow('REDIS_URL'),
disableOfflineQueue: true,
socket: {
reconnectStrategy: (attempt) =>
Math.min(1000 + attempt * 250, 5000),
connectTimeout: 5000,
},
}) as Client;
// Reconnect failures must be visible; the readiness probe pings Redis.
this.client.on('error', (error: Error) => {
this.metrics.increment('redis.error');
this.logger.warn(`Redis error: ${error.message}`);
});
}
async onModuleInit(): Promise<void> {
await this.client.connect();
}
async onModuleDestroy(): Promise<void> {
if (this.client.isOpen) await this.client.quit();
}
async health(): Promise<void> {
this.metrics.increment('redis.ping');
// AbortSignal.timeout ограничивает именно пробу: обычные GET/SET остаются
// без командного таймаута, а замороженный Redis проваливает готовность
// в бюджет, который короче timeout check балансировщика.
const timeout = AbortSignal.timeout(
this.config.getOrThrow('HEALTH_TIMEOUT_MS'),
);
await this.client.withAbortSignal(timeout).ping();
}
async get(key: string): Promise<string | null> {
this.metrics.increment('redis.get');
return this.client.get(key);
}
async set(
key: string,
value: string,
options?: { EX?: number; PX?: number; NX?: boolean },
): Promise<string | null> {
this.metrics.increment('redis.set');
return this.client.set(key, value, options);
}
async setNxEx(
key: string,
value: string,
seconds: number,
): Promise<boolean> {
this.metrics.increment('redis.set');
return (
(await this.client.set(key, value, { NX: true, EX: seconds })) ===
'OK'
);
}
async setNxPx(
key: string,
value: string,
milliseconds: number,
): Promise<boolean> {
this.metrics.increment('redis.set');
return (
(await this.client.set(key, value, {
NX: true,
PX: milliseconds,
})) === 'OK'
);
}
async del(key: string): Promise<number> {
this.metrics.increment('redis.del');
return this.client.del(key);
}
async incr(key: string): Promise<number> {
this.metrics.increment('redis.incr');
return this.client.incr(key);
}
async expire(key: string, seconds: number): Promise<boolean> {
this.metrics.increment('redis.expire');
return (await this.client.expire(key, seconds)) === 1;
}
async scan(
cursor: number,
pattern?: string,
count = 100,
): Promise<{ cursor: number; keys: string[] }> {
this.metrics.increment('redis.scan');
const result = await this.client.scan(String(cursor), {
MATCH: pattern,
COUNT: count,
});
return { cursor: Number(result.cursor), keys: result.keys };
}
async unlock(key: string, owner: string): Promise<number> {
this.metrics.increment('redis.unlock');
return Number(
await this.client.eval(UNLOCK_SCRIPT, {
keys: [key],
arguments: [owner],
}),
);
}
pipeline(commands: Array<[string, ...string[]]>): Promise<unknown[]> {
this.metrics.increment('redis.pipeline');
const multi = this.client.multi();
for (const [command, ...args] of commands)
multi.addCommand([command, ...args]);
return multi.exec();
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsModule } from '../metrics/metrics.module.js';
import { RedisClient } from './redis.client.js';
@Module({
imports: [MetricsModule],
providers: [RedisClient],
exports: [RedisClient],
})
export class RedisModule {}
+7
View File
@@ -0,0 +1,7 @@
import { User } from './users/user.ts';
declare module 'fastify' {
interface FastifyRequest {
currentUser?: User;
}
}
+22
View File
@@ -0,0 +1,22 @@
import { IsString, Matches } from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateUserDTO {
@IsString()
@Matches(/^[a-z0-9_]{3,32}$/)
username!: string;
@IsString()
@CodePointLength(1, 100)
@Matches(/\S/u, {
message: 'display_name must contain a non-whitespace character',
})
display_name!: string;
@IsString()
@CodePointLength(12, 128)
@Matches(/\S/u, {
message: 'password must contain a non-whitespace character',
})
password!: string;
}
+6
View File
@@ -0,0 +1,6 @@
export type User = {
id: string;
username: string;
display_name: string;
created_at: string;
};
+22
View File
@@ -0,0 +1,22 @@
import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import type { User } from './user.js';
import { CreateUserDTO } from './dto/create-user.dto.js';
import { UsersService } from './users.service.js';
@Controller('api/v1/users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Post()
create(@Body() body: CreateUserDTO) {
return this.usersService.create(body);
}
@Get('/me')
@UseGuards(CurrentUserGuard)
getMe(@CurrentUser() currentUser: User) {
return currentUser;
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller.js';
import { UsersRepository } from './users.repository.js';
import { UsersService } from './users.service.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
import { DatabaseModule } from '../database/database.module.js';
@Module({
imports: [DatabaseModule, RedisModule, MetricsModule],
controllers: [UsersController],
providers: [UsersRepository, UsersService, CurrentUserGuard],
exports: [UsersService, CurrentUserGuard, RedisModule, MetricsModule],
})
export class UsersModule {}
+71
View File
@@ -0,0 +1,71 @@
import { ConflictException, Injectable } from '@nestjs/common';
import { DatabaseClient } from '../database/database.client.js';
import type { User } from './user.js';
type UserRow = {
id: string;
username: string;
display_name: string;
password_hash: string;
created_at: Date | string;
};
function toUser(row: UserRow): User {
return {
id: row.id,
username: row.username,
display_name: row.display_name,
created_at: new Date(row.created_at).toISOString(),
};
}
@Injectable()
export class UsersRepository {
constructor(private readonly database: DatabaseClient) {}
async findById(id: string): Promise<User | undefined> {
const result = await this.database.query<UserRow>(
'users.findById',
'SELECT id, username, display_name, password_hash, created_at FROM users WHERE id = $1',
[id],
);
const row = result.rows[0];
return row ? toUser(row) : undefined;
}
async findByUsername(
username: string,
): Promise<(User & { password_hash: string }) | undefined> {
const result = await this.database.query<UserRow>(
'users.findByUsername',
'SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = $1',
[username],
);
const row = result.rows[0];
return row
? { ...toUser(row), password_hash: row.password_hash }
: undefined;
}
async create(user: {
id: string;
username: string;
display_name: string;
password_hash: string;
}): Promise<User> {
try {
const result = await this.database.query<UserRow>(
'users.insert',
`INSERT INTO users (id, username, display_name, password_hash)
VALUES ($1, $2, $3, $4)
RETURNING id, username, display_name, password_hash, created_at`,
[user.id, user.username, user.display_name, user.password_hash],
);
return toUser(result.rows[0]);
} catch (error) {
if ((error as { code?: string }).code === '23505')
throw new ConflictException('Username already exists');
throw error;
}
}
}
+31
View File
@@ -0,0 +1,31 @@
import { Injectable } from '@nestjs/common';
import argon2 from 'argon2';
import { randomUUID } from 'node:crypto';
import { CreateUserDTO } from './dto/create-user.dto.js';
import { User } from './user.js';
import { UsersRepository } from './users.repository.js';
@Injectable()
export class UsersService {
constructor(private readonly usersRepository: UsersRepository) {}
async create(input: CreateUserDTO): Promise<User> {
const passwordHash = await argon2.hash(input.password, {
type: argon2.argon2id,
});
return this.usersRepository.create({
id: randomUUID(),
username: input.username,
display_name: input.display_name,
password_hash: passwordHash,
});
}
findById(id: string): Promise<User | undefined> {
return this.usersRepository.findById(id);
}
findByUsername(username: string) {
return this.usersRepository.findByUsername(username);
}
}
+674
View File
@@ -0,0 +1,674 @@
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { Pool } from 'pg';
import { createClient } from 'redis';
import type { SessionResponse } from '../src/auth/auth.service.js';
import type { Chat } from '../src/chats/chat.js';
import type { ApiErrorBody } from '../src/common/errors/api-error.js';
import type { Page } from '../src/common/http/page.js';
import type { Message } from '../src/messages/message.js';
import type { User } from '../src/users/user.js';
// The suite is black-box: run it against the compiled application process.
// Vitest sets process.env.BASE_URL itself (Vite base), so the API URL uses its own name.
const baseUrl = (process.env.API_BASE_URL ?? 'http://localhost:8080').replace(
/\/+$/u,
'',
);
const basicChallenge = 'Basic realm="messenger", charset="UTF-8"';
const bearerChallenge = 'Bearer realm="messenger"';
const password = 'integration:пароль🔐';
const runId = randomUUID().replaceAll('-', '').slice(0, 12);
const usernames: string[] = [];
const tokens: string[] = [];
let sequence = 0;
let database: Pool;
let redis: ReturnType<typeof createClient>;
type Actor = { user: User; password: string; token: string };
type HttpResult<T> = { body: T; response: Response };
async function http<T = unknown>(
path: string,
init: RequestInit = {},
): Promise<HttpResult<T>> {
const response = await fetch(`${baseUrl}${path}`, init);
const text = await response.text();
let body: unknown = undefined;
if (text) {
try {
body = JSON.parse(text);
} catch {
body = text;
}
}
return { body: body as T, response };
}
function json(
body: unknown,
headers: Record<string, string> = {},
): RequestInit {
return {
method: 'POST',
headers: { 'content-type': 'application/json', ...headers },
body: JSON.stringify(body),
};
}
function basic(username: string, secret: string): string {
return `Basic ${Buffer.from(`${username}:${secret}`, 'utf8').toString('base64')}`;
}
function bearer(token: string): Record<string, string> {
return { authorization: `Bearer ${token}` };
}
function idempotencyKey(): Record<string, string> {
return { 'idempotency-key': randomUUID().replaceAll('-', '') };
}
function messageHeaders(token: string): Record<string, string> {
return { ...bearer(token), ...idempotencyKey() };
}
async function register(
displayName = 'Интеграционный пользователь',
secret = password,
): Promise<User> {
const username = `e2e_${runId}_${sequence++}`.slice(0, 32);
usernames.push(username);
const result = await http<User>(
'/api/v1/users',
json({ username, display_name: displayName, password: secret }),
);
expect(result.response.status).toBe(201);
return result.body;
}
async function login(user: User, secret = password): Promise<SessionResponse> {
const result = await http<SessionResponse>('/api/v1/auth/sessions', {
method: 'POST',
headers: { authorization: basic(user.username, secret) },
});
expect(result.response.status).toBe(201);
tokens.push(result.body.token);
return result.body;
}
async function actor(displayName?: string): Promise<Actor> {
const user = await register(displayName);
const session = await login(user);
return { user, password, token: session.token };
}
function expectError(
result: HttpResult<ApiErrorBody>,
status: number,
code: string,
): void {
expect(result.response.status).toBe(status);
expect(result.body.error.code).toBe(code);
expect(result.body.error.request_id).toBe(
result.response.headers.get('x-request-id'),
);
}
describe('HTTP integration contract', () => {
beforeAll(async () => {
database = new Pool({
connectionString: process.env.DATABASE_URL,
connectionTimeoutMillis: 5000,
});
redis = createClient({
url: process.env.REDIS_URL,
socket: { reconnectStrategy: false },
});
redis.on('error', () => {});
await redis.connect();
});
afterAll(async () => {
if (usernames.length) {
await database.query('BEGIN');
try {
await database.query(
`DELETE FROM messages WHERE sender_id IN (SELECT id FROM users WHERE username = ANY($1::text[]))`,
[usernames],
);
await database.query(
`DELETE FROM chats WHERE id IN (SELECT chat_id FROM chat_members WHERE user_id IN (SELECT id FROM users WHERE username = ANY($1::text[])))`,
[usernames],
);
await database.query(
'DELETE FROM users WHERE username = ANY($1::text[])',
[usernames],
);
await database.query('COMMIT');
} catch (error) {
await database.query('ROLLBACK');
throw error;
}
}
if (redis.isOpen) redis.destroy();
await database.end();
});
it('serves liveness and requires real session authentication', async () => {
const live = await http<{ status: string }>('/health/live');
expect(live.response.status).toBe(200);
expect(live.body).toEqual({ status: 'ok' });
const denied = await http<ApiErrorBody>('/api/v1/users/me');
expectError(denied, 401, 'unauthorized');
expect(denied.response.headers.get('www-authenticate')).toBe(
bearerChallenge,
);
});
it('measures string lengths in Unicode code points', async () => {
const emoji = '🔐';
const username = (suffix: string) =>
`e2e_${runId}_${suffix}`.slice(0, 32);
const rejected = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_short'),
display_name: 'Code points',
password: emoji.repeat(11),
}),
);
expectError(rejected, 400, 'invalid_request');
const tooLongPassword = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_long'),
display_name: 'Code points',
password: emoji.repeat(129),
}),
);
expectError(tooLongPassword, 400, 'invalid_request');
const tooLongName = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_name'),
display_name: emoji.repeat(101),
password,
}),
);
expectError(tooLongName, 400, 'invalid_request');
const shortUsername = username('cp_ok');
usernames.push(shortUsername);
const boundaryPassword = emoji.repeat(12);
const created = await http<User>(
'/api/v1/users',
json({
username: shortUsername,
display_name: emoji.repeat(100),
password: boundaryPassword,
}),
);
expect(created.response.status).toBe(201);
expect([...created.body.display_name].length).toBe(100);
// The stored password keeps all 12 code points: authentication works.
const session = await http<SessionResponse>('/api/v1/auth/sessions', {
method: 'POST',
headers: {
authorization: basic(shortUsername, boundaryPassword),
},
});
expect(session.response.status).toBe(201);
tokens.push(session.body.token);
const longTitleRejected = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{ title: emoji.repeat(101), member_ids: [created.body.id] },
bearer(session.body.token),
),
);
expectError(longTitleRejected, 400, 'invalid_request');
const longTitle = await http<Chat>(
'/api/v1/chats',
json(
{ title: emoji.repeat(100), member_ids: [created.body.id] },
bearer(session.body.token),
),
);
expect(longTitle.response.status).toBe(201);
const tooLongText = await http<ApiErrorBody>(
`/api/v1/chats/${longTitle.body.id}/messages`,
json({ text: emoji.repeat(4001) }, messageHeaders(session.body.token)),
);
expectError(tooLongText, 400, 'invalid_request');
const boundaryText = await http<Message>(
`/api/v1/chats/${longTitle.body.id}/messages`,
json({ text: emoji.repeat(4000) }, messageHeaders(session.body.token)),
);
expect(boundaryText.response.status).toBe(201);
expect([...boundaryText.body.text].length).toBe(4000);
});
it('rejects whitespace-only and too-short credentials', async () => {
const username = `e2e_${runId}_${sequence++}`.slice(0, 32);
usernames.push(username);
const cases = [
{ password: ' '.repeat(12), display_name: 'Пользователь' },
{ password: '\t'.repeat(16), display_name: 'Пользователь' },
{ password: 'short-pass', display_name: 'Пользователь' },
{ password, display_name: ' ' },
];
for (const body of cases) {
const result = await http<ApiErrorBody>(
'/api/v1/users',
json({ username, ...body }),
);
expectError(result, 400, 'invalid_request');
}
const accepted = await http<User>(
'/api/v1/users',
json({ username, display_name: 'Пользователь', password }),
);
expect(accepted.response.status).toBe(201);
});
it('registers, logs in with Unicode/colon password, and challenges malformed Basic', async () => {
const user = await register();
const session = await login(user);
expect(session.user.id).toBe(user.id);
expect(session.token_type).toBe('Bearer');
const me = await http<User>('/api/v1/users/me', {
headers: bearer(session.token),
});
expect(me.response.status).toBe(200);
expect(me.body.id).toBe(user.id);
for (const authorization of [
'Basic !!!',
'Basic YWJj',
'Bearer nope',
]) {
const result = await http<ApiErrorBody>('/api/v1/auth/sessions', {
method: 'POST',
headers: { authorization },
});
expectError(result, 401, 'unauthorized');
expect(result.response.headers.get('www-authenticate')).toBe(
basicChallenge,
);
}
const bodyResult = await http<ApiErrorBody>('/api/v1/auth/sessions', {
...json({ unexpected: true }),
headers: { authorization: basic(user.username, password) },
});
expectError(bodyResult, 400, 'invalid_request');
});
it('returns conflict for concurrent duplicate registration', async () => {
const username = `e2e_${runId}_race`.slice(0, 32);
usernames.push(username);
const results = await Promise.all([
http<User>(
'/api/v1/users',
json({ username, display_name: 'Race A', password }),
),
http<User>(
'/api/v1/users',
json({ username, display_name: 'Race B', password }),
),
]);
expect(
results.filter((item) => item.response.status === 201),
'duplicate registration must create exactly one user',
).toHaveLength(1);
expect(
results.filter((item) => item.response.status === 409),
'loser of the race must receive 409, not 500',
).toHaveLength(1);
// The database unique index is the race-proof guard, so verify its effect.
const persisted = await database.query<{ count: string }>(
'SELECT count(*)::text AS count FROM users WHERE username = $1',
[username],
);
expect(persisted.rows[0]?.count).toBe('1');
});
it('uses Bearer only, ignores X-User-Id spoofing, and prevents logout replay', async () => {
const alice = await actor('Алиса');
const bob = await actor('Боб');
const spoof = await http<ApiErrorBody>('/api/v1/users/me', {
headers: { ...bearer(alice.token), 'x-user-id': bob.user.id },
});
expect(spoof.response.status).toBe(200);
expect((spoof.body as unknown as User).id).toBe(alice.user.id);
const basicBusiness = await http<ApiErrorBody>('/api/v1/users/me', {
headers: { authorization: basic(alice.user.username, password) },
});
expectError(basicBusiness, 401, 'unauthorized');
expect(basicBusiness.response.headers.get('www-authenticate')).toBe(
bearerChallenge,
);
const logout = await http('/api/v1/auth/sessions/current', {
method: 'DELETE',
headers: bearer(alice.token),
});
expect(logout.response.status).toBe(204);
const replay = await http<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(alice.token),
});
expectError(replay, 401, 'unauthorized');
});
it('rejects unknown and duplicate chat members and hides chats from outsiders', async () => {
const alice = await actor();
const bob = await actor();
const outsider = await actor();
const unknown = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{ title: 'unknown', member_ids: [alice.user.id, randomUUID()] },
bearer(alice.token),
),
);
expectError(unknown, 400, 'invalid_request');
const leaked = await http<ApiErrorBody>(`/api/v1/chats?limit=100`, {
headers: bearer(alice.token),
});
expect(leaked.response.status).toBe(200);
expect(
(leaked.body as unknown as Page<Chat>).items.some(
(item) => item.title === 'unknown',
),
).toBe(false);
const duplicate = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{
title: 'duplicate',
member_ids: [alice.user.id, alice.user.id],
},
bearer(alice.token),
),
);
expectError(duplicate, 400, 'invalid_request');
const created = await http<Chat>(
'/api/v1/chats',
json(
{
title: `chat-${runId}`,
member_ids: [alice.user.id, bob.user.id],
},
bearer(alice.token),
),
);
expect(created.response.status).toBe(201);
const hidden = await http<ApiErrorBody>(
`/api/v1/chats/${created.body.id}`,
{ headers: bearer(outsider.token) },
);
expectError(hidden, 404, 'not_found');
});
it('keeps sender server-owned and makes writes visible to a second session', async () => {
const alice = await actor();
const secondSession = (await login(alice.user)).token;
const chat = await http<Chat>(
'/api/v1/chats',
json(
{ title: `messages-${runId}`, member_ids: [alice.user.id] },
bearer(alice.token),
),
);
expect(chat.response.status).toBe(201);
const blank = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages`,
json(
{ text: ' \n\t', sender_id: randomUUID() },
messageHeaders(alice.token),
),
);
expectError(blank, 400, 'invalid_request');
const spoof = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages`,
json(
{ text: 'hello', sender_id: randomUUID() },
messageHeaders(alice.token),
),
);
expectError(spoof, 400, 'invalid_request');
await http(`/api/v1/chats/${chat.body.id}/messages?limit=50`, {
headers: bearer(secondSession),
});
const sent = await http<Message>(
`/api/v1/chats/${chat.body.id}/messages`,
json({ text: 'hello' }, messageHeaders(alice.token)),
);
expect(sent.response.status).toBe(201);
expect(sent.body.sender_id).toBe(alice.user.id);
const page = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=50`,
{ headers: bearer(secondSession) },
);
expect(page.response.status).toBe(200);
expect(page.body.items.map((item) => item.id)).toContain(sent.body.id);
});
it('validates cursor, limits, malformed JSON, and paginates without repeats', async () => {
const alice = await actor();
const chat = await http<Chat>(
'/api/v1/chats',
json(
{ title: `pages-${runId}`, member_ids: [alice.user.id] },
bearer(alice.token),
),
);
for (const text of ['one', 'two', 'three']) {
const sent = await http(
`/api/v1/chats/${chat.body.id}/messages`,
json({ text }, messageHeaders(alice.token)),
);
expect(sent.response.status).toBe(201);
}
const invalidLimit = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?limit=101`,
{ headers: bearer(alice.token) },
);
expectError(invalidLimit, 400, 'invalid_request');
const invalidCursor = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?cursor=not-a-cursor`,
{ headers: bearer(alice.token) },
);
expectError(invalidCursor, 400, 'invalid_request');
const rolledOver = http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?cursor=${encodeURIComponent(
Buffer.from(
JSON.stringify({
scope: `messages:${chat.body.id}`,
created_at: '2026-02-31T00:00:00.000Z',
id: randomUUID(),
}),
'utf8',
).toString('base64url'),
)}`,
{ headers: bearer(alice.token) },
);
expectError(await rolledOver, 400, 'invalid_request');
const malformed = await http<ApiErrorBody>('/api/v1/users', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: '{',
});
expectError(malformed, 400, 'invalid_request');
const first = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=2`,
{ headers: bearer(alice.token) },
);
expect(first.body.items).toHaveLength(2);
const second = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=2&cursor=${encodeURIComponent(first.body.next_cursor!)}`,
{ headers: bearer(alice.token) },
);
expect(second.body.items).toHaveLength(1);
expect(
new Set(
[...first.body.items, ...second.body.items].map(
(item) => item.id,
),
).size,
).toBe(3);
});
it.skipIf(process.env.SESSION_TTL_SECONDS !== '2')(
'expires sessions with TTL=2',
async () => {
const user = await register();
const session = await login(user);
await sleep(2300);
const expired = await http<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(session.token),
});
expectError(expired, 401, 'unauthorized');
},
);
});
// lab3: the Idempotency-Key contract of POST /chats/{id}/messages. The suite is
// black-box, so these assertions hold for one replica and for a load-balanced
// fleet alike.
describe('message idempotency', () => {
async function chatFor(token: string, memberIds: string[]): Promise<string> {
const created = await http<Chat>(
'/api/v1/chats',
json({ title: `idempotency-${runId}`, member_ids: memberIds }, bearer(token)),
);
expect(created.response.status).toBe(201);
return created.body.id;
}
async function textsIn(chatId: string, token: string): Promise<string[]> {
const page = await http<Page<Message>>(
`/api/v1/chats/${chatId}/messages?limit=100`,
{ headers: bearer(token) },
);
expect(page.response.status).toBe(200);
return page.body.items.map((item) => item.text);
}
it('requires a well-formed Idempotency-Key', async () => {
const alice = await actor();
const chatId = await chatFor(alice.token, [alice.user.id]);
const path = `/api/v1/chats/${chatId}/messages`;
const missing = await http<ApiErrorBody>(
path,
json({ text: 'без ключа' }, bearer(alice.token)),
);
expectError(missing, 400, 'invalid_request');
for (const key of ['has space', 'comma,separated', 'x'.repeat(129)]) {
const malformed = await http<ApiErrorBody>(
path,
json({ text: 'плохой ключ' }, { ...bearer(alice.token), 'idempotency-key': key }),
);
expectError(malformed, 400, 'invalid_request');
}
});
it('replays the stored response and conflicts on a different body', async () => {
const alice = await actor();
const chatId = await chatFor(alice.token, [alice.user.id]);
const path = `/api/v1/chats/${chatId}/messages`;
const key = randomUUID().replaceAll('-', '');
const headers = { ...bearer(alice.token), 'idempotency-key': key };
const text = `повтор ${runId}`;
const first = await http<Message>(path, json({ text }, headers));
expect(first.response.status).toBe(201);
const replayed = await http<Message>(path, json({ text }, headers));
expect(replayed.response.status).toBe(201);
expect(replayed.body).toEqual(first.body);
const conflict = await http<ApiErrorBody>(
path,
json({ text: 'другой body' }, headers),
);
expectError(conflict, 409, 'conflict');
expect(await textsIn(chatId, alice.token)).toEqual([text]);
});
it('creates exactly one message for concurrent requests with one key', async () => {
const alice = await actor();
const chatId = await chatFor(alice.token, [alice.user.id]);
const path = `/api/v1/chats/${chatId}/messages`;
const headers = { ...bearer(alice.token), ...idempotencyKey() };
const text = `конкурентный повтор ${runId}`;
const results = await Promise.all(
Array.from({ length: 8 }, () => http<Message>(path, json({ text }, headers))),
);
for (const result of results) expect(result.response.status).toBe(201);
const ids = new Set(results.map((result) => result.body.id));
expect(
ids.size,
'one key must resolve to exactly one message across replicas',
).toBe(1);
expect(await textsIn(chatId, alice.token)).toEqual([text]);
});
it('replays a key created by another replica', async () => {
// lab3: повтор с тем же ключом может прийти на любую реплику, поэтому
// проверяем не только сам повтор, но и то, что его обслужила другая реплика
// (иначе тест не отличал бы общий журнал от локального состояния процесса).
const alice = await actor();
const chatId = await chatFor(alice.token, [alice.user.id]);
const path = `/api/v1/chats/${chatId}/messages`;
const key = randomUUID().replaceAll('-', '');
const headers = { ...bearer(alice.token), 'idempotency-key': key };
const first = await http<Message>(path, json({ text: 'переключение реплики' }, headers));
expect(first.response.status).toBe(201);
const firstInstance = first.response.headers.get('x-instance-id');
expect(firstInstance).toBeTruthy();
let replay = first;
let replayInstance = firstInstance;
for (let attempt = 0; attempt < 12 && replayInstance === firstInstance; attempt += 1) {
replay = await http<Message>(path, json({ text: 'переключение реплики' }, headers));
expect(replay.response.status).toBe(201);
replayInstance = replay.response.headers.get('x-instance-id');
}
expect(
replayInstance,
'повтор должен был прийти на другую реплику (round-robin за LB)',
).not.toBe(firstInstance);
expect(replay.body).toEqual(first.body);
expect(await textsIn(chatId, alice.token)).toEqual(['переключение реплики']);
});
it('scopes the key per user and per chat path', async () => {
const alice = await actor();
const bob = await actor();
const outsider = await actor();
const chatId = await chatFor(alice.token, [alice.user.id, bob.user.id]);
const path = `/api/v1/chats/${chatId}/messages`;
const key = randomUUID().replaceAll('-', '');
const foreignChatId = await chatFor(outsider.token, [outsider.user.id]);
const denied = await http<ApiErrorBody>(
`/api/v1/chats/${foreignChatId}/messages`,
json({ text: 'чужое' }, { ...bearer(alice.token), 'idempotency-key': key }),
);
expectError(denied, 404, 'not_found');
const mine = await http<Message>(
path,
json({ text: 'своё' }, { ...bearer(alice.token), 'idempotency-key': key }),
);
expect(mine.response.status).toBe(201);
const other = await http<Message>(
path,
json({ text: 'своё' }, { ...bearer(bob.token), 'idempotency-key': key }),
);
expect(other.response.status).toBe(201);
expect(other.body.id).not.toBe(mine.body.id);
});
});
+799
View File
@@ -0,0 +1,799 @@
import { execFile } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import type { SessionResponse } from '../src/auth/auth.service.js';
import type { Chat } from '../src/chats/chat.js';
import type { ApiErrorBody } from '../src/common/errors/api-error.js';
import type { Page } from '../src/common/http/page.js';
import type { Message } from '../src/messages/message.js';
import type { User } from '../src/users/user.js';
// Automated counterpart of the manual Redis/PostgreSQL outage checks. Four
// topologies, because the load balancer probes /health/ready (the same route as
// the container healthcheck):
// 1. Redis outage — shared dependency: every replica turns not-ready, HAProxy
// removes all backends and answers 503 itself, while the replica's own
// readiness stays a bounded API 503 with request_id.
// 2. PostgreSQL outage — same shared-dependency topology, confirmed data and
// the session survive the restart.
// 3. Per-replica PostgreSQL fault — only the selected replica loses its own
// path to the database (temporary pg_hba reject entry for its address plus
// connection termination): that slot leaves rotation, the healthy replica
// keeps serving, and the fault is always undone.
// 4. Pool saturation — a busy shared pool is overload, not a lost dependency:
// the replicas stay in rotation because the probe uses its own connection.
//
// It is opt-in because it needs control over the Docker Compose project:
// make test-dependencies
// cd app && E2E_DEPENDENCY_FAULTS=1 npm run test:dependencies
const enabled = process.env.E2E_DEPENDENCY_FAULTS === '1';
const baseUrl = (process.env.API_BASE_URL ?? 'http://localhost:8080').replace(
/\/+$/u,
'',
);
const composeDir =
process.env.E2E_COMPOSE_DIR ??
fileURLToPath(new URL('../..', import.meta.url));
const composeEnvFile = process.env.E2E_COMPOSE_ENV_FILE ?? '.env';
const redisService = process.env.E2E_REDIS_SERVICE ?? 'redis';
const postgresService = process.env.E2E_POSTGRES_SERVICE ?? 'postgres';
const apiService = process.env.E2E_API_SERVICE ?? 'api';
const lbStatsUrl =
process.env.E2E_LB_STATS_URL ?? 'http://127.0.0.1:8404/stats;csv';
// PostgreSQL superuser of the stand (compose.yaml, .env); psql runs over the
// container's local socket, so no password is needed here.
const postgresUser = process.env.E2E_POSTGRES_USER ?? 'messenger';
const postgresDatabase = process.env.E2E_POSTGRES_DB ?? 'messenger';
const pgHbaPath =
process.env.E2E_PG_HBA_PATH ?? '/var/lib/postgresql/data/pg_hba.conf';
const pgHbaBackup = `${pgHbaPath}.lab3-partial-fault.bak`;
const password = 'outage-check:пароль🔐';
const runId = randomUUID().replaceAll('-', '').slice(0, 12);
// A request that reaches a stopped database waits for the pool connection
// timeout, so every outage step costs up to DATABASE_CONNECTION_TIMEOUT_MS.
const outagedRequestBudgetMs = 180_000;
const slotBudgetMs = 20_000;
const readyReads = 16;
const saturatingWrites = 60; // больше, чем replicas × DATABASE_POOL_MAX (2 × 10)
const execFileAsync = promisify(execFile);
type Result<T> = { body: T; text: string; response: Response };
type ReplicaProbe = {
instanceId: string | null;
requestId: string | null;
status: number;
text: string;
};
type LbSlot = { addr: string; check: string; name: string; status: string };
async function compose(...args: string[]): Promise<string> {
const result = await execFileAsync(
'docker',
['compose', '--env-file', composeEnvFile, ...args],
{ cwd: composeDir, timeout: 120_000 },
);
return result.stdout.trim();
}
async function docker(...args: string[]): Promise<string> {
const result = await execFileAsync('docker', args, {
cwd: composeDir,
timeout: 60_000,
});
return result.stdout.trim();
}
async function request<T = unknown>(
path: string,
init: RequestInit = {},
): Promise<Result<T>> {
const response = await fetch(`${baseUrl}${path}`, init);
const text = await response.text();
// With every backend out of rotation the answer is the LB's own HTML 503,
// so a body is not guaranteed to be JSON (it always is for API answers).
let body: T | undefined;
try {
body = text ? (JSON.parse(text) as T) : undefined;
} catch {
body = undefined;
}
return { body: body as T, text, response };
}
function json(
body: unknown,
headers: Record<string, string> = {},
): RequestInit {
return {
method: 'POST',
headers: { 'content-type': 'application/json', ...headers },
body: JSON.stringify(body),
};
}
function bearer(token: string): Record<string, string> {
return { authorization: `Bearer ${token}` };
}
// POST messages needs a unique Idempotency-Key in lab3+; outage checks only
// need the write path, not replay semantics.
function messageHeaders(token: string): Record<string, string> {
return {
...bearer(token),
'idempotency-key': randomUUID().replaceAll('-', ''),
};
}
function basic(username: string, secret: string): string {
return `Basic ${Buffer.from(`${username}:${secret}`, 'utf8').toString('base64')}`;
}
// The dependencies recover asynchronously, so readiness is polled instead of
// asserted right after docker compose returns.
async function waitForReadiness(
expected: number,
timeoutMs = 90_000,
): Promise<void> {
const deadline = Date.now() + timeoutMs;
let last: number | string = 'no response';
for (;;) {
try {
const probe = await request('/health/ready');
last = probe.response.status;
if (probe.response.status === expected) return;
} catch (error) {
last = error instanceof Error ? error.message : 'request failed';
}
if (Date.now() > deadline)
throw new Error(
`readiness never became ${expected} within ${timeoutMs}ms (last: ${String(last)})`,
);
await sleep(250);
}
}
async function waitFor(
condition: () => Promise<boolean>,
describe: () => Promise<string>,
timeoutMs: number,
): Promise<void> {
const deadline = Date.now() + timeoutMs;
for (;;) {
if (await condition()) return;
if (Date.now() > deadline)
throw new Error(
`condition not reached within ${timeoutMs}ms: ${await describe()}`,
);
await sleep(250);
}
}
function expectBoundedError(
status: number,
text: string,
requestId: string | null,
): void {
expect(status).toBe(503);
const body = JSON.parse(text) as ApiErrorBody;
expect(body.error.code).toBe('unavailable');
expect(body.error.message).toBe('Service unavailable');
expect(body.error.request_id).toBe(requestId);
// A bounded error must not leak driver details, SQL text or a stack trace.
expect(text).not.toMatch(
/ECONNREFUSED|ECONNRESET|Connection terminated|pg\.|node_modules|at .*\(.+:\d+:\d+\)/u,
);
}
function expectBoundedOutage(result: Result<ApiErrorBody>): void {
expectBoundedError(
result.response.status,
result.text,
result.response.headers.get('x-request-id'),
);
}
// With every backend out of rotation the last hop is the load balancer itself:
// it answers with its own 503 page, so there is no API error body and no
// X-Instance-Id — the request never reached a replica.
function expectLbOutage(result: Result<unknown>): void {
expect(result.response.status).toBe(503);
expect(result.response.headers.get('x-instance-id')).toBeNull();
}
// What a client sees while a shared dependency is down: either the bounded 503
// of a replica that is still in rotation (identified by X-Instance-Id), or the
// LB's own 503 once every replica has left rotation. Never a success.
function expectUnavailableThroughLb(result: Result<ApiErrorBody>): void {
expect(result.response.status).toBe(503);
if (result.response.headers.get('x-instance-id') === null) return;
expectBoundedOutage(result);
}
async function historyOf(
chatId: string,
token: string,
): Promise<Result<Page<Message>>> {
return request<Page<Message>>(
`/api/v1/chats/${chatId}/messages?limit=100`,
{
headers: bearer(token),
},
);
}
async function apiContainers(): Promise<string[]> {
const stdout = await compose('ps', '-q', apiService);
return stdout
.split('\n')
.map((line) => line.trim())
.filter((line) => line.length > 0)
.sort();
}
async function containerIp(container: string): Promise<string> {
return docker(
'inspect',
'-f',
'{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}',
container,
);
}
// The replicas publish no ports, so a single replica is probed from inside its
// own network namespace (loopback).
const probeScript = `
const params = JSON.parse(process.env.LAB3_PROBE);
const port = process.env.APP_PORT || 8080;
const response = await fetch('http://127.0.0.1:' + port + params.path, {
method: params.method || 'GET',
headers: params.headers || {},
body: params.body,
});
const text = await response.text();
console.log(JSON.stringify({
status: response.status,
text,
instanceId: response.headers.get('x-instance-id'),
requestId: response.headers.get('x-request-id'),
}));
`;
type ProbeInit = {
body?: string;
headers?: Record<string, string>;
method?: string;
};
async function probeReplica(
container: string,
path: string,
init: ProbeInit = {},
): Promise<ReplicaProbe> {
const stdout = await docker(
'exec',
'-e',
`LAB3_PROBE=${JSON.stringify({ path, ...init })}`,
container,
'node',
'--input-type=module',
'-e',
probeScript,
);
return JSON.parse(stdout) as ReplicaProbe;
}
async function waitForReplicaReadiness(
container: string,
expected: number,
timeoutMs: number,
): Promise<void> {
let last = 'no probe';
await waitFor(
async () => {
try {
const probe = await probeReplica(container, '/health/ready');
last = `${probe.status} ${probe.text}`;
return probe.status === expected;
} catch (error) {
last = error instanceof Error ? error.message : 'probe failed';
return false;
}
},
async () => last,
timeoutMs,
);
}
function parseCsvLine(line: string): string[] {
const values: string[] = [];
let current = '';
let quoted = false;
for (const character of line) {
if (character === '"') quoted = !quoted;
else if (character === ',' && !quoted) {
values.push(current);
current = '';
} else current += character;
}
values.push(current.replace(/\r$/u, ''));
return values;
}
// Resolved backend slots of the api backend: the unused slots of the
// server-template have no address and are ignored.
async function lbSlots(): Promise<LbSlot[]> {
const response = await fetch(lbStatsUrl);
const lines = (await response.text()).trim().split('\n');
const header = parseCsvLine(lines[0].replace(/^#\s*/u, '')).map((name) =>
name.trim(),
);
const column = (name: string): number => header.indexOf(name);
return lines
.slice(1)
.map(parseCsvLine)
.filter(
(columns) =>
columns[column('pxname')] === 'api' &&
/^api\d+$/u.test(columns[column('svname')] ?? '') &&
(columns[column('addr')] ?? '').length > 0,
)
.map((columns) => ({
addr: columns[column('addr')],
check: columns[column('check_status')],
name: columns[column('svname')],
status: columns[column('status')],
}));
}
async function waitForSlot(
predicate: (slots: LbSlot[]) => boolean,
describe: string,
timeoutMs = slotBudgetMs,
): Promise<LbSlot[]> {
let last = 'no stats';
await waitFor(
async () => {
try {
const slots = await lbSlots();
last = slots
.map(
(slot) =>
`${slot.name}@${slot.addr} ${slot.status}/${slot.check}`,
)
.join(', ');
return slots.length > 0 && predicate(slots);
} catch (error) {
last = error instanceof Error ? error.message : 'stats failed';
return false;
}
},
async () => `${describe} (last: ${last})`,
timeoutMs,
);
return lbSlots();
}
function upSlots(slots: LbSlot[]): LbSlot[] {
return slots.filter((slot) => slot.status === 'UP');
}
async function psql(query: string): Promise<string> {
return dockerExecService(
postgresService,
'psql',
'-U',
postgresUser,
'-d',
postgresDatabase,
'-tA',
'-c',
query,
);
}
// docker exec needs a container, while the suite is configured with Compose
// service names, so the container of the service is resolved first.
async function dockerExecService(
service: string,
...args: string[]
): Promise<string> {
const container = (await compose('ps', '-q', service))
.split('\n')[0]
?.trim();
if (!container) throw new Error(`no container for service ${service}`);
return docker('exec', container, ...args);
}
// Takes away the replica's own path to PostgreSQL without touching the shared
// database: a reject entry for the replica's address becomes the first matching
// line of pg_hba.conf, so its new connections fail while the server stays up
// for everyone else. The file is rewritten through the existing inode (`cat >
// file`) to preserve the owner and mode the server needs to reload it.
async function applyReplicaDatabaseReject(address: string): Promise<void> {
const script = [
`test -f ${pgHbaBackup} || cat ${pgHbaPath} > ${pgHbaBackup}`,
`printf 'host all all ${address}/32 reject\\n' > /tmp/lab3-pg-hba`,
`cat ${pgHbaPath} >> /tmp/lab3-pg-hba`,
`cat /tmp/lab3-pg-hba > ${pgHbaPath}`,
'rm -f /tmp/lab3-pg-hba',
].join('; ');
await dockerExecService(postgresService, 'sh', '-c', script);
await psql('select pg_reload_conf()');
await psql(
`select count(pg_terminate_backend(pid)) from pg_stat_activity where client_addr = '${address}'`,
);
}
// Idempotent restore: also runs from afterAll, so an assertion that failed
// mid-fault cannot leave the stand rejecting one replica.
async function restoreDatabaseAccess(): Promise<void> {
await dockerExecService(
postgresService,
'sh',
'-c',
`if [ -f ${pgHbaBackup} ]; then cat ${pgHbaBackup} > ${pgHbaPath}; rm -f ${pgHbaBackup}; fi`,
);
await psql('select pg_reload_conf()');
}
describe.skipIf(!enabled)('dependency outages', () => {
let user: User;
let token: string;
let chat: Chat;
let message: Message;
let replicas: string[];
beforeAll(async () => {
await compose('up', '-d');
await waitForReadiness(200);
const username = `outage_${runId}`;
const registered = await request<User>(
'/api/v1/users',
json({ username, display_name: 'Отказ зависимости', password }),
);
expect(registered.response.status).toBe(201);
user = registered.body;
const session = await request<SessionResponse>(
'/api/v1/auth/sessions',
{
method: 'POST',
headers: { authorization: basic(username, password) },
},
);
expect(session.response.status).toBe(201);
token = session.body.token;
const created = await request<Chat>(
'/api/v1/chats',
json(
{ title: `outage-${runId}`, member_ids: [user.id] },
bearer(token),
),
);
expect(created.response.status).toBe(201);
chat = created.body;
const sent = await request<Message>(
`/api/v1/chats/${chat.id}/messages`,
json({ text: 'Сообщение до отказа' }, messageHeaders(token)),
);
expect(sent.response.status).toBe(201);
message = sent.body;
replicas = await apiContainers();
expect(replicas.length).toBeGreaterThanOrEqual(2);
await waitForSlot(
(slots) => upSlots(slots).length === replicas.length,
'not every replica is UP',
30_000,
);
}, outagedRequestBudgetMs);
afterAll(async () => {
// Always restore the stand, even when an assertion failed mid-outage:
// first the services (pg_hba is only reachable in a running container),
// then the temporary per-replica rule, then rotation.
await compose('start', redisService);
await compose('start', postgresService);
await waitForReadiness(200);
await restoreDatabaseAccess();
const expected = (await apiContainers()).length;
await waitForSlot(
(slots) => upSlots(slots).length === expected,
'backends did not return to rotation',
30_000,
);
}, outagedRequestBudgetMs);
it(
'keeps every replica in rotation while the database pool is saturated',
async () => {
// A row lock on the chat parks every write in the shared pool; the
// readiness probe uses its own connection and must keep answering.
const lock = psql(
`begin; select id from chats where id = '${chat.id}' for update; select pg_sleep(4); commit;`,
);
await sleep(300);
const statuses = new Set<string>();
let sampling = true;
const sampler = (async () => {
while (sampling) {
for (const slot of await lbSlots()) statuses.add(slot.status);
await sleep(200);
}
})();
const writes = await Promise.all(
Array.from({ length: saturatingWrites }, () =>
request(
`/api/v1/chats/${chat.id}/messages`,
json({ text: 'saturation' }, messageHeaders(token)),
),
),
);
await lock;
await sleep(1000);
sampling = false;
await sampler;
expect([...statuses]).toEqual(['UP']);
expect(
writes
.map((write) => write.response.status)
.filter((status) => status !== 201),
).toEqual([]);
},
outagedRequestBudgetMs,
);
it(
'serves bounded 503 for the Redis outage and recovers the session',
async () => {
await compose('stop', redisService);
const replica = replicas[0];
expect((await probeReplica(replica, '/health/live')).status).toBe(
200,
);
await waitForReplicaReadiness(replica, 503, 30_000);
const readiness = await probeReplica(replica, '/health/ready');
expectBoundedError(
readiness.status,
readiness.text,
readiness.requestId,
);
const me = await probeReplica(replica, '/api/v1/users/me', {
headers: bearer(token),
});
expectBoundedError(me.status, me.text, me.requestId);
// A request without a session must stay unauthorized during an outage:
// the outage may not turn an anonymous caller into a trusted one.
const anonymous = await probeReplica(replica, '/api/v1/chats', {
headers: { 'x-user-id': user.id },
});
expect(anonymous.status).toBe(401);
expect(
(JSON.parse(anonymous.text) as ApiErrorBody).error.code,
).toBe('unauthorized');
expectUnavailableThroughLb(
await request<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(token),
}),
);
await waitForSlot(
// 'UP 1/2' is still in rotation: wait for DOWN itself.
(slots) => slots.every((slot) => slot.status === 'DOWN'),
'not every slot left rotation',
);
expectLbOutage(
await request('/api/v1/users/me', { headers: bearer(token) }),
);
await compose('start', redisService);
await waitForReadiness(200);
await waitForSlot(
(slots) => upSlots(slots).length === replicas.length,
'backends did not return to rotation',
30_000,
);
// Sessions live in Redis with persistence, so the old token still works.
const recovered = await request<User>('/api/v1/users/me', {
headers: bearer(token),
});
expect(recovered.response.status).toBe(200);
expect(recovered.body.id).toBe(user.id);
const history = await historyOf(chat.id, token);
expect(history.response.status).toBe(200);
expect(history.body.items.map((item) => item.id)).toContain(
message.id,
);
},
outagedRequestBudgetMs,
);
it(
'serves bounded 503 for the PostgreSQL outage and keeps confirmed data',
async () => {
await compose('stop', postgresService);
const replica = replicas[0];
expect((await probeReplica(replica, '/health/live')).status).toBe(
200,
);
await waitForReplicaReadiness(replica, 503, 30_000);
const readiness = await probeReplica(replica, '/health/ready');
expectBoundedError(
readiness.status,
readiness.text,
readiness.requestId,
);
// Redis still answers, so these requests reach the database layer and
// must fail with the bounded 503, not an unhandled 500.
const me = await probeReplica(replica, '/api/v1/users/me', {
headers: bearer(token),
});
expectBoundedError(me.status, me.text, me.requestId);
const chats = await probeReplica(replica, '/api/v1/chats', {
headers: bearer(token),
});
expectBoundedError(chats.status, chats.text, chats.requestId);
const history = await probeReplica(
replica,
`/api/v1/chats/${chat.id}/messages?limit=100`,
{ headers: bearer(token) },
);
expectBoundedError(history.status, history.text, history.requestId);
const registration = await probeReplica(replica, '/api/v1/users', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
username: `outage_${runId}_late`,
display_name: 'Отказ зависимости',
password,
}),
});
expectBoundedError(
registration.status,
registration.text,
registration.requestId,
);
expectUnavailableThroughLb(
await request<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(token),
}),
);
await waitForSlot(
// 'UP 1/2' is still in rotation: wait for DOWN itself.
(slots) => slots.every((slot) => slot.status === 'DOWN'),
'not every slot left rotation',
);
expectLbOutage(
await request('/api/v1/users/me', { headers: bearer(token) }),
);
await compose('start', postgresService);
await waitForReadiness(200);
await waitForSlot(
(slots) => upSlots(slots).length === replicas.length,
'backends did not return to rotation',
30_000,
);
const recovered = await request<User>('/api/v1/users/me', {
headers: bearer(token),
});
expect(recovered.response.status).toBe(200);
expect(recovered.body.id).toBe(user.id);
const after = await historyOf(chat.id, token);
expect(after.response.status).toBe(200);
expect(after.body.items.map((item) => item.id)).toContain(
message.id,
);
const sent = await request<Message>(
`/api/v1/chats/${chat.id}/messages`,
json({ text: 'Сообщение после отказа' }, messageHeaders(token)),
);
expect(sent.response.status).toBe(201);
},
outagedRequestBudgetMs,
);
it(
'excludes only the replica that lost its own database path',
async () => {
const selected = replicas[0];
const healthy = replicas[1];
const selectedIp = await containerIp(selected);
const selectedAddress = `${selectedIp}:8080`;
const selectedInstance = (
await probeReplica(selected, '/health/live')
).instanceId;
expect(selectedInstance).not.toBeNull();
const healthyInstance = (
await probeReplica(healthy, '/health/live')
).instanceId;
try {
await applyReplicaDatabaseReject(selectedIp);
const faultAt = Date.now();
await waitForReplicaReadiness(selected, 503, 30_000);
expect(
(await probeReplica(healthy, '/health/ready')).status,
).toBe(200);
// Only the affected slot leaves rotation. While `fall 2` counts the
// failed checks the slot passes through "UP 1/2 (L7STS)", so the
// wait is for DOWN itself, not for "no longer plain UP".
const slots = await waitForSlot(
(candidates) =>
upSlots(candidates).length === replicas.length - 1 &&
candidates.some(
(slot) =>
slot.addr === selectedAddress &&
slot.status === 'DOWN',
),
`selected slot ${selectedAddress} did not go down`,
30_000,
);
// inter 500 ms × fall 2 + timeout check 500 ms + polling step 250 ms.
expect(Date.now() - faultAt).toBeLessThan(3_000);
expect(
slots.find((slot) => slot.addr === selectedAddress)?.status,
).toBe('DOWN');
const served = new Set<string>();
for (let index = 0; index < readyReads; index += 1) {
const read = await historyOf(chat.id, token);
expect(read.response.status).toBe(200);
served.add(
read.response.headers.get('x-instance-id') ?? 'unknown',
);
}
expect(served.has(selectedInstance as string)).toBe(false);
expect(served.has(healthyInstance as string)).toBe(true);
} finally {
await restoreDatabaseAccess();
}
await waitForReplicaReadiness(selected, 200, 30_000);
await waitForSlot(
(slots) =>
upSlots(slots).length === replicas.length &&
slots.some(
(slot) =>
slot.addr === selectedAddress &&
slot.status === 'UP',
),
'restored replica did not return to rotation',
30_000,
);
let servedAgain = false;
for (
let index = 0;
index < readyReads * 2 && !servedAgain;
index += 1
) {
const read = await historyOf(chat.id, token);
expect(read.response.status).toBe(200);
servedAgain =
read.response.headers.get('x-instance-id') ===
selectedInstance;
}
expect(servedAgain).toBe(true);
},
outagedRequestBudgetMs,
);
});
+8
View File
@@ -0,0 +1,8 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": "./src"
},
"include": ["src"],
"exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}
+22
View File
@@ -0,0 +1,22 @@
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"resolvePackageJsonExports": true,
"esModuleInterop": true,
"isolatedModules": true,
"declaration": true,
"removeComments": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"allowSyntheticDefaultImports": true,
"target": "ES2023",
"sourceMap": true,
"outDir": "./dist",
"incremental": true,
"skipLibCheck": true,
"strict": true,
"strictPropertyInitialization": false,
"types": ["vitest/globals", "node"]
}
}
+14
View File
@@ -0,0 +1,14 @@
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
globals: true,
root: './',
include: ['test/*.e2e-spec.ts'],
testTimeout: 30_000,
hookTimeout: 30_000,
sequence: { concurrent: false },
},
});
+13
View File
@@ -0,0 +1,13 @@
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
// Resolves the path aliases declared in tsconfig.json, including the ones
// added by `nest g library`.
plugins: [tsconfigPaths()],
test: {
globals: true,
root: './',
include: ['**/*.spec.ts'],
},
});
+177
View File
@@ -0,0 +1,177 @@
# Стенд lab3: клиент -> HAProxy -> API x N -> общие PostgreSQL и Redis.
# Одна команда запуска: make stand-up (docker compose --env-file .env up -d --build --wait)
#
# Проект запинен именем, чтобы имена контейнеров и labels были предсказуемы для
# scripts/stop-one.sh; container_name нигде не задан, иначе масштабирование
# одного Compose-service стало бы невозможным.
name: mtusi-lab3
services:
postgres:
image: postgres:16.4-alpine
# pg_stat_statements включён для трека 1 (агрегаты SQL по репликам);
# max_connections поднят под N x DATABASE_POOL_MAX.
command:
[
'postgres',
'-c',
'shared_preload_libraries=pg_stat_statements',
'-c',
'max_connections=120',
'-c',
'shared_buffers=128MB',
'-c',
'effective_cache_size=384MB',
]
environment:
POSTGRES_DB: ${POSTGRES_DB:-messenger}
POSTGRES_USER: ${POSTGRES_USER:-messenger}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
# Только loopback: операторские проверки (host-side npm run test:e2e,
# psql в evidence). API-реплики портов не публикуют вовсе.
ports:
- '127.0.0.1:${POSTGRES_PUBLISHED_PORT:-5432}:5432'
volumes:
- postgres-data:/var/lib/postgresql/data
deploy:
resources:
limits:
cpus: '${PG_CPUS:-1.5}'
memory: ${PG_MEMORY:-512m}
healthcheck:
test:
[
'CMD-SHELL',
'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}',
]
interval: 5s
timeout: 3s
retries: 20
redis:
image: redis:7.4.2-alpine
# appendonly: сессии и кэш переживают рестарт контейнера (проверка
# сохранности с неизменным токеном). volatile-lru вытесняет только
# ключи с TTL; в стенде у них ограниченный набор и объём.
command:
[
'redis-server',
'--appendonly',
'yes',
'--appendfsync',
'everysec',
'--maxmemory',
'96mb',
'--maxmemory-policy',
'volatile-lru',
]
ports:
- '127.0.0.1:${REDIS_PUBLISHED_PORT:-6379}:6379'
volumes:
- redis-data:/data
deploy:
resources:
limits:
cpus: '${REDIS_CPUS:-0.25}'
memory: ${REDIS_MEMORY:-128m}
healthcheck:
test: ['CMD', 'redis-cli', 'ping']
interval: 5s
timeout: 3s
retries: 20
# Миграции выполняются один раз отдельным сервисом, а не гонкой реплик:
# api стартует только после его успешного завершения.
migrate:
build:
context: .
dockerfile: Dockerfile
image: ${API_IMAGE:-mtusi-messenger:lab3}
command: ['node', 'dist/database/migration.runner.js']
env_file: [.env]
deploy:
resources:
limits:
cpus: '0.5'
memory: 192m
depends_on:
postgres: { condition: service_healthy }
redis: { condition: service_healthy }
restart: 'no'
api:
build:
context: .
dockerfile: Dockerfile
args:
BUILD_ID: ${BUILD_ID:-unknown}
image: ${API_IMAGE:-mtusi-messenger:lab3}
# Портов нет намеренно: единственная точка входа — HAProxy.
env_file: [.env]
environment:
DATABASE_POOL_MAX: ${DATABASE_POOL_MAX:-10}
CACHE_MODE: ${CACHE_MODE:-protected}
CACHE_MISS_DELAY_MS: ${CACHE_MISS_DELAY_MS:-0}
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
# Бюджет пробы готовности; LB проверяет ту же ручку с timeout check 500 ms.
HEALTH_TIMEOUT_MS: ${HEALTH_TIMEOUT_MS:-400}
# Дрейн длиннее обнаружения отказа LB (500 ms x fall 2 ≈ 1 s).
DRAIN_DELAY_MS: ${DRAIN_DELAY_MS:-3000}
deploy:
replicas: ${API_REPLICAS:-2}
resources:
limits:
cpus: '${API_CPUS_PER_REPLICA:-1.5}'
memory: ${API_MEMORY_PER_REPLICA:-768m}
stop_grace_period: 20s
restart: unless-stopped
depends_on:
migrate: { condition: service_completed_successfully }
postgres: { condition: service_healthy }
redis: { condition: service_healthy }
healthcheck:
test:
[
'CMD',
'node',
'-e',
"fetch('http://127.0.0.1:'+ (process.env.APP_PORT||8080) + '/health/ready').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))",
]
interval: 5s
timeout: 3s
retries: 20
haproxy:
image: haproxy:3.2-alpine
ports:
- '${APP_PUBLIC_PORT:-8080}:8080'
# Страница статистики — интерфейс LB, публикуется только на loopback.
- '127.0.0.1:${LB_STATS_PORT:-8404}:8404'
volumes:
- ./infra/haproxy/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
deploy:
resources:
limits:
cpus: '${LB_CPUS:-0.25}'
memory: ${LB_MEMORY:-128m}
depends_on:
api: { condition: service_healthy }
# Генератор нагрузки запускается только явно: --profile load
loadgen:
image: grafana/k6:0.54.0
profiles: ['load']
volumes:
- ./scripts/load:/load:ro
command: ['run', '/load/write-ladder.js']
deploy:
resources:
limits:
cpus: '${LOADGEN_CPUS:-1.5}'
memory: ${LOADGEN_MEMORY:-256m}
depends_on:
haproxy: { condition: service_healthy }
volumes:
postgres-data:
redis-data:
+76 -2
View File
@@ -1,5 +1,79 @@
# Доказательства
Храните небольшие обезличенные результаты: команды и stdout проверок, JSON/CSV агрегатов нагрузки, EXPLAIN, dashboard JSON, текст разбора отказа. Укажите дату, commit, аппаратные лимиты и профиль нагрузки.
Небольшие обезличенные результаты: команды и stdout проверок, агрегаты нагрузки,
состояния контейнеров. В файлах нет `.env`, session tokens, cookies, приватных
ключей, паролей и реальных сообщений: все данные синтетические, пользователи
создаются тестами с случайными именами. Полные условия измерения каждого прогона
(лимиты, образ и его id, `X-Instance-Id` → контейнер, версии, объём данных, фон
хоста) лежат в `track1/raw/<label>.manifest.json`; сырые наблюдения сэмплера —
в сжатых `*.samples.jsonl.gz`.
Не добавляйте .env, session tokens, cookies, приватные ключи, credentials, реальные сообщения, raw dumps и signed URLs. Для скриншотов скрывайте секреты. Большие логи/бинарные traces сохраняйте отдельно по правилам преподавателя; одного скриншота без методики недостаточно.
## Уровень 3
| Файл | Что подтверждает | Как воспроизвести |
| --- | --- | --- |
| `level3/smoke.txt` | публичный smoke lab3 проходит через LB (идемпотентность, `X-Instance-Id`), `docker compose ps` содержит ≥2 реплики | `make test` |
| `level3/persistence.txt` | после `scripts/restart.sh` перезапущены postgres, redis, api ×2, haproxy (StartedAt до/после), данные и прежний токен целы | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` |
| `level3/failover-mtusi-lab3-api-1.txt` | остановлена именно эта реплика: `docker ps` до/после, `TARGET_INSTANCE_ID`, переходы слотов HAProxy (`UP → DOWN (L7STS) → MAINT (resolution)`) с отметками времени, `observed_instances_before=2`, 130 записей во время отказа, `first_recovery_seconds≈3.3` | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (затем `scripts/start-replica.sh`) |
| `level3/failover-mtusi-lab3-api-2.txt` | то же для второй реплики (проверены обе) | то же, повтор после восстановления |
| `level3/clean-clone.txt` | стенд поднимается с нуля из чистого clone (миграции с пустого тома), проходят smoke, сохранность и отказ реплики | `git clone -b lab3 … && cp .env.example .env && docker compose down -v && make stand-up && make test && make test-persistence && make test-failover` |
## Уровень 4
| Файл | Что подтверждает | Как воспроизвести |
| --- | --- | --- |
| `level4/spread.json` | один токен обслуживается двумя репликами (20/20 запросов), карта `X-Instance-Id` → контейнер | `python3 scripts/lab3/lab3.py check spread --requests 40` |
| `level4/idempotency-concurrency.txt` | 4 теста идемпотентности, включая 8 параллельных POST с одним ключом через LB: одно сообщение, один id; другой body → 409; без ключа → 400 | `python3 scripts/lab3/lab3.py check idempotency` |
| `level4/failover-sweep.json`, `.md` | отказ каждой реплики под нагрузкой 200 req/s: 0 ошибок клиента и LB, 0 дублей, 0 потерянных подтверждений, реплика возвращается за 3.4–3.9 s, HAProxy помечает узел `DOWN` | `python3 scripts/lab3/lab3.py failover --replicas all --rate 200 --duration 60` |
| `level4/rolling-update.json`, `.md` | поочерёдная замена реплик под нагрузкой: `BUILD_ID`/image id меняются по шагам, 0 ответов 5xx из 884 попыток, `migrate` не перезапускался | `python3 scripts/lab3/lab3.py rolling-update --under-load --rate 200 --build-id <id>` |
| `level4/idempotency-gc.txt` | операторский GC удаляет ровно просроченную запись журнала идемпотентности и не трогает свежую | `docker compose --env-file .env exec -T api node dist/messages/idempotency/idempotency-gc.cli.js` |
| `level4/dependency-faults.txt` | четыре сценария: общий отказ Redis и PostgreSQL (реплика отвечает ограниченным `503 unavailable` с `request_id`, неготовыми становятся все реплики, LB выводит их из ротации и отвечает своим `503`, `401` без сессии остаётся), локальный отказ БД у одной реплики (из ротации уходит только она, `DOWN` менее чем за 3 s), насыщение пула (слоты остаются `UP`, все записи `201`); после возврата зависимости данные и сессия целы | `make test-dependencies` |
| `level4/limits-and-ports.txt` | лимиты CPU/RAM каждого контейнера, отсутствие опубликованных портов у реплик API, отсутствие `container_name`, отсутствие секретов в трекаемых файлах | см. команды внутри файла |
## Трек 1 (`track1/`)
`track1/raw/<label>.*` — по каждому прогону:
| Файл | Содержимое |
| --- | --- |
| `<label>.k6.json` | сводка генератора: по каждому шагу предложенный темп, **успешный RPS** (`successful_rps` — ответы ожидаемого класса) и частота ответов (`attempted_rps` — все ответы, включая ошибки), классы `2xx/4xx/5xx/other`, p50/p95/p99, активные VU, `dropped_iterations` |
| `<label>.samples.jsonl.gz` | поток наблюдений: `docker stats` (CPU/RAM контейнеров), статистика HAProxy (запросы, очередь, статусы слотов с отметками времени), `/internal/metrics` каждой реплики, `pg_stat_database`/`pg_stat_activity`/`pg_stat_statements`, фон хоста |
| `<label>.manifest.json` | условия измерения: лимиты, число реплик, образ и его id, `X-Instance-Id` → контейнер, версии образов и рантаймов, объём данных, состояния томов, фон хоста, commit |
| `<label>.phases.json` | временные метки фаз (для отказов и rolling update) |
Метки: `p-a#nN#repR` — серия A (профиль p-a, N реплик, повтор R); `p-b#n4` — горячий
чат; `p-c#lbX` — путь чтения при лимите LB X CPU; `ab#A#repR` / `ab#B#repR` — A/B
двух образов; `abdiag#A#repR` /
`abdiag#B#repR` — контрольный A/B на бюджете по умолчанию; `vuswap#nN-vuM` —
проверка потолка генератора (та же конфигурация, другой `MAX_VUS`); `block#…#repR`
(900 req/s) — блок «почему» около колена; `why#…#repR` (1500 req/s) — блок «почему»
и серия роста ресурсов: один темп, разные распределения того же бюджета;
`probecheck#n4#rep1` — контроль пробы готовности под перегрузкой; `knee#nN` —
лестница 900–2200 req/s на текущей
сборке; `failover#<instance>`, `rolling` — сценарии отказов.
Сводные документы (пересобираются из raw командой
`python3 scripts/lab3/lab3.py analyze`):
| Файл | Содержимое |
| --- | --- |
| `track1/summary-runs.md` | разбор каждого прогона: шаги, ресурсы контейнеров, PostgreSQL, LB, счётчики реплик |
| `track1/summary-series-a.md` | серия 1/2/4 реплики: успешный RPS, частота ответов, латентность, точки сатурации, ресурсы при разных конфигурациях |
| `track1/summary-diagnostics.md` | горячий чат (p-b) и путь чтения (p-c) при разных лимитах LB |
| `track1/summary-growth.md` | серия роста ресурсов — блок `why#` на 1500 req/s: контроль `why#n4`, Δ каждой точки и вердикт; несопоставимые по манифестам точки — в разделе «Вне сравнения» с причиной |
| `track1/summary-probe-check.md` | проба готовности под перегрузкой: контрольный прогон `probecheck#n4` против `why#n4`, статусы слотов LB, 5xx, Δ успешного RPS |
| `track1/summary-ab.md`, `track1/summary-ab-abdiag.md` | A/B до/после оптимизации: медианы успешного RPS, разброс по повторам, частота ответов как диагностика, вывод «подтверждено/не подтверждено»; `abdiag` — контрольная серия на бюджете по умолчанию (бюджет записан в `ab-verdict*.json`) |
| `track1/ab-verdict.json`, `track1/ab-verdict-abdiag.json` | вердикт A/B по шагам (успешный RPS, min/max, частота ответов, классы отказов по сторонам), бюджет серии, хеш коммита, образы сторон |
| `track1/summary-mechanism.md` | разрез «почему»: один темп, разные конфигурации/число реплик, ожидания сессий PostgreSQL (`Lock`/`tuple`/`transactionid`), дельты `pg_stat_statements` по операторам, CPU контейнеров, пер-реплики латентности |
| `track1/statement-deltas.md` | доказательство «8 → 1 обращение»: дельта вызовов и времени по операторам за прогон (A: три оператора ×18 629 вызовов, 95 ms среднего на `UPDATE chats`; B: один составной оператор, 2.35 ms) |
| `track1/graphs/*.png` | графики: пропускная способность, латентность и ошибки, занятость генератора, CPU контейнеров во времени, распределение по слотам LB, рост ресурсов, A/B |
Правила интерпретации: `dropped_iterations > 0` вместе с ростом p95 означает
перегрузку сервера; `dropped_iterations > 0` при низком p95 и упоре генератора в
свой CPU-лимит означает, что узкое место — генератор, а не стенд (занятость
генератора видна на `graphs/*vus*.png` и в CPU `loadgen`). Пропускная способность
сравнивается по **успешному** RPS: частота ответов (`attempted_rps`) растёт и тогда,
когда сервис отвечает отказами, поэтому она годится только как диагностика.
Регрессия аналитики (успешный RPS не подменяется частотой ответов; рост сравнивается
только внутри одного блока `why#` на одном темпе) лежит в `tests/test_lab3_analytics.py` и запускается
`make test-analytics` без стенда.
+40
View File
@@ -0,0 +1,40 @@
=== Проверка воспроизводимости из чистого clone (шаг 16 плана)
captured_at 2026-10-15T20:15:56Z
клон: git clone -b lab3 <repo> /tmp/lab3-clean; коммит: 2950b77967bdd852431ae5592bd9d9b72dac4671
команды: cp .env.example .env (свои POSTGRES_PASSWORD, DATABASE_URL, METRICS_TOKEN);
docker compose --env-file .env down -v # чистые тома, схема создаётся миграциями
make stand-up && make wait-ready && make test && make test-persistence && make test-failover
Container mtusi-lab3-api-2 Starting
Container mtusi-lab3-api-2 Started
Container mtusi-lab3-api-1 Waiting
Container mtusi-lab3-api-2 Waiting
Container mtusi-lab3-api-1 Healthy
Container mtusi-lab3-api-2 Healthy
Container mtusi-lab3-haproxy-1 Starting
Container mtusi-lab3-haproxy-1 Started
Container mtusi-lab3-postgres-1 Waiting
Container mtusi-lab3-redis-1 Waiting
Container mtusi-lab3-migrate-1 Waiting
Container mtusi-lab3-api-1 Waiting
Container mtusi-lab3-api-2 Waiting
Container mtusi-lab3-haproxy-1 Waiting
Container mtusi-lab3-postgres-1 Healthy
Container mtusi-lab3-redis-1 Healthy
Container mtusi-lab3-migrate-1 Exited
Container mtusi-lab3-haproxy-1 Healthy
Container mtusi-lab3-api-1 Healthy
Container mtusi-lab3-api-2 Healthy
stand is ready (http://localhost:8080)
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
=== make test PASS в чистом clone
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
=== test-persistence PASS в чистом clone
{"observed_instances_before": 2, "successful_writes": 129, "failed_attempts": 0, "first_recovery_seconds": 3.287}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
Container mtusi-lab3-api-2 Running
Container mtusi-lab3-api-1 Starting
Container mtusi-lab3-api-1 Started
Итог: стенд поднимается с нуля (миграции применяются с пустого тома), публичный
smoke lab3, проверка сохранности и отказ одной реплики проходят без правок репозитория.
@@ -0,0 +1,23 @@
=== failover одной реплики: остановлена mtusi-lab3-api-1 (прогон 4)
commit: 410e1ea3ad1b12b1bc650484c3531e6bf76479be
captured_at 2026-10-15T18:29:41Z
--- api-реплики до теста:
4579bce31e8d mtusi-lab3-api-1
77b49a240814 mtusi-lab3-api-2
python3 tests/resilience.py --mode failover --action-script "scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 130, "failed_attempts": 0, "first_recovery_seconds": 3.436}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
--- api-реплики после теста:
77b49a240814 mtusi-lab3-api-2
--- цель TARGET_INSTANCE_ID = 4579bce31e8d; hostname контейнера = X-Instance-Id, остановка docker stop --time 10 (SIGTERM -> дрейн 3s)
--- HAProxy: переходы статусов backend-слотов во время теста:
2026-10-15T18:28:56Z api1 addr=172.30.0.5:8080 status=UP check=L7OK
2026-10-15T18:28:56Z api2 addr=172.30.0.4:8080 status=UP check=L7OK
2026-10-15T18:28:57Z api1 addr=172.30.0.5:8080 status=DOWN check=L7STS
2026-10-15T18:29:00Z api1 addr=172.30.0.5:8080 status=DOWN check=* L7STS
2026-10-15T18:29:01Z api1 addr= status=MAINT (resolution) check=
@@ -0,0 +1,23 @@
=== failover одной реплики: остановлена mtusi-lab3-api-2 (прогон 1)
commit: 410e1ea3ad1b12b1bc650484c3531e6bf76479be
captured_at 2026-10-15T18:26:23Z
--- api-реплики до теста:
4579bce31e8d mtusi-lab3-api-1
77b49a240814 mtusi-lab3-api-2
python3 tests/resilience.py --mode failover --action-script "scripts/stop-one.sh" --base-url "http://localhost:8080"
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 130, "failed_attempts": 0, "first_recovery_seconds": 3.294}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
--- api-реплики после теста:
4579bce31e8d mtusi-lab3-api-1
--- цель TARGET_INSTANCE_ID = 77b49a240814 (hostname контейнера совпадает с X-Instance-Id, docker stop --time 10)
--- HAProxy: переходы статусов во время теста:
2026-10-15T18:25:37Z api1 addr=172.30.0.5:8080 status=UP check=L7OK
2026-10-15T18:25:37Z api2 addr=172.30.0.4:8080 status=UP check=L7OK
2026-10-15T18:25:39Z api2 addr=172.30.0.4:8080 status=UP 1/2 check=L7STS
2026-10-15T18:25:39Z api2 addr=172.30.0.4:8080 status=DOWN check=L7STS
2026-10-15T18:25:42Z api2 addr= status=MAINT (resolution) check=
+14
View File
@@ -0,0 +1,14 @@
=== make test-persistence ACTION_SCRIPT=scripts/restart.sh
captured_at 2026-10-15T23:59:23Z
commit: e38795d0a39c20960049f84bf6b301832804964d
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
--- docker compose ps после теста:
api mtusi-lab3-api-3 Up 5 seconds (healthy)
api mtusi-lab3-api-4 Up 5 seconds (healthy)
haproxy mtusi-lab3-haproxy-1 Up 8 seconds
postgres mtusi-lab3-postgres-1 Up 8 seconds (healthy)
redis mtusi-lab3-redis-1 Up 8 seconds (healthy)
+13
View File
@@ -0,0 +1,13 @@
=== make test (публичный smoke lab3)
captured_at 2026-10-15T23:57:20Z
commit: e38795d0a39c20960049f84bf6b301832804964d
api mtusi-lab3-api-3 Up 2 minutes (healthy)
api mtusi-lab3-api-4 Up 2 minutes (healthy)
api mtusi-lab3-api-5 Up 2 minutes (healthy)
api mtusi-lab3-api-6 Up 2 minutes (healthy)
haproxy mtusi-lab3-haproxy-1 Up 4 hours
postgres mtusi-lab3-postgres-1 Up 4 hours (healthy)
redis mtusi-lab3-redis-1 Up 4 hours (healthy)
python3 tests/smoke.py --base-url "http://localhost:8080"
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
+40
View File
@@ -0,0 +1,40 @@
=== make test-dependencies (отказы Redis и PostgreSQL; общая зависимость, локальный путь к БД у одной реплики, насыщение пула)
captured_at 2026-10-16T19:18:14Z
commit: 1b4aac7
cd app && E2E_COMPOSE_DIR="/home/tomato/Projects/VP/mtusi2026lab3" E2E_COMPOSE_ENV_FILE=".env" npm run test:dependencies
> app@0.0.1 test:dependencies
> E2E_DEPENDENCY_FAULTS=1 vitest run --config ./vitest.config.e2e.ts dependency-failures
The plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. You can remove the plugin and set resolve.tsconfigPaths: true in your Vite config instead.
RUN v4.1.11 /home/tomato/Projects/VP/mtusi2026lab3/app
Test Files 1 passed (1)
Tests 4 passed (4)
Start at 22:18:15
Duration 38.20s (transform 80ms, setup 0ms, import 95ms, tests 38.01s, environment 0ms)
--- docker compose ps после теста (все реплики вернулись, зависимости снова работают):
api mtusi-lab3-api-3 running healthy
api mtusi-lab3-api-4 running healthy
haproxy mtusi-lab3-haproxy-1 running
postgres mtusi-lab3-postgres-1 running healthy
redis mtusi-lab3-redis-1 running healthy
--- слоты HAProxy после теста (проверка GET /health/ready, timeout check 500 ms):
api1 172.30.0.5:8080 status=UP L7OK 200 last_chk=
api2 172.30.0.4:8080 status=UP L7OK 200 last_chk=
--- pg_hba.conf после теста (временная reject-строка снята, владелец и режим не менялись):
-rw------- 1 postgres postgres 5743 Oct 16 19:18 /var/lib/postgresql/data/pg_hba.conf
ls: /var/lib/postgresql/data/pg_hba.conf.lab3-partial-fault.bak: No such file or directory
--- HEALTH_TIMEOUT_MS действующей реплики (бюджет пробы готовности):
HEALTH_TIMEOUT_MS=400 DRAIN_DELAY_MS=3000
11:# пула) меньше timeout check 500 ms, который равен интервалу inter. Обнаружение
50: option httpchk GET /health/ready
52: timeout check 500ms
File diff suppressed because it is too large Load Diff
+9
View File
@@ -0,0 +1,9 @@
# Отказ каждой реплики под нагрузкой
| реплика | контейнер | попыток пробы | успешных | ошибок в отказе | остановка контейнера, s | первый успех после остановки, s | реплика вернулась, s | LB DOWN | RPS до | RPS в окне остановки | ошибок в окне | RPS без реплики | RPS после | k6 успешный RPS | k6 ошибок | дубли | потери |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 18e28d666159 | 18e28d666159 | 295 | 295 | 0 | 3.25 | 0.21 | 3.92 | 19:19:07 | 4.87 | 4.91 | 0 | 4.87 | 4.85 | 200 | 0 | 0 | 0 |
| ec6ad0632ac0 | ec6ad0632ac0 | 294 | 294 | 0 | 3.3 | 0.1 | 3.4 | 19:20:13 | 4.87 | 5.0 | 0 | 10.09 | 4.84 | 200.02 | 0 | 0 | 0 |
Проба: последовательные POST с интервалом 0.2 s, при неопределённом результате повтор с тем же Idempotency-Key (как у реального клиента). «Окно остановки» — от команды docker stop до первого успеха после выхода контейнера (сюда попадает дрейн); «RPS без реплики» — от выхода контейнера до первого успеха после него, при корректном дреине это доли секунды. Ошибок не должно быть ни в одном из окон, потери и дубли проверяются по истории чата.
@@ -0,0 +1,18 @@
=== e2e-фильтр идемпотентности (конкурентный повтор через LB)
captured_at 2026-10-15T23:56:58Z
commit e38795d0a39c20960049f84bf6b301832804964d
> app@0.0.1 test:e2e
> vitest run --config ./vitest.config.e2e.ts -t idempotency
RUN v4.1.11 /home/tomato/Projects/VP/mtusi2026lab3/app
Test Files 1 passed | 1 skipped (2)
Tests 5 passed | 12 skipped (17)
Start at 02:56:53
Duration 4.94s (transform 113ms, setup 0ms, import 353ms, tests 4.54s, environment 0ms)
The plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. You can remove the plugin and set resolve.tsconfigPaths: true in your Vite config instead.
+18
View File
@@ -0,0 +1,18 @@
=== Операторский GC журнала идемпотентности (проверка детерминированного SQL)
captured_at 2026-10-15T20:25:04Z
commit: 06431d824bea50776d91836fded8788f3066f877
Сценарий: в журнал вставлены две записи одного пользователя — просроченная
(created_at = now() - 2 days) и свежая (created_at = now()); затем выполнен
операторский прогон GC внутри контейнера API и проверено, что удалена ровно
просроченная запись. Команда (из корня репозитория):
docker compose --env-file .env exec -T api node dist/messages/idempotency/idempotency-gc.cli.js
На хосте без Docker: npm run idempotency:gc (нужен доступный DATABASE_URL).
--- вставка записей: INSERT 0 1 / INSERT 0 1, всего 2
--- вывод GC: Purged 1 idempotency key(s) older than 86400 seconds
--- проверка после GC: expired_left=0, fresh_left=1 (свежая запись не тронута)
Порог берётся из IDEMPOTENCY_TTL_SECONDS (по умолчанию 86400 s = 24 ч, как
требует контракт); фоновый проход с тем же SQL выполняется на реплике не чаще
одного раза на 512 успешных записей под pg_try_advisory_xact_lock.
+33
View File
@@ -0,0 +1,33 @@
=== Лимиты, порты, секреты, container_name (критерий уровня 4)
captured_at 2026-10-15T20:13:59Z
commit: 5a5a8fe5cb0eb5f2848e79462c37d109b2367e49
--- docker inspect: лимиты, образ и публикуемые порты каждого контейнера стенда
api mtusi-lab3-api-2 cpus=1500000000 mem_bytes=805306368 bindings=map[] image=sha256:08d15150aa588f9b9a2da7f3992c858e32f9c761d85ce3a9e5e583c9311c05f9 build=DRAIN_DELAY_MS=3000
api mtusi-lab3-api-1 cpus=1500000000 mem_bytes=805306368 bindings=map[] image=sha256:08d15150aa588f9b9a2da7f3992c858e32f9c761d85ce3a9e5e583c9311c05f9 build=APP_ENV=lab
haproxy mtusi-lab3-haproxy-1 cpus=250000000 mem_bytes=134217728 bindings=map[8080/tcp:[map[HostIp: HostPort:8080]] 8404/tcp:[map[HostIp:127.0.0.1 HostPort:8404]]] image=sha256:254e6370f01cd654e0744edf607c67f33777c1b6a9dc0d4b28bcba7171460122 build=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
postgres mtusi-lab3-postgres-1 cpus=1500000000 mem_bytes=536870912 bindings=map[5432/tcp:[map[HostIp:127.0.0.1 HostPort:5432]]] image=sha256:5660c2cbfea50c7a9127d17dc4e48543eedd3d7a41a595a2dfa572471e37e64c build=POSTGRES_USER=messenger
redis mtusi-lab3-redis-1 cpus=250000000 mem_bytes=134217728 bindings=map[6379/tcp:[map[HostIp:127.0.0.1 HostPort:6379]]] image=sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952 build=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
--- суммарный лимит RAM стенда, MiB:
2304 MiB
--- публикуемые порты (docker compose ps):
api mtusi-lab3-api-1 8080/tcp
api mtusi-lab3-api-2 8080/tcp
haproxy mtusi-lab3-haproxy-1 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 127.0.0.1:8404->8404/tcp
postgres mtusi-lab3-postgres-1 127.0.0.1:5432->5432/tcp
redis mtusi-lab3-redis-1 127.0.0.1:6379->6379/tcp
--- API-реплики: опубликованные порты и identity:
/mtusi-lab3-api-2 hostname=58cd4a0118d1 bindings=map[]
/mtusi-lab3-api-1 hostname=2dd7b04d4e25 bindings=map[]
--- container_name в конфигурации (ожидается отсутствие):
container_name отсутствует
--- секреты:
.gitignore:2:.env .env
.env не отслеживается git
файлов в git с паролем БД: 0
файлов в git с METRICS_TOKEN: 0
+57
View File
@@ -0,0 +1,57 @@
{
"build_id": "final-1b4aac7",
"build_stderr_tail": [
"#15 unpacking to docker.io/library/mtusi-messenger:lab3",
"#15 unpacking to docker.io/library/mtusi-messenger:lab3 1.8s done",
"#15 DONE 5.0s"
],
"captured_at": "2026-10-16T19:24:40Z",
"commit": "1b4aac7587d3dd849f4d18bcdfac456ef2338376",
"image": "mtusi-messenger:lab3",
"image_id": "sha256:21532b582a7b906713e3b25e3dcb3d0dbc3c4915638167bb6d4c6306896b12de",
"k6": {
"attempted_rps": 200,
"failed": 0,
"successful_rps": 200
},
"migrate": {
"after": "2026-10-16T19:18:16.162376367Z",
"before": "2026-10-16T19:18:16.162376367Z",
"restarted": false
},
"probe": {
"attempts": 884,
"failures": 0,
"server_5xx": 0
},
"replacement_seconds": [
9.76,
9.75
],
"replicas": 2,
"steps": [
{
"migrate_started_at": "2026-10-16T19:18:16.162376367Z",
"new_build_id": "final-1b4aac7",
"new_container": "040cce950896",
"new_instance": "040cce950896",
"old_build_id": "unknown",
"old_container": "18e28d666159",
"old_instance": "18e28d666159",
"replacement_seconds": 9.76,
"step": 1
},
{
"migrate_started_at": "2026-10-16T19:18:16.162376367Z",
"new_build_id": "final-1b4aac7",
"new_container": "0f36b6480431",
"new_instance": "0f36b6480431",
"old_build_id": "unknown",
"old_container": "ec6ad0632ac0",
"old_instance": "ec6ad0632ac0",
"replacement_seconds": 9.75,
"step": 2
}
],
"under_load": true
}

Some files were not shown because too many files have changed in this diff Show More