secure-upload-fastify-sdk 1.0.0

package/dist/server/utils/storage/index.mjs

@@ -0,0 +1,247 @@
+// src/server/utils/storage/local.ts
+import { promises as fs, createReadStream, createWriteStream } from "fs";
+import path from "path";
+import { createHash } from "crypto";
+var LocalStorage = class {
+  baseDir;
+  constructor(opts) {
+    this.baseDir = typeof opts === "string" ? opts : opts.baseDir;
+  }
+  // ============================================================
+  // 内部工具
+  // ============================================================
+  inferExt(filename, contentType) {
+    const fromName = path.extname(filename).toLowerCase();
+    if (fromName) return fromName;
+    const map = {
+      "image/png": ".png",
+      "image/jpeg": ".jpg",
+      "image/gif": ".gif",
+      "image/webp": ".webp",
+      "image/svg+xml": ".svg",
+      "application/pdf": ".pdf",
+      "text/plain": ".txt",
+      "application/json": ".json",
+      "application/zip": ".zip",
+      "video/mp4": ".mp4"
+    };
+    return map[contentType] ?? ".bin";
+  }
+  generateKey(filename, contentType, id) {
+    const now = /* @__PURE__ */ new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    const ext = this.inferExt(filename, contentType);
+    return `${yyyy}/${mm}/${dd}/${id}${ext}`;
+  }
+  multipartDir(uploadId) {
+    return path.resolve(this.baseDir, "_multipart", uploadId);
+  }
+  partPath(uploadId, partNumber) {
+    if (!Number.isInteger(partNumber) || partNumber < 1) {
+      throw new Error(`[storage] partNumber \u975E\u6CD5: ${partNumber}`);
+    }
+    return path.join(this.multipartDir(uploadId), `part_${String(partNumber).padStart(4, "0")}.bin`);
+  }
+  // ============================================================
+  // StorageAdapter 实现
+  // ============================================================
+  async put(data, meta) {
+    const key = this.generateKey(meta.filename, meta.contentType, meta.id);
+    const absolutePath = path.resolve(this.baseDir, key);
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    await fs.writeFile(absolutePath, data);
+    return { key, absolutePath };
+  }
+  get(key) {
+    const absolutePath = path.resolve(this.baseDir, key);
+    return createReadStream(absolutePath);
+  }
+  async delete(key) {
+    const absolutePath = path.resolve(this.baseDir, key);
+    try {
+      await fs.unlink(absolutePath);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+  async exists(key) {
+    const absolutePath = path.resolve(this.baseDir, key);
+    try {
+      await fs.access(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async putPart(uploadId, partNumber, data) {
+    const dir = this.multipartDir(uploadId);
+    await fs.mkdir(dir, { recursive: true });
+    const finalPath = this.partPath(uploadId, partNumber);
+    const tmpPath = `${finalPath}.tmp`;
+    try {
+      await fs.writeFile(tmpPath, data);
+      await fs.rename(tmpPath, finalPath);
+    } catch (e) {
+      try {
+        await fs.unlink(tmpPath);
+      } catch {
+      }
+      throw e;
+    }
+    return { size: data.length, path: finalPath };
+  }
+  async listParts(uploadId) {
+    const dir = this.multipartDir(uploadId);
+    try {
+      const names = await fs.readdir(dir);
+      const nums = [];
+      for (const n of names) {
+        const m = n.match(/^part_(\d{4,})\.bin$/);
+        if (m) nums.push(parseInt(m[1], 10));
+      }
+      nums.sort((a, b) => a - b);
+      return nums;
+    } catch (e) {
+      if (e.code === "ENOENT") return [];
+      throw e;
+    }
+  }
+  async partSize(uploadId, partNumber) {
+    const p = this.partPath(uploadId, partNumber);
+    const stat = await fs.stat(p);
+    return stat.size;
+  }
+  async mergeParts(uploadId, totalParts, target) {
+    const key = this.generateKey(target.filename, target.contentType, target.id);
+    const absolutePath = path.resolve(this.baseDir, key);
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    const tmpPath = `${absolutePath}.merge.tmp`;
+    const out = createWriteStream(tmpPath);
+    try {
+      for (let i = 1; i <= totalParts; i++) {
+        const partPath = this.partPath(uploadId, i);
+        try {
+          await fs.access(partPath);
+        } catch {
+          throw new Error(`[storage] \u7F3A\u5206\u7247 part_${i} (uploadId=${uploadId})`);
+        }
+        await new Promise((resolve, reject) => {
+          const rs = createReadStream(partPath);
+          rs.on("error", reject);
+          rs.on("end", resolve);
+          rs.pipe(out, { end: false });
+        });
+      }
+      out.end();
+      await new Promise((resolve, reject) => {
+        out.on("finish", () => resolve());
+        out.on("error", reject);
+      });
+      const stat = await fs.stat(tmpPath);
+      await fs.rename(tmpPath, absolutePath);
+      return { key, absolutePath, size: stat.size };
+    } catch (e) {
+      try {
+        await fs.unlink(tmpPath);
+      } catch {
+      }
+      throw e;
+    }
+  }
+  async cleanupMultipart(uploadId) {
+    const dir = this.multipartDir(uploadId);
+    try {
+      await fs.rm(dir, { recursive: true, force: true });
+    } catch (e) {
+      if (e.code !== "ENOENT") {
+        console.warn(`[storage] cleanup multipart failed: uploadId=${uploadId} err=${e.message}`);
+      }
+    }
+  }
+  async computeMergedHash(uploadId, totalParts) {
+    const hash = createHash("sha256");
+    for (let i = 1; i <= totalParts; i++) {
+      const partPath = this.partPath(uploadId, i);
+      const stream = createReadStream(partPath);
+      await new Promise((resolve, reject) => {
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", resolve);
+        stream.on("error", reject);
+      });
+    }
+    return hash.digest("hex");
+  }
+};
+
+// src/server/utils/storage/memory.ts
+import { Readable } from "stream";
+import { createHash as createHash2 } from "crypto";
+var InMemoryStorage = class {
+  files = /* @__PURE__ */ new Map();
+  parts = /* @__PURE__ */ new Map();
+  async put(data, meta) {
+    const key = `mem/${meta.id}`;
+    this.files.set(key, Buffer.from(data));
+    return { key };
+  }
+  get(key) {
+    const buf = this.files.get(key);
+    if (!buf) throw new Error(`[memory-storage] not found: ${key}`);
+    return Readable.from(buf);
+  }
+  async delete(key) {
+    this.files.delete(key);
+  }
+  async exists(key) {
+    return this.files.has(key);
+  }
+  async putPart(uploadId, partNumber, data) {
+    let m = this.parts.get(uploadId);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      this.parts.set(uploadId, m);
+    }
+    m.set(partNumber, Buffer.from(data));
+    return { size: data.length };
+  }
+  async listParts(uploadId) {
+    const m = this.parts.get(uploadId);
+    if (!m) return [];
+    return [...m.keys()].sort((a, b) => a - b);
+  }
+  async mergeParts(uploadId, totalParts, target) {
+    const m = this.parts.get(uploadId);
+    if (!m) throw new Error(`[memory-storage] no parts for ${uploadId}`);
+    const parts = [];
+    for (let i = 1; i <= totalParts; i++) {
+      const p = m.get(i);
+      if (!p) throw new Error(`[memory-storage] missing part ${i}`);
+      parts.push(p);
+    }
+    const merged = Buffer.concat(parts);
+    const key = `mem/${target.id}`;
+    this.files.set(key, merged);
+    return { key, size: merged.length };
+  }
+  async computeMergedHash(uploadId, totalParts) {
+    const hash = createHash2("sha256");
+    const m = this.parts.get(uploadId);
+    if (!m) throw new Error(`[memory-storage] no parts for ${uploadId}`);
+    for (let i = 1; i <= totalParts; i++) {
+      const p = m.get(i);
+      if (!p) throw new Error(`[memory-storage] missing part ${i}`);
+      hash.update(p);
+    }
+    return hash.digest("hex");
+  }
+  async cleanupMultipart(uploadId) {
+    this.parts.delete(uploadId);
+  }
+};
+export {
+  InMemoryStorage,
+  LocalStorage
+};
+//# sourceMappingURL=index.mjs.map

package/dist/server/utils/storage/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/server/utils/storage/local.ts","../../../../src/server/utils/storage/memory.ts"],"sourcesContent":["/**\r\n * 本地磁盘存储实现(默认)\r\n *\r\n * 目录布局:\r\n *   <baseDir>/yyyy/mm/dd/<id>.<ext>          <- 合并后的正式文件\r\n *   <baseDir>/_multipart/<uploadId>/part_0001.bin\r\n *                                          part_0002.bin\r\n *                                          ...\r\n *\r\n * 兼容性: 实现 StorageAdapter 接口,可被 SDK 接受。\r\n *         后续可写 S3Storage(实现同一接口)直接替换,业务代码零改动。\r\n */\r\n\r\nimport { promises as fs, createReadStream, createWriteStream } from 'node:fs';\r\nimport path from 'node:path';\r\nimport { createHash } from 'node:crypto';\r\nimport type { ReadStream } from 'node:fs';\r\nimport type {\r\n  StorageAdapter,\r\n  FileMeta,\r\n  PutResult,\r\n  MergeResult,\r\n} from './types';\r\n\r\nexport interface LocalStorageOptions {\r\n  /** 存储根目录(绝对路径或相对 cwd) */\r\n  baseDir: string;\r\n}\r\n\r\nexport class LocalStorage implements StorageAdapter {\r\n  private baseDir: string;\r\n\r\n  constructor(opts: LocalStorageOptions | string) {\r\n    this.baseDir = typeof opts === 'string' ? opts : opts.baseDir;\r\n  }\r\n\r\n  // ============================================================\r\n  // 内部工具\r\n  // ============================================================\r\n\r\n  private inferExt(filename: string, contentType: string): string {\r\n    const fromName = path.extname(filename).toLowerCase();\r\n    if (fromName) return fromName;\r\n    const map: Record<string, string> = {\r\n      'image/png': '.png',\r\n      'image/jpeg': '.jpg',\r\n      'image/gif': '.gif',\r\n      'image/webp': '.webp',\r\n      'image/svg+xml': '.svg',\r\n      'application/pdf': '.pdf',\r\n      'text/plain': '.txt',\r\n      'application/json': '.json',\r\n      'application/zip': '.zip',\r\n      'video/mp4': '.mp4',\r\n    };\r\n    return map[contentType] ?? '.bin';\r\n  }\r\n\r\n  private generateKey(filename: string, contentType: string, id: string): string {\r\n    const now = new Date();\r\n    const yyyy = now.getFullYear();\r\n    const mm = String(now.getMonth() + 1).padStart(2, '0');\r\n    const dd = String(now.getDate()).padStart(2, '0');\r\n    const ext = this.inferExt(filename, contentType);\r\n    return `${yyyy}/${mm}/${dd}/${id}${ext}`;\r\n  }\r\n\r\n  private multipartDir(uploadId: string): string {\r\n    return path.resolve(this.baseDir, '_multipart', uploadId);\r\n  }\r\n\r\n  private partPath(uploadId: string, partNumber: number): string {\r\n    if (!Number.isInteger(partNumber) || partNumber < 1) {\r\n      throw new Error(`[storage] partNumber 非法: ${partNumber}`);\r\n    }\r\n    return path.join(this.multipartDir(uploadId), `part_${String(partNumber).padStart(4, '0')}.bin`);\r\n  }\r\n\r\n  // ============================================================\r\n  // StorageAdapter 实现\r\n  // ============================================================\r\n\r\n  async put(data: Buffer, meta: FileMeta & { id: string }): Promise<PutResult> {\r\n    const key = this.generateKey(meta.filename, meta.contentType, meta.id);\r\n    const absolutePath = path.resolve(this.baseDir, key);\r\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\r\n    await fs.writeFile(absolutePath, data);\r\n    return { key, absolutePath };\r\n  }\r\n\r\n  get(key: string): ReadStream {\r\n    const absolutePath = path.resolve(this.baseDir, key);\r\n    return createReadStream(absolutePath);\r\n  }\r\n\r\n  async delete(key: string): Promise<void> {\r\n    const absolutePath = path.resolve(this.baseDir, key);\r\n    try {\r\n      await fs.unlink(absolutePath);\r\n    } catch (e: any) {\r\n      if (e.code !== 'ENOENT') throw e;\r\n    }\r\n  }\r\n\r\n  async exists(key: string): Promise<boolean> {\r\n    const absolutePath = path.resolve(this.baseDir, key);\r\n    try {\r\n      await fs.access(absolutePath);\r\n      return true;\r\n    } catch {\r\n      return false;\r\n    }\r\n  }\r\n\r\n  async putPart(\r\n    uploadId: string,\r\n    partNumber: number,\r\n    data: Buffer\r\n  ): Promise<{ size: number; path: string }> {\r\n    const dir = this.multipartDir(uploadId);\r\n    await fs.mkdir(dir, { recursive: true });\r\n    const finalPath = this.partPath(uploadId, partNumber);\r\n    const tmpPath = `${finalPath}.tmp`;\r\n    try {\r\n      await fs.writeFile(tmpPath, data);\r\n      await fs.rename(tmpPath, finalPath);\r\n    } catch (e) {\r\n      try { await fs.unlink(tmpPath); } catch { /* ignore */ }\r\n      throw e;\r\n    }\r\n    return { size: data.length, path: finalPath };\r\n  }\r\n\r\n  async listParts(uploadId: string): Promise<number[]> {\r\n    const dir = this.multipartDir(uploadId);\r\n    try {\r\n      const names = await fs.readdir(dir);\r\n      const nums: number[] = [];\r\n      for (const n of names) {\r\n        const m = n.match(/^part_(\\d{4,})\\.bin$/);\r\n        if (m) nums.push(parseInt(m[1], 10));\r\n      }\r\n      nums.sort((a, b) => a - b);\r\n      return nums;\r\n    } catch (e: any) {\r\n      if (e.code === 'ENOENT') return [];\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  async partSize(uploadId: string, partNumber: number): Promise<number> {\r\n    const p = this.partPath(uploadId, partNumber);\r\n    const stat = await fs.stat(p);\r\n    return stat.size;\r\n  }\r\n\r\n  async mergeParts(\r\n    uploadId: string,\r\n    totalParts: number,\r\n    target: { id: string; filename: string; contentType: string }\r\n  ): Promise<MergeResult> {\r\n    const key = this.generateKey(target.filename, target.contentType, target.id);\r\n    const absolutePath = path.resolve(this.baseDir, key);\r\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\r\n    const tmpPath = `${absolutePath}.merge.tmp`;\r\n\r\n    const out = createWriteStream(tmpPath);\r\n    try {\r\n      for (let i = 1; i <= totalParts; i++) {\r\n        const partPath = this.partPath(uploadId, i);\r\n        try {\r\n          await fs.access(partPath);\r\n        } catch {\r\n          throw new Error(`[storage] 缺分片 part_${i} (uploadId=${uploadId})`);\r\n        }\r\n        await new Promise<void>((resolve, reject) => {\r\n          const rs = createReadStream(partPath);\r\n          rs.on('error', reject);\r\n          rs.on('end', resolve);\r\n          rs.pipe(out, { end: false });\r\n        });\r\n      }\r\n      out.end();\r\n      await new Promise<void>((resolve, reject) => {\r\n        out.on('finish', () => resolve());\r\n        out.on('error', reject);\r\n      });\r\n      const stat = await fs.stat(tmpPath);\r\n      await fs.rename(tmpPath, absolutePath);\r\n      return { key, absolutePath, size: stat.size };\r\n    } catch (e) {\r\n      try { await fs.unlink(tmpPath); } catch { /* ignore */ }\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  async cleanupMultipart(uploadId: string): Promise<void> {\r\n    const dir = this.multipartDir(uploadId);\r\n    try {\r\n      await fs.rm(dir, { recursive: true, force: true });\r\n    } catch (e: any) {\r\n      if (e.code !== 'ENOENT') {\r\n        console.warn(`[storage] cleanup multipart failed: uploadId=${uploadId} err=${e.message}`);\r\n      }\r\n    }\r\n  }\r\n\r\n  async computeMergedHash(uploadId: string, totalParts: number): Promise<string> {\r\n    const hash = createHash('sha256');\r\n    for (let i = 1; i <= totalParts; i++) {\r\n      const partPath = this.partPath(uploadId, i);\r\n      const stream = createReadStream(partPath);\r\n      await new Promise<void>((resolve, reject) => {\r\n        stream.on('data', (chunk) => hash.update(chunk as Buffer));\r\n        stream.on('end', resolve);\r\n        stream.on('error', reject);\r\n      });\r\n    }\r\n    return hash.digest('hex');\r\n  }\r\n}\r\n","/**\r\n * 内存存储实现(测试 / POC 场景)\r\n *\r\n * 用 Map 模拟:\r\n *   - files:     key -> Buffer         (正式文件)\r\n *   - parts:     uploadId -> Map<partNumber, Buffer>  (分片)\r\n *   - partSizes: uploadId -> Map<partNumber, number>\r\n *\r\n * 注意: 内存存储在重启时全部丢失,只用于测试。\r\n *       生产请使用 LocalStorage / S3Storage / OSSStorage。\r\n */\r\n\r\nimport { Readable } from 'node:stream';\r\nimport { createHash } from 'node:crypto';\r\nimport type {\r\n  StorageAdapter,\r\n  FileMeta,\r\n  PutResult,\r\n  MergeResult,\r\n} from './types';\r\n\r\nexport class InMemoryStorage implements StorageAdapter {\r\n  private files = new Map<string, Buffer>();\r\n  private parts = new Map<string, Map<number, Buffer>>();\r\n\r\n  async put(data: Buffer, meta: FileMeta & { id: string }): Promise<PutResult> {\r\n    const key = `mem/${meta.id}`;\r\n    this.files.set(key, Buffer.from(data));\r\n    return { key };\r\n  }\r\n\r\n  get(key: string): NodeJS.ReadableStream {\r\n    const buf = this.files.get(key);\r\n    if (!buf) throw new Error(`[memory-storage] not found: ${key}`);\r\n    return Readable.from(buf);\r\n  }\r\n\r\n  async delete(key: string): Promise<void> {\r\n    this.files.delete(key);\r\n  }\r\n\r\n  async exists(key: string): Promise<boolean> {\r\n    return this.files.has(key);\r\n  }\r\n\r\n  async putPart(\r\n    uploadId: string,\r\n    partNumber: number,\r\n    data: Buffer\r\n  ): Promise<{ size: number }> {\r\n    let m = this.parts.get(uploadId);\r\n    if (!m) {\r\n      m = new Map();\r\n      this.parts.set(uploadId, m);\r\n    }\r\n    m.set(partNumber, Buffer.from(data));\r\n    return { size: data.length };\r\n  }\r\n\r\n  async listParts(uploadId: string): Promise<number[]> {\r\n    const m = this.parts.get(uploadId);\r\n    if (!m) return [];\r\n    return [...m.keys()].sort((a, b) => a - b);\r\n  }\r\n\r\n  async mergeParts(\r\n    uploadId: string,\r\n    totalParts: number,\r\n    target: { id: string; filename: string; contentType: string }\r\n  ): Promise<MergeResult> {\r\n    const m = this.parts.get(uploadId);\r\n    if (!m) throw new Error(`[memory-storage] no parts for ${uploadId}`);\r\n    const parts: Buffer[] = [];\r\n    for (let i = 1; i <= totalParts; i++) {\r\n      const p = m.get(i);\r\n      if (!p) throw new Error(`[memory-storage] missing part ${i}`);\r\n      parts.push(p);\r\n    }\r\n    const merged = Buffer.concat(parts);\r\n    const key = `mem/${target.id}`;\r\n    this.files.set(key, merged);\r\n    return { key, size: merged.length };\r\n  }\r\n\r\n  async computeMergedHash(uploadId: string, totalParts: number): Promise<string> {\r\n    const hash = createHash('sha256');\r\n    const m = this.parts.get(uploadId);\r\n    if (!m) throw new Error(`[memory-storage] no parts for ${uploadId}`);\r\n    for (let i = 1; i <= totalParts; i++) {\r\n      const p = m.get(i);\r\n      if (!p) throw new Error(`[memory-storage] missing part ${i}`);\r\n      hash.update(p);\r\n    }\r\n    return hash.digest('hex');\r\n  }\r\n\r\n  async cleanupMultipart(uploadId: string): Promise<void> {\r\n    this.parts.delete(uploadId);\r\n  }\r\n}\r\n"],"mappings":"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","names":["createHash"]}

package/dist/server/utils/storage/local.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 本地磁盘存储实现(默认)
+ *
+ * 目录布局:
+ *   <baseDir>/yyyy/mm/dd/<id>.<ext>          <- 合并后的正式文件
+ *   <baseDir>/_multipart/<uploadId>/part_0001.bin
+ *                                          part_0002.bin
+ *                                          ...
+ *
+ * 兼容性: 实现 StorageAdapter 接口,可被 SDK 接受。
+ *         后续可写 S3Storage(实现同一接口)直接替换,业务代码零改动。
+ */
+import type { ReadStream } from 'node:fs';
+import type { StorageAdapter, FileMeta, PutResult, MergeResult } from './types';
+export interface LocalStorageOptions {
+    /** 存储根目录(绝对路径或相对 cwd) */
+    baseDir: string;
+}
+export declare class LocalStorage implements StorageAdapter {
+    private baseDir;
+    constructor(opts: LocalStorageOptions | string);
+    private inferExt;
+    private generateKey;
+    private multipartDir;
+    private partPath;
+    put(data: Buffer, meta: FileMeta & {
+        id: string;
+    }): Promise<PutResult>;
+    get(key: string): ReadStream;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    putPart(uploadId: string, partNumber: number, data: Buffer): Promise<{
+        size: number;
+        path: string;
+    }>;
+    listParts(uploadId: string): Promise<number[]>;
+    partSize(uploadId: string, partNumber: number): Promise<number>;
+    mergeParts(uploadId: string, totalParts: number, target: {
+        id: string;
+        filename: string;
+        contentType: string;
+    }): Promise<MergeResult>;
+    cleanupMultipart(uploadId: string): Promise<void>;
+    computeMergedHash(uploadId: string, totalParts: number): Promise<string>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/server/utils/storage/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/storage/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,SAAS,EACT,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,YAAa,YAAW,cAAc;IACjD,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,mBAAmB,GAAG,MAAM;IAQ9C,OAAO,CAAC,QAAQ;IAkBhB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAWV,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAQ5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAKtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrC,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAepC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM/D,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,WAAW,CAAC;IAoCjB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjD,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAa/E"}

package/dist/server/utils/storage/memory.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 内存存储实现(测试 / POC 场景)
+ *
+ * 用 Map 模拟:
+ *   - files:     key -> Buffer         (正式文件)
+ *   - parts:     uploadId -> Map<partNumber, Buffer>  (分片)
+ *   - partSizes: uploadId -> Map<partNumber, number>
+ *
+ * 注意: 内存存储在重启时全部丢失,只用于测试。
+ *       生产请使用 LocalStorage / S3Storage / OSSStorage。
+ */
+import type { StorageAdapter, FileMeta, PutResult, MergeResult } from './types';
+export declare class InMemoryStorage implements StorageAdapter {
+    private files;
+    private parts;
+    put(data: Buffer, meta: FileMeta & {
+        id: string;
+    }): Promise<PutResult>;
+    get(key: string): NodeJS.ReadableStream;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    putPart(uploadId: string, partNumber: number, data: Buffer): Promise<{
+        size: number;
+    }>;
+    listParts(uploadId: string): Promise<number[]>;
+    mergeParts(uploadId: string, totalParts: number, target: {
+        id: string;
+        filename: string;
+        contentType: string;
+    }): Promise<MergeResult>;
+    computeMergedHash(uploadId: string, totalParts: number): Promise<string>;
+    cleanupMultipart(uploadId: string): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/server/utils/storage/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/storage/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,SAAS,EACT,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAA0C;IAEjD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAM5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc;IAMjC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAUtB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAM9C,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,WAAW,CAAC;IAejB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYxE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxD"}

package/dist/server/utils/storage/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 存储适配器接口
+ *
+ * 任何实现这个接口的对象都可以被 SDK 接受:
+ *   - 内置: LocalStorage
+ *   - 用户实现: S3Storage / AliyunOSSStorage / TencentCOSStorage / 内存 / 任何外部存储
+ *
+ * 设计目标: 不与具体存储服务耦合,业务层只依赖 StorageAdapter 接口
+ */
+import type { ReadStream } from 'node:fs';
+export interface FileMeta {
+    filename: string;
+    contentType: string;
+    size: number;
+    isPublic: boolean;
+    userId?: number;
+}
+export interface PutResult {
+    key: string;
+    /** 本地存储的绝对路径(S3/OSS 这类云存储没有,可以是 null) */
+    absolutePath?: string;
+}
+export interface MergeResult {
+    key: string;
+    absolutePath?: string;
+    size: number;
+}
+export interface StorageAdapter {
+    /** 写入完整文件(单文件直传场景,MVP 保留) */
+    put(data: Buffer, meta: FileMeta & {
+        id: string;
+    }): Promise<PutResult>;
+    /** 读取文件流(用于下载 / 代理) */
+    get(key: string): ReadStream | NodeJS.ReadableStream;
+    /** 删除文件(用于秒传孤儿清理 / abort) */
+    delete(key: string): Promise<void>;
+    /** 校验 key 在存储上是否存在(用于秒传二次校验) */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 写入单个分片(原子)
+     *  - 写入失败自动清理临时文件
+     *  - 返回该分片写入后的实际字节数
+     */
+    putPart(uploadId: string, partNumber: number, data: Buffer): Promise<{
+        size: number;
+        path?: string;
+    }>;
+    /**
+     * 列出已收到的 partNumber(数字升序)
+     *  - 用于断点续传
+     *  - 目录不存在时返回空数组
+     */
+    listParts(uploadId: string): Promise<number[]>;
+    /**
+     * 按 partNumber 顺序合并所有分片到目标 key
+     *  - 必须按 1 → 2 → ... → totalParts 顺序拼接
+     *  - 失败抛错,需要上层 catch + cleanup
+     *  - 临时文件路径可以由实现自定义
+     */
+    mergeParts(uploadId: string, totalParts: number, target: {
+        id: string;
+        filename: string;
+        contentType: string;
+    }): Promise<MergeResult>;
+    /**
+     * 计算整个 uploadId 下所有分片合并后的 SHA-256(hex)
+     *  - 用于 complete 阶段最终 hash 校验
+     *  - 流式计算,不一次性加载整个文件
+     */
+    computeMergedHash(uploadId: string, totalParts: number): Promise<string>;
+    /**
+     * 清理整个 uploadId 的临时分片目录
+     *  - 用于:用户主动 abort、TTL 到期、合并成功后
+     *  - 幂等:目录/对象不存在不抛错
+     */
+    cleanupMultipart(uploadId: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/utils/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/server/utils/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAK7B,6BAA6B;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEvE,uBAAuB;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC;IAErD,6BAA6B;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,gCAAgC;IAChC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAMtC;;;;OAIG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE5C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,UAAU,CACR,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzE;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/server/utils/strategy.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Smart 上传策略选择器
+ *
+ * 服务端根据 totalSize 自动选择 ONE_SHOT 或 MULTIPART:
+ *   - ONE_SHOT:  1 个 part(适合 ≤ ONE_SHOT_MAX 的小文件)
+ *                客户端只调 1 次 part + 1 次 complete = 2 RTT
+ *   - MULTIPART: N 个 part,根据文件大小动态调整 partSize:
+ *                  ≤ 1GB         → 1MB / part
+ *                  1 ~ 10GB      → 5MB / part
+ *                  > 10GB        → 10MB / part
+ *
+ * 设计约束
+ * ========
+ *   - 纯函数:无副作用、不读 IO、不访问全局状态,易于单测
+ *   - 0 字节文件合法(partSize=0, totalParts=1)
+ *   - 决策结果携带 reason 字段,便于日志/排障
+ *   - 不与 config 直接耦合:调用方传入 cfg
+ */
+export type StrategyKind = 'ONE_SHOT' | 'MULTIPART';
+export interface StrategyConfig {
+    /** ≤ 此字节数走 ONE_SHOT(默认 1MB) */
+    oneShotMax: number;
+    /** 默认分片大小(默认 1MB) */
+    defaultPartSize: number;
+    /** 超过此字节数切到大分片(默认 1GB) */
+    bigFileThreshold: number;
+    /** 大文件分片大小(默认 5MB) */
+    bigFilePartSize: number;
+    /** 超过此字节数切到超大分片(默认 10GB) */
+    hugeFileThreshold: number;
+    /** 超大文件分片大小(默认 10MB) */
+    hugeFilePartSize: number;
+}
+export interface StrategyResult {
+    kind: StrategyKind;
+    /** 实际分片大小(字节) */
+    partSize: number;
+    /** 总分片数(ONE_SHOT 固定为 1) */
+    totalParts: number;
+    /** 决策原因(便于日志/调试) */
+    reason: string;
+}
+/** 默认策略配置 */
+export declare const DEFAULT_STRATEGY_CONFIG: StrategyConfig;
+/**
+ * 根据 totalSize 选出上传策略
+ *
+ * @throws  totalSize 非法(负数 / NaN / 非有限数)
+ *
+ * @example
+ *   chooseStrategy(1024)            // → ONE_SHOT  1 part, partSize=1024
+ *   chooseStrategy(5 * 1024 * 1024) // → MULTIPART 5 part, partSize=1MB
+ *   chooseStrategy(5 * 1024**3)     // → MULTIPART 1024 part, partSize=5MB
+ *   chooseStrategy(50 * 1024**3)    // → MULTIPART 5120 part, partSize=10MB
+ */
+export declare function chooseStrategy(totalSize: number, cfg?: StrategyConfig): StrategyResult;
+/**
+ * 建议的客户端并发上传 part 数
+ *   - ONE_SHOT:固定 1(只传 1 个 part,无需并发)
+ *   - totalParts ≤ 4:用 totalParts(part 太少,无并发必要)
+ *   - totalParts > 4:用 4(服务端限流/带宽考虑)
+ */
+export declare function suggestConcurrency(s: StrategyResult): number;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/server/utils/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../src/server/utils/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,iBAAiB;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,aAAa;AACb,eAAO,MAAM,uBAAuB,EAAE,cAOrC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,cAAwC,GAC5C,cAAc,CA8ChB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAI5D"}

package/dist/server/utils/strategy.js

@@ -0,0 +1,130 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/utils/strategy.ts
+var strategy_exports = {};
+__export(strategy_exports, {
+  DEFAULT_STRATEGY_CONFIG: () => DEFAULT_STRATEGY_CONFIG,
+  chooseStrategy: () => chooseStrategy,
+  suggestConcurrency: () => suggestConcurrency
+});
+module.exports = __toCommonJS(strategy_exports);
+var DEFAULT_STRATEGY_CONFIG = {
+  oneShotMax: 1024 * 1024,
+  // 1MB
+  defaultPartSize: 1024 * 1024,
+  // 1MB
+  bigFileThreshold: 1024 ** 3,
+  // 1GB
+  bigFilePartSize: 5 * 1024 * 1024,
+  // 5MB
+  hugeFileThreshold: 10 * 1024 ** 3,
+  // 10GB
+  hugeFilePartSize: 10 * 1024 * 1024
+  // 10MB
+};
+function chooseStrategy(totalSize, cfg = DEFAULT_STRATEGY_CONFIG) {
+  if (!Number.isFinite(totalSize) || totalSize < 0) {
+    throw new Error(`[strategy] totalSize \u975E\u6CD5: ${totalSize}(\u5FC5\u987B \u2265 0 \u7684\u6709\u9650\u6570)`);
+  }
+  validateConfig(cfg);
+  if (totalSize === 0) {
+    return { kind: "ONE_SHOT", partSize: 0, totalParts: 1, reason: "0\u5B57\u8282" };
+  }
+  if (totalSize <= cfg.oneShotMax) {
+    return {
+      kind: "ONE_SHOT",
+      partSize: totalSize,
+      totalParts: 1,
+      reason: `\u2264 ${cfg.oneShotMax}B \u8D70 ONE_SHOT(1 part \u76F4\u4F20)`
+    };
+  }
+  if (totalSize > cfg.hugeFileThreshold) {
+    const partSize2 = cfg.hugeFilePartSize;
+    return {
+      kind: "MULTIPART",
+      partSize: partSize2,
+      totalParts: Math.ceil(totalSize / partSize2),
+      reason: `> ${cfg.hugeFileThreshold}B \u8D70 HUGE(${partSize2}B/part)`
+    };
+  }
+  if (totalSize > cfg.bigFileThreshold) {
+    const partSize2 = cfg.bigFilePartSize;
+    return {
+      kind: "MULTIPART",
+      partSize: partSize2,
+      totalParts: Math.ceil(totalSize / partSize2),
+      reason: `> ${cfg.bigFileThreshold}B \u8D70 BIG(${partSize2}B/part)`
+    };
+  }
+  const partSize = cfg.defaultPartSize;
+  return {
+    kind: "MULTIPART",
+    partSize,
+    totalParts: Math.ceil(totalSize / partSize),
+    reason: `\u2264 ${cfg.bigFileThreshold}B \u8D70 DEFAULT(${partSize}B/part)`
+  };
+}
+function suggestConcurrency(s) {
+  if (s.kind === "ONE_SHOT") return 1;
+  if (s.totalParts <= 4) return Math.max(1, s.totalParts);
+  return 4;
+}
+function validateConfig(cfg) {
+  const fields = [
+    ["oneShotMax", "oneShotMax"],
+    ["defaultPartSize", "defaultPartSize"],
+    ["bigFileThreshold", "bigFileThreshold"],
+    ["bigFilePartSize", "bigFilePartSize"],
+    ["hugeFileThreshold", "hugeFileThreshold"],
+    ["hugeFilePartSize", "hugeFilePartSize"]
+  ];
+  for (const [k, name] of fields) {
+    if (!Number.isFinite(cfg[k]) || cfg[k] <= 0) {
+      throw new Error(`[strategy] cfg.${name} \u975E\u6CD5: ${cfg[k]}(\u5FC5\u987B > 0)`);
+    }
+  }
+  if (cfg.oneShotMax > cfg.defaultPartSize) {
+    throw new Error(
+      `[strategy] oneShotMax(${cfg.oneShotMax}) \u4E0D\u80FD > defaultPartSize(${cfg.defaultPartSize})`
+    );
+  }
+  if (cfg.bigFileThreshold >= cfg.hugeFileThreshold) {
+    throw new Error(
+      `[strategy] bigFileThreshold(${cfg.bigFileThreshold}) \u5FC5\u987B < hugeFileThreshold(${cfg.hugeFileThreshold})`
+    );
+  }
+  if (cfg.defaultPartSize > cfg.bigFilePartSize) {
+    throw new Error(
+      `[strategy] defaultPartSize(${cfg.defaultPartSize}) \u4E0D\u80FD > bigFilePartSize(${cfg.bigFilePartSize})`
+    );
+  }
+  if (cfg.bigFilePartSize > cfg.hugeFilePartSize) {
+    throw new Error(
+      `[strategy] bigFilePartSize(${cfg.bigFilePartSize}) \u4E0D\u80FD > hugeFilePartSize(${cfg.hugeFilePartSize})`
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_STRATEGY_CONFIG,
+  chooseStrategy,
+  suggestConcurrency
+});
+//# sourceMappingURL=strategy.js.map