@myassis/gateway 1.0.85 → 1.0.87

package/dist/services/relay/RelayClient.js

@@ -0,0 +1,541 @@
+"use strict";
+/**
+ * 中继客户端（Gateway 侧）
+ *
+ * 维持一条到 Server 的出站 WSS 长连接，把 Server 转发来的帧还原成对本机的
+ * 真实 HTTP / WebSocket 请求，再把结果按帧回传。
+ *
+ * 为什么是「出站」：网关跑在用户机器上，绝大多数处于 NAT 之后，没有公网入口，
+ * 只有由网关主动连出才能建立双向通道；这同时避免了要求用户做端口映射。
+ *
+ * 三条不可妥协的原则：
+ * 1. 不缓冲：响应头与每个数据块都立刻发帧，保证 SSE 首字延迟；
+ * 2. 有流控：发送窗口耗尽即暂停读取本机响应，避免大响应把网关内存打爆；
+ * 3. 默认关闭：未显式开启中继时完全不建连，不产生任何外联行为。
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayClient = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const shared_1 = require("@myassis/shared");
+const protocol_js_1 = require("./protocol.js");
+const LoopbackForwarder_js_1 = require("./LoopbackForwarder.js");
+const relayConfig_js_1 = require("./relayConfig.js");
+const logger = (0, shared_1.getLogger)('relay/Client');
+/** 重连退避：1s 起，指数增长至 30s 上限 */
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+class RelayClient {
+    ws = null;
+    state = 'idle';
+    localPort = 0;
+    failureCount = 0;
+    lastError;
+    connectedAt;
+    httpStreams = new Map();
+    wsStreams = new Map();
+    pingTimer = null;
+    reconnectTimer = null;
+    lastPongAt = 0;
+    /** 主动停止后不再重连（SIGTERM / 用户关闭开关） */
+    stopped = false;
+    /** Server 在 HELLO_ACK 中下发的参数，未收到前用协议默认值 */
+    initialWindowSize = protocol_js_1.INITIAL_WINDOW_SIZE;
+    maxConcurrentStreams = protocol_js_1.MAX_CONCURRENT_STREAMS;
+    /**
+     * 启动中继。
+     * 必须在 HTTP Server 监听成功后调用——回环转发需要真实端口，
+     * 而端口存在自动顺延（3001 被占用则 3002），配置值不可信。
+     */
+    start(port) {
+        this.localPort = port;
+        this.stopped = false;
+        if (!(0, relayConfig_js_1.isRelayEnabled)()) {
+            logger.info('中继未开启，跳过隧道建连');
+            return;
+        }
+        const credential = (0, relayConfig_js_1.getRelayCredential)();
+        if (!credential) {
+            logger.info('中继已开启但尚未配对，等待用户在客户端完成配对');
+            return;
+        }
+        this.connect();
+    }
+    /** 用户开启中继：立即尝试建连（无需重启网关） */
+    enable() {
+        if (this.state === 'connecting' || this.state === 'online')
+            return;
+        if (!this.localPort) {
+            logger.warn('HTTP 服务尚未就绪，中继将在服务启动后自动建连');
+            return;
+        }
+        this.stopped = false;
+        this.failureCount = 0;
+        this.connect();
+    }
+    /** 用户关闭中继或进程退出：优雅关闭所有流与隧道 */
+    stop(reason = '中继已停止') {
+        this.stopped = true;
+        this.clearTimers();
+        // 先中止所有在途流，让远端客户端立刻收到明确错误而不是等超时
+        for (const [streamId, stream] of this.httpStreams) {
+            stream.request.abort(protocol_js_1.AbortReason.TUNNEL_CLOSING, reason);
+            this.sendAbort(streamId, protocol_js_1.AbortReason.TUNNEL_CLOSING, reason);
+        }
+        this.httpStreams.clear();
+        for (const stream of this.wsStreams.values()) {
+            stream.socket.close(1001, reason);
+        }
+        this.wsStreams.clear();
+        const ws = this.ws;
+        this.ws = null;
+        if (ws) {
+            try {
+                ws.close(1000, reason);
+            }
+            catch {
+                ws.terminate();
+            }
+        }
+        this.setState('idle');
+    }
+    /** 当前状态，供 /health 与 relay 路由暴露 */
+    getStatus() {
+        const credential = (0, relayConfig_js_1.getRelayCredential)();
+        return {
+            state: this.state,
+            connected: this.state === 'online',
+            gatewayId: credential?.gatewayId,
+            activeStreams: this.httpStreams.size + this.wsStreams.size,
+            failureCount: this.failureCount,
+            lastError: this.lastError,
+            connectedAt: this.connectedAt,
+        };
+    }
+    // ─── 连接管理 ────────────────────────────────────────
+    connect() {
+        if (this.stopped)
+            return;
+        const credential = (0, relayConfig_js_1.getRelayCredential)();
+        const tunnelUrl = (0, relayConfig_js_1.getTunnelUrl)();
+        if (!credential || !tunnelUrl) {
+            logger.warn('缺少配对凭据或中继入口地址，放弃建连');
+            return;
+        }
+        this.setState('connecting');
+        // 延迟 require：未启用中继的网关不加载 ws 客户端
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { WebSocket } = require('ws');
+        // 隧道鉴权用 HMAC 而非直接送 secret：即使日志或中间设备记录了请求头，
+        // 也拿不到长期凭据；timestamp + nonce 用于服务端防重放。
+        const timestamp = Date.now();
+        const nonce = crypto_1.default.randomBytes(16).toString('hex');
+        const signature = crypto_1.default
+            .createHmac('sha256', credential.secret)
+            .update(`${credential.gatewayId}.${timestamp}.${nonce}`)
+            .digest('hex');
+        logger.info(`正在连接中继隧道: ${tunnelUrl}`);
+        const ws = new WebSocket(tunnelUrl, {
+            headers: {
+                'x-gateway-id': credential.gatewayId,
+                'x-relay-timestamp': String(timestamp),
+                'x-relay-nonce': nonce,
+                'x-relay-signature': signature,
+                'x-relay-protocol': String(protocol_js_1.RELAY_PROTOCOL_VERSION),
+            },
+            handshakeTimeout: 15000,
+            // 隧道上跑的是已压缩/流式内容，再开 permessage-deflate 只增加延迟与内存
+            perMessageDeflate: false,
+        });
+        this.ws = ws;
+        ws.on('open', () => this.handleOpen(credential.gatewayId));
+        ws.on('message', (data, isBinary) => {
+            if (!isBinary) {
+                // 帧协议是二进制的；收到文本帧说明对端实现有误，直接判协议错误
+                this.failTunnel('隧道收到非二进制消息');
+                return;
+            }
+            this.handleFrame(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+        });
+        ws.on('close', (code, reason) => {
+            this.handleClose(`隧道关闭 code=${code} ${reason?.toString() || ''}`);
+        });
+        ws.on('error', (err) => {
+            this.lastError = err.message;
+            logger.warn(`隧道错误: ${err.message}`);
+        });
+        ws.on('pong', () => {
+            this.lastPongAt = Date.now();
+        });
+    }
+    handleOpen(gatewayId) {
+        logger.info('隧道已建立，发送 HELLO');
+        this.lastPongAt = Date.now();
+        const hello = {
+            protocolVersion: protocol_js_1.RELAY_PROTOCOL_VERSION,
+            gatewayId,
+            gatewayVersion: getGatewayVersion(),
+            platform: process.platform,
+            features: ['direct@1', `relay@${protocol_js_1.RELAY_PROTOCOL_VERSION}`],
+            timestamp: Date.now(),
+            nonce: crypto_1.default.randomBytes(8).toString('hex'),
+        };
+        this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.HELLO, protocol_js_1.CONTROL_STREAM_ID, hello));
+        // 自检：确认回环端口上的进程就是自己。
+        // 同机跑着多个网关时（端口顺延 3001→3002），若这里取错端口，请求会被
+        // 转进另一个进程 —— 隧道在线、/health 正常，但业务接口全 404，极难定位。
+        // 只告警不阻断：自检本身可能因时序（HTTP 尚未完全就绪）误判，
+        // 阻断会把一个诊断辅助变成新的故障源。
+        void (0, LoopbackForwarder_js_1.verifyLoopbackIdentity)(this.localPort, gatewayId).then((problem) => {
+            if (problem) {
+                logger.error(`中继回环自检未通过：${problem}。中继请求可能被转发到错误的进程。`);
+            }
+        });
+    }
+    handleClose(message) {
+        if (this.ws === null && this.stopped)
+            return;
+        this.ws = null;
+        this.clearTimers();
+        this.connectedAt = undefined;
+        // 隧道断开时在途流全部无效：本机请求必须销毁，否则会继续跑完并浪费资源
+        for (const stream of this.httpStreams.values()) {
+            stream.request.abort(protocol_js_1.AbortReason.TUNNEL_CLOSING, message);
+        }
+        this.httpStreams.clear();
+        for (const stream of this.wsStreams.values()) {
+            stream.socket.close(1001, message);
+        }
+        this.wsStreams.clear();
+        if (this.stopped) {
+            this.setState('idle');
+            return;
+        }
+        this.failureCount += 1;
+        this.lastError = message;
+        logger.warn(`${message}，准备重连（第 ${this.failureCount} 次）`);
+        this.scheduleReconnect();
+    }
+    failTunnel(message) {
+        this.lastError = message;
+        logger.error(`隧道协议错误: ${message}`);
+        const ws = this.ws;
+        this.ws = null;
+        try {
+            ws?.close(1002, 'protocol error');
+        }
+        catch {
+            ws?.terminate();
+        }
+        this.handleClose(message);
+    }
+    scheduleReconnect() {
+        this.setState('backoff');
+        // 指数退避 + 抖动：大量网关同时掉线时避免在同一刻齐涌回来把 Server 打满
+        const exponential = Math.min(RECONNECT_BASE_MS * 2 ** (this.failureCount - 1), RECONNECT_MAX_MS);
+        const delay = Math.round(exponential * (0.5 + Math.random() * 0.5));
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.stopped)
+                return;
+            if (!(0, relayConfig_js_1.isRelayEnabled)() || !(0, relayConfig_js_1.getRelayCredential)()) {
+                logger.info('中继已被关闭或解绑，停止重连');
+                this.setState('idle');
+                return;
+            }
+            this.connect();
+        }, delay);
+        logger.info(`将在 ${delay}ms 后重连`);
+    }
+    startHeartbeat() {
+        this.pingTimer = setInterval(() => {
+            const ws = this.ws;
+            if (!ws)
+                return;
+            // 超时判定基于最后一次 PONG：只发不收说明链路已是「半开」状态，
+            // TCP 层面可能仍然「正常」，必须靠应用层心跳发现。
+            if (Date.now() - this.lastPongAt > protocol_js_1.PING_TIMEOUT_MS) {
+                this.failTunnel(`心跳超时（${protocol_js_1.PING_TIMEOUT_MS}ms 未收到 PONG）`);
+                return;
+            }
+            this.sendFrame((0, protocol_js_1.encodeFrame)(protocol_js_1.FrameType.PING, protocol_js_1.CONTROL_STREAM_ID));
+        }, protocol_js_1.PING_INTERVAL_MS);
+    }
+    clearTimers() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    setState(state) {
+        this.state = state;
+    }
+    // ─── 帧分发 ──────────────────────────────────────────
+    handleFrame(data) {
+        let frame;
+        try {
+            frame = (0, protocol_js_1.decodeFrame)(data);
+        }
+        catch (err) {
+            // 解析失败无法定位 streamId，只能按连接级错误处理
+            this.failTunnel(err instanceof Error ? err.message : '帧解析失败');
+            return;
+        }
+        try {
+            switch (frame.type) {
+                case protocol_js_1.FrameType.HELLO_ACK:
+                    this.onHelloAck(frame.payload);
+                    break;
+                case protocol_js_1.FrameType.PING:
+                    this.sendFrame((0, protocol_js_1.encodeFrame)(protocol_js_1.FrameType.PONG, protocol_js_1.CONTROL_STREAM_ID));
+                    break;
+                case protocol_js_1.FrameType.PONG:
+                    this.lastPongAt = Date.now();
+                    break;
+                case protocol_js_1.FrameType.REQ_HEAD:
+                    this.onReqHead(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.REQ_DATA:
+                    this.onReqData(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.REQ_END:
+                    this.onReqEnd(frame.streamId);
+                    break;
+                case protocol_js_1.FrameType.STREAM_ABORT:
+                    this.onStreamAbort(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.WINDOW_UPDATE:
+                    this.onWindowUpdate(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.WS_OPEN:
+                    this.onWsOpen(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.WS_DATA:
+                    this.onWsData(frame.streamId, frame.payload);
+                    break;
+                case protocol_js_1.FrameType.WS_CLOSE:
+                    this.onWsClose(frame.streamId, frame.payload);
+                    break;
+                default:
+                    // RESP_* 是网关自己发出的方向，收到说明对端实现有误
+                    logger.warn(`忽略非预期帧: ${(0, protocol_js_1.frameTypeName)(frame.type)}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (err instanceof protocol_js_1.RelayProtocolError && frame.streamId !== protocol_js_1.CONTROL_STREAM_ID) {
+                // 单流协议错误只中止该流，不牵连整条隧道上的其他会话
+                this.abortStream(frame.streamId, err.reason, message);
+                return;
+            }
+            this.failTunnel(message);
+        }
+    }
+    onHelloAck(payload) {
+        const ack = (0, protocol_js_1.decodeJsonPayload)(payload);
+        const check = (0, protocol_js_1.checkProtocolVersion)(ack.protocolVersion);
+        if (!check.compatible) {
+            // 版本不兼容属于确定性失败，重连也不会好转，直接停止并记录原因供用户查看
+            this.stopped = true;
+            this.failTunnel(check.reason || '协议版本不兼容');
+            return;
+        }
+        if (ack.initialWindowSize > 0)
+            this.initialWindowSize = ack.initialWindowSize;
+        if (ack.maxConcurrentStreams > 0)
+            this.maxConcurrentStreams = ack.maxConcurrentStreams;
+        this.failureCount = 0;
+        this.lastError = undefined;
+        this.connectedAt = Date.now();
+        this.setState('online');
+        this.startHeartbeat();
+        logger.info(`中继隧道已就绪 tunnelId=${ack.tunnelId} window=${this.initialWindowSize}`);
+    }
+    // ─── HTTP 流 ─────────────────────────────────────────
+    onReqHead(streamId, payload) {
+        if (this.httpStreams.has(streamId) || this.wsStreams.has(streamId)) {
+            throw new protocol_js_1.RelayProtocolError(`streamId ${streamId} 重复使用`);
+        }
+        if (this.httpStreams.size + this.wsStreams.size >= this.maxConcurrentStreams) {
+            this.abortStream(streamId, protocol_js_1.AbortReason.QUOTA_EXCEEDED, '超过最大并发流数');
+            return;
+        }
+        const head = (0, protocol_js_1.decodeJsonPayload)(payload);
+        const sendWindow = new protocol_js_1.SendWindow(this.initialWindowSize);
+        const recvWindow = new protocol_js_1.ReceiveWindow(this.initialWindowSize);
+        const request = new LoopbackForwarder_js_1.LoopbackRequest(this.localPort, head, {
+            onHead: (status, headers) => {
+                this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.RESP_HEAD, streamId, { status, headers }));
+            },
+            onData: (chunk) => {
+                const stream = this.httpStreams.get(streamId);
+                if (!stream)
+                    return;
+                // 信用不足时先暂停本机响应，等 WINDOW_UPDATE 再继续。
+                // 这一步是防止「本机产出快于隧道上传」导致内存无界增长的关键。
+                if (!stream.sendWindow.canSend(chunk.byteLength)) {
+                    stream.request.pauseResponse();
+                }
+                stream.sendWindow.consume(chunk.byteLength);
+                this.sendFrame((0, protocol_js_1.encodeFrame)(protocol_js_1.FrameType.RESP_DATA, streamId, chunk));
+            },
+            onEnd: () => {
+                this.sendFrame((0, protocol_js_1.encodeFrame)(protocol_js_1.FrameType.RESP_END, streamId));
+                this.httpStreams.delete(streamId);
+            },
+            onError: (reason, message) => {
+                this.sendAbort(streamId, reason, message);
+                this.httpStreams.delete(streamId);
+            },
+        });
+        this.httpStreams.set(streamId, { request, sendWindow, recvWindow });
+    }
+    onReqData(streamId, payload) {
+        const stream = this.httpStreams.get(streamId);
+        // 流已结束仍收到数据是正常竞态（对端尚未收到 RESP_END），静默丢弃
+        if (!stream)
+            return;
+        stream.recvWindow.receive(payload.byteLength);
+        stream.request.writeBody(payload);
+        // 数据已交给本机，立刻归还信用；达到半窗阈值才实际发帧
+        const delta = stream.recvWindow.consume(payload.byteLength);
+        if (delta > 0) {
+            this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.WINDOW_UPDATE, streamId, { delta }));
+        }
+    }
+    onReqEnd(streamId) {
+        this.httpStreams.get(streamId)?.request.endBody();
+    }
+    onWindowUpdate(streamId, payload) {
+        const { delta } = (0, protocol_js_1.decodeJsonPayload)(payload);
+        const http = this.httpStreams.get(streamId);
+        if (http) {
+            http.sendWindow.increase(delta);
+            http.request.resumeResponse();
+            return;
+        }
+        this.wsStreams.get(streamId)?.sendWindow.increase(delta);
+    }
+    onStreamAbort(streamId, payload) {
+        const { reason, message } = (0, protocol_js_1.decodeJsonPayload)(payload);
+        const text = message || `对端中止 reason=${reason}`;
+        const http = this.httpStreams.get(streamId);
+        if (http) {
+            http.request.abort(reason, text);
+            this.httpStreams.delete(streamId);
+            return;
+        }
+        const ws = this.wsStreams.get(streamId);
+        if (ws) {
+            ws.socket.close(1001, text);
+            this.wsStreams.delete(streamId);
+        }
+    }
+    /** 中止某条流：同时清理本地资源并通知对端 */
+    abortStream(streamId, reason, message) {
+        const http = this.httpStreams.get(streamId);
+        if (http) {
+            http.request.abort(reason, message);
+            this.httpStreams.delete(streamId);
+        }
+        const ws = this.wsStreams.get(streamId);
+        if (ws) {
+            ws.socket.close(1011, message);
+            this.wsStreams.delete(streamId);
+        }
+        this.sendAbort(streamId, reason, message);
+    }
+    // ─── WebSocket 流 ────────────────────────────────────
+    onWsOpen(streamId, payload) {
+        if (this.wsStreams.has(streamId) || this.httpStreams.has(streamId)) {
+            throw new protocol_js_1.RelayProtocolError(`streamId ${streamId} 重复使用`);
+        }
+        if (this.httpStreams.size + this.wsStreams.size >= this.maxConcurrentStreams) {
+            this.abortStream(streamId, protocol_js_1.AbortReason.QUOTA_EXCEEDED, '超过最大并发流数');
+            return;
+        }
+        const open = (0, protocol_js_1.decodeJsonPayload)(payload);
+        const sendWindow = new protocol_js_1.SendWindow(this.initialWindowSize);
+        const recvWindow = new protocol_js_1.ReceiveWindow(this.initialWindowSize);
+        const socket = new LoopbackForwarder_js_1.LoopbackWebSocket(this.localPort, open.path, open.headers, {
+            onOpen: () => {
+                // 回环连上后无需额外通知：远端 WS 在 Server 侧已经 accept，
+                // 这里若再发帧反而要引入新的帧类型，收益不大。
+                logger.debug(`中继 WS 已连通 stream=${streamId}`);
+            },
+            onMessage: (data, binary) => {
+                const stream = this.wsStreams.get(streamId);
+                if (!stream)
+                    return;
+                if (!stream.sendWindow.canSend(data.byteLength)) {
+                    // WS 消息无法暂停（ws 库无逐条背压），超窗时中止该流比静默丢消息安全：
+                    // 丢消息会让前端状态与网关不一致，而中止会触发前端重连并补拉。
+                    this.abortStream(streamId, protocol_js_1.AbortReason.QUOTA_EXCEEDED, 'WS 发送窗口耗尽');
+                    return;
+                }
+                stream.sendWindow.consume(data.byteLength);
+                for (const frame of (0, protocol_js_1.encodeWsDataFrames)(streamId, data, binary)) {
+                    this.sendFrame(frame);
+                }
+            },
+            onClose: (code, reason) => {
+                this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.WS_CLOSE, streamId, { code, reason }));
+                this.wsStreams.delete(streamId);
+            },
+        });
+        this.wsStreams.set(streamId, { socket, sendWindow, recvWindow });
+    }
+    onWsData(streamId, payload) {
+        const stream = this.wsStreams.get(streamId);
+        if (!stream)
+            return;
+        const chunk = (0, protocol_js_1.decodeWsData)(payload);
+        stream.recvWindow.receive(chunk.data.byteLength);
+        stream.socket.send(chunk.data, chunk.binary);
+        const delta = stream.recvWindow.consume(chunk.data.byteLength);
+        if (delta > 0) {
+            this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.WINDOW_UPDATE, streamId, { delta }));
+        }
+    }
+    onWsClose(streamId, payload) {
+        const stream = this.wsStreams.get(streamId);
+        if (!stream)
+            return;
+        const { code, reason } = (0, protocol_js_1.decodeJsonPayload)(payload);
+        stream.socket.close(code, reason || '');
+        this.wsStreams.delete(streamId);
+    }
+    // ─── 发送 ────────────────────────────────────────────
+    sendFrame(frame) {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== 1 /* OPEN */)
+            return;
+        ws.send(frame, { binary: true });
+    }
+    sendAbort(streamId, reason, message) {
+        this.sendFrame((0, protocol_js_1.encodeJsonFrame)(protocol_js_1.FrameType.STREAM_ABORT, streamId, { reason, message }));
+    }
+}
+/** 读取网关自身版本，失败时不影响建连 */
+function getGatewayVersion() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { readFileSync } = require('fs');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { resolve } = require('path');
+        const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../../package.json'), 'utf-8'));
+        return pkg.version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** 单例：整个进程只维持一条隧道 */
+exports.relayClient = new RelayClient();
+exports.default = exports.relayClient;