@application-kit/bootstrap

Бутстрап процессов NestJS: web на Fastify с периметром, consumer с сервером метрик и CLI на nestjs-console. Состав модулей, контроллеры документа Swagger и хуки метрик знает приложение: пакет собирает процесс из его корневого модуля и опций. Порт, число прокси и порт метрик — переменные окружения контракта чарта; невалидное значение роняет старт.

Установка

yarn add @application-kit/bootstrap

Peer-зависимости — @nestjs/common, @nestjs/core, nestjs-pino; остальные optional и нужны только своему входу. @application-kit/observability пакет приносит сам. Логгер обоих входов — nestjs-pino: его LoggerModule обязан быть в графе корневого модуля.

Входы

Корневого входа нет: web-процессу nestjs-console не нужен, CLI — Fastify.

Окружение

Значение числовых переменных — целое не меньше 0 (порт — не больше 65535). Иное (abc, 1.5, -1) — ClassValidationError с именем переменной до создания приложения: Number('abc') дал бы NaN, и доверенных прокси молча стало бы ноль.

Web

import { webBootstrap } from '@application-kit/bootstrap/web'

void webBootstrap(AppModule, {
  configure: (app) => {
    setupMetricsHooks(app)
  },
})

webBootstrap берёт порт и прокси из окружения, собирает приложение через createFastifyApplication, слушает и возвращает его. createFastifyApplication — для своего запуска, когда порт и прокси приходят не из окружения:

import { createFastifyApplication } from '@application-kit/bootstrap/web'

const app = await createFastifyApplication(AppModule, {
  configure: (app) => {
    setupMetricsHooks(app)
  },
  trustProxyHops: 2,
})
await app.listen(port, '0.0.0.0')

Периметр, который ставит пакет, по порядку:

1. Fastify-адаптер: genReqId — x-request-id от прокси либо свой UUID (fastifyRequestId из @application-kit/observability/logging); доверенные прокси — первые trustProxyHops прыжков справа в X-Forwarded-For, так что адрес, подсунутый клиентом слева, request.ip не подменяет.
2. @fastify/cookie с опциями cookie.
3. Хук onRequest: заголовок x-request-id на каждый ответ, включая 404 и ошибки парсинга тела.
4. configure(app) — настройка продукта.
5. LoggerErrorInterceptor и логгер nestjs-pino для Nest; uncaughtException — в тот же лог.
6. Shutdown hooks: по SIGTERM/SIGINT провайдеры закрываются, HTTP-сервер дожидается открытых соединений.
7. Глобальный ValidationPipe с transform: true: невалидный DTO — статус validationErrorStatus и тело { statusCode, validationErrors: [{ property, constraints }] }, вложенное поле — путём parent.child.

Swagger

import { setupSwagger } from '@application-kit/bootstrap/swagger'

const options = {
  configure: (app) => {
    setupSwagger(app, { include: [HealthHttpModule, MetricsHttpModule] })
  },
} satisfies FastifyApplicationOptionsInterface

Документ описывает всю серверную поверхность и аутентификации не требует, поэтому без SWAGGER_ENABLED он не публикуется. В документ попадают контроллеры модулей из include, operationId — имя метода. UI отдаётся по path (по умолчанию swagger), JSON — по <path>-json, версия в info — version (по умолчанию 1.0).

Consumer

import { consumerBootstrap } from '@application-kit/bootstrap/consumer'
import { kafkaConsumerServer } from '@application-kit/kafka'

void consumerBootstrap(ConsumerModule, kafkaConsumerServer)

Сервер /metrics поднимается на METRICS_PORT со своим реестром метрик процесса, затем корневой модуль уходит транспорту вместе с логгером nestjs-pino. Транспорт передаёт приложение: от брокера пакет не зависит.

CLI

import { cliBootstrap } from '@application-kit/bootstrap/cli'

void cliBootstrap(CliModule)

Команда берётся из process.argv, после неё приложение закрывается. Упавшая команда — запись уровня error с context: 'Console process failed.' и код выхода 1: cron и джоба кластера видят провал только по коду. Корневой модуль импортирует ConsoleModule из nestjs-console.