Files

315 lines
24 KiB
Markdown
Raw Permalink 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 с проверкой зависимостей (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 и эксперименты.