@taicode/common-server 3.7.13 → 4.0.0-beta.1

package/output/app/redis.js

@@ -0,0 +1,61 @@
+import { createRedisClient, RedisCache } from '../redis-cache/index.js';
+/**
+ * 引导期 Redis / cache helper（N2 §2.13）。
+ *
+ * 在 `resources(ctx)` 槽位里按需调用（框架自己**不**创建 Redis）：
+ *
+ * ```ts
+ * resources: (ctx) => {
+ *   const redis = createRedis(ctx.env, ctx.log)          // 无 REDIS_URL → undefined
+ *   return { redis, cache: createCache({ env: ctx.env, prefix: 'account', redis }) }
+ * }
+ * ```
+ *
+ * `REDIS_URL` 由 helper 直接读 `env`（固定约定），**不**取自 `config`；`redis` / `cache` 一律是
+ * **惰性包装**：构造时不建连、不 ping，首次真正使用才建连 —— 「出 spec 不连库/Redis」结构性成立。
+ */
+/** 一级/二级缓存默认 TTL（秒），与 `RedisCache` 默认一致 */
+export const DEFAULT_REDIS_CACHE_TTL_SECONDS = 300;
+/**
+ * 构造 Redis 句柄（惰性包装：不建连、不 ping）。
+ *
+ * 无 `REDIS_URL` 时返回 `undefined` —— 资源包里写成 `redis: RedisHandle | undefined` 即可
+ * （显式可选，运行时缺省）。
+ */
+export function createRedis(env, log) {
+    const redisUrl = env.REDIS_URL;
+    if (!redisUrl) {
+        log?.debug({}, '[redis] REDIS_URL not configured; cache falls back to in-process L1');
+        return undefined;
+    }
+    const client = createRedisClient({ url: redisUrl });
+    return {
+        client,
+        dispose: async () => {
+            if (client.isOpen) {
+                await client.quit().catch(() => undefined);
+            }
+            else {
+                client.destroy();
+            }
+        },
+    };
+}
+/**
+ * 构造缓存（前缀由调用方给出）。
+ *
+ * - 传 `redis` → 复用同一个客户端；
+ * - 未传 `redis` 但有 `REDIS_URL` → 自建客户端（由 `RedisCache` 自己持有并断开）；
+ * - 都没有 → 纯进程内一级缓存（不建连）。
+ */
+export function createCache(params) {
+    if (params.redis) {
+        return new RedisCache({ prefix: params.prefix, redisClient: params.redis.client });
+    }
+    const redisUrl = params.env.REDIS_URL;
+    if (redisUrl) {
+        return new RedisCache({ prefix: params.prefix, redisUrl });
+    }
+    params.log?.debug({}, '[redis] REDIS_URL not configured; cache falls back to in-process L1');
+    return new RedisCache({ prefix: params.prefix });
+}

package/output/app/registered-operations.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registered-operations.test.d.ts.map

package/output/app/registered-operations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered-operations.test.d.ts","sourceRoot":"","sources":["../../source/app/registered-operations.test.ts"],"names":[],"mappings":""}

package/output/app/registered-operations.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { createContextMiddleware } from './middleware/context.js';
+import { readRegisteredOperations, toPermissionOperations } from './permission-operations.js';
+/**
+ * 路由注册表 + swagger 时序。
+ *
+ * 关键点：自定义 `middlewares`（**不含 cors**）时，swagger 插件体也必须在任何路由注册之前执行完
+ * （`registerOpenApi` 内 `await app.after()`），路由注册表同样非空——两者都不依赖「恰好有 cors
+ * 顺带冲刷队列」这种隐式巧合。
+ */
+const listWidgetSchema = {
+    operationId: 'listWidget',
+    summary: 'List widgets',
+    tags: ['Widget'],
+};
+/** 未声明 `operationId` 的路由（回落 url，且不进权限目录） */
+const plainSchema = {};
+function createServer() {
+    return defineServer({
+        app: { service: 'registry', title: 'Registry', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        // 自定义中间件：只有 context，**没有 cors**（不得靠 cors 冲刷 swagger 队列）
+        middlewares: () => [createContextMiddleware()],
+        routers: (ctx) => {
+            ctx.app.get('/widget/list', { schema: listWidgetSchema }, () => ({ items: [] }));
+            ctx.app.post('/widget/plain', { schema: plainSchema }, () => ({ ok: true }));
+        },
+    });
+}
+describe('路由注册表', () => {
+    it('自定义 middlewares（无 cors）时，注册表非空且能拿到 operationId', async () => {
+        const app = await startServer(createServer(), { listen: false });
+        try {
+            const operations = readRegisteredOperations(app);
+            expect(operations.length).toBeGreaterThan(0);
+            const listWidget = operations.find((entry) => entry.url === '/widget/list');
+            expect(listWidget).toMatchObject({ method: 'GET', url: '/widget/list', operationId: 'listWidget' });
+            // Fastify 为 GET 自动生成的 HEAD 路由不进注册表（与 swagger 同口径）
+            expect(operations.some((entry) => entry.method === 'HEAD')).toBe(false);
+            // 未声明 operationId 的路由不进权限目录
+            expect(toPermissionOperations(operations)).toEqual([
+                { operation: 'listWidget', summary: 'List widgets', description: '', tags: ['Widget'] },
+            ]);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('自定义 middlewares（无 cors）时，swagger 文档仍包含已注册路由（确定性冲刷）', async () => {
+        const spec = (await generateOpenApi(createServer()));
+        const paths = spec.paths ?? {};
+        expect(Object.keys(paths)).toEqual(expect.arrayContaining(['/widget/list', '/widget/plain']));
+    });
+});

package/output/app/request-id.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=request-id.test.d.ts.map

package/output/app/request-id.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.test.d.ts","sourceRoot":"","sources":["../../source/app/request-id.test.ts"],"names":[],"mappings":""}

package/output/app/request-id.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import { createRequestIdOptions, normalizeInboundRequestId, REQUEST_ID_HEADER, REQUEST_ID_LOG_LABEL, } from './core/request-id.js';
+import { defineServer, startServer } from './entries.js';
+/**
+ * `requestId` 契约（设计 §5.1 / §8）——**框架内置、锁定**。
+ *
+ * 入站 `x-request-id` 存在且非空 → 复用，否则 `randomUUID`；响应 header 统一回吐
+ * `x-request-id`；**不进响应体**；日志字段键名统一为全拼 `requestId`。
+ */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function createRequestIdServer() {
+    return defineServer({
+        app: { service: 'request-id-test', title: 'Request Id Test', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            ctx.app.get('/echo', () => ({ ok: true }));
+        },
+    });
+}
+/** 启动一个可读取请求日志 bindings 的 app（`x-request-id` 归一化断言用） */
+async function startBindingApp() {
+    let bindings;
+    const server = defineServer({
+        app: { service: 'request-id-normalize', title: 'Request Id Normalize', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            ctx.app.addHook('onRequest', (request, _reply, done) => {
+                bindings = request.log.bindings();
+                done();
+            });
+            ctx.app.get('/echo', () => ({ ok: true }));
+        },
+    });
+    const app = await startServer(server, { listen: false });
+    return { app, getBindings: () => bindings };
+}
+describe('requestId（设计 §5.1 / §8）', () => {
+    it('固定 header 名与日志字段名', () => {
+        expect(REQUEST_ID_HEADER).toBe('x-request-id');
+        expect(REQUEST_ID_LOG_LABEL).toBe('requestId');
+        const options = createRequestIdOptions();
+        expect(options.requestIdHeader).toBe('x-request-id');
+        expect(options.requestIdLogLabel).toBe('requestId');
+    });
+    it('genReqId：入站值非空则复用，否则生成 UUID', () => {
+        const { genReqId } = createRequestIdOptions();
+        expect(genReqId({ headers: { 'x-request-id': 'abc' } })).toBe('abc');
+        expect(genReqId({ headers: { 'x-request-id': ['abc', 'def'] } })).toBe('abc');
+        expect(genReqId({ headers: {} })).toMatch(UUID_PATTERN);
+        expect(genReqId({ headers: { 'x-request-id': '   ' } })).toMatch(UUID_PATTERN);
+    });
+    it('normalizeInboundRequestId：trim 后为空视为缺失（undefined），非空返回 trim 值', () => {
+        expect(normalizeInboundRequestId(undefined)).toBeUndefined();
+        expect(normalizeInboundRequestId('')).toBeUndefined();
+        expect(normalizeInboundRequestId('   ')).toBeUndefined();
+        expect(normalizeInboundRequestId('trace-abc')).toBe('trace-abc');
+        expect(normalizeInboundRequestId('  trace-abc  ')).toBe('trace-abc');
+        expect(normalizeInboundRequestId(['abc', 'def'])).toBe('abc');
+    });
+    it('空白入站 header → 视为缺失，重新生成 UUID（request.id / 日志字段 / 响应 header 一致）', async () => {
+        const { app, getBindings } = await startBindingApp();
+        const response = await app.inject({ method: 'GET', url: '/echo', headers: { [REQUEST_ID_HEADER]: '   ' } });
+        expect(response.statusCode).toBe(200);
+        const requestId = String(response.headers[REQUEST_ID_HEADER]);
+        expect(requestId).toMatch(UUID_PATTERN);
+        expect(getBindings()).toEqual({ [REQUEST_ID_LOG_LABEL]: requestId });
+        await app.close();
+    });
+    it('带空格的入站 header → trim 后复用（request.id / 日志字段 / 响应 header 一致）', async () => {
+        const { app, getBindings } = await startBindingApp();
+        const response = await app.inject({
+            method: 'GET',
+            url: '/echo',
+            headers: { [REQUEST_ID_HEADER]: '  trace-trim  ' },
+        });
+        expect(response.statusCode).toBe(200);
+        expect(response.headers[REQUEST_ID_HEADER]).toBe('trace-trim');
+        expect(getBindings()).toEqual({ [REQUEST_ID_LOG_LABEL]: 'trace-trim' });
+        await app.close();
+    });
+    it('缺失入站 header → 生成 UUID（request.id / 日志字段 / 响应 header 一致）', async () => {
+        const { app, getBindings } = await startBindingApp();
+        const response = await app.inject({ method: 'GET', url: '/echo' });
+        expect(response.statusCode).toBe(200);
+        const requestId = String(response.headers[REQUEST_ID_HEADER]);
+        expect(requestId).toMatch(UUID_PATTERN);
+        expect(getBindings()).toEqual({ [REQUEST_ID_LOG_LABEL]: requestId });
+        await app.close();
+    });
+    it('复用入站 header 并回吐到响应 header；日志绑定字段为 requestId；不进响应体', async () => {
+        let bindings;
+        const server = defineServer({
+            app: { service: 'request-id-integration', title: 'Request Id Integration', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.addHook('onRequest', (request, _reply, done) => {
+                    bindings = request.log.bindings();
+                    done();
+                });
+                ctx.app.get('/echo', () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        const reused = await app.inject({ method: 'GET', url: '/echo', headers: { 'x-request-id': 'trace-abc' } });
+        expect(reused.statusCode).toBe(200);
+        expect(reused.headers[REQUEST_ID_HEADER]).toBe('trace-abc');
+        expect(bindings).toEqual({ requestId: 'trace-abc' });
+        expect(reused.body).not.toContain('trace-abc');
+        const generated = await app.inject({ method: 'GET', url: '/echo' });
+        expect(String(generated.headers[REQUEST_ID_HEADER])).toMatch(UUID_PATTERN);
+        expect(bindings).toHaveProperty(REQUEST_ID_LOG_LABEL);
+        await app.close();
+    });
+    it('startServer 冒烟：定义可跑、路由可用', async () => {
+        const app = await startServer(createRequestIdServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/echo' });
+        expect(response.statusCode).toBe(200);
+        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { ok: true } });
+        await app.close();
+    });
+});

package/output/app/resources.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resources.test.d.ts.map

package/output/app/resources.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.test.d.ts","sourceRoot":"","sources":["../../source/app/resources.test.ts"],"names":[],"mappings":""}

package/output/app/resources.test.js

@@ -0,0 +1,197 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { createTestConfigEnv } from './test-support.js';
+/** 资源包实现（显式标注返回类型：否则资源实现的回调参数会吃隐式 `any`） */
+function createResources() {
+    return {
+        database: { query: (sql) => `rows:${sql}` },
+        cache: { read: (key) => `${key}:cached` },
+        telemetry: false,
+        queue: undefined,
+    };
+}
+// ── 类型自证：`false` 键在 `Live<TestResources>` 中被剔除 ─────────
+const assertLiveKeysRemovesFalse = () => {
+    expectTypeOf().toEqualTypeOf();
+};
+void assertLiveKeysRemovesFalse;
+describe('resources 槽位（N1 §2 / N2 §2.3）', () => {
+    it('① 入参只有 env + log，且资源嵌套在 ctx.resources 下（config / services 都能用）', async () => {
+        let captured;
+        const observed = {};
+        const server = defineServer({
+            app: { service: 'resources-basic', title: 'Resources Basic', version: '1.0.0' },
+            resources: (ctx) => {
+                captured = ctx;
+                return createResources();
+            },
+            config: (ctx) => {
+                // 类型自证：精确到资源包里的声明类型（不是 unknown / any）
+                expectTypeOf(ctx.resources.database.query).toEqualTypeOf();
+                observed.inConfig = ctx.resources.database.query('select 1');
+                return { domain: 'example.com' };
+            },
+            services: (ctx) => {
+                expectTypeOf(ctx.resources.cache.read).toEqualTypeOf();
+                observed.inServices = ctx.resources.cache.read('domain');
+                return {};
+            },
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/resource', () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            expect(Object.keys(captured ?? {}).sort()).toEqual(['env', 'log']);
+            expect(captured?.env.ENV).toBeTypeOf('string');
+            expect(typeof captured?.log.info).toBe('function');
+            expect(observed.inConfig).toBe('rows:select 1');
+            expect(observed.inServices).toBe('domain:cached');
+            const response = await app.inject({ method: 'GET', url: '/resource' });
+            expect(response.statusCode).toBe(200);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('② `false` 关闭资源：装配正常，键在类型与运行时都不存在', async () => {
+        let ctxInServices;
+        const server = defineServer({
+            app: { service: 'resources-disabled', title: 'Resources Disabled', version: '1.0.0' },
+            resources: createResources,
+            config: () => ({}),
+            services: (ctx) => {
+                // 编译期：`telemetry` 被 `Live<>` 剔除 → 访问必须编译失败
+                // @ts-expect-error `telemetry: false` 已从资源视图中剔除
+                void ctx.resources.telemetry;
+                ctxInServices = ctx;
+                return {};
+            },
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/alive', () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            // 运行时也不存在该键（与类型一致）
+            const resources = ctxInServices.resources;
+            expect('telemetry' in resources).toBe(false);
+            const response = await app.inject({ method: 'GET', url: '/alive' });
+            expect(response.statusCode).toBe(200);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('③ 缺省可选资源：类型为 `T | undefined`，运行时为 undefined（键仍在）', async () => {
+        const observed = {};
+        const server = defineServer({
+            app: { service: 'resources-optional', title: 'Resources Optional', version: '1.0.0' },
+            resources: createResources,
+            config: (ctx) => {
+                expectTypeOf(ctx.resources.queue).toEqualTypeOf();
+                observed.inConfig = ctx.resources.queue;
+                return {};
+            },
+            services: (ctx) => {
+                observed.inServices = ctx.resources.queue;
+                observed.keys = Object.keys(ctx.resources);
+                return {};
+            },
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            expect(observed.inConfig).toBeUndefined();
+            expect(observed.inServices).toBeUndefined();
+            expect(observed.keys).toContain('queue');
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('④ resources 允许异步：返回 Promise<资源包> 时同样是精确类型', async () => {
+        let domain;
+        const server = defineServer({
+            app: { service: 'resources-async', title: 'Resources Async', version: '1.0.0' },
+            resources: async () => ({
+                database: { query: (sql) => `async:${sql}` },
+            }),
+            config: (ctx) => {
+                expectTypeOf(ctx.resources.database.query).toEqualTypeOf();
+                return { domain: ctx.resources.database.query('domain') };
+            },
+            services: (ctx) => {
+                domain = ctx.config.domain;
+                return {};
+            },
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            expect(domain).toBe('async:domain');
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('⑤ 框架不管资源生命周期：资源上的 dispose 不被调用（释放要放 services）', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'resources-lifecycle', title: 'Resources Lifecycle', version: '1.0.0' },
+            resources: () => ({
+                database: {
+                    dispose: () => {
+                        calls.push('dispose:resource');
+                    },
+                },
+            }),
+            config: () => ({}),
+            services: () => ({
+                databaseClient: {
+                    dispose: () => {
+                        calls.push('dispose:service');
+                    },
+                },
+            }),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        await app.close();
+        expect(calls).toEqual(['dispose:service']);
+    });
+    it('⑥ 出 spec 路径同样跑 resources（只构造，不建连）', async () => {
+        let calls = 0;
+        const server = defineServer({
+            app: { service: 'resources-openapi', title: 'Resources OpenApi', version: '1.0.0' },
+            resources: () => {
+                calls += 1;
+                return {};
+            },
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        await generateOpenApi(server);
+        expect(calls).toBe(1);
+    });
+});
+/** `ResourcesView` 自证：`Awaited<>` 归一（同步 / 异步两写法等价） */
+const assertResourcesViewNormalizes = () => {
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+};
+void assertResourcesViewNormalizes;
+/** 测试用 env 自证：固定读取约定里的五项 */
+const assertTestConfigEnv = () => {
+    expectTypeOf(createTestConfigEnv().ENV).toEqualTypeOf();
+};
+void assertTestConfigEnv;

package/output/app/shutdown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * 新口径下框架不再持有 Redis / 数据库 / 外链客户端（这些都在 `resources` 里，由各仓自行构造，
+ * 需要释放时放 `services` 单元）；配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ *
+ * 固定两步：`stopProducers`（`ctx.disposer` 注册的清理）→ `disposeServices`（services 逆序）。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
+ */
+export declare const SHUTDOWN_ORDER: readonly ["stopProducers", "disposeServices"];
+export type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
+export 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>;
+//# sourceMappingURL=shutdown.d.ts.map

package/output/app/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../source/app/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,+CAAgD,CAAA;AAE3E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAElF,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/app/shutdown.js

@@ -0,0 +1,30 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * 新口径下框架不再持有 Redis / 数据库 / 外链客户端（这些都在 `resources` 里，由各仓自行构造，
+ * 需要释放时放 `services` 单元）；配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ *
+ * 固定两步：`stopProducers`（`ctx.disposer` 注册的清理）→ `disposeServices`（services 逆序）。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
+ */
+export const SHUTDOWN_ORDER = ['stopProducers', 'disposeServices'];
+/**
+ * 顺序执行关闭步骤；单步抛错记录后**继续**后续步骤，最后聚合上报
+ * （避免「一步报错导致后面资源没关」）。
+ */
+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/app/shutdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shutdown.test.d.ts.map

package/output/app/shutdown.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.test.d.ts","sourceRoot":"","sources":["../../source/app/shutdown.test.ts"],"names":[],"mappings":""}

package/output/app/shutdown.test.js

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { defineServer, startServer } from './entries.js';
+import { runShutdown, SHUTDOWN_ORDER } from './shutdown.js';
+function createShutdownLog() {
+    const entries = [];
+    return { entries, log: { error: (obj, msg) => void entries.push({ obj, msg }) } };
+}
+function createRecordingHandles(record, throwOn) {
+    const step = (name) => () => {
+        record.push(name);
+        if (name === throwOn) {
+            throw new Error(`boom:${name}`);
+        }
+    };
+    return {
+        stopProducers: step('stopProducers'),
+        disposeServices: step('disposeServices'),
+    };
+}
+describe('SHUTDOWN_ORDER', () => {
+    it('固定两步且顺序不可变', () => {
+        expect(SHUTDOWN_ORDER).toEqual(['stopProducers', 'disposeServices']);
+    });
+});
+describe('runShutdown', () => {
+    it('按固定序执行全部步骤', async () => {
+        const record = [];
+        const { log } = createShutdownLog();
+        await runShutdown(createRecordingHandles(record), log);
+        expect(record).toEqual([...SHUTDOWN_ORDER]);
+    });
+    it('单步抛错不阻断后续，并聚合上报', async () => {
+        const record = [];
+        const { entries, log } = createShutdownLog();
+        await runShutdown(createRecordingHandles(record, 'stopProducers'), log);
+        expect(record).toEqual([...SHUTDOWN_ORDER]);
+        const aggregate = entries.find((entry) => entry.msg === '[shutdown] completed with errors');
+        expect(aggregate).toBeDefined();
+        const payload = aggregate?.obj;
+        expect(payload.count).toBe(1);
+        expect(payload.errors).toHaveLength(1);
+    });
+});
+describe('关闭流程集成', () => {
+    it('默认两步按序执行：disposer → services 逆序', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'shutdown-integration', title: 'Shutdown Integration', version: '1.0.0' },
+            resources: () => ({ database: { dispose: () => calls.push('disposeResource') } }),
+            config: () => ({}),
+            services: (ctx) => {
+                ctx.disposer.addDisposer(() => {
+                    calls.push('stopProducers');
+                });
+                return {
+                    a: {
+                        dispose: () => {
+                            calls.push('disposeServiceA');
+                        },
+                    },
+                    b: {
+                        dispose: () => {
+                            calls.push('disposeServiceB');
+                        },
+                    },
+                };
+            },
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        await app.close();
+        // 资源不在生命周期内（框架只管 services）
+        expect(calls).toEqual(['stopProducers', 'disposeServiceB', 'disposeServiceA']);
+    });
+    it('StartServerOptions.shutdown 整体覆盖默认关闭流程', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'shutdown-override', title: 'Shutdown Override', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({
+                a: {
+                    dispose: () => {
+                        calls.push('default-dispose');
+                    },
+                },
+            }),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, {
+            listen: false,
+            shutdown: async (ctx) => {
+                expect(ctx.app).toBeDefined();
+                expect(ctx.services).toBeDefined();
+                calls.push('custom');
+            },
+        });
+        await app.close();
+        expect(calls).toEqual(['custom']);
+    });
+});

package/output/app/signal.d.ts

@@ -0,0 +1,12 @@
+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)`。**仅 `listen: true` 时装信号处理**。
+ *
+ * @returns detach 函数（移除本次注册的监听器）
+ */
+export declare function attachSignalHandlers(app: FastifyInstance, log: LoggerLike): () => void;
+//# sourceMappingURL=signal.d.ts.map

package/output/app/signal.d.ts.map

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