@verdeect/kit 0.0.0-stage → 1.0.0-rc.2

package/dist/http/api/openapi-document.js

@@ -0,0 +1,452 @@
+import { RequestMethod } from '@nestjs/common';
+import { GUARDS_METADATA, HTTP_CODE_METADATA, METHOD_METADATA, MODULE_METADATA, PATH_METADATA, ROUTE_ARGS_METADATA, } from '@nestjs/common/constants.js';
+import { RouteParamtypes } from '@nestjs/common/enums/route-paramtypes.enum.js';
+import { VerdeectAuthGuard } from '@verdeect/auth/nest';
+import { IDEMPOTENT_METADATA } from '../../internal/metadata.js';
+import { z } from 'zod';
+import { errorStatus } from '../errors.js';
+import { ZodValidationPipe } from '../zod-validation.pipe.js';
+import { API_METADATA } from './api.decorator.js';
+// Ключи метаданных Require* @verdeect/auth 1.0.1 (dist/nest/decorators.js): пакет их не экспортирует.
+const REQUIRE_SCOPES = 'verdeect-auth:require-scopes';
+const REQUIRE_USER = 'verdeect-auth:require-user';
+const REQUIRE_SERVICE = 'verdeect-auth:require-service';
+const REQUIRE_TENANT = 'verdeect-auth:require-tenant';
+const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete'];
+const METHODS = {
+    [RequestMethod.GET]: 'get',
+    [RequestMethod.POST]: 'post',
+    [RequestMethod.PUT]: 'put',
+    [RequestMethod.PATCH]: 'patch',
+    [RequestMethod.DELETE]: 'delete',
+};
+const ERROR_RESPONSE_REF = { $ref: '#/components/schemas/ErrorResponse' };
+const ERROR_RESPONSE = {
+    type: 'object',
+    properties: {
+        error: {
+            type: 'object',
+            properties: {
+                code: { type: 'string' },
+                message: { type: 'string' },
+                details: { type: 'object' },
+            },
+            required: ['code', 'message', 'details'],
+        },
+    },
+    required: ['error'],
+};
+function toSchema(schema, io) {
+    const json = z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+    delete json.$schema;
+    return json;
+}
+function joinPath(...parts) {
+    const path = parts
+        .flatMap((part) => part.split('/'))
+        .filter((segment) => segment !== '')
+        .map((segment) => (segment.startsWith(':') ? `{${segment.slice(1)}}` : segment))
+        .join('/');
+    return `/${path}`;
+}
+function pathsOf(value) {
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string');
+    }
+    return [typeof value === 'string' ? value : ''];
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Глубокое слияние `extra` (операция, `contracts/openapi.extra.json`): объекты сливаются, прочее заменяется. */
+export function deepMerge(target, extra) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(extra)) {
+        const current = result[key];
+        result[key] = isObject(current) && isObject(value) ? deepMerge(current, value) : value;
+    }
+    return result;
+}
+function enveloped(schema, envelope) {
+    switch (envelope) {
+        case 'page':
+            return {
+                type: 'object',
+                properties: {
+                    items: { type: 'array', items: schema },
+                    nextCursor: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+                },
+                required: ['items', 'nextCursor'],
+                additionalProperties: false,
+            };
+        case 'items':
+            return {
+                type: 'object',
+                properties: { items: { type: 'array', items: schema } },
+                required: ['items'],
+                additionalProperties: false,
+            };
+        case 'array':
+            return { type: 'array', items: schema };
+        default:
+            return schema;
+    }
+}
+function zodPipeOf(argument) {
+    const pipe = argument.pipes?.find((item) => item instanceof ZodValidationPipe);
+    return pipe instanceof ZodValidationPipe ? pipe : null;
+}
+/** Метаданные метода перекрывают метаданные класса (как у guard'а @verdeect/auth). */
+function metadataOf(key, handler, controller) {
+    const own = Reflect.getMetadata(key, handler);
+    return own === undefined ? Reflect.getMetadata(key, controller) : own;
+}
+function hasAuthGuard(target) {
+    const guards = Reflect.getMetadata(GUARDS_METADATA, target);
+    return (Array.isArray(guards) &&
+        guards.some((guard) => guard === VerdeectAuthGuard ||
+            guard instanceof VerdeectAuthGuard ||
+            (typeof guard === 'function' && guard.name === VerdeectAuthGuard.name)));
+}
+function securityOf(controller, handler) {
+    const scopes = metadataOf(REQUIRE_SCOPES, handler, controller);
+    const user = metadataOf(REQUIRE_USER, handler, controller) === true;
+    const service = metadataOf(REQUIRE_SERVICE, handler, controller) === true;
+    const tenant = metadataOf(REQUIRE_TENANT, handler, controller) === true;
+    const guarded = hasAuthGuard(handler) || hasAuthGuard(controller);
+    if (!guarded && !user && !service && !tenant && scopes === undefined) {
+        return null;
+    }
+    const schemes = [];
+    if (service || !user) {
+        schemes.push('serviceToken');
+    }
+    if (user || !service) {
+        schemes.push('userToken');
+    }
+    return {
+        schemes,
+        tenant,
+        scopes: Array.isArray(scopes)
+            ? scopes.filter((s) => typeof s === 'string')
+            : [],
+    };
+}
+function queryParameters(schema, data) {
+    if (typeof data === 'string') {
+        return [{ name: data, in: 'query', required: false, schema }];
+    }
+    const properties = (schema.properties ?? {});
+    const required = new Set((schema.required ?? []));
+    return Object.entries(properties).map(([name, property]) => ({
+        name,
+        in: 'query',
+        required: required.has(name),
+        schema: property,
+    }));
+}
+/** Схема успешного ответа маршрута (с конвертом). */
+function responseSchemaOf(api) {
+    return api.response === undefined
+        ? null
+        : enveloped(toSchema(api.response, 'output'), api.envelope);
+}
+/** Опции `@Idempotent` обработчика (декоратор методный) или `null`. */
+function idempotentOf(route) {
+    const options = Reflect.getMetadata(IDEMPOTENT_METADATA, route.handler);
+    return typeof options === 'object' && options !== null
+        ? options
+        : null;
+}
+/** Ошибки операции: статус → коды. */
+function errorsOf(route, security) {
+    const errors = new Map([
+        [400, ['BAD_REQUEST']],
+        [422, ['VALIDATION_FAILED']],
+        [429, ['RATE_LIMITED']],
+    ]);
+    if (security !== null) {
+        errors.set(401, ['UNAUTHENTICATED']);
+        errors.set(403, security.scopes.length > 0 ? ['FORBIDDEN', 'SCOPE_REQUIRED'] : ['FORBIDDEN']);
+        if (security.tenant) {
+            // Тело — {error: {code: 'TENANT_REQUIRED', message: 'Не выбрана компания', details: {}}} guard'а.
+            errors.set(409, ['TENANT_REQUIRED']);
+        }
+    }
+    for (const code of route.api.errors ?? []) {
+        const status = errorStatus(code);
+        if (status === undefined) {
+            throw new Error(`openapi: ${route.controller.name}.${route.handlerName} — код ${code} не зарегистрирован в defineErrors`);
+        }
+        errors.set(status, [...(errors.get(status) ?? []), code]);
+    }
+    const idempotent = idempotentOf(route);
+    if (idempotent !== null) {
+        const add = (status, code) => void errors.set(status, [...(errors.get(status) ?? []), code]);
+        add(409, 'IDEMPOTENCY_IN_PROGRESS');
+        add(422, 'IDEMPOTENCY_KEY_REUSED');
+        if (idempotent.required === true) {
+            add(400, 'IDEMPOTENCY_KEY_REQUIRED');
+        }
+    }
+    return errors;
+}
+function parametersOf(route, path) {
+    const args = (Reflect.getMetadata(ROUTE_ARGS_METADATA, route.controller, route.handlerName) ??
+        {});
+    const pathSchemas = new Map();
+    const parameters = [];
+    let body;
+    for (const [key, argument] of Object.entries(args)) {
+        const paramtype = Number(key.split(':', 1)[0]);
+        const pipe = zodPipeOf(argument);
+        if (pipe === null) {
+            continue;
+        }
+        const schema = toSchema(pipe.schema, 'input');
+        if (paramtype === RouteParamtypes.BODY) {
+            body = { required: true, content: { 'application/json': { schema } } };
+        }
+        else if (paramtype === RouteParamtypes.QUERY) {
+            parameters.push(...queryParameters(schema, argument.data));
+        }
+        else if (paramtype === RouteParamtypes.PARAM && typeof argument.data === 'string') {
+            pathSchemas.set(argument.data, schema);
+        }
+    }
+    const pathParameters = [...path.matchAll(/\{([^}]+)\}/g)].map((match) => {
+        const name = match[1] ?? '';
+        return {
+            name,
+            in: 'path',
+            required: true,
+            schema: pathSchemas.get(name) ?? { type: 'string' },
+        };
+    });
+    const idempotent = idempotentOf(route);
+    const idempotencyKey = idempotent === null
+        ? []
+        : [
+            {
+                name: 'Idempotency-Key',
+                in: 'header',
+                required: idempotent.required === true,
+                schema: { type: 'string', pattern: '^[\\x21-\\x7E]{1,200}$' },
+            },
+        ];
+    return {
+        parameters: [...pathParameters, ...parameters, ...idempotencyKey],
+        ...(body === undefined ? {} : { body }),
+    };
+}
+function buildOperation(route, path) {
+    const security = securityOf(route.controller, route.handler);
+    const { parameters, body } = parametersOf(route, path);
+    const schema = responseSchemaOf(route.api);
+    const responses = {
+        [String(route.status)]: schema === null
+            ? { description: 'успех, без тела' }
+            : { description: 'успех', content: { 'application/json': { schema } } },
+    };
+    if (idempotentOf(route) !== null) {
+        const success = responses[String(route.status)];
+        responses[String(route.status)] = {
+            ...success,
+            headers: {
+                'Idempotent-Replayed': {
+                    schema: { type: 'string', enum: ['true'] },
+                    description: 'ответ сохранён и повторён',
+                },
+            },
+        };
+    }
+    for (const [status, codes] of [...errorsOf(route, security).entries()].sort(([a], [b]) => a - b)) {
+        responses[String(status)] = {
+            description: [...new Set(codes)].join(', '),
+            content: { 'application/json': { schema: ERROR_RESPONSE_REF } },
+            ...(status === 429
+                ? {
+                    headers: {
+                        'Retry-After': {
+                            schema: { type: 'integer' },
+                            description: 'секунды до повтора',
+                        },
+                    },
+                }
+                : {}),
+        };
+    }
+    const name = route.controller.name.replace(/Controller$/, '');
+    const operationId = `${name.charAt(0).toLowerCase()}${name.slice(1)}${route.handlerName.charAt(0).toUpperCase()}${route.handlerName.slice(1)}`;
+    const operation = {
+        operationId,
+        summary: route.api.summary,
+        ...(security === null
+            ? {}
+            : { security: security.schemes.map((scheme) => ({ [scheme]: [...security.scopes] })) }),
+        ...(parameters.length === 0 ? {} : { parameters }),
+        ...(body === undefined ? {} : { requestBody: body }),
+        responses,
+    };
+    return {
+        path,
+        method: route.method,
+        operation: route.api.extra === undefined ? operation : deepMerge(operation, route.api.extra),
+        security,
+    };
+}
+/** Маршрут `[Controller, 'method']` с `@Api`; без `@Api` — `null`; `@Api` без метода HTTP — Error. */
+function apiRouteOf(controller, handlerName) {
+    const prototype = controller.prototype;
+    const handler = prototype[handlerName];
+    if (typeof handler !== 'function') {
+        return null;
+    }
+    const api = Reflect.getMetadata(API_METADATA, handler);
+    if (api === undefined) {
+        return null;
+    }
+    const method = METHODS[Reflect.getMetadata(METHOD_METADATA, handler)];
+    const handlerPath = Reflect.getMetadata(PATH_METADATA, handler);
+    if (method === undefined || handlerPath === undefined) {
+        throw new Error(`openapi: ${controller.name}.${handlerName} — @Api без пути или метода HTTP`);
+    }
+    const status = Reflect.getMetadata(HTTP_CODE_METADATA, handler) ??
+        (method === 'post' ? 201 : 200);
+    const paths = pathsOf(Reflect.getMetadata(PATH_METADATA, controller)).flatMap((prefix) => pathsOf(handlerPath).map((suffix) => joinPath(prefix, suffix)));
+    return { controller, handlerName, handler, api, method, paths, status };
+}
+/** Схема успешного ответа, статус и описанные статусы ошибок маршрута для `expectMatchesApi`. Внутренняя функция. */
+export function routeResponseSchema(route) {
+    const [controller, handlerName] = route;
+    const api = apiRouteOf(controller, handlerName);
+    if (api === null) {
+        throw new Error(`expectMatchesApi: у ${controller.name}.${handlerName} нет @Api`);
+    }
+    const errors = errorsOf(api, securityOf(api.controller, api.handler));
+    return {
+        status: api.status,
+        schema: responseSchemaOf(api.api),
+        errorStatuses: [...errors.keys()].sort((a, b) => a - b),
+        errorSchema: ERROR_RESPONSE,
+    };
+}
+/**
+ * Имена методов класса и его предков до `Object.prototype`, как у `MetadataScanner` Nest: метод наследника с тем же
+ * именем заменяет метод предка (берётся `prototype[name]` наследника).
+ */
+function handlerNamesOf(controller) {
+    const names = new Set();
+    let prototype = controller.prototype;
+    while (typeof prototype === 'object' && prototype !== null && prototype !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(prototype)) {
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+            if (name !== 'constructor' && typeof descriptor?.value === 'function') {
+                names.add(name);
+            }
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return [...names].sort();
+}
+async function resolveEntry(entry) {
+    const resolved = await entry;
+    if (resolved === null || resolved === undefined) {
+        return null;
+    }
+    if (isObject(resolved) && typeof resolved.forwardRef === 'function') {
+        return resolveEntry(resolved.forwardRef());
+    }
+    if (isObject(resolved) && typeof resolved.module === 'function') {
+        return { cls: resolved.module, dynamic: resolved };
+    }
+    if (typeof resolved === 'function') {
+        return { cls: resolved };
+    }
+    return null;
+}
+/** Контроллеры графа модулей по метаданным: приложение не создаётся. */
+async function collectControllers(root) {
+    const seen = new Set();
+    const controllers = new Set();
+    const queue = [root];
+    for (let entry = queue.shift(); entry !== undefined; entry = queue.shift()) {
+        const resolved = await resolveEntry(entry);
+        const key = resolved?.dynamic ?? resolved?.cls;
+        if (resolved === null || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const staticImports = (Reflect.getMetadata(MODULE_METADATA.IMPORTS, resolved.cls) ??
+            []);
+        const staticControllers = (Reflect.getMetadata(MODULE_METADATA.CONTROLLERS, resolved.cls) ??
+            []);
+        queue.push(...staticImports, ...(resolved.dynamic?.imports ?? []));
+        for (const controller of [...staticControllers, ...(resolved.dynamic?.controllers ?? [])]) {
+            controllers.add(controller);
+        }
+    }
+    return [...controllers];
+}
+function securitySchemes(built) {
+    const scopesOf = (scheme) => Object.fromEntries([
+        ...new Set(built.flatMap((item) => item.security?.schemes.includes(scheme) === true
+            ? item.security.scopes
+            : [])),
+    ]
+        .sort()
+        .map((scope) => [scope, scope]));
+    return {
+        serviceToken: {
+            type: 'oauth2',
+            description: 'сервисный токен client_credentials (at+jwt) Identity',
+            flows: {
+                clientCredentials: { tokenUrl: '/oidc/token', scopes: scopesOf('serviceToken') },
+            },
+        },
+        userToken: {
+            type: 'oauth2',
+            description: 'токен пользователя (at+jwt) Identity',
+            flows: {
+                authorizationCode: {
+                    authorizationUrl: '/oidc/auth',
+                    tokenUrl: '/oidc/token',
+                    scopes: scopesOf('userToken'),
+                },
+            },
+        },
+    };
+}
+/**
+ * Документ OpenAPI 3.1 сервиса по метаданным модулей и контроллеров (§3.5): приложение не создаётся, окружение не
+ * нужно. В документ входят только маршруты с `@Api`; пути и коды отсортированы. Внутренняя функция (CLI, тесты).
+ */
+export async function buildOpenApiDocument(module, info, logger) {
+    const built = [];
+    for (const controller of await collectControllers(module)) {
+        for (const handlerName of handlerNamesOf(controller)) {
+            const route = apiRouteOf(controller, handlerName);
+            for (const path of route?.paths ?? []) {
+                built.push(buildOperation(route, path));
+            }
+        }
+    }
+    const paths = {};
+    const sorted = [...built].sort((a, b) => a.path.localeCompare(b.path) ||
+        METHOD_ORDER.indexOf(a.method) - METHOD_ORDER.indexOf(b.method));
+    for (const item of sorted) {
+        const operations = paths[item.path] ?? {};
+        operations[item.method] = item.operation;
+        paths[item.path] = operations;
+    }
+    logger?.debug({ operations: built.length }, 'openapi: собран');
+    return {
+        openapi: '3.1.0',
+        info: { title: info.title, version: info.version },
+        paths,
+        components: {
+            securitySchemes: securitySchemes(built),
+            schemas: { ErrorResponse: ERROR_RESPONSE },
+        },
+    };
+}

package/dist/http/bootstrap-service.d.ts

@@ -0,0 +1,33 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+import { z } from 'zod';
+import { type KitBaseEnv } from '../config/fragments.js';
+import { type KitRedaction } from '../observability/redaction.js';
+import type { KitHttpLoggerOptions } from './kit-http-core.module.js';
+/** Схема окружения сервиса: результат содержит ключи `envBase`. */
+type ServiceEnvSchema = z.ZodType<KitBaseEnv & Record<string, unknown>>;
+/** Опции `bootstrapService` (§3.5). */
+export interface KitBootstrapOptions<S extends ServiceEnvSchema = ServiceEnvSchema> {
+    /** Корневой модуль сервиса; импортирует `KitConfigModule.forRoot({schema: env})` с той же схемой. */
+    readonly module: Type | DynamicModule;
+    /** Имя сервиса `^[a-z][a-z0-9-]{1,31}$`; вне формата — отказ запуска. */
+    readonly service: string;
+    /** Схема окружения (`defineEnv`): разбирается до создания приложения. */
+    readonly env: S;
+    /** Опции логгера по роли: BFF — `trustTraceparent: false`; P, O — `quietRoutes`. */
+    readonly logger?: KitHttpLoggerOptions;
+    /** Опции HTTP: `bodyLimit` — лимит тела, байт (по умолчанию — лимит Fastify). */
+    readonly http?: {
+        readonly bodyLimit?: number;
+    };
+    /** Правила редактирования сервиса (общие с `initSentry` в `instrument.ts`). */
+    readonly redaction?: KitRedaction;
+}
+/**
+ * Точка входа `main.ts` сервиса (§3.5): `parseEnv(env, process.env)` до создания приложения → логгер →
+ * предупреждение `SENTRY_NOT_PRELOADED` → `createHttpApp` → сервер метрик (`METRICS_PORT`, шаг 5) →
+ * `KitLifecycle.listen()` (SIGTERM, SIGINT) → прослушивание `PORT` на `0.0.0.0`. Отказ на любом шаге — `failStartup`
+ * (`fatal`, GlitchTip, `exit(1)`): при неверном окружении приложение не создаётся и порт не открывается.
+ */
+export declare function bootstrapService<S extends ServiceEnvSchema>(options: KitBootstrapOptions<S>): Promise<NestFastifyApplication>;
+export {};

package/dist/http/bootstrap-service.js

@@ -0,0 +1,107 @@
+import * as Sentry from '@sentry/nestjs';
+import { pino } from 'pino';
+import { z } from 'zod';
+import { envSentry } from '../config/fragments.js';
+import { parseEnv } from '../config/parse-env.js';
+import { setPreparsedEnv } from '../internal/preparsed-env.js';
+import { assertServiceName } from '../internal/service-name.js';
+import { KIT_METRICS } from '../internal/tokens.js';
+import { failStartup } from '../observability/fail-startup.js';
+import { HealthRegistry } from '../observability/health-registry.js';
+import { KitLifecycle } from '../observability/lifecycle.js';
+import { createLoggerOptions } from '../observability/logger-options.js';
+import { MetricsServer } from '../observability/metrics-server.js';
+import { redactPaths } from '../observability/redaction.js';
+import { isValidDsn } from '../observability/sentry.js';
+import { buildHttpApp } from './create-http-app.js';
+/** Sentry не подключён через `--import instrument`, хотя конфигурация верна и он должен был включиться (§3.5, AC-3.11). */
+function sentryNotPreloaded() {
+    // Окружение Sentry — как в initSentry: схема сервиса может не содержать envSentry.
+    const parsed = z.object(envSentry).safeParse(process.env);
+    return (parsed.success &&
+        parsed.data.SENTRY_DSN !== null &&
+        // Неверный DSN initSentry выключает намеренно (AC-2.4): предупреждать не о чем.
+        isValidDsn(parsed.data.SENTRY_DSN) &&
+        parsed.data.NODE_ENV === 'production' &&
+        Sentry.getClient() === undefined);
+}
+/** Фактический порт HTTP-сервера приложения (в тестах PORT=0). */
+function httpPort(app) {
+    const address = app.getHttpServer().address();
+    if (typeof address !== 'object' || address === null || !('port' in address)) {
+        return null;
+    }
+    return typeof address.port === 'number' ? address.port : null;
+}
+/**
+ * Точка входа `main.ts` сервиса (§3.5): `parseEnv(env, process.env)` до создания приложения → логгер →
+ * предупреждение `SENTRY_NOT_PRELOADED` → `createHttpApp` → сервер метрик (`METRICS_PORT`, шаг 5) →
+ * `KitLifecycle.listen()` (SIGTERM, SIGINT) → прослушивание `PORT` на `0.0.0.0`. Отказ на любом шаге — `failStartup`
+ * (`fatal`, GlitchTip, `exit(1)`): при неверном окружении приложение не создаётся и порт не открывается.
+ */
+export async function bootstrapService(options) {
+    // 1. Запасной логгер: отказ до разбора окружения тоже пишется JSON в stdout.
+    let logger = pino({
+        level: 'info',
+        base: { service: options.service, entry: 'http' },
+        redact: { paths: redactPaths(options.redaction), censor: '[Filtered]' },
+    }, process.stdout);
+    let env;
+    try {
+        // 2. Имя сервиса.
+        assertServiceName(options.service, 'bootstrapService');
+        // 3. Окружение до создания приложения (AC-3.13).
+        env = parseEnv(options.env, process.env);
+        // 4. KitConfigModule того же процесса берёт разобранное окружение без повторного разбора.
+        setPreparsedEnv(options.env, env);
+        // 5. Логгер сервиса.
+        logger = pino(...createLoggerOptions({
+            ...options.logger,
+            service: options.service,
+            entry: 'http',
+            env,
+            redaction: options.redaction,
+        }).pinoHttp);
+    }
+    catch (error) {
+        return failStartup(error, logger);
+    }
+    logger.debug('bootstrap: окружение разобрано');
+    // 6. Sentry инициализируется в instrument.ts до загрузки приложения (AC-3.11).
+    if (sentryNotPreloaded()) {
+        logger.warn({ code: 'SENTRY_NOT_PRELOADED' }, 'Sentry не подключён: запустите сервис с node --import ./dist/instrument.js');
+    }
+    try {
+        // 7. Приложение: участники шагов 2 (http) и 3 (nest) KitLifecycle регистрирует buildHttpApp.
+        const app = await buildHttpApp({
+            module: options.module,
+            service: options.service,
+            bodyLimit: options.http?.bodyLimit,
+            logger: options.logger,
+            redaction: options.redaction,
+            caller: 'bootstrapService',
+        });
+        logger.debug('bootstrap: приложение собрано');
+        // 8. Сервер метрик — участник шага 5.
+        const lifecycle = app.get(KitLifecycle);
+        const metricsServer = new MetricsServer({
+            port: env.METRICS_PORT,
+            registry: app.get(KIT_METRICS).registry,
+            health: app.get(HealthRegistry),
+            logger,
+        });
+        await metricsServer.listen();
+        lifecycle.register({ name: 'metrics', stop: () => metricsServer.close() }, { step: 5 });
+        logger.debug('bootstrap: метрики слушают');
+        // 9. Сигналы ОС — только KitLifecycle: сторож срока и exit.
+        lifecycle.listen();
+        // 10. Прослушивание PORT.
+        await app.listen(env.PORT, '0.0.0.0');
+        // 11. Фактические порты: в тестах PORT=0 и METRICS_PORT=0.
+        logger.info({ port: httpPort(app), metricsPort: metricsServer.address() }, 'сервис слушает');
+        return app;
+    }
+    catch (error) {
+        return failStartup(error, logger);
+    }
+}

package/dist/http/create-http-app.d.ts

@@ -0,0 +1,38 @@
+import { type DynamicModule, type Type } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import type { KitRedaction } from '../observability/redaction.js';
+import { type KitHttpLoggerOptions } from './kit-http-core.module.js';
+/** Опции `createHttpApp` (§3.5). */
+export interface KitHttpAppOptions {
+    /** Корневой модуль сервиса; обязан импортировать `KitConfigModule.forRoot({schema})`. */
+    readonly module: Type | DynamicModule;
+    /** Имя сервиса `^[a-z][a-z0-9-]{1,31}$`: поле `service` логов и метка метрик. */
+    readonly service: string;
+    /** Лимит тела запроса, байт; по умолчанию — лимит Fastify (1 MiB). Больше — 413 `PAYLOAD_TOO_LARGE`. */
+    readonly bodyLimit?: number;
+    /** Набор заголовков безопасности; единственный — `api` (`nosniff`, `Referrer-Policy: no-referrer`). */
+    readonly securityHeaders?: 'api';
+}
+/** Сборка Nest-приложения на адаптере (createTestApp — через Test.createTestingModule). */
+type Compile = (root: DynamicModule, adapter: FastifyAdapter) => Promise<NestFastifyApplication>;
+/** Внутренние опции сборки: общие для createHttpApp, bootstrapService и createTestApp. */
+export interface BuildHttpAppOptions extends KitHttpAppOptions {
+    /** Опции логгера по роли сервиса. */
+    readonly logger?: KitHttpLoggerOptions;
+    /** Правила редактирования сервиса. */
+    readonly redaction?: KitRedaction;
+    /** Своя сборка приложения на корневом модуле и адаптере. */
+    readonly compile?: Compile;
+    /** Имя вызывающего для текста ошибки формата имени. */
+    readonly caller?: string;
+}
+/** Внутренняя сборка приложения: «тот же createHttpApp» для bootstrapService и createTestApp (§3.8). */
+export declare function buildHttpApp(options: BuildHttpAppOptions): Promise<NestFastifyApplication>;
+/**
+ * Fastify-приложение Nest сервиса (§3.5): заголовки безопасности API, trace-id из `traceparent`, `GET /ok`, фильтр
+ * `KitExceptionFilter`, 404 `ROUTE_NOT_FOUND`, логгер nestjs-pino, `KitLifecycle` и `HealthRegistry` для модулей сервиса.
+ * `app.close()` — программная остановка по шагам 1–5 (§3.2) без сторожа и `exit`. Процесс сервиса запускает
+ * `bootstrapService`; `createHttpApp` — для своих точек входа и тестов.
+ */
+export declare function createHttpApp(options: KitHttpAppOptions): Promise<NestFastifyApplication>;
+export {};