Files
2026-10-10 02:13:35 +03:00

200 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 при
этом не затрагиваются).