Перенесено дерево lab4 целиком: NestJS-приложение с вложениями и S3,
Dockerfile, compose.yaml, infra/{haproxy,minio}, стендовые скрипты,
scripts/lab4, evidence/lab4 и contracts/extensions.openapi.json.
Задание lab5 оставлено своим: README, REPORT, COURSE, lab.json,
contracts/{openapi,infrastructure,jobs.schema,attachment-states,examples},
tests, compose.example.yaml, .github/pull_request_template.md.
Адаптации при переносе:
- docker-проект mtusi-lab4 -> mtusi-lab5 и тег образа mtusi-messenger:lab5,
чтобы тома и контейнеры не пересекались с lab4 (scripts/stop-one.sh:
LAB_PROJECT вместо LAB4_PROJECT);
- Makefile: цели lab5 сохранены, добавлены стендовые (stand-up/down,
wait-ready, init-env, test-e2e, test-dependencies, s3-security,
consistency, bench);
- .env.example: реальные переменные приложения и стенда lab4 (без них
compose.yaml не поднимается) + блок lab5 (BROKER_URL_FILE, WORKER_*).
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..004)
redis/ клиент Redis (AOF-совместимый, без offline queue)
auth/ Basic-вход, Redis-сессии, logout
users/ регистрация (Argon2id), профиль
chats/ создание чата в транзакции, список и чтение
messages/ отправка сообщения, keyset-история
cache/ версионированный кэш истории + lock на страницу
idempotency/ журнал Idempotency-Key (claim/read/store/forget/GC)
metrics/ /internal/metrics и /internal/metrics/reset
health/ liveness/readiness с проверкой зависимостей (readiness — проба LB)
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 — локальных сессий и
файлов на диске реплики нет, поэтому N взаимозаменяемых реплик за одним LB
дают один и тот же результат.
Быстрый старт
Рекомендуемый путь — весь стенд из корня репозитория (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
sed -i "s/^METRICS_TOKEN=.*/METRICS_TOKEN=$(openssl rand -hex 16)/" .env
make stand-up # сборка + up -d --wait: migrate -> api x API_REPLICAS -> haproxy
make wait-ready
curl -fsS http://localhost:8080/health/ready
for i in 1 2 3 4; do curl -sD- -o /dev/null localhost:8080/health/live | grep -i x-instance-id; done
Публичной точкой входа служит HAProxy (compose.yaml): реплики API портов не
публикуют. API_REPLICAS задаёт их число, API_TOTAL_CPUS / API_TOTAL_MEMORY_MB
делятся между ними — это бюджет серии трека 1 (../REPORT.md).
Локальный запуск без 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) |
HEALTH_TIMEOUT_MS |
400 |
бюджет проверки PostgreSQL/Redis внутри /health/ready; меньше timeout check HAProxy (500 ms) и DATABASE_STATEMENT_TIMEOUT_MS |
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 (в стенде 3000) |
окно дрейна при SIGTERM: реплика сразу перестаёт проходить пробу LB, ждёт этот интервал и только затем закрывает сервер и пулы |
INSTANCE_ID |
hostname контейнера | значение X-Instance-Id; в Docker hostname = короткий ID контейнера, поэтому scripts/stop-one.sh находит реплику по нему |
IDEMPOTENCY_TTL_SECONDS |
86400 |
срок хранения журнала Idempotency-Key (минимум 60) |
Поддерживаются также DATABASE_URL_FILE / REDIS_URL_FILE: если заданы, значение
читается из файла (docker secrets / Swarm). Подробности и компромиссы —
../REPORT.md, раздел «Конфигурация и секреты».
Эндпоинты
Публичный контракт — ../contracts/openapi.json.
| Метод и путь | Аутентификация | Назначение |
|---|---|---|
GET /health/live |
нет | процесс жив; не обращается к зависимостям, поэтому отвечает 200 и при их отказе |
GET /health/ready |
нет | готовность реплики: флаг дреина + PostgreSQL и Redis (бюджет HEALTH_TIMEOUT_MS), иначе 503; эту же ручку пробует HAProxy |
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 + обязательный Idempotency-Key |
отправка сообщения (см. ниже) |
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 idempotency:gc |
ручной прогон удаления просроченных записей Idempotency-Key |
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, E2E_API_SERVICE, E2E_LB_STATS_URL,
E2E_POSTGRES_USER, E2E_POSTGRES_DB, E2E_PG_HBA_PATH.
Проверяются три топологии отказа:
- Отказ Redis (общая зависимость):
/health/liveреплики остаётся200,/health/readyи бизнес-запросы —503 unavailableсrequest_idизX-Request-Idи без деталей драйвера, запрос без сессии — по-прежнему401. Неготовыми становятся все реплики, HAProxy исключает их из ротации и отвечает собственным503; после старта Redis сессия и подтверждённое сообщение живы. - Отказ PostgreSQL (общая зависимость): то же плюс проверка, что после возврата зависимости данные на месте и новая запись проходит.
- Отказ PostgreSQL у одной реплики (локальный путь к БД): для адреса
выбранной реплики временно ставится
reject-строка вpg_hba.conf(первое совпадение) и обрываются её соединения. Выбранная реплика отвечает503и её слот уходит вDOWN, здоровая продолжает200/UPи обслуживает все чтения через LB;pg_hba.confвосстанавливается вfinally, после чего реплика возвращается в ротацию и снова получает запросы.
Реплики API портов не публикуют, поэтому отдельная реплика опрашивается изнутри
своего контейнера (loopback), а состояние слотов — из stats;csv HAProxy
(127.0.0.1:8404). Каждый запрос к остановленной БД ждёт
DATABASE_CONNECTION_TIMEOUT_MS, поэтому набор идёт около минуты.
Реплики, балансировка и остановка реплики
Все реплики запускаются из одного образа и одного compose.yaml; API портов не
публикует, трафик идёт только через HAProxy. Состояние, от которого зависит
корректность, лежит в общих PostgreSQL и Redis, поэтому клиент с одним
Bearer-токеном обслуживается любой репликой:
make test BASE_URL=http://localhost:8080 # сквозной сценарий через LB
python3 scripts/lab3/lab3.py check spread # распределение X-Instance-Id
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # отказ одной реплики
scripts/start-replica.sh # вернуть остановленную реплику
X-Instance-Id=INSTANCE_IDили hostname процесса, стабилен для процесса; в Docker hostname контейнера — короткий ID, поэтомуscripts/stop-one.shостанавливает ровно ту реплику, которую обслужил запрос теста. Тот же заголовок добавляется к ответам об ошибках, которые формируются фильтром до интерсептора.- Остановка (
SIGTERM) идёт в порядке «сначала дрейн, потом разбор ресурсов»: реплика помечается not-ready (проба LB и/health/readyначинают отвечать503),DRAIN_DELAY_MSждёт, пока LB её исключит (обнаружение ≈1 s), и лишь затем закрываются HTTP-сервер, пул PostgreSQL и соединение Redis. Если полагаться на стандартный порядок Nest (onModuleDestroyвызывает закрытие пулов раньшеbeforeApplicationShutdown), реплика какое-то время остаётся в ротации уже без ресурсов — это и было причиной явной последовательности вsrc/main.ts. - Проба LB — тот же
/health/ready, что и healthcheck контейнера: реплика, потерявшая обязательную зависимость (свой путь к PostgreSQL или Redis), выходит из ротации, и трафик уходит на здоровые реплики. Проба с зависимостями ограничена общим дедлайномHEALTH_TIMEOUT_MS=400на реплику; проверка PostgreSQL (SELECT 1) идёт по отдельному соединению, а не из общего пула бизнес-запросов, а дляPINGRedis стоитAbortSignal.timeout, поэтому проба укладывается вtimeout check 500msHAProxy и не реагирует на перегрузку. Когда недоступна общая для всех зависимость, неготовыми становятся все реплики, и клиент получает503от самого LB: это честный ответ «готовых узлов нет» вместо маскировки отказа. /health/liveзависимостей не касается: он отвечает200, пока жив процесс, и по нему проверяют, что реплика не упала (в том числе при отказе PG/Redis).
Идемпотентность отправки сообщения
POST /api/v1/chats/{chatId}/messages требует заголовок Idempotency-Key
(ASCII [A-Za-z0-9._:-]{1,128}). Область уникальности — пользователь + метод +
путь чата + ключ, поэтому одинаковый ключ у разных пользователей или в разных
чатах не конфликтует. Журнал — таблица idempotency_keys (миграция 003), то
есть общая для всех реплик.
| Ситуация | Ответ |
|---|---|
| Заголовок отсутствует, пуст или не подходит под шаблон | 400 invalid_request (до обращения к БД) |
| Первый запрос с ключом | 201 и сообщение; заявка, вставка сообщения, инкремент версии чата и тело ответа записываются одним оператором SQL (атомарность обеспечивает сам оператор) |
| Повтор того же тела с тем же ключом | тот же 201 и тот же JSON (включая id и created_at), новое сообщение не создаётся |
| Другое тело с тем же ключом | 409 conflict |
Повтор после 404 (нет доступа к чату) |
404, ключ не занят: оператор вставляет заявку только при наличии членства, иначе не создаётся ничего |
Ключ старше IDEMPOTENCY_TTL_SECONDS |
запись удаляется, ключ считается свободным |
| Одновременные повторы через разные реплики | ровно одно сообщение: заявка берётся INSERT ... ON CONFLICT DO NOTHING, повтор читает сохранённый ответ |
Путь записи — один round trip: messages.createIdempotent проверяет членство,
занимает ключ (INSERT ... ON CONFLICT DO NOTHING), вставляет сообщение, поднимает
chats.message_version и сохраняет тело ответа, а повтор читает сохранённый ответ
вместе с повторной проверкой доступа (idempotency.read). До оптимизации это были
8 обращений к БД в явной транзакции (см. REPORT.md, раздел «A/B улучшения»).
Отпечаток тела считается по валидированному DTO с фиксированным порядком полей,
поэтому порядок ключей в JSON не влияет на результат. Транзиентные сбои
PostgreSQL (57014, 40001, 40P01) и обрывы соединения отдаются как
503 unavailable и не фиксируются как окончательный результат: клиент может
безопасно повторить запрос с тем же ключом. Просроченные записи удаляются
фоновым проходом (idempotency.purged в метриках) под
pg_try_advisory_xact_lock, а также вручную: npm run idempotency:gc.
Харнесс экспериментов
Уровни 3/4 и трек 1 обслуживает ../scripts/lab3/lab3.py (только stdlib) и
профили k6 в ../scripts/load/: run, sweep, track1-extras, failover,
rolling-update, ab, analyze, watch, check, quiesce, track1.
Сырые результаты прогонов, манифесты условий измерения и графики складываются в
../evidence/track1/. Подробности — в ../REPORT.md и
../evidence/README.md.
Метрики
GET /internal/metrics возвращает {counters, latency_ms, instance_id, build_id}: именованные 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, а также
идемпотентность: idempotency.claim, idempotency.replay, idempotency.conflict,
idempotency.claim_lost, idempotency.released, idempotency.purged,
idempotency.purge_error, messages.write.
Счётчики локальны процессу: при нескольких репликах их нельзя суммировать как
распределённый снимок, а рестарт API обнуляет их (данные PostgreSQL и Redis при
этом не затрагиваются). instance_id и build_id позволяют сопоставить ответ
конкретной реплике и сборке — этим пользуются rolling update и эксперименты.