4 Commits
Author SHA1 Message Date
ilya.tyunin ff47290919 fix: правки
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-10 02:13:35 +03:00
ilya.tyunin 1bef3845bc docs: add pr link for report.md
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-09 15:59:49 +03:00
ilya.tyunin 575f8ee386 feat: lab2 done
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-10-09 15:48:03 +03:00
ilya.tyunin f743ee10a2 feat: init after lab 1 2026-10-01 19:29:22 +03:00
122 changed files with 14818 additions and 49 deletions
+41 -7
View File
@@ -1,11 +1,45 @@
# Copy to .env for your LOCAL synthetic test environment; never commit .env.
# These are logical interface suggestions; map actual framework names in REPORT.md.
APP_HOST=0.0.0.0
APP_PORT=8080
APP_PUBLIC_PORT=8080
APP_ENV=lab
SESSION_TTL_SECONDS=3600
# Choose credentials locally. File paths contain no secret values.
DATABASE_URL_FILE=/run/secrets/database_url
# Optional on 3, required use on 4 in lab2; Redis OR Valkey:
SESSION_STORE=postgres
CACHE_URL_FILE=/run/secrets/cache_url
# Credentials for the local synthetic stand. Never commit a real .env.
# Rationale and tradeoffs: REPORT.md, section "Конфигурация и секреты".
# POSTGRES_PASSWORD initializes the database volume; DATABASE_URL must use the
# same password, otherwise the API cannot connect to an existing volume.
POSTGRES_DB=messenger
POSTGRES_USER=messenger
POSTGRES_PASSWORD=change-me
DATABASE_URL=postgresql://messenger:change-me@postgres:5432/messenger
REDIS_URL=redis://redis:6379
# Application tuning
DATABASE_POOL_MAX=10
DATABASE_CONNECTION_TIMEOUT_MS=5000
DATABASE_STATEMENT_TIMEOUT_MS=5000
CACHE_TTL_SECONDS=30
CACHE_MODE=protected
CACHE_LOCK_TTL_MS=1000
CACHE_MISS_DELAY_MS=0
METRICS_TOKEN=change-me
# Clean clone (run once, then `docker compose --env-file .env up -d --build`):
# 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
# unset password
#
# Existing postgres-data keeps its original password: changing POSTGRES_PASSWORD
# alone does not rotate it. Update DATABASE_URL to the volume's password, or
# rotate the password inside PostgreSQL explicitly.
#
# Alternative for docker-secrets or Swarm deployments: point DATABASE_URL_FILE /
# REDIS_URL_FILE at mounted secret files instead of inline URLs. The application
# reads the file, trims it, and validates it exactly like an inline value.
# Optional file-based secret override (uncomment to use):
# DATABASE_URL_FILE=/run/secrets/database_url
# REDIS_URL_FILE=/run/secrets/redis_url
+75 -14
View File
@@ -1,18 +1,79 @@
## Лабораторная 2
Автор / группа: TODO
Целевая оценка (3/4/5): TODO
Трек 5, если заявлен: TODO
Автор / группа: Тюнин Илья БВТ2303
Целевая оценка (3/4/5): 5
Трек 1, если заявлен: Трек 1 «Согласованность кэша» — при 32 конкурентных чтениях холодной страницы × 5 повторностей: **160 SQL-запросов истории в naive против 5 в protected (−96,9 %)**, read-after-write подтверждён, сессия и история переживают рестарт Redis
Что реализовано и что перенесено: TODO
Команды запуска из чистого clone: TODO
Результаты проверок и ссылка на REPORT.md: TODO
Ограничения / известные ошибки: TODO
Источники и использование ИИ: TODO
### Что реализовано
- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [ ] Контракт и публичные тесты не ослаблены.
- [ ] make check и make test выполнены; приложен реальный вывод.
- [ ] Сценарии отказов/безопасности своего уровня воспроизведены.
- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
- **PostgreSQL 16.4 — источник истины**: `users`, `chats`, `chat_members`, `messages`; версионируемые миграции `001_initial.sql`, `002_timestamp_precision.sql`; raw `pg.Pool` с ограниченным пулом, connection/statement timeout и параметризованными запросами, без ORM.
- **Транзакционные границы**: создание чата (валидация участников + chat + membership) и отправка сообщения (membership + insert + `message_version`) — в одной транзакции с rollback; проверено отсутствие частичных данных.
- **Redis 7.4.2 с AOF — серверные Bearer-сессии** с TTL, expiry и logout; одновременно версионированный кэш истории с lock на конкретную страницу `(chat_id, message_version, cursor, limit)` и fallback в PostgreSQL при недоступности Redis.
- **Аутентификация по контракту lab2**: Basic только на `POST /auth/sessions` (UTF-8, первый `:`), Bearer на бизнес-endpoint, `X-User-Id` не аутентифицирует и не подменяет владельца, Argon2id, opaque-токен 256 бит.
- **Воспроизводимый стенд**: Compose с pinned-образами, именованными volumes, healthchecks, сервисом миграций перед API, конфигурацией через `.env`.
- **Наблюдаемость**: token-gated `GET /internal/metrics` и `POST /internal/metrics/reset` — SQL-метки, операции Redis, cache hit/miss/lock wait, session get/set/del, request count, агрегаты латентности; деградации кэша и зависимостей пишутся счётчиками и `warn`-логами, а не проглатываются.
- **Перенесено из lab1** с объявленным переходом: health, регистрация/пользователи, чаты и участники, сообщения, keyset-пагинация — переведены на новую аутентификацию.
Подробности решения — [`REPORT.md`](../REPORT.md) (архитектура, схема, транзакции, политика кэша, команды, ограничения).
Проверки уровня 3/4 — [`evidence/level3-4-verification.md`](../evidence/level3-4-verification.md).
Трек 1 — [`evidence/track1-cache-consistency.md`](../evidence/track1-cache-consistency.md) и [`evidence/track1-explain.md`](../evidence/track1-explain.md).
Навигация по доказательствам — [`evidence/README.md`](../evidence/README.md).
Ручной клиент для разбора API — [`bruno/README.md`](../bruno/README.md).
### Команды запуска из чистого clone
```sh
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
unset password
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build # postgres/redis healthy, migrate exit 0, api healthy
curl -fsS http://localhost:8080/health/ready
```
Пояснения по переменным и паролю существующего volume — [`.env.example`](../.env.example) и [REPORT.md § «Конфигурация и секреты»](../REPORT.md).
### Результаты проверок (фактический вывод)
```text
make check PASS
make validate PASS
make test BASE_URL=http://localhost:8080 PASS: lab2 public API scenario
make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: preserved confirmed data and existing session
make test-dependencies PASS: 2 passed (отказы Redis и PostgreSQL)
(cd app && npm run build) PASS
(cd app && npm test) 7 files, 20 tests passed
(cd app && npx tsc --noEmit) PASS
integration suite (реальные PostgreSQL/Redis) 9 passed | 1 skipped
то же с SESSION_TTL_SECONDS=2 10 passed (expiry → 401)
коллекция Bruno (bru run -r --env local) 29 запросов, 58 проверок — все зелёные
```
Трек 1 (32 конкурентных GET × 5 повторностей, `CACHE_MISS_DELAY_MS=75`):
| Режим | SQL `messages.history` | Cache hits | Ошибок | p50, мс |
| --------- | ---------------------: | ---------: | -----: | ------: |
| naive | 160 | 0 | 0 | ≈ 89 |
| protected | 5 | 155 | 0 | ≈ 20 |
Отдельно проверены границы длин в code points (11 эмодзи-пароль → 400, 12 → 201 и вход работает, 101 эмодзи в `display_name` → 400, 4001 эмодзи в тексте → 400, 4000 → 201). Также проверены: гонка одинакового username (201 + 409, в таблице ровно 1 строка, unique-индекс), rollback при неизвестном участнике чата (`400`, строк не осталось), отказы Redis и PostgreSQL автоматическим набором (`make test-dependencies`: `/health/live` 200, `/health/ready` и бизнес-запросы — ограниченная `503` без деталей драйвера, анонимный запрос 401, процесс API жив, после старта — 200 с тем же токеном и подтверждённым сообщением), `EXPLAIN (ANALYZE, BUFFERS)` на 10 002 сообщениях (Index Scan по `messages_chat_created_id_idx`, keyset-предикат в `Index Cond`).
- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
- [x] Контракт и публичные тесты не ослаблены (`contracts/` и `tests/` не изменялись).
- [x] `make check` и `make test` выполнены; приложен реальный вывод (выше и в evidence).
- [x] Сценарии отказов/безопасности своего уровня воспроизведены (отказы Redis/PostgreSQL, expiry, logout/replay, spoofing, rollback — [журнал](../evidence/level3-4-verification.md)).
- [x] Все секреты и приватные ключи находятся вне Git: `.env` и локальные секреты покрыты `.gitignore`, в отчёте и evidence нет токенов и паролей.
- [x] README задания сохранён, `REPORT.md` содержит инструкцию именно этого решения.
### Ограничения / известные ошибки
- Метрики локальны процессу API и сбрасываются при его рестарте; при нескольких репликах их нельзя суммировать как распределённый снимок.
- Измерения трека 1 — closed-loop на одном хосте (32 конкурентных читателя, 5 повторностей): это не production-пропускная способность.
- `redis-data` хранит действующие сессии: удаление volume осознанно разлогинивает пользователей; AOF плюс сохранённый volume — проверенная граница durability.
- `CACHE_MODE=naive` и `CACHE_MISS_DELAY_MS` предназначены только для эксперимента и задаются переменными окружения при пересоздании контейнера `api` (например, `CACHE_MODE=naive CACHE_MISS_DELAY_MS=75 docker compose --env-file .env up -d api`); задержка влияет только на naive-путь.
- Порты PostgreSQL/Redis наружу не публикуются, поэтому интеграционный набор запускается с адресами контейнеров (команда в [REPORT.md](../REPORT.md) § «Команды проверок»).
- Сырые прогоны бенчмарка не коммитятся (локальные идентификаторы); их хеши — в [`evidence/track1-cache-consistency.md`](../evidence/track1-cache-consistency.md) §8.
+3
View File
@@ -30,3 +30,6 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
secrets/
.env
evidence/track1-raw/
+33
View File
@@ -0,0 +1,33 @@
FROM node:25.7.0-slim AS build
WORKDIR /usr/src/app
RUN apt-get update \
&& apt-get install -y --no-install-recommends python3 make g++ \
&& rm -rf /var/lib/apt/lists/*
COPY app/package.json app/package-lock.json ./
RUN npm ci
COPY app/ ./
RUN npm run build && npm prune --omit=dev
FROM node:25.7.0-slim AS runtime
WORKDIR /usr/src/app
ENV NODE_ENV=production
ENV APP_PORT=8080
ENV DRAIN_DELAY_MS=5000
COPY --from=build /usr/src/app/package.json /usr/src/app/package-lock.json ./
COPY --from=build /usr/src/app/node_modules ./node_modules
COPY --from=build /usr/src/app/dist ./dist
USER node
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
CMD node -e "const port=process.env.APP_PORT||'8080'; fetch('http://127.0.0.1:'+port+'/health/ready').then((response) => { if (!response.ok) process.exit(1); }).catch(() => process.exit(1))"
CMD ["node", "dist/main.js"]
+6 -2
View File
@@ -3,11 +3,12 @@ BASE_URL ?= http://localhost:8080
CA_FILE ?=
ACTION_SCRIPT ?=
TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",)
COMPOSE_ENV_FILE ?= .env
.PHONY: help check validate test load test-persistence
.PHONY: help check validate test load test-persistence test-dependencies
help:
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes"
@echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes; test-persistence: restart hook; test-dependencies: stops/restarts Redis and PostgreSQL"
check:
$(PYTHON) scripts/check_contract.py
@@ -24,3 +25,6 @@ load:
test-persistence:
@test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2)
$(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS)
test-dependencies:
cd app && E2E_COMPOSE_DIR="$(CURDIR)" E2E_COMPOSE_ENV_FILE="$(COMPOSE_ENV_FILE)" npm run test:dependencies
+223 -23
View File
@@ -1,37 +1,237 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Тюнин Илья БВТ2303
- Целевая оценка: 5, трек 1 («Согласованность кэша»)
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/33
## Запуск из чистого clone
## Карта документации
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
| Документ | Что содержит |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Этот отчёт | Архитектура, схема данных, транзакции, аутентификация, политика кэша, методика и результаты трека 1, наблюдаемые проверки, ограничения. |
| [`evidence/README.md`](evidence/README.md) | Индекс доказательств: что какой файл подтверждает и как всё регенерировать. |
| [`evidence/level3-4-verification.md`](evidence/level3-4-verification.md) | Журнал проверок уровня 3/4 с наблюдаемым выводом команд и таблицей найденных дефектов. |
| [`evidence/track1-cache-consistency.md`](evidence/track1-cache-consistency.md) | Трек 1: окружение, методика, числа по повторностям, сравнение, read-after-write, рестарт Redis, хеши артефактов. |
| [`evidence/track1-explain.md`](evidence/track1-explain.md) | Тексты анализируемых SQL-запросов и `EXPLAIN (ANALYZE, BUFFERS)`. |
| [`.github/pull_request_template.md`](.github/pull_request_template.md) | Краткая сводка работы, команды запуска, результаты проверок, чек-лист сдачи. |
| [`tests/README.md`](tests/README.md) | Публичные проверки репозитория (`make check`, `make test`, persistence, load, TLS). |
| [`docs/architecture/`](docs/architecture/README.md) | Граф модулей и провайдеров NestJS (`npm run graph`). |
| [`bruno/README.md`](bruno/README.md) | Коллекция Bruno: ручные запросы на все эндпоинты, негативные кейсы и автосохранение токенов/ID между запросами. |
| [`scripts/track1_cache_benchmark.py`](scripts/track1_cache_benchmark.py), [`scripts/track1_verify.py`](scripts/track1_verify.py) | Инструменты измерения трека 1 и проверки рестарта Redis. |
| [`scripts/restart.sh`](scripts/restart.sh) | Хук перезапуска для `make test-persistence`. |
## Архитектура и решения
## Архитектура и роли компонентов
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
Client
-> Fastify/Nest API
AuthController (Basic -> opaque Bearer session)
CurrentUserGuard (Bearer -> Redis session -> PostgreSQL user)
UsersController / ChatsController / MessagesController
-> UsersRepository -> pg.Pool -> PostgreSQL
-> ChatsRepository -> pg.Pool -> PostgreSQL (transaction)
-> MessagesRepository-> pg.Pool -> PostgreSQL (transaction)
-> MessagesCacheService -> Redis versioned message page
-> SessionRepository -> Redis session:{token} (AOF)
-> MetricsService -> token-gated /internal/metrics
```
## Доказательства критериев
Источник истины:
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
- PostgreSQL — пользователи, чаты, membership, сообщения.
- Redis — действующие безопасные сессии (AOF persistence) и производный кэш истории.
- Удаление Redis cache не теряет подтверждённые данные: они восстанавливаются из PostgreSQL.
- Отказ Redis не даёт анонимного доступа: сессионный путь возвращает ограниченную 503.
- Отказ PostgreSQL не убивает процесс API и даёт ограниченную 503.
- Оба отказа проверяются автоматически (`make test-dependencies`): остановка и старт контейнеров, ограниченные ошибки без деталей драйвера, восстановление сессии и подтверждённых данных.
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
### Схема данных и миграции
## Эксперименты и отказы
`001_initial.sql`:
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
- `users(id uuid pk, username unique, display_name, password_hash, created_at)`;
- `chats(id uuid pk, title, created_at, message_version bigint)`;
- `chat_members(chat_id, user_id)` — composite PK, cascade FK;
- `messages(id, chat_id, sender_id, text, created_at)`, FK на chat и на member;
- `messages_chat_created_id_idx (chat_id, created_at, id)`;
- `chat_members_user_chat_idx (user_id, chat_id)`.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
`002_timestamp_precision.sql` приводит `created_at` к `timestamptz(3)`, чтобы значения совпадали с millisecond timestamps JavaScript. Без этого следующая страница keyset-пагинации повторяла последнее сообщение предыдущей.
## Ограничения и следующие шаги
Migration runner сам находит `NNN_*.sql`, сортирует по имени и применяет каждую незаписанную миграцию в отдельной транзакции через `schema_migrations`. Повторный запуск — no-op; сиды не выполняются.
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
### Транзакционные границы
Создание чата: валидация `member_ids` через `ANY($1::uuid[])`, вставка `chats`, вставка всех `chat_members`, commit либо полный rollback. Создание сообщения: проверка membership, вставка `messages`, инкремент `chats.message_version`, commit либо rollback.
## Аутентификация и доступ
- `POST /api/v1/users` — регистрация с паролем 12–128 code points; Argon2id.
- `POST /api/v1/auth/sessions` — только Basic, UTF-8, разделение по первому `:`; тело не принимается.
- Токен — 32 случайных байта (Base64URL), серверная сессия в Redis с TTL.
- Бизнес-endpoint — только Bearer; истёкший/отозванный/неизвестный токен → 401 + `WWW-Authenticate: Bearer realm="messenger"`.
- `X-User-Id` не аутентифицирует и не подменяет владельца сессии.
- `DELETE /api/v1/auth/sessions/current` → 204 без тела; повтор с тем же токеном → 401.
- Ответы 401 содержат корректный challenge: Basic для создания сессии, Bearer для остальных.
## Валидация входа
- Обязательные строки не состоят только из пробельных символов (`contracts/README.md`): у `display_name` и `password` есть проверка `\S`, поэтому пароль из 12 пробелов — `400`, а не созданная учётная запись.
- Курсор истории — непрозрачная строка, но сервер проверяет формат (`YYYY-MM-DDTHH:MM:SS(.f)Z`, диапазоны часов/минут/секунд) и календарь через `date-fns` `parseISO` + `isValid`. Несуществующие даты (`2026-02-31`, `2025-02-29`) и `24:00:00` отклоняются как `400 invalid_request`, потому что `Date.parse` молча переносит их на другой день и такое значение падало бы уже в PostgreSQL (`500`). Разобранный инстант нормализуется к каноническим миллисекундам.
- Длины строк считаются в Unicode code points, как в JSON Schema и контракте: собственный декоратор `@CodePointLength` (`app/src/common/validation/`) заменяет `@Length`, который мерил UTF-16-единицы. Поэтому `display_name` и `title` — 1–100, пароль — 12–128, текст сообщения — 1–4000 code points независимо от наличия эмодзи вне BMP; подсчёт идёт по code points, а не по графемным кластерам (комбинирующие символы считаются отдельно, как в JSON Schema).
- Неизвестные поля и неверные типы — `400`; лимит истории — целое 1–100.
## Политика кэша и трек 1
Ключ страницы: `messages:{chat_id}:v{message_version}:c{cursor|start}:l{limit}`.
Protected режим: exact-page lock `lock:{cache_key}` (`SET NX PX` + compare-owner Lua unlock), ограниченные повторы, повторная проверка кэша, запись результата владельцем, best-effort запись кэша и fallback в PostgreSQL при недоступности Redis. Любой commit сообщения увеличивает `message_version`, поэтому старые страницы становятся недостижимыми.
Naive режим — управляемый baseline без распределённой блокировки; `CACHE_MISS_DELAY_MS` расширяет окно гонки.
Гипотеза: при одном холодном ключе и `N` конкурентных читателях naive порождает около `N` SQL-запросов истории, protected — один запрос владельца, остальные ждут и попадают в кэш.
## Воспроизводимый запуск
```sh
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
unset password
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -fsS http://localhost:8080/health/ready
```
- `postgres:16.4-alpine` c named volume `postgres-data`;
- `redis:7.4.2-alpine`, AOF (`appendonly yes`, `appendfsync everysec`), named volume `redis-data`;
- одноразовый сервис `migrate`;
- `api` с healthcheck `/health/ready`.
### Конфигурация и секреты
Все параметры, включая `POSTGRES_PASSWORD`, `DATABASE_URL` и `REDIS_URL`, задаются в `.env`
(вне Git). Это сознательный выбор для локального синтетического стенда:
- `.env` уже игнорируется `.gitignore`; отдельных файлов секретов и лишнего маппинга не требуется;
- значения видны через `docker inspect`/`/proc/<pid>/environ` — для учебного стенда с
синтетическими данными это допустимо, для production нужен внешний secret store;
- `postgres-data` хранит пароль, заданный при первой инициализации: смена `POSTGRES_PASSWORD`
сама по себе его не меняет, поэтому `DATABASE_URL` должен указывать на пароль этого volume;
- файловый вариант (`DATABASE_URL_FILE`, `REDIS_URL_FILE`, docker secrets/Swarm) поддержан в
конфигурации как опциональная альтернатива и описан в `.env.example`.
`scripts/restart.sh` перезапускает `postgres redis api` и ждёт готовности, не удаляя volumes и не выполняя `FLUSHALL`.
## Track 1: методика и результаты
Методика: режим кэша и задержка промаха задаются переменными окружения при пересоздании контейнера (`CACHE_MODE`, `CACHE_MISS_DELAY_MS`; shell-значение перекрывает `.env`). Каждая повторность использует новый чат (холодный ключ), поэтому `FLUSHALL` не нужен. Барьер синхронизирует старт конкурентных GET, метрики сбрасываются через `POST /internal/metrics/reset`.
Важно: `CACHE_MISS_DELAY_MS` действует только в naive-пути (пауза между промахом и запросом в PostgreSQL) и намеренно расширяет окно гонки. Protected-путь задержку не использует, поэтому замеренная разница p50/p95 между режимами включает эти 75 мс и не является «честным» сравнением скорости; независимая от задержки метрика — число SQL-запросов истории.
Команды:
```sh
printf '%s' "$METRICS_TOKEN" > /tmp/track1-metrics-token
CACHE_MODE=naive CACHE_MISS_DELAY_MS=75 docker compose --env-file .env up -d api
python3 scripts/track1_cache_benchmark.py --base-url http://localhost:8080 --mode naive \
--concurrency 32 --repetitions 5 --metrics-token-file /tmp/track1-metrics-token \
--runtime-version node=25.7.0 --runtime-version postgres=16.4 --runtime-version redis=7.4.2 \
--output evidence/track1-raw/naive.json
CACHE_MODE=protected docker compose --env-file .env up -d api
python3 scripts/track1_cache_benchmark.py --base-url http://localhost:8080 --mode protected \
--concurrency 32 --repetitions 5 --metrics-token-file /tmp/track1-metrics-token \
--runtime-version node=25.7.0 --runtime-version postgres=16.4 --runtime-version redis=7.4.2 \
--output evidence/track1-raw/protected.json
python3 scripts/track1_verify.py --summary \
--naive-raw evidence/track1-raw/naive.json --protected-raw evidence/track1-raw/protected.json \
--output evidence/track1-cache-consistency.md
```
Наблюдено (concurrency 32, 5 повторностей, 160 успешных GET в каждом режиме, ошибок 0):
| Режим | `messages.history` SQL | Cache misses | Cache hits | Lock waits |
| --------- | ---------------------: | -----------: | ---------: | ---------: |
| naive | 160 | 160 | 0 | 0 |
| protected | 5 | 46 | 155 | 41 |
Снижение числа SQL-запросов истории: **160 → 5 (96.9 %)**. Латентность успешных запросов: naive p50 ≈ 82–117 ms, protected p50 ≈ 28–44 ms (сырые значения в `evidence/track1-raw/`). Эта разница не является чистым сравнением скорости: в naive-путь искусственно добавлена пауза `CACHE_MISS_DELAY_MS=75` (задержка применяется только в naive), тогда как protected её не использует. Независимая от задержки метрика — число SQL-запросов истории.
Read-after-write (protected, вторая действующая сессия): `asserted=true`, `stale_observed=false`.
Рестарт Redis с сохранением AOF-volume и последующим удалением только `messages:*`:
```json
{
"restart_redis": true,
"same_token_users_me": true,
"history_equal": true,
"cache_eviction": { "requested": true, "message_keys_deleted": 9 }
}
```
## Уровень 3/4: наблюдаемые проверки
| Проверка | Команда/сценарий | Наблюдаемый результат |
| ---------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Публичный smoke | `make test` | `PASS: lab2 public API scenario` |
| Сохранность через полный рестарт | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session` |
| Интеграционный набор (реальные PG/Redis) | `npx vitest run --config vitest.config.e2e.ts` | 9 passed, 1 gated |
| То же с `SESSION_TTL_SECONDS=2` | тот же набор с TTL=2 | 10 passed (включая expiry → 401) |
| Гонка одинакового username | набор: два одновременных POST + `select count(*)` | 201 и 409; в `users` ровно 1 строка (гарантия — unique index `users_username_key`, ошибка `23505` → 409) |
| Rollback чата с неизвестным участником | HTTP 400 + `select count(*)` | 400; строк в `chats` — 0 |
| Индекс истории | `EXPLAIN (ANALYZE, BUFFERS)` на 10 002 строках | `Index Scan using messages_chat_created_id_idx` для первой страницы (0.040 мс) и для keyset-продолжения (0.048 мс) |
| Отказ Redis (автоматически) | `make test-dependencies` | `/health/live` 200; `/health/ready` и бизнес-запросы — ограниченная 503; анонимный запрос 401; после старта сессия и данные живы |
| Отказ PostgreSQL (автоматически) | `make test-dependencies` | `/health/live` 200; все бизнес-запросы и регистрация — 503 без утечки деталей; процесс жив; после старта запись работает |
| Логин/логаут/подмена | набор + `X-User-Id` | Basic на бизнес-endpoint 401, `X-User-Id` не меняет владельца, replay после logout 401 |
| Ручной клиент (Bruno) | `bru run -r --env local ...` из `bruno/` | 29 запросов, 58 проверок — все зелёные (включая негативные и метрики) |
Отдельно исправлен реальный дефект: при падении PostgreSQL процесс API завершался из-за необработанного события `error` у idle-клиента пула. Добавлен обработчик `pool.on('error')`, а ошибки доступности БД в фильтре отображаются в ограниченную 503 вместо 500.
Полный журнал проверок с наблюдаемым выводом команд — [`evidence/level3-4-verification.md`](evidence/level3-4-verification.md); методика и по-повторностные числа трека — [`evidence/track1-cache-consistency.md`](evidence/track1-cache-consistency.md).
`EXPLAIN` (фрагмент): `Index Scan using messages_chat_created_id_idx on messages`, первая страница `actual time=0.020..0.028 ms` / `Execution Time: 0.040 ms`, keyset-продолжение `Index Cond: ((chat_id = ...) AND (ROW(created_at, id) > ROW(...)))` / `Execution Time: 0.048 ms` — полного скана истории нет, предикат продолжения уходит в индекс. Тексты проанализированных запросов и подготовка данных — [`evidence/track1-explain.md`](evidence/track1-explain.md).
## Команды проверок
```sh
make check
make validate
(cd app && npm run build && npm test && npx tsc --noEmit)
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-dependencies
(cd app && API_BASE_URL=http://localhost:8080 \
DATABASE_URL=postgresql://messenger:<password>@<pg-host>:5432/messenger \
REDIS_URL=redis://<redis-host>:6379 npx vitest run --config ./vitest.config.e2e.ts)
```
Примечание: набор для интеграционных тестов читает `API_BASE_URL`, потому что Vitest сам устанавливает `process.env.BASE_URL`.
## Наблюдаемость отказов
`GET /internal/metrics` и `POST /internal/metrics/reset` открыты только с `Authorization: Bearer <METRICS_TOKEN>` и возвращают `{counters, latency_ms}` без секретов и SQL-текста. Счётчики, по которым видно деградацию (а не «тихое» проглатывание ошибок):
| Счётчик | Когда растёт |
| ------------------------------------------------- | --------------------------------------------------------------------------------- |
| `cache_hit` / `cache_miss` | попадание/промах страницы |
| `cache_lock_wait` / `cache_lock_timeout` | ожидание владельца lock; владелец не успел за отведённые повторы |
| `cache_fallback` | Redis недоступен на чтении/lock/повторном чтении, ответ отдан из PostgreSQL |
| `cache_write_error` / `cache_unlock_error` | не удалось записать страницу или снять lock (ответ не ломается) |
| `cache_corrupt_entry` | повреждённая запись кэша трактуется как промах и перезаписывается |
| `database.pool_error` / `database.rollback_error` | обрыв idle-клиента пула; ошибка `ROLLBACK` (исходная ошибка операции сохраняется) |
| `redis.error` | ошибка соединения/reconnect Redis |
Те же события дополнительно пишутся в лог уровнем `warn` с контекстом, поэтому один сбойный запрос уже видно без разбора дампов.
## Ограничения и границы
- Метрики локальны процессу API и сбрасываются при его рестарте; PostgreSQL и Redis не затрагиваются.
- Измерения выполнены на одном локальном хосте (closed-loop, конкуренция 32, 5 повторностей); это не production-пропускная способность и не распределённая телеметрия.
- `redis-data` — источник истины сессий: удаление volume осознанно разлогинивает пользователей; сохранённый AOF — проверенная граница durability.
- `CACHE_MODE=naive` предназначен только для эксперимента и не должен включаться в штатном профиле.
- Файлы `evidence/track1-raw/*.json` игнорируются git (содержат локальные идентификаторы); в репозитории хранится санитизированная сводка.
- Публичные `contracts/` и `tests/` не изменялись.
+59
View File
@@ -0,0 +1,59 @@
# compiled output
/dist
/node_modules
/build
# TypeScript build cache
*.tsbuildinfo
# Logs
logs
*.log
npm-debug.log*
pnpm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
# OS
.DS_Store
# Tests
/coverage
/.nyc_output
# IDEs and editors
/.idea
.project
.classpath
.c9/
*.launch
.settings/
*.sublime-workspace
# IDE - VSCode
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local
# temp directory
.temp
.tmp
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+6
View File
@@ -0,0 +1,6 @@
{
"singleQuote": true,
"trailingComma": "all",
"tabWidth": 4,
"useTabs": true
}
+199
View File
@@ -0,0 +1,199 @@
# 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 при
этом не затрагиваются).
+15
View File
@@ -0,0 +1,15 @@
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true,
"assets": [
{
"include": "database/migrations/*.sql",
"outDir": "dist"
}
],
"watchAssets": true
}
}
+10
View File
@@ -0,0 +1,10 @@
{
"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/crates/oxc_linter/src/rules.rs",
"rules": {
"@typescript-eslint/no-explicit-any": "off",
"@typescript-eslint/no-floating-promises": "warn"
},
"env": {
"node": true
}
}
+7401
View File
File diff suppressed because it is too large Load Diff
+65
View File
@@ -0,0 +1,65 @@
{
"name": "app",
"version": "0.0.1",
"description": "",
"author": "",
"private": true,
"license": "UNLICENSED",
"type": "module",
"scripts": {
"build": "nest build",
"deploy": "nest deploy",
"format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
"start": "nest start",
"start:dev": "nest start --watch",
"start:debug": "nest start --debug --watch",
"start:prod": "node dist/main",
"lint": "oxlint src/ test/",
"test": "vitest run",
"test:unit": "vitest run --include 'src/**/*.spec.ts'",
"test:watch": "vitest",
"test:cov": "vitest run --coverage",
"test:debug": "vitest --inspect-brk --no-file-parallelism",
"graph": "npm run build && DATABASE_URL=postgresql://graph-only.invalid/messenger REDIS_URL=redis://graph-only.invalid:6379 tsx scripts/graph-modules.ts",
"test:e2e": "vitest run --config ./vitest.config.e2e.ts",
"test:dependencies": "E2E_DEPENDENCY_FAULTS=1 vitest run --config ./vitest.config.e2e.ts dependency-failures"
},
"dependencies": {
"@nestjs/common": "^12.0.1",
"@nestjs/config": "^12.0.0",
"@nestjs/core": "^12.0.1",
"@nestjs/platform-express": "^12.0.1",
"@nestjs/platform-fastify": "^12.0.3",
"argon2": "^0.45.1",
"class-transformer": "^0.5.1",
"class-validator": "^0.15.1",
"date-fns": "^4.4.0",
"fastify": "^5.12.5",
"pg": "^8.23.1",
"redis": "^6.3.0",
"reflect-metadata": "^0.2.2",
"rxjs": "^7.8.1",
"zod": "^4.6.5"
},
"devDependencies": {
"@nestjs/cli": "^12.0.0",
"@nestjs/mau": "^0.2.6",
"@nestjs/schematics": "^12.0.0",
"@nestjs/testing": "^12.0.1",
"@types/express": "^5.0.0",
"@types/node": "^24.0.0",
"@types/pg": "^8.23.1",
"@types/supertest": "^7.0.0",
"@vitest/coverage-v8": "^4.1.2",
"dotenv": "^18.0.5",
"nestjs-spelunker": "^1.3.2",
"oxlint": "^1.58.0",
"prettier": "^3.4.2",
"source-map-support": "^0.5.21",
"supertest": "^7.2.2",
"tsx": "^4.23.15",
"typescript": "^6.0.3",
"vite-tsconfig-paths": "^5.1.4",
"vitest": "^4.1.2"
}
}
+123
View File
@@ -0,0 +1,123 @@
import { mkdir, writeFile } from 'node:fs/promises';
import 'reflect-metadata';
import { SpelunkerModule, type DebuggedTree } from 'nestjs-spelunker';
import { AppModule } from '../dist/app.module.js';
function mermaidId(name: string): string {
return name.replace(/[^a-zA-Z0-9_]/gu, '_');
}
function findDependencyModule(
tree: DebuggedTree[],
dependency: string,
): DebuggedTree | undefined {
return tree.find(
(candidate) =>
candidate.providers.some((item) => item.name === dependency) ||
candidate.controllers.some((item) => item.name === dependency),
);
}
function renderMermaid(tree: DebuggedTree[]): string {
const lines = [
'flowchart LR',
' %% Generated by scripts/graph-modules.ts',
' %% Solid arrows: module imports; dotted arrows: constructor dependencies',
];
const moduleNames = tree.map((module) => module.name);
for (const module of tree) {
const moduleId = mermaidId(module.name);
lines.push(` subgraph ${moduleId}["${module.name}"]`);
for (const provider of module.providers) {
lines.push(
` ${moduleId}_${mermaidId(provider.name)}["provider: ${provider.name}"]`,
);
}
for (const controller of module.controllers) {
lines.push(
` ${moduleId}_${mermaidId(controller.name)}["controller: ${controller.name}"]`,
);
}
lines.push(' end');
}
for (const module of tree) {
for (const imported of module.imports) {
if (moduleNames.includes(imported)) {
lines.push(
` ${mermaidId(module.name)} -->|imports| ${mermaidId(imported)}`,
);
}
}
for (const item of [...module.providers, ...module.controllers]) {
for (const dependency of item.dependencies) {
const targetModule = findDependencyModule(tree, dependency);
if (targetModule) {
const source = `${mermaidId(module.name)}_${mermaidId(item.name)}`;
const target = `${mermaidId(targetModule.name)}_${mermaidId(dependency)}`;
lines.push(` ${source} -.->|injects| ${target}`);
}
}
}
}
return `${lines.join('\n')}\n`;
}
function renderMarkdown(tree: DebuggedTree[], mermaid: string): string {
const lines = [
'# NestJS dependency graph',
'',
'Generated from `AppModule` with `nestjs-spelunker` static module debugging.',
'',
'- Solid arrows: module imports.',
'- Dotted arrows: constructor dependencies.',
'- The generator does not boot PostgreSQL or Redis.',
'',
'```mermaid',
mermaid.trim(),
'```',
'',
'## Module details',
'',
];
for (const module of tree) {
lines.push(
`### ${module.name}`,
'',
`- Imports: ${module.imports.join(', ') || 'none'}`,
);
lines.push(
`- Exports: ${module.exports.map((item) => `${item.name} (${item.type})`).join(', ') || 'none'}`,
);
lines.push('', '| Kind | Name | Dependencies |', '| --- | --- | --- |');
for (const provider of module.providers) {
lines.push(
`| provider | ${provider.name} | ${provider.dependencies.join(', ') || 'none'} |`,
);
}
for (const controller of module.controllers) {
lines.push(
`| controller | ${controller.name} | ${controller.dependencies.join(', ') || 'none'} |`,
);
}
lines.push('');
}
return lines.join('\n');
}
const tree = await SpelunkerModule.debug(AppModule);
const mermaid = renderMermaid(tree);
await mkdir('../docs/architecture', { recursive: true });
await writeFile(
'../docs/architecture/nest-module-details.json',
JSON.stringify(tree, null, 2),
);
await writeFile('../docs/architecture/nest-module-graph.mmd', mermaid);
await writeFile(
'../docs/architecture/nest-dependency-graph.md',
renderMarkdown(tree, mermaid),
);
+33
View File
@@ -0,0 +1,33 @@
import { Module } from '@nestjs/common';
import { AppConfigModule } from './config/app-config.module.js';
import { DatabaseModule } from './database/database.module.js';
import { RedisModule } from './redis/redis.module.js';
import { AuthModule } from './auth/auth.module.js';
import { ChatsModule } from './chats/chats.module.js';
import { HealthModule } from './health/health.module.js';
import { MessagesModule } from './messages/messages.module.js';
import { MetricsModule } from './metrics/metrics.module.js';
import { UsersModule } from './users/users.module.js';
import { APP_FILTER } from '@nestjs/core';
import { ApiExceptionFilter } from './common/errors/api-exception.filter.js';
@Module({
imports: [
AppConfigModule,
DatabaseModule,
RedisModule,
UsersModule,
AuthModule,
HealthModule,
ChatsModule,
MessagesModule,
MetricsModule,
],
providers: [
{
provide: APP_FILTER,
useClass: ApiExceptionFilter,
},
],
})
export class AppModule {}
+79
View File
@@ -0,0 +1,79 @@
import {
BadRequestException,
Body,
Controller,
Delete,
Headers,
HttpCode,
HttpStatus,
Post,
UnauthorizedException,
UseGuards,
} from '@nestjs/common';
import { TextDecoder } from 'node:util';
import { AuthService } from './auth.service.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
const BASE64 =
/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
const BASIC_CHALLENGE = 'Basic realm="messenger", charset="UTF-8"';
function basicUnauthorized(): UnauthorizedException {
return new UnauthorizedException({
message: 'Unauthorized',
challenge: BASIC_CHALLENGE,
});
}
function bearerUnauthorized(): UnauthorizedException {
return new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
function parseBasic(value: string | undefined): [string, string] {
if (typeof value !== 'string') throw basicUnauthorized();
const match = /^Basic[ \t]+([^ \t]+)$/iu.exec(value);
if (!match || !BASE64.test(match[1])) throw basicUnauthorized();
const bytes = Buffer.from(match[1], 'base64');
if (bytes.toString('base64') !== match[1]) throw basicUnauthorized();
let decoded: string;
try {
decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
} catch {
throw basicUnauthorized();
}
const separator = decoded.indexOf(':');
if (separator < 1) throw basicUnauthorized();
return [decoded.slice(0, separator), decoded.slice(separator + 1)];
}
@Controller('api/v1/auth/sessions')
export class AuthController {
constructor(private readonly auth: AuthService) {}
@Post()
create(
@Headers('authorization') authorization: string | undefined,
@Body() body: unknown,
) {
const [username, password] = parseBasic(authorization);
if (body !== undefined)
throw new BadRequestException(
'Session creation does not accept a body',
);
return this.auth.createSession(username, password);
}
@Delete('current')
@UseGuards(CurrentUserGuard)
@HttpCode(HttpStatus.NO_CONTENT)
async delete(
@Headers('authorization') authorization: string | undefined,
): Promise<void> {
if (!authorization || !/^Bearer\s+[^\s]+$/iu.test(authorization))
throw bearerUnauthorized();
await this.auth.deleteSession(authorization.slice(7).trim());
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { UsersModule } from '../users/users.module.js';
import { AuthController } from './auth.controller.js';
import { AuthService } from './auth.service.js';
import { SessionRepository } from './session.repository.js';
import { MetricsModule } from '../metrics/metrics.module.js';
@Module({
imports: [UsersModule, DatabaseModule, RedisModule, MetricsModule],
controllers: [AuthController],
providers: [AuthService, SessionRepository],
exports: [AuthService, SessionRepository],
})
export class AuthModule {}
+63
View File
@@ -0,0 +1,63 @@
import {
Injectable,
ServiceUnavailableException,
UnauthorizedException,
} from '@nestjs/common';
import argon2 from 'argon2';
import type { User } from '../users/user.js';
import { UsersService } from '../users/users.service.js';
import { SessionRepository } from './session.repository.js';
export type SessionResponse = {
token: string;
token_type: 'Bearer';
expires_at: string;
user: User;
};
@Injectable()
export class AuthService {
constructor(
private readonly users: UsersService,
private readonly sessions: SessionRepository,
) {}
async createSession(
username: string,
password: string,
): Promise<SessionResponse> {
const storedUser = await this.users.findByUsername(username);
if (
!storedUser ||
!(await argon2.verify(storedUser.password_hash, password))
) {
throw new UnauthorizedException();
}
const user: User = {
id: storedUser.id,
username: storedUser.username,
display_name: storedUser.display_name,
created_at: storedUser.created_at,
};
let session: { token: string; expiresAt: string };
try {
session = await this.sessions.create(user.id);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
return {
token: session.token,
token_type: 'Bearer',
expires_at: session.expiresAt,
user,
};
}
async deleteSession(token: string): Promise<void> {
try {
await this.sessions.delete(token);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
}
}
+35
View File
@@ -0,0 +1,35 @@
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { randomBytes } from 'node:crypto';
import type { AppConfig } from '../config/app-config.schema.js';
import { RedisClient } from '../redis/redis.client.js';
import { MetricsService } from '../metrics/metrics.service.js';
@Injectable()
export class SessionRepository {
constructor(
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
async create(
userId: string,
): Promise<{ token: string; expiresAt: string }> {
const token = randomBytes(32).toString('base64url');
const ttl = this.config.getOrThrow('SESSION_TTL_SECONDS');
const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
this.metrics.increment('session_set');
await this.redis.set(
`session:${token}`,
JSON.stringify({ user_id: userId, expires_at: expiresAt }),
{ EX: ttl },
);
return { token, expiresAt };
}
delete(token: string): Promise<number> {
this.metrics.increment('session_del');
return this.redis.del(`session:${token}`);
}
}
+6
View File
@@ -0,0 +1,6 @@
export type Chat = {
id: string;
title: string;
member_ids: string[];
created_at: string;
};
+49
View File
@@ -0,0 +1,49 @@
import {
BadRequestException,
Body,
Controller,
DefaultValuePipe,
Get,
Param,
ParseIntPipe,
ParseUUIDPipe,
Post,
Query,
UseGuards,
} from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import { ChatsService } from './chats.service.js';
import { CreateChatDto } from './dto/create-chat.dto.js';
import type { User } from '../users/user.js';
@Controller('api/v1/chats')
@UseGuards(CurrentUserGuard)
export class ChatsController {
constructor(private readonly chatsService: ChatsService) {}
@Post()
create(@Body() body: CreateChatDto, @CurrentUser() currentUser: User) {
return this.chatsService.create(body, currentUser);
}
@Get()
list(
@CurrentUser() currentUser: User,
@Query('limit', new DefaultValuePipe(50), new ParseIntPipe())
limit: number,
@Query('cursor') cursor?: string,
) {
if (limit < 1 || limit > 100)
throw new BadRequestException('limit must be between 1 and 100');
return this.chatsService.listForUser(currentUser, limit, cursor);
}
@Get(':chatId')
get(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@CurrentUser() currentUser: User,
) {
return this.chatsService.getForUser(chatId, currentUser);
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
import { UsersModule } from '../users/users.module.js';
import { ChatsController } from './chats.controller.js';
import { ChatsRepository } from './chats.repository.js';
import { ChatsService } from './chats.service.js';
@Module({
imports: [UsersModule, DatabaseModule, RedisModule, MetricsModule],
controllers: [ChatsController],
providers: [ChatsRepository, ChatsService],
exports: [ChatsService],
})
export class ChatsModule {}
+109
View File
@@ -0,0 +1,109 @@
import { BadRequestException, Injectable } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { DatabaseClient } from '../database/database.client.js';
import type { Cursor } from '../common/http/cursor.js';
import type { User } from '../users/user.js';
import type { Chat } from './chat.js';
type ChatRow = {
id: string;
title: string;
created_at: Date | string;
member_ids: string[];
};
function toChat(row: ChatRow): Chat {
return {
id: row.id,
title: row.title,
created_at: new Date(row.created_at).toISOString(),
member_ids: row.member_ids,
};
}
@Injectable()
export class ChatsRepository {
constructor(private readonly database: DatabaseClient) {}
async create(title: string, memberIds: string[]): Promise<Chat> {
const id = randomUUID();
return this.database.withTransaction(async (client) => {
const users = await client.query<{ id: string }>({
name: 'chats.validateMembers',
text: 'SELECT id FROM users WHERE id = ANY($1::uuid[])',
values: [memberIds],
});
if (users.rowCount !== memberIds.length)
throw new BadRequestException('Chat member does not exist');
const inserted = await client.query<ChatRow>({
name: 'chats.insert',
text: 'INSERT INTO chats (id, title) VALUES ($1, $2) RETURNING id, title, created_at',
values: [id, title],
});
for (const memberId of memberIds) {
await client.query({
name: 'chats.insertMember',
text: 'INSERT INTO chat_members (chat_id, user_id) VALUES ($1, $2)',
values: [id, memberId],
});
}
return {
...toChat({ ...inserted.rows[0], member_ids: memberIds }),
member_ids: memberIds,
};
});
}
async findForUser(id: string, user: User): Promise<Chat | undefined> {
const result = await this.database.query<ChatRow>(
'chats.findForUser',
`SELECT c.id, c.title, c.created_at,
COALESCE(array_agg(cm.user_id ORDER BY cm.user_id)
FILTER (WHERE cm.user_id IS NOT NULL), '{}') AS member_ids
FROM chats c
LEFT JOIN chat_members cm ON cm.chat_id = c.id
WHERE c.id = $1
AND EXISTS (
SELECT 1 FROM chat_members own
WHERE own.chat_id = c.id AND own.user_id = $2
)
GROUP BY c.id`,
[id, user.id],
);
return result.rows[0] ? toChat(result.rows[0]) : undefined;
}
async findPageForUser(
user: User,
limit: number,
cursor?: Cursor,
): Promise<{ items: Chat[]; hasMore: boolean }> {
const values: unknown[] = [user.id];
let predicate = '';
if (cursor) {
values.push(cursor.created_at, cursor.id);
predicate =
'AND (c.created_at, c.id) > ($2::timestamptz, $3::uuid)';
}
values.push(limit + 1);
const result = await this.database.query<ChatRow>(
'chats.listForUser',
`SELECT c.id, c.title, c.created_at,
COALESCE(array_agg(cm.user_id ORDER BY cm.user_id)
FILTER (WHERE cm.user_id IS NOT NULL), '{}') AS member_ids
FROM chats c
LEFT JOIN chat_members cm ON cm.chat_id = c.id
WHERE EXISTS (
SELECT 1 FROM chat_members own
WHERE own.chat_id = c.id AND own.user_id = $1
)
${predicate}
GROUP BY c.id ORDER BY c.created_at, c.id LIMIT $${values.length}`,
values,
);
return {
items: result.rows.slice(0, limit).map(toChat),
hasMore: result.rows.length > limit,
};
}
}
+61
View File
@@ -0,0 +1,61 @@
import {
BadRequestException,
Injectable,
NotFoundException,
} from '@nestjs/common';
import { encodeCursor, decodeCursor } from '../common/http/cursor.js';
import type { Page } from '../common/http/page.js';
import type { User } from '../users/user.js';
import type { CreateChatDto } from './dto/create-chat.dto.js';
import type { Chat } from './chat.js';
import { ChatsRepository } from './chats.repository.js';
@Injectable()
export class ChatsService {
constructor(private readonly chatsRepository: ChatsRepository) {}
create(input: CreateChatDto, currentUser: User): Promise<Chat> {
if (!input.member_ids.includes(currentUser.id))
throw new BadRequestException('Current user must be a chat member');
if (new Set(input.member_ids).size !== input.member_ids.length)
throw new BadRequestException('Duplicate chat member');
return this.chatsRepository.create(input.title, input.member_ids);
}
async getForUser(chatId: string, currentUser: User): Promise<Chat> {
const chat = await this.chatsRepository.findForUser(
chatId,
currentUser,
);
if (!chat) throw new NotFoundException();
return chat;
}
async listForUser(
currentUser: User,
limit: number,
cursorValue?: string,
): Promise<Page<Chat>> {
const scope = `chats:${currentUser.id}`;
const cursor = cursorValue
? decodeCursor(cursorValue, scope)
: undefined;
const page = await this.chatsRepository.findPageForUser(
currentUser,
limit,
cursor,
);
const last = page.items.at(-1);
return {
items: page.items,
next_cursor:
page.hasMore && last
? encodeCursor({
scope,
created_at: last.created_at,
id: last.id,
})
: null,
};
}
}
+26
View File
@@ -0,0 +1,26 @@
import {
ArrayMaxSize,
ArrayMinSize,
ArrayUnique,
IsArray,
IsString,
IsUUID,
Matches,
} from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateChatDto {
@IsString()
@CodePointLength(1, 100)
@Matches(/\S/, {
message: 'title must contain a non-whitespace character',
})
title: string;
@IsArray()
@ArrayMinSize(1)
@ArrayMaxSize(100)
@ArrayUnique()
@IsUUID('4', { each: true })
member_ids: string[];
}
@@ -0,0 +1,10 @@
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import type { User } from '../../users/user.js';
import { FastifyRequest } from 'fastify';
export const CurrentUser = createParamDecorator(
(_data: unknown, context: ExecutionContext): User => {
const request = context.switchToHttp().getRequest<FastifyRequest>();
return request.currentUser!;
},
);
+85
View File
@@ -0,0 +1,85 @@
import {
CanActivate,
ExecutionContext,
Injectable,
ServiceUnavailableException,
UnauthorizedException,
} from '@nestjs/common';
import type { FastifyRequest } from 'fastify';
import type { User } from '../../users/user.js';
import { RedisClient } from '../../redis/redis.client.js';
import { UsersService } from '../../users/users.service.js';
import { MetricsService } from '../../metrics/metrics.service.js';
@Injectable()
export class CurrentUserGuard implements CanActivate {
constructor(
private readonly redis: RedisClient,
private readonly users: UsersService,
private readonly metrics: MetricsService,
) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest<FastifyRequest>();
const authorization = request.headers.authorization;
if (
typeof authorization !== 'string' ||
!/^Bearer\s+[^\s]+$/u.test(authorization)
) {
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
let session: string | null;
try {
this.metrics.increment('session_get');
session = await this.redis.get(
`session:${authorization.slice(7).trim()}`,
);
} catch {
throw new ServiceUnavailableException('Session store unavailable');
}
if (!session)
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
let userId: string;
try {
const parsed: unknown = JSON.parse(session);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('user_id' in parsed) ||
typeof parsed.user_id !== 'string' ||
!('expires_at' in parsed) ||
typeof parsed.expires_at !== 'string' ||
!/^(?:\d{4})-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u.test(
parsed.expires_at,
)
)
throw new Error('invalid session');
const expiresAt = Date.parse(parsed.expires_at);
if (!Number.isFinite(expiresAt) || Date.now() >= expiresAt)
throw new Error('expired session');
userId = parsed.user_id;
} catch {
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="messenger"',
});
}
let user: User | undefined;
try {
user = await this.users.findById(userId);
} catch {
throw new ServiceUnavailableException(
'Authentication service unavailable',
);
}
if (!user) throw new UnauthorizedException();
request.currentUser = user;
return true;
}
}
+7
View File
@@ -0,0 +1,7 @@
export type ApiErrorBody = {
error: {
code: string;
message: string;
request_id: string;
};
};
@@ -0,0 +1,148 @@
import {
ArgumentsHost,
Catch,
ExceptionFilter,
HttpException,
HttpStatus,
Logger,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import { randomUUID } from 'node:crypto';
import type { ApiErrorBody } from './api-error.js';
type RequestWithId = { requestId?: string; method?: string; url?: string };
type ExceptionBody = { message?: unknown; challenge?: unknown };
// Connection/session loss codes reported by node-postgres and the network layer.
const UNAVAILABLE_ERROR_CODES: Record<string, true> = {
ECONNREFUSED: true,
ECONNRESET: true,
ENOTFOUND: true,
ETIMEDOUT: true,
EPIPE: true,
'08000': true,
'08001': true,
'08003': true,
'08004': true,
'08006': true,
'57P01': true,
'57P02': true,
'57P03': true,
'53300': true,
};
// Some driver failures carry no `code` at all: node-postgres raises plain errors
// when a connection dies or its pool attempt times out, and node-redis reports a
// closed socket the same way. Without these patterns a stopped database would
// surface as an internal fault instead of a bounded outage.
const UNAVAILABLE_ERROR_MESSAGES = [
'Connection terminated unexpectedly',
'Connection terminated due to connection timeout',
'timeout exceeded when trying to connect',
'Client has encountered a connection error and is not queryable',
'Socket closed unexpectedly',
'Connection is closed',
];
function isDependencyOutage(exception: unknown): boolean {
if (typeof exception !== 'object' || exception === null) return false;
const code = (exception as { code?: unknown }).code;
if (typeof code === 'string' && UNAVAILABLE_ERROR_CODES[code] === true)
return true;
const message = (exception as { message?: unknown }).message;
return (
typeof message === 'string' &&
UNAVAILABLE_ERROR_MESSAGES.some((pattern) => message.includes(pattern))
);
}
function errorCodeForStatus(status: number): string {
const codes: Record<number, string> = {
[HttpStatus.BAD_REQUEST]: 'invalid_request',
[HttpStatus.UNAUTHORIZED]: 'unauthorized',
[HttpStatus.NOT_FOUND]: 'not_found',
[HttpStatus.CONFLICT]: 'conflict',
[HttpStatus.PAYLOAD_TOO_LARGE]: 'payload_too_large',
[HttpStatus.UNSUPPORTED_MEDIA_TYPE]: 'unsupported_media_type',
[HttpStatus.TOO_MANY_REQUESTS]: 'rate_limited',
[HttpStatus.SERVICE_UNAVAILABLE]: 'unavailable',
};
return codes[status] ?? 'internal_error';
}
@Catch()
export class ApiExceptionFilter implements ExceptionFilter {
private readonly logger = new Logger(ApiExceptionFilter.name);
constructor(private readonly adapterHost: HttpAdapterHost) {}
catch(exception: unknown, host: ArgumentsHost): void {
const http = host.switchToHttp();
const request = http.getRequest<RequestWithId>();
const response = http.getResponse<unknown>();
const adapter = this.adapterHost.httpAdapter;
const requestId = request.requestId ?? randomUUID();
request.requestId = requestId;
let status = HttpStatus.INTERNAL_SERVER_ERROR;
let message = 'Internal server error';
let challenge: string | undefined;
if (exception instanceof HttpException) {
status = exception.getStatus();
const body = exception.getResponse();
const details: ExceptionBody =
typeof body === 'object' && body !== null
? (body as ExceptionBody)
: {};
const rawMessage =
'message' in details ? details.message : undefined;
challenge =
typeof details.challenge === 'string'
? details.challenge
: undefined;
message = Array.isArray(rawMessage)
? rawMessage.join('; ')
: typeof rawMessage === 'string'
? rawMessage
: 'Request failed';
if (status === HttpStatus.NOT_FOUND) message = 'Resource not found';
if (status >= HttpStatus.INTERNAL_SERVER_ERROR)
message =
status === HttpStatus.SERVICE_UNAVAILABLE
? 'Service unavailable'
: 'Internal server error';
} else if (isDependencyOutage(exception)) {
// A dropped dependency is a bounded outage, not an internal fault.
status = HttpStatus.SERVICE_UNAVAILABLE;
message = 'Service unavailable';
this.logger.warn(
`Dependency outage on ${request.method ?? ''} ${request.url ?? ''}: ${exception instanceof Error ? exception.message : 'unknown error'}`,
);
} else {
this.logger.error(
`Unhandled exception on ${request.method ?? ''} ${request.url ?? ''}`,
exception instanceof Error
? exception.stack
: String(exception),
);
}
if (status === HttpStatus.UNAUTHORIZED) {
const authChallenge =
challenge ??
(request.method === 'POST' &&
request.url?.startsWith('/api/v1/auth/sessions')
? 'Basic realm="messenger", charset="UTF-8"'
: 'Bearer realm="messenger"');
adapter.setHeader(response, 'WWW-Authenticate', authChallenge);
}
adapter.setHeader(response, 'X-Request-Id', requestId);
const payload: ApiErrorBody = {
error: {
code: errorCodeForStatus(status),
message,
request_id: requestId,
},
};
adapter.reply(response, payload, status);
}
}
+85
View File
@@ -0,0 +1,85 @@
import { BadRequestException } from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { describe, expect, it } from 'vitest';
import { decodeCursor, encodeCursor } from './cursor.js';
const scope = 'messages:6f1c2a3e-1111-4222-8333-444455556666';
function encode(createdAt: string, cursorScope = scope): string {
return encodeCursor({
scope: cursorScope,
created_at: createdAt,
id: randomUUID(),
});
}
describe('decodeCursor', () => {
it('accepts valid instants and normalizes them to canonical milliseconds', () => {
const accepted: Array<[string, string]> = [
['2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z'],
['2026-01-01T00:00:00Z', '2026-01-01T00:00:00.000Z'],
['2026-01-01T00:00:00.999999Z', '2026-01-01T00:00:00.999Z'],
['2024-02-29T23:59:59.000Z', '2024-02-29T23:59:59.000Z'],
['2026-12-31T23:59:59.999Z', '2026-12-31T23:59:59.999Z'],
];
for (const [createdAt, expected] of accepted) {
const decoded = decodeCursor(encode(createdAt), scope);
expect(decoded.created_at).toBe(expected);
expect(decoded.scope).toBe(scope);
}
});
it('rejects calendar dates that the platform parser rolls over', () => {
// 2026-02-31 would silently become 2026-03-03 and then fail inside SQL.
for (const createdAt of [
'2026-02-31T00:00:00.000Z',
'2025-02-29T00:00:00.000Z',
'2026-04-31T00:00:00.000Z',
'2026-06-31T12:00:00.000Z',
]) {
expect(() => decodeCursor(encode(createdAt), scope)).toThrow(
BadRequestException,
);
}
});
it('rejects out-of-range and malformed timestamps', () => {
for (const createdAt of [
'2026-01-01T24:00:00.000Z',
'2026-01-01T00:00:60.000Z',
'2026-13-01T00:00:00.000Z',
'2026-00-01T00:00:00.000Z',
'2026-01-01T00:00:00',
'2026-01-01T00:00:00+02:00',
'2026-1-1T00:00:00.000Z',
'2026-01-01',
'not-a-timestamp',
]) {
expect(() => decodeCursor(encode(createdAt), scope)).toThrow(
BadRequestException,
);
}
});
it('rejects a cursor from another scope, a malformed id, and non-cursor input', () => {
expect(() =>
decodeCursor(
encode('2026-01-01T00:00:00.000Z', 'messages:other'),
scope,
),
).toThrow(BadRequestException);
expect(() =>
decodeCursor(
encodeCursor({
scope,
created_at: '2026-01-01T00:00:00.000Z',
id: 'not-a-uuid',
}),
scope,
),
).toThrow(BadRequestException);
expect(() => decodeCursor('not-a-cursor', scope)).toThrow(
BadRequestException,
);
});
});
+54
View File
@@ -0,0 +1,54 @@
import { BadRequestException } from '@nestjs/common';
import { isValid, parseISO } from 'date-fns';
export type Cursor = {
scope: string;
created_at: string;
id: string;
};
// Format check for the canonical API shape: `Date.prototype.toISOString()` with
// optional fractional seconds. Explicit ranges reject values such as 24:00:00.
// Calendar validity (2026-02-31, 2025-02-29, 2026-04-31) is checked by
// date-fns `parseISO`, which refuses impossible dates that the platform parser
// would silently roll over into another day.
const CURSOR_TIMESTAMP =
/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?Z$/u;
export function encodeCursor(cursor: Cursor): string {
return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
}
export function decodeCursor(value: string, expectedScope: string): Cursor {
try {
const parsed: unknown = JSON.parse(
Buffer.from(value, 'base64url').toString('utf8'),
);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('scope' in parsed) ||
!('created_at' in parsed) ||
!('id' in parsed) ||
typeof parsed.scope !== 'string' ||
typeof parsed.created_at !== 'string' ||
typeof parsed.id !== 'string' ||
parsed.scope !== expectedScope ||
!/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu.test(
parsed.id,
) ||
!CURSOR_TIMESTAMP.test(parsed.created_at)
)
throw new Error('invalid cursor');
const instant = parseISO(parsed.created_at);
if (!isValid(instant)) throw new Error('invalid cursor');
return {
scope: parsed.scope,
created_at: instant.toISOString(),
id: parsed.id,
};
} catch {
throw new BadRequestException('Invalid cursor');
}
}
+4
View File
@@ -0,0 +1,4 @@
export type Page<T> = {
items: T[];
next_cursor: string | null;
};
@@ -0,0 +1,50 @@
import {
CallHandler,
ExecutionContext,
Injectable,
NestInterceptor,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import { randomUUID } from 'node:crypto';
import { finalize, Observable } from 'rxjs';
import { MetricsService } from '../../metrics/metrics.service.js';
const INSTANCE_ID = randomUUID();
type RequestWithId = { requestId?: string };
@Injectable()
export class RequestIdInterceptor implements NestInterceptor {
constructor(
private readonly adapterHost: HttpAdapterHost,
private readonly metrics: MetricsService,
) {}
intercept(
context: ExecutionContext,
next: CallHandler,
): Observable<unknown> {
const request = context.switchToHttp().getRequest<RequestWithId>();
const response = context.switchToHttp().getResponse<unknown>();
const requestId = randomUUID();
const startedAt = performance.now();
request.requestId = requestId;
this.adapterHost.httpAdapter.setHeader(
response,
'X-Request-Id',
requestId,
);
this.adapterHost.httpAdapter.setHeader(
response,
'X-Instance-Id',
INSTANCE_ID,
);
this.metrics.increment('request_count');
return next
.handle()
.pipe(
finalize(() =>
this.metrics.observeLatency(performance.now() - startedAt),
),
);
}
}
@@ -0,0 +1,43 @@
import { validate } from 'class-validator';
import { describe, expect, it } from 'vitest';
import { CodePointLength } from './code-point-length.js';
class Sample {
@CodePointLength(3, 5)
value!: string;
}
async function fails(value: unknown): Promise<boolean> {
const sample = new Sample();
(sample as { value: unknown }).value = value;
const errors = await validate(sample);
return errors.length > 0;
}
describe('CodePointLength', () => {
it('counts Unicode code points instead of UTF-16 units', async () => {
// '🔐' is one code point but two UTF-16 units.
expect(await fails('🔐🔐')).toBe(true);
expect(await fails('🔐🔐🔐')).toBe(false);
expect(await fails('🔐🔐🔐🔐🔐')).toBe(false);
expect(await fails('🔐🔐🔐🔐🔐🔐')).toBe(true);
// Combining marks are separate code points, not grapheme clusters:
// three 'é' sequences are six code points and exceed the maximum.
expect(await fails('e\u0301e\u0301')).toBe(false);
expect(await fails('e\u0301e\u0301e\u0301')).toBe(true);
});
it('applies to BMP text boundaries', async () => {
expect(await fails('ab')).toBe(true);
expect(await fails('abc')).toBe(false);
expect(await fails('abcde')).toBe(false);
expect(await fails('abcdef')).toBe(true);
});
it('rejects empty and non-string values', async () => {
expect(await fails('')).toBe(true);
expect(await fails(undefined)).toBe(true);
expect(await fails(12345)).toBe(true);
expect(await fails(['a', 'b', 'c'])).toBe(true);
});
});
@@ -0,0 +1,38 @@
import {
registerDecorator,
ValidatorConstraint,
type ValidationArguments,
type ValidatorConstraintInterface,
} from 'class-validator';
// JSON Schema (and the course contract) measure string lengths in Unicode code
// points, while String.prototype.length counts UTF-16 units: one emoji outside
// the BMP is two units. `@Length` therefore accepted an 11-emoji password
// (22 units) and rejected 4000 emoji (8000 units), so these fields use an
// explicit code-point validator instead.
@ValidatorConstraint({ name: 'codePointLength', async: false })
class CodePointLengthConstraint implements ValidatorConstraintInterface {
validate(value: unknown, args: ValidationArguments): boolean {
const [min, max] = args.constraints as [number, number];
if (typeof value !== 'string') return false;
const length = [...value].length;
return length >= min && length <= max;
}
defaultMessage(args: ValidationArguments): string {
const [min, max] = args.constraints as [number, number];
return `${args.property} must be between ${min} and ${max} code points`;
}
}
export function CodePointLength(min: number, max: number): PropertyDecorator {
return (target, propertyKey) => {
registerDecorator({
name: 'codePointLength',
target: target.constructor,
propertyName: String(propertyKey),
constraints: [min, max],
validator: CodePointLengthConstraint,
});
};
}
+16
View File
@@ -0,0 +1,16 @@
import { Global, Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { parseAppConfig } from './app-config.schema.js';
@Global()
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
cache: true,
validate: parseAppConfig,
}),
],
exports: [ConfigModule],
})
export class AppConfigModule {}
+91
View File
@@ -0,0 +1,91 @@
import { readFileSync } from 'node:fs';
import { z } from 'zod';
function numeric(
name: string,
minimum: number,
maximum: number | undefined,
fallback: number,
) {
let schema = z
.number({ message: `${name} must be a number` })
.int()
.min(minimum);
if (maximum !== undefined) schema = schema.max(maximum);
return z.preprocess(
(value) =>
typeof value === 'string' && value.trim() !== ''
? Number(value)
: value,
schema.default(fallback),
);
}
function requiredString(name: string) {
return z
.string({ message: `${name} is required` })
.min(1, `${name} is required`);
}
export const appConfigSchema = z
.object({
APP_HOST: z.string().min(1).default('0.0.0.0'),
APP_PORT: numeric('APP_PORT', 1, 65535, 8080),
APP_ENV: z.string().min(1).default('lab'),
SESSION_TTL_SECONDS: numeric('SESSION_TTL_SECONDS', 2, undefined, 3600),
DATABASE_URL: requiredString('DATABASE_URL'),
REDIS_URL: requiredString('REDIS_URL'),
DATABASE_POOL_MAX: numeric('DATABASE_POOL_MAX', 1, 100, 10),
DATABASE_CONNECTION_TIMEOUT_MS: numeric(
'DATABASE_CONNECTION_TIMEOUT_MS',
1,
undefined,
5000,
),
DATABASE_STATEMENT_TIMEOUT_MS: numeric(
'DATABASE_STATEMENT_TIMEOUT_MS',
1,
undefined,
5000,
),
CACHE_TTL_SECONDS: numeric('CACHE_TTL_SECONDS', 1, undefined, 30),
CACHE_MODE: z.enum(['protected', 'naive']).default('protected'),
CACHE_LOCK_TTL_MS: numeric('CACHE_LOCK_TTL_MS', 1, undefined, 1000),
CACHE_MISS_DELAY_MS: numeric('CACHE_MISS_DELAY_MS', 0, undefined, 0),
METRICS_TOKEN: z.string().min(1).optional(),
DRAIN_DELAY_MS: numeric('DRAIN_DELAY_MS', 0, undefined, 5000),
})
.strip();
export type AppConfig = z.infer<typeof appConfigSchema>;
export type AppConfigKey = keyof AppConfig;
function resolveSecret(
raw: Record<string, unknown>,
key: 'DATABASE_URL' | 'REDIS_URL',
): unknown {
const fileKey = `${key}_FILE`;
const path = raw[fileKey];
if (typeof path !== 'string' || path.length === 0) return raw[key];
try {
const value = readFileSync(path, 'utf8').trim();
if (value.length === 0)
throw new Error(`${fileKey} contains an empty value`);
return value;
} catch (error) {
if (
error instanceof Error &&
error.message.includes('contains an empty value')
)
throw error;
throw new Error(`${fileKey} could not be read`);
}
}
export function parseAppConfig(raw: Record<string, unknown>): AppConfig {
return appConfigSchema.parse({
...raw,
DATABASE_URL: resolveSecret(raw, 'DATABASE_URL'),
REDIS_URL: resolveSecret(raw, 'REDIS_URL'),
});
}
+75
View File
@@ -0,0 +1,75 @@
import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import pg from 'pg';
import { MetricsService } from '../metrics/metrics.service.js';
import type { AppConfig } from '../config/app-config.schema.js';
@Injectable()
export class DatabaseClient implements OnModuleDestroy {
readonly pool: pg.Pool;
private readonly logger = new Logger(DatabaseClient.name);
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {
this.pool = new pg.Pool({
connectionString: this.config.getOrThrow('DATABASE_URL'),
max: this.config.getOrThrow('DATABASE_POOL_MAX'),
connectionTimeoutMillis: this.config.getOrThrow(
'DATABASE_CONNECTION_TIMEOUT_MS',
),
statement_timeout: this.config.getOrThrow(
'DATABASE_STATEMENT_TIMEOUT_MS',
),
});
// Idle clients emit 'error' on the pool when the database drops; without a
// listener Node treats it as uncaught and terminates the process.
this.pool.on('error', (error: Error) => {
this.metrics.increment('database.pool_error');
this.logger.warn(`PostgreSQL pool error: ${error.message}`);
});
}
query<T extends pg.QueryResultRow = pg.QueryResultRow>(
label: string,
text: string,
values: readonly unknown[] = [],
): Promise<pg.QueryResult<T>> {
this.metrics.increment(label);
return this.pool.query<T>({ text, values: [...values] });
}
async health(): Promise<void> {
await this.query('health.database', 'SELECT 1');
}
async withTransaction<T>(
work: (client: pg.PoolClient) => Promise<T>,
): Promise<T> {
const client = await this.pool.connect();
try {
await client.query('BEGIN');
const result = await work(client);
await client.query('COMMIT');
return result;
} catch (error) {
try {
await client.query('ROLLBACK');
} catch (rollbackError) {
this.metrics.increment('database.rollback_error');
this.logger.warn(
`Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : 'unknown error'}`,
);
}
// Callers must see the operation error, not the rollback error.
throw error;
} finally {
client.release();
}
}
async onModuleDestroy(): Promise<void> {
await this.pool.end();
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsModule } from '../metrics/metrics.module.js';
import { DatabaseClient } from './database.client.js';
@Module({
imports: [MetricsModule],
providers: [DatabaseClient],
exports: [DatabaseClient],
})
export class DatabaseModule {}
+63
View File
@@ -0,0 +1,63 @@
import { readdir, readFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { DatabaseClient } from './database.client.js';
import { MetricsService } from '../metrics/metrics.service.js';
import { parseAppConfig } from '../config/app-config.schema.js';
const migrationsDirectory = join(
dirname(fileURLToPath(import.meta.url)),
'migrations',
);
async function migrationFiles(): Promise<string[]> {
const files = await readdir(migrationsDirectory);
return files.filter((file) => /^\d+_.+\.sql$/u.test(file)).sort();
}
export async function runMigrations(database: DatabaseClient): Promise<void> {
await database.query(
'migrations.ensure_table',
`CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
)`,
);
for (const version of await migrationFiles()) {
await database.withTransaction(async (client) => {
const applied = await client.query({
text: 'SELECT version FROM schema_migrations WHERE version = $1',
values: [version],
});
if (applied.rowCount) return;
const sql = await readFile(
join(migrationsDirectory, version),
'utf8',
);
await client.query(sql);
await client.query({
text: 'INSERT INTO schema_migrations (version) VALUES ($1)',
values: [version],
});
});
}
}
async function main(): Promise<void> {
const config = parseAppConfig(process.env as Record<string, unknown>);
const database = new DatabaseClient(
{
getOrThrow: (key: keyof typeof config) => config[key],
} as never,
new MetricsService(),
);
try {
await runMigrations(database);
} finally {
await database.onModuleDestroy();
}
}
if (process.argv[1] === fileURLToPath(import.meta.url)) await main();
@@ -0,0 +1,41 @@
CREATE TABLE IF NOT EXISTS schema_migrations (
version text PRIMARY KEY,
applied_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS users (
id uuid PRIMARY KEY,
username text NOT NULL UNIQUE,
display_name text NOT NULL,
password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS chats (
id uuid PRIMARY KEY,
title text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
message_version bigint NOT NULL DEFAULT 0
);
CREATE TABLE IF NOT EXISTS chat_members (
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
PRIMARY KEY (chat_id, user_id)
);
CREATE TABLE IF NOT EXISTS messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
sender_id uuid NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
text text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT messages_sender_member_fk
FOREIGN KEY (chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
ON DELETE RESTRICT
);
CREATE INDEX IF NOT EXISTS messages_chat_created_id_idx
ON messages (chat_id, created_at, id);
CREATE INDEX IF NOT EXISTS chat_members_user_chat_idx
ON chat_members (user_id, chat_id);
@@ -0,0 +1,5 @@
-- HTTP timestamps and keyset cursors use JavaScript millisecond precision.
-- Store the same precision so a returned cursor cannot point before its own row.
ALTER TABLE users ALTER COLUMN created_at TYPE timestamptz(3);
ALTER TABLE chats ALTER COLUMN created_at TYPE timestamptz(3);
ALTER TABLE messages ALTER COLUMN created_at TYPE timestamptz(3);
+17
View File
@@ -0,0 +1,17 @@
import { Controller, Get } from '@nestjs/common';
import { HealthService } from './health.service.js';
@Controller('health')
export class HealthController {
constructor(private readonly healthService: HealthService) {}
@Get('live')
getLive() {
return this.healthService.getLiveness();
}
@Get('ready')
async getReady() {
return this.healthService.getReadiness();
}
}
+12
View File
@@ -0,0 +1,12 @@
import { Module } from '@nestjs/common';
import { HealthController } from './health.controller.js';
import { HealthService } from './health.service.js';
import { DatabaseModule } from '../database/database.module.js';
import { RedisModule } from '../redis/redis.module.js';
@Module({
imports: [DatabaseModule, RedisModule],
controllers: [HealthController],
providers: [HealthService],
})
export class HealthModule {}
+46
View File
@@ -0,0 +1,46 @@
import { describe, expect, it, vi } from 'vitest';
import { ServiceUnavailableException } from '@nestjs/common';
import { HealthService } from './health.service.js';
describe('HealthService', () => {
it('reports liveness and readiness when dependencies are healthy', async () => {
const database = { health: vi.fn().mockResolvedValue(undefined) };
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const config = { get: vi.fn().mockReturnValue(0) };
const service = new HealthService(
database as never,
redis as never,
config as never,
);
expect(service.getLiveness()).toEqual({ status: 'ok' });
await expect(service.getReadiness()).resolves.toEqual({ status: 'ok' });
});
it('rejects readiness when a dependency is unavailable', async () => {
const database = {
health: vi.fn().mockRejectedValue(new Error('down')),
};
const redis = { health: vi.fn().mockResolvedValue(undefined) };
const service = new HealthService(
database as never,
redis as never,
{ get: vi.fn() } as never,
);
await expect(service.getReadiness()).rejects.toBeInstanceOf(
ServiceUnavailableException,
);
});
it('keeps liveness healthy while draining', async () => {
const service = new HealthService(
{ health: vi.fn() } as never,
{ health: vi.fn() } as never,
{ get: vi.fn() } as never,
);
service.setDraining();
expect(service.getLiveness()).toEqual({ status: 'ok' });
await expect(service.getReadiness()).rejects.toThrow(
'Service is shutting down',
);
});
});
+47
View File
@@ -0,0 +1,47 @@
import {
Global,
Injectable,
Module,
ServiceUnavailableException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { DatabaseClient } from '../database/database.client.js';
import { RedisClient } from '../redis/redis.client.js';
import type { AppConfig } from '../config/app-config.schema.js';
@Injectable()
export class HealthService {
private ready = true;
constructor(
private readonly database: DatabaseClient,
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
) {}
getLiveness() {
return { status: 'ok' as const };
}
async getReadiness() {
if (!this.ready)
throw new ServiceUnavailableException('Service is shutting down');
try {
await Promise.all([this.database.health(), this.redis.health()]);
} catch {
throw new ServiceUnavailableException('Dependencies unavailable');
}
return { status: 'ok' as const };
}
setDraining() {
this.ready = false;
}
async beforeApplicationShutdown(signal?: string): Promise<void> {
this.setDraining();
const delay = this.config.get<number>('DRAIN_DELAY_MS') ?? 5000;
if (signal && delay > 0) {
await new Promise<void>((resolve) => setTimeout(resolve, delay));
}
}
}
@Global()
@Module({ providers: [HealthService], exports: [HealthService] })
export class HealthServiceModule {}
+39
View File
@@ -0,0 +1,39 @@
import { NestFactory } from '@nestjs/core';
import { HttpAdapterHost } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { ValidationPipe } from '@nestjs/common';
import {
FastifyAdapter,
NestFastifyApplication,
} from '@nestjs/platform-fastify';
import { AppModule } from './app.module.js';
import { MetricsService } from './metrics/metrics.service.js';
import { RequestIdInterceptor } from './common/http/request-id.interceptor.js';
async function bootstrap(): Promise<void> {
const app = await NestFactory.create<NestFastifyApplication>(
AppModule,
new FastifyAdapter({ logger: true }),
);
app.useGlobalInterceptors(
new RequestIdInterceptor(
app.get(HttpAdapterHost),
app.get(MetricsService),
),
);
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
}),
);
app.enableShutdownHooks();
const config = app.get(ConfigService);
const port = config.getOrThrow<number>('APP_PORT');
const host = config.getOrThrow<string>('APP_HOST');
await app.listen(port, host);
}
await bootstrap();
+37
View File
@@ -0,0 +1,37 @@
import { ConfigService } from '@nestjs/config';
import { describe, expect, it, vi } from 'vitest';
import { MetricsService } from '../../metrics/metrics.service.js';
import { MessagesCacheService } from './messages-cache.service.js';
describe('MessagesCacheService metrics', () => {
it('records a miss and a hit for a protected page fill', async () => {
const metrics = new MetricsService();
const page = { items: [], next_cursor: null };
const redis = {
get: vi
.fn()
.mockResolvedValueOnce(null)
.mockResolvedValueOnce(null)
.mockResolvedValue(JSON.stringify(page)),
setNxPx: vi.fn().mockResolvedValue(true),
set: vi.fn().mockResolvedValue('OK'),
unlock: vi.fn().mockResolvedValue(1),
};
const config = new ConfigService({
CACHE_MODE: 'protected',
CACHE_LOCK_TTL_MS: 1000,
CACHE_TTL_SECONDS: 30,
});
const service = new MessagesCacheService(
redis as never,
config,
metrics,
);
await service.getOrLoad('chat', 1n, undefined, 50, async () => page);
await service.getOrLoad('chat', 1n, undefined, 50, async () => page);
expect(metrics.snapshot().counters).toMatchObject({
cache_miss: 1,
cache_hit: 1,
});
});
});
+11
View File
@@ -0,0 +1,11 @@
import { Module } from '@nestjs/common';
import { MessagesCacheService } from './messages-cache.service.js';
import { MetricsModule } from '../../metrics/metrics.module.js';
import { RedisModule } from '../../redis/redis.module.js';
@Module({
imports: [RedisModule, MetricsModule],
providers: [MessagesCacheService],
exports: [MessagesCacheService],
})
export class MessagesCacheModule {}
+72
View File
@@ -0,0 +1,72 @@
import { ConfigService } from '@nestjs/config';
import { describe, expect, it, vi } from 'vitest';
import type { AppConfig } from '../../config/app-config.schema.js';
import type { RedisClient } from '../../redis/redis.client.js';
import { MessagesCacheService } from './messages-cache.service.js';
import { MetricsService } from '../../metrics/metrics.service.js';
function serviceWithRedis(redis: Partial<RedisClient>): MessagesCacheService {
const config = new ConfigService<AppConfig>({
CACHE_MODE: 'protected',
CACHE_LOCK_TTL_MS: 1000,
CACHE_TTL_SECONDS: 30,
CACHE_MISS_DELAY_MS: 0,
});
return new MessagesCacheService(
redis as RedisClient,
config,
new MetricsService(),
);
}
describe('MessagesCacheService fallback', () => {
it('loads from the authoritative source when Redis read fails', async () => {
const load = vi
.fn()
.mockResolvedValue({ items: [{ id: 'db' }], next_cursor: null });
const service = serviceWithRedis({
get: vi.fn().mockRejectedValue(new Error('redis down')),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual({
items: [{ id: 'db' }],
next_cursor: null,
});
expect(load).toHaveBeenCalledOnce();
});
it('falls back after bounded lock contention', async () => {
const load = vi
.fn()
.mockResolvedValue({ items: [{ id: 'db' }], next_cursor: null });
const service = serviceWithRedis({
get: vi.fn().mockResolvedValue(null),
setNxPx: vi.fn().mockResolvedValue(false),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual({
items: [{ id: 'db' }],
next_cursor: null,
});
expect(load).toHaveBeenCalledOnce();
});
it('returns the authoritative page when cache write fails', async () => {
const page = { items: [{ id: 'db' }], next_cursor: null };
const load = vi.fn().mockResolvedValue(page);
const service = serviceWithRedis({
get: vi.fn().mockResolvedValue(null),
setNxPx: vi.fn().mockResolvedValue(true),
set: vi.fn().mockRejectedValue(new Error('redis down')),
unlock: vi.fn().mockResolvedValue(1),
});
await expect(
service.getOrLoad('chat', 1n, undefined, 50, load),
).resolves.toEqual(page);
});
});
+205
View File
@@ -0,0 +1,205 @@
import { Injectable, Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { setTimeout as delay } from 'node:timers/promises';
import type { AppConfig } from '../../config/app-config.schema.js';
import { RedisClient } from '../../redis/redis.client.js';
import type { Page } from '../../common/http/page.js';
import { MetricsService } from '../../metrics/metrics.service.js';
const LOCK_RETRY_COUNT = 4;
const LOCK_RETRY_DELAY_MS = 25;
export type CachePage = Page<unknown>;
@Injectable()
export class MessagesCacheService {
private readonly logger = new Logger(MessagesCacheService.name);
constructor(
private readonly redis: RedisClient,
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
async getOrLoad(
chatId: string,
version: bigint,
cursor: string | undefined,
limit: number,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
const key = this.cacheKey(chatId, version, cursor, limit);
if (this.config.getOrThrow('CACHE_MODE') === 'naive') {
return this.loadNaively(key, loader);
}
let cached: string | null;
try {
cached = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('read', error, loader);
}
const cachedPage = this.parsePage(cached);
if (cachedPage) {
this.metrics.increment('cache_hit');
return cachedPage;
}
this.metrics.increment('cache_miss');
const lockKey = `lock:${key}`;
const owner = `${process.pid}:${Math.random().toString(36).slice(2)}`;
for (let attempt = 0; attempt < LOCK_RETRY_COUNT; attempt += 1) {
let locked: boolean;
try {
locked = await this.redis.setNxPx(
lockKey,
owner,
this.config.getOrThrow('CACHE_LOCK_TTL_MS'),
);
} catch (error) {
return this.fallbackToDatabase('lock', error, loader);
}
if (locked) return this.fillLocked(key, lockKey, owner, loader);
if (attempt === 0) this.metrics.increment('cache_lock_wait');
try {
const waitedPage = this.parsePage(await this.redis.get(key));
if (waitedPage) {
this.metrics.increment('cache_hit');
return waitedPage;
}
} catch (error) {
return this.fallbackToDatabase('waiting read', error, loader);
}
await delay(LOCK_RETRY_DELAY_MS);
}
// The owner did not publish the page within the bounded wait: serve the
// authoritative result instead of blocking the request further.
this.metrics.increment('cache_lock_timeout');
return loader();
}
private async fillLocked(
key: string,
lockKey: string,
owner: string,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
try {
let secondCheck: string | null;
try {
secondCheck = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('double-check', error, loader);
}
const secondPage = this.parsePage(secondCheck);
if (secondPage) {
this.metrics.increment('cache_hit');
return secondPage;
}
const page = await loader();
try {
await this.redis.set(key, JSON.stringify(page), {
EX: this.config.getOrThrow('CACHE_TTL_SECONDS'),
});
} catch (error) {
// Redis is derived state: the page is still valid for this response,
// but the failure must stay visible in metrics and logs.
this.metrics.increment('cache_write_error');
this.logger.warn(
`Cache fill failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
return page;
} finally {
try {
await this.redis.unlock(lockKey, owner);
} catch (error) {
// The lock has a TTL, so a stale lock expires on its own; a successful
// response must not be replaced by an unlock failure.
this.metrics.increment('cache_unlock_error');
this.logger.warn(
`Cache unlock failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
}
}
private cacheKey(
chatId: string,
version: bigint,
cursor: string | undefined,
limit: number,
): string {
return `messages:${chatId}:v${version.toString()}:c${cursor ?? 'start'}:l${limit}`;
}
private async loadNaively(
key: string,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
let cached: string | null;
try {
cached = await this.redis.get(key);
} catch (error) {
return this.fallbackToDatabase('naive read', error, loader);
}
const cachedPage = this.parsePage(cached);
if (cachedPage) {
this.metrics.increment('cache_hit');
return cachedPage;
}
this.metrics.increment('cache_miss');
const cacheMissDelay = this.config.getOrThrow('CACHE_MISS_DELAY_MS');
if (cacheMissDelay > 0) await delay(cacheMissDelay);
const page = await loader();
try {
await this.redis.set(key, JSON.stringify(page), {
EX: this.config.getOrThrow('CACHE_TTL_SECONDS'),
});
} catch (error) {
this.metrics.increment('cache_write_error');
this.logger.warn(
`Cache fill failed: ${error instanceof Error ? error.message : 'unknown error'}`,
);
}
return page;
}
private async fallbackToDatabase(
stage: string,
error: unknown,
loader: () => Promise<CachePage>,
): Promise<CachePage> {
this.metrics.increment('cache_fallback');
this.logger.warn(
`Cache ${stage} failed, serving PostgreSQL: ${error instanceof Error ? error.message : 'unknown error'}`,
);
return loader();
}
private parsePage(value: string | null): CachePage | undefined {
if (!value) return undefined;
try {
const parsed: unknown = JSON.parse(value);
if (
typeof parsed !== 'object' ||
parsed === null ||
!('items' in parsed) ||
!('next_cursor' in parsed) ||
!Array.isArray(parsed.items) ||
(parsed.next_cursor !== null &&
typeof parsed.next_cursor !== 'string')
)
return undefined;
return { items: parsed.items, next_cursor: parsed.next_cursor };
} catch {
// A malformed entry is treated as a miss and overwritten by the owner fill.
this.metrics.increment('cache_corrupt_entry');
return undefined;
}
}
}
@@ -0,0 +1,8 @@
import { IsString } from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateMessageDto {
@IsString()
@CodePointLength(1, 4000)
text!: string;
}
+7
View File
@@ -0,0 +1,7 @@
export type Message = {
id: string;
chat_id: string;
sender_id: string;
text: string;
created_at: string;
};
+46
View File
@@ -0,0 +1,46 @@
import {
BadRequestException,
Body,
Controller,
DefaultValuePipe,
Get,
Param,
ParseIntPipe,
ParseUUIDPipe,
Post,
Query,
UseGuards,
} from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import type { User } from '../users/user.js';
import { CreateMessageDto } from './dto/create-message.dto.js';
import { MessagesService } from './messages.service.js';
@Controller('api/v1/chats/:chatId/messages')
@UseGuards(CurrentUserGuard)
export class MessagesController {
constructor(private readonly messagesService: MessagesService) {}
@Post()
create(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@Body() body: CreateMessageDto,
@CurrentUser() currentUser: User,
) {
return this.messagesService.create(chatId, body, currentUser);
}
@Get()
list(
@Param('chatId', new ParseUUIDPipe()) chatId: string,
@CurrentUser() currentUser: User,
@Query('limit', new DefaultValuePipe(50), new ParseIntPipe())
limit: number,
@Query('cursor') cursor?: string,
) {
if (limit < 1 || limit > 100)
throw new BadRequestException('limit must be between 1 and 100');
return this.messagesService.list(chatId, currentUser, limit, cursor);
}
}
+24
View File
@@ -0,0 +1,24 @@
import { Module } from '@nestjs/common';
import { DatabaseModule } from '../database/database.module.js';
import { ChatsModule } from '../chats/chats.module.js';
import { MessagesController } from './messages.controller.js';
import { MessagesRepository } from './messages.repository.js';
import { MessagesService } from './messages.service.js';
import { MessagesCacheModule } from './cache/messages-cache.module.js';
import { UsersModule } from '../users/users.module.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
@Module({
imports: [
ChatsModule,
MessagesCacheModule,
DatabaseModule,
UsersModule,
RedisModule,
MetricsModule,
],
controllers: [MessagesController],
providers: [MessagesRepository, MessagesService],
})
export class MessagesModule {}
@@ -0,0 +1,47 @@
import { describe, expect, it, vi } from 'vitest';
import type { Cursor } from '../common/http/cursor.js';
import type { Message } from './message.js';
import { MessagesRepository } from './messages.repository.js';
const message = (id: string, created_at: string): Message => ({
id,
chat_id: 'chat',
sender_id: 'sender',
text: id,
created_at,
});
describe('MessagesRepository', () => {
it('uses named SQL history and a keyset cursor', async () => {
const query = vi.fn().mockResolvedValue({ rows: [], rowCount: 0 });
const repository = new MessagesRepository({
query,
withTransaction: vi.fn(),
} as never);
const cursor: Cursor = {
scope: 'messages:chat',
created_at: '2026-01-01T00:00:01.000Z',
id: '1',
};
await repository.findPage('chat', 10, cursor);
expect(query).toHaveBeenCalledWith(
'messages.history',
expect.stringContaining('(created_at, id) >'),
expect.arrayContaining(['chat', cursor.created_at, cursor.id, 11]),
);
});
it('returns rows in response shape', async () => {
const query = vi
.fn()
.mockResolvedValue({
rows: [message('1', '2026-01-01T00:00:00.000Z')],
rowCount: 1,
});
const repository = new MessagesRepository({ query } as never);
await expect(repository.findPage('chat', 1)).resolves.toEqual({
items: [message('1', '2026-01-01T00:00:00.000Z')],
hasMore: false,
});
});
});
+91
View File
@@ -0,0 +1,91 @@
import {
Injectable,
NotFoundException,
} from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { DatabaseClient } from '../database/database.client.js';
import type { Cursor } from '../common/http/cursor.js';
import type { Message } from './message.js';
type MessageRow = {
id: string;
chat_id: string;
sender_id: string;
text: string;
created_at: Date | string;
};
function toMessage(row: MessageRow): Message {
return {
id: row.id,
chat_id: row.chat_id,
sender_id: row.sender_id,
text: row.text,
created_at: new Date(row.created_at).toISOString(),
};
}
@Injectable()
export class MessagesRepository {
constructor(private readonly database: DatabaseClient) {}
async create(
chatId: string,
senderId: string,
text: string,
): Promise<Message> {
const id = randomUUID();
return this.database.withTransaction(async (client) => {
const membership = await client.query({
name: 'messages.checkMembership',
text: 'SELECT 1 FROM chat_members WHERE chat_id = $1 AND user_id = $2',
values: [chatId, senderId],
});
if (!membership.rowCount) throw new NotFoundException();
const result = await client.query<MessageRow>({
name: 'messages.insert',
text: 'INSERT INTO messages (id, chat_id, sender_id, text) VALUES ($1, $2, $3, $4) RETURNING id, chat_id, sender_id, text, created_at',
values: [id, chatId, senderId, text],
});
await client.query({
name: 'messages.incrementVersion',
text: 'UPDATE chats SET message_version = message_version + 1 WHERE id = $1',
values: [chatId],
});
return toMessage(result.rows[0]);
});
}
async getVersion(chatId: string, userId: string): Promise<bigint> {
const result = await this.database.query<{ message_version: string }>(
'messages.version',
'SELECT c.message_version FROM chats c WHERE c.id = $1 AND EXISTS (SELECT 1 FROM chat_members WHERE chat_id = c.id AND user_id = $2)',
[chatId, userId],
);
if (!result.rows[0]) throw new NotFoundException();
return BigInt(result.rows[0].message_version);
}
async findPage(
chatId: string,
limit: number,
cursor?: Cursor,
): Promise<{ items: Message[]; hasMore: boolean }> {
const values: unknown[] = [chatId];
let predicate = '';
if (cursor) {
values.push(cursor.created_at, cursor.id);
predicate = 'AND (created_at, id) > ($2::timestamptz, $3::uuid)';
}
values.push(limit + 1);
const result = await this.database.query<MessageRow>(
'messages.history',
`SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE chat_id = $1 ${predicate} ORDER BY created_at, id LIMIT $${values.length}`,
values,
);
return {
items: result.rows.slice(0, limit).map(toMessage),
hasMore: result.rows.length > limit,
};
}
}
+76
View File
@@ -0,0 +1,76 @@
import { BadRequestException, Injectable } from '@nestjs/common';
import { decodeCursor, encodeCursor } from '../common/http/cursor.js';
import type { Page } from '../common/http/page.js';
import type { User } from '../users/user.js';
import { ChatsService } from '../chats/chats.service.js';
import type { CreateMessageDto } from './dto/create-message.dto.js';
import type { Message } from './message.js';
import { MessagesRepository } from './messages.repository.js';
import { MessagesCacheService } from './cache/messages-cache.service.js';
@Injectable()
export class MessagesService {
constructor(
private readonly messagesRepository: MessagesRepository,
private readonly chatsService: ChatsService,
private readonly cache: MessagesCacheService,
) {}
async create(
chatId: string,
input: CreateMessageDto,
currentUser: User,
): Promise<Message> {
await this.chatsService.getForUser(chatId, currentUser);
if ([...input.text].every((character) => /\s/u.test(character)))
throw new BadRequestException('Message text cannot be blank');
return this.messagesRepository.create(
chatId,
currentUser.id,
input.text,
);
}
async list(
chatId: string,
currentUser: User,
limit: number,
cursorValue?: string,
): Promise<Page<Message>> {
await this.chatsService.getForUser(chatId, currentUser);
const scope = `messages:${chatId}`;
const cursor = cursorValue
? decodeCursor(cursorValue, scope)
: undefined;
const version = await this.messagesRepository.getVersion(
chatId,
currentUser.id,
);
const page = await this.cache.getOrLoad(
chatId,
version,
cursorValue,
limit,
async () => {
const loaded = await this.messagesRepository.findPage(
chatId,
limit,
cursor,
);
const lastLoaded = loaded.items.at(-1);
return {
items: loaded.items,
next_cursor:
loaded.hasMore && lastLoaded
? encodeCursor({
scope,
created_at: lastLoaded.created_at,
id: lastLoaded.id,
})
: null,
};
},
);
return page as Page<Message>;
}
}
+43
View File
@@ -0,0 +1,43 @@
import {
Controller,
Get,
Headers,
HttpCode,
HttpStatus,
Post,
UnauthorizedException,
} from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import type { AppConfig } from '../config/app-config.schema.js';
import { MetricsService } from './metrics.service.js';
@Controller('internal')
export class MetricsController {
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {}
@Get('metrics')
get(@Headers('authorization') authorization?: string) {
this.requireToken(authorization);
return this.metrics.snapshot();
}
@Post('metrics/reset')
@HttpCode(HttpStatus.OK)
reset(@Headers('authorization') authorization?: string): { status: 'ok' } {
this.requireToken(authorization);
this.metrics.reset();
return { status: 'ok' };
}
private requireToken(authorization?: string): void {
const token = this.config.get<string>('METRICS_TOKEN');
if (!token || authorization !== `Bearer ${token}`)
throw new UnauthorizedException({
message: 'Unauthorized',
challenge: 'Bearer realm="metrics"',
});
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsController } from './metrics.controller.js';
import { MetricsService } from './metrics.service.js';
@Module({
controllers: [MetricsController],
providers: [MetricsService],
exports: [MetricsService],
})
export class MetricsModule {}
+62
View File
@@ -0,0 +1,62 @@
import { describe, expect, it } from 'vitest';
import { MetricsService } from './metrics.service.js';
describe('MetricsService', () => {
it('computes nearest-rank percentiles from observed latencies', () => {
const metrics = new MetricsService();
metrics.increment('cache_hit');
metrics.increment('cache_hit');
metrics.observeLatency(30);
metrics.observeLatency(10);
metrics.observeLatency(20);
expect(metrics.snapshot()).toEqual({
counters: { cache_hit: 2 },
latency_ms: {
count: 3,
sample_count: 3,
p50: 20,
p95: 30,
p99: 30,
max: 30,
},
});
});
it('keeps snapshots isolated from callers and later observations', () => {
const metrics = new MetricsService();
metrics.increment('cache_hit');
const snapshot = metrics.snapshot();
snapshot.counters.cache_hit = 99;
metrics.increment('cache_hit');
expect(metrics.snapshot().counters.cache_hit).toBe(2);
expect(snapshot.latency_ms.count).toBe(0);
});
it('bounds retained samples but keeps cumulative count and maximum', () => {
const metrics = new MetricsService();
metrics.observeLatency(9000);
for (let index = 0; index < 4096; index += 1)
metrics.observeLatency(10);
expect(metrics.snapshot().latency_ms).toEqual({
count: 4097,
sample_count: 4096,
p50: 10,
p95: 10,
p99: 10,
max: 9000,
});
});
it('ignores invalid latency observations', () => {
const metrics = new MetricsService();
for (const value of [-1, NaN, Infinity]) metrics.observeLatency(value);
expect(metrics.snapshot().latency_ms).toEqual({
count: 0,
sample_count: 0,
p50: 0,
p95: 0,
p99: 0,
max: 0,
});
});
});
+69
View File
@@ -0,0 +1,69 @@
import { Injectable } from '@nestjs/common';
const LATENCY_SAMPLE_CAPACITY = 4096;
type LatencySnapshot = {
count: number;
sample_count: number;
p50: number;
p95: number;
p99: number;
max: number;
};
@Injectable()
export class MetricsService {
private readonly counters: Record<string, number> = {};
private readonly latencies: number[] = [];
private latencyCount = 0;
private maximumLatency = 0;
private nextSample = 0;
increment(name: string): void {
this.counters[name] = (this.counters[name] ?? 0) + 1;
}
observeLatency(milliseconds: number): void {
if (!Number.isFinite(milliseconds) || milliseconds < 0) return;
this.latencyCount += 1;
this.maximumLatency = Math.max(this.maximumLatency, milliseconds);
this.latencies[this.nextSample] = milliseconds;
this.nextSample = (this.nextSample + 1) % LATENCY_SAMPLE_CAPACITY;
}
snapshot(): {
counters: Record<string, number>;
latency_ms: LatencySnapshot;
} {
const sorted = [...this.latencies].sort((left, right) => left - right);
return {
counters: { ...this.counters },
latency_ms: {
count: this.latencyCount,
sample_count: sorted.length,
p50: this.percentile(sorted, 0.5),
p95: this.percentile(sorted, 0.95),
p99: this.percentile(sorted, 0.99),
max: this.maximumLatency,
},
};
}
reset(): void {
for (const name of Object.keys(this.counters))
delete this.counters[name];
this.latencies.length = 0;
this.latencyCount = 0;
this.maximumLatency = 0;
this.nextSample = 0;
}
private percentile(sorted: number[], percentile: number): number {
if (sorted.length === 0) return 0;
const index = Math.min(
sorted.length - 1,
Math.ceil(sorted.length * percentile) - 1,
);
return sorted[index];
}
}
+134
View File
@@ -0,0 +1,134 @@
import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { createClient, type RedisClientType } from 'redis';
import type { AppConfig } from '../config/app-config.schema.js';
import { MetricsService } from '../metrics/metrics.service.js';
const UNLOCK_SCRIPT =
'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end';
type Client = RedisClientType;
@Injectable()
export class RedisClient implements OnModuleInit, OnModuleDestroy {
readonly client: Client;
private readonly logger = new Logger(RedisClient.name);
constructor(
private readonly config: ConfigService<AppConfig>,
private readonly metrics: MetricsService,
) {
this.client = createClient({
url: this.config.getOrThrow('REDIS_URL'),
disableOfflineQueue: true,
socket: {
reconnectStrategy: (attempt) =>
Math.min(1000 + attempt * 250, 5000),
connectTimeout: 5000,
},
}) as Client;
// Reconnect failures must be visible; the readiness probe pings Redis.
this.client.on('error', (error: Error) => {
this.metrics.increment('redis.error');
this.logger.warn(`Redis error: ${error.message}`);
});
}
async onModuleInit(): Promise<void> {
await this.client.connect();
}
async onModuleDestroy(): Promise<void> {
if (this.client.isOpen) await this.client.quit();
}
async health(): Promise<void> {
this.metrics.increment('redis.ping');
await this.client.ping();
}
async get(key: string): Promise<string | null> {
this.metrics.increment('redis.get');
return this.client.get(key);
}
async set(
key: string,
value: string,
options?: { EX?: number; PX?: number; NX?: boolean },
): Promise<string | null> {
this.metrics.increment('redis.set');
return this.client.set(key, value, options);
}
async setNxEx(
key: string,
value: string,
seconds: number,
): Promise<boolean> {
this.metrics.increment('redis.set');
return (
(await this.client.set(key, value, { NX: true, EX: seconds })) ===
'OK'
);
}
async setNxPx(
key: string,
value: string,
milliseconds: number,
): Promise<boolean> {
this.metrics.increment('redis.set');
return (
(await this.client.set(key, value, {
NX: true,
PX: milliseconds,
})) === 'OK'
);
}
async del(key: string): Promise<number> {
this.metrics.increment('redis.del');
return this.client.del(key);
}
async incr(key: string): Promise<number> {
this.metrics.increment('redis.incr');
return this.client.incr(key);
}
async expire(key: string, seconds: number): Promise<boolean> {
this.metrics.increment('redis.expire');
return (await this.client.expire(key, seconds)) === 1;
}
async scan(
cursor: number,
pattern?: string,
count = 100,
): Promise<{ cursor: number; keys: string[] }> {
this.metrics.increment('redis.scan');
const result = await this.client.scan(String(cursor), {
MATCH: pattern,
COUNT: count,
});
return { cursor: Number(result.cursor), keys: result.keys };
}
async unlock(key: string, owner: string): Promise<number> {
this.metrics.increment('redis.unlock');
return Number(
await this.client.eval(UNLOCK_SCRIPT, {
keys: [key],
arguments: [owner],
}),
);
}
pipeline(commands: Array<[string, ...string[]]>): Promise<unknown[]> {
this.metrics.increment('redis.pipeline');
const multi = this.client.multi();
for (const [command, ...args] of commands)
multi.addCommand([command, ...args]);
return multi.exec();
}
}
+10
View File
@@ -0,0 +1,10 @@
import { Module } from '@nestjs/common';
import { MetricsModule } from '../metrics/metrics.module.js';
import { RedisClient } from './redis.client.js';
@Module({
imports: [MetricsModule],
providers: [RedisClient],
exports: [RedisClient],
})
export class RedisModule {}
+7
View File
@@ -0,0 +1,7 @@
import { User } from './users/user.ts';
declare module 'fastify' {
interface FastifyRequest {
currentUser?: User;
}
}
+22
View File
@@ -0,0 +1,22 @@
import { IsString, Matches } from 'class-validator';
import { CodePointLength } from '../../common/validation/code-point-length.js';
export class CreateUserDTO {
@IsString()
@Matches(/^[a-z0-9_]{3,32}$/)
username!: string;
@IsString()
@CodePointLength(1, 100)
@Matches(/\S/u, {
message: 'display_name must contain a non-whitespace character',
})
display_name!: string;
@IsString()
@CodePointLength(12, 128)
@Matches(/\S/u, {
message: 'password must contain a non-whitespace character',
})
password!: string;
}
+6
View File
@@ -0,0 +1,6 @@
export type User = {
id: string;
username: string;
display_name: string;
created_at: string;
};
+22
View File
@@ -0,0 +1,22 @@
import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
import { CurrentUser } from '../common/auth/current-user.decorator.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import type { User } from './user.js';
import { CreateUserDTO } from './dto/create-user.dto.js';
import { UsersService } from './users.service.js';
@Controller('api/v1/users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Post()
create(@Body() body: CreateUserDTO) {
return this.usersService.create(body);
}
@Get('/me')
@UseGuards(CurrentUserGuard)
getMe(@CurrentUser() currentUser: User) {
return currentUser;
}
}
+16
View File
@@ -0,0 +1,16 @@
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller.js';
import { UsersRepository } from './users.repository.js';
import { UsersService } from './users.service.js';
import { CurrentUserGuard } from '../common/auth/current-user.guard.js';
import { RedisModule } from '../redis/redis.module.js';
import { MetricsModule } from '../metrics/metrics.module.js';
import { DatabaseModule } from '../database/database.module.js';
@Module({
imports: [DatabaseModule, RedisModule, MetricsModule],
controllers: [UsersController],
providers: [UsersRepository, UsersService, CurrentUserGuard],
exports: [UsersService, CurrentUserGuard, RedisModule, MetricsModule],
})
export class UsersModule {}
+71
View File
@@ -0,0 +1,71 @@
import { ConflictException, Injectable } from '@nestjs/common';
import { DatabaseClient } from '../database/database.client.js';
import type { User } from './user.js';
type UserRow = {
id: string;
username: string;
display_name: string;
password_hash: string;
created_at: Date | string;
};
function toUser(row: UserRow): User {
return {
id: row.id,
username: row.username,
display_name: row.display_name,
created_at: new Date(row.created_at).toISOString(),
};
}
@Injectable()
export class UsersRepository {
constructor(private readonly database: DatabaseClient) {}
async findById(id: string): Promise<User | undefined> {
const result = await this.database.query<UserRow>(
'users.findById',
'SELECT id, username, display_name, password_hash, created_at FROM users WHERE id = $1',
[id],
);
const row = result.rows[0];
return row ? toUser(row) : undefined;
}
async findByUsername(
username: string,
): Promise<(User & { password_hash: string }) | undefined> {
const result = await this.database.query<UserRow>(
'users.findByUsername',
'SELECT id, username, display_name, password_hash, created_at FROM users WHERE username = $1',
[username],
);
const row = result.rows[0];
return row
? { ...toUser(row), password_hash: row.password_hash }
: undefined;
}
async create(user: {
id: string;
username: string;
display_name: string;
password_hash: string;
}): Promise<User> {
try {
const result = await this.database.query<UserRow>(
'users.insert',
`INSERT INTO users (id, username, display_name, password_hash)
VALUES ($1, $2, $3, $4)
RETURNING id, username, display_name, password_hash, created_at`,
[user.id, user.username, user.display_name, user.password_hash],
);
return toUser(result.rows[0]);
} catch (error) {
if ((error as { code?: string }).code === '23505')
throw new ConflictException('Username already exists');
throw error;
}
}
}
+31
View File
@@ -0,0 +1,31 @@
import { Injectable } from '@nestjs/common';
import argon2 from 'argon2';
import { randomUUID } from 'node:crypto';
import { CreateUserDTO } from './dto/create-user.dto.js';
import { User } from './user.js';
import { UsersRepository } from './users.repository.js';
@Injectable()
export class UsersService {
constructor(private readonly usersRepository: UsersRepository) {}
async create(input: CreateUserDTO): Promise<User> {
const passwordHash = await argon2.hash(input.password, {
type: argon2.argon2id,
});
return this.usersRepository.create({
id: randomUUID(),
username: input.username,
display_name: input.display_name,
password_hash: passwordHash,
});
}
findById(id: string): Promise<User | undefined> {
return this.usersRepository.findById(id);
}
findByUsername(username: string) {
return this.usersRepository.findByUsername(username);
}
}
+525
View File
@@ -0,0 +1,525 @@
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { Pool } from 'pg';
import { createClient } from 'redis';
import type { SessionResponse } from '../src/auth/auth.service.js';
import type { Chat } from '../src/chats/chat.js';
import type { ApiErrorBody } from '../src/common/errors/api-error.js';
import type { Page } from '../src/common/http/page.js';
import type { Message } from '../src/messages/message.js';
import type { User } from '../src/users/user.js';
// The suite is black-box: run it against the compiled application process.
// Vitest sets process.env.BASE_URL itself (Vite base), so the API URL uses its own name.
const baseUrl = (process.env.API_BASE_URL ?? 'http://localhost:8080').replace(
/\/+$/u,
'',
);
const basicChallenge = 'Basic realm="messenger", charset="UTF-8"';
const bearerChallenge = 'Bearer realm="messenger"';
const password = 'integration:пароль🔐';
const runId = randomUUID().replaceAll('-', '').slice(0, 12);
const usernames: string[] = [];
const tokens: string[] = [];
let sequence = 0;
let database: Pool;
let redis: ReturnType<typeof createClient>;
type Actor = { user: User; password: string; token: string };
type HttpResult<T> = { body: T; response: Response };
async function http<T = unknown>(
path: string,
init: RequestInit = {},
): Promise<HttpResult<T>> {
const response = await fetch(`${baseUrl}${path}`, init);
const text = await response.text();
let body: unknown = undefined;
if (text) {
try {
body = JSON.parse(text);
} catch {
body = text;
}
}
return { body: body as T, response };
}
function json(
body: unknown,
headers: Record<string, string> = {},
): RequestInit {
return {
method: 'POST',
headers: { 'content-type': 'application/json', ...headers },
body: JSON.stringify(body),
};
}
function basic(username: string, secret: string): string {
return `Basic ${Buffer.from(`${username}:${secret}`, 'utf8').toString('base64')}`;
}
function bearer(token: string): Record<string, string> {
return { authorization: `Bearer ${token}` };
}
async function register(
displayName = 'Интеграционный пользователь',
secret = password,
): Promise<User> {
const username = `e2e_${runId}_${sequence++}`.slice(0, 32);
usernames.push(username);
const result = await http<User>(
'/api/v1/users',
json({ username, display_name: displayName, password: secret }),
);
expect(result.response.status).toBe(201);
return result.body;
}
async function login(user: User, secret = password): Promise<SessionResponse> {
const result = await http<SessionResponse>('/api/v1/auth/sessions', {
method: 'POST',
headers: { authorization: basic(user.username, secret) },
});
expect(result.response.status).toBe(201);
tokens.push(result.body.token);
return result.body;
}
async function actor(displayName?: string): Promise<Actor> {
const user = await register(displayName);
const session = await login(user);
return { user, password, token: session.token };
}
function expectError(
result: HttpResult<ApiErrorBody>,
status: number,
code: string,
): void {
expect(result.response.status).toBe(status);
expect(result.body.error.code).toBe(code);
expect(result.body.error.request_id).toBe(
result.response.headers.get('x-request-id'),
);
}
describe('HTTP integration contract', () => {
beforeAll(async () => {
database = new Pool({
connectionString: process.env.DATABASE_URL,
connectionTimeoutMillis: 5000,
});
redis = createClient({
url: process.env.REDIS_URL,
socket: { reconnectStrategy: false },
});
redis.on('error', () => {});
await redis.connect();
});
afterAll(async () => {
if (usernames.length) {
await database.query('BEGIN');
try {
await database.query(
`DELETE FROM messages WHERE sender_id IN (SELECT id FROM users WHERE username = ANY($1::text[]))`,
[usernames],
);
await database.query(
`DELETE FROM chats WHERE id IN (SELECT chat_id FROM chat_members WHERE user_id IN (SELECT id FROM users WHERE username = ANY($1::text[])))`,
[usernames],
);
await database.query(
'DELETE FROM users WHERE username = ANY($1::text[])',
[usernames],
);
await database.query('COMMIT');
} catch (error) {
await database.query('ROLLBACK');
throw error;
}
}
if (redis.isOpen) redis.destroy();
await database.end();
});
it('serves liveness and requires real session authentication', async () => {
const live = await http<{ status: string }>('/health/live');
expect(live.response.status).toBe(200);
expect(live.body).toEqual({ status: 'ok' });
const denied = await http<ApiErrorBody>('/api/v1/users/me');
expectError(denied, 401, 'unauthorized');
expect(denied.response.headers.get('www-authenticate')).toBe(
bearerChallenge,
);
});
it('measures string lengths in Unicode code points', async () => {
const emoji = '🔐';
const username = (suffix: string) =>
`e2e_${runId}_${suffix}`.slice(0, 32);
const rejected = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_short'),
display_name: 'Code points',
password: emoji.repeat(11),
}),
);
expectError(rejected, 400, 'invalid_request');
const tooLongPassword = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_long'),
display_name: 'Code points',
password: emoji.repeat(129),
}),
);
expectError(tooLongPassword, 400, 'invalid_request');
const tooLongName = await http<ApiErrorBody>(
'/api/v1/users',
json({
username: username('cp_name'),
display_name: emoji.repeat(101),
password,
}),
);
expectError(tooLongName, 400, 'invalid_request');
const shortUsername = username('cp_ok');
usernames.push(shortUsername);
const boundaryPassword = emoji.repeat(12);
const created = await http<User>(
'/api/v1/users',
json({
username: shortUsername,
display_name: emoji.repeat(100),
password: boundaryPassword,
}),
);
expect(created.response.status).toBe(201);
expect([...created.body.display_name].length).toBe(100);
// The stored password keeps all 12 code points: authentication works.
const session = await http<SessionResponse>('/api/v1/auth/sessions', {
method: 'POST',
headers: {
authorization: basic(shortUsername, boundaryPassword),
},
});
expect(session.response.status).toBe(201);
tokens.push(session.body.token);
const longTitleRejected = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{ title: emoji.repeat(101), member_ids: [created.body.id] },
bearer(session.body.token),
),
);
expectError(longTitleRejected, 400, 'invalid_request');
const longTitle = await http<Chat>(
'/api/v1/chats',
json(
{ title: emoji.repeat(100), member_ids: [created.body.id] },
bearer(session.body.token),
),
);
expect(longTitle.response.status).toBe(201);
const tooLongText = await http<ApiErrorBody>(
`/api/v1/chats/${longTitle.body.id}/messages`,
json({ text: emoji.repeat(4001) }, bearer(session.body.token)),
);
expectError(tooLongText, 400, 'invalid_request');
const boundaryText = await http<Message>(
`/api/v1/chats/${longTitle.body.id}/messages`,
json({ text: emoji.repeat(4000) }, bearer(session.body.token)),
);
expect(boundaryText.response.status).toBe(201);
expect([...boundaryText.body.text].length).toBe(4000);
});
it('rejects whitespace-only and too-short credentials', async () => {
const username = `e2e_${runId}_${sequence++}`.slice(0, 32);
usernames.push(username);
const cases = [
{ password: ' '.repeat(12), display_name: 'Пользователь' },
{ password: '\t'.repeat(16), display_name: 'Пользователь' },
{ password: 'short-pass', display_name: 'Пользователь' },
{ password, display_name: ' ' },
];
for (const body of cases) {
const result = await http<ApiErrorBody>(
'/api/v1/users',
json({ username, ...body }),
);
expectError(result, 400, 'invalid_request');
}
const accepted = await http<User>(
'/api/v1/users',
json({ username, display_name: 'Пользователь', password }),
);
expect(accepted.response.status).toBe(201);
});
it('registers, logs in with Unicode/colon password, and challenges malformed Basic', async () => {
const user = await register();
const session = await login(user);
expect(session.user.id).toBe(user.id);
expect(session.token_type).toBe('Bearer');
const me = await http<User>('/api/v1/users/me', {
headers: bearer(session.token),
});
expect(me.response.status).toBe(200);
expect(me.body.id).toBe(user.id);
for (const authorization of [
'Basic !!!',
'Basic YWJj',
'Bearer nope',
]) {
const result = await http<ApiErrorBody>('/api/v1/auth/sessions', {
method: 'POST',
headers: { authorization },
});
expectError(result, 401, 'unauthorized');
expect(result.response.headers.get('www-authenticate')).toBe(
basicChallenge,
);
}
const bodyResult = await http<ApiErrorBody>('/api/v1/auth/sessions', {
...json({ unexpected: true }),
headers: { authorization: basic(user.username, password) },
});
expectError(bodyResult, 400, 'invalid_request');
});
it('returns conflict for concurrent duplicate registration', async () => {
const username = `e2e_${runId}_race`.slice(0, 32);
usernames.push(username);
const results = await Promise.all([
http<User>(
'/api/v1/users',
json({ username, display_name: 'Race A', password }),
),
http<User>(
'/api/v1/users',
json({ username, display_name: 'Race B', password }),
),
]);
expect(
results.filter((item) => item.response.status === 201),
'duplicate registration must create exactly one user',
).toHaveLength(1);
expect(
results.filter((item) => item.response.status === 409),
'loser of the race must receive 409, not 500',
).toHaveLength(1);
// The database unique index is the race-proof guard, so verify its effect.
const persisted = await database.query<{ count: string }>(
'SELECT count(*)::text AS count FROM users WHERE username = $1',
[username],
);
expect(persisted.rows[0]?.count).toBe('1');
});
it('uses Bearer only, ignores X-User-Id spoofing, and prevents logout replay', async () => {
const alice = await actor('Алиса');
const bob = await actor('Боб');
const spoof = await http<ApiErrorBody>('/api/v1/users/me', {
headers: { ...bearer(alice.token), 'x-user-id': bob.user.id },
});
expect(spoof.response.status).toBe(200);
expect((spoof.body as unknown as User).id).toBe(alice.user.id);
const basicBusiness = await http<ApiErrorBody>('/api/v1/users/me', {
headers: { authorization: basic(alice.user.username, password) },
});
expectError(basicBusiness, 401, 'unauthorized');
expect(basicBusiness.response.headers.get('www-authenticate')).toBe(
bearerChallenge,
);
const logout = await http('/api/v1/auth/sessions/current', {
method: 'DELETE',
headers: bearer(alice.token),
});
expect(logout.response.status).toBe(204);
const replay = await http<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(alice.token),
});
expectError(replay, 401, 'unauthorized');
});
it('rejects unknown and duplicate chat members and hides chats from outsiders', async () => {
const alice = await actor();
const bob = await actor();
const outsider = await actor();
const unknown = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{ title: 'unknown', member_ids: [alice.user.id, randomUUID()] },
bearer(alice.token),
),
);
expectError(unknown, 400, 'invalid_request');
const leaked = await http<ApiErrorBody>(`/api/v1/chats?limit=100`, {
headers: bearer(alice.token),
});
expect(leaked.response.status).toBe(200);
expect(
(leaked.body as unknown as Page<Chat>).items.some(
(item) => item.title === 'unknown',
),
).toBe(false);
const duplicate = await http<ApiErrorBody>(
'/api/v1/chats',
json(
{
title: 'duplicate',
member_ids: [alice.user.id, alice.user.id],
},
bearer(alice.token),
),
);
expectError(duplicate, 400, 'invalid_request');
const created = await http<Chat>(
'/api/v1/chats',
json(
{
title: `chat-${runId}`,
member_ids: [alice.user.id, bob.user.id],
},
bearer(alice.token),
),
);
expect(created.response.status).toBe(201);
const hidden = await http<ApiErrorBody>(
`/api/v1/chats/${created.body.id}`,
{ headers: bearer(outsider.token) },
);
expectError(hidden, 404, 'not_found');
});
it('keeps sender server-owned and makes writes visible to a second session', async () => {
const alice = await actor();
const secondSession = (await login(alice.user)).token;
const chat = await http<Chat>(
'/api/v1/chats',
json(
{ title: `messages-${runId}`, member_ids: [alice.user.id] },
bearer(alice.token),
),
);
expect(chat.response.status).toBe(201);
const blank = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages`,
json(
{ text: ' \n\t', sender_id: randomUUID() },
bearer(alice.token),
),
);
expectError(blank, 400, 'invalid_request');
const spoof = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages`,
json(
{ text: 'hello', sender_id: randomUUID() },
bearer(alice.token),
),
);
expectError(spoof, 400, 'invalid_request');
await http(`/api/v1/chats/${chat.body.id}/messages?limit=50`, {
headers: bearer(secondSession),
});
const sent = await http<Message>(
`/api/v1/chats/${chat.body.id}/messages`,
json({ text: 'hello' }, bearer(alice.token)),
);
expect(sent.response.status).toBe(201);
expect(sent.body.sender_id).toBe(alice.user.id);
const page = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=50`,
{ headers: bearer(secondSession) },
);
expect(page.response.status).toBe(200);
expect(page.body.items.map((item) => item.id)).toContain(sent.body.id);
});
it('validates cursor, limits, malformed JSON, and paginates without repeats', async () => {
const alice = await actor();
const chat = await http<Chat>(
'/api/v1/chats',
json(
{ title: `pages-${runId}`, member_ids: [alice.user.id] },
bearer(alice.token),
),
);
for (const text of ['one', 'two', 'three']) {
const sent = await http(
`/api/v1/chats/${chat.body.id}/messages`,
json({ text }, bearer(alice.token)),
);
expect(sent.response.status).toBe(201);
}
const invalidLimit = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?limit=101`,
{ headers: bearer(alice.token) },
);
expectError(invalidLimit, 400, 'invalid_request');
const invalidCursor = await http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?cursor=not-a-cursor`,
{ headers: bearer(alice.token) },
);
expectError(invalidCursor, 400, 'invalid_request');
const rolledOver = http<ApiErrorBody>(
`/api/v1/chats/${chat.body.id}/messages?cursor=${encodeURIComponent(
Buffer.from(
JSON.stringify({
scope: `messages:${chat.body.id}`,
created_at: '2026-02-31T00:00:00.000Z',
id: randomUUID(),
}),
'utf8',
).toString('base64url'),
)}`,
{ headers: bearer(alice.token) },
);
expectError(await rolledOver, 400, 'invalid_request');
const malformed = await http<ApiErrorBody>('/api/v1/users', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: '{',
});
expectError(malformed, 400, 'invalid_request');
const first = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=2`,
{ headers: bearer(alice.token) },
);
expect(first.body.items).toHaveLength(2);
const second = await http<Page<Message>>(
`/api/v1/chats/${chat.body.id}/messages?limit=2&cursor=${encodeURIComponent(first.body.next_cursor!)}`,
{ headers: bearer(alice.token) },
);
expect(second.body.items).toHaveLength(1);
expect(
new Set(
[...first.body.items, ...second.body.items].map(
(item) => item.id,
),
).size,
).toBe(3);
});
it.skipIf(process.env.SESSION_TTL_SECONDS !== '2')(
'expires sessions with TTL=2',
async () => {
const user = await register();
const session = await login(user);
await sleep(2300);
const expired = await http<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(session.token),
});
expectError(expired, 401, 'unauthorized');
},
);
});
+290
View File
@@ -0,0 +1,290 @@
import { execFile } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import type { SessionResponse } from '../src/auth/auth.service.js';
import type { Chat } from '../src/chats/chat.js';
import type { ApiErrorBody } from '../src/common/errors/api-error.js';
import type { Page } from '../src/common/http/page.js';
import type { Message } from '../src/messages/message.js';
import type { User } from '../src/users/user.js';
// Automated counterpart of the manual Redis/PostgreSQL outage checks: the suite
// stops a dependency of the Compose stand, asserts a bounded 503 (never a 500,
// never a trusted anonymous request, never a leaked driver error) and then
// restarts it to prove recovery without data loss.
//
// It is opt-in because it needs control over the Docker Compose project:
// make test-dependencies
// cd app && E2E_DEPENDENCY_FAULTS=1 npm run test:dependencies
const enabled = process.env.E2E_DEPENDENCY_FAULTS === '1';
const baseUrl = (process.env.API_BASE_URL ?? 'http://localhost:8080').replace(
/\/+$/u,
'',
);
const composeDir =
process.env.E2E_COMPOSE_DIR ??
fileURLToPath(new URL('../..', import.meta.url));
const composeEnvFile = process.env.E2E_COMPOSE_ENV_FILE ?? '.env';
const redisService = process.env.E2E_REDIS_SERVICE ?? 'redis';
const postgresService = process.env.E2E_POSTGRES_SERVICE ?? 'postgres';
const password = 'outage-check:пароль🔐';
const runId = randomUUID().replaceAll('-', '').slice(0, 12);
// A request that reaches a stopped database waits for the pool connection
// timeout, so every outage step costs up to DATABASE_CONNECTION_TIMEOUT_MS.
const outagedRequestBudgetMs = 180_000;
const execFileAsync = promisify(execFile);
type Result<T> = { body: T; text: string; response: Response };
async function compose(...args: string[]): Promise<void> {
await execFileAsync(
'docker',
['compose', '--env-file', composeEnvFile, ...args],
{ cwd: composeDir, timeout: 120_000 },
);
}
async function request<T = unknown>(
path: string,
init: RequestInit = {},
): Promise<Result<T>> {
const response = await fetch(`${baseUrl}${path}`, init);
const text = await response.text();
return { body: (text ? JSON.parse(text) : undefined) as T, text, response };
}
function json(
body: unknown,
headers: Record<string, string> = {},
): RequestInit {
return {
method: 'POST',
headers: { 'content-type': 'application/json', ...headers },
body: JSON.stringify(body),
};
}
function bearer(token: string): Record<string, string> {
return { authorization: `Bearer ${token}` };
}
function basic(username: string, secret: string): string {
return `Basic ${Buffer.from(`${username}:${secret}`, 'utf8').toString('base64')}`;
}
// The dependencies recover asynchronously, so readiness is polled instead of
// asserted right after docker compose returns.
async function waitForReadiness(
expected: number,
timeoutMs = 90_000,
): Promise<void> {
const deadline = Date.now() + timeoutMs;
let last: number | string = 'no response';
for (;;) {
try {
const probe = await request('/health/ready');
last = probe.response.status;
if (probe.response.status === expected) return;
} catch (error) {
last = error instanceof Error ? error.message : 'request failed';
}
if (Date.now() > deadline)
throw new Error(
`readiness never became ${expected} within ${timeoutMs}ms (last: ${String(last)})`,
);
await sleep(250);
}
}
function expectBoundedOutage(result: Result<ApiErrorBody>): void {
expect(result.response.status).toBe(503);
expect(result.body.error.code).toBe('unavailable');
expect(result.body.error.message).toBe('Service unavailable');
expect(result.body.error.request_id).toBe(
result.response.headers.get('x-request-id'),
);
// A bounded error must not leak driver details, SQL text or a stack trace.
expect(result.text).not.toMatch(
/ECONNREFUSED|ECONNRESET|Connection terminated|pg\.|node_modules|at .*\(.+:\d+:\d+\)/u,
);
}
async function historyOf(
chatId: string,
token: string,
): Promise<Result<Page<Message>>> {
return request<Page<Message>>(`/api/v1/chats/${chatId}/messages?limit=100`, {
headers: bearer(token),
});
}
describe.skipIf(!enabled)('dependency outages', () => {
let user: User;
let token: string;
let chat: Chat;
let message: Message;
beforeAll(async () => {
await compose('up', '-d');
await waitForReadiness(200);
const username = `outage_${runId}`;
const registered = await request<User>(
'/api/v1/users',
json({ username, display_name: 'Отказ зависимости', password }),
);
expect(registered.response.status).toBe(201);
user = registered.body;
const session = await request<SessionResponse>(
'/api/v1/auth/sessions',
{
method: 'POST',
headers: { authorization: basic(username, password) },
},
);
expect(session.response.status).toBe(201);
token = session.body.token;
const created = await request<Chat>(
'/api/v1/chats',
json(
{ title: `outage-${runId}`, member_ids: [user.id] },
bearer(token),
),
);
expect(created.response.status).toBe(201);
chat = created.body;
const sent = await request<Message>(
`/api/v1/chats/${chat.id}/messages`,
json({ text: 'Сообщение до отказа' }, bearer(token)),
);
expect(sent.response.status).toBe(201);
message = sent.body;
}, outagedRequestBudgetMs);
afterAll(async () => {
// Always restore the stand, even when an assertion failed mid-outage.
await compose('start', redisService);
await compose('start', postgresService);
await waitForReadiness(200);
}, outagedRequestBudgetMs);
it(
'serves bounded 503 for the Redis outage and recovers the session',
async () => {
await compose('stop', redisService);
const live = await request('/health/live');
expect(live.response.status).toBe(200);
await waitForReadiness(503);
expectBoundedOutage(await request<ApiErrorBody>('/health/ready'));
expectBoundedOutage(
await request<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(token),
}),
);
expectBoundedOutage(
await request<ApiErrorBody>('/api/v1/auth/sessions', {
method: 'POST',
headers: { authorization: basic(user.username, password) },
}),
);
// A request without a session must stay unauthorized during an outage:
// the outage may not turn an anonymous caller into a trusted one.
const anonymous = await request<ApiErrorBody>('/api/v1/chats', {
headers: { 'x-user-id': user.id },
});
expect(anonymous.response.status).toBe(401);
expect(anonymous.body.error.code).toBe('unauthorized');
await compose('start', redisService);
await waitForReadiness(200);
// Sessions live in Redis with persistence, so the old token still works.
const recovered = await request<User>('/api/v1/users/me', {
headers: bearer(token),
});
expect(recovered.response.status).toBe(200);
expect(recovered.body.id).toBe(user.id);
const history = await historyOf(chat.id, token);
expect(history.response.status).toBe(200);
expect(history.body.items.map((item) => item.id)).toContain(
message.id,
);
},
outagedRequestBudgetMs,
);
it(
'serves bounded 503 for the PostgreSQL outage and keeps confirmed data',
async () => {
await compose('stop', postgresService);
const live = await request('/health/live');
expect(live.response.status).toBe(200);
await waitForReadiness(503);
expectBoundedOutage(await request<ApiErrorBody>('/health/ready'));
// Redis still answers, so these requests reach the database layer.
expectBoundedOutage(
await request<ApiErrorBody>('/api/v1/users/me', {
headers: bearer(token),
}),
);
expectBoundedOutage(
await request<ApiErrorBody>('/api/v1/chats', {
headers: bearer(token),
}),
);
expectBoundedOutage(
await request<ApiErrorBody>(
`/api/v1/chats/${chat.id}/messages?limit=100`,
{ headers: bearer(token) },
),
);
expectBoundedOutage(
await request<ApiErrorBody>(
'/api/v1/users',
json({
username: `outage_${runId}_late`,
display_name: 'Отказ зависимости',
password,
}),
),
);
await compose('start', postgresService);
await waitForReadiness(200);
const recovered = await request<User>('/api/v1/users/me', {
headers: bearer(token),
});
expect(recovered.response.status).toBe(200);
expect(recovered.body.id).toBe(user.id);
const history = await historyOf(chat.id, token);
expect(history.response.status).toBe(200);
expect(history.body.items.map((item) => item.id)).toContain(
message.id,
);
const sent = await request<Message>(
`/api/v1/chats/${chat.id}/messages`,
json({ text: 'Сообщение после отказа' }, bearer(token)),
);
expect(sent.response.status).toBe(201);
},
outagedRequestBudgetMs,
);
});
+8
View File
@@ -0,0 +1,8 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": "./src"
},
"include": ["src"],
"exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}
+22
View File
@@ -0,0 +1,22 @@
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"resolvePackageJsonExports": true,
"esModuleInterop": true,
"isolatedModules": true,
"declaration": true,
"removeComments": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"allowSyntheticDefaultImports": true,
"target": "ES2023",
"sourceMap": true,
"outDir": "./dist",
"incremental": true,
"skipLibCheck": true,
"strict": true,
"strictPropertyInitialization": false,
"types": ["vitest/globals", "node"]
}
}
+14
View File
@@ -0,0 +1,14 @@
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
globals: true,
root: './',
include: ['test/*.e2e-spec.ts'],
testTimeout: 30_000,
hookTimeout: 30_000,
sequence: { concurrent: false },
},
});
+13
View File
@@ -0,0 +1,13 @@
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
// Resolves the path aliases declared in tsconfig.json, including the ones
// added by `nest g library`.
plugins: [tsconfigPaths()],
test: {
globals: true,
root: './',
include: ['**/*.spec.ts'],
},
});
+99
View File
@@ -0,0 +1,99 @@
# Коллекция Bruno: ручки messenger (lab 2)
Ручной клиент для API: регистрация, Basic-вход, Bearer-доступ, чаты, сообщения
с пагинацией, метрики и негативные проверки. Формат — стандартный Bruno (`.bru`).
Связанные документы: [`../REPORT.md`](../REPORT.md) (архитектура и решения),
[`../evidence/README.md`](../evidence/README.md) (индекс доказательств),
[`../.github/pull_request_template.md`](../.github/pull_request_template.md) (сдача).
## Как открыть и запустить
```sh
# GUI: Collection -> Open -> выбрать папку bruno/ этого репозитория.
# baseUrl уже подставлен на уровне коллекции (collection.bru), вводить его
# в каждой ручке не нужно. Для реального METRICS_TOKEN выберите окружение
# `local` в правом верхнем углу и поправьте metricsToken.
# CLI (требуется @usebruno/cli; запускать из корня коллекции):
npm install -g @usebruno/cli
cd bruno
bru run -r --env-var metricsToken=$(grep '^METRICS_TOKEN=' ../.env | cut -d= -f2)
```
Проверено на `bru` 4.2.1 против локального стенда: 29 запросов, 58 проверок,
все зелёные (см. `../evidence/level3-4-verification.md` §12).
Стенд должен быть поднят: `docker compose --env-file .env up -d --build`,
готовность — `curl -fsS http://localhost:8080/health/ready`.
## Переменные и приоритет
| Источник | Что задаёт | Приоритет |
|---|---|---|
| `collection.bru` → `script:pre-request` | `baseUrl=http://localhost:8080`, `password=demo-password-123`, `metricsToken=change-me-metrics-token` | самый низкий: подставляется только если переменная нигде не задана |
| `environments/local.bru` (`--env local`) | те же три переменные для конкретного стенда | выше дефолтов |
| `--env-var name=value` (CLI) / runtime-переменные (GUI) | разовое значение | самый высокий |
Поэтому адрес API больше не нужно вводить в каждой ручке: он берётся из
настроек коллекции. Если `metricsToken` оставить заглушкой, два запроса к
`/internal/*` вернут 401 — это ожидаемо и описано в их `docs`; остальные 26
запросов проходят.
## Окружение
`environments/local.bru`:
| Переменная | Значение по умолчанию | Комментарий |
|---|---|---|
| `baseUrl` | `http://localhost:8080` | адрес API |
| `password` | `demo-password-123` | пароль демо-пользователей (12–128 code points) |
| `metricsToken` | `change-me-metrics-token` | возьмите `METRICS_TOKEN` из `.env`, иначе запросы к `/internal/*` вернут 401 |
## Порядок выполнения
Папки обходятся по алфавиту, внутри папки — по `seq`:
```text
auth/ регистрация трёх пользователей и три Basic-сессии, /users/me
chats/ создание чата (два участника), список чатов, чат по id
health/ /health/live и /health/ready
internal/ /internal/metrics и /internal/metrics/reset
messages/ два сообщения, первая страница истории, страница по курсору
negative/ неверный пароль, Basic на бизнес-endpoint, X-User-Id, 404 чужого чата, 400 на limit/cursor,
несуществующую календарную дату курсора и пробельный текст, 409 дубликата
zz-cleanup/ logout и проверка, что отозванный токен даёт 401 (выполняется последним)
```
Коллекция сохраняет переменные между запросами: `suffix`, `username`,
`secondUsername`, `thirdUsername`, `userId`, `secondUserId`, `thirdUserId`,
`token`, `secondToken`, `thirdToken`, `chatId`, `messageId`, `nextCursor`.
Повторный запуск не конфликтует с прошлым прогоном: username генерируется
из случайного суффикса, а дубликат проверяется отдельной негативной ручкой.
## Что проверяет каждая ручка
- `auth/register-user.bru` — 201, ответ без `password`/`password_hash`;
- `auth/create-session*.bru` — 201, `token_type: Bearer`, `expires_at` в UTC, `user` совпадает с зарегистрированным;
- `auth/me.bru` — Bearer-доступ и совпадение владельца;
- `chats/create-chat.bru` — атомарное создание чата с двумя участниками;
- `messages/send-message*.bru` — `sender_id` выведен из сессии, `chat_id` верный;
- `messages/history-*.bru` — `limit` соблюдён, курсор ведёт на следующую страницу и не повторяет элемент;
- `internal/metrics.bru` — счётчики и агрегаты латентности без секретов;
- `negative/*` — коды и challenge-заголовки, отсутствие подмены владельца через `X-User-Id`, 404 вместо 403 для чужого чата, 409 при дубликате username, 400 на невалидные limit/cursor (включая несуществующую дату `2026-02-31`, которая раньше доходила до SQL и давала 500) и пробельный текст.
## Проверка истечения сессии
```sh
SESSION_TTL_SECONDS=2 docker compose --env-file .env up -d api
# в Bruno: auth/create-session.bru -> создать сессию, подождать ~2.5 с
# затем auth/me.bru -> ожидается 401 с Bearer-challenge
docker compose --env-file .env up -d api # вернуть штатный TTL из .env
```
## Границы
Коллекция — удобный ручной клиент, а не замена автоматике: контракт и приёмку
проверяют `make test`, набор из `app/test/app.e2e-spec.ts` и бенчмарк трека 1
(`scripts/track1_cache_benchmark.py`). Секретов в файлах нет: пароль и токен
метрик задаются переменными окружения.
+31
View File
@@ -0,0 +1,31 @@
meta {
name: Create second session (Basic)
type: http
seq: 5
}
post {
url: {{baseUrl}}/api/v1/auth/sessions
body: none
auth: basic
}
auth:basic {
username: {{secondUsername}}
password: {{password}}
}
docs {
Сессия второго участника чата: нужна, чтобы читать историю другой
действующей сессией (read-after-write). Сохраняет secondToken.
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
}
script:post-response {
bru.setVar("secondToken", res.body.token);
}
+31
View File
@@ -0,0 +1,31 @@
meta {
name: Create third session (Basic)
type: http
seq: 6
}
post {
url: {{baseUrl}}/api/v1/auth/sessions
body: none
auth: basic
}
auth:basic {
username: {{thirdUsername}}
password: {{password}}
}
docs {
Сессия постороннего пользователя: используется только в негативных
проверках доступа к чужому чату. Сохраняет thirdToken.
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
}
script:post-response {
bru.setVar("thirdToken", res.body.token);
}
+46
View File
@@ -0,0 +1,46 @@
meta {
name: Create session (Basic)
type: http
seq: 4
}
post {
url: {{baseUrl}}/api/v1/auth/sessions
body: none
auth: basic
}
auth:basic {
username: {{username}}
password: {{password}}
}
docs {
Вход: Authorization: Basic base64(username:password), тело запроса не передаётся.
Пароль кодируется как UTF-8, разделитель — первый символ ":".
Сохраняет token и expiresAt. Неверные credentials дают 401 с
WWW-Authenticate: Basic realm="messenger", charset="UTF-8".
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
test("token_type bearer", function() {
expect(res.body.token_type).to.equal("Bearer");
});
test("expires_at в UTC", function() {
expect(res.body.expires_at).to.match(/Z$/);
});
test("user совпадает с зарегистрированным", function() {
expect(res.body.user.id).to.equal(bru.getVar("userId"));
});
}
script:post-response {
bru.setVar("token", res.body.token);
bru.setVar("expiresAt", res.body.expires_at);
}
+30
View File
@@ -0,0 +1,30 @@
meta {
name: Current user
type: http
seq: 7
}
get {
url: {{baseUrl}}/api/v1/users/me
body: none
auth: none
}
headers {
Authorization: Bearer {{token}}
}
docs {
Бизнес-endpoint требует только Bearer. Basic здесь даёт 401,
а заголовок X-User-Id сам по себе доступа не даёт и не подменяет владельца.
}
tests {
test("status 200", function() {
expect(res.status).to.equal(200);
});
test("это тот же пользователь", function() {
expect(res.body.id).to.equal(bru.getVar("userId"));
});
}
+42
View File
@@ -0,0 +1,42 @@
meta {
name: Register second user
type: http
seq: 2
}
post {
url: {{baseUrl}}/api/v1/users
body: json
auth: none
}
docs {
Второй пользователь: нужен для чата с двумя участниками и проверки,
что чужой чат отдаёт 404. Сохраняет secondUserId и secondUsername,
используя тот же пароль.
}
script:pre-request {
if (!bru.getVar("suffix")) {
bru.setVar("suffix", Math.random().toString(36).slice(2, 10));
}
bru.setVar("secondUsername", `demo2_${bru.getVar("suffix")}`);
}
body:json {
{
"username": "{{secondUsername}}",
"display_name": "Второй участник",
"password": "{{password}}"
}
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
}
script:post-response {
bru.setVar("secondUserId", res.body.id);
}
+41
View File
@@ -0,0 +1,41 @@
meta {
name: Register third user
type: http
seq: 3
}
post {
url: {{baseUrl}}/api/v1/users
body: json
auth: none
}
docs {
Третий пользователь не входит в демо-чат: нужен, чтобы показать,
что чужой чат отдаёт 404, а не раскрывает факт существования.
}
script:pre-request {
if (!bru.getVar("suffix")) {
bru.setVar("suffix", Math.random().toString(36).slice(2, 10));
}
bru.setVar("thirdUsername", `demo3_${bru.getVar("suffix")}`);
}
body:json {
{
"username": "{{thirdUsername}}",
"display_name": "Посторонний",
"password": "{{password}}"
}
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
}
script:post-response {
bru.setVar("thirdUserId", res.body.id);
}
+53
View File
@@ -0,0 +1,53 @@
meta {
name: Register first user
type: http
seq: 1
}
post {
url: {{baseUrl}}/api/v1/users
body: json
auth: none
}
body:json {
{
"username": "{{username}}",
"display_name": "Демо-пользователь",
"password": "{{password}}"
}
}
vars:pre-request {
baseUrl: http://localhost:8080
}
script:pre-request {
if (!bru.getVar("suffix")) {
bru.setVar("suffix", Math.random().toString(36).slice(2, 10));
}
bru.setVar("username", `demo_${bru.getVar("suffix")}`);
}
script:post-response {
bru.setVar("userId", res.body.id);
bru.setVar("displayName", res.body.display_name);
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
test("пароль и хеш не утекли", function() {
expect(res.body).to.not.have.property("password");
expect(res.body).to.not.have.property("password_hash");
});
}
docs {
Регистрация с паролем (12–128 code points).
Username генерируется из случайного суффикса, чтобы повторный запуск коллекции
не упирался в 409. Сохраняет переменные: username, userId, displayName.
Ответ никогда не содержит password или password_hash.
}
+6
View File
@@ -0,0 +1,6 @@
{
"version": "1",
"name": "mtusi-messenger-lab2",
"type": "collection",
"ignore": ["node_modules", ".git"]
}
+46
View File
@@ -0,0 +1,46 @@
meta {
name: Create chat
type: http
seq: 1
}
post {
url: {{baseUrl}}/api/v1/chats
body: json
auth: none
}
headers {
Authorization: Bearer {{token}}
}
body:json {
{
"title": "Демо-чат {{suffix}}",
"member_ids": ["{{userId}}", "{{secondUserId}}"]
}
}
script:post-response {
bru.setVar("chatId", res.body.id);
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
test("оба участника в чате", function() {
expect(res.body.member_ids).to.have.members([
bru.getVar("userId"),
bru.getVar("secondUserId")
]);
});
}
docs {
Составная операция в одной транзакции: проверка участников, вставка чата
и всех chat_members. Текущий пользователь обязан входить в member_ids,
неизвестные и дублирующиеся ID дают 400 без частичных данных.
Сохраняет chatId.
}
+30
View File
@@ -0,0 +1,30 @@
meta {
name: Get chat by id
type: http
seq: 3
}
get {
url: {{baseUrl}}/api/v1/chats/{{chatId}}
body: none
auth: none
}
headers {
Authorization: Bearer {{token}}
}
docs {
Участник получает чат, посторонний — 404 (не 403: существование чужого
объекта не раскрывается).
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("id совпадает", function() {
expect(res.body.id).to.equal(bru.getVar("chatId"));
});
}
+30
View File
@@ -0,0 +1,30 @@
meta {
name: List my chats
type: http
seq: 2
}
get {
url: {{baseUrl}}/api/v1/chats?limit=100
body: none
auth: none
}
headers {
Authorization: Bearer {{token}}
}
docs {
Список только доступных чатов, сортировка по (created_at, id), keyset-cursor.
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("созданный чат виден", function() {
const ids = res.body.items.map(function(item) { return item.id; });
expect(ids).to.include(bru.getVar("chatId"));
});
}
+29
View File
@@ -0,0 +1,29 @@
script:pre-request {
// Дефолты уровня коллекции: baseUrl не нужно вводить в каждой ручке.
// ВАЖНО: bru.getVar читает только runtime-переменные, значения environment
// приходят через bru.getEnvVar — поэтому проверяем оба источника и не
// перекрываем то, что задано окружением.
const defaults = {
baseUrl: "http://localhost:8080",
password: "demo-password-123",
metricsToken: "GsdgewgDSFkoseGSJGpodsgsdppDS"
};
for (const name of Object.keys(defaults)) {
if (!bru.getEnvVar(name) && !bru.getVar(name)) {
bru.setVar(name, defaults[name]);
}
}
}
docs {
# Настройки уровня коллекции.
Скрипт выше подставляет `baseUrl`, `password` и `metricsToken`, только если
они не заданы environment-ом или runtime-переменной. Поэтому в GUI достаточно
открыть коллекцию — вводить адрес в каждой ручке не требуется, а выбранный
environment `local` (environments/local.bru) остаётся приоритетным.
Для реального токена метрик возьмите `METRICS_TOKEN` из `.env` (в GUI — через
environment, в CLI — `--env-var metricsToken=...`). Без него `/internal/*`
вернут 401: дефолт-заглушка намеренно не совпадает с рабочим токеном.
}
+5
View File
@@ -0,0 +1,5 @@
vars {
baseUrl: http://localhost:8080
password: demo-password-123
metricsToken: change-me-metrics-token
}
+26
View File
@@ -0,0 +1,26 @@
meta {
name: Health live
type: http
seq: 1
}
get {
url: {{baseUrl}}/health/live
body: none
auth: none
}
docs {
Liveness процесса. Зависимости не проверяются: если API жив, ответ 200.
}
tests {
test("status 200", function() {
expect(res.status).to.equal(200);
});
test("X-Request-Id присутствует", function() {
expect(res.headers["x-request-id"]).to.be.a("string");
expect(res.headers["x-request-id"].length).to.be.greaterThan(0);
});
}
+26
View File
@@ -0,0 +1,26 @@
meta {
name: Health ready
type: http
seq: 2
}
get {
url: {{baseUrl}}/health/ready
body: none
auth: none
}
docs {
Readiness: 200 только если доступны PostgreSQL и Redis.
При остановленном Redis или PostgreSQL вернётся 503 в общем формате ошибки.
}
tests {
test("status 200", function() {
expect(res.status).to.equal(200);
});
test("status ok", function() {
expect(res.body.status).to.equal("ok");
});
}
+30
View File
@@ -0,0 +1,30 @@
meta {
name: Metrics reset
type: http
seq: 2
}
post {
url: {{baseUrl}}/internal/metrics/reset
body: none
auth: none
}
headers {
Authorization: Bearer {{metricsToken}}
}
docs {
Обнуляет счётчики процесса API (используется бенчмарком трека 1, чтобы
считать дельту по повторности). На PostgreSQL и Redis не влияет.
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("status ok", function() {
expect(res.body.status).to.equal("ok");
});
}
+33
View File
@@ -0,0 +1,33 @@
meta {
name: Metrics snapshot
type: http
seq: 1
}
get {
url: {{baseUrl}}/internal/metrics
body: none
auth: none
}
headers {
Authorization: Bearer {{metricsToken}}
}
docs {
Внутренний диагностический endpoint (не часть публичного контракта).
Требует Authorization: Bearer <METRICS_TOKEN>; без него — 401.
Возвращает счётчики SQL/Redis/cache/session и агрегаты латентности,
без токенов, паролей и SQL-текста. Токен возьмите из .env (METRICS_TOKEN).
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("есть счётчики и латентность", function() {
expect(res.body.counters).to.be.an("object");
expect(res.body.latency_ms).to.have.property("p50");
});
}
+40
View File
@@ -0,0 +1,40 @@
meta {
name: History first page
type: http
seq: 3
}
get {
url: {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=1
body: none
auth: none
}
headers {
Authorization: Bearer {{secondToken}}
}
docs {
Keyset-пагинация по (created_at, id) по возрастанию. История читается
любой действующей сессией участника — здесь второй сессией, что заодно
показывает read-after-write для ранее отправленного сообщения.
Сохраняет nextCursor.
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("страница ограничена limit", function() {
expect(res.body.items.length).to.equal(1);
});
test("есть курсор на следующую страницу", function() {
expect(res.body.next_cursor).to.be.a("string");
});
}
script:post-response {
bru.setVar("nextCursor", res.body.next_cursor);
}
+31
View File
@@ -0,0 +1,31 @@
meta {
name: History next page by cursor
type: http
seq: 4
}
get {
url: {{baseUrl}}/api/v1/chats/{{chatId}}/messages?limit=1&cursor={{nextCursor}}
body: none
auth: none
}
headers {
Authorization: Bearer {{secondToken}}
}
docs {
Продолжение по курсору. Курсор привязан к чату: значение от другого
чата вернёт 400. Последний элемент предыдущей страницы не повторяется.
}
tests {
test("200 ok", function() {
expect(res.status).to.equal(200);
});
test("второй элемент не дублирует первый", function() {
expect(res.body.items.length).to.equal(1);
expect(res.body.items[0].id).to.not.equal(bru.getVar("messageId"));
});
}
@@ -0,0 +1,40 @@
meta {
name: Send message as second user
type: http
seq: 2
}
post {
url: {{baseUrl}}/api/v1/chats/{{chatId}}/messages
body: json
auth: none
}
headers {
Authorization: Bearer {{secondToken}}
}
docs {
Любой участник чата может писать. Второе сообщение нужно, чтобы
страница с limit=1 вернула next_cursor и пагинацию можно было проверить.
}
body:json {
{
"text": "Ответ второго участника"
}
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
test("sender — второй пользователь", function() {
expect(res.body.sender_id).to.equal(bru.getVar("secondUserId"));
});
}
script:post-response {
bru.setVar("secondMessageId", res.body.id);
}
+46
View File
@@ -0,0 +1,46 @@
meta {
name: Send message
type: http
seq: 1
}
post {
url: {{baseUrl}}/api/v1/chats/{{chatId}}/messages
body: json
auth: none
}
headers {
Authorization: Bearer {{token}}
}
docs {
Отправитель берётся из Bearer-идентичности; поле sender_id в теле
не принимается (лишние поля — 400). Пустой или пробельный текст — 400.
Запись коммитит сообщение и увеличивает chats.message_version в одной
транзакции. Сохраняет messageId.
}
body:json {
{
"text": "Привет из Bruno 👋"
}
}
tests {
test("201 created", function() {
expect(res.status).to.equal(201);
});
test("sender выведен из сессии", function() {
expect(res.body.sender_id).to.equal(bru.getVar("userId"));
});
test("сообщение в нужном чате", function() {
expect(res.body.chat_id).to.equal(bru.getVar("chatId"));
});
}
script:post-response {
bru.setVar("messageId", res.body.id);
}
@@ -0,0 +1,31 @@
meta {
name: Basic on business endpoint
type: http
seq: 2
}
get {
url: {{baseUrl}}/api/v1/users/me
body: none
auth: basic
}
auth:basic {
username: {{username}}
password: {{password}}
}
docs {
Basic принимается только на POST /auth/sessions. На бизнес-endpoint
он даёт 401 с Bearer-challenge, даже если credentials верные.
}
tests {
test("401 unauthorized", function() {
expect(res.status).to.equal(401);
});
test("Bearer challenge", function() {
expect(res.headers["www-authenticate"]).to.equal('Bearer realm="messenger"');
});
}

Some files were not shown because too many files have changed in this diff Show More