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

package/dist/testing/outbox-coverage.js

@@ -0,0 +1,98 @@
+// expectOutbox, assertOutboxCoverage (prd.md §3.8 E5, GAP-2, UC-14, AC-5.13; П16). Покрытие — файлы воркеров
+// w<VITEST_POOL_ID>.txt в каталоге прогона startTestStack({outboxEvents}); teardown при KIT_OUTBOX_COVERAGE=1. vitest —
+// loadPeer внутри функций: /testing импортируется без vitest; /messaging не импортируется (без amqplib).
+import { appendFileSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sql } from 'drizzle-orm';
+import { OUTBOX_TABLE } from '../internal/outbox-policy.js';
+import { loadPeer } from '../internal/peer.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+let coverageDir;
+let workerCoverageDir;
+/** @internal Каталог прогона в процессе globalSetup (startTestStack). */
+export function setCoverageDir(dir) {
+    coverageDir = dir;
+}
+/** @internal Каталог покрытия воркера вместо `inject('kitOutboxCoverageDir')` (тесты пакета). */
+export function setWorkerCoverageDir(dir) {
+    workerCoverageDir = dir;
+}
+/** Ключ покрытия события. */
+function coverageKey(event) {
+    return `${event.type}.v${event.version}`;
+}
+/**
+ * Проверяет запись события в **текущей** транзакции `tx` (строки других транзакций не учитываются): строка
+ * `<schema>.outbox` с типом и версией события есть, `data` проходит схему события и (если задано) совпадает с
+ * `expected.data` (`toMatchObject`), `subjectId` (если задан) совпадает. После успешной проверки ключ `<type>.v<version>`
+ * дописывается в файл покрытия воркера (`assertOutboxCoverage`).
+ * @throws утверждение vitest — строки нет, `data` не по схеме или не совпала.
+ * @throws {TypeError} `startTestStack` без `postgres`.
+ */
+export async function expectOutbox(tx, event, expected = {}) {
+    const { expect, inject } = await loadPeer('vitest', 'testing');
+    const schema = inject('kitDatabaseService');
+    if (schema === undefined) {
+        throw new TypeError('expectOutbox: startTestStack запущен без postgres');
+    }
+    const key = coverageKey(event);
+    const table = sql.raw(`${quoteIdentifier(schema)}.${quoteIdentifier(OUTBOX_TABLE)}`);
+    const subject = expected.subjectId === undefined ? sql `` : sql ` and subject_id = ${expected.subjectId}`;
+    const { rows } = await tx.execute(sql `select id, subject_id, data from ${table}
+            where type = ${event.type} and version = ${event.version}
+            and xmin = pg_current_xact_id()::xid${subject} order by seq`);
+    const where = expected.subjectId === undefined ? '' : ` (subjectId ${expected.subjectId})`;
+    expect(rows, `expectOutbox: нет строки ${key}${where} в транзакции`).not.toHaveLength(0);
+    for (const row of rows) {
+        const parsed = event.data.safeParse(row.data);
+        if (!parsed.success) {
+            const paths = parsed.error.issues.map((issue) => issue.path.join('.') || '(root)');
+            expect.fail(`expectOutbox: data строки ${row.id} (${key}) не по схеме: ${paths.join(', ')}`);
+        }
+    }
+    if (expected.data !== undefined) {
+        const matching = rows.some((row) => {
+            try {
+                expect(row.data).toMatchObject(expected.data);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!matching) {
+            expect(rows[0]?.data, `expectOutbox: data ${key} не совпала`).toMatchObject(expected.data);
+        }
+    }
+    const dir = workerCoverageDir ?? inject('kitOutboxCoverageDir');
+    if (dir !== undefined) {
+        appendFileSync(join(dir, `w${process.env.VITEST_POOL_ID ?? '0'}.txt`), `${key}\n`);
+    }
+}
+/**
+ * Падает со списком событий без успешного `expectOutbox` за прогон (GAP-2): объединяет файлы воркеров каталога
+ * прогона. Вызывает teardown `startTestStack({outboxEvents})` при `KIT_OUTBOX_COVERAGE=1`.
+ * @throws {TypeError} вызов вне teardown `startTestStack({outboxEvents})`.
+ * @throws {Error} «assertOutboxCoverage: события без успешного expectOutbox: <ключи>».
+ */
+export function assertOutboxCoverage(events) {
+    const dir = coverageDir;
+    if (dir === undefined) {
+        throw new TypeError('assertOutboxCoverage: вызывается из teardown startTestStack({outboxEvents})');
+    }
+    const covered = new Set();
+    for (const file of readdirSync(dir).filter((name) => name.endsWith('.txt'))) {
+        for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+            if (line !== '') {
+                covered.add(line);
+            }
+        }
+    }
+    const missing = [...new Set(events.map(coverageKey))].filter((key) => !covered.has(key));
+    if (missing.length > 0) {
+        const message = `assertOutboxCoverage: события без успешного expectOutbox: ${missing.join(', ')}`;
+        // Vite теряет текст ошибок globalSetup: сообщение — в stderr до throw.
+        process.stderr.write(`${message}\n`);
+        throw new Error(message);
+    }
+}

package/dist/testing/rabbitmq-admin.d.ts

@@ -0,0 +1,81 @@
+import { type RabbitDefinitions } from '../internal/rabbitmq-definitions.js';
+/** vhost воркера: пользователь воркера (`url`) и администратор (`adminUrl`) на том же vhost. */
+export interface KitRabbitWorker {
+    /** Имя vhost. */
+    readonly vhost: string;
+    /** amqp://<пользователь воркера>@host:port/<vhost> — права M3 сервиса. */
+    readonly url: string;
+    /** amqp://<администратор>@host:port/<vhost> — полные права (тесты, publishTestEvent). */
+    readonly adminUrl: string;
+}
+/** Состояние очереди по management API. */
+export interface RabbitQueueInfo {
+    /** Переживает перезапуск. */
+    readonly durable: boolean;
+    /** Удаляется без потребителей. */
+    readonly autoDelete: boolean;
+    /** Эксклюзивная. */
+    readonly exclusive: boolean;
+    /** Аргументы. */
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /** Сообщений всего. */
+    readonly messages: number;
+    /** Готовых к выдаче. */
+    readonly messagesReady: number;
+    /** Без подтверждения. */
+    readonly messagesUnacknowledged: number;
+    /** Потребителей. */
+    readonly consumers: number;
+}
+/** Запросы к management API с Basic auth администратора. */
+export declare class RabbitAdmin {
+    private readonly managementUrl;
+    /** Имя пользователя; по умолчанию — имя сервиса. */
+    readonly user: string;
+    private readonly auth;
+    constructor(managementUrl: string, 
+    /** Имя пользователя; по умолчанию — имя сервиса. */
+    user: string, password: string);
+    private request;
+    /** Ожидание готовности management API (15672 поднимается позже 5672). */
+    waitReady(timeoutMs?: number): Promise<void>;
+    /** Импорт definitions.json (vhosts, users, permissions, exchanges). */
+    loadDefinitions(definitions: RabbitDefinitions): Promise<void>;
+    /** Права пользователя на vhost. */
+    setPermissions(vhost: string, user: string, permissions: {
+        readonly configure: string;
+        readonly write: string;
+        readonly read: string;
+    }): Promise<void>;
+    /** Имена vhost. */
+    listVhosts(): Promise<string[]>;
+    /** Имена пользователей. */
+    listUsers(): Promise<string[]>;
+    /** Удаление vhost; нет — успех. */
+    deleteVhost(name: string): Promise<void>;
+    /** Удаление пользователя; нет — успех. */
+    deleteUser(name: string): Promise<void>;
+    /** Очередь vhost или `null`. */
+    queue(vhost: string, name: string): Promise<RabbitQueueInfo | null>;
+}
+/** Администратор из `kitRabbitmqUrl` (учётные данные в URL amqp) и `kitRabbitmqManagementUrl` (без них). */
+export declare function rabbitAdminFromProvided(managementUrl: string, amqpAdminUrl: string): RabbitAdmin;
+/** Удаление vhost и пользователей с префиксом. */
+export declare function deleteTestVhosts(admin: RabbitAdmin, prefix: string): Promise<{
+    readonly vhosts: number;
+    readonly users: number;
+}>;
+/**
+ * vhost и пользователь на каждый воркер `1..workers` (`<service>-test-<runId>-w<n>`) из `buildDefinitions` — те же
+ * права, что CLI; администратору — полные права на vhost. До создания удаляются остатки прошлых прогонов с префиксом.
+ */
+export declare function prepareWorkerVhosts(admin: RabbitAdmin, options: {
+    /** Имя сервиса — права на его очереди. */
+    readonly service: string;
+    readonly workers: number;
+    readonly runId: string;
+    readonly amqpAdminUrl: string;
+}): Promise<{
+    readonly removed: readonly string[];
+    readonly workers: readonly KitRabbitWorker[];
+}>;

package/dist/testing/rabbitmq-admin.js

@@ -0,0 +1,146 @@
+// Клиент management API RabbitMQ тестового стека (prd.md §3.8 E5, AC-5.18, UC-14; П2): definitions.json, vhost и
+// пользователь на воркер, удаление по префиксу <svc>-test-. Эталон — B test/support/broker.ts (BrokerAdmin). Внутренний
+// модуль /testing: глобальный fetch, без amqplib.
+import { randomBytes } from 'node:crypto';
+import { buildDefinitions, hashRabbitPassword, } from '../internal/rabbitmq-definitions.js';
+const ALL = { configure: '.*', write: '.*', read: '.*' };
+/** Запросы к management API с Basic auth администратора. */
+export class RabbitAdmin {
+    managementUrl;
+    user;
+    auth;
+    constructor(managementUrl, 
+    /** Имя пользователя; по умолчанию — имя сервиса. */
+    user, password) {
+        this.managementUrl = managementUrl;
+        this.user = user;
+        this.auth = `Basic ${Buffer.from(`${user}:${password}`).toString('base64')}`;
+    }
+    async request(method, path, body, ok = [200, 201, 204]) {
+        const response = await fetch(new URL(path, this.managementUrl), {
+            method,
+            headers: { authorization: this.auth, 'content-type': 'application/json' },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (!ok.includes(response.status)) {
+            // Без тела и пароля: только метод, путь и статус.
+            throw new Error(`RabbitMQ management ${method} ${path}: статус ${response.status}`);
+        }
+        return response;
+    }
+    /** Ожидание готовности management API (15672 поднимается позже 5672). */
+    async waitReady(timeoutMs = 60_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            try {
+                await this.request('GET', 'api/overview');
+                return;
+            }
+            catch (error) {
+                if (Date.now() > deadline) {
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 250));
+            }
+        }
+    }
+    /** Импорт definitions.json (vhosts, users, permissions, exchanges). */
+    async loadDefinitions(definitions) {
+        await this.request('POST', 'api/definitions', definitions);
+    }
+    /** Права пользователя на vhost. */
+    async setPermissions(vhost, user, permissions) {
+        await this.request('PUT', `api/permissions/${encodeURIComponent(vhost)}/${encodeURIComponent(user)}`, permissions);
+    }
+    /** Имена vhost. */
+    async listVhosts() {
+        const response = await this.request('GET', 'api/vhosts');
+        return (await response.json()).map(({ name }) => name);
+    }
+    /** Имена пользователей. */
+    async listUsers() {
+        const response = await this.request('GET', 'api/users');
+        return (await response.json()).map(({ name }) => name);
+    }
+    /** Удаление vhost; нет — успех. */
+    async deleteVhost(name) {
+        await this.request('DELETE', `api/vhosts/${encodeURIComponent(name)}`, undefined, [204, 404]);
+    }
+    /** Удаление пользователя; нет — успех. */
+    async deleteUser(name) {
+        await this.request('DELETE', `api/users/${encodeURIComponent(name)}`, undefined, [204, 404]);
+    }
+    /** Очередь vhost или `null`. */
+    async queue(vhost, name) {
+        const response = await this.request('GET', `api/queues/${encodeURIComponent(vhost)}/${encodeURIComponent(name)}`, undefined, [200, 404]);
+        if (response.status === 404) {
+            return null;
+        }
+        const raw = (await response.json());
+        const count = (key) => (typeof raw[key] === 'number' ? raw[key] : 0);
+        return {
+            durable: raw['durable'] === true,
+            autoDelete: raw['auto_delete'] === true,
+            exclusive: raw['exclusive'] === true,
+            arguments: raw['arguments'] ?? {},
+            messages: count('messages'),
+            messagesReady: count('messages_ready'),
+            messagesUnacknowledged: count('messages_unacknowledged'),
+            consumers: count('consumers'),
+        };
+    }
+}
+/** Администратор из `kitRabbitmqUrl` (учётные данные в URL amqp) и `kitRabbitmqManagementUrl` (без них). */
+export function rabbitAdminFromProvided(managementUrl, amqpAdminUrl) {
+    const url = new URL(amqpAdminUrl);
+    return new RabbitAdmin(managementUrl, decodeURIComponent(url.username), decodeURIComponent(url.password));
+}
+function amqpUrl(base, user, password, vhost) {
+    const url = new URL(base);
+    url.username = encodeURIComponent(user);
+    url.password = encodeURIComponent(password);
+    url.pathname = `/${encodeURIComponent(vhost)}`;
+    return url.toString();
+}
+/** Удаление vhost и пользователей с префиксом. */
+export async function deleteTestVhosts(admin, prefix) {
+    const [vhosts, users] = await Promise.all([admin.listVhosts(), admin.listUsers()]);
+    const ownVhosts = vhosts.filter((name) => name.startsWith(prefix));
+    const ownUsers = users.filter((name) => name.startsWith(prefix));
+    await Promise.all(ownVhosts.map((name) => admin.deleteVhost(name)));
+    await Promise.all(ownUsers.map((name) => admin.deleteUser(name)));
+    return { vhosts: ownVhosts.length, users: ownUsers.length };
+}
+/**
+ * vhost и пользователь на каждый воркер `1..workers` (`<service>-test-<runId>-w<n>`) из `buildDefinitions` — те же
+ * права, что CLI; администратору — полные права на vhost. До создания удаляются остатки прошлых прогонов с префиксом.
+ */
+export async function prepareWorkerVhosts(admin, options) {
+    const prefix = `${options.service}-test-`;
+    const leftovers = (await admin.listVhosts()).filter((name) => name.startsWith(prefix));
+    await deleteTestVhosts(admin, prefix);
+    const admins = new URL(options.amqpAdminUrl);
+    const adminPassword = decodeURIComponent(admins.password);
+    const workers = [];
+    for (let n = 1; n <= options.workers; n += 1) {
+        const vhost = `${prefix}${options.runId}-w${n}`;
+        const password = randomBytes(16).toString('hex');
+        await admin.loadDefinitions(buildDefinitions({
+            vhost,
+            users: [
+                {
+                    service: options.service,
+                    user: vhost,
+                    passwordHash: hashRabbitPassword(password),
+                },
+            ],
+        }));
+        await admin.setPermissions(vhost, admin.user, ALL);
+        workers.push({
+            vhost,
+            url: amqpUrl(options.amqpAdminUrl, vhost, password, vhost),
+            adminUrl: amqpUrl(options.amqpAdminUrl, admin.user, adminPassword, vhost),
+        });
+    }
+    return { removed: leftovers, workers };
+}

package/dist/testing/redis-worker.d.ts

@@ -0,0 +1,10 @@
+import type { KitTestOverride } from './create-test-app.js';
+/**
+ * Подмена префикса ключей и каналов `KitRedisModule` префиксом воркера `workerScope().redisPrefix` (AC-8.5).
+ *
+ * @example
+ * vi.stubEnv('REDIS_URL', inject('kitRedisUrl') ?? '');
+ * const app = await createTestApp({ module: AppModule, service: 'svc', overrides: [redisWorkerOverride()] });
+ * @throws {TypeError} стек без `redis: true`.
+ */
+export declare function redisWorkerOverride(): KitTestOverride;

package/dist/testing/redis-worker.js

@@ -0,0 +1,15 @@
+// redisWorkerOverride (prd.md §3.8, AC-8.5, UC-14; D2 плана E8): подмена префикса Redis приложения префиксом воркера
+// <svc>:w<N>: для createTestApp({overrides}). Токен префикса — внутренний, из /redis не экспортируется.
+import { KIT_REDIS_PREFIX } from '../internal/tokens.js';
+import { workerScope } from './worker-scope.js';
+/**
+ * Подмена префикса ключей и каналов `KitRedisModule` префиксом воркера `workerScope().redisPrefix` (AC-8.5).
+ *
+ * @example
+ * vi.stubEnv('REDIS_URL', inject('kitRedisUrl') ?? '');
+ * const app = await createTestApp({ module: AppModule, service: 'svc', overrides: [redisWorkerOverride()] });
+ * @throws {TypeError} стек без `redis: true`.
+ */
+export function redisWorkerOverride() {
+    return { provide: KIT_REDIS_PREFIX, useValue: workerScope().redisPrefix };
+}

package/dist/testing/repo-conventions.d.ts

@@ -0,0 +1,10 @@
+import { type RepoFiles } from './repo-files.js';
+/** Параметры assertRepoConventions (§3.8). */
+export interface RepoConventionsOptions {
+    /** Корень репозитория сервиса. */
+    readonly root: string;
+}
+/** Базовый файл Compose репозитория — первый найденный по порядку поиска Compose; null — базового файла нет. */
+export declare function baseComposeFile(files: RepoFiles): string | null;
+/** Проверяет репозиторий сервиса по правилам §3.8; при нарушениях бросает ошибку со списком. */
+export declare function assertRepoConventions(options: RepoConventionsOptions): void;