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

package/output/app/middleware-order.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineServer, startServer } from './entries.js';
+import { defaultMiddlewares } from './middleware/index.js';
+/**
+ * 中间件数组序（N1 §1 / §4）。
+ *
+ * `middlewares(ctx)` 返回**有序数组**，框架**严格按数组序**注册（无键、无枚举、无内置相对顺序魔法）；
+ * `rateLimit` **不在**默认预设内。中间件单元是 `{ name?, register(app) }`：**不参与生命周期**。
+ */
+const fakeMiddlewareContext = {
+    app: {},
+    log: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+    services: {},
+    config: {},
+};
+describe('ctx 可见性（N1 §2）', () => {
+    it('MiddlewareContext 有 app / log / services / config；没有 resources / env / disposer', () => {
+        expectTypeOf().toHaveProperty('app');
+        expectTypeOf().toHaveProperty('services');
+        expectTypeOf().toHaveProperty('config');
+        // @ts-expect-error 中间件看不到 resources（禁直连数据层）
+        void 0..resources;
+        // @ts-expect-error 中间件看不到 env
+        void 0..env;
+        // @ts-expect-error 中间件看不到 disposer（disposer 只属 services）
+        void 0..disposer;
+    });
+});
+describe('默认预设', () => {
+    it('defaultMiddlewares 为 [cors, context, auth]，且不含 rateLimit', () => {
+        const units = defaultMiddlewares(fakeMiddlewareContext);
+        expect(units.map((unit) => unit.name)).toEqual(['cors', 'context', 'auth']);
+        expect(units.map((unit) => unit.name)).not.toContain('rateLimit');
+    });
+});
+describe('数组序即注册序', () => {
+    it('严格按数组序执行每一项注册的钩子', async () => {
+        const calls = [];
+        const makeUnit = (name) => ({
+            name,
+            register: (app) => {
+                app.addHook('preValidation', (_request, _reply, done) => {
+                    calls.push(name);
+                    done();
+                });
+            },
+        });
+        const server = defineServer({
+            app: { service: 'middleware-order', title: 'Middleware Order', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [makeUnit('third'), makeUnit('first'), makeUnit('second')],
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ pong: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/ping' });
+        expect(response.statusCode).toBe(200);
+        expect(calls).toEqual(['third', 'first', 'second']);
+        await app.close();
+    });
+    it('ctx.services 与 services 槽位产物是同一个实例（M5 强类型）', async () => {
+        const servicesValue = { user: { find: (id) => `user:${id}` } };
+        let seen;
+        let seenFind;
+        const server = defineServer({
+            app: { service: 'middleware-services', title: 'Middleware Services', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => servicesValue,
+            middlewares: (ctx) => {
+                seen = ctx.services;
+                seenFind = ctx.services.user.find;
+                return [];
+            },
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ pong: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        expect(seen).toBe(servicesValue);
+        expect(seenFind).toBe(servicesValue.user.find);
+        await app.close();
+    });
+    it('注册的钩子返回 reply → 终止链（后续单元不执行）', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'middleware-terminate', title: 'Middleware Terminate', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [
+                {
+                    name: 'short',
+                    register: (app) => {
+                        app.addHook('preValidation', (_request, reply, done) => {
+                            calls.push('short');
+                            void reply.status(418).send({ stopped: true });
+                            done();
+                        });
+                    },
+                },
+                {
+                    name: 'after',
+                    register: (app) => {
+                        app.addHook('preValidation', (_request, _reply, done) => {
+                            calls.push('after');
+                            done();
+                        });
+                    },
+                },
+            ],
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ pong: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/ping' });
+        expect(response.statusCode).toBe(418);
+        expect(calls).toEqual(['short']);
+        await app.close();
+    });
+    it('出 spec 路径也注册中间件（保证 schema 一致）', async () => {
+        const { generateOpenApi } = await import('./entries.js');
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'middleware-openapi', title: 'Middleware OpenApi', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [
+                {
+                    name: 'probe',
+                    register: () => {
+                        calls.push('register:probe');
+                    },
+                },
+            ],
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ pong: true }));
+            },
+        });
+        await generateOpenApi(server);
+        expect(calls).toEqual(['register:probe']);
+    });
+});

package/output/app/permission-operations.d.ts

@@ -0,0 +1,48 @@
+import type { FastifyInstance } from 'fastify';
+/**
+ * 权限操作提取（设计 §5.2）——**框架内置**。
+ *
+ * 两条来源：
+ *
+ * 1. **路由注册表**（`installRegisteredOperations` / `readRegisteredOperations`）：core 装配期
+ *    在 root 挂 `onRoute` 钩子，采集每条路由的 `{ method, url, operationId, summary, description, tags }`。
+ *    `auth` 的权限自注册只读这张表，**不依赖 `app.swagger()`**（swagger 只负责出文档）。
+ * 2. **OpenAPI 文档提取**（`extractPermissionOperations`）：从 `paths` 提取。
+ *    各仓的 `onReady` 自注册（如 account 作为签发方走进程内调用）用它与 `app.swagger()` 配合，
+ *    **替代各仓自写实现**（已从公共面导出）。
+ *
+ * 目录元素形状（`{ operation, summary?, description?, tags? }`）与各仓原自写实现一致：
+ *
+ * - 缺 `operationId` 的条目（如 `parameters` / vendor 扩展 / 文档路由）**跳过**；
+ * - 缺 `paths` / 空文档 → 返回 `[]`；
+ * - `summary` / `description` / `tags` 缺省分别归一为 `''` / `''` / `[]`。
+ */
+/** 单条权限操作（对齐 account `POST /permission/operation/register` 的 `operations` 元素） */
+export interface PermissionOperation {
+    operation: string;
+    summary: string;
+    description: string;
+    tags: string[];
+}
+/** 单条已注册路由的采集项（`onRoute` 期收集；`operationId` 缺省表示该路由未声明） */
+export interface RegisteredOperation {
+    method: string;
+    url: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+}
+/**
+ * 在 root 挂 `onRoute` 钩子，收集框架自身可见的**路由注册表**（设计 §5.2）。
+ *
+ * 必须在**路由注册之前**（core 装配期）调用：钩子挂在 root，随后 `routers` 阶段注册的路由逐条被采集。
+ * 该表与 swagger 解耦：swagger 只负责出文档，`auth` 的权限自注册只读这张表。
+ */
+export declare function installRegisteredOperations(app: FastifyInstance): void;
+/** 读取 root `onRoute` 采集的路由注册表；未安装（未走框架装配）时返回空数组。 */
+export declare function readRegisteredOperations(app: FastifyInstance): RegisteredOperation[];
+/** 从路由注册表筛出声明了 `operationId` 的项，归一为权限操作目录元素 */
+export declare function toPermissionOperations(operations: readonly RegisteredOperation[]): PermissionOperation[];
+export declare function extractPermissionOperations(openApiSpec: unknown): PermissionOperation[];
+//# sourceMappingURL=permission-operations.d.ts.map

package/output/app/permission-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-operations.d.ts","sourceRoot":"","sources":["../../source/app/permission-operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,SAAS,CAAA;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAeD,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAaD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CA+BtE;AAED,oDAAoD;AACpD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,eAAe,GAAG,mBAAmB,EAAE,CAIpF;AAED,+CAA+C;AAC/C,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAcxG;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,OAAO,GAAG,mBAAmB,EAAE,CAoBvF"}

package/output/app/permission-operations.js

@@ -0,0 +1,77 @@
+/** 路由注册表在 `app` 上的存放键（Symbol，不进公共契约） */
+const REGISTERED_OPERATIONS = Symbol.for('@taicode/common-server/registered-operations');
+/**
+ * 在 root 挂 `onRoute` 钩子，收集框架自身可见的**路由注册表**（设计 §5.2）。
+ *
+ * 必须在**路由注册之前**（core 装配期）调用：钩子挂在 root，随后 `routers` 阶段注册的路由逐条被采集。
+ * 该表与 swagger 解耦：swagger 只负责出文档，`auth` 的权限自注册只读这张表。
+ */
+export function installRegisteredOperations(app) {
+    const collected = [];
+    Object.defineProperty(app, REGISTERED_OPERATIONS, {
+        value: collected,
+        enumerable: false,
+        configurable: true,
+    });
+    app.addHook('onRoute', (routeOptions) => {
+        const routeConfig = (routeOptions.config ?? {});
+        // 与 `@fastify/swagger` 同口径：Fastify 默认为 GET 自动生成 HEAD 路由；未显式
+        // `config.swagger.exposeHeadRoute = true` 时跳过，避免与 GET 重复（权限目录保持同源）。
+        if (routeOptions.method === 'HEAD' && routeConfig.swagger?.exposeHeadRoute !== true) {
+            return;
+        }
+        const schema = (routeOptions.schema ?? {});
+        const methods = Array.isArray(routeOptions.method)
+            ? routeOptions.method
+            : [routeOptions.method];
+        for (const method of methods) {
+            collected.push({
+                method,
+                url: routeOptions.url,
+                operationId: schema.operationId,
+                summary: schema.summary,
+                description: schema.description,
+                tags: schema.tags,
+            });
+        }
+    });
+}
+/** 读取 root `onRoute` 采集的路由注册表；未安装（未走框架装配）时返回空数组。 */
+export function readRegisteredOperations(app) {
+    return (app[REGISTERED_OPERATIONS] ?? []);
+}
+/** 从路由注册表筛出声明了 `operationId` 的项，归一为权限操作目录元素 */
+export function toPermissionOperations(operations) {
+    const result = [];
+    for (const entry of operations) {
+        if (!entry.operationId) {
+            continue;
+        }
+        result.push({
+            operation: entry.operationId,
+            summary: entry.summary ?? '',
+            description: entry.description ?? '',
+            tags: entry.tags ?? [],
+        });
+    }
+    return result;
+}
+export function extractPermissionOperations(openApiSpec) {
+    // 出 spec 路径拿到的文档是未知形态；只按结构取字段，缺什么就跳过什么
+    const spec = (openApiSpec ?? {});
+    const operations = [];
+    for (const pathItem of Object.values(spec.paths ?? {})) {
+        for (const operation of Object.values(pathItem ?? {})) {
+            if (!operation?.operationId) {
+                continue;
+            }
+            operations.push({
+                operation: operation.operationId,
+                summary: operation.summary ?? '',
+                description: operation.description ?? '',
+                tags: operation.tags ?? [],
+            });
+        }
+    }
+    return operations;
+}

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

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

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

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

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

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { extractPermissionOperations } from './permission-operations.js';
+/**
+ * `extractPermissionOperations`（设计 §5.2，框架内置）契约。
+ *
+ * 口径与各仓原自写实现一致：逐 path → 逐 method，缺 `operationId` 跳过；缺 `paths` / 空文档 → `[]`；
+ * `summary` / `description` / `tags` 缺省归一为 `''` / `''` / `[]`。
+ */
+describe('extractPermissionOperations（设计 §5.2）', () => {
+    it('提取 operationId 与可选元信息（summary / description / tags）', () => {
+        expect(extractPermissionOperations({
+            paths: {
+                '/release/list': {
+                    post: {
+                        operationId: 'listRelease',
+                        summary: 'List releases',
+                        description: 'Returns available releases.',
+                        tags: ['Release'],
+                    },
+                },
+            },
+        })).toEqual([
+            {
+                operation: 'listRelease',
+                summary: 'List releases',
+                description: 'Returns available releases.',
+                tags: ['Release'],
+            },
+        ]);
+    });
+    it('可选元信息缺省归一，且跳过无 operationId 的条目', () => {
+        expect(extractPermissionOperations({
+            paths: {
+                '/release/create': {
+                    post: { operationId: 'createRelease' },
+                    parameters: { description: 'Shared parameters' },
+                },
+            },
+        })).toEqual([
+            {
+                operation: 'createRelease',
+                summary: '',
+                description: '',
+                tags: [],
+            },
+        ]);
+    });
+    it('缺 paths 时返回空数组', () => {
+        expect(extractPermissionOperations({})).toEqual([]);
+    });
+    it('空文档 / 非对象入参返回空数组', () => {
+        expect(extractPermissionOperations({ paths: {} })).toEqual([]);
+        expect(extractPermissionOperations(undefined)).toEqual([]);
+    });
+    it('多路径 + 多方法：按 paths → methods 的遍历序全量提取', () => {
+        expect(extractPermissionOperations({
+            paths: {
+                '/widget/list': {
+                    get: { operationId: 'listWidget', tags: ['Widget'] },
+                    post: { operationId: 'queryWidget' },
+                },
+                '/widget/create': {
+                    post: { operationId: 'createWidget', summary: 'Create widget' },
+                },
+            },
+        })).toEqual([
+            { operation: 'listWidget', summary: '', description: '', tags: ['Widget'] },
+            { operation: 'queryWidget', summary: '', description: '', tags: [] },
+            { operation: 'createWidget', summary: 'Create widget', description: '', tags: [] },
+        ]);
+    });
+});

package/output/app/permission-registration.test.d.ts

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

package/output/app/permission-registration.test.d.ts.map

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

package/output/app/permission-registration.test.js

@@ -0,0 +1,138 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { defaultMiddlewares } from './middleware/index.js';
+import { createAuthMiddleware } from './middleware/auth.js';
+/** 注入假 fetch：记录请求，并按 `responder` 返回最小 Response 形状 */
+function stubFetch(responder) {
+    const requests = [];
+    const fetchStub = vi.fn(async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        requests.push({
+            url,
+            method: init?.method,
+            body: init?.body ? JSON.parse(String(init.body)) : undefined,
+        });
+        const { status, payload } = responder(url);
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            json: async () => payload,
+        };
+    });
+    vi.stubGlobal('fetch', fetchStub);
+    return { requests, fetchStub };
+}
+const listWidgetSchema = {
+    operationId: 'listWidget',
+    summary: 'List widgets',
+    tags: ['Widget'],
+};
+const createWidgetSchema = {
+    operationId: 'createWidget',
+};
+function createServer(configuration, authOptions) {
+    return defineServer({
+        app: { service: 'widgets', title: 'Widgets Service', version: '2.3.4' },
+        resources: () => ({}),
+        config: () => configuration,
+        // 默认预设去掉 auth，换上带选项的 auth（设计 §5.2 预设只是内容）
+        middlewares: (ctx) => [...defaultMiddlewares(ctx).slice(0, -1), createAuthMiddleware(ctx, authOptions)],
+        services: () => ({}),
+        routers: (ctx) => {
+            // 公开路由（不走 verify）；本用例只关心 onReady 的自注册
+            ctx.app.get('/widget/list', { schema: listWidgetSchema, config: { accessControls: ['NoLoginRequired'] } }, () => ({ items: [] }));
+            ctx.app.post('/widget/create', { schema: createWidgetSchema, config: { accessControls: ['NoLoginRequired'] } }, () => ({ id: 'w-1' }));
+        },
+    });
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe('权限操作自注册（设计 §5.2 / §10-11）', () => {
+    it('onReady 阶段向 /permission/operation/register POST 正确请求体（service / version / operations）', async () => {
+        const { requests, fetchStub } = stubFetch(() => ({ status: 200, payload: { status: 'SUCCESS', data: {} } }));
+        const app = await startServer(createServer({ account: { enabled: true, serviceUrl: 'http://account.local' } }), { listen: false });
+        try {
+            expect(fetchStub).toHaveBeenCalledTimes(1);
+            expect(requests).toHaveLength(1);
+            expect(requests[0].url).toBe('http://account.local/permission/operation/register');
+            expect(requests[0].method).toBe('POST');
+            expect(requests[0].body).toEqual({
+                service: 'widgets',
+                version: '2.3.4',
+                operations: [
+                    { operation: 'listWidget', summary: 'List widgets', description: '', tags: ['Widget'] },
+                    { operation: 'createWidget', summary: '', description: '', tags: [] },
+                ],
+            });
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('account 无 serviceUrl 时不注册（自然排除 account 自身）', async () => {
+        const { fetchStub } = stubFetch(() => ({ status: 200, payload: { status: 'SUCCESS' } }));
+        const app = await startServer(createServer({ account: { enabled: false } }), { listen: false });
+        try {
+            expect(fetchStub).not.toHaveBeenCalled();
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('registerPermissions: false 时不注册', async () => {
+        const { fetchStub } = stubFetch(() => ({ status: 200, payload: { status: 'SUCCESS' } }));
+        const app = await startServer(createServer({ account: { serviceUrl: 'http://account.local' } }, { registerPermissions: false }), { listen: false });
+        try {
+            expect(fetchStub).not.toHaveBeenCalled();
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('注册失败（HTTP 非 2xx）不致命：startServer 仍 resolve、服务可用', async () => {
+        const { fetchStub } = stubFetch(() => ({ status: 500, payload: { status: 'UNKNOWN_ERROR', message: 'boom' } }));
+        const app = await startServer(createServer({ account: { serviceUrl: 'http://account.local' } }), { listen: false });
+        try {
+            expect(fetchStub).toHaveBeenCalledTimes(1);
+            const response = await app.inject({ method: 'GET', url: '/widget/list' });
+            expect(response.statusCode).toBe(200);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('HTTP ok 但信封非 SUCCESS 也不致命（成功判定与 /gateway/verify 同口径）', async () => {
+        const { fetchStub } = stubFetch(() => ({ status: 200, payload: { status: 'INVALID_INPUT', message: 'bad' } }));
+        const app = await startServer(createServer({ account: { serviceUrl: 'http://account.local' } }), { listen: false });
+        try {
+            expect(fetchStub).toHaveBeenCalledTimes(1);
+            const response = await app.inject({ method: 'GET', url: '/widget/list' });
+            expect(response.statusCode).toBe(200);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('fetch 抛错（网络不可达）也不致命', async () => {
+        const fetchStub = vi.fn(async () => {
+            throw new Error('network unreachable');
+        });
+        vi.stubGlobal('fetch', fetchStub);
+        const app = await startServer(createServer({ account: { serviceUrl: 'http://account.local' } }), { listen: false });
+        try {
+            expect(fetchStub).toHaveBeenCalledTimes(1);
+            const response = await app.inject({ method: 'GET', url: '/widget/list' });
+            expect(response.statusCode).toBe(200);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('出 spec 路径（generateOpenApi 不调 loadConfig）不注册', async () => {
+        const { fetchStub } = stubFetch(() => ({ status: 200, payload: { status: 'SUCCESS' } }));
+        const spec = (await generateOpenApi(createServer({ account: { serviceUrl: 'http://account.local' } })));
+        expect(fetchStub).not.toHaveBeenCalled();
+        expect(Object.keys(spec.paths ?? {})).toEqual(expect.arrayContaining(['/widget/list', '/widget/create']));
+    });
+});

package/output/app/redis.d.ts

@@ -0,0 +1,45 @@
+import { RedisCache } from '../redis-cache/index.js';
+import type { ConfigEnv } from './env.js';
+import type { LoggerLike, RedisHandle } from './types.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 declare const DEFAULT_REDIS_CACHE_TTL_SECONDS = 300;
+/**
+ * 构造 Redis 句柄（惰性包装：不建连、不 ping）。
+ *
+ * 无 `REDIS_URL` 时返回 `undefined` —— 资源包里写成 `redis: RedisHandle | undefined` 即可
+ * （显式可选，运行时缺省）。
+ */
+export declare function createRedis(env: ConfigEnv, log?: LoggerLike): RedisHandle | undefined;
+/** `createCache` 入参 */
+export interface CacheSetupParams {
+    env: ConfigEnv;
+    /** 键前缀（通常形如 `<service>:`），避免不同服务 / 环境互相污染 */
+    prefix: string;
+    /** 复用既有 Redis 句柄（**推荐**：一条连接同时给 cache 与其它消费者） */
+    redis?: RedisHandle;
+    log?: LoggerLike;
+}
+/**
+ * 构造缓存（前缀由调用方给出）。
+ *
+ * - 传 `redis` → 复用同一个客户端；
+ * - 未传 `redis` 但有 `REDIS_URL` → 自建客户端（由 `RedisCache` 自己持有并断开）；
+ * - 都没有 → 纯进程内一级缓存（不建连）。
+ */
+export declare function createCache(params: CacheSetupParams): RedisCache;
+//# sourceMappingURL=redis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../source/app/redis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEzD;;;;;;;;;;;;;;GAcG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,+BAA+B,MAAM,CAAA;AAElD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAmBrF;AAED,uBAAuB;AACvB,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,SAAS,CAAA;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAYhE"}

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":""}