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

package/dist/messaging/outbox-relay.d.ts

@@ -0,0 +1,67 @@
+import type { Db } from '../database/db.js';
+import type { KitMetrics } from '../observability/metrics.js';
+import type { KitEvent } from './define-event.js';
+import type { OutboxStore } from './outbox-store.js';
+import { type MessagingLog, type RabbitConnection } from './rabbit-connection.js';
+/** Часы relay (внутренние): подмена в тесте AC-5.16 — без реальных пауз. */
+export interface RelayTimers {
+    /** Текущее время, мс. */
+    now(): number;
+    /** Пауза `ms` (`Infinity` — до прерывания); прерывание `signal` — resolve. */
+    sleep(ms: number, signal: AbortSignal, kind: 'pause' | 'confirm' | 'stats'): Promise<void>;
+}
+/** Зависимости relay (внутренние). */
+export interface OutboxRelayDeps {
+    /** `Db` сервиса. */
+    readonly db: Db;
+    /** Запросы outbox. */
+    readonly store: OutboxStore;
+    /** Соединение. */
+    readonly connection: Pick<RabbitConnection, 'isConnected' | 'isChannelReady' | 'createChannel' | 'onChannelReady' | 'shutdownDeadline'>;
+    /** События модуля по type. */
+    readonly events: ReadonlyMap<string, KitEvent>;
+    /** Метрики экземпляра. */
+    readonly metrics?: KitMetrics;
+    /** Логгер. */
+    readonly log?: MessagingLog;
+    /** Часы. */
+    readonly timers?: RelayTimers;
+}
+/** Публикатор outbox: фоновый цикл, хуки Nest вызывает модуль (внутренний класс). */
+export declare class OutboxRelay {
+    private readonly deps;
+    private readonly log;
+    private readonly timers;
+    private channel;
+    private unsubscribe;
+    private loop;
+    private stats;
+    private running;
+    private backoffMs;
+    private wakeRequested;
+    private sleepAbort;
+    private readonly statsAbort;
+    private requestStop;
+    private readonly stopRequested;
+    private statsFailing;
+    private readonly unknownTypes;
+    constructor(deps: OutboxRelayDeps);
+    /** Запуск цикла после старта приложения. */
+    onApplicationBootstrap(): void;
+    /** Будит цикл (после COMMIT `OutboxStore.add`, готовности канала, остановки). */
+    wake(): void;
+    /** Шаг 3 остановки: пачка дорабатывает в общем сроке, неподтверждённая публикация бросается. */
+    beforeApplicationShutdown(): Promise<void>;
+    private run;
+    private iterate;
+    private drain;
+    /** null — подтверждено; STOPPED — остановка прервала ожидание; иначе текст ошибки. */
+    private publish;
+    private subjectKind;
+    private reportFailure;
+    private nextBackoff;
+    /** Пробуждение во время drain не теряется: флаг проверяется до сна. */
+    private pause;
+    /** Метрики outbox раз в RELAY_POLL_MS, независимо от канала (П10). */
+    private statsLoop;
+}

package/dist/messaging/outbox-relay.js

@@ -0,0 +1,260 @@
+// OutboxRelay (prd.md §3.4 relay, UC-5, AC-5.3–AC-5.5, AC-5.11, AC-5.16, AC-9.5). Эталон — O outbox-relay.ts; из P —
+// гонка publish с остановкой (STOPPED) и beforeApplicationShutdown против shutdownDeadline; по PRD — опрос 1000 мс
+// (O — 200), метрики verdeect_outbox_* раз в RELAY_POLL_MS независимо от канала (П10), строка неизвестного типа —
+// subject.kind 'unknown' (П23). Пачка ≤ 100 по seq под FOR UPDATE SKIP LOCKED, публикация последовательно с
+// подтверждением; первая неудача прерывает пачку — порядок сохраняется. Без соединения или канала БД не опрашивается.
+// Остановка во время неподтверждённой публикации оставляет строку без attempts + 1: повтор после рестарта —
+// «не больше одного раза по смыслу» через inbox получателя (UC-6).
+import { setTimeout as sleepFor } from 'node:timers/promises';
+import { ulid } from '../internal/ids.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError, captureThrottled } from '../observability/sentry.js';
+import { buildEnvelope } from './envelope.js';
+import { nestLog, } from './rabbit-connection.js';
+import { EVENTS_EXCHANGE, PUBLISH_CONFIRM_TIMEOUT_MS, RELAY_ALERT_ATTEMPTS, RELAY_BACKOFF_MAX_MS, RELAY_BACKOFF_MIN_MS, RELAY_BATCH_DEADLINE_MS, RELAY_BATCH_SIZE, RELAY_POLL_MS, } from './topology.js';
+const CHANNEL_NAME = 'outbox-relay';
+const CONFIRM_DEADLINE_ERROR = 'confirm deadline';
+const STOPPED = Symbol('stopped');
+const realTimers = {
+    now: () => Date.now(),
+    sleep: async (ms, signal) => {
+        if (signal.aborted) {
+            return;
+        }
+        // Infinity — ждать прерывания: setTimeout не принимает бесконечность.
+        const wait = Number.isFinite(ms) ? ms : 2_147_483_647;
+        await sleepFor(wait, undefined, { signal, ref: false }).catch(() => undefined);
+    },
+};
+/** Публикатор outbox: фоновый цикл, хуки Nest вызывает модуль (внутренний класс). */
+export class OutboxRelay {
+    deps;
+    log;
+    timers;
+    channel = null;
+    unsubscribe = null;
+    loop = null;
+    stats = null;
+    running = false;
+    backoffMs = 0;
+    wakeRequested = false;
+    sleepAbort = new AbortController();
+    statsAbort = new AbortController();
+    requestStop = () => undefined;
+    stopRequested = new Promise((resolve) => {
+        this.requestStop = () => resolve(STOPPED);
+    });
+    statsFailing = false;
+    unknownTypes = new Set();
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? nestLog('OutboxRelay');
+        this.timers = deps.timers ?? realTimers;
+    }
+    /** Запуск цикла после старта приложения. */
+    onApplicationBootstrap() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.channel = this.deps.connection.createChannel({
+            name: CHANNEL_NAME,
+            confirm: true,
+            publishTimeout: PUBLISH_CONFIRM_TIMEOUT_MS,
+        });
+        // Канал настроен (после подключения или повтора): пауза сбрасывается, разгрузка — сразу.
+        this.unsubscribe = this.deps.connection.onChannelReady(CHANNEL_NAME, () => {
+            this.backoffMs = 0;
+            this.wake();
+        });
+        this.loop = this.run();
+        this.stats = this.statsLoop();
+        this.log.debug({}, 'outbox: relay запущен');
+    }
+    /** Будит цикл (после COMMIT `OutboxStore.add`, готовности канала, остановки). */
+    wake() {
+        this.wakeRequested = true;
+        this.sleepAbort.abort();
+    }
+    /** Шаг 3 остановки: пачка дорабатывает в общем сроке, неподтверждённая публикация бросается. */
+    async beforeApplicationShutdown() {
+        if (!this.running) {
+            return;
+        }
+        this.running = false;
+        this.requestStop();
+        this.wake();
+        this.statsAbort.abort();
+        const loop = this.loop ?? Promise.resolve();
+        const stopped = await Promise.race([
+            loop.then(() => true),
+            this.deps.connection.shutdownDeadline(),
+        ]);
+        if (!stopped) {
+            this.log.warn({}, 'outbox: срок остановки relay вышел, идём дальше');
+        }
+        await this.stats;
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        await this.channel?.close();
+        this.channel = null;
+        this.log.debug({}, 'outbox: relay остановлен');
+    }
+    async run() {
+        while (this.running) {
+            const pause = await this.iterate();
+            if (!this.running) {
+                return;
+            }
+            await this.pause(pause);
+        }
+    }
+    async iterate() {
+        const { connection } = this.deps;
+        if (!connection.isConnected() || !connection.isChannelReady(CHANNEL_NAME)) {
+            // Без соединения или канала БД не опрашивается: строки копятся, lag растёт; ждём готовности канала.
+            return Infinity;
+        }
+        try {
+            const result = await this.drain();
+            if (result.failed) {
+                return this.nextBackoff();
+            }
+            this.backoffMs = 0;
+            return result.claimed === RELAY_BATCH_SIZE ? 0 : RELAY_POLL_MS;
+        }
+        catch (error) {
+            this.log.error({ err: sanitizeError(error) }, 'outbox: ошибка БД relay');
+            captureThrottled('outbox-relay:db', error);
+            return this.nextBackoff();
+        }
+    }
+    async drain() {
+        const ctx = { tenant: null, traceId: ulid(), actor: { channel: 'system' } };
+        return this.deps.db.transaction(ctx, async (tx) => {
+            const rows = await this.deps.store.claimBatch(tx, RELAY_BATCH_SIZE);
+            const deadline = this.timers.now() + RELAY_BATCH_DEADLINE_MS;
+            const published = [];
+            let failed = false;
+            for (const row of rows) {
+                if (!this.running) {
+                    break;
+                }
+                const remaining = deadline - this.timers.now();
+                if (remaining <= 0) {
+                    this.log.warn({ published: published.length, left: rows.length - published.length }, 'outbox: срок пачки вышел');
+                    break;
+                }
+                const outcome = await this.publish(row, remaining);
+                if (outcome === STOPPED) {
+                    break;
+                }
+                if (outcome === null) {
+                    published.push(row.id);
+                    continue;
+                }
+                failed = true;
+                const attempts = await this.deps.store.markFailed(tx, row.id, outcome);
+                this.reportFailure(row, attempts, outcome);
+                break;
+            }
+            await this.deps.store.markPublished(tx, published);
+            if (published.length > 0) {
+                this.log.debug({ published: published.length, claimed: rows.length }, 'outbox: пачка опубликована');
+            }
+            return { claimed: rows.length, failed };
+        });
+    }
+    /** null — подтверждено; STOPPED — остановка прервала ожидание; иначе текст ошибки. */
+    async publish(row, timeoutMs) {
+        const channel = this.channel;
+        if (channel === null) {
+            return 'channel closed';
+        }
+        const envelope = buildEnvelope({ ...row, subjectKind: this.subjectKind(row.type) });
+        const confirmAbort = new AbortController();
+        const confirmed = channel
+            .publish(EVENTS_EXCHANGE, row.type, Buffer.from(JSON.stringify(envelope)), {
+            persistent: true,
+            messageId: row.id,
+            type: row.type,
+            contentType: 'application/json',
+            // AMQP timestamp — секунды.
+            timestamp: Math.floor(row.occurredAt.getTime() / 1000),
+        })
+            .then(() => null, (error) => (error instanceof Error ? error.message : String(error)));
+        const deadline = this.timers
+            .sleep(timeoutMs, confirmAbort.signal, 'confirm')
+            .then(() => (confirmAbort.signal.aborted ? null : CONFIRM_DEADLINE_ERROR));
+        try {
+            // Опоздавшее подтверждение даст дубль при повторе: доставка at-least-once.
+            return await Promise.race([
+                confirmed,
+                deadline.then((value) => value ?? new Promise(() => undefined)),
+                this.stopRequested,
+            ]);
+        }
+        finally {
+            confirmAbort.abort();
+        }
+    }
+    subjectKind(type) {
+        const event = this.deps.events.get(type);
+        if (event !== undefined) {
+            return event.subject;
+        }
+        if (!this.unknownTypes.has(type)) {
+            this.unknownTypes.add(type);
+            this.log.warn({ type }, 'outbox: тип события вне outbox.events — subject.kind unknown');
+        }
+        return 'unknown';
+    }
+    reportFailure(row, attempts, error) {
+        this.log.warn({ id: row.id, type: row.type, attempts, error }, 'outbox: публикация не удалась');
+        if (attempts !== RELAY_ALERT_ATTEMPTS) {
+            return;
+        }
+        // Ровно раз на строку: attempts растёт монотонно. Без data (AC-5.16).
+        this.log.error({ id: row.id, type: row.type, attempts }, 'outbox: строка не опубликована 5 раз');
+        captureError(new Error('outbox: строка не опубликована 5 раз'), {
+            tags: { code: 'OUTBOX_PUBLISH_FAILED' },
+            extra: { id: row.id, type: row.type, attempts },
+        });
+    }
+    nextBackoff() {
+        this.backoffMs =
+            this.backoffMs === 0
+                ? RELAY_BACKOFF_MIN_MS
+                : Math.min(this.backoffMs * 2, RELAY_BACKOFF_MAX_MS);
+        return this.backoffMs;
+    }
+    /** Пробуждение во время drain не теряется: флаг проверяется до сна. */
+    async pause(ms) {
+        if (ms === 0 || this.wakeRequested) {
+            this.wakeRequested = false;
+            return;
+        }
+        this.sleepAbort = new AbortController();
+        await this.timers.sleep(ms, this.sleepAbort.signal, 'pause');
+        this.wakeRequested = false;
+    }
+    /** Метрики outbox раз в RELAY_POLL_MS, независимо от канала (П10). */
+    async statsLoop() {
+        const ctx = { tenant: null, traceId: ulid(), actor: { channel: 'system' } };
+        while (!this.statsAbort.signal.aborted) {
+            try {
+                const { pending, lag } = await this.deps.db.transaction(ctx, (tx) => this.deps.store.stats(tx));
+                this.deps.metrics?.outboxPending.set(pending);
+                this.deps.metrics?.outboxLagSeconds.set(lag);
+                this.statsFailing = false;
+            }
+            catch (error) {
+                if (!this.statsFailing) {
+                    this.statsFailing = true;
+                    this.log.warn({ err: sanitizeError(error) }, 'outbox: метрики не обновлены');
+                }
+            }
+            await this.timers.sleep(RELAY_POLL_MS, this.statsAbort.signal, 'stats');
+        }
+    }
+}

package/dist/messaging/outbox-store.d.ts

@@ -0,0 +1,75 @@
+import type { z } from 'zod';
+import type { Db, DbTx } from '../database/db.js';
+import type { KitEvent } from './define-event.js';
+import { type MessagingLog } from './rabbit-connection.js';
+import type { KitOutboxTable } from './tables.js';
+/** Строка, взятая relay. */
+export interface OutboxClaimedRow {
+    /** id события. */
+    readonly id: string;
+    /** Тип. */
+    readonly type: string;
+    /** Версия. */
+    readonly version: number;
+    /** Тенант. */
+    readonly tenant: string | null;
+    /** id субъекта. */
+    readonly subjectId: string;
+    /** Актор. */
+    readonly actor: Record<string, unknown>;
+    /** traceId. */
+    readonly traceId: string;
+    /** Данные. */
+    readonly data: Record<string, unknown>;
+    /** Время события. */
+    readonly occurredAt: Date;
+    /** Неудачных публикаций. */
+    readonly attempts: number;
+}
+/** Зависимости `OutboxStore` (внутренние). */
+export interface OutboxStoreDeps {
+    /** `Db` сервиса. */
+    readonly db: Db;
+    /** Таблица outbox. */
+    readonly table: KitOutboxTable;
+    /** События `outbox.events` модуля по type. */
+    readonly events: ReadonlyMap<string, KitEvent>;
+    /** Пробуждение relay после COMMIT. */
+    readonly wake: () => void;
+    /** Логгер. */
+    readonly log?: MessagingLog;
+}
+/**
+ * Запись событий в outbox в транзакции сервиса (§3.4): `add(tx, Event, {subjectId, data})`. Строка видна relay после
+ * `COMMIT` вместе с изменением домена; откат транзакции — ни изменения, ни события.
+ */
+export declare class OutboxStore {
+    private readonly deps;
+    private readonly log;
+    /** @internal Создаёт KitMessagingModule. */
+    constructor(deps: OutboxStoreDeps);
+    /**
+     * Добавляет событие в outbox транзакции `tx` (`Db.transaction`): `tenant`, `actor`, `traceId` — из `DbContext`,
+     * `id` — `evt_` + ULID; после `COMMIT` relay публикует его без ожидания опроса. Любая ошибка — исключение до записи:
+     * транзакция сервиса откатывается.
+     * @returns id события.
+     * @throws {TypeError} событие не из `outbox.events`, `tx` не из `Db.transaction`, признак `tenant` нарушен, пустой
+     * `subjectId`, `data` не по схеме (в тексте — пути полей без значений).
+     * @throws {AfterCommitInReadOnlyError} `tx` из `Db.read`.
+     */
+    add<E extends KitEvent>(tx: DbTx, event: E, input: {
+        readonly subjectId: string;
+        readonly data: z.input<E['data']>;
+    }): Promise<string>;
+    /** @internal Пачка неопубликованных по `seq` под `FOR UPDATE SKIP LOCKED` (relay). */
+    claimBatch(tx: DbTx, limit: number): Promise<OutboxClaimedRow[]>;
+    /** @internal Отметка опубликованных. */
+    markPublished(tx: DbTx, ids: readonly string[]): Promise<void>;
+    /** @internal Неудача публикации: `attempts + 1`, `last_error` ≤ 500; возвращает новое `attempts`. */
+    markFailed(tx: DbTx, id: string, error: string): Promise<number>;
+    /** @internal Число неопубликованных и возраст старейшей, с (метрики). */
+    stats(tx: DbTx): Promise<{
+        readonly pending: number;
+        readonly lag: number;
+    }>;
+}

package/dist/messaging/outbox-store.js

@@ -0,0 +1,126 @@
+// OutboxStore (prd.md §3.4, §6, UC-5, AC-5.1, AC-5.2, AC-5.15). Эталон — O outbox-store.ts; по PRD — id = newId('evt') в
+// коде, tenant/actor/traceId из DbContext (txContextOf), проверка data и признака tenant до записи, afterCommit →
+// relay.wake(); SQL-триггеров нет (P0). Запросы relay и очистки — построителем Drizzle по объекту таблицы (AC-9.4).
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
+import { newId } from '../internal/ids.js';
+import { txContextOf } from '../internal/tx-context.js';
+import { nestLog } from './rabbit-connection.js';
+/** Предел `last_error`. */
+const LAST_ERROR_MAX = 500;
+/**
+ * Запись событий в outbox в транзакции сервиса (§3.4): `add(tx, Event, {subjectId, data})`. Строка видна relay после
+ * `COMMIT` вместе с изменением домена; откат транзакции — ни изменения, ни события.
+ */
+export class OutboxStore {
+    deps;
+    log;
+    /** @internal Создаёт KitMessagingModule. */
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? nestLog('OutboxStore');
+    }
+    /**
+     * Добавляет событие в outbox транзакции `tx` (`Db.transaction`): `tenant`, `actor`, `traceId` — из `DbContext`,
+     * `id` — `evt_` + ULID; после `COMMIT` relay публикует его без ожидания опроса. Любая ошибка — исключение до записи:
+     * транзакция сервиса откатывается.
+     * @returns id события.
+     * @throws {TypeError} событие не из `outbox.events`, `tx` не из `Db.transaction`, признак `tenant` нарушен, пустой
+     * `subjectId`, `data` не по схеме (в тексте — пути полей без значений).
+     * @throws {AfterCommitInReadOnlyError} `tx` из `Db.read`.
+     */
+    async add(tx, event, input) {
+        const { type } = event;
+        if (this.deps.events.get(type) !== event) {
+            throw new TypeError(`OutboxStore.add: событие ${type} не объявлено в KitMessagingModule.forRoot({outbox: {events}})`);
+        }
+        const ctx = txContextOf(tx);
+        if (ctx === undefined) {
+            throw new TypeError('OutboxStore.add: tx — не транзакция Db.transaction');
+        }
+        const tenant = ctx.tenant ?? '';
+        if (event.tenant === 'required' && tenant === '') {
+            throw new TypeError(`OutboxStore.add: событие ${type} требует компанию (tenant: 'required'), в DbContext тенанта нет`);
+        }
+        if (event.tenant === 'none' && tenant !== '') {
+            throw new TypeError(`OutboxStore.add: событие ${type} без компании (tenant: 'none'), а в DbContext тенант задан`);
+        }
+        if (typeof input.subjectId !== 'string' || input.subjectId === '') {
+            throw new TypeError(`OutboxStore.add: событие ${type} — пустой subjectId`);
+        }
+        const parsed = event.data.safeParse(input.data);
+        if (!parsed.success) {
+            const paths = [
+                ...new Set(parsed.error.issues.map((issue) => issue.path.join('.') || '(root)')),
+            ];
+            throw new TypeError(`OutboxStore.add: data события ${type} не по схеме: ${paths.join(', ')}`);
+        }
+        // До INSERT: read-only транзакция отклоняется здесь (AfterCommitInReadOnlyError), а не ошибкой 25006.
+        this.deps.db.afterCommit(tx, () => {
+            this.deps.wake();
+        });
+        const id = newId('evt');
+        await tx.insert(this.deps.table).values({
+            id,
+            tenant: event.tenant === 'none' ? null : tenant,
+            type,
+            version: event.version,
+            subjectId: input.subjectId,
+            actor: { ...ctx.actor },
+            traceId: ctx.traceId,
+            data: parsed.data,
+        });
+        this.log.debug({ type, id }, 'outbox: строка добавлена');
+        return id;
+    }
+    /** @internal Пачка неопубликованных по `seq` под `FOR UPDATE SKIP LOCKED` (relay). */
+    async claimBatch(tx, limit) {
+        const t = this.deps.table;
+        return tx
+            .select({
+            id: t.id,
+            type: t.type,
+            version: t.version,
+            tenant: t.tenant,
+            subjectId: t.subjectId,
+            actor: t.actor,
+            traceId: t.traceId,
+            data: t.data,
+            occurredAt: t.occurredAt,
+            attempts: t.attempts,
+        })
+            .from(t)
+            .where(isNull(t.publishedAt))
+            .orderBy(t.seq)
+            .limit(limit)
+            .for('update', { skipLocked: true });
+    }
+    /** @internal Отметка опубликованных. */
+    async markPublished(tx, ids) {
+        if (ids.length === 0) {
+            return;
+        }
+        const t = this.deps.table;
+        await tx
+            .update(t)
+            .set({ publishedAt: sql `now()` })
+            .where(inArray(t.id, [...ids]));
+    }
+    /** @internal Неудача публикации: `attempts + 1`, `last_error` ≤ 500; возвращает новое `attempts`. */
+    async markFailed(tx, id, error) {
+        const t = this.deps.table;
+        const [row] = await tx
+            .update(t)
+            .set({ attempts: sql `${t.attempts} + 1`, lastError: error.slice(0, LAST_ERROR_MAX) })
+            .where(and(eq(t.id, id), isNull(t.publishedAt)))
+            .returning({ attempts: t.attempts });
+        return row?.attempts ?? 0;
+    }
+    /** @internal Число неопубликованных и возраст старейшей, с (метрики). */
+    async stats(tx) {
+        const t = this.deps.table;
+        const { rows } = await tx.execute(sql `select count(*)::int as pending,
+                coalesce(extract(epoch from now() - min(${t.occurredAt}))::float8, 0) as lag
+                from ${t} where ${t.publishedAt} is null`);
+        return { pending: rows[0]?.pending ?? 0, lag: Math.max(0, rows[0]?.lag ?? 0) };
+    }
+}

package/dist/messaging/peer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/messaging/peer.js

@@ -0,0 +1,5 @@
+// Проверка опциональных peer /messaging при загрузке подпути (prd.md NFR-3, AC-1.2; П15 E4): без top-level await.
+// Первый импорт index.ts — текст AC-1.2 называет /messaging. Сами пакеты грузит rabbit-connection.ts при подключении.
+import { requirePeer } from '../internal/peer.js';
+requirePeer('amqplib', 'messaging');
+requirePeer('amqp-connection-manager', 'messaging');