Files
mtusi2026lab2/app
ilya.tyunin ff47290919
Skeleton contracts / contracts (pull_request) Canceled after 0s
fix: правки
2026-10-10 02:13:35 +03:00
..
2026-10-09 15:48:03 +03:00
2026-10-10 02:13:35 +03:00
2026-10-10 02:13:35 +03:00
2026-10-01 19:29:22 +03:00
2026-10-01 19:29:22 +03:00
2026-10-09 15:48:03 +03:00
2026-10-01 19:29:22 +03:00
2026-10-10 02:13:35 +03:00
2026-10-10 02:13:35 +03:00
2026-10-10 02:13:35 +03:00
2026-10-01 19:29:22 +03:00
2026-10-01 19:29:22 +03:00
2026-10-10 02:13:35 +03:00
2026-10-01 19:29:22 +03:00

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/
    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):

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 test:dependencies автоматическая проверка отказов Redis/PostgreSQL: останавливает и поднимает контейнеры Compose-стенда
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, и у набора.

Отказы зависимостей

Отдельный набор останавливает и поднимает контейнеры Compose-стенда и проверяет ограниченные ошибки вместо 500:

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 при этом не затрагиваются).