10 KiB
app — API мессенджера (лабораторная 2)
NestJS 12 + Fastify, ESM TypeScript. PostgreSQL — источник истины бизнес-данных, Redis — серверные Bearer-сессии и производный кэш истории сообщений.
Общая документация (в корне репозитория):
| Документ | Что содержит |
|---|---|
../REPORT.md |
архитектура, схема данных, транзакции, политика кэша, команды, результаты проверок и трека 1 |
../evidence/README.md |
индекс доказательств: что подтверждено и как это воспроизвести |
../bruno/README.md |
коллекция ручных запросов ко всем эндпоинтам |
../contracts/openapi.json |
нормативный контракт API |
../tests/README.md |
публичные проверки репозитория (make check, make test, persistence) |
../docs/architecture/README.md |
граф модулей NestJS (npm run graph) |
Что внутри
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/ guard, exception filter, request-id, cursor, errors
test/
app.e2e-spec.ts black-box набор против запущенного API (PG + Redis)
scripts/
graph-modules.ts генератор графа зависимостей (nestjs-spelunker)
Принципы: raw pg.Pool без ORM, параметризованные запросы, никаких in-memory
хранилищ в боевых путях; кэш — производное состояние и всегда допускает
восстановление из PostgreSQL; отказ зависимости даёт ограниченную ошибку
(503), а не аварийное завершение процесса.
Быстрый старт
Рекомендуемый путь — весь стенд из корня репозитория (PostgreSQL, Redis, миграции, API):
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):
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 |
окно дрейна при получении сигнала завершения |
Поддерживаются также DATABASE_URL_FILE / REDIS_URL_FILE: если заданы, значение
читается из файла (docker secrets / Swarm). Подробности и компромиссы —
../REPORT.md, раздел «Конфигурация и секреты».
Эндпоинты
Публичный контракт — ../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 lint |
oxlint по src/ и test/ |
npm run format |
prettier |
npm run graph |
граф модулей и провайдеров через nestjs-spelunker (пишет ../docs/architecture/) |
Тесты
Unit-тесты не требуют инфраструктуры:
npm test
Интеграционный набор работает по HTTP против запущенного стенда и дополнительно подключается к PostgreSQL (очистка тестовых данных) и Redis:
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, и у набора.
Метрики
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 при этом не затрагиваются).