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

package/lib/relay/client.d.ts

@@ -0,0 +1,262 @@
+import { type HttpRequestFrame, type WsOpenFrame, type RpcErrorCode, type RpcFrame, type RpcFrameEnd, type RpcRequest } from '@ntdgy/dsh-remote-proto';
+import type { UpstreamResult } from './http-forward.ts';
+/**
+ * 校验 relayUrl 的 scheme。
+ *
+ * 返回两种**不同性质**的结论，调用方据此采取不同动作 —— 这是刻意分开的：
+ *   · fatalReason   配置根本不可用（非 ws/wss、URL 畸形）→ 重连没有意义
+ *   · insecureReason 可用但不安全（ws://）→ 照常连接，只提醒一次
+ *
+ * 混在一起的后果实测过：ws:// 每次重连都打一条同样的 stderr（8 条刷屏），
+ * 而且把「本机联调」这种合法配置当成错误。日志噪音会让人对真正的告警麻木。
+ *
+ * 为什么单独成函数而不是内联：这是纯函数，可以直接单测，
+ * 而"配了个 http:// 的地址"这种事只会在部署现场出现一次，测不到就等于没有。
+ */
+export interface SchemeVerdict {
+    /** 不可用：调用方应放弃本次连接尝试。 */
+    readonly fatalReason?: string;
+    /** 可用但不安全：调用方应连接，并（只）提醒一次。 */
+    readonly insecureReason?: string;
+}
+export declare function checkRelayUrlScheme(url: string): SchemeVerdict;
+export interface RelayClientOptions {
+    url: string;
+    instanceId: string;
+    instanceKey: string;
+    reconnectBaseMs: number;
+    reconnectMaxMs: number;
+    /** 首次心跳间隔；网关 hello 回执携带权威值，收到后以网关为准。 */
+    heartbeatIntervalMs: number;
+    onRequest: (req: RpcRequest) => Promise<unknown>;
+    /**
+     * 订阅控制面（网关 → 插件的退订指令）。
+     *
+     * 这是**唯一**允许由网关发起、作用于插件侧订阅的消息；它不是业务 RPC，
+     * 所以不走 onRequest，也不产生 RpcResponse（见 proto 的 wire-sub-control 提案）。
+     */
+    onSubscriptionControl: (subscriptionId: string, reason: string) => void;
+    /**
+     * ADR-005：HTTP 转发。返回的 body 以二进制帧紧随控制帧回传。
+     * 缺省时收到 http-request 会回 upstream_unreachable，而不是静默丢弃。
+     */
+    onHttpRequest?: (frame: HttpRequestFrame, body?: Uint8Array) => Promise<UpstreamResult>;
+    /** ADR-005 T34：网关要求发起 WS 升级。 */
+    onWsOpen?: (frame: WsOpenFrame) => void;
+    /** 网关流量控制：暂停/恢复从上游读取。 */
+    onWsFlow?: (id: string, action: 'pause' | 'resume') => void;
+    /** 网关要求关闭上游 WS。 */
+    onWsClose?: (id: string, code: number, reason: string) => void;
+    /** 网关转来的 WS 数据帧（写入上游）。 */
+    onWsData?: (id: string, opcode: number, payload: Uint8Array) => void;
+    /**
+     * 取本实例在 DSH webServer 上实际注册的路径前缀（ADR-005 运行时自声明）。
+     *
+     * 每次 hello 都会调用一次，实现方应该现读路由表而不是缓存 ——
+     * 插件可能在两次重连之间注册了新路由。
+     */
+    collectHttpPrefixes?: () => string[] | Promise<string[]>;
+    /**
+     * 上报本实例的已认证应用 URL（含 DSH 的 launch token）。
+     *
+     * 由 DSH 的 `connection.authenticatedUrl()` 生成；网关用它代浏览器完成
+     * DSH 登录，用户从此不必手输 DSH token。
+     *
+     * 每次 hello 都现取：**DSH 重启后 token 会变**，缓存会让网关拿到过期值。
+     * 取不到就返回 undefined —— 网关退化为原有行为，不做任何代持。
+     */
+    collectLaunchUrl?: () => string | undefined;
+    onOpen: (connectionId: string) => void;
+    /** 带 code：网关主动踢线（如 4408 心跳超时）时可据 code 区分，不改变退避策略。 */
+    onClose: (reason: string, code: number) => void;
+    /** 协议告警（如收不到 hello 回执的裸帧），用于观测而不是静默。 */
+    onProtocolWarning?: (detail: string) => void;
+    /**
+     * 认证被网关拒绝。
+     *
+     * 与普通断连分开上报：密钥配错是**运维事故**，不是网络抖动，
+     * 混在"disconnected"里会让人一直去查网络。文案里绝不带 key。
+     */
+    onAuthFailure?: (code: RpcErrorCode, message: string) => void;
+    /**
+     * 发送缓冲越过硬上限、本端主动断开连接时回调。
+     *
+     * 与普通断连分开上报：这是**本端主动止损**，不是对端掉线，
+     * 混在一起会让人去查网关的网络，而真正该查的是"网关为什么不读了"。
+     */
+    onBackpressure?: (bufferedAmount: number) => void;
+}
+export declare class RelayClient {
+    private socket?;
+    private timer?;
+    private heartbeatTimer?;
+    /** WS ping/pong 存活探测的定时器。 */
+    private pingTimer?;
+    /** 上一轮 ping 是否尚未收到 pong。 */
+    private awaitingPong;
+    private delay;
+    private stopped;
+    private connectionId?;
+    /** 是否已收到 hello 回执。未确认前收到的业务请求一律拒绝。 */
+    private registered;
+    private heartbeatIntervalMs;
+    /** 被丢弃的反向帧计数，供调试读取（ADR-004 纪律 1 的可观测位）。 */
+    private droppedFrames;
+    /** 认证被拒次数。持续增长 = 密钥配错，而不是网络问题。 */
+    private authFailures;
+    /**
+     * 本次连接上 hello 的请求 id。
+     *
+     * 用来校验 hello-challenge 是不是**这一次**握手的挑战：断线重连时旧连接与新连接
+     * 可能短暂共存，迟到的挑战若不校验，会拿过期 nonce 去签名，
+     * 表现为"握手失败但看不出原因"。
+     */
+    private pendingHelloId?;
+    /** 在途的入站 HTTP 请求数，与 MAX_INFLIGHT_HTTP_REQUESTS 对照。 */
+    private inflightHttpRequests;
+    private readonly opts;
+    constructor(opts: RelayClientOptions);
+    get connected(): boolean;
+    /** 已注册（收到 hello 回执）才算真正可用。 */
+    get ready(): boolean;
+    get stats(): {
+        droppedFrames: number;
+        heartbeatIntervalMs: number;
+        authFailures: number;
+    };
+    start(): void;
+    stop(): void;
+    private connect;
+    /**
+     * ADR-005 HTTP 转发：先回控制帧，再回二进制 body 帧。
+     *
+     * 顺序是协议约定（body 帧必须紧随其控制帧）；这里用 void 并发调度，
+     * 多个请求互不阻塞。
+     */
+    /**
+     * 在途 HTTP 请求已满：回明确的错误帧，不排队。
+     *
+     * 复用既有的 http-response-error 通道而不是硬塞一个 503 响应：
+     *   - HttpResponseFrame 没有 reason 字段，伪造一个能让网关解析失败；
+     *   - 该通道的语义正是"请求根本没被完整处理"，与本场景一致，前端能区分。
+     *
+     * 排队不是选项：排队只是把内存压力推迟到队列里，而且让请求方白等到超时，
+     * 错误更不可读。明确拒绝比慢慢耗尽内存负责。
+     */
+    private rejectTooBusy;
+    private onHttpRequest;
+    /**
+     * 底层发送：JSON 走文本帧，Uint8Array 走二进制帧。带**发送水位**检查。
+     *
+     * 为什么需要：ws 的 send() 只是把数据塞进内核/userland 缓冲**立即返回**。
+     * 网关不读（挂住、限速、被暂停）时缓冲只增不减，本进程内存随之线性增长；
+     * 单个 HTTP 响应体上限是 32MB（HTTP_BODY_MAX_BYTES），几十个在途响应就足以吃光内存。
+     * 故障网关或恶意网关都能远程触发这件事——私网 DSH 不该被公网对端拖垮。
+     *
+     * 策略：**不丢帧**（丢帧会让上面的多路复用协议失去同步），而是当水位超过硬上限时
+     * 主动断开本条连接。断开是安全的收口：上层走既有退避重连，网关侧 dropInstance
+     * 会作废名下订阅，本端重建状态后重新开始。
+     *
+     * @returns 是否真的写出去了。调用方目前都不依赖返回值，保留以便将来分流。
+     */
+    private sendRaw;
+    /** 发一条控制帧（JSON 文本帧）。ADR-005 T34 的 ws-open-ack / ws-close 走这里。 */
+    sendControl(frame: unknown): void;
+    /** 发一条二进制帧（WS 数据帧）。与 HTTP body 帧共用通道，靠 id 前缀区分。 */
+    sendBinary(payload: Uint8Array): void;
+    /**
+     * 入站分发。
+     *
+     * 修复点（原 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}。 */
+    private readonly pendingBodies;
+    /**
+     * 等请求体二进制帧。超时返回 undefined，由调用方报明确错误而不是挂死。
+     *
+     * 用 Promise + 定时器而不是轮询：这是纯粹的「等一条消息」语义。
+     */
+    private awaitRequestBody;
+    /** 二进制帧入口：区分 HTTP body 与 WS 数据帧（按 id 前缀 'h' / 'w'）。 */
+    private onBinary;
+    private onMessage;
+    /**
+     * 订阅控制帧（网关 → 插件）。
+     *
+     * 控制面事务：不产生 RpcResponse，失败只告警。畸形消息不计入统计，
+     * 否则网关侧一个 bug 会让插件的协议告警计数失真。
+     */
+    private onSubscriptionControl;
+    /**
+     * 网关的认证挑战（ADR-003 挑战应答第二跳）。
+     *
+     * 挑战是独立顶层控制帧 `kind:'hello-challenge'`（网关 → 插件，与 sub-control 同向），
+     * **不是**失败响应里附带的字段——"挑战"与"真拒"的区分是类型级的，
+     * 不靠"失败里有没有 nonce"这种约定。
+     */
+    private onHelloChallenge;
+    /** 网关对本插件的响应（hello 回执 / 心跳回执 / 认证失败）。 */
+    private onResponse;
+    /** 浏览器 → 插件方向：只接受 RpcRequest（ADR-004 纪律 1）。 */
+    private onInboundRequest;
+    /**
+     * 主动心跳。
+     *
+     * 用 setTimeout 链而非 setInterval：发送本身不阻塞消息循环（ws.send 是
+     * 非阻塞入队），但排程必须与连接生命周期同生共死，避免 stop 后残留 tick。
+     * 心跳不等待回执（回执只是网关时间戳），因此不存在"心跳阻塞消息循环"。
+     */
+    private scheduleHeartbeat;
+    private clearHeartbeat;
+    /**
+     * WS ping/pong 存活探测 —— **应用层心跳发现不了对端进程死亡**。
+     *
+     * 为什么必须用协议层 ping：relay 被 kill -9 后，ws.send() 仍会成功
+     * （写进内核发送缓冲），应用层 heartbeat 永远收不到回复也不报错，
+     * 连接半开挂起、重连永不触发。实测就是这么卡住的。
+     *
+     * 规则：每 pingIntervalMs 发一次 ping；若**上一轮 ping 尚未收到 pong**，
+     * 就判定连接已死 → terminate()（不是 close()：半开连接调 close() 会等握手，
+     * 等不到就卡住），随后走既有退避重连。
+     */
+    private startLivenessProbe;
+    private stopLivenessProbe;
+    /** 上一次**成功发送**的 launchUrl，用于变化时才重发（省流量）。 */
+    private lastSentLaunchUrl;
+    private sendHeartbeat;
+    /**
+     * 投递一条订阅帧（ADR-004）。
+     *
+     * 未就绪（socket 未开或 hello 未回执）时返回 false 而不抛：帧流是异步泵，
+     * 投递失败只会让浏览器少几帧，正确的是让订阅侧收到 frame-end 而不是炸掉泵循环。
+     */
+    sendFrame(frame: RpcFrame): boolean;
+    /** 投递帧流终止信号。返回 false 的含义同 sendFrame。 */
+    sendFrameEnd(end: RpcFrameEnd): boolean;
+    private send;
+    /**
+     * 上报一条"配置层面不可恢复、但每次重连都应可见"的问题。
+     *
+     * 走 stderr 而不是 ctx.logger：配置错误通常发生在插件还没激活时，
+     * 这时 logger 可能不可用；而运维排查的第一现场是进程启动输出。
+     * 文案里绝不带 instanceKey。
+     */
+    private reportFatalConfig;
+    /**
+     * 只提醒一次「链路不安全」。
+     *
+     * 为什么不能走 reportFatalConfig：那条路径每次重连都会执行，
+     * 实测 ws:// 配置重连 8 次就打 8 条一模一样的 stderr。
+     * 同一个已知情况反复刷屏，会让人对真正的告警麻木 —— 比不告警更糟。
+     *
+     * 用实例字段记状态而不是模块级标志：多实例（不同 relayUrl）各自独立判断。
+     */
+    private warnInsecureSchemeOnce;
+    /** ws:// 告警是否已打过（只提醒一次，避免重连刷屏）。 */
+    private warnedInsecureScheme;
+    private scheduleReconnect;
+}