secure-upload-fastify-sdk 1.0.4 → 1.0.6

package/README.md

@@ -18,6 +18,7 @@
 - **后台任务** — 过期 `uploadId` 清理 + 孤儿文件扫描，全部可关闭
 - **严格秒传隔离（v1.0.0+）** — 按 `(contentHash, isPublic, userId)` 三元组匹配，公开池/私有池/不同用户之间完全隔离
 - **可配置 /smart/init 批量上限（v1.0.2+）** — `rateLimit.smartMaxFilesPerInit` 动态生效，工厂函数生成 zod schema，业务校验 + 启动日志同源
+- **complete 业务钩子（v1.0.6+）** — `onComplete` 在文件落库后被调用，可读写已合并 buffer、可返回 patch 升级 file record（典型用法：自动水印、转码、敏感扫描），失败不阻塞主流程，幂等命中跳过
 
 ---
 
@@ -215,11 +216,125 @@ await app.register(secureUploadPlugin, {
 ```
 
 > 默认 `sessionValidator` 只 base64-decode JWT payload 并校验 `exp` + 读 `sub`,不做 HMAC 验签(SDK 不持有 `appSecret`)。
+>
+> **详细 onComplete 钩子契约、类型签名、失败隔离说明、自动水印示例**：见本文档 **"🪝 onComplete 业务钩子（v1.0.6+）"** 章节。
 > 完整安全链路:gateway 已做 JWT 验签,业务服务信任透传的 session;若业务服务要自己验签,通过 `options.sessionValidator` 注入即可。
 > 校验失败应抛 `SecureError(ErrorCode.BINARY_AUTH_REQUIRED / BINARY_AUTH_FAILED)`,SDK 会自动转成 401 响应。
 
 ---
 
+## 🪝 onComplete 业务钩子（v1.0.6+）
+
+> **核心场景**：在文件落到 storage、写到 `File` 表之后，**在 `multipart/complete` 响应返回前**，给你一个机会"加工"这个文件——典型用例：
+> - **自动水印**（upload-service 的 `autoWatermarkOnComplete`）：读明文 → 嵌入可见/数字水印 → put 新文件 → 升级 file record；complete 响应的 url 直接是水印后文件
+> - **图片转码**（WebP / AVIF 压缩）
+> - **敏感词/版权扫描**
+> - **异步转存 / CDN 预热**
+
+### 1. 类型签名
+
+```ts
+import type {
+  OnCompleteHook,
+  OnCompleteContext,
+  OnCompletePatch,
+} from 'secure-upload-fastify-sdk/server';
+
+export type OnCompletePatch = Partial<{
+  storageKey: string;          // 替换指向新文件
+  size: number;                // 新文件字节数
+  contentType: string;         // 新 mime(如 image/webp)
+  watermarked: boolean;        // 标记是否已水印
+  isOriginal: boolean;         // 标记"是不是原图"
+  retentionExpiresAt: Date;    // 自定义保留期
+  meta: Record<string, unknown>;// 附加元数据
+}>;
+
+export type OnCompleteContext = {
+  file: FileRecord;            // 刚写进库的 file record
+  storage: StorageAdapter;     // storage 实例(读/写 / delete)
+  multipart: MultipartUploadRecord;
+  log: FastifyBaseLogger;
+  getOriginalBuffer: () => Promise<Buffer>; // ★ 读已合并文件明文(走 storage.get)
+};
+
+export type OnCompleteHook = (ctx: OnCompleteContext) => Promise<OnCompletePatch | void | undefined>;
+```
+
+### 2. 使用示例（自动水印精简版）
+
+```ts
+import sharp from 'sharp';
+import type { OnCompleteHook } from 'secure-upload-fastify-sdk/server';
+
+const autoWatermark: OnCompleteHook = async (ctx) => {
+  const { file, storage, getOriginalBuffer, log } = ctx;
+
+  // 1) 判条件（图片 + 私有 + 大小允许）
+  if (!file.userId) return;                       // 公开上传跳过数字水印
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.contentType)) return;
+
+  // 2) 读原图
+  const buf = await getOriginalBuffer();
+  const png = await sharp(buf).png().toBuffer();
+
+  // 3) put 水印后文件,新 storageKey
+  const newKey = file.storageKey.replace(/(\.\w+)?$/, '.wm.png');
+  await storage.put(newKey, png, { contentType: 'image/png' });
+
+  // 4) 返回 patch,SDK 会把 file record 升级为水印后版本
+  return {
+    storageKey: newKey,
+    size: png.length,
+    contentType: 'image/png',
+    watermarked: true,
+    isOriginal: false,
+    retentionExpiresAt: new Date(Date.now() + 30 * 86400 * 1000),
+    meta: { autoWatermark: true, sourceFileId: file.id },
+  };
+};
+
+await app.register(secureUploadPlugin, {
+  storage: { adapter: 'local', options: { baseDir } },
+  repository: { kind: 'prisma', prisma },
+  onComplete: autoWatermark,                  // ← 一行接入
+});
+```
+
+### 3. SDK 调用契约（务必读完）
+
+| 场景 | SDK 行为 |
+|------|---------|
+| 钩子返回 `undefined` / `void` | file record 不动,complete 正常 200 返回 |
+| 钩子返回 `OnCompletePatch` | SDK 调 `fileRepo.update(id, patch)`;原 storage 文件**保留**(如需清理可钩子里自己 `storage.delete(oldKey)`) |
+| 钩子**抛错** | **不阻塞**主流程,file record 不变,complete 仍 200;记 `log.warn({ err, fileId }, 'onComplete hook failed')` |
+| 钩子**超时**(若外部包了超时) | 同上:不阻塞,不污染 file record |
+| **idempotent 命中**(同一 uploadId 第二次 complete) | **不调**钩子,直接返回原 fileId(idempotent: true) |
+| `getOriginalBuffer()` | 内部走 `storage.get(file.storageKey)`,**会读完整文件到内存**,大文件注意 |
+| 钩子里再调 `storage` / `fileRepo` | ✅ 安全,但要注意：调 `fileRepo.update` 会覆盖前一个钩子的 patch |
+
+### 4. 失败隔离（设计哲学）
+
+> 上传是核心路径，**任何**钩子失败都不能让用户重新传文件。
+>
+> - 钩子抛错 → SDK catch → log.warn → 仍返回成功响应（原文件 url）
+> - 钩子返回无效 patch（如 storageKey 已存在） → SDK 把 patch 当"无效"，file record 不变，记 warn
+> - 测试可注入"100% 失败"钩子验证主流程不受影响
+
+### 5. 端到端测试覆盖
+
+`tests/hook.test.ts` 用 `InMemoryMultipartRepository` + `InMemoryFileRepository` 覆盖：
+
+1. **钩子在 complete 成功路径调用一次**（不是两次）
+2. **patch 应用** → file record 字段、complete 响应字段都被更新
+3. **`undefined`** → file record 不变
+4. **钩子抛错** → 主流程仍 200，file record 不变
+5. **idempotent 命中** → 不重复调钩子
+6. **`getOriginalBuffer()`** → 内容与上传文件 byte-for-byte 一致
+7. **不传 `onComplete`** → 完全向后兼容（旧代码不受影响）
+
+---
+
 ## 🔐 Secure-Crypto 模式
 
 默认情况下,SDK 从 `req.body` 和 `req.headers['x-secure-raw-base64']` 读数据(`raw` 模式)。  
@@ -438,7 +553,7 @@ if (body.files.length > rt.config.smartMaxFiles) {
 | `ttlSeconds` | `number` | `86400` (24h) | `uploadId` 有效期 |
 | `suggestedClientConcurrency` | `number` | `3` | 建议客户端并发 part 数 |
 | `rateLimit.initPerMin` | `number` | `30` | `/multipart/init` 限流 |
-| `rateLimit.partPerMin` | `number` | `600` | `/multipart/part` 限流 |
+| `rateLimit.partPerMin` | `number` | `600` | `/multipart/part` 限流(**v1.0.5+ 按 `uploadId` 维度**,每个文件独立 600/min 配额,不再按 sessionKey 共享;详见 Changelog) |
 | `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 路由挂载前缀 |
@@ -452,6 +567,7 @@ if (body.files.length > rt.config.smartMaxFiles) {
 | `orphanScan.intervalSeconds` | `number` | `300` | 扫描间隔(秒) |
 | `orphanScan.lookbackDays` | `number` | `7` | 回溯天数 |
 | `orphanScan.batchSize` | `number` | `2000` | 单次扫描条数 |
+| `onComplete` | `OnCompleteHook` | `undefined` | **v1.0.6+** complete 后业务钩子(详见下文"onComplete 业务钩子"章节) |
 
 ---
 
@@ -473,6 +589,7 @@ pnpm test:e2e            # SDK 独立启动 e2e(server-only,不依赖 MySQL/Redi
 | `memory-repo.test.ts` | `InMemoryMultipartRepository` / `InMemoryFileRepository` |
 | `plugin.test.ts` | 端到端 init / part / complete / abort / status / smart |
 | `dedup.test.ts` | 秒传命中 + 隔离(可见性 / userId 不同时不命中) |
+| `hook.test.ts` | **v1.0.6+** `onComplete` 钩子:调用顺序 / patch 应用 / 失败隔离 / idempotent 跳过 / `getOriginalBuffer` 内容正确 / 无钩子向后兼容 |
 | `e2e-with-prefix.mjs` / `standalone-e2e.*` | 启动完整 Fastify 实例,跑通 5 个集成流程 |
 
 ---
@@ -561,6 +678,69 @@ HTTP 状态码映射由 `getHttpStatus(code)` 给出,用户业务侧可直接用
 
 ## 📝 Changelog
 
+### v1.0.6 — `onComplete` 业务钩子(自动水印/转码/敏感扫描通用入口)
+
+**🎉 Feature**
+
+- **`SecureUploadOptions.onComplete?: OnCompleteHook`**  
+  在 multipart/smart complete 完成(file record 已落库)、响应返回前**调用一次**,给你一个机会"加工"这个文件:
+  - **读**原 buffer:`ctx.getOriginalBuffer()`(走 `storage.get`)
+  - **改**file record:返回 `OnCompletePatch` → SDK 调 `fileRepo.update(id, patch)`  
+  - **失败隔离**:钩子抛错 → SDK catch → log.warn → complete 仍返回 200(file record 不变)  
+  - **幂等跳过**:同一 uploadId 第二次 complete(命中 idempotent)→ 不调钩子  
+
+- **典型用例:upload-service 的自动水印**  
+  ```ts
+  onComplete: autoWatermarkOnComplete  // 后端代码 src/watermark/auto.ts
+  ```
+  私有 PNG/JPEG/WebP 走分片上传 → complete 时自动:
+  1. 读明文 → `processWatermark` (LSB 数字 + 可见)
+  2. put 新文件 → 返回 `storageKey/size/contentType/watermarked/isOriginal/retentionExpiresAt/meta` patch
+  3. 前端拿到的 complete url 直接是水印后文件,**无二次请求**
+
+- **新增类型导出**:`OnCompleteHook` / `OnCompleteContext` / `OnCompletePatch`
+
+**🧪 Tests**
+
+- `tests/hook.test.ts`(7 用例):钩子调用顺序 / patch 应用 / 失败隔离 / idempotent 跳过 / `getOriginalBuffer` 内容 / 无钩子向后兼容
+
+**⚙️ 升级**
+
+```bash
+cd secure-upload-fastify-sdk && pnpm build
+cd ../backend && pnpm install
+```
+
+完全向后兼容(不传 `onComplete` 时行为不变)。
+
+### v1.0.5 — `/multipart/part` 限流维度从 sessionKey 改为 uploadId
+
+**🛠 Fix**
+
+- **`/multipart/part` 限流 key 改为按 `uploadId` 维度**  
+  之前 key 是 `rl:mp:part:${sessionKey.slice(0, 64)}`(**单用户共享 600 part/min 配额**),单用户并发 N 个文件会互相挤兑。  
+  实测 60 个文件 × 16 part = 960 part,60s 内必爆,第 42 号文件全部 part 报 `1402 part 上传过于频繁`。  
+  改为 `rl:mp:part:${uploadId}` 后,**每个文件独立 600 part/min**,多文件并发互不影响。
+
+**⚙️ 影响面**
+
+| 组件 | 行为 | 是否需要改动 |
+|------|------|-------------|
+| 单文件上传 | 行为不变(单文件本身就是 1 个 uploadId) | ❌ |
+| 单用户并发多文件 | 60+ 文件不再互相挤兑配额 | ❌(自动生效) |
+| 旧 key `rl:mp:part:{sessionKey}` | 立即失效,等 60s 滑动窗口自然过期 | 无需手动清理 |
+| `rateLimit.partPerMin` 默认值 | 不变(600) | ❌ |
+
+**🔄 升级步骤**
+
+```bash
+cd secure-upload-fastify-sdk && pnpm build      # 重建 dist
+cd ../backend && pnpm install                   # workspace 重链接
+pnpm dev                                        # 重启 upload-service
+```
+
+---
+
 ### v1.0.2 — /smart/init 批量上限可配置化
 
 **🛠 Fix / Feature**

package/dist/index.js

@@ -345,7 +345,12 @@ function toFileRecord(row) {
     meta: row.meta && typeof row.meta === "object" ? row.meta : null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
-    deletedAt: row.deletedAt
+    deletedAt: row.deletedAt,
+    // v1.5.1+:水印溯源字段(可选;旧 schema/老库里 row 可能没有,需要兜底)
+    watermarked: row.watermarked ?? false,
+    isOriginal: row.isOriginal ?? true,
+    parentId: row.parentId ?? null,
+    retentionExpiresAt: row.retentionExpiresAt ?? null
   };
 }
 var PrismaMultipartRepository = class {
@@ -511,6 +516,27 @@ var PrismaFileRepository = class {
     });
     return toFileRecord(row);
   }
+  /**
+   * v1.5.1: 钩子 onComplete 返回 patch 后 SDK 调这个方法
+   *   - 只更新传入的字段;其他字段保留原值
+   *   - 文件不存在 → 抛错(由调用方决定是否捕获)
+   *   - 业务字段 watermarked/isOriginal/parentId/retentionExpiresAt 需要 schema v1.4.0+
+   */
+  async update(id, patch) {
+    const data = {};
+    if (patch.storageKey !== void 0) data.storageKey = patch.storageKey;
+    if (patch.size !== void 0) data.size = BigInt(patch.size);
+    if (patch.contentType !== void 0) data.contentType = patch.contentType;
+    if (patch.meta !== void 0) data.meta = patch.meta;
+    if (patch.watermarked !== void 0) data.watermarked = patch.watermarked;
+    if (patch.isOriginal !== void 0) data.isOriginal = patch.isOriginal;
+    if (patch.parentId !== void 0) data.parentId = patch.parentId;
+    if (patch.retentionExpiresAt !== void 0) {
+      data.retentionExpiresAt = patch.retentionExpiresAt;
+    }
+    const row = await this.prisma.file.update({ where: { id }, data });
+    return toFileRecord(row);
+  }
   async softDelete(id, metaPatch) {
     if (metaPatch) {
       const cur = await this.prisma.file.findUnique({ where: { id } });
@@ -737,6 +763,30 @@ var InMemoryFileRepository = class {
     };
     this.store.set(id, next);
   }
+  /**
+   * v1.5.1: 钩子 onComplete 返回 patch 后 SDK 调这个方法
+   *   - 只更新传入的字段;其他字段保留原值
+   *   - 文件不存在 → 抛错(由调用方决定是否捕获)
+   */
+  async update(id, patch) {
+    const rec = this.store.get(id);
+    if (!rec) throw new Error("NOT_FOUND");
+    const now = /* @__PURE__ */ new Date();
+    const next = {
+      ...rec,
+      storageKey: patch.storageKey ?? rec.storageKey,
+      size: patch.size !== void 0 ? BigInt(patch.size) : rec.size,
+      contentType: patch.contentType ?? rec.contentType,
+      meta: patch.meta === void 0 ? rec.meta : patch.meta,
+      watermarked: patch.watermarked ?? rec.watermarked,
+      isOriginal: patch.isOriginal ?? rec.isOriginal,
+      parentId: patch.parentId === void 0 ? rec.parentId : patch.parentId,
+      retentionExpiresAt: patch.retentionExpiresAt === void 0 ? rec.retentionExpiresAt : patch.retentionExpiresAt,
+      updatedAt: now
+    };
+    this.store.set(id, next);
+    return next;
+  }
   async listOrphans(opts) {
     const sinceMs = opts.sinceDays * 24 * 3600 * 1e3;
     const list = [];
@@ -1184,6 +1234,47 @@ async function lock(rt, key, ttlMs, fn, retries = 0) {
   }
   return await memoryWithLock(key, fn, retries);
 }
+async function streamToBuffer(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+}
+async function runOnComplete(rt, file, log) {
+  if (!rt.onComplete) return file;
+  try {
+    const patch = await rt.onComplete({
+      file,
+      storage: rt.storage,
+      log,
+      getOriginalBuffer: async () => {
+        const stream = await Promise.resolve(rt.storage.get(file.storageKey));
+        return streamToBuffer(stream);
+      }
+    });
+    if (!patch || Object.keys(patch).length === 0) {
+      return file;
+    }
+    const updated = await rt.fileRepo.update(file.id, patch);
+    log.info(
+      {
+        fileId: file.id,
+        patchKeys: Object.keys(patch),
+        newStorageKey: patch.storageKey,
+        watermarked: patch.watermarked
+      },
+      "\u2705 onComplete \u94A9\u5B50\u5DF2\u5E94\u7528 patch"
+    );
+    return updated;
+  } catch (err) {
+    log.warn(
+      { err, fileId: file.id, uploadId: file.uploadId },
+      "\u26A0\uFE0F onComplete \u94A9\u5B50\u6267\u884C\u5931\u8D25,\u5DF2\u8DF3\u8FC7\u4E1A\u52A1\u540E\u5904\u7406(file record \u4FDD\u6301\u539F\u72B6)"
+    );
+    return file;
+  }
+}
 async function registerMultipartRoutes(app, rt) {
   if (!rt.config.enabled) {
     app.log.warn("\u26A0\uFE0F  multipart \u4E0A\u4F20\u5DF2\u7981\u7528 (enabled=false)");
@@ -1489,8 +1580,14 @@ async function registerMultipartRoutes(app, rt) {
           contentHash: finalHash,
           meta: rec.meta ?? void 0
         });
+        const finalFile = await runOnComplete(rt, file2, req.log);
         await rt.multipartRepo.markCompleted(rec.id, fileId);
-        return { idempotent: false, fileId: file2.id, size: merged.size, finalHash };
+        return {
+          idempotent: false,
+          fileId: finalFile.id,
+          size: Number(finalFile.size),
+          finalHash
+        };
       }
     );
     if (!result.idempotent) {
@@ -1503,7 +1600,8 @@ async function registerMultipartRoutes(app, rt) {
         uploadId: body.uploadId,
         fileId: result.fileId,
         size: result.size,
-        userId: rec.userId
+        userId: rec.userId,
+        watermarkHook: rt.onComplete ? "on" : "off"
       },
       "\u2705 multipart: complete"
     );
@@ -1979,7 +2077,8 @@ async function secureUploadPluginImpl(app, options) {
         ...options.strategy ?? {}
       }
     },
-    validateSession: options.sessionValidator ?? defaultSessionValidator
+    validateSession: options.sessionValidator ?? defaultSessionValidator,
+    onComplete: options.onComplete ?? null
   };
   app.decorate("secureUpload", runtime);
   await registerMultipartRoutes(app, runtime);