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

package/dist/http/create-http-app.js

@@ -0,0 +1,137 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+// createHttpApp (prd.md §3.5, AC-3.4, AC-3.5, AC-3.12; §3.2 шаги 2–3; KT-11, KT-15 п. 1). Эталоны: O/P main.ts (NestFactory,
+// FastifyAdapter({genReqId}), bufferLogs, useLogger), P/O configure-http-server.ts + security-headers.ts (onRequest на
+// reply.raw: nosniff, no-referrer), регистрация фильтра — KitHttpCoreModule. По PRD: участники KitLifecycle вместо
+// enableShutdownHooks/InstanceShutdown — шаг 2 `http` (server.close Fastify), шаг 3 `nest` (исходный app.close Nest);
+// app.close() экземпляра = lifecycle.close(); своих парсеров тела нет (лимит — bodyLimit адаптера и route.bodyLimit).
+import { Module } from '@nestjs/common';
+import { NestApplication, NestFactory } from '@nestjs/core';
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+import { Logger as NestPinoLogger } from 'nestjs-pino';
+import { assertServiceName } from '../internal/service-name.js';
+import { KIT_LOGGER } from '../internal/tokens.js';
+import { KitLifecycle } from '../observability/lifecycle.js';
+import { traceIdGenerator } from '../observability/logger-options.js';
+import { KitHttpCoreModule } from './kit-http-core.module.js';
+/** Заголовки безопасности API (P/O security-headers.ts): есть и на ошибках, `/ok` и 404. */
+const API_SECURITY_HEADERS = [
+    ['X-Content-Type-Options', 'nosniff'],
+    ['Referrer-Policy', 'no-referrer'],
+];
+/** Корень приложения: модуль сервиса и ядро. */
+let KitHttpRootModule = class KitHttpRootModule {
+};
+KitHttpRootModule = __decorate([
+    Module({})
+], KitHttpRootModule);
+const defaultCompile = (root, adapter) => NestFactory.create(root, adapter, {
+    bufferLogs: true,
+    // С умолчанием true Nest при ошибке DI сам вызывает process.exit(1), минуя failStartup.
+    abortOnError: false,
+});
+/** Хуки Fastify и участник шага 2: заголовки, Connection: close и закрытие простаивающих соединений при остановке. */
+function installServerHooks(app) {
+    const fastify = app.getHttpAdapter().getInstance();
+    let closing = false;
+    // Все хуки — до init: addHook после listen() бросает FST_ERR_INSTANCE_ALREADY_LISTENING.
+    fastify.addHook('onRequest', (_request, reply, done) => {
+        for (const [name, value] of API_SECURITY_HEADERS) {
+            reply.raw.setHeader(name, value);
+        }
+        done();
+    });
+    fastify.addHook('onSend', (_request, reply, _payload, done) => {
+        if (closing) {
+            void reply.header('Connection', 'close');
+        }
+        done();
+    });
+    fastify.addHook('onResponse', (_request, _reply, done) => {
+        if (closing) {
+            // keep-alive соединение, ответ на котором закончился после начала close(), иначе живёт до keepAliveTimeout.
+            fastify.server.closeIdleConnections();
+        }
+        done();
+    });
+    return async () => {
+        const server = fastify.server;
+        if (!server.listening) {
+            return;
+        }
+        closing = true;
+        const closed = new Promise((resolve, reject) => {
+            server.close((error) => (error === undefined ? resolve() : reject(error)));
+        });
+        server.closeIdleConnections();
+        await closed;
+    };
+}
+/** Регистрирует участников шагов 2–3 и подменяет app.close() на lifecycle.close(). */
+function installLifecycle(app, closeServer, logger) {
+    const lifecycle = app.get(KitLifecycle);
+    lifecycle.register({
+        name: 'http',
+        stop: async () => {
+            const startedAt = performance.now();
+            await closeServer();
+            logger.debug({ durationMs: Math.round(performance.now() - startedAt) }, 'http: приём соединений остановлен');
+        },
+    }, { step: 2 });
+    logger.debug({ participant: 'http' }, 'http: участник шага 2 зарегистрирован');
+    lifecycle.register({
+        name: 'nest',
+        // Исходный close — с прототипа: app.close уже подменён и ждал бы сам себя.
+        stop: async () => {
+            await NestApplication.prototype.close.call(app);
+            logger.debug('http: хуки Nest завершены');
+        },
+    }, { step: 3 });
+    // Присваивание не работает: set-ловушка прокси NestFactory не сохраняет значение; defineProperty уходит в цель.
+    Object.defineProperty(app, 'close', {
+        value: () => lifecycle.close(),
+        configurable: true,
+        writable: true,
+    });
+}
+/** Внутренняя сборка приложения: «тот же createHttpApp» для bootstrapService и createTestApp (§3.8). */
+export async function buildHttpApp(options) {
+    assertServiceName(options.service, options.caller ?? 'createHttpApp');
+    const root = {
+        module: KitHttpRootModule,
+        imports: [
+            options.module,
+            KitHttpCoreModule.forRoot({
+                service: options.service,
+                logger: options.logger,
+                redaction: options.redaction,
+            }),
+        ],
+    };
+    const adapter = new FastifyAdapter({
+        genReqId: traceIdGenerator(options.logger?.trustTraceparent !== false),
+        ...(options.bodyLimit === undefined ? {} : { bodyLimit: options.bodyLimit }),
+    });
+    const app = await (options.compile ?? defaultCompile)(root, adapter);
+    app.useLogger(app.get(NestPinoLogger));
+    const logger = app.get(KIT_LOGGER);
+    const closeServer = installServerHooks(app);
+    installLifecycle(app, closeServer, logger);
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+    logger.debug({ service: options.service, bodyLimit: options.bodyLimit ?? null }, 'http: приложение собрано');
+    return app;
+}
+/**
+ * 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 function createHttpApp(options) {
+    return buildHttpApp(options);
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,118 @@
+/** Запись словаря ошибок: HTTP-статус и текст по-русски. */
+export interface KitErrorEntry {
+    /** HTTP-статус ответа. */
+    readonly status: number;
+    /** Текст для пользователя по-русски. */
+    readonly message: string;
+}
+/** Словарь ошибок: код (SCREAMING_SNAKE) → статус и текст. */
+export type KitErrorDictionary = Readonly<Record<string, KitErrorEntry>>;
+/** Общие коды пакета (§3.5); сервис дополняет их своими через `defineErrors({...kitErrors, …})`. */
+export declare const kitErrors: {
+    readonly UNAUTHENTICATED: {
+        readonly status: 401;
+        readonly message: "Требуется вход";
+    };
+    readonly FORBIDDEN: {
+        readonly status: 403;
+        readonly message: "Доступ запрещён";
+    };
+    readonly VALIDATION_FAILED: {
+        readonly status: 422;
+        readonly message: "Некорректные данные запроса";
+    };
+    readonly BAD_REQUEST: {
+        readonly status: 400;
+        readonly message: "Некорректный запрос";
+    };
+    readonly PAYLOAD_TOO_LARGE: {
+        readonly status: 413;
+        readonly message: "Слишком большой запрос";
+    };
+    readonly UNSUPPORTED_MEDIA_TYPE: {
+        readonly status: 415;
+        readonly message: "Неподдерживаемый формат запроса";
+    };
+    readonly ROUTE_NOT_FOUND: {
+        readonly status: 404;
+        readonly message: "Адрес не найден";
+    };
+    readonly VERSION_CONFLICT: {
+        readonly status: 409;
+        readonly message: "Данные изменились в другом окне. Обновите страницу.";
+    };
+    readonly RATE_LIMITED: {
+        readonly status: 429;
+        readonly message: "Слишком много запросов. Повторите позже.";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly status: 500;
+        readonly message: "Внутренняя ошибка сервиса";
+    };
+    readonly SERVICE_UNAVAILABLE: {
+        readonly status: 503;
+        readonly message: "Сервис временно недоступен. Повторите попытку позже.";
+    };
+    readonly SERVICE_STOPPING: {
+        readonly status: 503;
+        readonly message: "Сервис перезапускается. Повторите через несколько секунд.";
+    };
+    readonly PLATFORM_UNAVAILABLE: {
+        readonly status: 503;
+        readonly message: "Сервис прав временно недоступен. Повторите позже";
+    };
+    readonly IDEMPOTENCY_KEY_REUSED: {
+        readonly status: 422;
+        readonly message: "Ключ Idempotency-Key уже использован с другим запросом.";
+    };
+    readonly IDEMPOTENCY_IN_PROGRESS: {
+        readonly status: 409;
+        readonly message: "Запрос с этим ключом ещё выполняется.";
+    };
+    readonly IDEMPOTENCY_KEY_REQUIRED: {
+        readonly status: 400;
+        readonly message: "Нужен заголовок Idempotency-Key.";
+    };
+};
+/** Коды пакета в словаре сервиса сохраняют свой статус: иначе свойство — `never` и ошибка компиляции (AC-3.2). */
+type KitCodesKeepStatus<D> = {
+    readonly [K in keyof D & keyof typeof kitErrors]: D[K] extends {
+        readonly status: (typeof kitErrors)[K]['status'];
+    } ? unknown : never;
+};
+/**
+ * Регистрирует словарь ошибок сервиса на процесс (§3.5). Повторный вызов объединяет словари; тот же код с другим
+ * статусом — `Error` при определении (ошибка разработчика), код пакета с другим статусом — ошибка компиляции.
+ * Возвращает тот же словарь.
+ */
+export declare function defineErrors<const D extends KitErrorDictionary>(dict: D & KitCodesKeepStatus<D>): D;
+/** Текст кода по-русски; неизвестный код — «Ошибка запроса». Внутренняя функция. */
+export declare function errorMessage(code: string): string;
+/** Статус кода из реестра; `undefined` — код не зарегистрирован. Внутренняя функция. */
+export declare function errorStatus(code: string): number | undefined;
+/** Тело ответа ошибки (§3.5). */
+interface ErrorBody {
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Ожидаемая ошибка домена (§3.5): статус и текст — из словаря `defineErrors`, `warn` без GlitchTip. Незарегистрированный
+ * код — ошибка разработчика: статус 500, фильтр отвечает `INTERNAL_ERROR` и отправляет событие. `options.cause` —
+ * исходная ошибка (например, срок пула БД). Заголовков нет; `Retry-After` для `RATE_LIMITED` ставит `KitExceptionFilter` по
+ * `details.retryAfterSec`.
+ */
+export declare class DomainError extends Error {
+    /** Код ошибки (SCREAMING_SNAKE). */
+    readonly code: string;
+    /** HTTP-статус из словаря; незарегистрированный код — 500. */
+    readonly status: number;
+    /** Подробности без секретов и ПДн; по умолчанию `{}`. */
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
+    /** Тело ответа `{error: {code, message, details}}`. */
+    toBody(): ErrorBody;
+}
+export {};

package/dist/http/errors.js

@@ -0,0 +1,94 @@
+// kitErrors, defineErrors, DomainError (prd.md §3.5, AC-3.2, AC-3.3). Эталон — O domain-error.ts + error-messages.ts (тело
+// {error: {code, message, details}}, name = new.target.name, общий текст «Ошибка запроса»). По PRD: запись словаря
+// {status, message}, реестр на процесс (как registerErrorSanitizer), статус берётся из словаря, коды §3.5; заголовков в
+// DomainError нет; Retry-After для RATE_LIMITED ставит KitExceptionFilter по details.retryAfterSec (E8, §3.7), третий аргумент — стандартный {cause}. Тексты — O error-messages.ts и guard
+// @verdeect/auth.
+/** Общие коды пакета (§3.5); сервис дополняет их своими через `defineErrors({...kitErrors, …})`. */
+export const kitErrors = {
+    UNAUTHENTICATED: { status: 401, message: 'Требуется вход' },
+    FORBIDDEN: { status: 403, message: 'Доступ запрещён' },
+    VALIDATION_FAILED: { status: 422, message: 'Некорректные данные запроса' },
+    BAD_REQUEST: { status: 400, message: 'Некорректный запрос' },
+    PAYLOAD_TOO_LARGE: { status: 413, message: 'Слишком большой запрос' },
+    UNSUPPORTED_MEDIA_TYPE: { status: 415, message: 'Неподдерживаемый формат запроса' },
+    ROUTE_NOT_FOUND: { status: 404, message: 'Адрес не найден' },
+    VERSION_CONFLICT: {
+        status: 409,
+        message: 'Данные изменились в другом окне. Обновите страницу.',
+    },
+    RATE_LIMITED: { status: 429, message: 'Слишком много запросов. Повторите позже.' },
+    INTERNAL_ERROR: { status: 500, message: 'Внутренняя ошибка сервиса' },
+    SERVICE_UNAVAILABLE: {
+        status: 503,
+        message: 'Сервис временно недоступен. Повторите попытку позже.',
+    },
+    SERVICE_STOPPING: {
+        status: 503,
+        message: 'Сервис перезапускается. Повторите через несколько секунд.',
+    },
+    PLATFORM_UNAVAILABLE: {
+        status: 503,
+        message: 'Сервис прав временно недоступен. Повторите позже',
+    },
+    IDEMPOTENCY_KEY_REUSED: {
+        status: 422,
+        message: 'Ключ Idempotency-Key уже использован с другим запросом.',
+    },
+    IDEMPOTENCY_IN_PROGRESS: { status: 409, message: 'Запрос с этим ключом ещё выполняется.' },
+    IDEMPOTENCY_KEY_REQUIRED: { status: 400, message: 'Нужен заголовок Idempotency-Key.' },
+};
+/** Общий текст неизвестного кода (O error-messages.ts FALLBACK_MESSAGE). */
+const FALLBACK_MESSAGE = 'Ошибка запроса';
+/** Реестр кодов процесса; `kitErrors` зарегистрирован всегда. */
+const registry = new Map(Object.entries(kitErrors));
+/**
+ * Регистрирует словарь ошибок сервиса на процесс (§3.5). Повторный вызов объединяет словари; тот же код с другим
+ * статусом — `Error` при определении (ошибка разработчика), код пакета с другим статусом — ошибка компиляции.
+ * Возвращает тот же словарь.
+ */
+export function defineErrors(dict) {
+    const entries = Object.entries(dict);
+    for (const [code, entry] of entries) {
+        const known = registry.get(code);
+        if (known !== undefined && known.status !== entry.status) {
+            throw new Error(`defineErrors: код ${code} уже зарегистрирован со статусом ${known.status}, а не ${entry.status}`);
+        }
+    }
+    for (const [code, entry] of entries) {
+        registry.set(code, { status: entry.status, message: entry.message });
+    }
+    return dict;
+}
+/** Текст кода по-русски; неизвестный код — «Ошибка запроса». Внутренняя функция. */
+export function errorMessage(code) {
+    return registry.get(code)?.message ?? FALLBACK_MESSAGE;
+}
+/** Статус кода из реестра; `undefined` — код не зарегистрирован. Внутренняя функция. */
+export function errorStatus(code) {
+    return registry.get(code)?.status;
+}
+/**
+ * Ожидаемая ошибка домена (§3.5): статус и текст — из словаря `defineErrors`, `warn` без GlitchTip. Незарегистрированный
+ * код — ошибка разработчика: статус 500, фильтр отвечает `INTERNAL_ERROR` и отправляет событие. `options.cause` —
+ * исходная ошибка (например, срок пула БД). Заголовков нет; `Retry-After` для `RATE_LIMITED` ставит `KitExceptionFilter` по
+ * `details.retryAfterSec`.
+ */
+export class DomainError extends Error {
+    /** Код ошибки (SCREAMING_SNAKE). */
+    code;
+    /** HTTP-статус из словаря; незарегистрированный код — 500. */
+    status;
+    /** Подробности без секретов и ПДн; по умолчанию `{}`. */
+    details;
+    constructor(code, details, options) {
+        super(errorMessage(code), options);
+        this.name = new.target.name;
+        this.code = code;
+        this.status = errorStatus(code) ?? 500;
+        this.details = details ?? {};
+    }
+    /** Тело ответа `{error: {code, message, details}}`. */
+    toBody() {
+        return { error: { code: this.code, message: this.message, details: this.details } };
+    }
+}

package/dist/http/index.d.ts

@@ -0,0 +1,12 @@
+export { bootstrapService } from './bootstrap-service.js';
+export type { KitBootstrapOptions } from './bootstrap-service.js';
+export { createHttpApp } from './create-http-app.js';
+export type { KitHttpAppOptions } from './create-http-app.js';
+export { defineErrors, DomainError, kitErrors } from './errors.js';
+export type { KitErrorDictionary, KitErrorEntry } from './errors.js';
+export { KitExceptionFilter } from './kit-exception.filter.js';
+export { afterCursor, decodeCursor, encodeCursor, pageOf, PageQuerySchema } from './pagination.js';
+export type { Page } from './pagination.js';
+export { ZodValidationPipe } from './zod-validation.pipe.js';
+export { Api } from './api/api.decorator.js';
+export type { KitApiOptions } from './api/api.decorator.js';

package/dist/http/index.js

@@ -0,0 +1,8 @@
+// Публичная поверхность @verdeect/kit/http (prd.md §3.5). Всё, что не перечислено, — не экспортируется.
+export { bootstrapService } from './bootstrap-service.js';
+export { createHttpApp } from './create-http-app.js';
+export { defineErrors, DomainError, kitErrors } from './errors.js';
+export { KitExceptionFilter } from './kit-exception.filter.js';
+export { afterCursor, decodeCursor, encodeCursor, pageOf, PageQuerySchema } from './pagination.js';
+export { ZodValidationPipe } from './zod-validation.pipe.js';
+export { Api } from './api/api.decorator.js';

package/dist/http/kit-exception.filter.d.ts

@@ -0,0 +1,18 @@
+import { type ArgumentsHost, type ExceptionFilter } from '@nestjs/common';
+/**
+ * Фильтр ошибок HTTP сервиса (§3.5). `DomainError` — статус словаря, `warn`, без GlitchTip (`RATE_LIMITED` с
+ * `details.retryAfterSec` — ещё `Retry-After`, §3.7); тело `{error}` guard'ов —
+ * без изменений; срок пула БД (в том числе в `cause`) — 503 `SERVICE_UNAVAILABLE` + `Retry-After: 1` (метрику и событие
+ * пишет пул /database, AC-4.5); `HttpException` без тела 400/401/403/404/413/415/429 — код по статусу, `warn`; прочее —
+ * 500 `INTERNAL_ERROR`, `error`, GlitchTip ровно раз. Текст исходной ошибки, стек и SQL в ответ не попадают.
+ * `createHttpApp` регистрирует фильтр сам; BFF собирает свой фильтр на `DomainError` и словаре (различие по роли).
+ */
+export declare class KitExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    /** Отвечает на исключение запроса по правилам §3.5. */
+    catch(exception: unknown, host: ArgumentsHost): void;
+    private handleHttpException;
+    private warn;
+    private reportUnexpected;
+    private send;
+}

package/dist/http/kit-exception.filter.js

@@ -0,0 +1,151 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var KitExceptionFilter_1;
+// KitExceptionFilter (prd.md §3.5, AC-3.1–AC-3.4; KT-15 п. 7–8): единый ответ {error: {code, message, details}}.
+// Эталон — O app-exception-filter.ts: порядок веток, libraryBody, send() с Content-Type: application/json; charset=utf-8,
+// reportUnexpected. Из B: ответ после отправленных заголовков — только warn. По PRD: коды HttpException без тела — таблица
+// HTTP_CODES (прочие статусы → 500 INTERNAL_ERROR), DomainError с незарегистрированным кодом → 500, срок пула —
+// isPoolTimeout по форме, 503 без метрики и события: метрику и событие срока пула пишет пул /database (AC-4.5, KT-19
+// п. 3); Retry-After RATE_LIMITED — по details.retryAfterSec (E8, §3.7); codeOf с путями O, maskSecretPath и instance-shutdown не
+// переносятся, путь в лог не пишется (он уже есть в строке доступа).
+import { Catch, HttpException, Injectable, Logger, } from '@nestjs/common';
+import { isPoolTimeout } from '../internal/pg-errors.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError } from '../observability/sentry.js';
+import { DomainError, errorMessage, errorStatus } from './errors.js';
+/** Код ответа HttpException без своего тела (Nest FastifyAdapter.mapException: FastifyError → HttpException). */
+const HTTP_CODES = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHENTICATED',
+    403: 'FORBIDDEN',
+    404: 'ROUTE_NOT_FOUND',
+    413: 'PAYLOAD_TOO_LARGE',
+    415: 'UNSUPPORTED_MEDIA_TYPE',
+    429: 'RATE_LIMITED',
+};
+/** Коды библиотек при 5xx — ожидаемая недоступность зависимости (эталон O). */
+const EXPECTED_UNAVAILABLE_CODES = new Set(['PLATFORM_UNAVAILABLE']);
+/** `Retry-After` при сроке пула БД (эталон O POOL_RETRY_AFTER). */
+const POOL_RETRY_AFTER = '1';
+/** `Retry-After` для `RATE_LIMITED` — целое `details.retryAfterSec ≥ 1` (§3.7, `throwRateLimited`, E8). */
+function rateLimitRetryAfter(error) {
+    if (error.code !== 'RATE_LIMITED') {
+        return undefined;
+    }
+    const value = error.details.retryAfterSec;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        return undefined;
+    }
+    return value;
+}
+function bodyOf(code) {
+    return { error: { code, message: errorMessage(code), details: {} } };
+}
+/** Тело HttpException уже в формате §3.5 (guard'ы @verdeect/auth, @verdeect/platform-client). */
+function libraryBody(response) {
+    if (typeof response !== 'object' || response === null || !('error' in response)) {
+        return null;
+    }
+    const error = response.error;
+    if (typeof error !== 'object' || error === null) {
+        return null;
+    }
+    const { code, message, details } = error;
+    if (typeof code !== 'string' || typeof message !== 'string') {
+        return null;
+    }
+    if (typeof details !== 'object' || details === null) {
+        return null;
+    }
+    return { error: { code, message, details } };
+}
+/**
+ * Фильтр ошибок HTTP сервиса (§3.5). `DomainError` — статус словаря, `warn`, без GlitchTip (`RATE_LIMITED` с
+ * `details.retryAfterSec` — ещё `Retry-After`, §3.7); тело `{error}` guard'ов —
+ * без изменений; срок пула БД (в том числе в `cause`) — 503 `SERVICE_UNAVAILABLE` + `Retry-After: 1` (метрику и событие
+ * пишет пул /database, AC-4.5); `HttpException` без тела 400/401/403/404/413/415/429 — код по статусу, `warn`; прочее —
+ * 500 `INTERNAL_ERROR`, `error`, GlitchTip ровно раз. Текст исходной ошибки, стек и SQL в ответ не попадают.
+ * `createHttpApp` регистрирует фильтр сам; BFF собирает свой фильтр на `DomainError` и словаре (различие по роли).
+ */
+let KitExceptionFilter = KitExceptionFilter_1 = class KitExceptionFilter {
+    logger = new Logger(KitExceptionFilter_1.name);
+    /** Отвечает на исключение запроса по правилам §3.5. */
+    catch(exception, host) {
+        const http = host.switchToHttp();
+        const reply = http.getResponse();
+        const request = http.getRequest();
+        if (reply.raw.headersSent) {
+            this.logger.warn({ method: request.method, traceId: request.id, err: sanitizeError(exception) }, 'ошибка после отправки заголовков ответа');
+            return;
+        }
+        // Срок пула — первой веткой: он может быть в cause DomainError (эталон O).
+        if (isPoolTimeout(exception)) {
+            // Метрику и событие ставит пул /database (KT-19 п. 3); срок своего пула сервиса — 503 без метрики.
+            this.warn('SERVICE_UNAVAILABLE', 503, request);
+            void reply.header('Retry-After', POOL_RETRY_AFTER);
+            this.send(reply, 503, bodyOf('SERVICE_UNAVAILABLE'));
+            return;
+        }
+        if (exception instanceof DomainError && errorStatus(exception.code) !== undefined) {
+            this.warn(exception.code, exception.status, request);
+            const retryAfterSec = rateLimitRetryAfter(exception);
+            if (retryAfterSec !== undefined) {
+                void reply.header('Retry-After', String(retryAfterSec));
+            }
+            this.send(reply, exception.status, exception.toBody());
+            return;
+        }
+        if (exception instanceof HttpException) {
+            this.handleHttpException(exception, reply, request);
+            return;
+        }
+        this.reportUnexpected(exception, request);
+        this.send(reply, 500, bodyOf('INTERNAL_ERROR'));
+    }
+    handleHttpException(exception, reply, request) {
+        const status = exception.getStatus();
+        const library = libraryBody(exception.getResponse());
+        if (library !== null) {
+            if (status < 500 || EXPECTED_UNAVAILABLE_CODES.has(library.error.code)) {
+                this.warn(library.error.code, status, request);
+            }
+            else {
+                this.reportUnexpected(exception, request);
+            }
+            this.send(reply, status, library);
+            return;
+        }
+        const code = HTTP_CODES[status];
+        if (code === undefined) {
+            // Прочие 4xx и ≥ 500 без тела — ошибка разработчика: доменные 4xx — только DomainError (KT-15 п. 8).
+            this.reportUnexpected(exception, request);
+            this.send(reply, 500, bodyOf('INTERNAL_ERROR'));
+            return;
+        }
+        this.warn(code, status, request);
+        this.send(reply, status, bodyOf(code));
+    }
+    warn(code, status, request) {
+        this.logger.warn({ code, status, method: request.method, traceId: request.id }, 'ожидаемая ошибка запроса');
+    }
+    reportUnexpected(exception, request) {
+        captureError(exception, { tags: { code: 'INTERNAL_ERROR' } });
+        // Тело запроса, заголовки и путь не логируются.
+        this.logger.error({ err: sanitizeError(exception), method: request.method, traceId: request.id }, 'неожиданная ошибка запроса');
+    }
+    send(reply, status, payload) {
+        void reply
+            .status(status)
+            .header('Content-Type', 'application/json; charset=utf-8')
+            .send(payload);
+    }
+};
+KitExceptionFilter = KitExceptionFilter_1 = __decorate([
+    Catch(),
+    Injectable()
+], KitExceptionFilter);
+export { KitExceptionFilter };

package/dist/http/kit-http-core.module.d.ts

@@ -0,0 +1,19 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type KitLoggerOptions } from '../observability/logger-options.js';
+import type { KitRedaction } from '../observability/redaction.js';
+/** Опции логгера по роли сервиса (§3.5). */
+export type KitHttpLoggerOptions = Pick<KitLoggerOptions, 'trustTraceparent' | 'quietRoutes' | 'extraBase'>;
+/** Опции ядра HTTP. */
+export interface KitHttpCoreOptions {
+    /** Имя сервиса (уже проверено вызывающим). */
+    readonly service: string;
+    /** Опции логгера по роли сервиса. */
+    readonly logger?: KitHttpLoggerOptions;
+    /** Правила редактирования сервиса. */
+    readonly redaction?: KitRedaction;
+}
+/** Внутренний глобальный модуль ядра; подключает его `createHttpApp`. */
+export declare class KitHttpCoreModule {
+    /** Ядро одного экземпляра приложения; экспортирует KitLifecycle, HealthRegistry, KIT_METRICS, KIT_LOGGER. */
+    static forRoot(options: KitHttpCoreOptions): DynamicModule;
+}