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

package/output/app/index.d.ts

@@ -1,16 +1,19 @@
-import './type-augment.js';
-export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
-export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
-export type { ConfigEnv } from './env.js';
-export { UserError, SystemError } from './errors.js';
-export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
-export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
-export { REQUEST_ID_HEADER } from './core/request-id.js';
-export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
-export { extractPermissionOperations } from './permission-operations.js';
-export type { AppIdentity, AppInstance, LoggerLike, MaybePromise, RedisHandle, Live, ResourcesView, AssertNoDependencies, ServicesShape, ResourcesContext, ResourcesFactory, ConfigContext, ConfigFactory, ServiceUnit, ServiceContext, ServicesFactory, MiddlewareUnit, MiddlewareContext, MiddlewaresFactory, RouterContext, RoutersFactory, ServerConfig, Server, StartServerOptions, ShutdownContext, OpenApiDocument, } from './types.js';
-export type { CacheSetupParams } from './redis.js';
-export type { PermissionOperation } from './permission-operations.js';
-export type { CorsMiddlewareOptions, ContextMiddlewareOptions, AuthMiddlewareOptions, AuthSkip, AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult, AccountIntegrationConfig, RateLimitMiddlewareOptions } from './middleware/index.js';
-export type { AccessControl, RateLimitRule } from './type-augment.js';
+import '../core/type-augment.js';
+export { defineServer, startServer, generateOpenApi } from '../core/entries.js';
+export { createTestServer } from '../core/test-support/test-server.js';
+export { createTestServiceContext } from '../core/test-support/service-context.js';
+export type { TestServiceContextOptions } from '../core/test-support/service-context.js';
+export { loadRuntimeEnvironment } from '../core/test-support/environment.js';
+export { createCorsMiddleware } from '../cors/index.js';
+export { createAuthMiddleware } from '../auth/index.js';
+export { createRateLimitMiddleware } from '../rate-limit/index.js';
+export { createRedis, createCache } from '../redis/index.js';
+export { defineResource } from '../core/resource.js';
+export { defineTestData } from '../core/test-support/testdata.js';
+export type { TestDataContext, TestDataDefinition, TestDataDefinitionOf, TestDataRunParams, TestDataScript, TestDataScriptOf, TestDataUnit, } from '../core/test-support/testdata.js';
+export type { AppEnv, AppInstance, ClientsContext, ClientsFactory, ClientsView, ConfigContext, LoggerLike, Middleware, MiddlewareContext, MiddlewareEntry, MiddlewareUnit, ResourceUnit, ResourcesContext, ResourcesView, RouterContext, ServiceContext, } from '../core/types.js';
+export type { AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult } from '../auth/index.js';
+export type { AuthMiddlewareOptions } from '../auth/index.js';
+export type { AuthClient, AuthVerifyPayload, RegisterPermissionOperationsPayload, } from '../core/modules/auth-provider/index.js';
+export type { RateLimitMiddlewareOptions } from '../rate-limit/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAEA,OAAO,mBAAmB,CAAA;AAG1B,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGjG,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACvI,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAA;AAGtF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAG3K,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AAGxE,YAAY,EAEV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EAEX,IAAI,EACJ,aAAa,EACb,oBAAoB,EACpB,aAAa,EAEb,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EAEd,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAA;AAC1O,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AA8HA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAQtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAA;AAClF,YAAY,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAA;AAyBxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AAyC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAuB5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AA0BpD,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACjE,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,kCAAkC,CAAA;AAGzC,YAAY,EACV,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}

package/output/app/index.js

@@ -1,18 +1,330 @@
-// 提供 `request.user` / `request.token` / `request.ctx` 与 `routeOptions.config.accessControls`
-// 的统一类型增强。
-import './type-augment.js';
-// ── 入口 API（N1 §1 / N2 §2.8 / §2.10 / §2.11）───────────────────
-export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
-// ── 配置层（env 固定加载）────────────────────────────────────────
-export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
-// ── 错误类型（N2 §2.12）──────────────────────────────────────────
-export { UserError, SystemError } from './errors.js';
-// ── 引导期 helper（`resources(ctx)` 里按需调用）─────────────────
-export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
-// ── 标准中间件单元 ───────────────────────────────────────────────
-export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
-// ── 公共路由 / header 常量 ───────────────────────────────────────
-export { REQUEST_ID_HEADER } from './core/request-id.js';
-export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
-// ── 权限操作目录（框架内置；各仓用它替代自写实现）───────────────
-export { extractPermissionOperations } from './permission-operations.js';
+// 服务入口 barrel（`@taicode/common-server/app`）：**业务仓唯一需要 import 的路径**。
+//
+// 这里只有两样东西：**入口 API**（定义 / 启动 / 出文档 / 测试）与**可替换的能力工厂**
+// （中间件、Redis）。框架自己决定得了一律不进这里——core 装配、`request.ctx`、系统路由、
+// 响应信封全部在内部固定完成。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 三十秒上手：一个服务写两个文件（出 spec 是构建期的第三个）
+// ─────────────────────────────────────────────────────────────
+//
+// ```ts
+// // source/server.ts —— **只定义，不启动**：不建连、不 listen、不读库
+// import { defineServer } from '@taicode/common-server/app'
+//
+// export const server = defineServer({
+//   app: { service: 'release', title: 'Release Service', version: packageJson.version },
+//
+//   // 我们拥有的基础设施：**只读 env**，构造时不建连。
+//   // 要扩展 env 类型？两种写法：① 手写首位泛型 `defineServer<{ FOO?: string }>({...})`（简单，但
+//   // 其余泛型会退化为 object）；② 给工厂 ctx 标注 `ResourcesContext<{ FOO?: string }>`（其余泛型照常推导）。
+//   // 加载都走内置逻辑，框架不提供自定义加载。
+//   resources: ({ env, disposer }) => ({ database: createDatabase(env.DATABASE_URL) }),
+//
+//   // 启动期的配置快照：可以读库，一次读完、进程内不再变
+//   config: ({ resources }) => loadConfig(resources),
+//
+//   // 可选：我们调用的外部服务（地址 / 凭证来自 config，故排在 config 之后）；没有就省略
+//   clients: ({ config }) => ({ webhook: createWebhookClient(config.webhook) }),
+//
+//   // 业务单元：**服务之间禁止互依**，要共享的东西放 clients
+//   services: ({ resources, config, clients }) => ({ user: createUserService({ resources, config, clients }) }),
+//
+//   // 中间件：**有序数组，数组位置即注册序**；标准工厂返回具名单元，直接按序摆进去
+//   middlewares: (ctx) => [createCorsMiddleware(ctx), createAuthMiddleware(ctx, { client })],
+//
+//   // 业务路由：**只能拿 app / services / clients**（绕不过 service 直连数据层）
+//   routers: ({ app, services }) => {
+//     app.register(createUserRouter(services.user))
+//   },
+// })
+// ```
+//
+// ```ts
+// // source/index.ts —— 启动（listen + 信号处理都在这里面）
+// import { startServer } from '@taicode/common-server/app'
+// import { server } from './server'
+//
+// await startServer(server)
+// ```
+//
+// ```ts
+// // build/openapi-gen.ts —— 出 spec（不连库、不建连、不要求配置有效）
+// import { generateOpenApi } from '@taicode/common-server/app'
+// import { server } from '../source/server'
+//
+// await writeFile('openapi.json', JSON.stringify(await generateOpenApi(server), null, 2))
+// ```
+//
+// ─────────────────────────────────────────────────────────────
+// ## 每个槽位能拿什么（拿不到的就是**故意**拿不到）
+// ─────────────────────────────────────────────────────────────
+//
+// | 槽位 | ctx 里有 | 刻意没有 | 为什么 |
+// |---|---|---|---|
+// | `resources` | `env`（可标注扩展） / `log` / `disposer` / `registerClassifyError` | `config` / `services` / `app` | 资源只依赖 env，从结构上消灭「资源依赖配置」的循环 |
+// | `config` | `env`（可标注扩展） / `log` / `disposer` / `resources` | `services` / `app` | 此时服务还没构造 |
+// | `clients`（可选） | `log` / `disposer` / `resources` / `config` | `env` / `services` / `app` | 运行期不许回头读 env；客户端地址来自 config |
+// | `services` | `log` / `disposer` / `resources` / `config` / `clients` | `env` / `services` / `app` | 服务层属运行期；禁 service 互依 |
+// | `middlewares` | `app` / `log` / `disposer` / `services` / `config` / `clients` | `resources` / `env` | 中间件碰数据必须穿过 service |
+// | `routers` | `app` / `log` / `disposer` / `services` / `clients` | `resources` / `env` / `config` | 路由只能穿过 service |
+//
+// 唯一的**可选**槽位是 `clients`（省略即空客户端包）；其余槽位恒定，没有业务路由也要写
+// `routers: () => {}`。应用扩展 env **不是槽位**，而是 `defineServer` 的**第一个泛型**：可手写
+// `defineServer<{ FOO?: string }>({...})`（简单，但其余泛型退化为 object），或给 `resources` /
+// `config` 的 `ctx` 标注 `ResourcesContext<Env>`（其余泛型照常推导）。加载仍走内置逻辑，框架不提供自定义加载。
+//
+// 资源释放**在创建处登记**：`ctx.disposer.add(() => closeXxx())`，关闭时框架按阶段逆序 flush，
+// 调用方不需要在任何地方再写一遍 close 逻辑。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 路由怎么写（`operationId` 必须有）
+// ─────────────────────────────────────────────────────────────
+//
+// 每个路由都要给 schema，`operationId` / `summary` / `description` / `tags` 缺一即报错。
+// `operationId` 不是文档装饰：**权限目录就是从它采集的**（启动时 `auth` 上报给 account），
+// 没有它这个接口在权限系统里就是「未知操作」。
+//
+// ```ts
+// app.post('/user', {
+//   schema: routerSchema({
+//     operationId: 'createUser',
+//     summary: '创建用户',
+//     description: '管理员创建用户，返回创建后的实体',
+//     tags: ['user'],
+//     body: z.object({ username: z.string() }),
+//     response: { 200: userSchema },
+//   }),
+//   config: {
+//     accessControls: ['IgnorePermission'],        // 免登录写 'NoLoginRequired'
+//     rateLimit: { limit: 100, window: 60 },       // 可选：需装 rateLimit 中间件
+//   },
+// }, handler)
+// ```
+//
+// 返回体会被框架包成 `{ status, message, data }`，你只管返回业务数据；错误就
+// `throw new UserError(...)` / `throw new SystemError(...)`（从 `@taicode/common-base` 引，
+// 不是从本包）——状态码映射与信封由框架统一处理，**不要在路由里手拼响应体**。
+//
+// ─────────────────────────────────────────────────────────────
+// ## 目录布局（见 `common/product/designs/create-server/design.md` §7.1）
+// ─────────────────────────────────────────────────────────────
+// ```
+// source/
+// ├── core/            核心设计（锁定：不可替换、不可修改，**不对外导出装配**）
+// │   └── test-support/  测试支持（`createTestServer` / `loadRuntimeEnvironment`）
+// ├── app/             服务入口 barrel（本文件，不含实现）
+// ├── auth/            可选：鉴权中间件
+// ├── cors/            可选：CORS 中间件
+// ├── rate-limit/      可选：限流中间件 + 限流实现
+// ├── redis/           请求期 Redis / 缓存 helper
+// └── redis-queue/     可选：Redis 队列（含自己的 `test` 辅助）
+// ```
+//
+// 测试工具**与正式工具同一个导出面**（不多开 `test-support` subpath）：入口的测试同构体
+// 就是入口，分两个出口只会让调用方多记一个路径。归属按「谁提供功能，谁提供配套测试工具」：
+// 队列的测试辅助在 `redis-queue` 里，服务装配的测试入口在 `core/test-support/` 里。
+import '../core/type-augment.js';
+// ── 入口 API（定义 / 启动 / 出文档 / 测试）─────────────────────────
+export { defineServer, startServer, generateOpenApi } from '../core/entries.js';
+// 测试对象的**唯一**构造方式：同一份 `defineServer` 定义、同一套装配，不给槽位覆盖入口。
+//
+// env 加载、测试库结算、闸门、`process.env.DATABASE_URL` 改写都是它的**内部步骤**，
+// 不单独导出。导出那一步就等于把「什么时候该跑闸门」交给调用方——顺序本身就是安全前提，
+// 历史上有仓把环境闸门排在 env 加载之前（判的是空的 `ENV`），守卫于是变成装饰。
+//
+// ── 测试怎么写 ──────────────────────────────────────────────
+//
+// ```ts
+// import { createTestServer } from '@taicode/common-server/app'
+// import { server } from '../server'
+//
+// describe('UserRouter', () => {
+//   let testServer: Awaited<ReturnType<typeof createTestServer>>
+//   let db: PrismaClient
+//
+//   beforeAll(async () => {
+//     testServer = await createTestServer(server)   // 唯一构造方式
+//     db = testServer.resources.database            // 生产用的那个客户端，不是新建的
+//   })
+//
+//   afterAll(async () => {
+//     await testServer.app.close()                  // 八步关闭，与生产同一条路径
+//   })
+//
+//   beforeEach(async () => {
+//     await db.user.deleteMany()                    // 真实数据库，不 mock
+//   })
+//
+//   it('创建用户', async () => {
+//     const res = await testServer.app.inject({
+//       method: 'POST',
+//       url: '/user',
+//       payload: { username: 'alice' },
+//     })
+//
+//     expect(res.statusCode).toBe(200)
+//     expect(await db.user.count()).toBe(1)         // 断言落库，不只断言响应
+//   })
+//
+//   it('service 行为', async () => {
+//     // 也可以完全不走 HTTP：直接调装配好的业务单元
+//     await testServer.services.user.create({ username: 'bob' })
+//   })
+// })
+// ```
+//
+// **三条规矩**：
+// 1. **不要 mock 数据库 / Redis / 外部依赖**。它们由 `resources` / `clients` 真实构造，
+//    测试连的是 `*_test` schema 上的真库。要替换某个外部服务，改组合（见下），不改装配。
+// 2. **不要另造构造器**（`createTestApp` / `createTestDb` / `new PrismaClient()`）。
+//    另造一份就等于测试里有第二套接线，绿了也不能说明生产是对的。
+// 3. **只测一个模块**时组合定义，不要覆盖槽位：
+//    ```ts
+//    const onlyUser = defineServer({
+//      ...server,
+//      routers: ({ app, services }) => app.register(createUserRouter(services.user)),
+//    })
+//    const testServer = await createTestServer(onlyUser)
+//    ```
+//
+// 返回值 `TestServer` 就是测试需要的一切：`app`（原生 Fastify，用 `inject()`）/
+// `env`（`env.DATABASE_URL` 就是本次实际连的测试连接串）/ `resources` / `config` /
+// `clients` / `services` / `log`。没有 `close()` 之类同义包装——关闭就是 `app.close()`。
+export { createTestServer } from '../core/test-support/test-server.js';
+// ── 单元级测试的 `services` 入参 ─────────────────────────────────
+//
+// `createTestServer()` 跑全量装配，适合集成用例；只想验一个 service 的判断逻辑时，
+// 此前四个仓各写一份 `createServiceContext(fakeDb, {...})`，且都带同一句
+// `as unknown as XxxServiceContext` —— 同一个绕过动作被抄多遍，说明缺的是框架能力。
+// 于是把它收进框架：**不伪造能力，只允许缺省能力**（缺省的键被读到当场抛错并点名）。
+export { createTestServiceContext } from '../core/test-support/service-context.js';
+// ── 工具进程的 env 出口（**不在任何入口里跑**的进程）──────────────
+//
+// `prisma.config.ts` / `scripts/*.ts` / 被它们静态 import 的配置模块：ES 模块顶层求值早于
+// 入口函数执行，所以「入口里加载 env」救不了这些文件。这个函数就是它们唯一的开口，只加载
+// 运行期分层、不带任何测试闸门。
+//
+// **什么时候需要它**：你的文件**不是** `startServer` / `createTestServer` 启动的，
+// 却要读 `process.env`（数据库连接串、Redis 地址、脚本参数）。
+//
+// ```ts
+// // prisma.config.ts —— 必须在任何读取 env 的 import 之前调用
+// import { loadRuntimeEnvironment } from '@taicode/common-server/app'
+// loadRuntimeEnvironment()
+//
+// // scripts/seed.ts
+// import { loadRuntimeEnvironment } from '@taicode/common-server/app'
+// const env = loadRuntimeEnvironment()
+// console.log(env.DATABASE_URL)
+// ```
+//
+// **什么时候不要用它**：`source/server.ts` / `source/index.ts` / 测试文件。前者由
+// `startServer` 负责，后者由 `createTestServer` 负责——在那些地方再调一次只是重复读 dotenv，
+// 还会让人误以为 env 需要自己加载。
+export { loadRuntimeEnvironment } from '../core/test-support/environment.js';
+// ── 可替换的标准中间件工厂 ────────────────────────────────────────
+//
+// 只在**要改默认行为**时才出现；不写就是框架默认。三者都接收 `middlewares` 槽位的 `ctx`，
+// 都返回**具名单元**（`MiddlewareUnit`），按顺序摆进 `middlewares` 数组即可：
+//
+// ```ts
+// middlewares: (ctx) => [
+//   createCorsMiddleware(ctx),                      // 允许的源来自 config 的 `cors` 键（请求期现读）
+//   createAuthMiddleware(ctx, { client }),          // client 必填：鉴权提供方实现
+//   createRateLimitMiddleware(ctx, { store }),      // store 可选，缺省进程内 memory
+// ]
+// ```
+//
+// **数组位置即注册序**（cors → auth → rateLimit）：不再用对象键序（键序由引擎决定、纯数字键
+// 还会被重排）。要插入自定义中间件，返回具名单元 `{ name, register }` 或一个裸注册函数即可。
+//
+// `cors` / `rateLimit` 都**没有行为开关**，配置面只有输入参数：
+// - `cors`：允许的源来自 `config.cors`（`{ enabled, origins }`）；未配置 → 放行任意源并 warn 一次。
+// - `rateLimit`：**限流规则写在路由上**，不在中间件里：
+//   ```ts
+//   app.get('/user', {
+//     schema: ...,
+//     config: { rateLimit: { limit: 100, window: 60, keys: ['ip'] } },  // 未声明的路由不空转
+//   }, handler)
+//   ```
+//   需要 Redis 存储时，在 `services` 里构造 `RedisRateLimitStore` 再注入 `store`
+//   （中间件拿不到 `resources`，这是刻意的）。
+//
+// ⚠️ 限流计数属于**单元内存状态**：它不会被 `clean()` 清掉（那是库外的东西），
+// 只有重新装配（`TestServer.reprovision()` 重跑 `init()`）才能得到干净基线。
+// 因此 store 必须由 `services` 单元提供：在中间件里 `new MemoryRateLimitStore()` 会让
+// 实例只活在那次 `register(app)` 的闭包里，测试拿不到句柄，只能靠伪造 `remoteAddress`
+// 换桶——那是测试在迁就实现细节。见 `rate-limit/types.ts` 的 `RateLimitStore.clear()`。
+//
+// `auth` 的两件事由框架固定、**不可关闭**：① 跳过判定（`OPTIONS` / 无匹配路由；
+// `NoLoginRequired` **不再跳过身份解析** —— 免登录路由改为「有凭证就解析并回填身份、
+// 解析失败按匿名放行」，否则 `/permission/user/operation/list` 恒返回空清单、
+// `/sign-out` 删不掉 SignIn Secret）；② 启动时从 `app.swagger()` 采集权限目录并上报。
+// 你只需要实现 `AuthClient` 的 `verify` / `registerPermissionOperations` 两个方法。
+export { createCorsMiddleware } from '../cors/index.js';
+export { createAuthMiddleware } from '../auth/index.js';
+export { createRateLimitMiddleware } from '../rate-limit/index.js';
+// ── 请求期 Redis / 缓存 helper（资源包里自行构造）─────────────────
+//
+// 框架**不替你建 Redis**；在 `resources` 里按需构造，并在创建处登记释放：
+//
+// ```ts
+// resources: ({ env, log, disposer }) => {
+//   const redis = createRedis(env, log)          // 无 REDIS_URL → undefined
+//   if (redis) disposer.add(() => redis.dispose())
+//   return { redis, cache: createCache({ env, prefix: 'release', redis }) }
+// }
+// ```
+//
+// 两者都是**惰性包装**：构造时不建连、不 ping，首次真正使用才连——「出 spec 不连库 / 不连
+// Redis」因此是结构性的，而不是靠调用方自觉。`createCache` 不传 `redis` 也能用（自建客户端，
+// 或在没有 `REDIS_URL` 时退化成纯进程内一级缓存）。
+export { createRedis, createCache } from '../redis/index.js';
+// ── 资源单元（槽位内的生命周期）────────────────────────────────
+//
+// 资源多是第三方对象（PrismaClient / Redis client），形状改不了，所以 `setup()` 挂在外壳上：
+//
+// ```ts
+// resources: (ctx) => ({
+//   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+//     async setup() { await pushSchema(ctx.env.DATABASE_URL) },   // 框架在 config 之前调
+//   }),
+// })
+// ```
+//
+// 三个生命周期各管一段：
+// - `setup()`     框架在 `config` 之前调（两个入口都跑）；
+// - `clean()`     框架在重新装配前调（**仅测试入口**，`TestServer.reprovision()`）；
+// - `dispose()`   框架在关闭流程最后一步调（两个入口都跑）。
+//
+// 「用例之间重置数据」（清表、清缓存、重新插入样本数据）**不在资源上**：资源只知道有哪些表 /
+// 哪些 key，不知道谁往里写了什么。它由一套独立机制承担：`packages/server/testdata/*.ts|js`，
+// 每个脚本自带 `load(ctx)`（+ 可选 `cleanup(ctx)`），框架在 `development` / `test` 下自动装载并执行。
+// 两者串起来的唯一入口是 `createTestServer` 返回的 `reprovision()`。
+export { defineResource } from '../core/resource.js';
+// ── 测试数据脚本（`testdata/`）声明 ──────
+//
+// `testdata/*.ts` 的**推荐写法**是默认导出一个 `defineTestData({ … })`：结构显式、缺 `load`
+// 在定义期就报错（不是等到装载期才发现），`ctx` 的类型由泛型一次性带进来：
+//
+// ```ts
+// import { defineTestData } from '@taicode/common-server/app'
+// import type { server } from '../source/server' // 纯类型导入，无副作用
+//
+// export default defineTestData<typeof server>({
+//   dependsOn: ['01-database'],
+//   async load(ctx) { … },
+// })
+// ```
+//
+// `cleanup` 是**可选**的：库里的行由资源单元的 `clean()` 在重新装配前清掉，只有「资源清不掉
+// 的东西」（下游 mock 预置状态 / 临时文件）才需要自己写。
+//
+// 命名导出 `load` / `cleanup`（+ 可选 `dependsOn`）继续支持，用于把脚本当对象传
+// （如测试里手造 in-memory 脚本）。同一个文件两者都有时**默认导出优先**。
+//
+// `ctx` 在 `app.ready()` 之后构造，因此装配产物全都在：`env` / `resources` /
+// `config` / `clients` / `services` / `log`。**唯一不给的是 `app`**——拿到它就能 `inject()`，
+// 等于用业务链路（中间件 / 信封 / 错误映射）造数据，基线就不再确定。
+export { defineTestData } from '../core/test-support/testdata.js';

package/output/auth/index.d.ts

@@ -0,0 +1,73 @@
+import type { AuthClient, AuthVerifyPayload } from '../core/modules/auth-provider/index.js';
+import type { MiddlewareContext, MiddlewareUnit } from '../core/types.js';
+/**
+ * 标准中间件单元 `auth`（可替换）。
+ *
+ * 本单元只做「**框架语义**」，不碰任何鉴权提供方的 HTTP：
+ *
+ * 1. 跳过判定（**固定**：`OPTIONS` → 无匹配路由）；`NoLoginRequired` 的免登录语义在
+ *    请求期展开为「有凭证就解析、解析失败按匿名放行」，**不会**跳过身份解析；
+ * 2. 取凭证（`Authorization: Bearer` / `Authorization: apikey-*` / `cookieNames` 声明的 cookie）；
+ * 3. 调 `client.verify`，把结果写回 `request.user` / `request.token`；
+ * 4. `onReady` 时调 `client.registerPermissionOperations`（**强制**，失败不致命）。
+ *
+ * 权限目录**只从 OpenAPI 文档派生**（`app.swagger()`）：core 保证「所有路由必须声明 schema」
+ * （缺失直接启动失败），所以文档里出现什么，权限系统里就有什么，不存在两套来源漂移的可能。
+ *
+ * **提供方是业务注入的，且可替换**（本文件的 `client`，类型见
+ * `core/modules/auth-provider`）：account 只是当前的主要实现，不是框架的预设——
+ * 自建 IAM、OIDC 网关、进程内静态校验都可以填进来。客户端构造需要地址、凭证、
+ * 协议与 HTTP 栈，这些只有业务侧才知道怎么配，框架不提供实现（设计 §5.2.2）。
+ *
+ * ## 为什么配置面只有两个字段
+ *
+ * `skip` / `mapError` / `registerPermissions` 曾经也是选项，现全部删除：
+ *
+ * - **跳过逻辑不可自定义**：放行是安全决策，一旦可按服务改写，「这条路由到底要不要
+ *   登录」就不再能从路由声明上读出来。约定只剩一条——**需要公开就声明
+ *   `config.accessControls: ['NoLoginRequired']`**。
+ * - **错误映射不可自定义**：错误分类是响应契约的一部分（401/403 还是 500），让调用方
+ *   替换就等于允许各仓自造状态码。标准做法是提供方**自己抛** `UserError` /
+ *   `SystemError`，框架原样透出；其它一切（网络 / 超时 / 非 JSON）统一
+ *   `SystemError('EXTERNAL_SERVICE_ERROR')`。
+ * - **权限自注册不可关闭**：权限目录是 account 侧判权的前提，关掉它等于让本服务的
+ *   全部接口在权限系统里变成「未知操作」，只有坏处。
+ *
+ * 剩下两个字段都是**输入参数**（不是行为开关）：提供方客户端 + 凭证在哪个 cookie 里。
+ */
+/** `verify` 的入参：框架校验入参 + 服务名 */
+export type AuthVerifyInput = AuthVerifyPayload;
+/** 请求元信息 / 校验结果（形状定义在 auth-provider 契约里） */
+export type { AuthVerifyMetadata, AuthVerifyResult } from '../core/modules/auth-provider/index.js';
+/**
+ * `auth` 中间件的配置面：**只接受输入参数**，不提供行为开关。
+ *
+ * 标准行为（跳过判定 / 错误归类 / 权限自注册）由框架固定，不开放覆盖——
+ * 见文件头的「为什么配置面只有两个字段」。
+ */
+export interface AuthMiddlewareOptions {
+    /**
+     * 鉴权提供方客户端（**必填**，业务服务实现；框架只定义契约，**允许任意实现替换**）。
+     *
+     * 由业务在自己的 `middlewares` 槽位里构造（可读 `ctx.config` / `ctx.services`），
+     * 职责：校验凭证 + 上报权限目录。account 只是其中一种实现——自带校验逻辑的服务
+     * （如 account 自己）实现同一个接口走进程内调用即可，不必绕 HTTP 回自己。
+     * 契约见 `core/modules/auth-provider`。
+     */
+    client: AuthClient;
+    /**
+     * 读取 token 的 cookie 名（**显式声明优先**）。
+     *
+     * 未传或传空数组时，请求期现读配置的 `server.cookieNames`（各仓的 cookie 名由运维改配置，
+     * 不能在注册期就定下）；仍为空则回落 `['token']`。
+     */
+    cookieNames?: readonly string[];
+}
+/**
+ * 构造标准 `auth` 中间件（具名单元 `name: 'auth'`）。
+ *
+ * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
+ * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
+ */
+export declare function createAuthMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options: AuthMiddlewareOptions): MiddlewareUnit;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/auth/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAG3F,OAAO,KAAK,EAAuC,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAG9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAE/C,4CAA4C;AAC5C,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAElG;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AA+ID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA8E3I"}