@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.0

package/dist/net/UploadReceiver.js

@@ -0,0 +1,494 @@
+/**
+ * 上传接收器：`asset.begin` → 若干二进制帧 → `asset.end`（architecture A11 / PRD D5、F-H8）。
+ *
+ * 三段式的分工：
+ *   1. `asset.begin`（JSON-RPC 请求）：声明用途、类型、总字节数。**超限在这里就拒**（PRD D5：
+ *      20MB/张），不接收完再说不行 —— 那既浪费带宽，也让客户端在上传中途白等一下。
+ *      素材行要按对话挂外键，所以开临时文件之前先让归属的对话落库（草稿对话在库里还没有行，
+ *      R56：落库发生在「第一次真正用到它」的那一刻，带图的第一条消息就属于这种）。
+ *   2. 任意多个二进制帧：每一帧带上「这是哪个上传」的头，字节直接追加进临时文件，不在内存里攒。
+ *   3. `asset.end`（JSON-RPC 请求）：校验总长度与客户端给的 `sha256`，通过后交给落定回调，
+ *      把临时文件变成正式素材（`<dataRoot>/assets/` 下的正式文件 + 库里一行引用）。
+ *
+ * 二进制帧的形状（`asset.chunk`）：
+ *
+ * ```
+ * | 4 字节大端无符号整数 N | N 字节 UTF-8 JSON 头 {"uploadId": "..."} | 若干字节片段 |
+ * ```
+ *
+ * 为什么头里要带 `uploadId` 而不是「一条连接同时只允许一个上传」：同一条连接上可以并发多个上传
+ * （一次拖进四张图就是四个），宿主分配的 `uploadId` 是它们之间唯一的区分方式。头做成
+ * 「长度前缀 + JSON」而不是固定长度二进制 id，是为了让帧在抓包/日志里仍然可读，也不绑定
+ * `uploadId` 的编码方式。
+ *
+ * 清理的口径（三处，都在本文件里）：
+ *   - 长度或摘要不符：删临时文件，报错；
+ *   - 连接断开 / 宿主收尾：这条连接名下所有未完成的上传按 `begin` 记下的临时文件删掉；
+ *   - 写盘出错：删临时文件，报错。
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_LANGUAGE } from "../i18n/index.js";
+import { HostError } from "../wire/errors.js";
+import { MAX_ASSET_BYTES } from "../wire/index.js";
+/** 二进制帧头部的长度字段占多少字节 */
+const HEADER_LENGTH_BYTES = 4;
+/** 头部 JSON 的长度上限（防一个坏帧声称自己有 4GB 的头） */
+const HEADER_LIMIT_BYTES = 4096;
+/** 目前只有「消息里的图片」这一种用途（PRD D5）；别的值按参数不对处理 */
+const PURPOSES = ["message_image"];
+/**
+ * MIME 的粗校验：`type/subtype`，两边都是 token 字符。
+ *
+ * 不做白名单：允许上传什么类型是「客户端让用户选什么」的事，宿主只保证这个值能被安全地
+ * 用于落盘命名与内容段（真正的类型判断在 `fileToContentSection` 那一层）。
+ */
+const MIME_PATTERN = /^[\w.+-]+\/[\w.+-]+$/;
+export class UploadReceiver {
+    assetsDir;
+    finalize;
+    onError;
+    /** 单张上限；`hello` 的 `limits` 也从这里取，两边不各写一个数 */
+    maxAssetBytes;
+    ensureConversation;
+    findExisting;
+    /** connectionId → uploadId → 进行中的上传 */
+    sessions = new Map();
+    constructor(options) {
+        this.assetsDir = options.assetsDir;
+        this.finalize = options.finalize;
+        this.maxAssetBytes = options.maxAssetBytes ?? MAX_ASSET_BYTES;
+        this.ensureConversation = options.ensureConversation;
+        this.findExisting = options.findExisting;
+        this.onError = options.onError;
+    }
+    /**
+     * `asset.begin`：校验声明、让归属的对话落库、问去重、开临时文件、发一个上传句柄。
+     *
+     * 声明里只有「总长」能验，字节本身还没到；所以这里的拒绝都是**声明层面**的
+     * （超限、类型不合法、缺对话归属、对话不存在）。
+     *
+     * 去重命中时这条路就到此为止：不建临时文件、不分配 `uploadId`。去重按内容摘要做，不区分
+     * 对话，所以命中并不证明这段对话存在 —— 「让对话落库」排在问去重之前，不存在的对话这一趟
+     * 一个字节也不会收。
+     *
+     * 「让对话落库」排在建临时文件之前：对话不存在时这一趟上传一个字节都不该落盘，
+     * 也不该占住一个 `uploadId`。`language` 是这条连接的语言，用来渲染那条隐藏的 cwd 消息。
+     */
+    async begin(connectionId, params, language = DEFAULT_LANGUAGE) {
+        const purpose = requirePurpose(params.purpose);
+        const mime = requireMime(params.mime);
+        const declaredBytes = requireDeclaredBytes(params.bytes, this.maxAssetBytes);
+        const conversationId = requireConversationId(params.conversationId);
+        const name = normalizeName(params.name);
+        const sha256 = params.sha256 === undefined ? null : normalizeDigest(params.sha256);
+        // 草稿对话在库里还没有行（R56），而「这段对话存在」是上传的前提：先落库再收字节
+        await this.persistConversation(conversationId, language);
+        // 库里已有同一份字节时只回引用：磁盘上只有一份，两段对话各自在关系表里留一行
+        const existing = sha256 === null ? null : await this.lookupExisting({ sha256, bytes: declaredBytes });
+        if (existing !== null) {
+            return {
+                deduped: true,
+                uploadId: null,
+                maxBytes: this.maxAssetBytes,
+                receivedBytes: 0,
+                asset: existing,
+            };
+        }
+        await fs.mkdir(this.assetsDir, { recursive: true });
+        const uploadId = randomUUID();
+        // 临时文件名用宿主分配的上传句柄，不用客户端给的名字：文件名不参与路径拼接之外任何判断
+        const tempPath = join(this.assetsDir, `.upload-${uploadId}.part`);
+        const handle = await fs.open(tempPath, "wx");
+        const session = {
+            uploadId,
+            connectionId,
+            purpose,
+            mime,
+            name,
+            conversationId,
+            declaredBytes,
+            tempPath,
+            handle,
+            hash: createHash("sha256"),
+            receivedBytes: 0,
+            chain: Promise.resolve(),
+            closed: false,
+        };
+        this.sessionMap(connectionId).set(uploadId, session);
+        return {
+            deduped: false,
+            uploadId,
+            maxBytes: this.maxAssetBytes,
+            receivedBytes: 0,
+            asset: null,
+        };
+    }
+    /**
+     * 一个二进制帧：解出上传句柄，把片段追加进临时文件。
+     *
+     * 返回值是这条上传目前已收到的字节数（用得上就返回，测试与调试都不必去翻文件）。
+     */
+    async receiveBinary(connectionId, frame) {
+        const { uploadId, chunk } = decodeChunkFrame(frame);
+        const session = this.sessions.get(connectionId)?.get(uploadId);
+        if (!session) {
+            throw new HostError("not_found", {
+                params: { entity: "upload" },
+                detail: { uploadId, reason: "unknown_upload_id" },
+            });
+        }
+        return await this.append(session, chunk);
+    }
+    /**
+     * `asset.end`：等写盘排空、关文件、校验长度与摘要，通过后落定。
+     *
+     * 校验不过时的顺序是「先删文件、再报错」：报错之后这条上传就没有别的出口了，
+     * 留着半个文件只会变成没人认领的垃圾。
+     */
+    async end(connectionId, params) {
+        const uploadId = requireUploadId(params.uploadId);
+        const session = this.sessions.get(connectionId)?.get(uploadId);
+        if (!session) {
+            throw new HostError("not_found", {
+                params: { entity: "upload" },
+                detail: { uploadId, reason: "unknown_upload_id" },
+            });
+        }
+        // 还有分片在写：等它们落完再验，否则长度会少算
+        await session.chain;
+        await this.closeHandle(session);
+        this.detach(session);
+        if (session.receivedBytes !== session.declaredBytes) {
+            await this.discard(session);
+            throw new HostError("invalid_params", {
+                detail: {
+                    reason: "size_mismatch",
+                    uploadId,
+                    declaredBytes: session.declaredBytes,
+                    receivedBytes: session.receivedBytes,
+                },
+            });
+        }
+        const digest = session.hash.digest("hex");
+        const expected = normalizeDigest(params.sha256);
+        if (digest !== expected) {
+            await this.discard(session);
+            throw new HostError("invalid_params", {
+                detail: { reason: "digest_mismatch", uploadId, expected, actual: digest },
+            });
+        }
+        try {
+            const asset = await this.finalize({
+                uploadId,
+                tempPath: session.tempPath,
+                mime: session.mime,
+                bytes: session.receivedBytes,
+                sha256: digest,
+                name: session.name,
+                purpose: session.purpose,
+                conversationId: session.conversationId,
+            });
+            return { asset };
+        }
+        catch (error) {
+            // 落定失败（改名失败、登记失败）：临时文件留着没有意义，删掉再往上抛
+            await this.discard(session);
+            throw error;
+        }
+    }
+    /**
+     * 丢掉一条连接名下所有未完成的上传（连接断开时调）。
+     *
+     * 这是「中途断开按 `begin` 记的临时文件清理」的落点。清理本身失败只报给 `onError`：
+     * 连接已经没了，没有谁在等一个失败结果。
+     */
+    async abortConnection(connectionId) {
+        const sessions = this.sessions.get(connectionId);
+        if (!sessions)
+            return;
+        this.sessions.delete(connectionId);
+        for (const session of sessions.values()) {
+            session.closed = true;
+            await this.closeHandle(session);
+            await this.discard(session);
+        }
+    }
+    /** 宿主收尾：把所有连接的上传都清掉 */
+    async dispose() {
+        const connectionIds = [...this.sessions.keys()];
+        for (const connectionId of connectionIds) {
+            await this.abortConnection(connectionId);
+        }
+    }
+    /** 这条连接上还有几个未完成的上传（测试与诊断用） */
+    pendingCount(connectionId) {
+        if (connectionId !== undefined)
+            return this.sessions.get(connectionId)?.size ?? 0;
+        let total = 0;
+        for (const sessions of this.sessions.values())
+            total += sessions.size;
+        return total;
+    }
+    // -------------------------------------------------------------------------
+    // 内部
+    // -------------------------------------------------------------------------
+    /**
+     * 让这段对话先成为库里的行（幂等由注入方保证）。
+     *
+     * 业务错误（`not_found` 之类）原样上抛：客户端要按码说人话，不能让「对话不存在」在出网时
+     * 变成一句 internal。其余异常（写库失败这类）收敛成 `internal` 并留一个原因，原始错误同时
+     * 交给 `onError` 进日志。
+     */
+    async persistConversation(conversationId, language) {
+        const ensure = this.ensureConversation;
+        if (!ensure)
+            return;
+        try {
+            await ensure(conversationId, language);
+        }
+        catch (error) {
+            if (HostError.is(error))
+                throw error;
+            this.onError?.(error, "让对话落库失败");
+            throw new HostError("internal", {
+                detail: { reason: "conversation_persist_failed", conversationId },
+                cause: error,
+            });
+        }
+    }
+    sessionMap(connectionId) {
+        let sessions = this.sessions.get(connectionId);
+        if (!sessions) {
+            sessions = new Map();
+            this.sessions.set(connectionId, sessions);
+        }
+        return sessions;
+    }
+    /**
+     * 问一句「库里有没有同一份字节」。
+     *
+     * 查询本身失败时当作「没命中」：去重是省一次上传的优化，不能因为它的存储出错就把整个上传拒掉。
+     */
+    async lookupExisting(input) {
+        const find = this.findExisting;
+        if (!find)
+            return null;
+        try {
+            return await find(input);
+        }
+        catch (error) {
+            this.onError?.(error, "查询重复素材失败");
+            return null;
+        }
+    }
+    detach(session) {
+        const sessions = this.sessions.get(session.connectionId);
+        sessions?.delete(session.uploadId);
+        if (sessions && sessions.size === 0)
+            this.sessions.delete(session.connectionId);
+    }
+    /** 追加一片：排在上一片之后写，累积摘要与已收字节数 */
+    append(session, chunk) {
+        const next = session.chain.then(async () => {
+            if (session.closed) {
+                throw new HostError("not_found", {
+                    params: { entity: "upload" },
+                    detail: { uploadId: session.uploadId, reason: "upload_closed" },
+                });
+            }
+            if (chunk.byteLength === 0)
+                return session.receivedBytes;
+            // 先算长度再写：超过声明总长的分片不留痕（临时文件随后整份删掉）
+            const nextBytes = session.receivedBytes + chunk.byteLength;
+            if (nextBytes > session.declaredBytes) {
+                session.closed = true;
+                this.detach(session);
+                await this.closeHandle(session);
+                await this.discard(session);
+                throw new HostError("payload_too_large", {
+                    params: {
+                        size: formatBytes(nextBytes),
+                        limit: formatBytes(session.declaredBytes),
+                    },
+                    detail: {
+                        reason: "exceeds_declared_bytes",
+                        uploadId: session.uploadId,
+                        declaredBytes: session.declaredBytes,
+                        receivedBytes: nextBytes,
+                    },
+                });
+            }
+            await session.handle.write(chunk);
+            session.hash.update(chunk);
+            session.receivedBytes = nextBytes;
+            return session.receivedBytes;
+        });
+        // 链条只用来排队：某一片失败不该把后面的分片也判成失败（它们各自会报自己的错）
+        session.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async closeHandle(session) {
+        await session.handle.close().catch((error) => {
+            this.onError?.(error, "关闭上传临时文件失败");
+        });
+    }
+    /** 删临时文件（不存在不算错：清理动作要能重复执行） */
+    async discard(session) {
+        session.closed = true;
+        await fs.rm(session.tempPath, { force: true }).catch((error) => {
+            this.onError?.(error, "删除上传临时文件失败");
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// 二进制帧
+// ---------------------------------------------------------------------------
+/**
+ * 拼一个 `asset.chunk` 二进制帧（客户端按同一份实现编码，测试也用它）。
+ *
+ * 导出它是为了让「帧长什么样」只有一处定义：客户端与宿主各写一份编码器迟早会错开一个字段。
+ */
+export function encodeChunkFrame(uploadId, chunk) {
+    const header = new TextEncoder().encode(JSON.stringify({ uploadId }));
+    const frame = new Uint8Array(HEADER_LENGTH_BYTES + header.byteLength + chunk.byteLength);
+    new DataView(frame.buffer).setUint32(0, header.byteLength, false);
+    frame.set(header, HEADER_LENGTH_BYTES);
+    frame.set(chunk, HEADER_LENGTH_BYTES + header.byteLength);
+    return frame;
+}
+/**
+ * 解一个 `asset.chunk` 二进制帧。
+ *
+ * 坏帧一律 `invalid_params` 并带 `detail.reason`：帧是二进制的，客户端拼错时唯一能帮上忙的
+ * 就是「哪一步不对」（头长度越界、头不是 JSON、头里没有 `uploadId`）。
+ */
+export function decodeChunkFrame(frame) {
+    if (frame.byteLength < HEADER_LENGTH_BYTES) {
+        throw new HostError("invalid_params", {
+            detail: { reason: "frame_too_short", bytes: frame.byteLength },
+        });
+    }
+    const headerLength = new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(0, false);
+    if (headerLength === 0 || headerLength > HEADER_LIMIT_BYTES) {
+        throw new HostError("invalid_params", {
+            detail: { reason: "bad_header_length", headerLength },
+        });
+    }
+    if (HEADER_LENGTH_BYTES + headerLength > frame.byteLength) {
+        throw new HostError("invalid_params", {
+            detail: {
+                reason: "truncated_header",
+                headerLength,
+                bytes: frame.byteLength - HEADER_LENGTH_BYTES,
+            },
+        });
+    }
+    const headerBytes = frame.subarray(HEADER_LENGTH_BYTES, HEADER_LENGTH_BYTES + headerLength);
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(headerBytes));
+    }
+    catch {
+        throw new HostError("invalid_params", { detail: { reason: "header_not_json" } });
+    }
+    if (typeof header !== "object" || header === null || Array.isArray(header)) {
+        throw new HostError("invalid_params", { detail: { reason: "header_not_an_object" } });
+    }
+    const uploadId = header.uploadId;
+    if (typeof uploadId !== "string" || uploadId.trim() === "") {
+        throw new HostError("invalid_params", { detail: { reason: "header_without_upload_id" } });
+    }
+    return { uploadId: uploadId.trim(), chunk: frame.subarray(HEADER_LENGTH_BYTES + headerLength) };
+}
+// ---------------------------------------------------------------------------
+// 参数校验与格式化
+// ---------------------------------------------------------------------------
+function requirePurpose(value) {
+    if (typeof value === "string" && PURPOSES.includes(value)) {
+        return value;
+    }
+    throw new HostError("invalid_params", {
+        params: { field: "purpose" },
+        detail: { field: "purpose", got: value ?? null, allowed: PURPOSES },
+    });
+}
+function requireMime(value) {
+    if (typeof value === "string" && MIME_PATTERN.test(value.trim())) {
+        return value.trim().toLowerCase();
+    }
+    throw new HostError("invalid_params", {
+        params: { field: "mime" },
+        detail: { field: "mime", got: value ?? null },
+    });
+}
+function requireDeclaredBytes(value, limit) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new HostError("invalid_params", {
+            params: { field: "bytes" },
+            detail: { field: "bytes", got: value ?? null, reason: "not_a_positive_integer" },
+        });
+    }
+    if (value > limit) {
+        throw new HostError("payload_too_large", {
+            params: { size: formatBytes(value), limit: formatBytes(limit) },
+            detail: { reason: "over_asset_limit", bytes: value, limit },
+        });
+    }
+    return value;
+}
+/**
+ * 上传必须归属一段对话。
+ *
+ * `asset.begin` 要这段对话在库里存在（草稿先落库），因为素材的引用关系（`conversation_assets`）
+ * 与「图片按引用清理」都按对话走；没有归属的上传只能留下一个没人认领的文件。所以这里直接拒
+ * （而不是先收完再失败）。
+ */
+function requireConversationId(value) {
+    if (typeof value === "string" && value.trim() !== "")
+        return value.trim();
+    throw new HostError("invalid_params", {
+        params: { field: "conversationId" },
+        detail: { field: "conversationId", reason: "conversation_required" },
+    });
+}
+function requireUploadId(value) {
+    if (typeof value === "string" && value.trim() !== "")
+        return value.trim();
+    throw new HostError("invalid_params", {
+        params: { field: "uploadId" },
+        detail: { field: "uploadId", reason: "missing_upload_id" },
+    });
+}
+function normalizeName(value) {
+    if (typeof value !== "string")
+        return null;
+    const name = value.trim();
+    return name === "" ? null : name;
+}
+function normalizeDigest(value) {
+    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value.trim())) {
+        throw new HostError("invalid_params", {
+            params: { field: "sha256" },
+            detail: { field: "sha256", reason: "not_a_sha256_digest" },
+        });
+    }
+    return value.trim().toLowerCase();
+}
+/**
+ * 字节数的人话形式（错误文案里的 `{size}` / `{limit}`）。
+ *
+ * 单位用 1024 进制、最多一位小数：`20 MB`、`8.5 MB`、`512 KB` —— 与用户看到文件大小时的口径一致。
+ */
+export function formatBytes(bytes) {
+    const units = ["B", "KB", "MB", "GB"];
+    let value = Math.max(0, bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const rounded = unit === 0 ? Math.round(value) : Math.round(value * 10) / 10;
+    return `${rounded} ${units[unit]}`;
+}