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

package/output/core/types.d.ts

@@ -0,0 +1,338 @@
+import type { Disposer, SystemError } from '@taicode/common-base';
+import type { FastifyBaseLogger, FastifyInstance, RawServerDefault } from 'fastify';
+import type { ZodTypeProvider } from 'fastify-type-provider-zod';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ConfigEnv } from './env.js';
+/**
+ * `defineServer` 槽位口径与接口类型（N1 / N2，**唯一规格来源**）。
+ *
+ * 顶层是「一个身份块 + 六个工厂槽位」，**键顺序即分层**：
+ *
+ * ```
+ * app            （身份块，无依赖）
+ * resources      ← env                            引导期：唯一读 env 的地方
+ * config         ← env + resources                引导期：❗不给 services（结构性解耦）
+ * clients        ← resources + config             外部服务客户端：❗不给 env / services / app
+ * services       ← resources + config + clients   运行期开始：❗不给 env、不给 services
+ * middlewares    ← app + services + config + clients （不给 resources / env）
+ * routers        ← app + services + clients       （不给 resources / env / config）
+ * ```
+ *
+ * 槽位只能引用**排在它前面**的产物（向下引用是编译错误）；`env` 只属引导期
+ * （`resources` / `config` 可见，运行期三层一律看不到）。
+ *
+ * **`resources` 与 `clients` 的语义分界**：`resources` = **我们拥有的基础设施**（DB / Redis，
+ * 连接串来自 env）；`clients` = **我们调用的外部服务**（地址 / 凭证来自业务配置）。
+ * 后者必然依赖 `config`，所以结构上只能排在 `config` 之后——这也解释了为什么不能把它
+ * 并进 `resources`。
+ *
+ * **`disposer` 是每个槽位 ctx 的标配**（不是某个槽位专属）：在**创建某个东西的地方**当场
+ * `ctx.disposer.add(() => 释放它)`，创建与释放同处一地；`disposer` 是**出口**（不产出任何依赖），
+ * 因此不会造成循环，也不削弱「只给该阶段该看的字段」的约束。
+ *
+ * 生命周期：每个阶段一个独立的 `Disposer` 实例；关闭时**按阶段逆序 flush**
+ * `routers → middlewares → services → clients → config → resources`（services 阶段内部：先 flush
+ * disposer，再逐单元逆序 `dispose`）。详见 `lifecycle.ts` / `shutdown.ts`。
+ *
+ * 类型安全机制（N2 §1）：
+ * - **M1 分阶段 ctx**：每个工厂只拿到「该阶段该看的字段」（**外加每个阶段都有的 `disposer`**）；
+ * - **M2 `Awaited<>` 归一**：工厂签名写 `(ctx) => R`（不是 `R | Promise<R>`），下游一律
+ *   `Awaited<R>` / `Awaited<C>` / `Awaited<CL>` / `Awaited<S>`；
+ * - **M3 资源嵌套**：资源包挂在 `ctx.resources` 上（不再摊平到 ctx，键冲突从根上消失）；
+ * - **M4 `Live<T>` 静态开关**：资源包 / 客户端包里值为 `false` 的键在类型上剔除；
+ * - **M5 强类型 `services`**：`middlewares` / `routers` 的 `ctx.services` 是 `S` 实体；
+ * - **M6 品牌 + 类型守卫**：`Server` 带品牌，`isServer()` 收窄；
+ * - **M7 负向类型测试**：`define-server.negative-cases.ts`，由 `tsc --noEmit` 覆盖。
+ *
+ * 命名全拼：`requestId` / `database` / `configuration` / `service`（不用 `db` / `cfg`）。
+ */
+/** 骨架只按 `(obj, msg)` 形态打日志；`app.log` 与 `@taicode/common-base` 的 `Logger` 都满足 */
+export interface LoggerLike {
+    debug: (obj: unknown, msg?: string) => void;
+    info: (obj: unknown, msg?: string) => void;
+    warn: (obj: unknown, msg?: string) => void;
+    error: (obj: unknown, msg?: string) => void;
+}
+/**
+ * 路由级类型安全的载体：带 `ZodTypeProvider` 的 `FastifyInstance`。
+ *
+ * 裸 `FastifyInstance` 会让路由的 `params` / `body` / `query` 全是 `unknown`；带上 provider 后
+ * `request.params.id` 有类型。
+ */
+export type AppInstance = FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse, FastifyBaseLogger, ZodTypeProvider>;
+/**
+ * 身份块：非 env 派生，出 spec 路径也要用。
+ *
+ * `version` **必填、无默认值**（缺它就是编译错误，杜绝「悄悄兜底成 1.0.0」）。
+ */
+export interface AppIdentity {
+    /** 权限注册键 / cache 前缀 / 失效通道前缀 / 日志标签 */
+    readonly service: string;
+    readonly title: string;
+    /** openapi `info.version` + 权限操作自注册；建议从 package.json 读入 */
+    readonly version: string;
+}
+/**
+ * Redis 句柄（惰性包装）。
+ *
+ * 框架**不操作** Redis 命令，只持有并在关闭时透传 dispose；构造时不建连、不 ping。
+ * 因此保持开放类型，各仓注入自己的客户端实现不受约束。
+ */
+export interface RedisHandle {
+    client: unknown;
+    dispose: () => void | Promise<void>;
+}
+/**
+ * 剔掉值为 `false` 的键（编译期静态开关）。
+ *
+ * 资源包里写 `cache: false` 表示**静态关闭**：`Live<T>` 里该键**不存在**，访问直接编译失败；
+ * 而 `cache: Cache | undefined`（显式可选）表示**运行时缺省**：键存在，类型为 `Cache | undefined`。
+ */
+export type Live<T> = {
+    [K in keyof T as T[K] extends false ? never : K]: T[K];
+};
+/** 框架在 ctx 上暴露的资源视图（`Awaited<>` 归一 + `false` 键剔除） */
+export type ResourcesView<R> = Live<Awaited<R>>;
+/** 框架在 ctx 上暴露的客户端视图（口径同 `ResourcesView`） */
+export type ClientsView<CL> = Live<Awaited<CL>>;
+/**
+ * 资源错误分类器（响应层用）。
+ *
+ * **每个资源注册自己的分类器**（一个资源一个）：只认领自己错误域内的错误，认领不了返回 `null` 交给
+ * 下一个。由服务仓在 `resources(ctx)` 里通过 `ctx.registerClassifyError(...)` 注册；可注册多个，
+ * 按注册顺序求值取第一个非 `null` 的结果；全部未命中 / 一个都没注册 → 响应层落 `UNKNOWN_ERROR` 兜底。
+ */
+export type ErrorClassifier = (error: unknown) => SystemError | null;
+/**
+ * `resources(ctx)` 的入参：**`env` + `log` + `disposer`**（外加槽位专属的注册能力）。
+ *
+ * 结构上排除 `config` / `services` / `app` → 「资源依赖配置」这类循环**编译期写不出来**。
+ * `disposer` 是**出口**（只能注册释放函数，不产出依赖），因此不构成新的循环面：
+ * 资源在构造处当场 `ctx.disposer.add(() => 释放它)`，关闭时框架最后 flush。
+ *
+ * ```ts
+ * resources: ({ env, log, disposer, registerClassifyError }) => {
+ *   const database = new PrismaClient({ adapter: new PrismaPg({ connectionString: env.DATABASE_URL }) })
+ *   disposer.add(() => database.$disconnect())
+ *
+ *   // 本资源认领自己的错误域（不认领就返回 null 交给下一个）
+ *   registerClassifyError((error) => (isPrismaError(error) ? new SystemError('DATABASE_ERROR') : null))
+ *
+ *   return { database }
+ * }
+ * ```
+ */
+export interface ResourcesContext {
+    readonly env: ConfigEnv;
+    readonly log: LoggerLike;
+    /**
+     * 本阶段的释放器：**在创建资源的地方当场注册释放**。
+     *
+     * 关闭序中 `resources` 阶段**最后** flush（所有其它阶段都还活着）。
+     */
+    readonly disposer: Disposer;
+    /**
+     * **每个资源注册自己的错误分类器**（响应层用）。
+     *
+     * 一个资源一个分类器，各管各的错误域：只认领自己域内的错误，认领不了返回 `null` 交给下一个。
+     * 可注册多个：按注册顺序求值，取第一个非 `null` 的结果；全部未命中 → 响应层落 `UNKNOWN_ERROR` 兜底。
+     * 本方法是 **resources 槽位专属能力**（其他槽位的 ctx 不提供）。
+     */
+    registerClassifyError(classifier: ErrorClassifier): void;
+}
+export type ResourcesFactory<R> = (ctx: ResourcesContext) => R;
+/**
+ * `config(ctx)` 的入参：`env` + `log` + `disposer` + 资源视图。
+ *
+ * **没有** `services`（此时尚未构造）/ `app`（此时尚未装配）。
+ *
+ * ```ts
+ * config: async ({ resources }) => {
+ *   const row = await resources.database.systemConfig.findFirst()   // 启动期一次读库
+ *   return { cors: row?.cors ?? defaultCors, webhook: { url: row?.webhookUrl } }
+ * }
+ * ```
+ *
+ * 返回值是**启动期快照**：进程内不再变，没有热更新通道。要能随时改的开关放数据库、请求期现读。
+ */
+export interface ConfigContext<R> {
+    readonly env: ConfigEnv;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时在 services 之后、resources 之前 flush） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<R>;
+}
+export type ConfigFactory<R, C> = (ctx: ConfigContext<R>) => C;
+/**
+ * `clients(ctx)` 的入参：`log` + `disposer` + `resources` + `config`。
+ *
+ * 与 `ServiceContext` 同一依赖集，差别只在**时序与语义**：`clients` 在 `services` 之前构造，
+ * 因此服务单元可以共享同一份外部客户端，而**不需要**破「service 之间禁止互依」。
+ *
+ * ❗**故意没有 `env`**（运行期不得读 env）；❗**故意没有 `services`**（此时尚未构造）；
+ * ❗**故意没有 `app`**（拿不到 app 就不可能注册路由）。
+ *
+ * 语义边界：`resources` = **我们拥有的基础设施**（连接串来自 env）；`clients` = **我们调用的
+ * 外部服务**（地址 / 凭证来自业务配置，即 `config`）。这也是它必须排在 `config` 之后的原因。
+ *
+ * ```ts
+ * clients: ({ config, disposer, log }) => {
+ *   const http = createHttpClient({ baseUrl: config.upstream.baseUrl, log })
+ *   disposer.add(() => http.close())
+ *   return { upstream: http }
+ * }
+ * ```
+ *
+ * 没有外部客户端时写 `clients: () => ({})`——槽位恒定，不留「可省略」分支。
+ */
+export interface ClientsContext<R, C> {
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时在 services 之后、config 之前 flush） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<R>;
+    readonly config: Awaited<C>;
+}
+export type ClientsFactory<R, C, CL> = (ctx: ClientsContext<NoInfer<R>, NoInfer<C>>) => CL;
+/**
+ * `services(ctx)` 的入参：`log` + `disposer` + `resources` + `config` + `clients`。
+ *
+ * ❗**故意没有 `env`**（服务层属运行期，不得读 env）；❗**故意没有 `services`**（禁 service 互依）。
+ *
+ * ```ts
+ * services: ({ resources, config, clients, disposer, log }) => {
+ *   const user = createUserService({ database: resources.database, config, log })
+ *   const queue = createQueue({ redis: resources.redis })   // 常驻单元：自己挂 init / dispose
+ *   disposer.add(() => queue.stop())
+ *   return { user, queue }
+ * }
+ * ```
+ *
+ * 两个约束：
+ * - **不得返回原始类型值**（`string` / `number` / `boolean`）——那是配置，不是服务。
+ * - **service 之间不得互依**：要共享的东西放 `clients`；需要常驻资源的单元自己实现
+ *   `init()` / `dispose()`（框架会在 `middlewares` 之前 `init`、关闭时逆序 `dispose`）。
+ */
+export interface ServiceContext<R, C, CL = unknown> {
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时**先** flush 它，再逐单元逆序 `dispose`） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<R>;
+    readonly config: Awaited<C>;
+    readonly clients: ClientsView<CL>;
+}
+/**
+ * 一个已构造好的中间件：接收 app 的注册函数。
+ *
+ * 中间件**不参与生命周期**（要常驻资源就放 `services`）；注册后不再暴露内部钩子名。
+ */
+export type Middleware = (app: AppInstance) => void | Promise<void>;
+/**
+ * `middlewares(ctx)` 的入参：`app` + `log` + `disposer` + `services` + `config` + `clients`。
+ *
+ * ❗**故意没有 `resources` / `env`** —— 中间件要访问数据层必须穿过 service。
+ *
+ * ```ts
+ * middlewares: (ctx) => ({
+ *   cors: createCorsMiddleware(ctx),
+ *   auth: createAuthMiddleware(ctx, { client: createAuthClient(ctx.services) }),
+ *   rateLimit: createRateLimitMiddleware(ctx, { limit: ctx.config.rateLimit }),
+ * })
+ * ```
+ *
+ * 返回对象是**键即名字、键序即注册序**（见下方 `MiddlewaresFactory` 的数字键陷阱）。
+ */
+export interface MiddlewareContext<C, S, CL = unknown> {
+    readonly app: AppInstance;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时最早 flush：在 services / clients / config / resources 之前） */
+    readonly disposer: Disposer;
+    readonly services: Awaited<S>;
+    readonly config: Awaited<C>;
+    readonly clients: ClientsView<CL>;
+}
+/**
+ * `middlewares` 必须返回 `{ 名字: 注册函数 }` —— **键即 name、键序即注册序**。
+ *
+ * 键只用于报错定位 / 注册期日志，**不参与生命周期**。
+ *
+ * ⚠️ **坑**：JS 对象的枚举序是「整数样式的键在前（按数值升序），其余按插入序」。所以
+ * **纯数字键会被引擎重排到最前**，注册序随之改变——键名避免纯数字（用 `auth` / `rateLimit`
+ * 这类标识符即可）。除此外，注册序 = 对象键顺序。
+ */
+export type MiddlewaresFactory<C, S, CL = unknown> = (ctx: MiddlewareContext<C, S, CL>) => Record<string, Middleware>;
+/**
+ * `routers(ctx)` 的入参：`app` + `log` + `disposer` + `services` + `clients`。
+ *
+ * ❗**故意没有 `resources` / `env` / `config`** —— 路由**只能穿过 service**，绕不过层直连数据层。
+ *
+ * ```ts
+ * routers: ({ app, services }) => {
+ *   app.register(createUserRouter(services.user))
+ * }
+ * ```
+ *
+ * ❗**注册期不得调用 `services` 的方法**（只能把 service 捕获进 handler、请求期使用）：
+ * `generateOpenApi` 走这条路径时不构造 `services`，注册期就读它会让出 spec 直接失败。
+ * 没业务路由也要写 `routers: () => {}`。
+ */
+export interface RouterContext<S, CL = unknown> {
+    readonly app: AppInstance;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时**最先** flush） */
+    readonly disposer: Disposer;
+    readonly services: Awaited<S>;
+    readonly clients: ClientsView<CL>;
+}
+export type RoutersFactory<S, CL = unknown> = (ctx: RouterContext<S, CL>) => void | Promise<void>;
+/**
+ * `services` 返回值形状闸门：
+ * - 原始类型值（`string` / `number` / `boolean`）**拒绝**（防把配置塞进 services）。
+ */
+export type ServicesShape<S> = {
+    [K in keyof S]: S[K] extends string | number | boolean ? never : S[K];
+};
+/**
+ * `defineServer()` 入参：一个身份块 + **六个**工厂槽位（键顺序=分层）。
+ *
+ * ```
+ * app → resources(env) → config(env+resources) → clients(resources+config)
+ *     → services(resources+config+clients) → middlewares(app+services+config+clients)
+ *     → routers(app+services+clients)
+ * ```
+ *
+ * `S` 上的两道闸门（`ServicesShape<S>`，N2 §2.5）写在 `services` 的返回类型上：
+ * `S & ServicesShape<S>` —— 形状合法时恒等，非法时该值塌成 `never` → 编译失败。
+ */
+export interface ServerConfig<R, C, CL, S> {
+    app: AppIdentity;
+    resources: ResourcesFactory<R>;
+    config: ConfigFactory<NoInfer<R>, C>;
+    /**
+     * 外部服务客户端（**我们调用的、地址/凭证来自业务配置的外部服务**）。
+     *
+     * 存在的唯一理由是「`services` 之间禁止互依」与「客户端需要 `config`」这两条约束
+     * 的交集：多个 service / middleware 必须共享同一份客户端，而它们之间没有共享通道。
+     * 没有这种需求就写 `() => ({})` —— 槽位恒定，不留「可省略」分支。
+     */
+    clients: ClientsFactory<NoInfer<R>, NoInfer<C>, CL>;
+    services: (ctx: ServiceContext<NoInfer<R>, NoInfer<C>, NoInfer<CL>>) => S & ServicesShape<S>;
+    middlewares: MiddlewaresFactory<NoInfer<C>, NoInfer<S>, NoInfer<CL>>;
+    /**
+     * 业务路由注册（**必填**）。
+     *
+     * 框架已自动注册 5 条系统路由（`/` / `/health` / `/system/health` / `/system/info` /
+     * `/system/openapi`，见 `core/modules/system-routes/`），应用侧无需再写 `createSystemRouter`；
+     * 本槽位只用于注册**业务**路由。没有业务路由的应用也必须显式传入（写 `() => {}`），
+     * 以保持槽位结构恒定、无「可省略」分支。
+     */
+    routers: RoutersFactory<NoInfer<S>, NoInfer<CL>>;
+}
+/** 品牌字段值（`Server` 的 `__brand`） */
+export declare const SERVER_BRAND = "taicode.server";
+/** 纯定义产物：同一份定义可同时喂给「启动」与「出 spec」 */
+export type Server<R, C, CL, S> = ServerConfig<R, C, CL, S> & {
+    readonly __brand: typeof SERVER_BRAND;
+};
+/** `generateOpenApi()` 的返回（OpenAPI 文档对象） */
+export type OpenApiDocument = Record<string, unknown>;
+//# sourceMappingURL=types.d.ts.map

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

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

package/output/cors/index.d.ts

@@ -0,0 +1,3 @@
+import type { Middleware, MiddlewareContext } from '../core/types.js';
+export declare function createCorsMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>): Middleware;
+//# sourceMappingURL=index.d.ts.map

package/output/cors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/cors/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAkBrE,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CA0BvG"}

package/output/cors/index.js

@@ -0,0 +1,27 @@
+import cors from '@fastify/cors';
+import { readConfigKey } from '../core/boot/context.js';
+export function createCorsMiddleware(ctx) {
+    return async (app) => {
+        let warned = false;
+        // 请求期现读：`cors` 配置变化立即生效；构造期不读
+        const resolveOrigins = () => {
+            const configured = readConfigKey(ctx.config, 'cors');
+            return configured?.enabled ? configured.origins : undefined;
+        };
+        await app.register(cors, {
+            origin: (origin, callback) => {
+                const origins = resolveOrigins();
+                if (origins === undefined || origins === '*') {
+                    if (!warned) {
+                        warned = true;
+                        ctx.log.warn({}, '[middleware] cors origins not configured; allowing any origin');
+                    }
+                    callback(null, true);
+                    return;
+                }
+                callback(null, origins.includes(origin ?? ''));
+            },
+            credentials: true,
+        });
+    };
+}

package/output/index.d.ts

@@ -1,6 +1,10 @@
-export * from './schema/index.js';
+export * from './core/modules/schema/builders.js';
+export { createContext } from './core/modules/context/index.js';
+export type { RequestContext } from './core/modules/context/index.js';
+export * from './redis/index.js';
+export * from './rate-limit/limiter.js';
+export * from './rate-limit/memory-store.js';
+export * from './rate-limit/redis-store.js';
+export * from './rate-limit/types.js';
 export * from './redis-queue/index.js';
-export * from './redis-cache/index.js';
-export * from './rate-limiter/index.js';
-export * from './context/index.js';
 //# sourceMappingURL=index.d.ts.map

package/output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAA;AACjC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAiBA,cAAc,mCAAmC,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA"}

package/output/index.js

@@ -1,6 +1,25 @@
-// 根 index.ts，统一导出 mock 目录下所有能力
-export * from './schema/index.js';
+// 包根出口（`@taicode/common-server`）：业务侧直接使用的**构件**——
+// 路由 / 查询 schema 工厂、请求上下文构造、Redis 缓存、限流实现、Redis 队列。
+//
+// 目录布局（见 `common/product/designs/create-server/design.md` §7.1）：
+// ```
+// source/
+// ├── core/            核心设计（锁定：不可替换、不可修改，**不对外导出装配**）
+// ├── app/             服务入口 barrel（defineServer / startServer / generateOpenApi）
+// ├── auth/            可选：鉴权中间件
+// ├── cors/            可选：CORS 中间件
+// ├── rate-limit/      可选：限流中间件 + 限流实现
+// ├── redis/           请求期 Redis / 缓存
+// └── redis-queue/     可选：Redis 队列
+// ```
+//
+// 框架自己装配的一切（`createFastify` / `registerCore` / 各 core 单元 / `request.ctx` 装配 /
+// 默认中间件预设）都不在这里：**固定下来的东西不再交给外面组装**。
+export * from './core/modules/schema/builders.js';
+export { createContext } from './core/modules/context/index.js';
+export * from './redis/index.js';
+export * from './rate-limit/limiter.js';
+export * from './rate-limit/memory-store.js';
+export * from './rate-limit/redis-store.js';
+export * from './rate-limit/types.js';
 export * from './redis-queue/index.js';
-export * from './redis-cache/index.js';
-export * from './rate-limiter/index.js';
-export * from './context/index.js';

package/output/rate-limit/index.d.ts

@@ -0,0 +1,23 @@
+import type { Middleware, MiddlewareContext } from '../core/types.js';
+import type { RateLimitStore } from './types.js';
+/**
+ * 标准中间件单元 `rateLimit`（可替换；**不在默认预设内**）。
+ *
+ * **规则只有一个来源：路由的 `config.rateLimit`**（与 `auth` 的 `accessControls` 同一取向）。
+ * 存储后端由调用方注入（缺省进程内 memory）。`TOO_MANY_REQUESTS` 经 `UserError` 仍映射 **400**。
+ * 路由未声明 `config.rateLimit` 时该项空转。
+ *
+ * 注：中间件的 ctx 看不到 `resources`（中间件不得直连数据层），因此 Redis store 需由调用方
+ * 在 `services` 侧构造后注入（`store`），框架不再自行探测 Redis。
+ */
+export interface RateLimitMiddlewareOptions {
+    /** 存储后端（缺省进程内 memory） */
+    store?: RateLimitStore;
+}
+export declare function createRateLimitMiddleware<C = unknown, S = unknown>(_ctx: MiddlewareContext<C, S>, options?: RateLimitMiddlewareOptions): Middleware;
+export { RateLimiter, createRateLimitKey } from './limiter.js';
+export { MemoryRateLimitStore } from './memory-store.js';
+export { RedisRateLimitStore } from './redis-store.js';
+export type { RedisRateLimitStoreOptions } from './redis-store.js';
+export type { RateLimitConfig, RateLimitInfo, RateLimiterOptions, RateLimitResult, RateLimitStore } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/output/rate-limit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/rate-limit/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD;;;;;;;;;GASG;AAEH,MAAM,WAAW,0BAA0B;IACzC,yBAAyB;IACzB,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB;AAqBD,wBAAgB,yBAAyB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,0BAA+B,GAAG,UAAU,CAkBvJ;AAGD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/output/rate-limit/index.js

@@ -0,0 +1,42 @@
+import { UserError } from '@taicode/common-base';
+import { createRateLimitKey, RateLimiter } from './limiter.js';
+import { MemoryRateLimitStore } from './memory-store.js';
+import { readServerIdentity } from '../core/modules/identity/index.js';
+function resolveRule(request) {
+    return request.routeOptions?.config?.rateLimit;
+}
+function buildKeys(request, keys) {
+    return keys.map((key) => {
+        if (key === 'ip') {
+            return `ip:${request.ip}`;
+        }
+        if (key === 'user') {
+            return `user:${String(request.user?.id ?? 'anonymous')}`;
+        }
+        if (key === 'path') {
+            return `path:${request.routeOptions?.url ?? request.url}`;
+        }
+        return `${key}:${String(request[key] ?? '')}`;
+    });
+}
+export function createRateLimitMiddleware(_ctx, options = {}) {
+    return (app) => {
+        const limiter = new RateLimiter({ store: options.store ?? new MemoryRateLimitStore() });
+        const prefix = `${readServerIdentity(app)?.service ?? ''}:`;
+        app.addHook('preValidation', async (request) => {
+            const rule = resolveRule(request);
+            if (!rule) {
+                return;
+            }
+            const keys = buildKeys(request, rule.keys ?? ['ip']).map((key) => createRateLimitKey(prefix, key));
+            const result = await limiter.checkMultiLimit(keys, { limit: rule.limit, window: rule.window });
+            if (!result.allowed) {
+                throw new UserError('TOO_MANY_REQUESTS', undefined, '请求过于频繁');
+            }
+        });
+    };
+}
+// ── 限流实现（与中间件同一模块）─────────────────────────────────
+export { RateLimiter, createRateLimitKey } from './limiter.js';
+export { MemoryRateLimitStore } from './memory-store.js';
+export { RedisRateLimitStore } from './redis-store.js';

package/output/{rate-limiter/rate-limiter.d.ts → rate-limit/limiter.d.ts}

@@ -14,4 +14,4 @@ export declare class RateLimiter {
  * 创建限流键的辅助函数
  */
 export declare function createRateLimitKey(prefix: string, ...parts: string[]): string;
-//# sourceMappingURL=rate-limiter.d.ts.map
+//# sourceMappingURL=limiter.d.ts.map

package/output/rate-limit/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../source/rate-limit/limiter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAA;AAErH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAgB;gBAEjB,OAAO,GAAE,kBAAuB;IAItC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAoC1E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAI9D;;OAEG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;CAezF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAE7E"}

package/output/rate-limit/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../source/rate-limit/memory-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAO/D,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,eAAe,CAA8B;gBAEzC,iBAAiB,SAAQ;IAY/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAY/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,OAAO,IAAI,IAAI;CAOhB"}

package/output/rate-limit/redis-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../../source/rate-limit/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,OAAO,CAAA;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,MAAM,WAAW,0BAA0B;IACzC,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,OAAO,CAAC,gBAAgB,CAAI;gBAEhB,OAAO,GAAE,0BAA+B;IAyBvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,UAAU,IAAI,IAAI;IAKZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqB/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,4BAA4B;IACf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;CAOjB"}

package/output/rate-limit/redis-store.test.d.ts.map

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

package/output/{rate-limiter → rate-limit}/redis-store.test.js

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createRedisClient } from '../redis-cache/redis-cache.js';
-import { RateLimiter } from './rate-limiter.js';
+import { createRedisClient } from '../redis/cache.js';
+import { RateLimiter } from './limiter.js';
 import { RedisRateLimitStore } from './redis-store.js';
 const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
 describe('RedisRateLimitStore', () => {

package/output/{rate-limiter → rate-limit}/types.d.ts

@@ -19,7 +19,6 @@ export interface RateLimitStore {
 export interface RateLimitConfig {
     limit: number;
     window: number;
-    lockout?: number;
 }
 export interface RateLimiterOptions {
     store?: RateLimitStore;

package/output/rate-limit/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../source/rate-limit/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,IAAI,CAAA;IACjB,SAAS,EAAE,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,IAAI,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB"}

package/output/rate-limit/types.js

@@ -0,0 +1 @@
+export {};

package/output/{redis-cache/redis-cache.d.ts → redis/cache.d.ts}

@@ -136,4 +136,4 @@ export interface CreateRedisClientOptions {
     connectTimeoutMs?: number;
 }
 export declare function createRedisClient(options: CreateRedisClientOptions): RedisClientType;
-//# sourceMappingURL=redis-cache.d.ts.map
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../source/redis/cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,OAAO,CAAA;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kDAAkD;IAClD,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,uBAAuB;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,EAAE,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;CACjC;AAaD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA0B;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,OAAO,CAAC,gBAAgB,CAAI;gBAEhB,OAAO,EAAE,iBAAiB;IA6BtC,uBAAuB;IACvB,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,sBAAsB;IACtB,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,wCAAwC;IACxC,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrC,0BAA0B;IACnB,UAAU,IAAI,IAAI;IAOzB;;;;;OAKG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrC;;;OAGG;IACI,KAAK,IAAI,IAAI;IAQP,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAItC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C;;;;;;OAMG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB5D;;;;;;OAMG;IACU,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA6BhG;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAIhB,8CAA8C;YAChC,aAAa;YAmBb,aAAa;IAY3B,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;CAOjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CAkBpF"}

package/output/redis/cache.test.d.ts

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

package/output/redis/cache.test.d.ts.map

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

package/output/{redis-cache/redis-cache.test.js → redis/cache.test.js}

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { RedisCache, createRedisClient } from './redis-cache.js';
+import { RedisCache, createRedisClient } from './cache.js';
 const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
 describe('RedisCache', () => {
     describe('纯一级缓存（未配置 Redis）', () => {

package/output/{app/redis.d.ts → redis/index.d.ts}

@@ -1,23 +1,25 @@
-import { RedisCache } from '../redis-cache/index.js';
-import type { ConfigEnv } from './env.js';
-import type { LoggerLike, RedisHandle } from './types.js';
+import { RedisCache } from './cache.js';
+import type { ConfigEnv } from '../core/env.js';
+import type { LoggerLike, RedisHandle } from '../core/types.js';
 /**
  * 引导期 Redis / cache helper（N2 §2.13）。
  *
- * 在 `resources(ctx)` 槽位里按需调用（框架自己**不**创建 Redis）：
+ * 在 `resources(ctx)` 槽位里按需调用（框架自己**不**创建 Redis）；释放**在创建处**登记：
  *
  * ```ts
  * resources: (ctx) => {
  *   const redis = createRedis(ctx.env, ctx.log)          // 无 REDIS_URL → undefined
+ *   if (redis) {
+ *     ctx.disposer.add(() => redis.dispose())            // 关闭时 resources 阶段最后 flush
+ *   }
  *   return { redis, cache: createCache({ env: ctx.env, prefix: 'account', redis }) }
  * }
  * ```
  *
  * `REDIS_URL` 由 helper 直接读 `env`（固定约定），**不**取自 `config`；`redis` / `cache` 一律是
  * **惰性包装**：构造时不建连、不 ping，首次真正使用才建连 —— 「出 spec 不连库/Redis」结构性成立。
+ * 释放永远走调用方在 `ctx.disposer` 里的登记，框架不替资源持有句柄。
  */
-/** 一级/二级缓存默认 TTL（秒），与 `RedisCache` 默认一致 */
-export declare const DEFAULT_REDIS_CACHE_TTL_SECONDS = 300;
 /**
  * 构造 Redis 句柄（惰性包装：不建连、不 ping）。
  *
@@ -42,4 +44,7 @@ export interface CacheSetupParams {
  * - 都没有 → 纯进程内一级缓存（不建连）。
  */
 export declare function createCache(params: CacheSetupParams): RedisCache;
-//# sourceMappingURL=redis.d.ts.map
+export { RedisCache, createRedisClient } from './cache.js';
+export type { CreateRedisClientOptions, RedisCacheL1Options, RedisCacheOptions } from './cache.js';
+export type { RedisClientType } from 'redis';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/redis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAwBrF;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;AAGD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC1D,YAAY,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA"}