Files
mtusi2026lab3/app/README.md
T
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

289 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 с проверкой зависимостей + /internal/lb-check
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) |
| `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` | нет | процесс жив |
| `GET /health/ready` | нет | готовность: PostgreSQL и Redis доступны, иначе `503` |
| `GET /internal/lb-check` | нет | проба балансировщика: только флаг дрейна, без обращения к БД/Redis |
| `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`. Проверяется для Redis и PostgreSQL: `/health/live`
остаётся `200`, `/health/ready` и бизнес-запросы возвращают `503 unavailable`
с `request_id` из `X-Request-Id` и без деталей драйвера, запрос без сессии —
по-прежнему `401`, а после старта зависимости живы прежняя сессия,
подтверждённое сообщение и новая запись. Каждый запрос к остановленной БД ждёт
`DATABASE_CONNECTION_TIMEOUT_MS`, поэтому набор идёт около 40 секунд.
## Реплики, балансировка и остановка реплики
Все реплики запускаются из одного образа и одного `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`.
- `/internal/lb-check` намеренно не проверяет БД и Redis: отказ общей
зависимости нельзя исправить выводом реплик из ротации, иначе LB ответит
клиенту своей HTML-страницей вместо ограниченного `503 unavailable`.
`/health/ready` остаётся операторским сигналом и healthcheck'ом контейнера.
## Идемпотентность отправки сообщения
`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`, `growth`, `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 и эксперименты.