forked from mtusi2026/mtusi2026lab2
200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 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:<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`](../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:<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`. Проверяется для 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 при
|
||
этом не затрагиваются).
|