- compose.yaml: проект mtusi-lab3, HAProxy как единственная точка входа,
deploy.replicas ${API_REPLICAS:-2}, CPU/RAM-лимиты на каждый сервис,
stop_grace_period 20s, лимиты из переменных (API_CPUS_PER_REPLICA и т.д.),
loopback-порты PostgreSQL/Redis только для операторских проверок; у API
портов нет; container_name нигде не задан.
- infra/haproxy/haproxy.cfg: проба GET /internal/lb-check, inter 500ms/fall 2
(~1s обнаружение), server-template + DNS Docker вместо статического списка,
stats на 127.0.0.1:8404.
- Дрейн: SIGTERM -> реплика сразу перестаёт проходить пробу LB -> пауза
DRAIN_DELAY_MS -> закрытие сервера и пулов. Nest уничтожает провайдеров
раньше beforeApplicationShutdown, поэтому последовательность вынесена в
main.ts, а HealthService отвечает только за флаг not-ready.
- scripts/stop-one.sh (остановка ровно одной реплики по X-Instance-Id),
scripts/start-replica.sh (восстановление до API_REPLICAS), scripts/quiesce.sh
(остановка/возврат посторонних контейнеров хоста), restart.sh перезапускает
и LB, scripts/app-e2e.sh (host-side e2e через loopback-порты).
- Makefile: stand-up/down/status, stand-replica, wait-ready, quiesce-up/down,
test-e2e, test-failover-all, rolling-update, track1, evidence.
- Dockerfile: ARG/ENV BUILD_ID для доказательства rolling update.
Проверено: make test, make test-e2e, make test-persistence (restart.sh),
make test-failover (stop-one.sh, восстановление через start-replica.sh),
make test-dependencies; docker inspect подтверждает NanoCpus/Memory и
отсутствие опубликованных портов у api.
app — API мессенджера
NestJS 12 + Fastify, ESM TypeScript. PostgreSQL — источник истины бизнес-данных, Redis — серверные Bearer-сессии и производный кэш истории сообщений.
Общая документация (в корне репозитория):
| Документ | Что содержит |
|---|---|
../REPORT.md |
архитектура, схема данных, транзакции, политика кэша, команды, результаты проверок и трека 1 |
../evidence/README.md |
индекс доказательств: что подтверждено и как это воспроизвести |
../contracts/openapi.json |
нормативный контракт API |
../tests/README.md |
публичные проверки репозитория (make check, make test, persistence) |
Что внутри
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 при этом не затрагиваются).