Files
mtusi2026lab3/app
ilya.tyunin 5a5a8fe5cb lab3: путь записи сообщения одним оператором (C2)
Владелец ключа идемпотентности больше не оркестрируется в приложении: проверка
членства, заявка ключа, вставка сообщения, инкремент версии чата (якорь
инвалидации кэша) и сохранение тела ответа выполняются одним оператором SQL,
атомарность которого обеспечивает сам оператор.

- messages.repository: createOnce() одним запросом вместо трёх (проверка
  членства + INSERT + UPDATE version) и явной транзакции; тело ответа строится
  в SQL и служит источником истины и для первого ответа, и для повторов.
- idempotency.repository: read() читает сохранённый ответ вместе с повторной
  проверкой доступа, delete/purge не изменились; claim/store внутри транзакции
  больше не нужны.
- messages.service: без DatabaseClient и без предварительного chatsService.
  getForUser в пути записи; ключ обязателен, тело проверяется до обращения к БД,
  просроченный ключ освобождается и занимается заново.

Итог: 1 round trip на запись вместо 8 и 2 вместо 3 на повтор; короче удержание
блокировки строки chats, что и проверяется A/B на профиле горячего чата.

Проверено: npm run build, tsc, unit-тесты, lint, публичный smoke и black-box
набор приложения (включая конкурентный повтор с одним ключом) на стенде с
образом mtusi-messenger:lab3-after.
2026-10-15 22:48:22 +03:00
..

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 с проверкой зависимостей + /internal/lb-check
  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)
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 нет процесс жив
GET /health/ready нет готовность: PostgreSQL и Redis доступны, иначе 503
GET /internal/lb-check нет проба балансировщика: только флаг дрейна, без обращения к БД/Redis
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. Проверяется для Redis и PostgreSQL: /health/live остаётся 200, /health/ready и бизнес-запросы возвращают 503 unavailable с request_id из X-Request-Id и без деталей драйвера, запрос без сессии — по-прежнему 401, а после старта зависимости живы прежняя сессия, подтверждённое сообщение и новая запись. Каждый запрос к остановленной БД ждёт DATABASE_CONNECTION_TIMEOUT_MS, поэтому набор идёт около 40 секунд.

Реплики, балансировка и остановка реплики

Все реплики запускаются из одного образа и одного 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.
  • /internal/lb-check намеренно не проверяет БД и Redis: отказ общей зависимости нельзя исправить выводом реплик из ротации, иначе LB ответит клиенту своей HTML-страницей вместо ограниченного 503 unavailable. /health/ready остаётся операторским сигналом и healthcheck'ом контейнера.

Идемпотентность отправки сообщения

POST /api/v1/chats/{chatId}/messages требует заголовок Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Область уникальности — пользователь + метод + путь чата + ключ, поэтому одинаковый ключ у разных пользователей или в разных чатах не конфликтует. Журнал — таблица idempotency_keys (миграция 003), то есть общая для всех реплик.

Ситуация Ответ
Заголовок отсутствует, пуст или не подходит под шаблон 400 invalid_request (до обращения к БД)
Первый запрос с ключом 201 и сообщение; заявка и тело ответа записываются одной транзакцией
Повтор того же тела с тем же ключом тот же 201 и тот же JSON (включая id и created_at), новое сообщение не создаётся
Другое тело с тем же ключом 409 conflict
Повтор после 404 (нет доступа к чату) 404, ключ не занят: заявка откатывается вместе с транзакцией
Ключ старше IDEMPOTENCY_TTL_SECONDS запись удаляется, ключ считается свободным
Одновременные повторы через разные реплики ровно одно сообщение: заявка берётся INSERT ... ON CONFLICT DO NOTHING, повтор читает сохранённый ответ

Отпечаток тела считается по валидированному 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, growth, 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 и эксперименты.