@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

package/output/core/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../source/core/assemble.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAM7D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED,gBAAgB;AAChB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,WAAW,CAAA;IACrB,GAAG,EAAE,SAAS,CAAA;IACd,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,eAAe,CAAA;IACvC,2DAA2D;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,IAAI,CAIrH;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlI;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxG"}

package/output/core/assemble.js

@@ -0,0 +1,88 @@
+import Fastify from 'fastify';
+import { registerCookie } from './modules/cookie/index.js';
+import { registerRequestContext } from './modules/context/index.js';
+import { attachServerIdentity } from './modules/identity/index.js';
+import { createLoggerOptions } from './modules/logging/index.js';
+import { registerOpenApi } from './modules/openapi/index.js';
+import { createRequestIdOptions, registerRequestId } from './modules/request-id/index.js';
+import { registerResponse } from './modules/response/index.js';
+import { installRouteSchemaGuard, registerSchema } from './modules/schema/index.js';
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ *
+ * 固定装配，**不从包对外导出**：对外入口只有 `defineServer` / `startServer` / `generateOpenApi`。
+ */
+export function createFastify(env) {
+    return Fastify({
+        trustProxy: true,
+        logger: createLoggerOptions(env),
+        ...createRequestIdOptions(),
+    });
+}
+/**
+ * 出文档用的**最小实例**（`generateOpenApi` 专用）。
+ *
+ * 没有 logger、没有 `requestId`、没有 `trustProxy`——这些只在**有请求**时才有意义，
+ * 而构建期一条请求都不会发。`logger: false` 下 `app.log` 仍是 `abstract-logging` 的
+ * 空实现，满足 `LoggerLike`，因此下游单元拿到的 `ctx.log` 调用不会炸，也不会产生输出。
+ */
+export function createDocumentFastify() {
+    return Fastify({ logger: false });
+}
+/**
+ * **schema 契约**（固定序，不可替换）：`identity` → `schema`（zod compiler）→ 路由契约守卫。
+ *
+ * 两个入口都必须有它：
+ * - `startServer` 要让 zod 真的校验/序列化请求，并让「路由缺 `schema`」在注册处就失败；
+ * - `generateOpenApi` 要把 zod 转成 JSON Schema 出文档，也要同一个守卫——**文档就是权限目录**，
+ *   构建期放过的路由会在线上变成「接口永远判不过」。
+ *
+ * 单独成函数是为了让「运行期 core」与「文档 core」两条装配路径共用同一段契约，
+ * 而不用把整段运行期能力拖进出文档路径。
+ */
+export function registerSchemaContract(app, options) {
+    attachServerIdentity(app, options.identity);
+    registerSchema(app); // schema → zod compiler
+    installRouteSchemaGuard(app); // 强制所有路由声明 schema（含 operationId / summary / description / tags）
+}
+/**
+ * **文档 core**（`generateOpenApi` 专用）：schema 契约 + swagger。
+ *
+ * 只有这三件事与「把 zod schema 转成 OpenAPI 文档」有关：身份（`info.title` /
+ * `info.version`）、zod compiler（转换前得能读懂 zod）、守卫（不让文档缺条目）、swagger（转换器）。
+ * `requestContext` / `cookie` / `response` / `requestId` 全部**不装**——它们只影响
+ * 请求怎么被处理，而构建期一条请求都不会发。
+ */
+export async function registerDocumentCore(app, options) {
+    registerSchemaContract(app, options);
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+}
+/**
+ * core 装配（固定序，不可替换）：`identity` → `schema`（+ 路由契约守卫）→ `requestContext`
+ * → `cookie` → `response` → `openapi` → `requestId` 回吐。
+ *
+ * 全部为框架内置能力，**不暴露选项面**；`request.ctx` 的装配也在这一步完成（`type-augment` 的
+ * 类型承诺因此总有运行期对应物）。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ *
+ * 这里**不建路由注册表**：权限目录直接由 `app.swagger()` 生成的文档派生（OpenAPI 是唯一来源）。
+ */
+export async function registerCore(app, options) {
+    registerSchemaContract(app, options);
+    registerRequestContext(app); // request.ctx（type-augment 承诺的运行期对应物）
+    registerCookie(app, { env: options.env, readConfig: options.readConfig });
+    registerResponse(app, { classifyResourceError: options.classifyResourceError });
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+    registerRequestId(app); // 响应回吐 x-request-id
+}

package/output/core/boot/context.d.ts

@@ -0,0 +1,89 @@
+import type { Disposer } from '@taicode/common-base';
+import type { ConfigEnv } from '../env.js';
+import type { AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClassifier, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext } from '../types.js';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+export declare function liveResources(resources: object): Record<string, unknown>;
+/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
+export declare function liveClients(clients: object): Record<string, unknown>;
+/**
+ * `config` 槽位的**读取能力**（不是容器）。
+ *
+ * 装配期各单元需要的是「能不能读、读到什么」，不是「一个有 `current` 字段的箱子」——
+ * 后者把**写入**也一并交给了每个拿到 `BootContext` 的步骤，绕开 `buildConfig` 就能改配置。
+ * 因此这里只暴露读：`available`（有没有产出）+ `read()`（读，未产出即抛）。
+ *
+ * 写入通道是**私有 Symbol**（本文件内、不导出）：调用方连键名都写不出来，只能通过
+ * `provideConfig()` 写，而它只被 `buildConfig` 调用。
+ */
+export interface ConfigAccess<C> {
+    /** `config` 槽位是否已产出（出 spec 路径恒为 `false`） */
+    readonly available: boolean;
+    /** 读配置；未产出时抛 `SystemError('CONFIG_UNAVAILABLE')` */
+    read(): Awaited<C>;
+}
+export declare function createConfigAccess<C>(): ConfigAccess<C>;
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export declare function provideConfig<C>(access: ConfigAccess<C>, value: Awaited<C>): void;
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export declare function readConfigKey(config: unknown, key: string): unknown;
+/** `resources(ctx)` 入参 */
+export interface ResourcesContextParams {
+    env: ConfigEnv;
+    log: LoggerLike;
+    disposer: Disposer;
+    /** 收集器：`buildResources` 注入，把各资源注册的分类器按注册顺序收起来 */
+    registerClassifyError: (classifier: ErrorClassifier) => void;
+}
+export declare function createResourcesContext(params: ResourcesContextParams): ResourcesContext;
+/** `config(ctx)` 入参 */
+export interface ConfigContextParams<R> {
+    env: ConfigEnv;
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+}
+export declare function createConfigContext<R>(params: ConfigContextParams<R>): ConfigContext<R>;
+/** `clients(ctx)` 入参（与 `services` 同依赖集：`resources` + `config`） */
+export interface ClientsContextParams<R, C> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    configAccess: ConfigAccess<C>;
+}
+export declare function createClientsContext<R, C>(params: ClientsContextParams<R, C>): ClientsContext<R, C>;
+/** `services(ctx)` 入参 */
+export interface ServiceContextParams<R, C, CL> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    configAccess: ConfigAccess<C>;
+    clients: ClientsView<CL>;
+}
+export declare function createServiceContext<R, C, CL>(params: ServiceContextParams<R, C, CL>): ServiceContext<R, C, CL>;
+/** `middlewares(ctx)` 入参 */
+export interface MiddlewareContextParams<C, S, CL> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<S>;
+    configAccess: ConfigAccess<C>;
+    clients: ClientsView<CL>;
+}
+export declare function createMiddlewareContext<C, S, CL>(params: MiddlewareContextParams<C, S, CL>): MiddlewareContext<C, S, CL>;
+/** `routers(ctx)` 入参 */
+export interface RouterContextParams<S, CL> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<S>;
+    clients: ClientsView<CL>;
+}
+export declare function createRouterContext<S, CL>(params: RouterContextParams<S, CL>): RouterContext<S, CL>;
+//# sourceMappingURL=context.d.ts.map

package/output/core/boot/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../source/core/boot/context.ts"],"names":[],"mappings":"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"}

package/output/core/boot/context.js

@@ -0,0 +1,106 @@
+import { SystemError } from '@taicode/common-base';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+export function liveResources(resources) {
+    const result = {};
+    for (const [key, value] of Object.entries(resources)) {
+        if (value !== false) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
+export function liveClients(clients) {
+    return liveResources(clients);
+}
+const CONFIG_WRITE = Symbol('config.write');
+export function createConfigAccess() {
+    let value;
+    const access = {
+        get available() {
+            return value !== undefined;
+        },
+        read() {
+            if (value === undefined) {
+                throw new SystemError('CONFIG_UNAVAILABLE', undefined, '配置尚未就绪（generateOpenApi 路径不跑 config 槽位）：任何单元不得在构造期读配置');
+            }
+            return value;
+        },
+        [CONFIG_WRITE](next) {
+            value = next;
+        },
+    };
+    return access;
+}
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export function provideConfig(access, value) {
+    const write = access[CONFIG_WRITE];
+    if (write === undefined) {
+        throw new Error('[config] 非法写入：`ConfigAccess` 只能由 `createConfigAccess()` 产出');
+    }
+    write(value);
+}
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export function readConfigKey(config, key) {
+    return config?.[key];
+}
+export function createResourcesContext(params) {
+    return {
+        env: params.env,
+        log: params.log,
+        disposer: params.disposer,
+        registerClassifyError: params.registerClassifyError,
+    };
+}
+export function createConfigContext(params) {
+    return { env: params.env, log: params.log, disposer: params.disposer, resources: params.resources };
+}
+export function createClientsContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createServiceContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        clients: params.clients,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createMiddlewareContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        disposer: params.disposer,
+        services: params.services,
+        clients: params.clients,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createRouterContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        disposer: params.disposer,
+        services: params.services,
+        clients: params.clients,
+    };
+}

package/output/core/boot/lifecycle.d.ts

@@ -0,0 +1,94 @@
+import type { Disposer } from '@taicode/common-base';
+import type { LoggerLike } from '../types.js';
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
+ * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
+ *
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
+ *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
+ * **`services` 额外有逐单元生命周期**：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - `init` 按**对象声明序**，`dispose` **逆序**；
+ * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
+ *
+ * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
+ */
+export declare const RESOURCES_STAGE = "resources";
+export declare const CONFIG_STAGE = "config";
+export declare const CLIENTS_STAGE = "clients";
+export declare const SERVICES_STAGE = "services";
+export declare const MIDDLEWARES_STAGE = "middlewares";
+export declare const ROUTERS_STAGE = "routers";
+/** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
+export declare const MIDDLEWARES_LOG_STAGE = "middlewares";
+/** 生命周期相位（逐单元日志字段 `phase`） */
+export declare const LIFECYCLE_PHASE_INIT = "init";
+export declare const LIFECYCLE_PHASE_DISPOSE = "dispose";
+export type LifecyclePhase = typeof LIFECYCLE_PHASE_INIT | typeof LIFECYCLE_PHASE_DISPOSE;
+/**
+ * 逐单元生命周期日志上下文。
+ *
+ * `log` / `service` 缺省时**不打日志**（纯单测可直接调用生命周期函数，不注入假 logger）。
+ * 字段名固定为全拼：`service` + `unit` + `stage` + `phase`。
+ */
+export interface LifecycleLogContext {
+    /** 日志标签（`defineServer({ app: { service } })`）；缺省时退路名字失去前缀 */
+    service?: string;
+    /** 记录型 logger（`ctx.log`）；缺省 = 不打日志 */
+    log?: LoggerLike;
+}
+/** 逐单元日志字段（全拼）：`unit` = 有效名字（阶段 flush 时为阶段名），`stage` = 阶段名 */
+export interface LifecycleUnitLogFields {
+    service: string;
+    unit: string;
+    stage: string;
+    phase: LifecyclePhase;
+}
+/**
+ * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ *
+ * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
+ */
+export declare function middlewareUnitName(service: string, key: string): string;
+/** `initServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface InitServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
+ */
+export declare function initServiceUnits(params: InitServiceUnitsParams): Promise<void>;
+/** `buildDisposeOrder` / `disposeServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface DisposeServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * 关闭步 `disposeServices`：`services` 声明序逆序释放。
+ *
+ * 单元级失败已在 `runLifecycleUnit` 内 `log.error`（带 service / unit / stage / phase）；
+ * 此处仅保证单步不阻断后续。
+ */
+export declare function disposeServices(params: DisposeServiceUnitsParams): Promise<void>;
+/** `disposeStage` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface DisposeStageParams extends LifecycleLogContext {
+    /** 阶段名（`routers` / `middlewares` / `services` / `config` / `resources`） */
+    stage: string;
+    /** 该阶段的 `Disposer`（构造期注册的清理函数，**逆注册序**执行） */
+    disposer: Disposer;
+}
+/**
+ * 关闭步：flush 某个阶段的 `disposer`。
+ *
+ * 单元名 = 阶段名（一个阶段一个 `Disposer`，不逐注册项打日志）；`phase` 固定 `dispose`。
+ * 单个清理函数失败由 `Disposer` 自己捕获记录，不影响同阶段其它函数。
+ */
+export declare function disposeStage(params: DisposeStageParams): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/output/core/boot/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../source/core/boot/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,eAAe,cAAc,CAAA;AAC1C,eAAO,MAAM,YAAY,WAAW,CAAA;AACpC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,cAAc,aAAa,CAAA;AACxC,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAC9C,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,gBAAoB,CAAA;AAEtD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,SAAS,CAAA;AAC1C,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,GAAG,OAAO,uBAAuB,CAAA;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,cAAc,CAAA;CACtB;AAaD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAmCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtF;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E"}

package/output/{app → core/boot}/lifecycle.js

@@ -1,15 +1,30 @@
 /**
  * 生命周期序（N1 §4 / N2 §2.5）。
  *
- * **只有 `services` 参与生命周期**：
+ * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
+ * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
+ *
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
+ *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
+ * **`services` 额外有逐单元生命周期**：
  * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
- * - 顺序语义只有一条：按**对象声明序** `init`、**逆序** `dispose`；
- * - `middlewares` 按数组序注册，**不参与生命周期**（要常驻资源就放 `services`）；
- * - `resources` 只是惰性包装（构造不建连），框架不替它们做生命周期。
+ * - `init` 按**对象声明序**，`dispose` **逆序**；
+ * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
+ *
+ * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
  */
+export const RESOURCES_STAGE = 'resources';
+export const CONFIG_STAGE = 'config';
+export const CLIENTS_STAGE = 'clients';
 export const SERVICES_STAGE = 'services';
-/** `middlewares` 的**注册期日志**阶段标签（中间件不参与生命周期，只用于注册日志） */
-export const MIDDLEWARES_LOG_STAGE = 'middlewares';
+export const MIDDLEWARES_STAGE = 'middlewares';
+export const ROUTERS_STAGE = 'routers';
+/** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
+export const MIDDLEWARES_LOG_STAGE = MIDDLEWARES_STAGE;
 /** 生命周期相位（逐单元日志字段 `phase`） */
 export const LIFECYCLE_PHASE_INIT = 'init';
 export const LIFECYCLE_PHASE_DISPOSE = 'dispose';
@@ -19,17 +34,16 @@ function isObject(value) {
 /**
  * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
  */
-export function serviceUnitName(key) {
+function serviceUnitName(key) {
     return key;
 }
 /**
- * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ *
+ * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
  */
-export function middlewareUnitName(service, unit, index) {
-    if (isObject(unit) && typeof unit.name === 'string' && unit.name.length > 0) {
-        return unit.name;
-    }
-    return `${service}:middleware[${index}]`;
+export function middlewareUnitName(service, key) {
+    return key.length > 0 ? key : `${service}:middleware`;
 }
 async function callInit(unit) {
     if (isObject(unit) && typeof unit.init === 'function') {
@@ -74,7 +88,7 @@ export async function initServiceUnits(params) {
 /**
  * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
  */
-export function buildDisposeOrder(params) {
+function buildDisposeOrder(params) {
     const steps = [];
     for (const key of Object.keys(params.services ?? {}).reverse()) {
         steps.push(() => runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_DISPOSE));
@@ -97,3 +111,20 @@ export async function disposeServices(params) {
         }
     }
 }
+/**
+ * 关闭步：flush 某个阶段的 `disposer`。
+ *
+ * 单元名 = 阶段名（一个阶段一个 `Disposer`，不逐注册项打日志）；`phase` 固定 `dispose`。
+ * 单个清理函数失败由 `Disposer` 自己捕获记录，不影响同阶段其它函数。
+ */
+export async function disposeStage(params) {
+    const fields = {
+        service: params.service ?? '',
+        unit: params.stage,
+        stage: params.stage,
+        phase: LIFECYCLE_PHASE_DISPOSE,
+    };
+    params.log?.debug(fields, `[lifecycle] ${LIFECYCLE_PHASE_DISPOSE} "${params.stage}" start`);
+    await params.disposer.dispose();
+    params.log?.debug(fields, `[lifecycle] ${LIFECYCLE_PHASE_DISPOSE} "${params.stage}" done`);
+}

package/output/core/boot/shutdown.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
+ *
+ * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
+ * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ *
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `flushResources`。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
+ */
+declare const SHUTDOWN_ORDER: readonly ["flushRouters", "flushMiddlewares", "flushServices", "disposeServices", "flushClients", "flushConfig", "flushResources"];
+type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
+type ShutdownHandles = Record<ShutdownStepName, () => void | Promise<void>>;
+export interface ShutdownLogger {
+    error: (obj: unknown, msg?: string) => void;
+}
+/**
+ * 顺序执行关闭步骤；单步抛错记录后**继续**后续步骤，最后聚合上报
+ * （避免「一步报错导致后面资源没关」）。
+ */
+export declare function runShutdown(handles: ShutdownHandles, log: ShutdownLogger): Promise<void>;
+export {};
+//# sourceMappingURL=shutdown.d.ts.map

package/output/core/boot/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../source/core/boot/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,cAAc,oIAQV,CAAA;AAEV,KAAK,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvD,KAAK,eAAe,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9F"}

package/output/core/boot/shutdown.js

@@ -0,0 +1,45 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
+ *
+ * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
+ * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ *
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `flushResources`。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
+ */
+const SHUTDOWN_ORDER = [
+    'flushRouters',
+    'flushMiddlewares',
+    'flushServices',
+    'disposeServices',
+    'flushClients',
+    'flushConfig',
+    'flushResources',
+];
+/**
+ * 顺序执行关闭步骤；单步抛错记录后**继续**后续步骤，最后聚合上报
+ * （避免「一步报错导致后面资源没关」）。
+ */
+export async function runShutdown(handles, log) {
+    const errors = [];
+    for (const step of SHUTDOWN_ORDER) {
+        try {
+            await handles[step]();
+        }
+        catch (error) {
+            errors.push(error);
+            log.error({ error, step }, '[shutdown] step failed');
+        }
+    }
+    if (errors.length > 0) {
+        log.error({ errors, count: errors.length }, '[shutdown] completed with errors');
+    }
+}

package/output/core/boot/signal.d.ts

@@ -0,0 +1,13 @@
+import type { LoggerLike } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
+ *
+ * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
+ * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
+ *
+ * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上
+ */
+export declare function attachSignalHandlers(app: FastifyInstance, log: LoggerLike): () => void;
+//# sourceMappingURL=signal.d.ts.map

package/output/core/boot/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../source/core/boot/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CA2CtF"}

package/output/{app → core/boot}/signal.js

@@ -2,9 +2,10 @@
  * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
  *
  * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
- * 的关闭 6 步）⇒ `process.exit(0/1)`。**仅 `listen: true` 时装信号处理**。
+ * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
  *
- * @returns detach 函数（移除本次注册的监听器）
+ * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上
  */
 export function attachSignalHandlers(app, log) {
     let closing = false;