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

package/dist/http/kit-http-core.module.js

@@ -0,0 +1,122 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var KitHttpCoreModule_1;
+// KitHttpCoreModule — внутренний глобальный модуль ядра createHttpApp (prd.md §3.2, §3.5; KT-11, KT-15 п. 2): логгер pino
+// экземпляра, HealthRegistry, KitLifecycle, kitMetrics, KitExceptionFilter, nestjs-pino и GET /ok. Эталоны — O
+// get-ok.controller.ts (/ok, no-store), регистрация фильтра APP_FILTER (O/I/P app.module.ts), O observability.module.ts
+// (LoggerModule на опциях createLoggerOptions). По PRD: окружение — из ConfigService модуля сервиса (KitConfigModule),
+// его нет — Error при сборке.
+import { Controller, Get, Header, Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { APP_FILTER } from '@nestjs/core';
+import { LoggerModule } from 'nestjs-pino';
+import { pino } from 'pino';
+import { KIT_LOGGER, KIT_METRICS } from '../internal/tokens.js';
+import { HealthRegistry } from '../observability/health-registry.js';
+import { KitLifecycle } from '../observability/lifecycle.js';
+import { createLoggerOptions, } from '../observability/logger-options.js';
+import { kitMetrics } from '../observability/metrics.js';
+import { KitExceptionFilter } from './kit-exception.filter.js';
+const CORE_ENV = Symbol('KIT_HTTP_CORE_ENV');
+const LOGGER_PARAMS = Symbol('KIT_HTTP_LOGGER_PARAMS');
+/** Проба живости процесса (эталон O get-ok.controller.ts); вне журнала доступа и OpenAPI. */
+let KitOkController = class KitOkController {
+    /** `200 {status: 'ok'}`, `Cache-Control: no-store`. */
+    ok() {
+        return { status: 'ok' };
+    }
+};
+__decorate([
+    Get('ok'),
+    Header('Cache-Control', 'no-store'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Object)
+], KitOkController.prototype, "ok", null);
+KitOkController = __decorate([
+    Controller()
+], KitOkController);
+function coreEnv(config) {
+    if (config === null || config === undefined) {
+        throw new Error('createHttpApp: модуль сервиса не импортирует KitConfigModule.forRoot({schema})');
+    }
+    return {
+        LOG_LEVEL: config.getOrThrow('LOG_LEVEL'),
+        REPLICA_ID: config.getOrThrow('REPLICA_ID'),
+        SHUTDOWN_TIMEOUT_MS: config.getOrThrow('SHUTDOWN_TIMEOUT_MS'),
+        SHUTDOWN_DRAIN_MS: config.getOrThrow('SHUTDOWN_DRAIN_MS'),
+    };
+}
+/** Внутренний глобальный модуль ядра; подключает его `createHttpApp`. */
+let KitHttpCoreModule = KitHttpCoreModule_1 = class KitHttpCoreModule {
+    /** Ядро одного экземпляра приложения; экспортирует KitLifecycle, HealthRegistry, KIT_METRICS, KIT_LOGGER. */
+    static forRoot(options) {
+        const loggerParams = {
+            provide: LOGGER_PARAMS,
+            useFactory: (env) => createLoggerOptions({
+                ...options.logger,
+                service: options.service,
+                entry: 'http',
+                env,
+                redaction: options.redaction,
+            }),
+            inject: [CORE_ENV],
+        };
+        return {
+            module: KitHttpCoreModule_1,
+            global: true,
+            imports: [
+                // Ограничение: nestjs-pino 5.3 держит один pino-http на процесс (rootLogger.js) — журнал доступа второго
+                // приложения в том же процессе (тесты) идёт с опциями первого; логгер ядра (KIT_LOGGER) — свой у каждого.
+                // README, «Один журнал доступа на процесс».
+                LoggerModule.forRootAsync({
+                    useFactory: (params, logger) => ({
+                        pinoHttp: [{ ...params.pinoHttp[0], logger }, params.pinoHttp[1]],
+                    }),
+                    inject: [LOGGER_PARAMS, KIT_LOGGER],
+                }),
+            ],
+            controllers: [KitOkController],
+            providers: [
+                {
+                    provide: CORE_ENV,
+                    useFactory: coreEnv,
+                    inject: [{ token: ConfigService, optional: true }],
+                },
+                loggerParams,
+                {
+                    provide: KIT_LOGGER,
+                    useFactory: (params) => pino(...params.pinoHttp),
+                    inject: [LOGGER_PARAMS],
+                },
+                {
+                    provide: HealthRegistry,
+                    useFactory: (logger) => new HealthRegistry({ logger }),
+                    inject: [KIT_LOGGER],
+                },
+                {
+                    provide: KitLifecycle,
+                    useFactory: (logger, health, env) => new KitLifecycle({ logger, health, env }),
+                    inject: [KIT_LOGGER, HealthRegistry, CORE_ENV],
+                },
+                {
+                    provide: KIT_METRICS,
+                    useFactory: () => kitMetrics({ service: options.service }),
+                },
+                { provide: APP_FILTER, useClass: KitExceptionFilter },
+            ],
+            exports: [KitLifecycle, HealthRegistry, KIT_METRICS, KIT_LOGGER, LOGGER_PARAMS],
+        };
+    }
+};
+KitHttpCoreModule = KitHttpCoreModule_1 = __decorate([
+    Module({})
+], KitHttpCoreModule);
+export { KitHttpCoreModule };

package/dist/http/pagination.d.ts

@@ -0,0 +1,30 @@
+import { type AnyColumn, type SQL } from 'drizzle-orm';
+import { z } from 'zod';
+/** Значение ключа сортировки в курсоре. */
+export type CursorValue = string | number | boolean | null;
+/** Параметры страницы `?cursor=&limit=`; списки расширяют схему своими фильтрами (`.extend`). */
+export declare const PageQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** Ответ списка: `nextCursor = null` — страниц больше нет. */
+export interface Page<T> {
+    /** Строки страницы (не больше `limit`). */
+    readonly items: T[];
+    /** Курсор следующей страницы или `null`. */
+    readonly nextCursor: string | null;
+}
+/** Курсор — base64url от JSON-массива ключей последней строки; не подписан. */
+export declare function encodeCursor(keys: readonly CursorValue[]): string;
+/** `undefined` → `null`; неразборчивый курсор или другое число ключей → 422 `VALIDATION_FAILED` `path: cursor`. */
+export declare function decodeCursor(cursor: string | undefined, arity: number): CursorValue[] | null;
+/** Репозиторий читает `limit + 1` строк: лишняя строка есть → курсор по последней из `limit`. */
+export declare function pageOf<T>(rows: readonly T[], limit: number, keyOf: (row: T) => readonly CursorValue[]): Page<T>;
+/**
+ * Условие «после курсора» для `where`: `(c1, …, cn) > (v1, …, vn)` (`desc` — `<`) как ИЛИ-цепочка
+ * `c1 > v1 OR (c1 = v1 AND c2 > v2) OR …`. `cursor = null` → `undefined` (первая страница). Последний столбец обязан
+ * быть `primaryKey()` или `unique()` — иначе `Error` (ошибка разработчика). Длина курсора ≠ числу столбцов или `null`
+ * в ключе → 422 `VALIDATION_FAILED` `path: cursor`. Значения передаются параметрами без кодировщика столбца: строка
+ * ISO подходит и столбцу timestamp.
+ */
+export declare function afterCursor(cols: readonly AnyColumn[], cursor: readonly CursorValue[] | null, dir: 'asc' | 'desc'): SQL | undefined;

package/dist/http/pagination.js

@@ -0,0 +1,73 @@
+// Keyset-пагинация (prd.md §3.5, AC-3.6). Эталон — I pagination.ts (encodeCursor, decodeCursor, pageOf, PageQuerySchema).
+// По PRD: limit умолч. 100 (у I — 50), макс. 200; неверный курсор → 422 VALIDATION_FAILED path: cursor (у I — 400
+// VALIDATION); ключи — JSON-скаляры, а не только строки; новое — afterCursor (условие Drizzle по ключам сортировки).
+import { and, or, sql } from 'drizzle-orm';
+import { z } from 'zod';
+import { DomainError } from './errors.js';
+/** Параметры страницы `?cursor=&limit=`; списки расширяют схему своими фильтрами (`.extend`). */
+export const PageQuerySchema = z.object({
+    cursor: z.string().min(1).max(512).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(100),
+});
+function invalidCursor() {
+    return new DomainError('VALIDATION_FAILED', { issues: [{ path: 'cursor', code: 'invalid' }] });
+}
+function isCursorValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)));
+}
+/** Курсор — base64url от JSON-массива ключей последней строки; не подписан. */
+export function encodeCursor(keys) {
+    return Buffer.from(JSON.stringify(keys), 'utf8').toString('base64url');
+}
+/** `undefined` → `null`; неразборчивый курсор или другое число ключей → 422 `VALIDATION_FAILED` `path: cursor`. */
+export function decodeCursor(cursor, arity) {
+    if (cursor === undefined) {
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw invalidCursor();
+    }
+    if (!Array.isArray(value) || value.length !== arity || !value.every(isCursorValue)) {
+        throw invalidCursor();
+    }
+    return value;
+}
+/** Репозиторий читает `limit + 1` строк: лишняя строка есть → курсор по последней из `limit`. */
+export function pageOf(rows, limit, keyOf) {
+    if (rows.length <= limit) {
+        return { items: [...rows], nextCursor: null };
+    }
+    const items = rows.slice(0, limit);
+    const last = items[items.length - 1];
+    return { items, nextCursor: last === undefined ? null : encodeCursor(keyOf(last)) };
+}
+/**
+ * Условие «после курсора» для `where`: `(c1, …, cn) > (v1, …, vn)` (`desc` — `<`) как ИЛИ-цепочка
+ * `c1 > v1 OR (c1 = v1 AND c2 > v2) OR …`. `cursor = null` → `undefined` (первая страница). Последний столбец обязан
+ * быть `primaryKey()` или `unique()` — иначе `Error` (ошибка разработчика). Длина курсора ≠ числу столбцов или `null`
+ * в ключе → 422 `VALIDATION_FAILED` `path: cursor`. Значения передаются параметрами без кодировщика столбца: строка
+ * ISO подходит и столбцу timestamp.
+ */
+export function afterCursor(cols, cursor, dir) {
+    const last = cols[cols.length - 1];
+    if (last === undefined || (!last.primary && !last.isUnique)) {
+        throw new Error('afterCursor: последний ключ сортировки должен быть уникальным');
+    }
+    if (cursor === null) {
+        return undefined;
+    }
+    // Ограничение: null в ключе не поддержан — ключи сортировки keyset должны быть NOT NULL (README, «Пагинация»).
+    if (cursor.length !== cols.length || cursor.includes(null)) {
+        throw invalidCursor();
+    }
+    const op = dir === 'asc' ? sql.raw('>') : sql.raw('<');
+    const branches = cols.map((col, index) => and(...cols.slice(0, index).map((prev, prevIndex) => sql `${prev} = ${cursor[prevIndex]}`), sql `${col} ${op} ${cursor[index]}`));
+    return or(...branches);
+}

package/dist/http/zod-validation.pipe.d.ts

@@ -0,0 +1,15 @@
+import { type PipeTransform } from '@nestjs/common';
+import type { z } from 'zod';
+/**
+ * Разбор тела, query или параметра запроса zod-схемой (§3.5). Успех — данные схемы (с умолчаниями); ошибка —
+ * `DomainError('VALIDATION_FAILED', {issues})`, путь — через точку, без пути — `(body)`. Схема публична: по ней
+ * построитель OpenAPI выводит схемы запроса.
+ */
+export declare class ZodValidationPipe<T extends z.ZodType> implements PipeTransform<unknown, z.output<T>> {
+    readonly schema: T;
+    private readonly logger;
+    /** @param schema схема входа (читает построитель OpenAPI). */
+    constructor(schema: T);
+    /** Данные схемы или 422 `VALIDATION_FAILED`. */
+    transform(value: unknown): z.output<T>;
+}

package/dist/http/zod-validation.pipe.js

@@ -0,0 +1,47 @@
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var ZodValidationPipe_1;
+// ZodValidationPipe (prd.md §3.5, AC-3.1): ошибка схемы → 422 VALIDATION_FAILED, details.issues [{path, code}] без значений.
+// Эталон — O zod-validation.pipe.ts (P — идентичен) и O validation-failed.error.ts (форма issues). По PRD:
+// DomainError('VALIDATION_FAILED') вместо ValidationFailedError; 400/413/415 даёт парсер тела Fastify, отображает фильтр.
+import { Injectable, Logger } from '@nestjs/common';
+import { DomainError } from './errors.js';
+/**
+ * Разбор тела, query или параметра запроса zod-схемой (§3.5). Успех — данные схемы (с умолчаниями); ошибка —
+ * `DomainError('VALIDATION_FAILED', {issues})`, путь — через точку, без пути — `(body)`. Схема публична: по ней
+ * построитель OpenAPI выводит схемы запроса.
+ */
+let ZodValidationPipe = ZodValidationPipe_1 = class ZodValidationPipe {
+    schema;
+    logger = new Logger(ZodValidationPipe_1.name);
+    /** @param schema схема входа (читает построитель OpenAPI). */
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /** Данные схемы или 422 `VALIDATION_FAILED`. */
+    transform(value) {
+        const result = this.schema.safeParse(value);
+        if (result.success) {
+            return result.data;
+        }
+        const issues = result.error.issues.map((issue) => ({
+            path: issue.path.map(String).join('.') || '(body)',
+            code: issue.code,
+        }));
+        // Только пути и коды: значения ввода в лог не попадают (эталон O).
+        this.logger.debug({ issues: issues.map((item) => `${item.path}:${item.code}`) }, 'запрос отклонён схемой');
+        throw new DomainError('VALIDATION_FAILED', { issues });
+    }
+};
+ZodValidationPipe = ZodValidationPipe_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [Object])
+], ZodValidationPipe);
+export { ZodValidationPipe };

package/dist/idempotency/idempotency.interceptor.d.ts

@@ -0,0 +1,55 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Principal } from '@verdeect/auth';
+import { type Observable } from 'rxjs';
+import { Db } from '../database/db.js';
+import { type KitIdempotentOptions } from '../internal/metadata.js';
+import type { KitIdempotencyTable } from './table.js';
+/** Токен таблицы идемпотентности сервиса (провайдер `KitIdempotencyModule`). */
+export declare const KIT_IDEMPOTENCY_TABLE: unique symbol;
+/** Печатные ASCII, ≤ 200 знаков (эталон O). */
+export declare const KEY_FORMAT: RegExp;
+/** Область ключа: тенант (или `null`) и субъект. */
+export interface IdempotencyScope {
+    /** Тенант записи или `null` (служба без `tenantFromBody`). */
+    readonly tenant: string | null;
+    /** `user:<sub>`, `agent:<sub>`, `service:<client_id>`. */
+    readonly subject: string;
+}
+/** JSON с рекурсивно отсортированными ключами: одинаковое тело — одинаковый отпечаток (эталон O). */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256 hex метода, пути без query и канонического тела. */
+export declare function fingerprintOf(method: string, path: string, body: unknown): string;
+/**
+ * Область ключа (§3.3а): пользователь и агент — тенант токена (поле тела игнорируется); служба — `client_id` и тенант
+ * из поля `tenantFromBody`, если это непустая строка, иначе `null`.
+ */
+export declare function scopeOf(principal: Principal, body: unknown, options: KitIdempotentOptions): IdempotencyScope;
+/**
+ * Интерсептор `@Idempotent` (§3.3а): регистрирует `KitIdempotencyModule` через `APP_INTERCEPTOR`. Повтор — сохранённый
+ * ответ и `Idempotent-Replayed: true`; другое тело — 422 `IDEMPOTENCY_KEY_REUSED`; запрос ещё идёт — 409
+ * `IDEMPOTENCY_IN_PROGRESS`. Сохраняются только успешные ответы.
+ */
+export declare class IdempotencyInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly db;
+    private readonly table;
+    private readonly logger;
+    constructor(reflector: Reflector, db: Db, table: KitIdempotencyTable);
+    /** Оборачивает обработчик маршрута с `@Idempotent`. */
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private run;
+    private where;
+    private begin;
+    /**
+     * Обработчик упал: строка своей попытки удаляется — повтор выполнит запрос заново; перехваченную строку другой
+     * попытки не трогает; сбой release не подменяет ответ.
+     */
+    private release;
+    /**
+     * Один повтор `complete` сразу после сбоя (эталон O). После двух сбоев ответ клиенту не меняется: строка остаётся
+     * `in_progress` и через 5 минут переиспользуется. Ответ пишется только своей попытки: строку перехватил повторный
+     * запрос (обработчик дольше 5 минут) — ответ не сохраняется, `warn` без ключа и тела (KT-22 п. 3).
+     */
+    private completeWithRetry;
+}