@ntdgy/dsh-remote-bridge-plugin 0.0.0-stage → 0.1.1

package/lib/relay/client.js

@@ -0,0 +1,825 @@
+/**
+ * 出站 WebSocket 客户端。
+ *
+ * 关键约束：
+ *   - 只有 DSH 主动拨出，网关永不主动连入（约束 C1）
+ *   - 指数退避重连，上限可配；stop() 必须清理 timer
+ *   - 凭据不进 URL 查询串，握手后第一帧带（见 ADR-003）
+ *   - 入站方向**只接受 RpcRequest**；帧（kind:'frame'）由实例发往浏览器，
+ *     反向任何帧一律丢弃并计数（ADR-004 纪律 1）
+ */
+import { createHmac } from 'node:crypto';
+import WebSocket from 'ws';
+import { classifyWireMessage, encodeHttpBodyFrame, decodeHttpBodyFrame, decodeWsDataFrame, } from '@ntdgy/dsh-remote-proto';
+import { RpcError } from "./errors.js";
+/** WS ping 间隔；一个间隔内没收到 pong 即判死连接。 */
+const PING_INTERVAL_MS = 15_000;
+/**
+ * 挑战应答的签名载荷。
+ *
+ * `nonce:instanceId:timestamp` —— instanceId 与 timestamp 都进签名，防止：
+ *   - 拿 A 实例的应答去冒充 B 实例（instanceId 不同则签名不同）；
+ *   - 重放旧应答（timestamp 由本端自带，配合网关的 nonce 一次性消费与 TTL）。
+ *
+ * 与网关 AgentAuth.verify 的既有实现对同一载荷格式，签名语义两侧必须逐字一致。
+ */
+function signChallenge(instanceKey, nonce, instanceId, timestamp) {
+    return createHmac('sha256', instanceKey)
+        .update(`${nonce}:${instanceId}:${timestamp}`)
+        .digest('base64url');
+}
+/**
+ * 把一个抛出的值格式化成**可指认**的一行文案。
+ *
+ * 目标：让同一故障在任何观测路径下产出同一段文字，且带上 name 与 cause 链，
+ * 而不是退化成裸的 "Cannot read properties of undefined"。
+ */
+function describeError(value) {
+    if (!(value instanceof Error))
+        return String(value);
+    const parts = [];
+    const name = value.name === 'Error' ? '' : value.name;
+    parts.push(name === '' ? value.message : `${name}: ${value.message}`);
+    const code = value.code;
+    if (typeof code === 'string' && !parts[0].includes(code))
+        parts.push(`(code=${code})`);
+    // cause 链最多展开 3 层：够指认来源，又不至于把响应体撑爆。
+    let cause = value.cause;
+    for (let depth = 0; depth < 3 && cause !== undefined; depth += 1) {
+        if (cause instanceof Error) {
+            parts.push(`<- ${cause.name === 'Error' ? cause.message : `${cause.name}: ${cause.message}`}`);
+            cause = cause.cause;
+        }
+        else {
+            parts.push(`<- ${String(cause)}`);
+            break;
+        }
+    }
+    return parts.join(' ');
+}
+export function checkRelayUrlScheme(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { fatalReason: `relayUrl is not a valid URL: ${url}` };
+    }
+    if (parsed.protocol === 'wss:')
+        return {};
+    if (parsed.protocol === 'ws:') {
+        return {
+            insecureReason: 'relayUrl uses ws:// (plaintext): the HMAC handshake can be bypassed by a ' +
+                'man-in-the-middle. Acceptable only behind a local TLS terminator or in local testing.',
+        };
+    }
+    return { fatalReason: `relayUrl must be ws:// or wss://, got ${parsed.protocol}` };
+}
+/** 插件实际实现的 method 子集；白名单全量在 proto，这里只报"我支持这些"。 */
+const ADVERTISED_METHODS = [
+    'session.list',
+    'session.history',
+    'session.prompt',
+    'session.follow',
+];
+/**
+ * WS 建连（TCP + HTTP Upgrade）超时。
+ *
+ * 为什么必须有：对端如果是 **TCP 黑洞**（丢包而非回 RST），内核握手会一直重传，
+ * ws 的 open/error/close **一个都不触发**，socket 永久停在 CONNECTING。
+ * 那样退避重连根本不会被调度（它挂在 close 事件上），整条链路静默死锁——
+ * 表现为"插件在跑，但网关永远收不到 hello"。
+ *
+ * 15s：覆盖跨洲 RTT + TLS 握手的正常上限，又短于网关 45s 的心跳巡检窗口，
+ * 保证一次坏连接不会拖过一个巡检周期。
+ */
+const WS_HANDSHAKE_TIMEOUT_MS = 15_000;
+/**
+ * 发送缓冲的水位阈值（字节）。
+ *
+ * 选值依据（不是拍脑袋）：
+ *   - 单个 HTTP 响应体上限 HTTP_BODY_MAX_BYTES = 32MB，一帧最大也就这个量级；
+ *   - 软上限 8MB ≈ 正常突发（若干并发小响应 + 帧流）的几倍，不该误报；
+ *   - 硬上限 64MB ≈ 两个满额响应体。到这一步网关显然已经不读了，
+ *     再写就是纯粹的内存燃烧，断连比继续灌更负责。
+ *
+ * 用 bufferedAmount（ws 暴露的内核+userland 待发字节数）作为唯一判据，
+ * 不自己维护计数器——那会在重连/多路复用时与实际不同步。
+ */
+const SEND_BUFFER_SOFT_LIMIT_BYTES = 8 * 1024 * 1024;
+const SEND_BUFFER_HARD_LIMIT_BYTES = 64 * 1024 * 1024;
+/**
+ * 同时在途的入站 HTTP 请求上限。
+ *
+ * 为什么要有：`void this.onHttpRequest(...)` 是无上限并发派发。
+ * 每个在途请求最终都会 produce 一个最大 32MB 的响应体，且都要排队经过上面那个发送缓冲。
+ * 恶意或故障网关只要狂发 http-request 就能让本进程同时持有几十份大 buffer。
+ *
+ * 32：按 32MB 上限算，最坏 1GB 上下，仍是可控量级；正常面板的并发远低于此。
+ */
+const MAX_INFLIGHT_HTTP_REQUESTS = 32;
+export class RelayClient {
+    socket;
+    timer;
+    heartbeatTimer;
+    /** WS ping/pong 存活探测的定时器。 */
+    pingTimer;
+    /** 上一轮 ping 是否尚未收到 pong。 */
+    awaitingPong = false;
+    delay;
+    stopped = false;
+    connectionId;
+    /** 是否已收到 hello 回执。未确认前收到的业务请求一律拒绝。 */
+    registered = false;
+    heartbeatIntervalMs;
+    /** 被丢弃的反向帧计数，供调试读取（ADR-004 纪律 1 的可观测位）。 */
+    droppedFrames = 0;
+    /** 认证被拒次数。持续增长 = 密钥配错，而不是网络问题。 */
+    authFailures = 0;
+    /**
+     * 本次连接上 hello 的请求 id。
+     *
+     * 用来校验 hello-challenge 是不是**这一次**握手的挑战：断线重连时旧连接与新连接
+     * 可能短暂共存，迟到的挑战若不校验，会拿过期 nonce 去签名，
+     * 表现为"握手失败但看不出原因"。
+     */
+    pendingHelloId;
+    /** 在途的入站 HTTP 请求数，与 MAX_INFLIGHT_HTTP_REQUESTS 对照。 */
+    inflightHttpRequests = 0;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.delay = opts.reconnectBaseMs;
+        this.heartbeatIntervalMs = opts.heartbeatIntervalMs;
+    }
+    get connected() {
+        return this.socket?.readyState === WebSocket.OPEN;
+    }
+    /** 已注册（收到 hello 回执）才算真正可用。 */
+    get ready() {
+        return this.connected && this.registered;
+    }
+    get stats() {
+        return {
+            droppedFrames: this.droppedFrames,
+            heartbeatIntervalMs: this.heartbeatIntervalMs,
+            authFailures: this.authFailures,
+        };
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.clearHeartbeat();
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.socket?.close(1000, 'shutdown');
+        this.socket = undefined;
+        this.registered = false;
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        // scheme 校验：非 TLS 链路可被中间人旁路掉 HMAC 挑战应答（nonce 与签名都可被替换），
+        // 那样"认证通过"就只是假象。
+        //
+        // 这里必须区分两种结果，否则会出现「告警刷屏」和「把可接受配置当错误」两个问题：
+        //   · 不可用（非 ws/wss）→ 致命，重连没意义，但也不该崩进程
+        //   · 可用但不安全（ws://）→ **只提醒一次**，然后照常连接
+        //
+        // 上一版把两者混在一起：ws:// 也走 reportFatalConfig 并 scheduleReconnect，
+        // 于是每一次重连都打一条同样的 stderr（实测 8 条），而且把「本机联调合法配置」
+        // 当成错误处理。日志噪音会让人对真正的告警失去敏感 —— 这比不告警更糟。
+        const schemeVerdict = checkRelayUrlScheme(this.opts.url);
+        if (schemeVerdict.insecureReason !== undefined) {
+            this.warnInsecureSchemeOnce(schemeVerdict.insecureReason);
+        }
+        if (schemeVerdict.fatalReason !== undefined) {
+            this.reportFatalConfig(schemeVerdict.fatalReason);
+            this.scheduleReconnect();
+            return;
+        }
+        let socket;
+        try {
+            socket = new WebSocket(this.opts.url, { handshakeTimeout: WS_HANDSHAKE_TIMEOUT_MS });
+        }
+        catch (error) {
+            // new WebSocket 对畸形 URL 会同步抛。不接住会从 socket.on('open') 的调用栈里炸出去。
+            this.reportFatalConfig(`invalid relayUrl: ${error instanceof Error ? error.message : String(error)}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.registered = false;
+        // 新连接：网关那边没有本实例的任何状态，下一次心跳必须完整带上 launchUrl。
+        this.lastSentLaunchUrl = undefined;
+        socket.on('open', async () => {
+            // TCP keepalive 兜底：对端进程被 kill -9 后内核层最终会探到。
+            // 但默认以小时计，所以**主判据是 WS ping/pong**（见 startLivenessProbe），这里只是兜底。
+            const raw = socket._socket;
+            raw?.setKeepAlive?.(true, 30_000);
+            // 凭据不进查询串：握手后立即发 hello（**不带密钥**）。
+            this.pendingHelloId = crypto.randomUUID();
+            // ADR-005 运行时自声明：读取 webServer 已注册路由。
+            // 可能要在别的插件注册完之前等一小段时间（见 collectWithRetry），
+            // 因此这里是 async —— 但 hello 只是稍晚发出，不影响协议正确性。
+            let prefixes = [];
+            if (this.opts.collectHttpPrefixes) {
+                try {
+                    prefixes = await this.opts.collectHttpPrefixes();
+                }
+                catch {
+                    // 读取失败不影响握手本身：退化为「未上报」，网关会打印提示。
+                    prefixes = [];
+                }
+            }
+            // 已认证应用 URL：网关据此代持 DSH 会话。取不到就不上报（不是错误）。
+            let launchUrl;
+            if (this.opts.collectLaunchUrl) {
+                try {
+                    const value = this.opts.collectLaunchUrl();
+                    if (typeof value === 'string' && value.length > 0)
+                        launchUrl = value;
+                }
+                catch {
+                    // 拿不到 token 不影响握手本身：退化为「用户自行带 ?token=」。
+                    launchUrl = undefined;
+                }
+            }
+            const hello = {
+                id: this.pendingHelloId,
+                method: 'hello',
+                params: {
+                    instanceId: this.opts.instanceId,
+                    version: '0.1.0',
+                    methods: ADVERTISED_METHODS,
+                    ...(prefixes.length > 0 ? { httpPrefixes: prefixes } : {}),
+                    ...(launchUrl !== undefined ? { launchUrl } : {}),
+                },
+                ts: Date.now(),
+            };
+            socket.send(JSON.stringify(hello));
+            // 心跳**推迟到挑战应答通过之后**（见 onResponse）。
+            //
+            // 以前在 open 时就开跑，理由是"网关在 hello 时即登记、早发可避免巡检误杀"。
+            // P5 起网关不再在 hello 时登记，而是挑战应答通过才登记；未认证连接发心跳
+            // 只会被当成未授权流量。把它挪到 registered=true 之后，语义与网关一致。
+        });
+        socket.on('message', (raw, isBinary) => {
+            // 二进制帧不是 JSON：HTTP body 与 WS 数据帧都走这里，按 id 前缀分流。
+            if (isBinary) {
+                const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+                this.onBinary(buf);
+                return;
+            }
+            void this.onMessage(raw.toString());
+        });
+        // 收到 pong 即证明对端进程活着（协议层，不受应用层缓冲区迷惑）。
+        socket.on('pong', () => {
+            this.awaitingPong = false;
+        });
+        socket.on('close', (code, reason) => {
+            this.socket = undefined;
+            this.registered = false;
+            this.pendingHelloId = undefined;
+            this.clearHeartbeat();
+            this.opts.onClose(`code=${code} reason=${reason.toString()}`, code);
+            this.scheduleReconnect();
+        });
+        socket.on('error', (err) => {
+            // error 之后必然跟随 close，这里只记录，不重复调度重连。
+            this.opts.onClose(err.message, -1);
+        });
+    }
+    /**
+     * ADR-005 HTTP 转发：先回控制帧，再回二进制 body 帧。
+     *
+     * 顺序是协议约定（body 帧必须紧随其控制帧）；这里用 void 并发调度，
+     * 多个请求互不阻塞。
+     */
+    /**
+     * 在途 HTTP 请求已满：回明确的错误帧，不排队。
+     *
+     * 复用既有的 http-response-error 通道而不是硬塞一个 503 响应：
+     *   - HttpResponseFrame 没有 reason 字段，伪造一个能让网关解析失败；
+     *   - 该通道的语义正是"请求根本没被完整处理"，与本场景一致，前端能区分。
+     *
+     * 排队不是选项：排队只是把内存压力推迟到队列里，而且让请求方白等到超时，
+     * 错误更不可读。明确拒绝比慢慢耗尽内存负责。
+     */
+    rejectTooBusy(frame) {
+        const errorFrame = {
+            kind: 'http-response-error',
+            id: frame.id,
+            code: 'internal',
+            message: `bridge busy: more than ${MAX_INFLIGHT_HTTP_REQUESTS} concurrent requests in flight`,
+        };
+        this.sendRaw(JSON.stringify(errorFrame));
+    }
+    async onHttpRequest(frame) {
+        // POST 的请求体由紧随控制帧的二进制帧送达。到这里时它可能还没到
+        // （两条独立 WS 消息，顺序不由我们控制），所以等待一小段时间再取。
+        const body = frame.bodyLength > 0 ? await this.awaitRequestBody(frame.id) : undefined;
+        const handler = this.opts.onHttpRequest;
+        let result;
+        if (!handler) {
+            result = {
+                frame: {
+                    kind: 'http-response-error',
+                    id: frame.id,
+                    code: 'upstream_unreachable',
+                    message: 'plugin has no HTTP forwarder configured',
+                },
+            };
+        }
+        else {
+            try {
+                result = await handler(frame, body);
+            }
+            catch (err) {
+                result = {
+                    frame: {
+                        kind: 'http-response-error',
+                        id: frame.id,
+                        code: 'internal',
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                };
+            }
+        }
+        this.sendRaw(JSON.stringify(result.frame));
+        if (result.body && result.body.byteLength > 0) {
+            this.sendRaw(encodeHttpBodyFrame(frame.id, result.body));
+        }
+    }
+    /**
+     * 底层发送：JSON 走文本帧，Uint8Array 走二进制帧。带**发送水位**检查。
+     *
+     * 为什么需要：ws 的 send() 只是把数据塞进内核/userland 缓冲**立即返回**。
+     * 网关不读（挂住、限速、被暂停）时缓冲只增不减，本进程内存随之线性增长；
+     * 单个 HTTP 响应体上限是 32MB（HTTP_BODY_MAX_BYTES），几十个在途响应就足以吃光内存。
+     * 故障网关或恶意网关都能远程触发这件事——私网 DSH 不该被公网对端拖垮。
+     *
+     * 策略：**不丢帧**（丢帧会让上面的多路复用协议失去同步），而是当水位超过硬上限时
+     * 主动断开本条连接。断开是安全的收口：上层走既有退避重连，网关侧 dropInstance
+     * 会作废名下订阅，本端重建状态后重新开始。
+     *
+     * @returns 是否真的写出去了。调用方目前都不依赖返回值，保留以便将来分流。
+     */
+    sendRaw(payload) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return false;
+        const buffered = socket.bufferedAmount;
+        if (buffered > SEND_BUFFER_HARD_LIMIT_BYTES) {
+            // 硬上限：继续写只会吃内存，直接弃连接，交给退避重连。
+            process.stderr.write(`remote-bridge: send buffer exceeded ${SEND_BUFFER_HARD_LIMIT_BYTES} bytes ` +
+                `(buffered=${buffered}); closing the connection to shed load\n`);
+            this.opts.onBackpressure?.(buffered);
+            // 1009 = message too big 的语义不合适；用 1013（try again later）表达"对端跟不上"。
+            try {
+                socket.close(1013, 'send buffer overflow');
+            }
+            catch { /* already gone */ }
+            return false;
+        }
+        if (buffered > SEND_BUFFER_SOFT_LIMIT_BYTES) {
+            // 软上限：只告警不中断。留出观察窗口，避免正常突发流量被直接掐断。
+            this.opts.onProtocolWarning?.(`send buffer high watermark: ${buffered} bytes (soft limit ${SEND_BUFFER_SOFT_LIMIT_BYTES})`);
+        }
+        socket.send(payload);
+        return true;
+    }
+    /** 发一条控制帧（JSON 文本帧）。ADR-005 T34 的 ws-open-ack / ws-close 走这里。 */
+    sendControl(frame) {
+        this.sendRaw(JSON.stringify(frame));
+    }
+    /** 发一条二进制帧（WS 数据帧）。与 HTTP body 帧共用通道，靠 id 前缀区分。 */
+    sendBinary(payload) {
+        this.sendRaw(payload);
+    }
+    /**
+     * 入站分发。
+     *
+     * 修复点（原 client.ts:101）：旧判定把**响应**当 hello 请求判，
+     * 而网关 hello 回执是 `{ id, ok: true, result }`，没有 method 字段，
+     * 因此 onOpen 永不触发、退避永不重置。现在用 proto 的唯一判别函数
+     * classifyWireMessage 区分顶层消息（request / response / frame / frame-end /
+     * sub-control / hello-challenge）。"挑战"因此是**类型级**判别，不靠约定。
+     */
+    /** 待配对的 HTTP 请求体：id → {body, resolve}。 */
+    pendingBodies = new Map();
+    /**
+     * 等请求体二进制帧。超时返回 undefined，由调用方报明确错误而不是挂死。
+     *
+     * 用 Promise + 定时器而不是轮询：这是纯粹的「等一条消息」语义。
+     */
+    awaitRequestBody(id) {
+        const already = this.pendingBodies.get(id);
+        if (already) {
+            this.pendingBodies.delete(id);
+            return Promise.resolve(already.body);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingBodies.delete(id);
+                resolve(undefined);
+            }, 5_000);
+            timer.unref?.();
+            this.pendingBodies.set(id, {
+                body: new Uint8Array(0),
+                resolve: (b) => { clearTimeout(timer); resolve(b); },
+            });
+        });
+    }
+    /** 二进制帧入口：区分 HTTP body 与 WS 数据帧（按 id 前缀 'h' / 'w'）。 */
+    onBinary(raw) {
+        const view = new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+        if (view.length < 5) {
+            this.droppedFrames += 1;
+            return;
+        }
+        const idLen = new DataView(view.buffer, view.byteOffset, view.byteLength).getUint32(0, false);
+        if (idLen === 0 || idLen > 256 || view.length < 4 + idLen) {
+            this.droppedFrames += 1;
+            return;
+        }
+        const id = new TextDecoder().decode(view.subarray(4, 4 + idLen));
+        if (id.startsWith('w')) {
+            const frame = decodeWsDataFrame(view);
+            if (!frame) {
+                this.droppedFrames += 1;
+                return;
+            }
+            this.opts.onWsData?.(frame.id, frame.opcode, frame.payload);
+            return;
+        }
+        // 'h' 前缀：HTTP 请求体（POST）。配给等待中的 onHttpRequest。
+        const decodedBody = decodeHttpBodyFrame(view);
+        if (!decodedBody) {
+            this.droppedFrames += 1;
+            return;
+        }
+        const waiting = this.pendingBodies.get(decodedBody.id);
+        if (!waiting) {
+            // 请求已超时或 id 未知：计数不静默。
+            this.droppedFrames += 1;
+            return;
+        }
+        this.pendingBodies.delete(decodedBody.id);
+        waiting.resolve(decodedBody.body);
+    }
+    async onMessage(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.opts.onProtocolWarning?.('inbound message is not valid JSON');
+            return;
+        }
+        const kind = classifyWireMessage(parsed);
+        // ── 统一入口守卫：握手完成前只接受握手相关的消息 ────────────────────
+        //
+        // 上一版的守卫写在 onInboundRequest **里面**，于是同级的四个分支
+        // （http-request / ws-open / ws-flow / ws-close）全部漏掉 ——
+        // 新加分支还会继续漏，因为拦截不在入口。
+        //
+        // 现在的规则：未认证时只放行
+        //   · hello-challenge   —— 网关下发的挑战，握手需要
+        //   · response          —— 对挑战的应答由 onResponse 内部判定 id 是否匹配
+        // 其余一律丢弃并计数。这与 onInboundRequest 里的语义一致，但覆盖了全部分支。
+        if (!this.registered && kind !== 'hello-challenge' && kind !== 'response') {
+            this.droppedFrames += 1;
+            this.opts.onProtocolWarning?.('inbound "' + String(kind) + '" dropped: handshake not completed');
+            return;
+        }
+        switch (kind) {
+            case 'response':
+                this.onResponse(parsed);
+                return;
+            case 'request':
+                await this.onInboundRequest(parsed);
+                return;
+            case 'frame':
+            case 'frame-end':
+                // 帧只能由实例发往浏览器。反向收到帧即协议违规，丢弃并计数。
+                this.droppedFrames += 1;
+                this.opts.onProtocolWarning?.('inbound frame rejected: frames travel instance→browser only');
+                return;
+            case 'sub-control':
+                this.onSubscriptionControl(parsed);
+                return;
+            case 'hello-challenge':
+                this.onHelloChallenge(parsed);
+                return;
+            case 'http-request': {
+                // ADR-005：网关转来的 HTTP 请求。并发处理，不排队（多路复用）。
+                //
+                // 但并发**必须有上限**：每个请求最终持有一份最大 32MB 的响应体，
+                // 无上限派发等于把本进程的内存交给对端决定。
+                // 超限时回一个明确的错误帧而不是排队 —— 排队只会把内存压力推迟，
+                // 而且让请求方白等到超时，错误更不可读。
+                const frame = parsed;
+                if (this.inflightHttpRequests >= MAX_INFLIGHT_HTTP_REQUESTS) {
+                    this.rejectTooBusy(frame);
+                    return;
+                }
+                this.inflightHttpRequests += 1;
+                void this.onHttpRequest(frame).finally(() => {
+                    this.inflightHttpRequests -= 1;
+                });
+                return;
+            }
+            case 'ws-open':
+                // ADR-005 T34：WS 升级。异步发起，不阻塞消息循环。
+                this.opts.onWsOpen?.(parsed);
+                return;
+            case 'ws-flow': {
+                const flow = parsed;
+                this.opts.onWsFlow?.(flow.id, flow.action);
+                return;
+            }
+            case 'ws-close': {
+                const close = parsed;
+                this.opts.onWsClose?.(close.id, close.code, close.reason);
+                return;
+            }
+            default:
+                this.opts.onProtocolWarning?.('inbound message not classifiable');
+        }
+    }
+    /**
+     * 订阅控制帧（网关 → 插件）。
+     *
+     * 控制面事务：不产生 RpcResponse，失败只告警。畸形消息不计入统计，
+     * 否则网关侧一个 bug 会让插件的协议告警计数失真。
+     */
+    onSubscriptionControl(message) {
+        const sub = message;
+        if (typeof sub.subscriptionId !== 'string' || sub.subscriptionId === '') {
+            this.opts.onProtocolWarning?.('sub-control rejected: missing subscriptionId');
+            return;
+        }
+        const reason = typeof sub.reason === 'string' ? sub.reason : 'cancelled';
+        this.opts.onSubscriptionControl(sub.subscriptionId, reason);
+    }
+    /**
+     * 网关的认证挑战（ADR-003 挑战应答第二跳）。
+     *
+     * 挑战是独立顶层控制帧 `kind:'hello-challenge'`（网关 → 插件，与 sub-control 同向），
+     * **不是**失败响应里附带的字段——"挑战"与"真拒"的区分是类型级的，
+     * 不靠"失败里有没有 nonce"这种约定。
+     */
+    onHelloChallenge(frame) {
+        // 必须是**本次**握手的挑战：断线重连时旧连接的挑战可能迟到。
+        // 丢弃比"拿过期 nonce 去签名"好——后者只会失败，而且看不出原因。
+        // 注意：这不算 authFailure，过期挑战不是认证失败。
+        if (frame.requestId !== this.pendingHelloId) {
+            this.opts.onProtocolWarning?.(`hello-challenge ignored: requestId ${frame.requestId} does not match pending hello ${this.pendingHelloId ?? '(none)'}`);
+            return;
+        }
+        const signature = signChallenge(this.opts.instanceKey, frame.nonce, this.opts.instanceId, frame.timestamp);
+        // 只回签名，不回 nonce、更不回 key。nonce 由网关持有，插件侧无需回显。
+        const auth = {
+            id: crypto.randomUUID(),
+            method: 'hello.auth',
+            params: { instanceId: this.opts.instanceId, signature, timestamp: frame.timestamp },
+            ts: Date.now(),
+        };
+        this.send(auth);
+    }
+    /** 网关对本插件的响应（hello 回执 / 心跳回执 / 认证失败）。 */
+    onResponse(response) {
+        if (response.ok) {
+            // hello 回执是注册成功的**唯一**权威信号：重置退避、采纳网关的心跳间隔。
+            const heartbeatIntervalMs = response.result
+                ?.heartbeatIntervalMs;
+            if (typeof heartbeatIntervalMs === 'number' && heartbeatIntervalMs > 0) {
+                this.heartbeatIntervalMs = heartbeatIntervalMs;
+            }
+            if (!this.registered) {
+                this.registered = true;
+                this.connectionId = response.result?.connectionId;
+                this.delay = this.opts.reconnectBaseMs; // 注册成功才重置退避
+                // 心跳从这一刻才开始——认证通过前发心跳只会被网关当成未授权流量。
+                this.scheduleHeartbeat();
+                // 存活探测与心跳同时开始：心跳管「网关收到我」，ping/pong 管「网关还活着」。
+                this.startLivenessProbe();
+                this.opts.onOpen(this.connectionId ?? 'unknown');
+            }
+            return;
+        }
+        // 到这里就是**纯粹的失败**——挑战是独立控制帧 hello-challenge，不经这里。
+        // （失败响应里不携带任何认证数据；把挑战混进失败是已经否决的承载方式。）
+        //
+        // 'unauthenticated' = 认证被拒（签名错 / 无 key / 重放），与传输错误分开上报：
+        // 密钥配错是运维事故，混进 disconnected 会让人去查网络。
+        //
+        // 两种情况都**不**重置退避、**不**置 registered，由调用方走正常的指数退避重连。
+        if (response.error.code === 'unauthenticated') {
+            this.authFailures += 1;
+            this.opts.onAuthFailure?.(response.error.code, response.error.message);
+            return;
+        }
+        this.opts.onProtocolWarning?.(`gateway error ${response.error.code}: ${response.error.message}`);
+    }
+    /** 浏览器 → 插件方向：只接受 RpcRequest（ADR-004 纪律 1）。 */
+    async onInboundRequest(req) {
+        if (req.method === 'hello' || !this.registered) {
+            this.send({
+                id: req.id,
+                ok: false,
+                error: { code: 'unauthenticated', message: 'hello handshake not completed for this connection' },
+            });
+            return;
+        }
+        try {
+            const result = await this.opts.onRequest(req);
+            this.send({ id: req.id, ok: true, result });
+        }
+        catch (err) {
+            // T16：错误在边界处必须**完整**出去。
+            //
+            // 以前这里只取 err.message。DSH 侧的 RemoteError / SessionFormatError 把
+            // 关键上下文放在 name / code / details / cause 上（例如
+            // "stored session … is corrupt: SessionFormatError: …"），只发 message
+            // 会让同一个故障在"进程内直调"和"经 relay 端到端"两种观测方式下文案不一致，
+            // 排查时看起来像两个不同的 bug。
+            //
+            // 这里仍然只是**格式化**，不是吞错：没有 try/catch 兜住原始异常，
+            // code 与 message 的原值一律保留。
+            const error = err instanceof RpcError
+                ? err
+                : new RpcError('internal', describeError(err), { cause: err });
+            this.send({ id: req.id, ok: false, error: { code: error.code, message: error.message } });
+        }
+    }
+    /**
+     * 主动心跳。
+     *
+     * 用 setTimeout 链而非 setInterval：发送本身不阻塞消息循环（ws.send 是
+     * 非阻塞入队），但排程必须与连接生命周期同生共死，避免 stop 后残留 tick。
+     * 心跳不等待回执（回执只是网关时间戳），因此不存在"心跳阻塞消息循环"。
+     */
+    scheduleHeartbeat() {
+        this.clearHeartbeat();
+        if (this.stopped)
+            return;
+        this.heartbeatTimer = setTimeout(() => {
+            this.heartbeatTimer = undefined;
+            this.sendHeartbeat();
+            this.scheduleHeartbeat();
+        }, this.heartbeatIntervalMs);
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        this.stopLivenessProbe();
+    }
+    /**
+     * WS ping/pong 存活探测 —— **应用层心跳发现不了对端进程死亡**。
+     *
+     * 为什么必须用协议层 ping：relay 被 kill -9 后，ws.send() 仍会成功
+     * （写进内核发送缓冲），应用层 heartbeat 永远收不到回复也不报错，
+     * 连接半开挂起、重连永不触发。实测就是这么卡住的。
+     *
+     * 规则：每 pingIntervalMs 发一次 ping；若**上一轮 ping 尚未收到 pong**，
+     * 就判定连接已死 → terminate()（不是 close()：半开连接调 close() 会等握手，
+     * 等不到就卡住），随后走既有退避重连。
+     */
+    startLivenessProbe() {
+        this.stopLivenessProbe();
+        if (this.stopped)
+            return;
+        this.awaitingPong = false;
+        this.pingTimer = setInterval(() => {
+            const socket = this.socket;
+            if (!socket || socket.readyState !== WebSocket.OPEN)
+                return;
+            // 上一轮 ping 没等到 pong → 对端已死。
+            if (this.awaitingPong) {
+                this.opts.onProtocolWarning?.('liveness: previous ping got no pong within ' + PING_INTERVAL_MS + 'ms; terminating dead connection');
+                this.awaitingPong = false;
+                try {
+                    // terminate 而非 close：半开连接上 close() 会等对端握手，永远等不到。
+                    socket.terminate();
+                }
+                catch {
+                    /* 已断开 */
+                }
+                return;
+            }
+            this.awaitingPong = true;
+            try {
+                socket.ping();
+            }
+            catch {
+                this.awaitingPong = false;
+            }
+        }, PING_INTERVAL_MS);
+        this.pingTimer.unref?.();
+    }
+    stopLivenessProbe() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = undefined;
+        }
+        this.awaitingPong = false;
+    }
+    /** 上一次**成功发送**的 launchUrl，用于变化时才重发（省流量）。 */
+    lastSentLaunchUrl;
+    sendHeartbeat() {
+        const params = { instanceId: this.opts.instanceId };
+        // 心跳顺带上报最新的 launchUrl。三个理由：
+        //   ① 网关重启后内存缓存全空，只有周期性重发才能让它重新代持；
+        //   ② DSH 重启会换 token，心跳自动把新值推过去；
+        //   ③ hello 时可能还取不到（connection 服务未就绪），心跳在运行期一定能取到。
+        //
+        // 值没变就不带：这是常态，没必要每 15 秒重复一份 token。
+        // 取不到时**不清空** lastSent —— 否则短暂的读取失败会让下一次又重发一遍。
+        if (this.opts.collectLaunchUrl) {
+            try {
+                const current = this.opts.collectLaunchUrl();
+                if (typeof current === 'string' && current.length > 0 && current !== this.lastSentLaunchUrl) {
+                    params.launchUrl = current;
+                    this.lastSentLaunchUrl = current;
+                }
+            }
+            catch {
+                // 取不到就这轮不带，不影响心跳本身。
+            }
+        }
+        this.send({ id: crypto.randomUUID(), method: 'heartbeat', params, ts: Date.now() });
+    }
+    /**
+     * 投递一条订阅帧（ADR-004）。
+     *
+     * 未就绪（socket 未开或 hello 未回执）时返回 false 而不抛：帧流是异步泵，
+     * 投递失败只会让浏览器少几帧，正确的是让订阅侧收到 frame-end 而不是炸掉泵循环。
+     */
+    sendFrame(frame) {
+        if (!this.ready)
+            return false;
+        return this.send(frame);
+    }
+    /** 投递帧流终止信号。返回 false 的含义同 sendFrame。 */
+    sendFrameEnd(end) {
+        if (!this.ready)
+            return false;
+        return this.send(end);
+    }
+    send(message) {
+        const socket = this.socket;
+        if (socket?.readyState !== WebSocket.OPEN)
+            return false;
+        socket.send(JSON.stringify(message));
+        return true;
+    }
+    /**
+     * 上报一条"配置层面不可恢复、但每次重连都应可见"的问题。
+     *
+     * 走 stderr 而不是 ctx.logger：配置错误通常发生在插件还没激活时，
+     * 这时 logger 可能不可用；而运维排查的第一现场是进程启动输出。
+     * 文案里绝不带 instanceKey。
+     */
+    reportFatalConfig(detail) {
+        process.stderr.write(`remote-bridge: ${detail}\n`);
+        this.opts.onProtocolWarning?.(detail);
+    }
+    /**
+     * 只提醒一次「链路不安全」。
+     *
+     * 为什么不能走 reportFatalConfig：那条路径每次重连都会执行，
+     * 实测 ws:// 配置重连 8 次就打 8 条一模一样的 stderr。
+     * 同一个已知情况反复刷屏，会让人对真正的告警麻木 —— 比不告警更糟。
+     *
+     * 用实例字段记状态而不是模块级标志：多实例（不同 relayUrl）各自独立判断。
+     */
+    warnInsecureSchemeOnce(detail) {
+        if (this.warnedInsecureScheme)
+            return;
+        this.warnedInsecureScheme = true;
+        process.stderr.write(`remote-bridge: ${detail}\n`);
+        this.opts.onProtocolWarning?.(detail);
+    }
+    /** ws:// 告警是否已打过（只提醒一次，避免重连刷屏）。 */
+    warnedInsecureScheme = false;
+    scheduleReconnect() {
+        if (this.stopped || this.timer)
+            return;
+        const delay = this.delay;
+        this.delay = Math.min(this.delay * 2, this.opts.reconnectMaxMs);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.connect();
+        }, delay);
+    }
+}
+//# sourceMappingURL=client.js.map