@xgspz/base-sdk 0.0.0-stage → 1.0.5

package/src/storage-upload.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import type { StorageUploadTicket } from "@xgspz/contracts";
+
+/**
+ * 拿到基础服务签发的上传令牌后，直接传到对象存储（七牛），文件不经过基础服务中转：
+ *   - 16MB 以内：表单上传；
+ *   - 更大：分片上传 v2（initiate → 逐片 PUT → complete），每片失败重试 3 次。
+ * 令牌只对一个确定的 key 有效且只能新建：同一个 key 已存在（614）视为成功（key 按内容命名）。
+ */
+export class StorageUploadError extends Error {
+  constructor(message: string, readonly status: number) {
+    super(message);
+    this.name = "StorageUploadError";
+  }
+}
+
+const FORM_LIMIT = 16 * 1024 * 1024;
+const DEFAULT_PART = 8 * 1024 * 1024;
+const b64url = (s: string) => Buffer.from(s).toString("base64").replace(/\+/g, "-").replace(/\//g, "_");
+
+/** 上传令牌里带着 putPolicy（scope = bucket:key），分片上传的地址要用到 bucket。 */
+function bucketOf(token: string) {
+  const encoded = token.split(":")[2] ?? "";
+  const policy = JSON.parse(Buffer.from(encoded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8")) as { scope?: string };
+  const bucket = String(policy.scope ?? "").split(":")[0];
+  if (!bucket) throw new StorageUploadError("上传令牌里没有 bucket", 400);
+  return bucket;
+}
+
+async function ok(res: Response, what: string) {
+  if (res.ok) return res.json().catch(() => ({})) as Promise<Record<string, unknown>>;
+  const text = await res.text().catch(() => "");
+  throw new StorageUploadError(`${what}失败（HTTP ${res.status}）：${text.slice(0, 200)}`, res.status);
+}
+
+export async function uploadToStorage(
+  ticket: Pick<StorageUploadTicket, "key" | "token" | "uploadUrl">,
+  source: { file: string } | { bytes: Buffer },
+  opts: { contentType: string; signal?: AbortSignal; partSize?: number },
+): Promise<{ key: string; existed: boolean; size: number }> {
+  const size = "bytes" in source ? source.bytes.length : fs.statSync(source.file).size;
+  if (size <= FORM_LIMIT) {
+    const bytes = "bytes" in source ? source.bytes : await fs.promises.readFile(source.file);
+    const form = new FormData();
+    form.set("token", ticket.token);
+    form.set("key", ticket.key);
+    form.set("file", new Blob([new Uint8Array(bytes)], { type: opts.contentType }), ticket.key.split("/").pop() || "file");
+    const res = await fetch(ticket.uploadUrl, { method: "POST", body: form, signal: opts.signal });
+    if (res.status === 614) return { key: ticket.key, existed: true, size };
+    await ok(res, "上传");
+    return { key: ticket.key, existed: false, size };
+  }
+
+  const partSize = Math.max(1024 * 1024, opts.partSize ?? DEFAULT_PART);
+  const base = `${ticket.uploadUrl}/buckets/${encodeURIComponent(bucketOf(ticket.token))}/objects/${b64url(ticket.key)}/uploads`;
+  const auth = { Authorization: `UpToken ${ticket.token}` };
+  const init = await fetch(base, { method: "POST", headers: auth, signal: opts.signal });
+  if (init.status === 614) return { key: ticket.key, existed: true, size };
+  const { uploadId } = await ok(init, "创建分片上传") as { uploadId?: string };
+  if (!uploadId) throw new StorageUploadError("创建分片上传没有返回 uploadId", 502);
+
+  const handle = "file" in source ? await fs.promises.open(source.file, "r") : null;
+  const parts: Array<{ partNumber: number; etag: string }> = [];
+  try {
+    for (let offset = 0, partNumber = 1; offset < size; offset += partSize, partNumber += 1) {
+      const length = Math.min(partSize, size - offset);
+      let chunk: Buffer;
+      if (handle) {
+        chunk = Buffer.alloc(length);
+        await handle.read(chunk, 0, length, offset);
+      } else {
+        chunk = (source as { bytes: Buffer }).bytes.subarray(offset, offset + length);
+      }
+      let etag = "";
+      for (let attempt = 1; attempt <= 3 && !etag; attempt += 1) {
+        try {
+          const res = await fetch(`${base}/${uploadId}/${partNumber}`, {
+            method: "PUT", headers: { ...auth, "Content-Type": "application/octet-stream" }, body: new Uint8Array(chunk), signal: opts.signal,
+          });
+          etag = String((await ok(res, `上传第 ${partNumber} 片`)).etag ?? "");
+          if (!etag) throw new StorageUploadError(`第 ${partNumber} 片没有返回 etag`, 502);
+        } catch (error) {
+          if (attempt === 3 || opts.signal?.aborted) throw error;
+          await new Promise((r) => setTimeout(r, 500 * attempt));
+        }
+      }
+      parts.push({ partNumber, etag });
+    }
+  } finally {
+    await handle?.close();
+  }
+  const done = await fetch(`${base}/${uploadId}`, {
+    method: "POST",
+    headers: { ...auth, "Content-Type": "application/json" },
+    body: JSON.stringify({ parts, mimeType: opts.contentType }),
+    signal: opts.signal,
+  });
+  if (done.status === 614) return { key: ticket.key, existed: true, size };
+  await ok(done, "完成分片上传");
+  return { key: ticket.key, existed: false, size };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.