secure-upload-fastify-sdk 1.0.0

package/README.md

@@ -0,0 +1,467 @@
+# secure-upload-fastify-sdk
+
+> 面向 Fastify 的可插拔上传 SDK：分片上传 / 秒传 / 断点续传 / 智能分流一站式解决方案。  
+> 存储可插拔（Local / S3 / OSS / COS），数据层可插拔（Prisma 或自实现），可选桥接 `secure-crypto-top-zod-sdk`。
+
+---
+
+## ✨ 特性
+
+- **5 + 1 端点**，覆盖所有上传场景
+  - `POST /multipart/{init, part, complete, abort, status}` — 通用分片上传
+  - `POST /smart/init` — 智能批量 init（自动按 `totalSize` 选 `ONE_SHOT` / `MULTIPART`）
+- **存储可插拔** — 实现一次 `StorageAdapter` 接口，就能在 Local / S3 / OSS / COS 之间切换
+- **数据层可插拔** — 内置 Prisma 实现，也支持 Drizzle / TypeORM / Mongo / 内存自实现
+- **可选 Redis** — 分布式限流 + 分布式锁；不传则自动降级为内存版（单进程）
+- **可选 Secure-Crypto 桥接** — 与 `secure-crypto-top-zod-sdk` 配对，从 `req.secureRequest` 读数据；纯 HTTP 场景用 `raw` 模式
+- **可自定义 Session 校验** — 默认 base64-decode JWT payload，可注入 `jwt.verify()` 完整验签
+- **后台任务** — 过期 `uploadId` 清理 + 孤儿文件扫描，全部可关闭
+- **严格秒传隔离（v1.0.0+）** — 按 `(contentHash, isPublic, userId)` 三元组匹配，公开池/私有池/不同用户之间完全隔离
+
+---
+
+## 📦 安装
+
+```bash
+pnpm add secure-upload-fastify-sdk
+# 必装 peer
+pnpm add fastify fastify-plugin zod
+# 按需装
+pnpm add @prisma/client   # 用 Prisma 数据层时
+pnpm add ioredis          # 用分布式限流 / 锁时
+# 可选:与加密 SDK 桥接
+pnpm add secure-crypto-top-zod-sdk
+```
+
+> `secure-crypto-top-zod-sdk` / `@prisma/client` / `ioredis` 在 `peerDependenciesMeta.optional` 中标记为可选，SDK 在不安装这些包时仍可独立运行（用 `raw` 模式 + 内存版限流）。
+
+---
+
+## 🚀 快速开始
+
+### 1. 接入 Prisma Schema（仅当用 Prisma 数据层时）
+
+把 [`prisma/schema.prisma`](./prisma/schema.prisma) 中的两张表（`File` / `MultipartUpload`）以及两个枚举（`FileStatus` / `MultipartStatus`）复制到你自己项目的 `prisma/schema.prisma`，然后：
+
+```bash
+npx prisma db push
+npx prisma generate
+```
+
+> 如果你的项目里已经有 `File` / `MultipartUpload`，按 SDK 的字段对一下即可，不需要新建表。
+
+### 2. 注册插件
+
+```ts
+import Fastify from 'fastify';
+import { PrismaClient } from '@prisma/client';
+import Redis from 'ioredis';
+import secureUploadPlugin, {
+  type SecureUploadOptions,
+} from 'secure-upload-fastify-sdk/server';
+
+const app = Fastify({ logger: true });
+const prisma = new PrismaClient();
+const redis = new Redis(process.env.REDIS_URL!);
+
+await app.register(secureUploadPlugin, {
+  // 1. 存储:本地磁盘(默认)
+  storage: { adapter: 'local', options: { baseDir: '/var/upload' } },
+
+  // 2. 数据层:Prisma(也可传 'custom' 注入自己的实现)
+  repository: { kind: 'prisma', prisma },
+
+  // 3. Redis(可选,不传则用内存版限流 + 锁)
+  redis,
+
+  // 4. 路径前缀(默认 '/multipart' '/smart',挂到 /api/v1/upload 时设这个)
+  pathPrefix: {
+    multipart: '/api/v1/upload/multipart',
+    smart: '/api/v1/upload/smart',
+  },
+  // complete 响应里的 url 字段前缀
+  fileUrlPrefix: '/api/v1/upload/files',
+
+  // 5. 可选:与 secure-crypto-top-zod-sdk 桥接
+  secure: { mode: 'secure-crypto' },
+
+  // 6. 可选:策略、限流、TTL(都有默认值,按需覆盖)
+  // strategy: { oneShotMax: 1024 * 1024, defaultPartSize: 1024 * 1024, ... },
+  // rateLimit: { initPerMin: 30, partPerMin: 600 },
+  // ttlSeconds: 24 * 60 * 60,
+} satisfies SecureUploadOptions);
+
+await app.listen({ port: 8083 });
+```
+
+### 3. 验证
+
+```bash
+# 1) init 一笔分片上传
+curl -X POST http://localhost:8083/api/v1/upload/multipart/init \
+  -H 'Content-Type: application/json' \
+  -d '{"filename":"a.txt","totalSize":1024,"isPublic":true}'
+# → { "success": true, "data": { "uploadId": "mp_...", "partSize": 20971520, "totalParts": 1, ... } }
+
+# 2) 或者用智能 init(一次批量,服务端自动分流 ONE_SHOT / MULTIPART)
+curl -X POST http://localhost:8083/api/v1/upload/smart/init \
+  -H 'Content-Type: application/json' \
+  -H 'x-secure-session: <jwt>' \
+  -d '{"files":[{"filename":"a.txt","size":1024,"isPublic":false}]}'
+```
+
+---
+
+## 🔌 扩展示例
+
+### A. S3 / 阿里云 OSS / 腾讯云 COS
+
+实现 `StorageAdapter`：
+
+```ts
+// my-storage.ts
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import type { StorageAdapter } from 'secure-upload-fastify-sdk/storage';
+
+export class S3Storage implements StorageAdapter {
+  constructor(
+    private client: S3Client,
+    private bucket: string,
+    private prefix = 'uploads/',
+  ) {}
+
+  async put(data, meta) { /* ... */ }
+  get(key) { /* ... */ }
+  async delete(key) { /* ... */ }
+  async exists(key) { /* ... */ }
+  async putPart(uploadId, partNumber, data) { /* ... */ }
+  async listParts(uploadId) { /* ... */ }
+  async mergeParts(uploadId, totalParts, target) { /* ... */ }
+  async computeMergedHash(uploadId, totalParts) { /* ... */ }
+  async cleanupMultipart(uploadId) { /* ... */ }
+}
+```
+
+然后直接传实例：
+
+```ts
+import { S3Storage } from './my-storage';
+await app.register(secureUploadPlugin, {
+  storage: new S3Storage(new S3Client({ region: 'us-east-1' }), 'my-bucket'),
+  // ... 其他 options
+});
+```
+
+> SDK 识别 `StorageAdapter` 实例的方式是 duck-typing:只要对象实现了 `put/get/delete/...` 全部方法,就视为自定义存储,不再走 `adapter: 'local'` 分支。
+
+### B. Drizzle / TypeORM / MongoDB（不用 Prisma）
+
+```ts
+import type { MultipartRepository, FileRepository } from 'secure-upload-fastify-sdk/repository';
+
+class DrizzleMultipartRepo implements MultipartRepository { /* ... */ }
+class DrizzleFileRepo implements FileRepository { /* ... */ }
+
+await app.register(secureUploadPlugin, {
+  storage: { adapter: 'local', options: { baseDir: '/var/upload' } },
+  repository: {
+    kind: 'custom',
+    multipart: new DrizzleMultipartRepo(db),
+    file: new DrizzleFileRepo(db),
+  },
+  redis,
+});
+```
+
+### C. 内存版（测试 / POC）
+
+```ts
+import {
+  InMemoryStorage,
+  InMemoryMultipartRepository,
+  InMemoryFileRepository,
+} from 'secure-upload-fastify-sdk';
+
+await app.register(secureUploadPlugin, {
+  storage: new InMemoryStorage(),
+  repository: {
+    kind: 'custom',
+    multipart: new InMemoryMultipartRepository(),
+    file: new InMemoryFileRepository(),
+  },
+  // 不传 redis → 自动用内存版限流 + 锁
+});
+```
+
+### D. 自定义 Session 校验（完整 JWT 验签）
+
+```ts
+import jwt from 'jsonwebtoken';
+
+await app.register(secureUploadPlugin, {
+  // ... storage & repository
+  sessionValidator: (token, isPublic) => {
+    if (isPublic) return null;
+    if (!token) throw new Error('session required');
+    try {
+      const payload = jwt.verify(token, process.env.JWT_SECRET!) as { sub: number };
+      return payload.sub;
+    } catch {
+      throw new Error('invalid session');
+    }
+  },
+});
+```
+
+> 默认 `sessionValidator` 只 base64-decode JWT payload 并校验 `exp` + 读 `sub`,不做 HMAC 验签(SDK 不持有 `appSecret`)。
+> 完整安全链路:gateway 已做 JWT 验签,业务服务信任透传的 session;若业务服务要自己验签,通过 `options.sessionValidator` 注入即可。
+> 校验失败应抛 `SecureError(ErrorCode.BINARY_AUTH_REQUIRED / BINARY_AUTH_FAILED)`,SDK 会自动转成 401 响应。
+
+---
+
+## 🔐 Secure-Crypto 模式
+
+默认情况下,SDK 从 `req.body` 和 `req.headers['x-secure-raw-base64']` 读数据(`raw` 模式)。  
+如果项目里装了 [`secure-crypto-top-zod-sdk`](https://www.npmjs.com/package/secure-crypto-top-zod-sdk) 并在上传插件**之前**注册,切到 `secure-crypto` 模式:
+
+```ts
+import secureCryptoPlugin from 'secure-crypto-top-zod-sdk/server';
+import secureUploadPlugin from 'secure-upload-fastify-sdk/server';
+
+await app.register(secureCryptoPlugin, {
+  apps: [{ appKey: 'demo', appSecret: 'xxx', allowedCiphers: ['aes-256-gcm'], allowedDigests: ['hmac-sha256'] }],
+  encryptionKeys: { demo: process.env.ENCRYPTION_KEY! },
+});
+
+await app.register(secureUploadPlugin, {
+  // ... storage & repository
+  secure: { mode: 'secure-crypto' },
+});
+```
+
+在该模式下,SDK 读:
+
+- `req.secureRequest.biz` — JSON 业务字段
+- `req.secureRequest.raw.data` — binary part 负载
+
+> SDK **不**在运行时 import 加密 SDK,只对 `req.secureRequest` 做 duck-typing。  
+> 该依赖在 `peerDependenciesMeta.optional` 标记为可选,完全 opt-in。
+
+---
+
+## 📐 架构
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Fastify App                                                 │
+│  ├─ secure-crypto-top-zod-sdk  (optional, before upload)    │
+│  └─ secure-upload-fastify-sdk  ← this SDK                   │
+│      │                                                      │
+│      ├─ Routes ─┬─ POST /multipart/init                     │
+│      │          ├─ POST /multipart/part    (binary)         │
+│      │          ├─ POST /multipart/complete                 │
+│      │          ├─ POST /multipart/abort                    │
+│      │          ├─ POST /multipart/status                   │
+│      │          └─ POST /smart/init                         │
+│      │                                                      │
+│      ├─ Strategy  (chooseStrategy: ONE_SHOT / MULTIPART)    │
+│      ├─ Storage   (StorageAdapter interface)                │
+│      │    ├─ LocalStorage (built-in)                        │
+│      │    └─ your S3Storage / OSSStorage / COSStorage       │
+│      │                                                      │
+│      ├─ Repository (MultipartRepo + FileRepo interface)    │
+│      │    ├─ PrismaMultipartRepo + PrismaFileRepo (built-in)│
+│      │    └─ your Drizzle / TypeORM / Mongo                 │
+│      │                                                      │
+│      ├─ RateLimit & Lock                                    │
+│      │    ├─ ioredis (if redis: provided)                   │
+│      │    └─ in-memory fallback (single-process)            │
+│      │                                                      │
+│      └─ Background tasks (setInterval)                      │
+│           ├─ multipart cleanup (expire INIT/UPLOADING)      │
+│           └─ orphan file scan (DB has / disk missing)       │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🧠 Smart 智能分流策略
+
+`/smart/init` 服务端按 `totalSize` 选 `ONE_SHOT` / `MULTIPART`,动态放大 partSize 减少 part 数:
+
+| 文件大小 | 策略 | partSize | 客户端 RTT |
+|---------|------|----------|-----------|
+| 0 字节 | `ONE_SHOT` | 0 | 2 (part+complete) |
+| ≤ 1MB (`oneShotMax`) | `ONE_SHOT` | = 文件大小 | 2 |
+| 1MB ~ 1GB | `MULTIPART` | 1MB | N+1 |
+| 1GB ~ 10GB | `MULTIPART` | 5MB | N+1 |
+| > 10GB | `MULTIPART` | 10MB | N+1 |
+
+> 5GB 用 1MB/part → 5120 part,DB / Redis / 客户端并发调度压力大;  
+> 5GB 用 5MB/part → 1024 part,网络利用率高、开销可接受。
+
+并发建议 (`suggestConcurrency`):
+
+- `ONE_SHOT` → 1
+- `totalParts ≤ 4` → `totalParts`
+- 其他 → 4
+
+---
+
+## ⚡ 秒传隔离
+
+`/multipart/init` 和 `/smart/init` 都支持秒传:传 `expectedHash` 时,服务端按 `(contentHash, isPublic, userId)` 三元组查询已有 `File` 记录。
+
+| 维度 | 公开上传 | 私有上传 |
+|------|----------|----------|
+| `contentHash` | 必须相同 | 必须相同 |
+| `isPublic` | 必须 `true` | 必须 `false` |
+| `userId` | 不参与 | 必须与上传者一致 |
+| `deletedAt` | 排除 | 排除 |
+
+> **为什么三元组而不是单 `contentHash`?**  
+> 只用 `contentHash` 会导致公开/私密串号,两个不同用户的私密文件也会互相命中。  
+> 公开池共享一份、私密池每人一份,完全隔离。
+
+---
+
+## 🔧 选项参考
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `storage` | `{ adapter: 'local', options: { baseDir } } \| StorageAdapter` | — (必填) | 存储后端 |
+| `repository` | `{ kind: 'prisma', prisma } \| { kind: 'custom', multipart, file }` | — (必填) | 数据层 |
+| `redis` | `Redis` (ioredis) | `undefined` | 不传则用内存版限流 + 锁 |
+| `secure.mode` | `'raw' \| 'secure-crypto'` | `'raw'` | `req.body` 或 `req.secureRequest` |
+| `enabled` | `boolean` | `true` | 上传路由总开关 |
+| `fileMaxSize` | `number` (字节) | `5 GB` | 单文件大小上限 |
+| `partSize.min` | `number` (字节) | `5 MB` | 最小分片 |
+| `partSize.max` | `number` (字节) | `50 MB` | 最大分片 |
+| `partSize.default` | `number` (字节) | `20 MB` | 默认分片(客户端不传时) |
+| `ttlSeconds` | `number` | `86400` (24h) | `uploadId` 有效期 |
+| `suggestedClientConcurrency` | `number` | `3` | 建议客户端并发 part 数 |
+| `rateLimit.initPerMin` | `number` | `30` | `/multipart/init` 限流 |
+| `rateLimit.partPerMin` | `number` | `600` | `/multipart/part` 限流 |
+| `rateLimit.smartMaxFilesPerInit` | `number` | `50` | `/smart/init` 单次最多文件数 |
+| `pathPrefix.multipart` | `string` | `'/multipart'` | 分片路由挂载前缀 |
+| `pathPrefix.smart` | `string` | `'/smart'` | smart 路由挂载前缀 |
+| `fileUrlPrefix` | `string` | `'/files'` | complete 响应 `url` 字段前缀 |
+| `sessionValidator` | `(token, isPublic) => userId \| null` | base64-decode JWT | 自定义 session 校验 |
+| `strategy` | `Partial<StrategyConfig>` | `DEFAULT_STRATEGY_CONFIG` | smart 策略调优 |
+| `cleanupTask.enabled` | `boolean` | `true` | 过期 `uploadId` 清理 |
+| `cleanupTask.intervalSeconds` | `number` | `300` | 清理间隔(秒) |
+| `cleanupTask.batchLimit` | `number` | `100` | 单次扫描条数 |
+| `orphanScan.enabled` | `boolean` | `true` | 孤儿文件扫描 |
+| `orphanScan.intervalSeconds` | `number` | `300` | 扫描间隔(秒) |
+| `orphanScan.lookbackDays` | `number` | `7` | 回溯天数 |
+| `orphanScan.batchSize` | `number` | `2000` | 单次扫描条数 |
+
+---
+
+## 🧪 测试
+
+```bash
+pnpm test                # 跑全部 node:test 用例
+pnpm test:strategy       # 只跑 strategy.test.ts
+pnpm test:e2e            # SDK 独立启动 e2e(server-only,不依赖 MySQL/Redis)
+```
+
+测试套件覆盖:
+
+| 用例 | 覆盖点 |
+|------|-------|
+| `strategy.test.ts` | `chooseStrategy` / `suggestConcurrency` 纯函数分支 |
+| `local-storage.test.ts` | `LocalStorage` put / part / merge / hash / cleanup |
+| `memory-rate-limit.test.ts` | 内存版限流 + 锁 |
+| `memory-repo.test.ts` | `InMemoryMultipartRepository` / `InMemoryFileRepository` |
+| `plugin.test.ts` | 端到端 init / part / complete / abort / status / smart |
+| `dedup.test.ts` | 秒传命中 + 隔离(可见性 / userId 不同时不命中) |
+| `e2e-with-prefix.mjs` / `standalone-e2e.*` | 启动完整 Fastify 实例,跑通 5 个集成流程 |
+
+---
+
+## 🧰 Prisma Schema 速览
+
+完整定义见 [`prisma/schema.prisma`](./prisma/schema.prisma),核心两张表:
+
+```prisma
+enum FileStatus       { PENDING UPLOADING COMPLETED FAILED }
+enum MultipartStatus  { INIT UPLOADING COMPLETED ABORTED EXPIRED FAILED }
+
+model File {
+  id           String   @id
+  userId       Int?
+  filename     String   @db.VarChar(255)
+  contentType  String   @db.VarChar(128)
+  size         BigInt
+  storageKey   String   @unique @db.VarChar(191)
+  isPublic     Boolean  @default(false)
+  status       FileStatus @default(COMPLETED)
+  uploadId     String?  @db.VarChar(128) @unique
+  totalParts   Int?
+  contentHash  String?  @db.VarChar(64)        // SHA-256 hex,用于秒传
+  meta         Json?
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+  deletedAt    DateTime?
+  @@index([userId, createdAt])
+  @@index([isPublic, createdAt])
+  @@index([status])
+  @@index([contentHash])
+  @@map("files")
+}
+
+model MultipartUpload {
+  id            String   @id
+  userId        Int?
+  filename      String   @db.VarChar(255)
+  contentType   String   @db.VarChar(128)
+  totalSize     BigInt
+  partSize      Int
+  totalParts    Int
+  isPublic      Boolean  @default(false)
+  status        MultipartStatus @default(INIT)
+  receivedParts Json     @default("[]")      // number[]
+  partHashes    Json     @default("{}")      // { [partNumber]: sha256 }
+  meta          Json?
+  expectedHash  String?  @db.VarChar(64)
+  fileId        String?  @db.VarChar(128)    @unique
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+  expiresAt     DateTime
+  completedAt   DateTime?
+  abortedAt     DateTime?
+  @@index([userId, createdAt])
+  @@index([status])
+  @@index([status, expiresAt])
+  @@map("multipart_uploads")
+}
+```
+
+---
+
+## 🚨 错误码
+
+定义在 `errors.ts`,SDK 内部统一返回 `{ success: false, code, error, message }` 格式:
+
+| 范围 | 类别 | 示例 |
+|------|------|------|
+| `1001` | 通用 | `INVALID_REQUEST` |
+| `1400-1499` | HTTP 语义 | `NOT_FOUND` / `FORBIDDEN` / `RATE_LIMITED` |
+| `1500-1599` | 上传相关 | `BINARY_AUTH_REQUIRED` / `MULTIPART_*` / `BATCH_*` |
+
+完整列表见 [`src/server/errors.ts`](./src/server/errors.ts)。  
+HTTP 状态码映射由 `getHttpStatus(code)` 给出,用户业务侧可直接用 `ErrorCode` 枚举做分支判断。
+
+---
+
+## 📚 相关项目
+
+- [`secure-crypto-top-zod-sdk`](../secure-crypto-top-zod-sdk) — 加密/解密协议,`req.secureRequest` 装饰器
+- `backend/apps/upload-service` — SDK 在本仓库的集成实例(v2-SDK,见 `backend/README.md`)
+
+---
+
+## 📄 License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 顶层入口
+ *
+ * 直接 re-export server/index.ts 的全部内容,
+ * 用户可以从 'secure-upload-fastify-sdk' 单点 import:
+ *
+ *   import secureUploadPlugin, { LocalStorage, ErrorCode, SecureError } from 'secure-upload-fastify-sdk';
+ *
+ * 也可以从子路径精确 import:
+ *   import { LocalStorage } from 'secure-upload-fastify-sdk/storage';
+ *   import { ErrorCode } from 'secure-upload-fastify-sdk/errors';
+ */
+export * from './server/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,gBAAgB,CAAC"}