pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/build/src/socket.js

@@ -0,0 +1,496 @@
+/**
+ * `src/socket.ts` —— 跨进程实时传输通道（M4b：unix domain socket）。
+ *
+ * 协议（plan §5.6）：
+ * - 端点：`<agentDir>/proactive/run/<agentId>.sock`（文件名安全化：`/`、`\`、`#`、空白 → `-`）；
+ * - 帧：**JSONL**，一行一条 JSON 信封；回执也是一个 JSON 行（ack 帧）；
+ * - 语义：socket 能连上 = 在线（比心跳更实时）；连不上 → 调用方降级落盘（`src/outbox.ts`）。
+ *
+ * ack 状态（服务端产生）：
+ * - `accepted`：信封合法、未过期、未重复，且已交给 `onMessage` 处理；
+ * - `duplicate`：id 已在接收侧 seen 集合里 → **不重复处理**；
+ * - `expired`：年龄 >= ttlMs → 不处理；
+ * - `rejected`：帧不是合法 JSON，或信封校验不过；
+ * - `error`：`onMessage` 抛错（异常隔离：server 继续存活）。
+ *
+ * 客户端产生：
+ * - `unreachable`：端点不存在 / 无进程监听；
+ * - `timeout`：连接上了但没等到 ack（**必须断开销毁 socket**，不得无限等待、不得泄漏 fd）。
+ *
+ * 唯一投递入口：`deliverCrossProcess()`（socket 优先 → 不可达则降级落盘 → 异常返回 error）。
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { PROACTIVE_FILE_MODE, chmodStrict, ensureDir, proactiveDir } from "./config.js";
+import { isExpired, isWellFormedId, validateEnvelopeStrict } from "./envelope.js";
+import { archiveUnverifiedEnvelope } from "./mailbox.js";
+import { writeToMailbox } from "./outbox.js";
+/** 合法 ack 状态全集（= `docs/a2a/ack.schema.json` 的 status 枚举）。 */
+export const ACK_STATUSES = [
+    "accepted",
+    "duplicate",
+    "expired",
+    "rejected",
+    "error",
+    "unreachable",
+    "queued",
+    "timeout",
+];
+/** 客户端默认 ack 超时（ms）。 */
+export const DEFAULT_SOCKET_TIMEOUT_MS = 2_000;
+/**
+ * **单帧上限（字节）** —— 本地 IPC 攻击面：超大 body 打爆对端。
+ *
+ * 取 256 KiB（与 `MAX_ENVELOPE_BYTES` 一致）：超过即**拒收**（回执 `rejected`）并断开该连接，
+ * **不**把整帧读进内存再判断。
+ */
+export const MAX_FRAME_BYTES = 256 * 1024;
+/**
+ * **单连接最多处理的帧数** —— 洪水攻击上限。
+ *
+ * 超过即断开连接（对端要么重连、要么换招；本端不会被单条连接无限灌）。
+ */
+export const DEFAULT_MAX_FRAMES_PER_CONNECTION = 500;
+/** socket 文件名安全化：路径分隔符、`#`、空白 → `-`（`#` 在 agentId 里是字段分隔符）。 */
+export function sanitizeSocketFileName(agentId) {
+    return agentId.replace(/[/\\#\s]/g, "-") || "unknown";
+}
+/**
+ * 端点路径长度上限（**字节**）。
+ *
+ * unix socket 的 `sun_path` 上限约 **104**（macOS，含结尾 NUL）/ **108**（Linux）；
+ * 取 **100** 留余量。超限 → 端点文件名按 {@link hashedSocketFileName} 降级。
+ *
+ * 与参考对端 `reference-peer/peer.py` 的 `MAX_SOCKET_PATH_BYTES` **逐字一致**（两侧必须推出同一路径）。
+ */
+export const MAX_SOCKET_PATH_BYTES = 100;
+/**
+ * G-R5 降级端点名：`h-<sha256(agentId) 的十六进制前 16 位>`。
+ *
+ * 规则只依赖 **agentId 原文** → 客户端（按目标 agentId 推导）与服务端（按自己的 agentId 推导）
+ * 必然推出同一个文件名。
+ */
+export function hashedSocketFileName(agentId) {
+    return `h-${createHash("sha256").update(agentId, "utf8").digest("hex").slice(0, 16)}`;
+}
+/**
+ * 本 agent 的 socket 端点绝对路径。
+ *
+ * **G-R5 长度降级**：常规名 `<sanitized(agentId)>.sock`；若**完整路径的字节长度**超过
+ * {@link MAX_SOCKET_PATH_BYTES} → 文件名降级为 `<hashedSocketFileName(agentId)>.sock`。
+ * 判定只依赖 (agentId, agentDir)，与环境/时序无关 → 客户端与服务端推出同一个路径。
+ */
+export function socketPathFor(agentId, agentDir) {
+    const runDir = path.join(proactiveDir(agentDir), "run");
+    const natural = path.join(runDir, `${sanitizeSocketFileName(agentId)}.sock`);
+    if (Buffer.byteLength(natural, "utf8") <= MAX_SOCKET_PATH_BYTES)
+        return natural;
+    return path.join(runDir, `${hashedSocketFileName(agentId)}.sock`);
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * 启动 socket server。
+ *
+ * 启动前若端点路径已存在 → 先连接探测：连得上 = 对方还活着 → **抛错「端点已被占用」**；
+ * 连不上（僵尸端点）→ unlink 后重建。
+ */
+export async function startSocketServer(opts) {
+    if (typeof opts.senderPolicy !== "function") {
+        // **缺省即抛错**（不静默宽松）：来源校验是安全边界，漏传 = 悄悄关掉它。
+        throw new Error("startSocketServer 必须显式指定 senderPolicy（缺省即抛错）：" +
+            "createStrictSenderPolicy()（注册表白名单 ＋ 主机一致）或 " +
+            "createSpecSenderPolicy()（仅字段级校验；跨机 / 互操作用）");
+    }
+    const sockPath = socketPathFor(opts.agentId, opts.agentDir);
+    // G-R5：降级后仍超长（agentDir 本身过长）→ 明确报错，不让 bind 抛一个看不懂的 EINVAL。
+    if (Buffer.byteLength(sockPath, "utf8") > MAX_SOCKET_PATH_BYTES) {
+        throw new Error(`端点路径超长（降级后仍超过 ${MAX_SOCKET_PATH_BYTES} 字节）：${sockPath} —— 请缩短 agentDir 或 agentId`);
+    }
+    // 端点目录：0700（显式 chmod；umask 只削弱、既有目录不会改）。
+    ensureDir(path.dirname(sockPath));
+    if (fs.existsSync(sockPath)) {
+        if (await isEndpointAlive(sockPath)) {
+            throw new Error(`端点已被占用：${sockPath}（已有进程在监听）`);
+        }
+        try {
+            fs.unlinkSync(sockPath);
+        }
+        catch (e) {
+            throw new Error(`僵尸端点清理失败：${sockPath}：${errMsg(e)}`);
+        }
+    }
+    // 跟踪所有已接受的连接：**close() 必须先毁掉它们**（见 closeServer 的注释）。
+    const sockets = new Set();
+    const server = net.createServer((sock) => {
+        sockets.add(sock);
+        sock.once("close", () => sockets.delete(sock));
+        handleConnection(sock, opts);
+    });
+    let settled = false;
+    await new Promise((resolve, reject) => {
+        const onError = (e) => {
+            if (settled)
+                return;
+            settled = true;
+            // 监听失败：把 server 关掉，避免留下一个永远不 listen 的 handle（挂死风险）
+            try {
+                server.close();
+            }
+            catch {
+                // 忽略
+            }
+            reject(e);
+        };
+        server.once("error", onError);
+        server.listen(sockPath, () => {
+            settled = true;
+            // 端点文件：0600（显式 chmod）。**收紧失败不得静默放行** → 关掉 server 并抛错
+            // （宁可没有 socket 通道，也不留一个其它同 UID 进程能接入的端点）。
+            try {
+                chmodStrict(sockPath, PROACTIVE_FILE_MODE);
+            }
+            catch (e) {
+                try {
+                    server.close();
+                }
+                catch {
+                    // 忽略
+                }
+                throw new Error(`端点权限收紧失败（${PROACTIVE_FILE_MODE.toString(8)}）：${sockPath}：${errMsg(e)}`);
+            }
+            server.removeListener("error", onError);
+            // 监听后的错误不再 reject：吞掉，避免 uncaughtException 打死宿主进程（plan §5.15）
+            server.on("error", () => { });
+            resolve();
+        });
+    });
+    return {
+        path: sockPath,
+        agentId: opts.agentId,
+        close: () => closeServer(server, sockPath, sockets),
+    };
+}
+/**
+ * 关闭 server 并清理端点文件（幂等）。
+ *
+ * **挂死根因（务必保留这两步）**：`server.close(cb)` 的回调只有在**所有连接都结束之后**才触发。
+ * 只要还有一条客户端连接挂着（例如客户端没 destroy、或对端只是连上不回 ack），
+ * `close()` 就永不返回 → `await server.close()` 永不返回 → event loop 里留着 open handle →
+ * **node 进程永不退出**（`--test-timeout` 只能中止用例，不能结束进程）。
+ * 因此：
+ * 1. 先 `destroy()` 全部已接受的连接（让它立刻进入 closed 状态）；
+ * 2. `server.close(cb)` 外再套一层**硬超时兜底**，保证 close() 在任何情况下都返回。
+ */
+export async function closeServer(server, sockPath, sockets) {
+    for (const sock of sockets) {
+        try {
+            sock.destroy();
+        }
+        catch {
+            // 忽略：销毁失败也不能让 close 卡住
+        }
+    }
+    sockets.clear();
+    await new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        server.close(() => finish());
+        // 兜底：万一有连接在竞态窗口里被接受，close 也必须在 1s 内返回。
+        //
+        // 注意：**不得**调用 `server.closeAllConnections()` —— 那是 `http.Server` 的方法，
+        // `net.Server` 没有（调用即 TypeError；TS 也会报 TS2339，合并门禁 G1 因此 FAIL）。
+        // 兜底只能依赖**已跟踪的连接集**（再次 destroy）+ `server.close(cb)` + 定时器强制 resolve。
+        const guard = setTimeout(() => {
+            for (const sock of sockets) {
+                try {
+                    sock.destroy();
+                }
+                catch {
+                    // 忽略：销毁失败也不能让 close 卡住
+                }
+            }
+            finish();
+        }, 1_000);
+        guard.unref?.();
+    });
+    try {
+        fs.unlinkSync(sockPath);
+    }
+    catch {
+        // 文件已不在（node 关闭时会自己删）→ 忽略
+    }
+}
+/** 探测端点是否有人监听（连得上 = 活着）。 */
+function isEndpointAlive(sockPath) {
+    return new Promise((resolve) => {
+        const sock = net.createConnection({ path: sockPath });
+        let done = false;
+        const finish = (alive) => {
+            if (done)
+                return;
+            done = true;
+            try {
+                sock.destroy();
+            }
+            catch {
+                // 忽略
+            }
+            resolve(alive);
+        };
+        sock.once("connect", () => finish(true));
+        sock.once("error", () => finish(false));
+    });
+}
+/** 每条连接：按 JSONL 逐行读，单行解析/处理异常不影响 server。 */
+function handleConnection(sock, opts) {
+    sock.setEncoding("utf8");
+    let buffer = "";
+    let frames = 0;
+    const maxFrames = opts.maxFramesPerConnection ?? DEFAULT_MAX_FRAMES_PER_CONNECTION;
+    sock.on("data", (chunk) => {
+        buffer += chunk;
+        // **帧体积上限**：缓冲里还没有换行且已超上限 → 拒收并断开（不把超大帧读进内存）。
+        if (buffer.length > MAX_FRAME_BYTES && !buffer.includes("\n")) {
+            console.error(`[socket] 帧超过上限（${MAX_FRAME_BYTES} 字节）→ 断开连接（拒收）`);
+            try {
+                sock.destroy();
+            }
+            catch {
+                // 忽略
+            }
+            return;
+        }
+        let idx = buffer.indexOf("\n");
+        while (idx >= 0) {
+            const line = buffer.slice(0, idx).trim();
+            buffer = buffer.slice(idx + 1);
+            if (line) {
+                frames += 1;
+                // **洪水上限**：单连接帧数超限 → 断开（对端不能靠一条连接无限灌）。
+                if (frames > maxFrames) {
+                    console.error(`[socket] 单连接帧数超过上限（${maxFrames}）→ 断开连接`);
+                    try {
+                        sock.destroy();
+                    }
+                    catch {
+                        // 忽略
+                    }
+                    return;
+                }
+                void handleFrame(sock, line, opts);
+            }
+            idx = buffer.indexOf("\n");
+        }
+    });
+    sock.on("error", () => {
+        // 连接层错误（对端断开等）不影响 server
+    });
+}
+/** 处理一帧：解析 → 校验 → 去重 → 过期 → 处理 → 回 ack。整体 try/catch（异常隔离）。 */
+async function handleFrame(sock, line, opts) {
+    let ack;
+    try {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            ack = { status: "rejected", error: "帧不是合法 JSON" };
+            writeAck(sock, ack);
+            return;
+        }
+        const validation = validateEnvelopeStrict(parsed);
+        if (!validation.ok) {
+            ack = { status: "rejected", error: validation.error };
+            writeAck(sock, ack);
+            return;
+        }
+        const msg = validation.envelope;
+        // **id 结构性合法性**（路径穿越形状）→ 拒收。
+        if (!isWellFormedId(msg.id)) {
+            ack = { status: "rejected", error: `信封 id 非法（可能用于路径穿越）：${msg.id}` };
+            writeAck(sock, ack);
+            return;
+        }
+        // **体积上限**（超大 body 攻击）：超限 → 拒收（不投递、不读进后续处理）。
+        if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+            ack = { status: "rejected", error: `信封超过体积上限（${MAX_FRAME_BYTES} 字节）` };
+            writeAck(sock, ack);
+            return;
+        }
+        // **来源校验（RELSEC P1）**：`from` 不可自填即采信。
+        // 未通过 → **拒收**（**不调用 onMessage**）+ 可审计归档（绝不「降级为 advisory 照样投递」）。
+        const verdict = opts.senderPolicy(msg);
+        if (!verdict.ok) {
+            archiveUnverifiedEnvelope({
+                agentDir: opts.agentDir,
+                agentId: opts.agentId,
+                envelope: msg,
+                reason: verdict.reason,
+                error: verdict.error,
+                at: opts.now?.() ?? Date.now(),
+            });
+            ack = { status: "rejected", id: msg.id, error: verdict.error };
+            writeAck(sock, ack);
+            return;
+        }
+        if (opts.seen && opts.seen.seen(msg.id)) {
+            ack = { status: "duplicate", id: msg.id };
+            writeAck(sock, ack);
+            return;
+        }
+        if (isExpired(msg, opts.now?.())) {
+            ack = { status: "expired", id: msg.id };
+            writeAck(sock, ack);
+            return;
+        }
+        await opts.onMessage(msg);
+        if (opts.seen)
+            opts.seen.mark(msg.id);
+        ack = { status: "accepted", id: msg.id };
+    }
+    catch (e) {
+        ack = { status: "error", error: errMsg(e) };
+    }
+    writeAck(sock, ack);
+}
+/** 写回 ack 帧（一行 JSON）。 */
+function writeAck(sock, ack) {
+    try {
+        sock.write(`${JSON.stringify(ack)}\n`);
+    }
+    catch {
+        // 对端已断开 → 忽略
+    }
+}
+/**
+ * 通过 socket 直投一封信封并等待 ack。
+ *
+ * **绝不抛错、绝不无限等待**：端点不可达 → `unreachable`；超时 → `timeout`（并销毁 socket，
+ * 不泄漏 fd）；其它异常 → `error`。
+ */
+export function sendViaSocket(targetSocketPath, envelope, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_SOCKET_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let settled = false;
+        const sock = net.createConnection({ path: targetSocketPath });
+        const finish = (ack) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                sock.destroy();
+            }
+            catch {
+                // 忽略
+            }
+            resolve(ack);
+        };
+        const timer = setTimeout(() => {
+            finish({ status: "timeout", error: `ack 超时（${timeoutMs}ms）` });
+        }, timeoutMs);
+        // 超时定时器不该拖住进程退出
+        timer.unref?.();
+        let buffer = "";
+        sock.on("connect", () => {
+            try {
+                sock.write(`${JSON.stringify(envelope)}\n`);
+            }
+            catch (e) {
+                finish({ status: "error", error: errMsg(e) });
+            }
+        });
+        sock.on("data", (chunk) => {
+            buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            const idx = buffer.indexOf("\n");
+            if (idx < 0)
+                return;
+            const line = buffer.slice(0, idx).trim();
+            if (!line)
+                return;
+            try {
+                const parsed = JSON.parse(line);
+                // D1（偏差 B-9）：**status 必须按 AckStatus 枚举校验** —— 非法值（缺失 / 越界 /
+                // 非字符串）一律判 `error`，**绝不原样透出**（否则调用方会走到未定义分支）。
+                const raw = parsed.status;
+                if (typeof raw !== "string" || !ACK_STATUSES.includes(raw)) {
+                    finish({
+                        status: "error",
+                        error: `invalid-ack-status：${JSON.stringify(raw ?? null)}（允许 ${ACK_STATUSES.join("|")}）`,
+                    });
+                    return;
+                }
+                finish({
+                    status: raw,
+                    ...(parsed.id !== undefined ? { id: parsed.id } : {}),
+                    ...(parsed.error !== undefined ? { error: parsed.error } : {}),
+                });
+            }
+            catch (e) {
+                finish({ status: "error", error: `ack 帧解析失败：${errMsg(e)}` });
+            }
+        });
+        sock.on("error", (e) => {
+            const code = e.code;
+            // EINVAL = 端点路径过长/非法（macOS unix socket 路径上限 ~104 字符）→ 同样连不上 → 降级落盘。
+            if (code === "ENOENT" ||
+                code === "ECONNREFUSED" ||
+                code === "ENOTSOCK" ||
+                code === "ECONNRESET" ||
+                code === "EINVAL") {
+                finish({ status: "unreachable", error: errMsg(e) });
+                return;
+            }
+            finish({ status: "error", error: errMsg(e) });
+        });
+        sock.on("close", () => {
+            finish({ status: "unreachable", error: "连接已关闭，未收到 ack" });
+        });
+    });
+}
+/**
+ * 跨进程投递的**唯一入口**（M5 / M4c 复用）：
+ * 1. 校验信封 —— 非法直接 `rejected`；
+ * 2. socket 直投 —— 拿到 ack（accepted/duplicate/rejected/expired）原样返回；
+ * 3. 不可达（unreachable）或超时（timeout）→ **降级落盘**到对方邮箱目录，返回 `queued`
+ *    （注意：**不是** delivered —— 消息还在待对方上线）；
+ * 4. 任何异常 → 返回 `error`，**不抛**。
+ */
+export async function deliverCrossProcess(opts) {
+    try {
+        const validation = validateEnvelopeStrict(opts.envelope);
+        if (!validation.ok) {
+            return { status: "rejected", error: validation.error };
+        }
+        const msg = validation.envelope;
+        if (opts.seen && opts.seen.seen(msg.id)) {
+            return { status: "duplicate", id: msg.id };
+        }
+        const targetPath = socketPathFor(opts.targetAgentId, opts.agentDir);
+        const ack = await sendViaSocket(targetPath, msg, { timeoutMs: opts.timeoutMs });
+        if (ack.status === "unreachable" || ack.status === "timeout") {
+            const file = writeToMailbox(opts.targetAgentId, msg, { agentDir: opts.agentDir });
+            if (opts.seen)
+                opts.seen.mark(msg.id);
+            return { status: "queued", id: msg.id, path: file };
+        }
+        if (ack.status === "accepted" || ack.status === "duplicate") {
+            if (opts.seen)
+                opts.seen.mark(msg.id);
+        }
+        return ack;
+    }
+    catch (e) {
+        return { status: "error", error: errMsg(e) };
+    }
+}