# app — API мессенджера (лабораторная 2) NestJS 12 + Fastify, ESM TypeScript. PostgreSQL — источник истины бизнес-данных, Redis — серверные Bearer-сессии и производный кэш истории сообщений. Общая документация (в корне репозитория): | Документ | Что содержит | |---|---| | [`../REPORT.md`](../REPORT.md) | архитектура, схема данных, транзакции, политика кэша, команды, результаты проверок и трека 1 | | [`../evidence/README.md`](../evidence/README.md) | индекс доказательств: что подтверждено и как это воспроизвести | | [`../bruno/README.md`](../bruno/README.md) | коллекция ручных запросов ко всем эндпоинтам | | [`../contracts/openapi.json`](../contracts/openapi.json) | нормативный контракт API | | [`../tests/README.md`](../tests/README.md) | публичные проверки репозитория (`make check`, `make test`, persistence) | | [`../docs/architecture/README.md`](../docs/architecture/README.md) | граф модулей NestJS (`npm run graph`) | ## Что внутри ```text src/ main.ts bootstrap: Fastify, ValidationPipe, shutdown hooks app.module.ts сборка модулей приложения config/ Zod-схема env + глобальный ConfigModule database/ pg.Pool, транзакции, миграции (001, 002) redis/ клиент Redis (AOF-совместимый, без offline queue) auth/ Basic-вход, Redis-сессии, logout users/ регистрация (Argon2id), профиль chats/ создание чата в транзакции, список и чтение messages/ отправка сообщения, keyset-история cache/ версионированный кэш истории + lock на страницу metrics/ /internal/metrics и /internal/metrics/reset health/ liveness/readiness с проверкой зависимостей 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, миграции, 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 docker compose --env-file .env up -d --build curl -fsS http://localhost:8080/health/ready ``` Локальный запуск без 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` | окно дрейна при получении сигнала завершения | Поддерживаются также `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` | | `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` | отправка сообщения | | `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 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 секунд. ## Метрики `GET /internal/metrics` возвращает `{counters, latency_ms}`: именованные 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`. Счётчики локальны процессу: при нескольких репликах их нельзя суммировать как распределённый снимок, а рестарт API обнуляет их (данные PostgreSQL и Redis при этом не затрагиваются).