@xgspz/base-sdk 0.0.0-stage → 1.0.5

package/dist/storage-upload.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+/**
+ * 拿到基础服务签发的上传令牌后，直接传到对象存储（七牛），文件不经过基础服务中转：
+ *   - 16MB 以内：表单上传；
+ *   - 更大：分片上传 v2（initiate → 逐片 PUT → complete），每片失败重试 3 次。
+ * 令牌只对一个确定的 key 有效且只能新建：同一个 key 已存在（614）视为成功（key 按内容命名）。
+ */
+export class StorageUploadError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "StorageUploadError";
+    }
+}
+const FORM_LIMIT = 16 * 1024 * 1024;
+const DEFAULT_PART = 8 * 1024 * 1024;
+const b64url = (s) => Buffer.from(s).toString("base64").replace(/\+/g, "-").replace(/\//g, "_");
+/** 上传令牌里带着 putPolicy（scope = bucket:key），分片上传的地址要用到 bucket。 */
+function bucketOf(token) {
+    const encoded = token.split(":")[2] ?? "";
+    const policy = JSON.parse(Buffer.from(encoded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+    const bucket = String(policy.scope ?? "").split(":")[0];
+    if (!bucket)
+        throw new StorageUploadError("上传令牌里没有 bucket", 400);
+    return bucket;
+}
+async function ok(res, what) {
+    if (res.ok)
+        return res.json().catch(() => ({}));
+    const text = await res.text().catch(() => "");
+    throw new StorageUploadError(`${what}失败（HTTP ${res.status}）：${text.slice(0, 200)}`, res.status);
+}
+export async function uploadToStorage(ticket, source, opts) {
+    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, "创建分片上传");
+    if (!uploadId)
+        throw new StorageUploadError("创建分片上传没有返回 uploadId", 502);
+    const handle = "file" in source ? await fs.promises.open(source.file, "r") : null;
+    const parts = [];
+    try {
+        for (let offset = 0, partNumber = 1; offset < size; offset += partSize, partNumber += 1) {
+            const length = Math.min(partSize, size - offset);
+            let chunk;
+            if (handle) {
+                chunk = Buffer.alloc(length);
+                await handle.read(chunk, 0, length, offset);
+            }
+            else {
+                chunk = source.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/dist/storage-upload.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-upload.test.d.ts.map

package/dist/storage-upload.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-upload.test.d.ts","sourceRoot":"","sources":["../src/storage-upload.test.ts"],"names":[],"mappings":""}

package/dist/storage-upload.test.js

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { BaseClient, uploadToStorage } from "./index.js";
+const policy = (scope) => Buffer.from(JSON.stringify({ scope, deadline: 1, insertOnly: 1 })).toString("base64").replace(/\+/g, "-").replace(/\//g, "_");
+const ticket = { key: "svc/notex/exports/a.mp4", token: `AK:SIGN:${policy("bkt:svc/notex/exports/a.mp4")}`, uploadUrl: "https://up.test" };
+function stub(handler) {
+    const calls = [];
+    const original = globalThis.fetch;
+    globalThis.fetch = (async (input, init = {}) => {
+        calls.push({ url: String(input), init });
+        return handler(String(input), init);
+    });
+    return { calls, restore: () => { globalThis.fetch = original; } };
+}
+test("小文件表单上传；key 已存在（614）视为成功", async () => {
+    const s = stub(() => new Response(JSON.stringify({ key: ticket.key }), { status: 200 }));
+    try {
+        const r = await uploadToStorage(ticket, { bytes: Buffer.from("hello") }, { contentType: "text/plain" });
+        assert.deepEqual(r, { key: ticket.key, existed: false, size: 5 });
+        const form = s.calls[0].init.body;
+        assert.equal(s.calls[0].url, "https://up.test");
+        assert.equal(form.get("key"), ticket.key);
+        assert.equal(form.get("token"), ticket.token);
+    }
+    finally {
+        s.restore();
+    }
+    // 七牛用非标准的 614 表示「已存在」：真实网络响应可以带这个码，构造的 Response 不行，这里用一个等价的对象。
+    const exists = { status: 614, ok: false, json: async () => ({ error: "file exists" }), text: async () => "{\"error\":\"file exists\"}" };
+    const again = stub(() => exists);
+    try {
+        assert.equal((await uploadToStorage(ticket, { bytes: Buffer.from("hello") }, { contentType: "text/plain" })).existed, true);
+    }
+    finally {
+        again.restore();
+    }
+});
+test("大文件分片上传 v2：initiate → 逐片 PUT（失败重试）→ complete，分片顺序和 etag 正确", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-upload-"));
+    const file = path.join(dir, "big.bin");
+    fs.writeFileSync(file, Buffer.alloc(17 * 1024 * 1024 + 5, 7));
+    let flaky = true;
+    const s = stub((url, init) => {
+        if (url.endsWith("/uploads") && init.method === "POST")
+            return new Response(JSON.stringify({ uploadId: "U1" }));
+        if (init.method === "PUT") {
+            if (url.endsWith("/2") && flaky) {
+                flaky = false;
+                return new Response("busy", { status: 503 });
+            }
+            return new Response(JSON.stringify({ etag: `e${url.split("/").pop()}` }));
+        }
+        return new Response(JSON.stringify({ key: ticket.key, hash: "h" }));
+    });
+    try {
+        const r = await uploadToStorage(ticket, { file }, { contentType: "video/mp4", partSize: 8 * 1024 * 1024 });
+        assert.equal(r.size, 17 * 1024 * 1024 + 5);
+        const base = `https://up.test/buckets/bkt/objects/${Buffer.from(ticket.key).toString("base64").replace(/\+/g, "-").replace(/\//g, "_")}/uploads`;
+        assert.equal(s.calls[0].url, base);
+        assert.equal(s.calls[0].init.headers.Authorization, `UpToken ${ticket.token}`);
+        const puts = s.calls.filter((c) => c.init.method === "PUT").map((c) => c.url.split("/").pop());
+        assert.deepEqual(puts, ["1", "2", "2", "3"], "第 2 片失败后重试");
+        const done = JSON.parse(String(s.calls[s.calls.length - 1].init.body));
+        assert.deepEqual(done.parts, [{ partNumber: 1, etag: "e1" }, { partNumber: 2, etag: "e2" }, { partNumber: 3, etag: "e3" }]);
+        assert.equal(done.mimeType, "video/mp4");
+    }
+    finally {
+        s.restore();
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("生图 / 看图用单次调用的长超时，不自动重试；存储签名可重试", async () => {
+    const client = new BaseClient({ baseUrl: "http://base.test", serviceName: "notex", serviceToken: "tok", timeoutMs: 1 });
+    let calls = 0;
+    const s = stub(() => { calls += 1; return new Response(JSON.stringify({ success: true, data: { callId: "c", model: "10006" } }), { status: 200 }); });
+    try {
+        // 客户端默认超时只有 1ms；生图接口用自己的长超时，所以不会被中止。
+        const r = await client.generateImage({ prompt: "画" }, { personId: "p1" });
+        assert.equal(r.callId, "c");
+        assert.equal(s.calls[0].url, "http://base.test/internal/media/images");
+    }
+    finally {
+        s.restore();
+    }
+    const fail = stub(() => { calls += 1; return new Response(JSON.stringify({ success: false, code: "MEDIA_UPSTREAM", message: "忙" }), { status: 502 }); });
+    try {
+        calls = 0;
+        await assert.rejects(client.analyzeImages({ prompt: "看", images: ["https://x/y.png"] }, { personId: "p1" }, { timeoutMs: 5000 }), /忙/);
+        assert.equal(calls, 1, "看图不自动重试（计次数）");
+    }
+    finally {
+        fail.restore();
+    }
+});

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@xgspz/base-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.5",
+  "type": "module",
+  "description": "业务服务调用基础服务的客户端。封装服务令牌、代理用户、幂等与重试。",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test --test-reporter=spec \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@xgspz/contracts": "^1.0.1",
+    "@xgspz/service-kit": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "tsx": "^4.19.2",
+    "@types/express": "^5.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.21.2"
+  }
+}

package/src/express.ts

@@ -0,0 +1,53 @@
+import type { NextFunction, Request, Response } from "express";
+import { apiError } from "@xgspz/service-kit";
+import type { InternalUserLookup } from "@xgspz/contracts";
+
+/** 通过基础服务校验后的终端用户。与 ActingUser（只含 personId）不是一回事。 */
+export interface AuthenticatedUser {
+  accessToken: string;
+  personId: string;
+  userId: string;
+  empId: string | null;
+  userName: string;
+  /** 平台部门。业务服务的准入控制按它判断，没有部门时是空数组。 */
+  departments: Array<{ id: string; name: string; isMain: boolean }>;
+  /** Base「用户与服务权限」里这个人在本服务上的角色，没授权（或 Base 是旧版）为 null。 */
+  serviceRole: NonNullable<InternalUserLookup["serviceRole"]> | null;
+}
+
+export type AuthRequest = Request & { actor?: AuthenticatedUser };
+
+/**
+ * 业务服务的用户鉴权中间件。
+ *
+ * 业务服务不自己发会话，也不能直接相信前端传来的头，一律回基础服务校验。
+ * verifier 内部有短 TTL 缓存，不会每个请求都往返。
+ */
+export function requireUser(verify: (token: string, personId: string) => Promise<InternalUserLookup>) {
+  return async function middleware(req: Request, _res: Response, next: NextFunction) {
+    try {
+      const token = String(req.header("access-token") || req.header("authorization")?.replace(/^Bearer\s+/i, "") || "").trim();
+      const personId = String(req.header("personId") || req.header("person-id") || "").trim();
+      if (!token || !personId) throw apiError("缺少 access-token 或 personId", "UNAUTHORIZED");
+      const user = await verify(token, personId);
+      (req as AuthRequest).actor = {
+        accessToken: token,
+        personId: user.personId,
+        userId: user.userId,
+        empId: user.empId,
+        userName: user.userName,
+        departments: user.departments ?? [],
+        serviceRole: user.serviceRole ?? null,
+      };
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+export function actor(req: Request): AuthenticatedUser {
+  const value = (req as AuthRequest).actor;
+  if (!value) throw apiError("未登录", "UNAUTHORIZED");
+  return value;
+}

package/src/index.test.ts

@@ -0,0 +1,231 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { BaseClient, BaseServiceError, createBaseClient, createSessionVerifier } from "./index.js";
+
+/** 用一个可控的 fetch 替身驱动客户端，不碰网络。 */
+function stubFetch(handler: (url: string, init: RequestInit) => { status: number; body: unknown }) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input: string | URL | Request, init: RequestInit = {}) => {
+    const url = String(input);
+    calls.push({ url, init });
+    const { status, body } = handler(url, init);
+    return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+  }) as typeof fetch;
+  return { calls, restore: () => { globalThis.fetch = original; } };
+}
+
+const client = () => new BaseClient({
+  baseUrl: "http://base.test",
+  serviceName: "demo",
+  serviceToken: "tok-1",
+});
+
+test("完整协同详情选项仅在启用时透传到 Base", async () => {
+  const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+  try {
+    await client().getCollaborationDetail("2110996699949559811", { personId: "11809" }, { includeAssociated: true });
+    await client().getCollaborationDetail("2110996699949559811", { personId: "11809" });
+    assert.ok(stub.calls[0]!.url.endsWith("2110996699949559811?includeAssociated=true"));
+    assert.ok(stub.calls[1]!.url.endsWith("2110996699949559811"));
+  } finally { stub.restore(); }
+});
+
+test("每个请求都带服务令牌、服务名和代理用户", async () => {
+  const stub = stubFetch(() => ({ status: 200, body: { success: true, data: { personId: "1" } } }));
+  try {
+    await client().lookupUser("11809", { personId: "11809" });
+    const headers = stub.calls[0].init.headers as Record<string, string>;
+    assert.equal(headers["X-Service-Token"], "tok-1");
+    assert.equal(headers["X-Service-Name"], "demo");
+    assert.equal(headers["X-Acting-PersonId"], "11809");
+  } finally {
+    stub.restore();
+  }
+});
+
+test("缺少 actingPersonId 时直接拒绝，不发请求", async () => {
+  const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+  try {
+    // 平台侧的发起人必须是真实的人，不能有"系统身份"默认值。
+    await assert.rejects(() => client().lookupUser("1", { personId: "" }), /actingPersonId/);
+    assert.equal(stub.calls.length, 0);
+  } finally {
+    stub.restore();
+  }
+});
+
+test("基础服务的业务错误会带上 code 和 status", async () => {
+  const stub = stubFetch(() => ({ status: 409, body: { success: false, message: "附件尚未同步", code: "CONFLICT" } }));
+  try {
+    await assert.rejects(
+      () => client().sendCollaboration({
+        title: "t", content: "c", recipients: [], idempotencyKey: "k",
+        origin: { service: "demo", entityType: "X", entityId: "1" },
+      }, { personId: "11809" }),
+      (error: unknown) => {
+        assert.ok(error instanceof BaseServiceError);
+        assert.equal(error.code, "CONFLICT");
+        assert.equal(error.status, 409);
+        assert.match(error.message, /附件尚未同步/);
+        return true;
+      },
+    );
+  } finally {
+    stub.restore();
+  }
+});
+
+test("写操作不重试（幂等键由基础服务兜底），读操作才重试", async () => {
+  let writes = 0;
+  let reads = 0;
+  const stub = stubFetch((url, init) => {
+    if (init.method === "POST") { writes += 1; return { status: 503, body: { success: false, message: "down" } }; }
+    reads += 1;
+    return { status: 503, body: { success: false, message: "down" } };
+  });
+  try {
+    await assert.rejects(() => client().sendTodo({
+      title: "t", content: "c", recipients: [], refUrl: "https://x.test", idempotencyKey: "k",
+      origin: { service: "demo", entityType: "X", entityId: "1" },
+    }, { personId: "11809" }));
+    // 写只发一次：重试可能造成重复送达。
+    assert.equal(writes, 1);
+    await assert.rejects(() => client().lookupUser("1", { personId: "11809" }));
+    // 读会退避重试。
+    assert.ok(reads > 1, `读操作应重试，实际只发了 ${reads} 次`);
+  } finally {
+    stub.restore();
+  }
+});
+
+test("基础服务不可达时给出可辨认的错误", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = (async () => { throw new Error("ECONNREFUSED"); }) as typeof fetch;
+  try {
+    await assert.rejects(
+      () => client().lookupUser("1", { personId: "11809" }),
+      (error: unknown) => {
+        assert.ok(error instanceof BaseServiceError);
+        assert.equal(error.code, "UNREACHABLE");
+        return true;
+      },
+    );
+  } finally {
+    globalThis.fetch = original;
+  }
+});
+
+test("会话校验结果会缓存，不会每个请求都往返", async () => {
+  let hits = 0;
+  const stub = stubFetch(() => {
+    hits += 1;
+    return { status: 200, body: { success: true, data: { personId: "11809", userId: "u1", empId: "e1", userName: "张三", corpId: null } } };
+  });
+  try {
+    const verify = createSessionVerifier(client(), { ttlMs: 10_000 });
+    await verify("tok", "11809");
+    await verify("tok", "11809");
+    assert.equal(hits, 1, "第二次应命中缓存");
+    // 换个 token 必须重新校验，否则退出登录后旧 token 还能用。
+    await verify("other", "11809");
+    assert.equal(hits, 2);
+  } finally {
+    stub.restore();
+  }
+});
+
+test("缓存过期后重新校验", async () => {
+  let hits = 0;
+  const stub = stubFetch(() => {
+    hits += 1;
+    return { status: 200, body: { success: true, data: { personId: "1", userId: "u", empId: null, userName: "n", corpId: null } } };
+  });
+  try {
+    const verify = createSessionVerifier(client(), { ttlMs: 1 });
+    await verify("tok", "1");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await verify("tok", "1");
+    assert.equal(hits, 2);
+  } finally {
+    stub.restore();
+  }
+});
+
+test("缺 token 或 personId 时不发请求", async () => {
+  const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+  try {
+    const verify = createSessionVerifier(client());
+    await assert.rejects(() => verify("", "1"), /access-token/);
+    await assert.rejects(() => verify("t", ""), /personId/);
+    assert.equal(stub.calls.length, 0);
+  } finally {
+    stub.restore();
+  }
+});
+
+test("通知令牌校验：空令牌一律拒绝", () => {
+  // 期望值为空时必须拒绝，不能退化成"谁都可以"。
+});
+
+test("createBaseClient 从环境变量装配", () => {
+  const built = createBaseClient({ BASE_SERVICE_URL: "http://x.test", BASE_SERVICE_TOKEN: "t" } as NodeJS.ProcessEnv, "legal");
+  assert.equal(built.configured, true);
+  const missing = createBaseClient({} as NodeJS.ProcessEnv, "legal");
+  assert.equal(missing.configured, false);
+});
+
+test("会话验不过时统一报 401，而不是把 404 透给前端", async () => {
+  const stub = stubFetch(() => ({ status: 404, body: { success: false, message: "用户不存在", code: "NOT_FOUND" } }));
+  try {
+    const verify = createSessionVerifier(client());
+    await assert.rejects(
+      () => verify("tok", "999999"),
+      (error: unknown) => {
+        assert.ok(error instanceof BaseServiceError);
+        assert.equal(error.status, 401);
+        assert.match(error.message, /重新登录/);
+        return true;
+      },
+    );
+  } finally {
+    stub.restore();
+  }
+});
+
+test("基础服务故障不能被误报成「登录失效」", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = (async () => { throw new Error("ECONNREFUSED"); }) as typeof fetch;
+  try {
+    const verify = createSessionVerifier(client());
+    await assert.rejects(
+      () => verify("tok", "11809"),
+      (error: unknown) => {
+        assert.ok(error instanceof BaseServiceError);
+        // 依赖挂了就该说依赖挂了，让用户去重新登录只会白折腾。
+        assert.equal(error.code, "UNREACHABLE");
+        assert.notEqual(error.status, 401);
+        return true;
+      },
+    );
+  } finally {
+    globalThis.fetch = original;
+  }
+});
+
+test("语音请求的签名校验：对的才过；改了通话 id、过期、缺头、令牌不对都不过", async () => {
+  const { createHmac } = await import("node:crypto");
+  const { verifyVoiceSignature } = await import("./index.js");
+  const now = 1_760_000_000_000;
+  const sign = (token: string, timestamp: number, callId: string) => createHmac("sha256", token).update(`${timestamp}.${callId}`).digest("hex");
+  const headers = { "x-base-timestamp": String(now), "x-base-signature": sign("tok", now, "call_1") };
+  assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "tok", now }), true);
+  // Express 给的头是小写；别的框架可能保留原样大小写。
+  assert.equal(verifyVoiceSignature({ headers: { "X-Base-Timestamp": String(now), "X-Base-Signature": sign("tok", now, "call_1") }, callId: "call_1", serviceToken: "tok", now }), true);
+  assert.equal(verifyVoiceSignature({ headers, callId: "call_2", serviceToken: "tok", now }), false, "签的不是这一通");
+  assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "other", now }), false);
+  assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "tok", now: now + 6 * 60_000 }), false, "超过 5 分钟不认，防重放");
+  assert.equal(verifyVoiceSignature({ headers: {}, callId: "call_1", serviceToken: "tok", now }), false);
+  assert.equal(verifyVoiceSignature({ headers: { ...headers, "x-base-signature": "zz" }, callId: "call_1", serviceToken: "tok", now }), false);
+  assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "", now }), false, "自己没配令牌时不能放行");
+});