secure-upload-fastify-sdk 1.0.1 → 1.0.3

package/README.md

@@ -17,6 +17,7 @@
 - **可自定义 Session 校验** — 默认 base64-decode JWT payload，可注入 `jwt.verify()` 完整验签
 - **后台任务** — 过期 `uploadId` 清理 + 孤儿文件扫描，全部可关闭
 - **严格秒传隔离（v1.0.0+）** — 按 `(contentHash, isPublic, userId)` 三元组匹配，公开池/私有池/不同用户之间完全隔离
+- **可配置 /smart/init 批量上限（v1.0.2+）** — `rateLimit.smartMaxFilesPerInit` 动态生效，工厂函数生成 zod schema，业务校验 + 启动日志同源
 
 ---
 
@@ -308,6 +309,102 @@ await app.register(secureUploadPlugin, {
 
 ---
 
+## 🔧 /smart/init 批量上限配置链路（v1.0.2+）
+
+`/smart/init` 是"一次接收 N 个文件 → 智能分流 ONE_SHOT / MULTIPART"的批量入口。  
+`N` 的上限在 **v1.0.2 之前**是 SDK 内部写死的 `z.array(...).max(50)`,业务方即便配置 `smartMaxFilesPerInit: 200` 也会被 zod 校验直接拒绝。
+
+**v1.0.2 修复**:`/smart/init` 的请求体 schema 改为工厂函数,`maxFiles` 从 `rt.config.smartMaxFiles` 读取,与业务校验、`rateLimit`、启动日志**同源**。
+
+```ts
+// src/server/routes/smart.ts
+function makeSmartInitBodySchema(maxFiles: number) {
+  return z.object({
+    files: z.array(FileInitItemSchema).min(1).max(maxFiles),
+  }).strict();
+}
+
+// handler 里动态生成
+const schema = makeSmartInitBodySchema(rt.config.smartMaxFiles);
+const body = schema.parse(req.body ?? {});
+
+// 业务侧防御性兜底(同源,防止 rt.config 异常时被绕过)
+if (body.files.length > rt.config.smartMaxFiles) {
+  throw new SecureError(ErrorCode.BATCH_TOO_MANY_FILES, ...);
+}
+```
+
+### 完整配置链路
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ ① backend/.env                                                 │
+│    UPLOAD_SMART_MAX_FILES_PER_INIT=200     # 单次 /smart/init   │
+│    UPLOAD_SMART_INIT_RATE_LIMIT=200        # 60s 配额           │
+└─────────────────────────┬──────────────────────────────────────┘
+                          │ dotenv 加载
+                          ▼
+┌────────────────────────────────────────────────────────────────┐
+│ ② backend/apps/upload-service/src/_bootstrap.ts                │
+│    getUPLOADConfig()                                           │
+│      → cfg.UPLOAD_SMART_MAX_FILES_PER_INIT = 200               │
+│      → cfg.UPLOAD_SMART_INIT_RATE_LIMIT     = 200              │
+└─────────────────────────┬──────────────────────────────────────┘
+                          │ app.ts 第 130 行
+                          ▼
+┌────────────────────────────────────────────────────────────────┐
+│ ③ upload-service/src/app.ts                                    │
+│    sdkOptions.rateLimit = {                                    │
+│      smartMaxFilesPerInit: cfg.UPLOAD_SMART_MAX_FILES_PER_INIT,│
+│    }                                                           │
+│    app.register(secureUploadPlugin, sdkOptions)                │
+└─────────────────────────┬──────────────────────────────────────┘
+                          │ 插件 option → 运行时配置
+                          ▼
+┌────────────────────────────────────────────────────────────────┐
+│ ④ SDK 内部 (this SDK)                                          │
+│    options.rateLimit.smartMaxFilesPerInit                      │
+│      → rt.config.smartMaxFiles                                 │
+│      → rt.config.smartInitRateLimit                            │
+└─────────────────────────┬──────────────────────────────────────┘
+                          │ 三处消费
+                          ▼
+┌────────────────────────────────────────────────────────────────┐
+│ ⑤ src/server/routes/smart.ts                                   │
+│    a) 启动日志(app.log.info):                                  │
+│       maxFiles: 200,  rateLimit: 200                           │
+│    b) zod schema(工厂函数):                                    │
+│       makeSmartInitBodySchema(rt.config.smartMaxFiles)         │
+│    c) 业务校验兜底:                                            │
+│       if (body.files.length > rt.config.smartMaxFiles)         │
+│         throw BATCH_TOO_MANY_FILES                             │
+│    d) 滑动窗口限流:                                            │
+│       slidingWindowRateLimit(..., rt.config.smartInitRateLimit)│
+└────────────────────────────────────────────────────────────────┘
+```
+
+### 启动时确认
+
+启动 `upload-service` 后,日志里应看到:
+
+```text
+🔧 smart-routes: 注册 smart 上传路由(...)
+  maxFiles: 200    ← 从 .env UPLOAD_SMART_MAX_FILES_PER_INIT 透传
+  rateLimit: 200   ← 从 .env UPLOAD_SMART_INIT_RATE_LIMIT 透传
+```
+
+> **为什么不用默认值?**  
+> 批量上传场景下,前端 `SmartClient` 一次发 60~200 个小文件很常见;  
+> 默认 50 适合"小批量场景",需要批量化时应**主动**调大,避免被 zod 静默拒在 400。
+
+### 升级到 v1.0.2 的 3 步
+
+1. 升级 SDK 版本:`secure-upload-fastify-sdk: ^1.0.1` → `^1.0.2`
+2. 业务侧 `pnpm install`(workspace 重链接 symlink)
+3. 重建 SDK:`pnpm build`(否则后端拿到的还是旧版 dist)
+
+---
+
 ## ⚡ 秒传隔离
 
 `/multipart/init` 和 `/smart/init` 都支持秒传:传 `expectedHash` 时,服务端按 `(contentHash, isPublic, userId)` 三元组查询已有 `File` 记录。
@@ -342,7 +439,7 @@ await app.register(secureUploadPlugin, {
 | `suggestedClientConcurrency` | `number` | `3` | 建议客户端并发 part 数 |
 | `rateLimit.initPerMin` | `number` | `30` | `/multipart/init` 限流 |
 | `rateLimit.partPerMin` | `number` | `600` | `/multipart/part` 限流 |
-| `rateLimit.smartMaxFilesPerInit` | `number` | `50` | `/smart/init` 单次最多文件数 |
+| `rateLimit.smartMaxFilesPerInit` | `number` | `50` | `/smart/init` 单次最多文件数(**v1.0.2+ 可配置**,从 `.env UPLOAD_SMART_MAX_FILES_PER_INIT` 透传,详见下文"配置链路"章节) |
 | `pathPrefix.multipart` | `string` | `'/multipart'` | 分片路由挂载前缀 |
 | `pathPrefix.smart` | `string` | `'/smart'` | smart 路由挂载前缀 |
 | `fileUrlPrefix` | `string` | `'/files'` | complete 响应 `url` 字段前缀 |
@@ -462,6 +559,47 @@ HTTP 状态码映射由 `getHttpStatus(code)` 给出,用户业务侧可直接用
 
 ---
 
+## 📝 Changelog
+
+### v1.0.2 — /smart/init 批量上限可配置化
+
+**🛠 Fix / Feature**
+
+- **`/smart/init` 请求体 zod schema 改为工厂函数**  
+  `makeSmartInitBodySchema(maxFiles: number)` 接收 `maxFiles` 参数,handler 里用 `rt.config.smartMaxFiles` 动态生成。  
+  修掉了 v1.0.1 写死 `z.array(...).max(50)` 导致 `rateLimit.smartMaxFilesPerInit` 配置**完全不生效**的 bug。
+
+- **业务校验保留为防御性兜底(同源)**  
+  `if (body.files.length > rt.config.smartMaxFiles)` 仍在 handler 里显式抛 `BATCH_TOO_MANY_FILES`,防止 `rt.config` 异常时被绕过。
+
+- **启动日志暴露 `maxFiles` + `rateLimit`**  
+  `app.log.info({ routes, maxFiles, rateLimit }, '🔧 smart-routes: ...')`,便于运维一眼确认配置是否生效。
+
+**⚙️ 影响面**
+
+| 组件 | 行为 | 是否需要改动 |
+|------|------|-------------|
+| SDK consumer(上传插件调用方) | 自动透传 `rateLimit.smartMaxFilesPerInit` → 运行时 `smartMaxFiles` | ❌ 无需改代码,只需升级 SDK 版本 |
+| `backend/.env` | 新增 `UPLOAD_SMART_MAX_FILES_PER_INIT` / `UPLOAD_SMART_INIT_RATE_LIMIT` | ✅ 已在 1.0.2 升级时加上 |
+| `upload-service` `_bootstrap.ts` | 新增 cfg 字段读取 | ✅ 已在 1.0.2 升级时加上 |
+| 前端 `SmartClient` | 调大 `maxFilesPerBatch` 配合后端上限 | ⚠️ 按需,见 `frontend-demo/index.html` |
+
+**🔄 升级步骤**
+
+```bash
+# 1) 升级 SDK 版本号(package.json)
+#    secure-upload-fastify-sdk: ^1.0.1  →  ^1.0.2
+cd secure-upload-fastify-sdk && pnpm build        # 重建 dist
+cd ../backend && pnpm install                     # workspace 重链接
+pnpm dev:all                                      # 启动后端,看启动日志 maxFiles: 200
+```
+
+**🔗 完整配置链路**
+
+见上文「🔧 /smart/init 批量上限配置链路（v1.0.2+）」章节的链路图。
+
+---
+
 ## 📄 License
 
 MIT

package/dist/index.js

@@ -1615,9 +1615,11 @@ var FileInitItemSchema = import_zod2.z.object({
   expectedHash: import_zod2.z.string().regex(/^[a-f0-9]{64}$/i).optional(),
   meta: import_zod2.z.record(import_zod2.z.unknown()).optional()
 }).strict();
-var SmartInitBodySchema = import_zod2.z.object({
-  files: import_zod2.z.array(FileInitItemSchema).min(1).max(50)
-}).strict();
+function makeSmartInitBodySchema(maxFiles) {
+  return import_zod2.z.object({
+    files: import_zod2.z.array(FileInitItemSchema).min(1).max(maxFiles)
+  }).strict();
+}
 async function processOneFile(req, rt, file, index) {
   try {
     const { userId } = await resolveSession(req, file.isPublic, rt.validateSession);
@@ -1731,7 +1733,8 @@ async function registerSmartRoutes(app, rt) {
     "\u{1F527} smart-routes: \u6CE8\u518C smart \u4E0A\u4F20\u8DEF\u7531(part/complete/abort/status \u590D\u7528 multipart/*)..."
   );
   app.post(`${base}/init`, async (req) => {
-    const body = SmartInitBodySchema.parse(req.body ?? {});
+    const schema = makeSmartInitBodySchema(rt.config.smartMaxFiles);
+    const body = schema.parse(req.body ?? {});
     if (body.files.length > rt.config.smartMaxFiles) {
       throw new SecureError(
         1511 /* BATCH_TOO_MANY_FILES */,
@@ -1972,7 +1975,7 @@ async function secureUploadPluginImpl(app, options) {
       initRateLimit: options.rateLimit?.initPerMin ?? DEFAULTS.initRateLimit,
       partRateLimit: options.rateLimit?.partPerMin ?? DEFAULTS.partRateLimit,
       smartMaxFiles: options.rateLimit?.smartMaxFilesPerInit ?? DEFAULTS.smartMaxFiles,
-      smartInitRateLimit: DEFAULTS.smartInitRateLimit,
+      smartInitRateLimit: options.rateLimit?.smartInitRateLimit ?? DEFAULTS.smartInitRateLimit,
       multipartPath: options.pathPrefix?.multipart ?? DEFAULTS.multipartPath,
       smartPath: options.pathPrefix?.smart ?? DEFAULTS.smartPath,
       fileUrlPrefix: options.fileUrlPrefix ?? DEFAULTS.fileUrlPrefix,