Health Checks¶

Документ описывает единственный health-эндпоинт Payment Manager — GET /health — его реализацию на базе @fastify/under-pressure, формат ответа и поведение под нагрузкой. Используется балансировщиками, мониторингом и smoke-тестами при деплое.

Единственный health endpoint¶

Payment Manager экспонирует один health-эндпоинт:

Метод	Путь	Назначение
GET	`/health`	Проверка живости процесса, доступности event loop и подключения к TigerBeetle

Эндпоинт не требует HMAC-подписи — он публичен и предназначен для внешних probes (nginx upstream, docker healthcheck, мониторинг).

Реализация¶

Источник: src/admin/health.ts, регистрация плагина — в src/server.ts.

Используется плагин @fastify/under-pressure версии ^9.0.3 (см. package.json). Он подключается одной строкой в server.ts:

// Event loop delay monitor — exposes app.isUnderPressure() to routes
await app.register(underPressure, { maxEventLoopDelay: 1000 })

Конфигурация:

maxEventLoopDelay: 1000 — порог в миллисекундах. Если задержка event loop превышает 1000 ms (1 секунду), плагин помечает процесс как «under pressure», и app.isUnderPressure() возвращает true.
Других limits (maxHeapUsedBytes, maxRssBytes, maxEventLoopUtilization) не настроено — мониторим только event loop delay.

Логика обработчика GET /health:

Если app.isUnderPressure() → ответ 503 Service Unavailable с телом { status: 'ko', message: 'Service under pressure' }.
Иначе — пробный вызов getTb().lookupAccounts([]) для проверки соединения с TigerBeetle. При любом исключении → 503 с { status: 'ko', message: 'TigerBeetle unavailable' }.
Если оба чек-а пройдены — 200 OK с телом текущего статуса.

Формат ответа¶

200 OK — здоровый процесс¶

{
  "status": "ok",
  "version": "0.3.0",
  "timestamp": "2026-05-29T12:34:56.789Z"
}

Поля:

Поле	Тип	Источник	Описание
`status`	string	литерал `"ok"`	Сигнал «всё в порядке».
`version`	string	`process.env.npm_package_version` либо `"0.0.0"`	Версия PM из `package.json` (текущая — `0.3.0`).
`timestamp`	string	`new Date().toISOString()`	Время ответа в UTC, ISO 8601.

503 Service Unavailable — деградация¶

{
  "status": "ko",
  "message": "Service under pressure"
}

Поле message принимает одно из двух значений:

"Service under pressure" — превышен maxEventLoopDelay = 1000 ms.
"TigerBeetle unavailable" — lookupAccounts([]) бросил исключение (нет соединения, таймаут).

Использование¶

nginx upstream healthcheck — ходит на GET /health, исключает реплику из ротации при 503.
Docker / Kubernetes liveness (текущая упрощённая схема) — GET /health, рестарт контейнера при долгих 503.
Smoke-тесты деплоя — после старта сервиса должен вернуться 200 с актуальным version.
Тест-покрытие — test/health.test.ts проверяет 200 OK и CORS headers.

Пример curl-вызова:

curl -fsS http://localhost:8080/health
# → {"status":"ok","version":"0.3.0","timestamp":"2026-05-29T12:34:56.789Z"}

Флаг -f нужен, чтобы curl упал с ненулевым кодом на 503 — это поведение используется healthcheck-скриптами в docker-compose.yml и nginx health_check.

Что эндпоинт не проверяет¶

❌ Соединение с PostgreSQL — нет отдельного query внутри /health.
❌ Соединение с Redis (pub/sub каналы интентов) — нет ping.
❌ Доступность IPPS PSP — это внешняя зависимость, не входит в SLO самого PM.
❌ Состояние OutboxWorker / saga-воркеров — у них собственная диагностика через логи и метрики.

Эти проверки запланированы в /readyz (Phase 2B). На сегодня их отсутствие компенсируется логами и алертами на падение фоновых задач.

Заготовка на будущее (Phase 2B)¶

Заготовка на будущее: в Phase 2B возможен переход на Kubernetes-style probes — отдельные эндпоинты /livez (живость процесса), /readyz (готовность принимать трафик: TB + Postgres + Redis) и /startupz (завершение инициализации воркеров и миграций). Сейчас этих эндпоинтов нет — используется только GET /health. Добавление будет согласовано с инфраструктурной командой при переезде в Kubernetes.

Связанные документы¶

Operations overview — общая эксплуатационная документация PM.
Deployment — env-переменные, docker, прод-конфигурация.
Testing — smoke- и integration-тесты, в т.ч. health-check.