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

package/dist/observability/health-registry.js

@@ -0,0 +1,81 @@
+import { sanitizeError } from './sanitize-error.js';
+/** Срок пробы (§3.2). */
+export const PROBE_TIMEOUT_MS = 2000;
+/** Реестр проб готовности; один на экземпляр приложения. */
+export class HealthRegistry {
+    logger;
+    probes = new Map();
+    lastState = new Map();
+    stopping = false;
+    constructor(options) {
+        this.logger = options.logger;
+    }
+    /** Регистрирует пробу; повторная регистрация имени заменяет прежнюю. */
+    register(name, probe, options) {
+        this.probes.set(name, { critical: options.critical, probe });
+    }
+    /** Шаг 1 остановки: с этого момента `evaluate` — `unavailable` без запуска проб. */
+    markStopping() {
+        this.stopping = true;
+    }
+    /** Идёт ли остановка. */
+    get isStopping() {
+        return this.stopping;
+    }
+    /** Запускает пробы параллельно и сводит статус; при остановке — `unavailable` без проб. */
+    async evaluate() {
+        if (this.stopping) {
+            return { status: 'unavailable', checks: {} };
+        }
+        const results = await Promise.all([...this.probes.entries()].map(async ([name, { critical, probe }]) => {
+            const result = await runProbe(probe);
+            this.trackState(name, critical, result);
+            return { name, critical, up: result.up };
+        }));
+        const checks = {};
+        for (const result of results) {
+            checks[result.name] = result.up ? 'up' : 'down';
+        }
+        const down = results.filter((result) => !result.up);
+        if (down.some((result) => result.critical)) {
+            return { status: 'unavailable', checks };
+        }
+        return { status: down.length > 0 ? 'degraded' : 'ok', checks };
+    }
+    /** Лог только при смене состояния: up → down (и первый down) — warn, down → up — info. */
+    trackState(name, critical, result) {
+        const previous = this.lastState.get(name);
+        const current = result.up ? 'up' : 'down';
+        this.lastState.set(name, current);
+        if (previous === current) {
+            return;
+        }
+        if (current === 'down') {
+            this.logger.warn({
+                check: name,
+                critical,
+                ...(result.error === undefined ? {} : { err: sanitizeError(result.error) }),
+            }, 'проба здоровья: down');
+            return;
+        }
+        if (previous === 'down') {
+            this.logger.info({ check: name }, 'проба здоровья: up');
+        }
+    }
+}
+/** Проба в гонке со сроком; таймер снимается после ответа. */
+async function runProbe(probe) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ up: false }), PROBE_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([probe().then((up) => ({ up: up === true })), timeout]);
+    }
+    catch (error) {
+        return { up: false, error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,16 @@
+export { failStartup } from './fail-startup.js';
+export type { StartupFailure } from './fail-startup.js';
+export { HealthRegistry } from './health-registry.js';
+export type { HealthProbe, HealthReport } from './health-registry.js';
+export { KitLifecycle } from './lifecycle.js';
+export type { KitShutdownParticipant, KitShutdownStep } from './lifecycle.js';
+export { createLoggerOptions } from './logger-options.js';
+export type { KitLoggerOptions, KitLoggerParams } from './logger-options.js';
+export { MetricsServer } from './metrics-server.js';
+export { alertRulesTemplate, kitMetrics } from './metrics.js';
+export type { KitMetrics } from './metrics.js';
+export { SENSITIVE_KEYS } from './redaction.js';
+export type { KitRedaction } from './redaction.js';
+export { registerErrorSanitizer, sanitizeError } from './sanitize-error.js';
+export { captureError, captureThrottled, initSentry } from './sentry.js';
+export type { KitSentryOptions } from './sentry.js';

package/dist/observability/index.js

@@ -0,0 +1,10 @@
+// Публичная поверхность @verdeect/kit/observability (prd.md §3.2). Всё, что не перечислено, — не экспортируется.
+export { failStartup } from './fail-startup.js';
+export { HealthRegistry } from './health-registry.js';
+export { KitLifecycle } from './lifecycle.js';
+export { createLoggerOptions } from './logger-options.js';
+export { MetricsServer } from './metrics-server.js';
+export { alertRulesTemplate, kitMetrics } from './metrics.js';
+export { SENSITIVE_KEYS } from './redaction.js';
+export { registerErrorSanitizer, sanitizeError } from './sanitize-error.js';
+export { captureError, captureThrottled, initSentry } from './sentry.js';

package/dist/observability/lifecycle.d.ts

@@ -0,0 +1,52 @@
+import type { Logger } from 'pino';
+import type { KitBaseEnv } from '../config/fragments.js';
+import type { HealthRegistry } from './health-registry.js';
+/** Шаг участника (§3.2): 2 — приём соединений, 3 — подписчики и фоновые задачи, 4 — пулы, 5 — сервер метрик. */
+export type KitShutdownStep = 2 | 3 | 4 | 5;
+/** Участник остановки: участники одного шага работают параллельно. */
+export interface KitShutdownParticipant {
+    /** Имя для логов и сторожа. */
+    readonly name: string;
+    /** Останавливает участника; ошибка логируется, остальные шаги выполняются. */
+    stop(): Promise<void> | void;
+}
+/** Остановка экземпляра приложения по шагам 1–5 (§3.2). Остановка одна на экземпляр. */
+export declare class KitLifecycle {
+    private readonly logger;
+    private readonly health;
+    private readonly timeoutMs;
+    private readonly drainMs;
+    private readonly participants;
+    private steps;
+    private closing;
+    private watchdog;
+    private finished;
+    private currentStep;
+    private readonly pending;
+    constructor(options: {
+        readonly logger: Logger;
+        readonly health: HealthRegistry;
+        readonly env: Pick<KitBaseEnv, 'SHUTDOWN_TIMEOUT_MS' | 'SHUTDOWN_DRAIN_MS'>;
+    });
+    /** Регистрирует участника шага; после начала остановки — ошибка разработчика. */
+    register(participant: KitShutdownParticipant, options: {
+        readonly step: KitShutdownStep;
+    }): void;
+    /**
+     * Остановка по сигналу ОС (умолч. SIGTERM, SIGINT): сторож срока, ошибки участников — `error` и GlitchTip.
+     * Обработчик остаётся (`process.on`): повторный сигнал не включает действие Node по умолчанию посреди шагов.
+     */
+    listen(signals?: readonly NodeJS.Signals[]): void;
+    /**
+     * Программное закрытие (тесты сервиса, CLI): шаги 1–5 без сторожа и `exit`. Ошибка участника — отказ после
+     * всех шагов (несколько — `AggregateError`). Повторный вызов возвращает тот же промис.
+     */
+    close(): Promise<void>;
+    private onSignal;
+    private start;
+    private run;
+    private runStep;
+    private stopParticipant;
+    /** Сторож: шаги не уложились в срок или процесс не вышел после них — error, GlitchTip, exit(1). */
+    private onDeadline;
+}

package/dist/observability/lifecycle.js

@@ -0,0 +1,151 @@
+// KitLifecycle — участники остановки и сторож срока (prd.md §3.2 шаги 1–5, AC-2.10, AC-2.13, UC-8, NFR-8; KT-10, KT-11).
+// Эталоны: общий срок от первого вызова — P/O RabbitConnection.shutdownDeadline(); флаг остановки первым действием —
+// O instance-shutdown.ts begin(). Механизм шагов и сторож с exit(1) написаны по PRD: эталона нет.
+// Два режима (KT-11): сигнал ОС (listen) — сторож SHUTDOWN_TIMEOUT_MS от сигнала, по окончании шагов сторож unref и
+// выход 0 сам; программный close() — те же шаги без сторожа и exit, ошибки участников — отказ close().
+import * as Sentry from '@sentry/nestjs';
+import { sanitizeError } from './sanitize-error.js';
+import { captureError } from './sentry.js';
+const STEPS = [2, 3, 4, 5];
+const DEFAULT_SIGNALS = ['SIGTERM', 'SIGINT'];
+const SENTRY_FLUSH_MS = 2000;
+/** Остановка экземпляра приложения по шагам 1–5 (§3.2). Остановка одна на экземпляр. */
+export class KitLifecycle {
+    logger;
+    health;
+    timeoutMs;
+    drainMs;
+    participants = new Map();
+    steps = null;
+    closing = null;
+    watchdog = null;
+    finished = false;
+    currentStep = 1;
+    pending = new Set();
+    constructor(options) {
+        this.logger = options.logger;
+        this.health = options.health;
+        this.timeoutMs = options.env.SHUTDOWN_TIMEOUT_MS;
+        this.drainMs = options.env.SHUTDOWN_DRAIN_MS;
+    }
+    /** Регистрирует участника шага; после начала остановки — ошибка разработчика. */
+    register(participant, options) {
+        if (this.steps !== null) {
+            throw new Error('KitLifecycle: регистрация после начала остановки');
+        }
+        const list = this.participants.get(options.step) ?? [];
+        list.push(participant);
+        this.participants.set(options.step, list);
+    }
+    /**
+     * Остановка по сигналу ОС (умолч. SIGTERM, SIGINT): сторож срока, ошибки участников — `error` и GlitchTip.
+     * Обработчик остаётся (`process.on`): повторный сигнал не включает действие Node по умолчанию посреди шагов.
+     */
+    listen(signals = DEFAULT_SIGNALS) {
+        for (const signal of signals) {
+            process.on(signal, () => this.onSignal(signal));
+        }
+    }
+    /**
+     * Программное закрытие (тесты сервиса, CLI): шаги 1–5 без сторожа и `exit`. Ошибка участника — отказ после
+     * всех шагов (несколько — `AggregateError`). Повторный вызов возвращает тот же промис.
+     */
+    close() {
+        this.closing ??= this.start({ mode: 'close' }).then(throwFailures);
+        return this.closing;
+    }
+    onSignal(signal) {
+        if (this.watchdog !== null) {
+            return;
+        }
+        // t0 — сигнал: сторож взводится до шагов, пауза входит в срок (CE-7).
+        this.watchdog = setTimeout(() => void this.onDeadline(), this.timeoutMs);
+        void this.start({ signal }).then(() => {
+            // Шаги завершены: процесс без открытых дескрипторов выходит сам с кодом 0 (KT-10 п. 4).
+            this.watchdog?.unref();
+        });
+    }
+    start(context) {
+        this.steps ??= this.run(context);
+        return this.steps;
+    }
+    async run(context) {
+        const startedAt = performance.now();
+        const failures = [];
+        this.logger.info(context, 'остановка: начало');
+        // Шаг 1: /health 503 и пауза SHUTDOWN_DRAIN_MS — балансировщик выводит реплику.
+        this.health.markStopping();
+        if (this.drainMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this.drainMs));
+        }
+        // Шаги 2–5: участники шага параллельно, следующий шаг — после завершения предыдущего.
+        for (const step of STEPS) {
+            await this.runStep(step, failures);
+        }
+        this.finished = true;
+        this.logger.info({ durationMs: elapsed(startedAt) }, 'остановка: завершена');
+        return failures;
+    }
+    async runStep(step, failures) {
+        const list = this.participants.get(step) ?? [];
+        const startedAt = performance.now();
+        this.currentStep = step;
+        for (const participant of list) {
+            this.pending.add(participant.name);
+        }
+        this.logger.debug({ step, participants: list.map((participant) => participant.name) }, 'остановка: шаг начат');
+        await Promise.allSettled(list.map((participant) => this.stopParticipant(step, participant, failures)));
+        this.logger.debug({ step, durationMs: elapsed(startedAt) }, 'остановка: шаг завершён');
+    }
+    async stopParticipant(step, participant, failures) {
+        const startedAt = performance.now();
+        try {
+            await participant.stop();
+            this.logger.debug({ step, participant: participant.name, durationMs: elapsed(startedAt) }, 'остановка: участник завершён');
+        }
+        catch (error) {
+            failures.push(error);
+            this.logger.error({ step, participant: participant.name, err: sanitizeError(error) }, 'остановка: участник завершился с ошибкой');
+            if (this.watchdog !== null) {
+                captureError(error, { tags: { code: 'SHUTDOWN_PARTICIPANT_FAILED' } });
+            }
+        }
+        finally {
+            this.pending.delete(participant.name);
+        }
+    }
+    /** Сторож: шаги не уложились в срок или процесс не вышел после них — error, GlitchTip, exit(1). */
+    async onDeadline() {
+        if (this.finished) {
+            this.logger.error({ code: 'SHUTDOWN_NOT_EXITED', timeoutMs: this.timeoutMs }, 'процесс не завершился после остановки');
+            captureError(new Error('Процесс не завершился после остановки'), {
+                tags: { code: 'SHUTDOWN_NOT_EXITED' },
+            });
+        }
+        else {
+            this.logger.error({
+                code: 'SHUTDOWN_TIMEOUT',
+                step: this.currentStep,
+                pending: [...this.pending],
+                timeoutMs: this.timeoutMs,
+            }, 'срок остановки истёк');
+            captureError(new Error('Срок остановки истёк'), {
+                tags: { code: 'SHUTDOWN_TIMEOUT' },
+            });
+        }
+        await Sentry.flush(SENTRY_FLUSH_MS);
+        process.exit(1);
+    }
+}
+function elapsed(startedAt) {
+    return Math.round(performance.now() - startedAt);
+}
+/** Отказ close(): одна ошибка — она сама, несколько — AggregateError. */
+function throwFailures(failures) {
+    if (failures.length === 1) {
+        throw failures[0];
+    }
+    if (failures.length > 1) {
+        throw new AggregateError(failures, 'KitLifecycle: участники остановки завершились с ошибкой');
+    }
+}

package/dist/observability/logger-options.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage } from 'node:http';
+import type { Params } from 'nestjs-pino';
+import type { DestinationStream } from 'pino';
+import type { KitBaseEnv } from '../config/fragments.js';
+import { type KitRedaction } from './redaction.js';
+/** Опции `createLoggerOptions` (§3.2). */
+export interface KitLoggerOptions {
+    /** Имя сервиса (`^[a-z][a-z0-9-]{1,31}$`) — поле `service` каждой строки. */
+    readonly service: string;
+    /** Точка входа: `http` — stdout и журнал доступа, `cli` — stderr без журнала доступа. */
+    readonly entry: 'http' | 'cli';
+    /** Разобранные ключи окружения: уровень лога и имя реплики (§3.1). */
+    readonly env: Pick<KitBaseEnv, 'REPLICA_ID' | 'LOG_LEVEL'>;
+    /** `false` — входящий `traceparent` игнорируется, trace-id всегда новый (роль BFF); по умолчанию — доверять. */
+    readonly trustTraceparent?: boolean;
+    /** Префиксы пути: успешный ответ пишется на `debug`, ошибка и статус ≥ 400 — как обычно. */
+    readonly quietRoutes?: readonly string[];
+    /** Дополнительные поля `base`. */
+    readonly extraBase?: Readonly<Record<string, unknown>>;
+    /** Правила редактирования сервиса (общие с `initSentry`). */
+    readonly redaction?: KitRedaction;
+}
+type PinoHttpOptions = Extract<NonNullable<Params['pinoHttp']>, readonly unknown[]>[0];
+/**
+ * Генератор trace-id: читает только заголовки, поэтому подходит и pino-http (`(req, res) => ReqId`), и адаптеру
+ * Fastify (`(req: IncomingMessage | Http2ServerRequest) => string`).
+ */
+type TraceIdGenerator = (req: Pick<IncomingMessage, 'headers'>) => string;
+/**
+ * Результат `createLoggerOptions`: `Params` nestjs-pino с кортежем `[options, stream]`. Логгер вне Nest —
+ * `pino(...params.pinoHttp)`; генератор trace-id для адаптера — `params.pinoHttp[0].genReqId`.
+ */
+export type KitLoggerParams = Omit<Params, 'pinoHttp'> & {
+    /** Опции pino-http и поток: `process.stdout` (http) или `process.stderr` (cli). */
+    readonly pinoHttp: [
+        Omit<PinoHttpOptions, 'genReqId'> & {
+            genReqId: TraceIdGenerator;
+        },
+        DestinationStream
+    ];
+};
+/** trace-id из `traceparent` (если доверяем) или новый. Внутренняя: генератор адаптера Fastify в `createHttpApp`. */
+export declare function traceIdGenerator(trust: boolean): TraceIdGenerator;
+/**
+ * Опции nestjs-pino сервиса (§3.2): `base: {service, entry, replica}`, редактирование `SENSITIVE_KEYS` ∪
+ * `redaction.sensitiveKeys` на уровнях 0–2, `err` через `sanitizeError`, путь запроса без query и через `maskPath`,
+ * `traceId` в каждой строке запроса, `/ok` вне журнала доступа, `quietRoutes` — на `debug`.
+ *
+ * На Fastify `genReqId` из `pinoHttp` не вызывается: Fastify ставит свой `request.id`, а pino-http оставляет уже
+ * заданный (`req.id = req.id || genReqId(…)`). Поэтому HTTP-адаптер получает тот же генератор:
+ * `new FastifyAdapter({genReqId: params.pinoHttp[0].genReqId})` (так делает `createHttpApp`).
+ */
+export declare function createLoggerOptions(options: KitLoggerOptions): KitLoggerParams;
+export {};

package/dist/observability/logger-options.js

@@ -0,0 +1,91 @@
+// createLoggerOptions — опции nestjs-pino (prd.md §3.2, AC-2.1, AC-2.2, AC-2.12, NFR-4, NFR-8). Эталон — O
+// observability.module.ts (requestId, serializeRequest, pinoOptions, accessLogLevel, httpLoggerOptions, stdout/stderr);
+// trustTraceparent: false и trace-id 32 hex — B observability.module.ts (randomBytes(16)); quietRoutes — P accessLogLevel
+// (QUIET_ACCESS_PREFIX). Окружение передаёт вызывающий (KitBaseEnv §3.1), своего process.env здесь нет.
+import { randomBytes } from 'node:crypto';
+import { assertServiceName } from '../internal/service-name.js';
+import { maskPathOf, redactPaths } from './redaction.js';
+import { sanitizeLogObject, serializeError } from './sanitize-error.js';
+const TRACEPARENT = /^[\da-f]{2}-([\da-f]{32})-[\da-f]{16}-[\da-f]{2}$/;
+const HEALTHCHECK_PATH = '/ok';
+/** Путь без query. */
+function pathOf(url) {
+    return typeof url === 'string' ? (url.split('?', 1)[0] ?? '') : '';
+}
+/**
+ * Путь запроса в middleware: на Fastify middie на время middleware заменяет `req.url` путём относительно точки
+ * монтирования, исходный — в `originalUrl`.
+ */
+function requestPath(req) {
+    return pathOf(req.originalUrl ?? req.url);
+}
+/** Новый trace-id W3C: 32 hex. */
+function newTraceId() {
+    return randomBytes(16).toString('hex');
+}
+/** trace-id из `traceparent` (если доверяем) или новый. Внутренняя: генератор адаптера Fastify в `createHttpApp`. */
+export function traceIdGenerator(trust) {
+    return (req) => {
+        if (!trust) {
+            return newTraceId();
+        }
+        const header = req.headers.traceparent;
+        const match = typeof header === 'string' ? TRACEPARENT.exec(header.trim()) : null;
+        return match?.[1] ?? newTraceId();
+    };
+}
+/** Уровень строки доступа: ошибка или статус ≥ 400 → info; успешный ответ «тихого» маршрута → debug. */
+function accessLogLevel(quietRoutes) {
+    return (req, res, err) => {
+        if (err !== undefined || res.statusCode >= 400) {
+            return 'info';
+        }
+        const path = requestPath(req);
+        return quietRoutes.some((prefix) => path.startsWith(prefix)) ? 'debug' : 'info';
+    };
+}
+/**
+ * Опции nestjs-pino сервиса (§3.2): `base: {service, entry, replica}`, редактирование `SENSITIVE_KEYS` ∪
+ * `redaction.sensitiveKeys` на уровнях 0–2, `err` через `sanitizeError`, путь запроса без query и через `maskPath`,
+ * `traceId` в каждой строке запроса, `/ok` вне журнала доступа, `quietRoutes` — на `debug`.
+ *
+ * На Fastify `genReqId` из `pinoHttp` не вызывается: Fastify ставит свой `request.id`, а pino-http оставляет уже
+ * заданный (`req.id = req.id || genReqId(…)`). Поэтому HTTP-адаптер получает тот же генератор:
+ * `new FastifyAdapter({genReqId: params.pinoHttp[0].genReqId})` (так делает `createHttpApp`).
+ */
+export function createLoggerOptions(options) {
+    assertServiceName(options.service, 'createLoggerOptions');
+    const maskPath = maskPathOf(options.redaction);
+    const http = options.entry === 'http';
+    return {
+        pinoHttp: [
+            {
+                level: options.env.LOG_LEVEL,
+                base: {
+                    service: options.service,
+                    entry: options.entry,
+                    replica: options.env.REPLICA_ID,
+                    ...options.extraBase,
+                },
+                redact: { paths: redactPaths(options.redaction), censor: '[Filtered]' },
+                // formatters.log видит исходный err (с cause), сериализатор — уже сериализованный pino-http.
+                formatters: { log: sanitizeLogObject },
+                serializers: {
+                    err: serializeError,
+                    req: (req) => ({
+                        id: req.id,
+                        method: req.method,
+                        url: maskPath(pathOf(req.url)),
+                    }),
+                },
+                genReqId: traceIdGenerator(options.trustTraceparent !== false),
+                customProps: (req) => ({ traceId: req.id }),
+                customLogLevel: accessLogLevel(options.quietRoutes ?? []),
+                autoLogging: http
+                    ? { ignore: (req) => requestPath(req) === HEALTHCHECK_PATH }
+                    : false,
+            },
+            http ? process.stdout : process.stderr,
+        ],
+    };
+}

package/dist/observability/metrics-server.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from 'pino';
+import type { Registry } from '@prometheus-io/client';
+import type { HealthRegistry } from './health-registry.js';
+/** HTTP-сервер метрик и готовности; закрывается последним (шаг 5 `KitLifecycle`). */
+export declare class MetricsServer {
+    private readonly port;
+    private readonly registry;
+    private readonly health;
+    private readonly logger;
+    private server;
+    private closing;
+    /** Обработчики в работе: closeAllConnections рвёт сокет, но обработчик ещё может ждать пробу. */
+    private readonly inflight;
+    constructor(options: {
+        readonly port: number;
+        readonly registry: Registry;
+        readonly health: HealthRegistry;
+        readonly logger: Logger;
+    });
+    /**
+     * Начинает слушать `port` (0 — порт выбирает ОС); ошибка прослушивания — отказ (передать в `failStartup`).
+     * После `close()` — ошибка разработчика: закрытый сервер не перезапускается.
+     */
+    listen(): Promise<void>;
+    /** Фактический порт; `null` — сервер не слушает. */
+    address(): number | null;
+    /** Закрывает сервер и ждёт обработчики в работе; идемпотентен. */
+    close(): Promise<void>;
+    private closeServer;
+    private handle;
+    /** ok, degraded → 200; unavailable (в том числе с начала остановки) → 503. Тело — только статусы. */
+    private handleHealth;
+}

package/dist/observability/metrics-server.js

@@ -0,0 +1,108 @@
+// MetricsServer — /health и /metrics на METRICS_PORT (prd.md §3.2, AC-2.7, AC-2.8, UC-13). Эталон — O metrics-server.ts:
+// node:http вне Nest, учёт inflight, query отбрасывается, /health — JSON с cache-control: no-store, /metrics —
+// registry.metrics(), прочее — 404, закрытие closeAllConnections + close + ожидание inflight, address() для порта 0.
+// По PRD и KT-10: без Nest-хуков (закрытие — участник шага 5 KitLifecycle), флаг остановки — в HealthRegistry, ошибка
+// listen (EADDRINUSE) — отказ listen(), а не работа без метрик. Строк лога на запрос нет.
+import { createServer } from 'node:http';
+import { sanitizeError } from './sanitize-error.js';
+import { captureError } from './sentry.js';
+const HEALTH_HEADERS = {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+};
+const UNAVAILABLE = JSON.stringify({ status: 'unavailable', checks: {} });
+/** HTTP-сервер метрик и готовности; закрывается последним (шаг 5 `KitLifecycle`). */
+export class MetricsServer {
+    port;
+    registry;
+    health;
+    logger;
+    server = null;
+    closing = null;
+    /** Обработчики в работе: closeAllConnections рвёт сокет, но обработчик ещё может ждать пробу. */
+    inflight = new Set();
+    constructor(options) {
+        this.port = options.port;
+        this.registry = options.registry;
+        this.health = options.health;
+        this.logger = options.logger;
+    }
+    /**
+     * Начинает слушать `port` (0 — порт выбирает ОС); ошибка прослушивания — отказ (передать в `failStartup`).
+     * После `close()` — ошибка разработчика: закрытый сервер не перезапускается.
+     */
+    async listen() {
+        if (this.closing !== null) {
+            throw new Error('MetricsServer: listen() после close()');
+        }
+        const server = createServer((req, res) => {
+            const handling = this.handle(req, res).finally(() => this.inflight.delete(handling));
+            this.inflight.add(handling);
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(this.port, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        this.server = server;
+        this.logger.info({ port: this.address() }, 'сервер метрик слушает');
+    }
+    /** Фактический порт; `null` — сервер не слушает. */
+    address() {
+        const address = this.server?.address();
+        if (address === null || address === undefined || typeof address === 'string') {
+            return null;
+        }
+        return address.port;
+    }
+    /** Закрывает сервер и ждёт обработчики в работе; идемпотентен. */
+    close() {
+        this.closing ??= this.closeServer();
+        return this.closing;
+    }
+    async closeServer() {
+        const server = this.server;
+        if (server === null) {
+            return;
+        }
+        this.server = null;
+        server.closeAllConnections();
+        await new Promise((resolve) => server.close(() => resolve()));
+        await Promise.allSettled(this.inflight);
+        this.logger.debug('сервер метрик закрыт');
+    }
+    async handle(req, res) {
+        const path = (req.url ?? '').split('?', 1)[0];
+        if (req.method === 'GET' && path === '/health') {
+            await this.handleHealth(res);
+            return;
+        }
+        if (req.method !== 'GET' || path !== '/metrics') {
+            res.writeHead(404).end();
+            return;
+        }
+        try {
+            const body = await this.registry.metrics();
+            res.writeHead(200, { 'content-type': this.registry.contentType }).end(body);
+        }
+        catch (error) {
+            this.logger.error({ err: sanitizeError(error) }, 'сервер метрик: сбор метрик не удался');
+            captureError(error);
+            res.writeHead(500).end();
+        }
+    }
+    /** ok, degraded → 200; unavailable (в том числе с начала остановки) → 503. Тело — только статусы. */
+    async handleHealth(res) {
+        try {
+            const report = await this.health.evaluate();
+            res.writeHead(report.status === 'unavailable' ? 503 : 200, HEALTH_HEADERS).end(JSON.stringify(report));
+        }
+        catch (error) {
+            this.logger.error({ err: sanitizeError(error) }, 'сервер метрик: проверка здоровья не удалась');
+            captureError(error);
+            res.writeHead(503, HEALTH_HEADERS).end(UNAVAILABLE);
+        }
+    }
+}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,30 @@
+import { Counter, Gauge, Registry } from '@prometheus-io/client';
+/** Реестр и метрики пакета одного экземпляра приложения (§3.2). Метрики домена — `<service>_*`, вне пакета. */
+export interface KitMetrics {
+    /** Реестр экземпляра: метки `service`, метрики процесса Node и пакета. */
+    readonly registry: Registry;
+    /** `verdeect_outbox_pending` — неотправленные строки outbox. */
+    readonly outboxPending: Gauge;
+    /** `verdeect_outbox_lag_seconds` — возраст самой старой неотправленной строки. */
+    readonly outboxLagSeconds: Gauge;
+    /** `verdeect_events_consumed_total{type, result}`; result: handled | duplicate | retry | dlq. */
+    readonly eventsConsumed: Counter<'type' | 'result'>;
+    /** `verdeect_db_pool_wait_timeouts_total{pool}` — истёк срок ожидания клиента пула. */
+    readonly dbPoolWaitTimeouts: Counter<'pool'>;
+    /** `verdeect_rate_limit_unavailable_total` — лимитер без Redis (fail-open). */
+    readonly rateLimitUnavailable: Counter;
+    /**
+     * `verdeect_cleanup_runs_total{table, result}` — проходы фоновой очистки. `table` — имя таблицы без схемы, только
+     * таблицы пакета (`idempotency_key`; E5 — `outbox`, `inbox`); `result`: `ok` — проход завершён, `partial` — упёрся
+     * в `maxBatches`, записи старше срока остались, `interrupted` — остановлен (выкат; алерт не срабатывает), `error` —
+     * проход упал. Проход без блокировки метрику не меняет;
+     * число удалённых строк — в `info`-логе прохода.
+     */
+    readonly cleanupRuns: Counter<'table' | 'result'>;
+}
+/** Создаёт реестр экземпляра с меткой `service`, метриками процесса Node и метриками пакета (§3.2, AC-2.8). */
+export declare function kitMetrics(options: {
+    readonly service: string;
+}): KitMetrics;
+/** Абсолютный путь к шаблону правил vmalert `alerts/verdeect-kit.rules.yml` внутри установленного пакета (§3.2). */
+export declare const alertRulesTemplate: string;