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

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,199 @@
+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 + registerClassifyError，且资源嵌套在 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', 'registerClassifyError']);
+            expect(captured?.env.ENV).toBeTypeOf('string');
+            expect(typeof captured?.log.info).toBe('function');
+            // resources 槽位专属能力：每个资源注册自己的错误分类器（函数）
+            expect(typeof captured?.registerClassifyError).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

@@ -1,9 +1,22 @@
 /**
- * 固定关闭 7 步（design §5）——**顺序写死在数组里**。
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
  *
- * 关键修正（相对现状）：Redis 晚于 queue/cache 消费者释放；afterInit（如 LDAP）资源进第 1 步。
- * 单步抛错记录后**继续**后续步骤，最后聚合上报（避免「config 报错导致 DB 没关」）。
+ * 新口径下框架不再持有 Redis / 数据库 / 外链客户端（这些都在 `resources` 里，由各仓自行构造，
+ * 需要释放时放 `services` 单元）；配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ *
+ * 固定两步：`stopProducers`（`ctx.disposer` 注册的清理）→ `disposeServices`（services 逆序）。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
  */
-export declare const SHUTDOWN_ORDER: readonly ["stopProducers", "unsubscribeConfig", "disposeConfig", "disposeServices", "disposeClients", "disposeRedis", "disposeDb"];
+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

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../source/app/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,oIAQjB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA"}
+{"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

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