forked from mtusi2026/mtusi2026lab4
315 lines
24 KiB
Markdown
315 lines
24 KiB
Markdown
# 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 и эксперименты.
|