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

package/output/core/types.d.ts

@@ -0,0 +1,582 @@
+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，**唯一规格来源**）。
+ *
+ * 顶层是「一个身份块 + 工厂槽位」，**键顺序即分层**（`clients` 可选）：
+ *
+ * ```
+ * 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（`Env`）**不是槽位**，而是 `defineServer` 的**第一个泛型**：可**单独手写**
+ * `defineServer<{ FOO?: string }>({...})`，也可不写、从 `resources` / `config` 的 `ctx` 类型标注
+ * 推导（`ResourcesContext<Env>`）。⚠️ 手写 `Env` 会让其余泛型停止推导（退化为 `object`，TS 限制），
+ * 详见 `defineServer` 文档。加载仍走内置逻辑，框架不提供自定义加载。
+ *
+ * 槽位只能引用**排在它前面**的产物（向下引用是编译错误）；`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) => Resources`（不是 `Resources | Promise<Resources>`），下游一律
+ *   `Awaited<Resources>` / `Awaited<Config>` / `Awaited<Clients>` / `Awaited<Services>`；
+ * - **M3 资源嵌套**：资源包挂在 `ctx.resources` 上（不再摊平到 ctx，键冲突从根上消失）；
+ * - **M4 `Live<Value>` 静态开关**：资源包 / 客户端包里值为 `false` 的键在类型上剔除；
+ * - **M5 强类型 `services`**：`middlewares` / `routers` 的 `ctx.services` 是 `Services` 实体；
+ * - **M6 品牌**：`Server` 带 `__brand`（`SERVER_BRAND`），只能由 `defineServer` 产出，入口函数据此拒收裸对象。
+ *
+ * 命名全拼：`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 title: string;
+    readonly service: string;
+    /** openapi `info.version` + 权限操作自注册；建议从 package.json 读入 */
+    readonly version: string;
+}
+/**
+ * Redis 句柄（惰性包装）。
+ *
+ * 框架**不操作** Redis 命令，只持有并在关闭时透传 dispose；构造时不建连、不 ping。
+ * 因此保持开放类型，各仓注入自己的客户端实现不受约束。
+ */
+export interface RedisHandle {
+    client: unknown;
+    dispose: () => void | Promise<void>;
+}
+/**
+ * 资源单元：**值 + 生命周期分离**。
+ *
+ * 为什么不把生命周期挂在值上（像 service 的 `init` / `dispose`）：资源多是**第三方对象**
+ * （`PrismaClient`、Redis client、连接池），形状改不了 —— `prisma.setup = …` 是在改别人的类型。
+ * 单元是框架私有外壳，`value` 保持原样。
+ *
+ * ## 与 `ctx.disposer` 的分工
+ *
+ * 两者都能释放，但默认路径不同：
+ * - **资源自己的连接 / 句柄 → `dispose()`**：它和资源写在同一个对象里，一处表达完。
+ * - **`ctx.disposer` → 逃生口**：非常规清理（不是这个资源自身的句柄、需要跨资源协调、
+ *   临时产物），或资源值确实是裸对象、不想包单元时。
+ *
+ * 这正是「框架收起具体实现，`ctx` 留给特殊情况」的分工：正常情况不需要知道 `ctx.disposer`
+ * 存在。
+ *
+ * ## 三个生命周期，各管一段
+ *
+ * | 方法 | 谁调 | 何时 |
+ * | --- | --- | --- |
+ * | `setup()` | 框架（两个入口） | 装配期，`config` 之前 |
+ * | `clean()` | 框架（仅测试入口） | 用例间清理，`app.close()` 之前 |
+ * | `dispose()` | 框架（关闭流程） | 进程关闭，最后一步 |
+ *
+ * 三者互不替代：`setup()` 是「连接前把地基铺好」（状态驱动的迁移 / 预热），`clean()` 清的是
+ * **数据行**（不碰结构），`dispose()` 断开的是**连接**（一次性）。
+ *
+ * ## 用例互间的样本数据不在资源上
+ *
+ * 「清表 + 重新插入样本数据」这伴事**不属于资源**：资源只知道有哪些表 / 哪些 key，不知道谁往里
+ * 写了什么。写在资源上就意味着新增一个 model 要回去改一次清库清单，漏改只会安静地变脏。
+ *
+ * 因此它单独做成一套机制：**`testdata/` 目录 + 每脚本自带 `load()`**，只在
+ * 可清理环境执行（见 `test-support/testdata.ts`）。
+ *
+ * `clean()` 不是这套机制，而是它的**前置条件**：`testdata/` 负责「必要的那几行」存在，
+ * `clean()` 负责「此外的一切」不存在。两者在 `TestServer.reprovision()` 里按固定顺序串起来。
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     // 自动执行：startServer / createTestServer 都会调，生产与测试同一份
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *     dispose: () => prisma.$disconnect(),
+ *   }),
+ *   cache: ctx.env.REDIS_URL ? defineResource(createRedis(ctx.env.REDIS_URL)) : false,
+ * })
+ * ```
+ */
+export interface ResourceUnit<Value> {
+    /** 真正的资源对象（框架不碰） */
+    readonly value: Value;
+    /**
+     * 装配期准备（建连验证、同步库结构、预热……）。
+     *
+     * **何时跑**：`resources` 槽位构造完成后、`config` 槽位之前，按**对象声明序**逐项 `await`。
+     * 排在 `config` 之前是硬要求：`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+     * 它就连不上。
+     *
+     * **谁跑**：框架。两个入口都调，应用永不手调；`generateOpenApi` 不调（出 spec 不构造资源）。
+     *
+     * **不要在这里写 `if (ENV === 'test')`**：准备动作本身应当是状态驱动的（迁移工具会自己比对
+     * 现状、只补差量），生产与测试跑同一份代码。需要区分环境时，区分点应当来自 `ctx.env`，
+     * 而不是「跑不跑这个函数」。
+     */
+    setup?(): void | Promise<void>;
+    /**
+     * 清掉本资源持有的**全部数据**，保留结构（**仅测试期调用**）。
+     *
+     * **何时跑**：`TestServer.reprovision()` 的第 0 步，此时连接还没断。清完后实例会被关掉重装，
+     * 所以不必考虑「清完还能不能用」。
+     *
+     * **不碰结构**：表 / 索引 / 序列的定义不归这里，它在 `setup()` 或 npm script 里建好。
+     * `clean()` 只清行——典型实现是 `TRUNCATE ... RESTART IDENTITY CASCADE`。
+     *
+     * **成功的前提是错在单元自己**：方言、表清单、级联策略都只有持有连接的单元知道，框架只认
+     * 「清干净」这个契约。不提供 `truncateTestSchema(url)` 这类代劳函数：一旦框架代判，就会
+     * 出现「只清某张表 / 某个 schema」的假合法场景。
+     *
+     * **失败冒泡**：清理没做干净就继续跑，后面全是伪绿。
+     */
+    clean?(): void | Promise<void>;
+    /**
+     * 关闭时释放本资源（断连、清池、flush……）。
+     *
+     * **何时跑**：关闭流程的最后一步（`resources` 阶段），按声明序**逆序**逐项 `await`——
+     * 后创建的先销毁；此时 `services` / `clients` / `config` 都已关完，不会再有使用方。
+     *
+     * **unit 级失败只记日志、不阻断其他资源**（关闭不能半途中断）。
+     */
+    dispose?(): void | Promise<void>;
+}
+/** 资源单元的生命周期（`defineResource` 的第二个参数） */
+export interface ResourceLifecycle {
+    setup?(): void | Promise<void>;
+    clean?(): void | Promise<void>;
+    dispose?(): void | Promise<void>;
+}
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * 实现见 `core/resource.ts`（`types.ts` 只放类型，不放运行时值）。
+ */
+export type DefineResource = <Value>(value: Value, lifecycle?: ResourceLifecycle) => ResourceUnit<Value>;
+/** 单元 → 值；非单元原样通过（`defineResource` 是可选的，裸对象照旧可用） */
+type UnwrapResource<Value> = Value extends ResourceUnit<infer Inner> ? Inner : Value;
+/**
+ * 剔掉「静态关闭」的键，并从保留键的类型里抹掉 `false` 分支（编译期静态开关）。
+ *
+ * 三种写法，三种语义，都被精确表达：
+ * - `cache: false`（**纯 `false`**）→ **静态关闭**：`Live<Value>` 里该键**不存在**，访问直接编译失败；
+ * - `cache: Cache | false`（**条件构造**）→ 键**保留**，但类型收窄为 `Cache`（`false` 分支被
+ *   `Exclude` 抹掉）——运行期 `liveResources` 会剔掉值为 `false` 的那一项，所以类型与运行时一致；
+ * - `cache: Cache | undefined`（**显式可选**）→ 键存在、类型保持 `Cache | undefined`（`undefined`
+ *   表示「运行时缺省」，与「静态关闭」语义不同，不受影响）。
+ *
+ * 旧版 `Value[K] extends false ? never : K` 只能处理「纯 `false`」，遇到 `Cache | false` 会把
+ * 整个键保留且类型仍含 `false`（与运行时剔除行为不符）。现版用 `Exclude<Value[K], false>` 对齐。
+ */
+export type Live<Value> = {
+    [K in keyof Value as [Exclude<Value[K], false>] extends [never] ? never : K]: Exclude<Value[K], false>;
+};
+/**
+ * 框架在 ctx 上暴露的资源视图（`Awaited<>` 归一 + `false` 键剔除 + **单元解包**）。
+ *
+ * 解包是必须的：`ctx.resources.database` 必须是那个客户端本身，不能是
+ * `ResourceUnit<PrismaClient>` —— 否则每个消费方都要多写一层 `.value`，而单元外壳
+ * 是框架用来挂 `setup` 的实现细节。
+ */
+export type ResourcesView<Resources> = Live<{
+    [K in keyof Awaited<Resources>]: UnwrapResource<Awaited<Resources>[K]>;
+}>;
+/** 框架在 ctx 上暴露的客户端视图（口径同 `ResourcesView`） */
+export type ClientsView<Clients> = Live<Awaited<Clients>>;
+/**
+ * 应用扩展后的 env 类型（固定 env + 应用声明的扩展字段）。
+ *
+ * `ConfigEnv` 是框架**固定约定**的最小集合（`ENV` / `API_PORT` / ...），不接受业务字段；
+ * 业务字段（如 `REDIS_KEY_PREFIX`、第三方 token）由应用声明：`Env` 是 `defineServer` 的**第一个
+ * 泛型**，可**手写** `defineServer<{ FOO?: string }>({...})`，也可从 `resources` / `config` 工厂的
+ * `ctx` 类型标注（`ResourcesContext<Env>` / `ConfigContext<Env>`）推导；两种方式都让扩展字段并进
+ * `ctx.env`、有类型地访问。（手写 `Env` 的代价见 `defineServer` 文档：其余泛型会退化为 `object`。）
+ *
+ * ⚠️ **只是类型声明，不影响加载**：env 的加载完全走框架内置逻辑（dotenv 分层 + 进程注入，
+ * 见 `env.ts`），框架**不提供自定义加载**。运行期扩展字段的值就是内置加载后的 `process.env[key]`
+ * （字符串直通，不映射 / 不校验 / 不给默认值——要默认值 / 归一化在 `resources` 里自己做）。
+ *
+ * 这样各仓不必再往 `ctx.env` 上开「`process.env.XXX` 无类型后门」——用泛型或 ctx 标注声明即可。
+ *
+ * ```ts
+ * // 命名工厂：参数标注扩展 env，`defineServer` 从中推导 Env（point-free 最简）
+ * function createResources(ctx: ResourcesContext<{ REDIS_KEY_PREFIX?: string }>) {
+ *   return { cache: createCache({ prefix: ctx.env.REDIS_KEY_PREFIX ?? 'account' }) }
+ * }
+ * const server = defineServer({ app, resources: createResources, config, services, middlewares, routers })
+ * ```
+ */
+export type AppEnv<Env> = ConfigEnv & Env;
+/**
+ * 资源错误分类器（响应层用）。
+ *
+ * **每个资源注册自己的分类器**（一个资源一个）：只认领自己错误域内的错误，认领不了返回 `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<Env = object> {
+    readonly env: AppEnv<Env>;
+    readonly log: LoggerLike;
+    /**
+     * 本阶段的释放器：**在创建资源的地方当场注册释放**。
+     *
+     * 关闭序中 `resources` 阶段**最后** flush（所有其它阶段都还活着）。
+     */
+    readonly disposer: Disposer;
+    /**
+     * **每个资源注册自己的错误分类器**（响应层用）。
+     *
+     * 一个资源一个分类器，各管各的错误域：只认领自己域内的错误，认领不了返回 `null` 交给下一个。
+     * 可注册多个：按注册顺序求值，取第一个非 `null` 的结果；全部未命中 → 响应层落 `UNKNOWN_ERROR` 兜底。
+     * 本方法是 **resources 槽位专属能力**（其他槽位的 ctx 不提供）。
+     */
+    registerClassifyError(classifier: ErrorClassifier): void;
+}
+export type ResourcesFactory<Resources, Env = object> = (ctx: ResourcesContext<Env>) => Resources;
+/**
+ * `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<Resources, Env = object> {
+    readonly env: AppEnv<Env>;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时在 services 之后、resources 之前 flush） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<Resources>;
+}
+export type ConfigFactory<Resources, Config, Env = object> = (ctx: ConfigContext<Resources, Env>) => Config;
+/**
+ * `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 }
+ * }
+ * ```
+ *
+ * 没有外部客户端时**省略本槽位**（框架默认空客户端包）——独立成层只为「分层依赖」
+ * （排在 `config` 之后、`services` 之前），不要求「必须出现」。
+ */
+export interface ClientsContext<Resources, Config> {
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时在 services 之后、config 之前 flush） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<Resources>;
+    readonly config: Awaited<Config>;
+}
+export type ClientsFactory<Resources, Config, Clients> = (ctx: ClientsContext<NoInfer<Resources>, NoInfer<Config>>) => Clients;
+/**
+ * `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<Resources, Config, Clients = unknown> {
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时**先** flush 它，再逐单元逆序 `dispose`） */
+    readonly disposer: Disposer;
+    readonly resources: ResourcesView<Resources>;
+    readonly config: Awaited<Config>;
+    readonly clients: ClientsView<Clients>;
+}
+/**
+ * 一个已构造好的中间件注册函数：接收 app，挂钩子 / 注册插件。
+ *
+ * 中间件**不参与生命周期**（要常驻资源就放 `services`）；注册后不再暴露内部钩子名。
+ */
+export type Middleware = (app: AppInstance) => void | Promise<void>;
+/**
+ * 具名中间件单元：`register` + 一个仅用于日志 / 报错定位的 `name`。
+ *
+ * 标准中间件工厂（`createCorsMiddleware` / `createAuthMiddleware` / `createRateLimitMiddleware`）
+ * 直接返回带默认名字的单元，调用方把它们按顺序摆进数组即可，不必自己起名。
+ */
+export interface MiddlewareUnit {
+    /** 名字：仅用于注册期日志 / 报错定位，**不参与生命周期、不影响注册序**（顺序由数组位置决定） */
+    readonly name: string;
+    /** 注册函数 */
+    readonly register: Middleware;
+}
+/**
+ * `middlewares` 数组里的一项：**具名单元**或**裸注册函数**。
+ *
+ * 裸函数会被框架补一个占位名（`middleware[i]`，`i` 为数组下标）用于日志；要可读的日志名
+ * 就返回 `MiddlewareUnit`（标准工厂已经这么做了）。
+ */
+export type MiddlewareEntry = MiddlewareUnit | Middleware;
+/**
+ * `middlewares(ctx)` 的入参：`app` + `log` + `disposer` + `services` + `config` + `clients`。
+ *
+ * ❗**故意没有 `resources` / `env`** —— 中间件要访问数据层必须穿过 service。
+ *
+ * ```ts
+ * middlewares: (ctx) => [
+ *   createCorsMiddleware(ctx),
+ *   createAuthMiddleware(ctx, { client: createAuthClient(ctx.services) }),
+ *   createRateLimitMiddleware(ctx, { store: ctx.services.rateLimitStore }),
+ * ]
+ * ```
+ */
+export interface MiddlewareContext<Config, Services, Clients = unknown> {
+    readonly app: AppInstance;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时最早 flush：在 services / clients / config / resources 之前） */
+    readonly disposer: Disposer;
+    readonly services: Awaited<Services>;
+    readonly config: Awaited<Config>;
+    readonly clients: ClientsView<Clients>;
+}
+/**
+ * `middlewares` 返回一个**有序数组** —— **数组位置即注册序**，再无歧义。
+ *
+ * 为什么是数组而不是 `Record<string, Middleware>`：注册序是中间件的核心语义（cors 必须在
+ * auth 之前、auth 必须在限流之前），而对象键的枚举序由 JS 引擎决定（纯数字键还会被重排到
+ * 最前）——用「顺序由引擎决定、且有已知陷阱」的结构承载「必须严格有序」的东西本身自相矛盾。
+ * 数组把顺序交还给书写顺序，既直观又没有数字键坑。
+ *
+ * 每一项可以是标准工厂返回的具名单元（`MiddlewareUnit`），也可以是一个裸注册函数
+ * （`Middleware`，框架会补占位名用于日志）。
+ */
+export type MiddlewaresFactory<Config, Services, Clients = unknown> = (ctx: MiddlewareContext<Config, Services, Clients>) => MiddlewareEntry[];
+/**
+ * `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<Services, Clients = unknown> {
+    readonly app: AppInstance;
+    readonly log: LoggerLike;
+    /** 本阶段的释放器（关闭时**最先** flush） */
+    readonly disposer: Disposer;
+    readonly services: Awaited<Services>;
+    readonly clients: ClientsView<Clients>;
+}
+export type RoutersFactory<Services, Clients = unknown> = (ctx: RouterContext<Services, Clients>) => void | Promise<void>;
+/**
+ * `services` 返回值形状闸门**的判据**（不是闸门本身）：
+ * - 原始类型值（`string` / `number` / `boolean`）**拒绝**（防把配置塞进 services）。
+ *
+ * 注意施加位置：本类型**不再出现在 `services` 工厂的返回类型上**，只作为
+ * {@link ServicesGate} 的条件类型判据、由 `defineServer` 追加在**入参**上。
+ * 旧写法（挂在返回值上）会让 `Server` 产物无法回喂 `defineServer` 做组合定义，
+ * 详见 `ServicesGate` 的 docblock。
+ */
+export type ServicesShape<Services> = {
+    [K in keyof Services]: Services[K] extends string | number | boolean ? never : Services[K];
+};
+/** 形状非法时被点名的那几个键（`string` / `number` / `boolean` 的键） */
+export type InvalidServiceKeys<Services> = {
+    [K in keyof Services]: Services[K] extends string | number | boolean ? K : never;
+}[keyof Services];
+/**
+ * `services` 形状闸门的**施加位置**：`defineServer` 的**入参**，不是返回类型。
+ *
+ * ## 为什么不在返回类型上做交集
+ *
+ * 旧写法是 `services: (ctx) => Services & ServicesShape<Services>` —— 闸门挂在工厂**返回值**上。
+ * 它有两个代价，第二个是致命的：
+ *
+ * 1. 报错点远离原因：写错时错误落在「返回类型不可赋值」，指向具体的某个属性，而不是
+ *    「`services` 里不许放配置」。
+ * 2. **组合定义（composition）无法编译**。`Server` 产物的 `services` 类型里已经含一层
+ *    `& ServicesShape<Services>`；再喂回 `defineServer({ ...server })` 时，新调用的
+ *    `Services` 需要满足 `S & Shape<S> & Shape<S & Shape<S>>` —— `ServicesShape` 被套
+ *    两层，且带 `NoInfer<>` 的家庭成员使反向推断不可逆，`Services` 只能回落成 `object`。
+ *    后果：`middlewares` / `routers` 一夜之间拿不到 `ctx.services` 的类型。
+ *    （框架文档自己推荐的模块级测试写法正是 `defineServer({ ...server, routers })`。）
+ *
+ * ## 现在的写法
+ *
+ * 工厂返回**裸 `Services`**（可以正常推导、spread 后也可以正常反推），闸门作为**入参的
+ * 条件类型**追加：
+ *
+ * ```ts
+ * config: ServerConfig<R, C, Cl, S, E> & ServicesGate<S>
+ * ```
+ *
+ * - 形状合法 → `unknown`，交集恒等，什么都不挡。
+ * - 形状非法 → 要求一个**不存在**的 `__services_invalid` 属性，编译失败，且报错文案里
+ *   直接点名违规的键（`{ readonly __services_invalid: "port" }`）。
+ *
+ * 用 `[Services] extends [...]` 的元组包裹是为了**关掉分布式条件类型**；否则联合类型的
+ * `Services` 会被拆开逐个判断。
+ */
+export type ServicesGate<Services> = [Services] extends [ServicesShape<Services>] ? unknown : {
+    readonly __services_invalid: InvalidServiceKeys<Services>;
+};
+/**
+ * `defineServer()` 入参：一个身份块 + 工厂槽位（键顺序=分层）。
+ *
+ * ```
+ * app → resources(env) → config(env+resources) → (clients?)(resources+config)
+ *     → services(resources+config+clients) → middlewares(app+services+config+clients)
+ *     → routers(app+services+clients)
+ * ```
+ *
+ * `clients` 槽位**可选**（省略即空客户端包、`Clients` 退化为空）。
+ *
+ * **应用扩展 env（`Env`）不是槽位**，而是 `defineServer` 的**第一个泛型**（本接口里排最后一位，
+ * 但 `defineServer` 把它提到首位以便单独手写）：手写 `defineServer<{ FOO?: string }>({...})`，或
+ * 不写、从 `resources` / `config` 的 `ctx` 类型标注推导。不声明即无扩展（`Env = object`）。
+ * 手写 `Env` 会让其余泛型退化为 `object`（TS 限制，详见 `defineServer`）。加载走内置逻辑。
+ *
+ * `Services` 上的形状闸门（`ServicesShape<Services>`，N2 §2.5）**不写在本接口上**，而是由
+ * `defineServer` 追加在入参上（`& ServicesGate<Services>`）：本接口的 `services` 返回裸
+ * `Services`，保证类型可正常推导、且 `Server` 产物能原样喂回 `defineServer` 做组合定义。
+ * 详见 `ServicesGate`。
+ */
+export interface ServerConfig<Resources, Config, Clients = object, Services = object, Env = object> {
+    app: AppIdentity;
+    /**
+     * 资源工厂。`ctx` 类型可写 `ResourcesContext<Env>` 声明应用扩展 env —— `Env` 从这里推导、
+     * 并进 `ctx.env`（见 `AppEnv`）。不声明即 `Env = object`（无扩展）。
+     */
+    resources: ResourcesFactory<Resources, Env>;
+    config: ConfigFactory<NoInfer<Resources>, Config, Env>;
+    /**
+     * 外部服务客户端（**我们调用的、地址/凭证来自业务配置的外部服务**）。
+     *
+     * 存在的唯一理由是「`services` 之间禁止互依」与「客户端需要 `config`」这两条约束
+     * 的交集：多个 service / middleware 必须共享同一份客户端，而它们之间没有共享通道。
+     *
+     * **可选**：没有外部客户端就**省略**本槽位（框架默认 `() => ({})`，`Clients` 退化为空）——
+     * 不再要求写一行仪式性的 `clients: () => ({})`。独立成层的意义只在于「分层依赖」
+     * （客户端排在 `config` 之后、`services` 之前），不在于「必须出现」。
+     */
+    clients?: ClientsFactory<NoInfer<Resources>, NoInfer<Config>, Clients>;
+    /**
+     * 业务单元工厂。
+     *
+     * 返回**裸 `Services`**：形状闸门（不许返回 `string` / `number` / `boolean`）在
+     * `defineServer` 的入参上一并施加（`ServicesGate`），不挂在返回类型上——否则
+     * `Server` 产物无法再喂回 `defineServer` 做组合定义。
+     *
+     * `Services` 在这里**故意不加 `NoInfer<>`**：中间件与路由的 `ctx.services` 依赖它的
+     * 推断结果，一旦反向推断被阻断，`Services` 会塌成 `object`。
+     */
+    services: (ctx: ServiceContext<NoInfer<Resources>, NoInfer<Config>, NoInfer<Clients>>) => Services;
+    middlewares: MiddlewaresFactory<NoInfer<Config>, Services, NoInfer<Clients>>;
+    /**
+     * 业务路由注册（**必填**）。
+     *
+     * 框架已自动注册 5 条系统路由（`/` / `/health` / `/system/health` / `/system/info` /
+     * `/system/openapi`，见 `core/modules/system-routes/`），应用侧无需再写 `createSystemRouter`；
+     * 本槽位只用于注册**业务**路由。没有业务路由的应用也必须显式传入（写 `() => {}`），
+     * 以保持槽位结构恒定、无「可省略」分支。
+     *
+     * `Services` 不加 `NoInfer<>`：理由同 `services` 槽位。
+     */
+    routers: RoutersFactory<Services, NoInfer<Clients>>;
+}
+/** 品牌字段值（`Server` 的 `__brand`） */
+export declare const SERVER_BRAND = "taicode.server";
+/** 纯定义产物：同一份定义可同时喂给「启动」与「出 spec」 */
+export type Server<Resources, Config, Clients = object, Services = object, Env = object> = ServerConfig<Resources, Config, Clients, Services, Env> & {
+    readonly __brand: typeof SERVER_BRAND;
+};
+/** `generateOpenApi()` 的返回（OpenAPI 文档对象） */
+export type OpenApiDocument = Record<string, unknown>;
+export {};
+//# 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 { MiddlewareContext, MiddlewareUnit } from '../core/types.js';
+export declare function createCorsMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>): MiddlewareUnit;
+//# 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,EAAc,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAkBrF,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CA4B3G"}

package/output/cors/index.js

@@ -0,0 +1,28 @@
+import cors from '@fastify/cors';
+import { readConfigKey } from '../core/boot/context.js';
+export function createCorsMiddleware(ctx) {
+    const register = 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,
+        });
+    };
+    return { name: 'cors', register };
+}

package/output/index.d.ts

@@ -1,6 +1,12 @@
-export * from './schema/index.js';
+export * from './core/modules/schema/builders.js';
+export { createSuccessResponse, createErrorResponse } from './core/modules/response/index.js';
+export type { ResponseEnvelope, SuccessResponse } from './core/modules/response/index.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,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAC7F,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AACzF,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"}