# 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:@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:@:5432/messenger export REDIS_URL=redis://: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 и эксперименты.