lz-nframe 1.0.0

package/lib/NWSServiceHub.js

@@ -0,0 +1,807 @@
+/*******************************************************************************
+文件: NWSServiceHub.ts
+创建: 2026年05月07日
+作者: 老张
+描述:
+    NWS 后台服务通讯模块（单文件实现）
+    - 同时支持 Client + Server 双角色
+    - A/B 节点互连时单连接复用（自动仲裁）
+    - 支持 request/response、push、心跳、自动重连
+
+使用方法(示例):
+    const hub = new NWSServiceHub({ nodeId: 'nodeA', log: true });
+    // 1) 开启服务端能力，供其他节点连入
+    hub.startServer(9001);
+    // 2) 注册对端并发起连接
+    hub.registerService({ nodeId: 'nodeB', url: 'http://127.0.0.1:9002', token: 'demo-token' });
+    hub.connectAll();
+    // 3) 注册请求处理器
+    hub.onRequest('user', 'ping', () => ({ pong: true }));
+    // 4) 发起请求
+    const res = await hub.request('nodeB', 'user', 'ping', { t: Date.now() });
+    // 5) 订阅推送
+    const onTip = (payload) => { console.log(payload); };
+    hub.onPush('notice', 'broadcast', onTip);
+    // 6) 发送推送
+    hub.send('nodeB', 'notice', 'broadcast', { msg: 'hello' });
+    // 7) 注销/下架(可选, 长期运行场景常用):
+    hub.offRequest('user', 'ping');             // 移除单个 request 路由
+    hub.offPush('notice', 'broadcast', onTip);  // 移除某个 push 订阅(不传 handler 则清空该路由)
+    hub.unregisterService('nodeB');             // 完整释放对端的所有资源(连接/重连/挂起请求)
+    // 8) 关闭整个 hub
+    hub.disconnect();
+
+命名约定 nodeId vs peerId（两者经常指向同一字符串，但语义不同）:
+    - nodeId: 协议层"节点身份", 表示某个节点自己的唯一 id。
+        使用场景:
+          * this.nodeId                 当前 Hub 自身节点 id
+          * packet.nodeId               协议包里发包方声明的节点 id
+          * NWSServicePeerConfig.nodeId 对端配置中的节点 id
+    - peerId: 本地视角下的"对端 key", 表示"我正在和哪个对端通信", 通常等于对端的 nodeId。
+        使用场景:
+          * peerChannels / clients / reconnectTimers 等 Map 的 key
+          * pendingRequests 中记录的归属 peerId
+          * request(peerId, ...) / send(peerId, ...) 等 public API 的参数
+    举例(A 收到 B 的包):
+        this.nodeId    = 'nodeA'  // A 自己
+        packet.nodeId  = 'nodeB'  // 包里 B 自称
+        const peerId   = packet.nodeId; // peerId='nodeB', 作为本地索引使用
+    简记: 协议层/配置层/自身用 nodeId, 本地索引/函数参数/Map key 用 peerId。
+
+两端互联（A/B 双方都 registerService 了对方）行为说明:
+    1) 初始建连——会出现"瞬时双连接":
+        两端各自的 connectAll() 没有先后约束, 会同时各发起一条 outbound,
+        因此每端短时间都会持有 1 条 outbound + 1 条 inbound, 物理上有 2 条 TCP。
+    2) 仲裁收敛——installOrArbitrateChannel + shouldKeepOutbound:
+        判定规则: nodeId 字典序更大的节点保留 outbound, 更小的节点保留 inbound。
+        两端独立做出的决定一定一致(规则与输入都对称), 不会出现互相打架的情况。
+        多余的那条连接会被 close()掉, 最终只剩一条物理连接 = "B.outbound ↔ A.inbound" (设 A < B)。
+    3) 稳态后的断线重连:
+        - outbound 侧(字典序大的一方): onOutboundDisconnected → scheduleReconnect, 进入指数退避重连。
+        - inbound  侧(字典序小的一方): 仅清理资源, 不主动重连(服务端不追客户端)。
+        所以重连只由仲裁后保留 outbound 的那一方承担, 不会形成重连风暴。
+    4) 后续并发再次互连仍然安全:
+        无论谁再随时多发起一次连接, 都会再次进入 installOrArbitrateChannel 仲裁,
+        多余的物理连接会被关掉, 状态收敛回唯一连接。
+    5) 心跳判死路径:
+        心跳判死后由 handleChannelDead 走与 onOutboundDisconnected 等价的清理 + 重连流程,
+        即 outbound 侧重连, inbound 侧只清理。
+    边角注意:
+        - outbound 侧进程死了不重启时, 链路会一直断开, 直到 outbound 侧再次启动主动连过来。
+        - 由于仲裁直接以 nodeId 字符串比较, 改名可能让"活跃的连接方向"换边, 一般无感。
+
+TODO:
+    1.路由
+*******************************************************************************/
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { EventEmitter } from 'events';
+import NWSClient from './NWSClient';
+import NWSServer from './NWSServer';
+class NWSServiceHub extends EventEmitter {
+    constructor(options) {
+        super();
+        this.server = null;
+        this.peerConfigs = new Map();
+        this.clients = new Map();
+        this.peerChannels = new Map();
+        this.inboundLinkPeerMap = new Map();
+        this.pendingRequests = new Map();
+        this.requestHandlers = new Map();
+        this.pushHandlers = new Map();
+        this.reconnectTimers = new Map();
+        /** 当前每个 peer 的下一次重连等待时长（毫秒），用于指数退避 */
+        this.reconnectDelays = new Map();
+        this.heartbeatTimer = null;
+        /** 请求追踪计数器 */
+        this.traceCounter = 0;
+        if (!(options === null || options === void 0 ? void 0 : options.nodeId)) {
+            throw new Error('NWSServiceHub 需要 nodeId');
+        }
+        this.nodeId = options.nodeId;
+        this.log = options.log || false;
+        this.requestTimeoutMs = options.requestTimeoutMs || 5000;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs || 10000;
+        this.reconnectIntervalMs = options.reconnectIntervalMs || 3000;
+        this.reconnectMaxIntervalMs = options.reconnectMaxIntervalMs || 60000;
+        this.heartbeatDeadFactor = options.heartbeatDeadFactor || 3;
+    }
+    registerService(config) {
+        if (!(config === null || config === void 0 ? void 0 : config.nodeId)) {
+            throw new Error('registerService 需要 nodeId');
+        }
+        if (config.nodeId === this.nodeId) {
+            throw new Error('不能注册自己作为对端服务');
+        }
+        this.peerConfigs.set(config.nodeId, config);
+    }
+    /**
+     * 注销已注册的对端服务, 完成完整资源释放:
+     *   - 删除静态配置 peerConfigs(避免后续被 connectAll 再次拉起)
+     *   - 取消该对端的重连定时器并清空退避计数
+     *   - 关闭并丢弃 NWSClient 实例(包括其 EventEmitter 监听)
+     *   - 关闭当前 channel(无论 inbound/outbound), 并清理 inboundLinkPeerMap 反查项
+     *   - 拒绝该 peer 所有挂起请求, 防止永远等不到响应
+     *   - 触发一次 EventPeerDisconnected, 便于上层做联动清理
+     * @returns 是否真的存在并被清理过(全部不存在时返回 false)
+     */
+    unregisterService(peerId) {
+        if (!peerId) {
+            return false;
+        }
+        let touched = false;
+        if (this.peerConfigs.delete(peerId)) {
+            touched = true;
+        }
+        const reconnectTimer = this.reconnectTimers.get(peerId);
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            this.reconnectTimers.delete(peerId);
+            touched = true;
+        }
+        this.reconnectDelays.delete(peerId);
+        const client = this.clients.get(peerId);
+        if (client) {
+            // 先摘事件再 disconnect, 避免遗留闭包导致的内存悬挂
+            client.removeAllListeners();
+            client.disconnect();
+            this.clients.delete(peerId);
+            touched = true;
+        }
+        const channel = this.peerChannels.get(peerId);
+        if (channel) {
+            channel.status = 'closed';
+            try {
+                channel.close();
+            }
+            catch (err) {
+                this.emitError(new Error(`注销时关闭通道异常: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+            }
+            this.peerChannels.delete(peerId);
+            if (channel.direction === 'inbound') {
+                for (let [linkId, mappedPeer] of this.inboundLinkPeerMap.entries()) {
+                    if (mappedPeer === peerId) {
+                        this.inboundLinkPeerMap.delete(linkId);
+                        break;
+                    }
+                }
+            }
+            this.emit(NWSServiceHub.EventPeerDisconnected, peerId);
+            touched = true;
+        }
+        // 拒绝所有指向该 peer 的挂起请求, 调用方可立即得到失败而非等到超时
+        for (let [traceId, pending] of this.pendingRequests.entries()) {
+            if (pending.peerId === peerId) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(traceId);
+                pending.reject(new Error(`peer ${peerId} 已注销`));
+                touched = true;
+            }
+        }
+        if (touched) {
+            this.logInfo(`对端 ${peerId} 已注销并释放资源`);
+        }
+        return touched;
+    }
+    /** 启动当前节点的 WS 服务端能力，用于承接其他节点主动连入 */
+    startServer(port, host = '0.0.0.0') {
+        if (this.server) {
+            this.stopServer();
+        }
+        this.server = new NWSServer({ log: this.log });
+        this.server.on(NWSServer.EventError, (err) => this.emitError(err));
+        this.server.on(NWSServer.EventClientMessage, (linkId, data) => this.onInboundMessage(linkId, data));
+        this.server.on(NWSServer.EventClientDisconnected, (linkId) => this.onInboundDisconnected(linkId));
+        this.server.start(port, host);
+        this.logInfo(`服务端启动: ws://${host}:${port}`);
+    }
+    /** 停止当前节点的 WS 服务端能力（不影响已注册配置） */
+    stopServer() {
+        if (!this.server) {
+            return;
+        }
+        this.server.stop();
+        this.server.removeAllListeners();
+        this.server = null;
+    }
+    /** 按静态配置连接所有对端节点，并启动心跳 */
+    connectAll() {
+        for (let [peerId] of this.peerConfigs.entries()) {
+            this.ensurePeerConnected(peerId);
+        }
+        this.startHeartbeat();
+    }
+    /** 关闭 hub 的所有能力（客户端连接、服务端监听、定时器、挂起请求） */
+    disconnect() {
+        for (let timer of this.reconnectTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.reconnectTimers.clear();
+        this.reconnectDelays.clear();
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        for (let client of this.clients.values()) {
+            client.disconnect();
+        }
+        this.clients.clear();
+        for (let channel of this.peerChannels.values()) {
+            channel.close();
+        }
+        this.peerChannels.clear();
+        this.inboundLinkPeerMap.clear();
+        for (let pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('hub disconnected'));
+        }
+        this.pendingRequests.clear();
+        this.stopServer();
+    }
+    /**
+     * 向指定 peer 发起请求并等待响应。
+     * 泛型:
+     *   - TRes  返回值类型, 默认 any。建议显式指定以获得调用处的类型推导。
+     *   - TReq  请求体类型, 默认 any。一般可由 payload 自动推断, 必要时显式指定。
+     * 用法: const user = await hub.request<UserInfo>('nodeB', 'user', 'get', { id: 1 });
+     */
+    request(peerId, service, action, payload, timeoutMs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const channel = this.peerChannels.get(peerId);
+            if (!channel || channel.status !== 'connected') {
+                throw new Error(`peer ${peerId} 未连接`);
+            }
+            const traceId = this.genTraceId();
+            const packet = {
+                type: 'request',
+                nodeId: this.nodeId,
+                ts: Date.now(),
+                traceId,
+                service,
+                action,
+                payload,
+            };
+            const requestTimeout = timeoutMs || this.requestTimeoutMs;
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pendingRequests.delete(traceId);
+                    reject(new Error(`请求超时: ${service}.${action}`));
+                }, requestTimeout);
+                this.pendingRequests.set(traceId, { peerId, resolve, reject, timer });
+                const ok = channel.send(packet);
+                if (!ok) {
+                    clearTimeout(timer);
+                    this.pendingRequests.delete(traceId);
+                    reject(new Error(`发送失败: ${peerId}`));
+                }
+            });
+        });
+    }
+    /** 向指定 peer 发送 push 消息（单向，不等待响应） */
+    send(peerId, service, action, payload) {
+        const channel = this.peerChannels.get(peerId);
+        if (!channel || channel.status !== 'connected') {
+            return false;
+        }
+        return channel.send({
+            type: 'push',
+            nodeId: this.nodeId,
+            ts: Date.now(),
+            service,
+            action,
+            payload,
+        });
+    }
+    /** 发送底层协议包（高级接口） */
+    sendToPeer(peerId, packet) {
+        const channel = this.peerChannels.get(peerId);
+        if (!channel || channel.status !== 'connected') {
+            return false;
+        }
+        return channel.send(packet);
+    }
+    /** 注册请求处理器，匹配键为 service:action */
+    onRequest(service, action, handler) {
+        this.requestHandlers.set(this.makeRouteKey(service, action), handler);
+    }
+    /**
+     * 注销请求处理器(同 onRequest 一对)。
+     * @returns 之前是否注册过该路由(false 表示不存在, 不会报错)
+     */
+    offRequest(service, action) {
+        return this.requestHandlers.delete(this.makeRouteKey(service, action));
+    }
+    /** 注册 push 处理器，支持同一路由多个订阅者 */
+    onPush(service, action, handler) {
+        const key = this.makeRouteKey(service, action);
+        const handlers = this.pushHandlers.get(key) || [];
+        handlers.push(handler);
+        this.pushHandlers.set(key, handlers);
+    }
+    /**
+     * 注销 push 处理器:
+     *   - 传入 handler: 仅移除该具体 handler(若注册过多次会全部移除, 与 EventEmitter.off 习惯一致)
+     *   - 不传 handler: 移除该路由下所有 handler
+     * @returns 实际被移除的 handler 数量(0 表示无对应注册)
+     */
+    offPush(service, action, handler) {
+        const key = this.makeRouteKey(service, action);
+        const handlers = this.pushHandlers.get(key);
+        if (!handlers || handlers.length === 0) {
+            return 0;
+        }
+        if (!handler) {
+            const count = handlers.length;
+            this.pushHandlers.delete(key);
+            return count;
+        }
+        let removed = 0;
+        // 倒序遍历, splice 不会影响后续索引
+        for (let i = handlers.length - 1; i >= 0; i--) {
+            if (handlers[i] === handler) {
+                handlers.splice(i, 1);
+                removed++;
+            }
+        }
+        if (handlers.length === 0) {
+            this.pushHandlers.delete(key);
+        }
+        return removed;
+    }
+    ensurePeerConnected(peerId) {
+        const config = this.peerConfigs.get(peerId);
+        if (!(config === null || config === void 0 ? void 0 : config.url)) {
+            // 没有对端 URL 就无法主动发起连接，由对端作为"客户端"侧负责连入即可
+            return;
+        }
+        const existed = this.peerChannels.get(peerId);
+        if ((existed === null || existed === void 0 ? void 0 : existed.status) === 'connected') {
+            return;
+        }
+        let client = this.clients.get(peerId);
+        if (!client) {
+            client = new NWSClient({ log: this.log });
+            this.clients.set(peerId, client);
+            client.on(NWSClient.EventConnected, () => this.onOutboundConnected(peerId));
+            client.on(NWSClient.EventDisconnected, () => this.onOutboundDisconnected(peerId));
+            client.on(NWSClient.EventError, (err) => {
+                this.emitError(new Error(`对端 ${peerId} 连接异常: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+            });
+            client.on(NWSClient.EventMessage, (raw) => this.onOutboundMessage(peerId, raw));
+        }
+        client.connect(this.buildUrlWithToken(config.url, config.token));
+    }
+    /** 处理客户端连接成功 */
+    onOutboundConnected(peerId) {
+        var _a;
+        const client = this.clients.get(peerId);
+        if (!client) {
+            return;
+        }
+        // 连接成功后重置退避计数，下次断线从初始间隔重新开始
+        this.reconnectDelays.delete(peerId);
+        const channel = {
+            peerId,
+            direction: 'outbound',
+            send: (packet) => this.sendByClient(packet, client),
+            close: () => client.disconnect(),
+            lastActiveTime: Date.now(),
+            status: 'connected',
+        };
+        this.installOrArbitrateChannel(channel);
+        channel.send({
+            type: 'hello',
+            nodeId: this.nodeId,
+            ts: Date.now(),
+            token: (_a = this.peerConfigs.get(peerId)) === null || _a === void 0 ? void 0 : _a.token,
+        });
+    }
+    onOutboundDisconnected(peerId) {
+        const channel = this.peerChannels.get(peerId);
+        if ((channel === null || channel === void 0 ? void 0 : channel.direction) === 'outbound') {
+            channel.status = 'closed';
+            this.peerChannels.delete(peerId);
+            this.emit(NWSServiceHub.EventPeerDisconnected, peerId);
+        }
+        this.scheduleReconnect(peerId);
+    }
+    onOutboundMessage(peerId, raw) {
+        const packet = this.parsePacket(raw);
+        if (!packet) {
+            return;
+        }
+        const channel = this.peerChannels.get(peerId);
+        if (channel) {
+            channel.lastActiveTime = Date.now();
+        }
+        this.onPacket(peerId, packet);
+    }
+    /** 处理客户端消息 */
+    onInboundMessage(linkId, data) {
+        const packet = this.parsePacket(data);
+        if (!packet) {
+            return;
+        }
+        const peerId = packet.nodeId;
+        if (!peerId) {
+            return;
+        }
+        const sendFunc = (msg) => { var _a; return ((_a = this.server) === null || _a === void 0 ? void 0 : _a.sendToClient(linkId, msg)) || false; };
+        let channel = this.peerChannels.get(peerId);
+        if (!channel || channel.direction !== 'inbound') {
+            const newChannel = {
+                peerId,
+                direction: 'inbound',
+                send: (pack) => this.sendBySocket(pack, sendFunc),
+                close: () => { var _a; return (_a = this.server) === null || _a === void 0 ? void 0 : _a.disconnectClient(linkId); },
+                lastActiveTime: Date.now(),
+                status: 'connected',
+            };
+            this.inboundLinkPeerMap.set(linkId, peerId);
+            this.installOrArbitrateChannel(newChannel);
+            channel = this.peerChannels.get(peerId);
+        }
+        if (channel) {
+            channel.lastActiveTime = Date.now();
+        }
+        this.onPacket(peerId, packet);
+    }
+    /** 处理客户端断开连接 */
+    onInboundDisconnected(linkId) {
+        const peerId = this.inboundLinkPeerMap.get(linkId);
+        if (!peerId) {
+            return;
+        }
+        this.inboundLinkPeerMap.delete(linkId);
+        const channel = this.peerChannels.get(peerId);
+        if ((channel === null || channel === void 0 ? void 0 : channel.direction) === 'inbound') {
+            channel.status = 'closed';
+            this.peerChannels.delete(peerId);
+            this.emit(NWSServiceHub.EventPeerDisconnected, peerId);
+        }
+        // 重连只由"发起方(客户端)"负责：服务端不追客户端，避免对端不可达时持续重试。
+        // 若本节点同时也持有对端 URL，对端那侧自身会按其退避策略重连过来。
+    }
+    /** 安装或仲裁客户端连接 */
+    installOrArbitrateChannel(channel) {
+        const existed = this.peerChannels.get(channel.peerId);
+        if (!existed) {
+            this.peerChannels.set(channel.peerId, channel);
+            this.emit(NWSServiceHub.EventPeerConnected, channel.peerId);
+            return;
+        }
+        // 已存在连接时进行仲裁，确保同一对端最终只保留一个物理连接
+        const keep = this.shouldKeepOutbound(channel.peerId) ? 'outbound' : 'inbound';
+        if (channel.direction === keep) {
+            existed.close();
+            existed.status = 'closed';
+            this.peerChannels.set(channel.peerId, channel);
+            this.emit(NWSServiceHub.EventPeerConnected, channel.peerId);
+        }
+        else {
+            channel.close();
+            channel.status = 'closed';
+        }
+    }
+    /** 是否保持 outbound 连接 */
+    shouldKeepOutbound(peerId) {
+        // 固定仲裁规则：nodeId 字典序更大的节点保持 outbound。
+        // 这样 A/B 同时互连时会自然收敛为一条链路，不会形成双连接。
+        return this.nodeId > peerId;
+    }
+    onPacket(peerId, packet) {
+        switch (packet.type) {
+            case 'hello':
+                this.handleHello(peerId, packet);
+                break;
+            case 'hello_ack':
+                break;
+            case 'request':
+                this.handleRequest(peerId, packet);
+                break;
+            case 'response':
+                this.handleResponse(peerId, packet);
+                break;
+            case 'push':
+                this.handlePush(peerId, packet);
+                break;
+            case 'ping':
+                this.replyPong(peerId);
+                break;
+            case 'pong':
+                break;
+            default:
+                break;
+        }
+    }
+    handleHello(peerId, packet) {
+        const conf = this.peerConfigs.get(peerId);
+        if ((conf === null || conf === void 0 ? void 0 : conf.token) && conf.token !== packet.token) {
+            this.emitError(new Error(`对端 ${peerId} 鉴权失败`));
+            const channel = this.peerChannels.get(peerId);
+            channel === null || channel === void 0 ? void 0 : channel.close();
+            return;
+        }
+        const channel = this.peerChannels.get(peerId);
+        if (!channel || channel.status !== 'connected') {
+            return;
+        }
+        channel.send({
+            type: 'hello_ack',
+            nodeId: this.nodeId,
+            ts: Date.now(),
+            payload: { ok: true, nodeId: this.nodeId },
+        });
+    }
+    handleRequest(peerId, packet) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const traceId = packet.traceId || '';
+            if (!traceId || !packet.service || !packet.action) {
+                return;
+            }
+            const routeKey = this.makeRouteKey(packet.service, packet.action);
+            const handler = this.requestHandlers.get(routeKey);
+            if (!handler) {
+                this.sendResponse(peerId, traceId, 404, null, `未找到处理器: ${routeKey}`);
+                return;
+            }
+            try {
+                const result = yield handler(packet.payload, {
+                    peerId,
+                    service: packet.service,
+                    action: packet.action,
+                    traceId,
+                });
+                this.sendResponse(peerId, traceId, 0, result, 'ok');
+            }
+            catch (err) {
+                // 抛出端打印完整堆栈, 便于在本地排查; 对端只拿到精简的 message
+                if (this.log) {
+                    console.error(`[NWSServiceHub] 请求处理异常 ${routeKey} (peer=${peerId}, traceId=${traceId}):\n${(err === null || err === void 0 ? void 0 : err.stack) || err}`);
+                }
+                this.sendResponse(peerId, traceId, 500, null, (err === null || err === void 0 ? void 0 : err.message) || '请求处理失败');
+            }
+        });
+    }
+    handleResponse(peerId, packet) {
+        const traceId = packet.traceId || '';
+        const pending = this.pendingRequests.get(traceId);
+        if (!pending) {
+            return;
+        }
+        if (pending.peerId !== peerId) {
+            return;
+        }
+        // traceId 命中后立即清理挂起表，避免重复响应污染状态
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(traceId);
+        if ((packet.code || 0) !== 0) {
+            pending.reject(new Error(packet.message || '请求失败'));
+            return;
+        }
+        pending.resolve(packet.payload);
+    }
+    handlePush(peerId, packet) {
+        if (!packet.service || !packet.action) {
+            return;
+        }
+        const routeKey = this.makeRouteKey(packet.service, packet.action);
+        const handlers = this.pushHandlers.get(routeKey) || [];
+        for (let handler of handlers) {
+            try {
+                handler(packet.payload, {
+                    peerId,
+                    service: packet.service,
+                    action: packet.action,
+                });
+            }
+            catch (err) {
+                this.emitError(new Error(`push 回调异常: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+            }
+        }
+    }
+    sendResponse(peerId, traceId, code, payload, message) {
+        const channel = this.peerChannels.get(peerId);
+        if (!channel || channel.status !== 'connected') {
+            return;
+        }
+        channel.send({
+            type: 'response',
+            nodeId: this.nodeId,
+            ts: Date.now(),
+            traceId,
+            code,
+            payload,
+            message,
+        });
+    }
+    replyPong(peerId) {
+        const channel = this.peerChannels.get(peerId);
+        if (!channel || channel.status !== 'connected') {
+            return;
+        }
+        channel.send({
+            type: 'pong',
+            nodeId: this.nodeId,
+            ts: Date.now(),
+        });
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+        }
+        this.heartbeatTimer = setInterval(() => {
+            const now = Date.now();
+            const deadThresholdMs = this.heartbeatIntervalMs * this.heartbeatDeadFactor;
+            // 先快照一份待处理的死链，避免在遍历过程中修改 peerChannels 导致迭代异常
+            const deadPeers = [];
+            for (let [peerId, channel] of this.peerChannels.entries()) {
+                if (channel.status !== 'connected') {
+                    continue;
+                }
+                const idleMs = now - channel.lastActiveTime;
+                if (idleMs >= deadThresholdMs) {
+                    // 心跳判死：连续多个周期没有任何来自对端的数据(包括 pong)，认为链路已死
+                    deadPeers.push(peerId);
+                    continue;
+                }
+                if (idleMs >= this.heartbeatIntervalMs) {
+                    // 仅在空闲时发心跳，减少高频业务消息下的额外开销
+                    channel.send({
+                        type: 'ping',
+                        nodeId: this.nodeId,
+                        ts: now,
+                    });
+                }
+            }
+            for (let peerId of deadPeers) {
+                this.logInfo(`对端 ${peerId} 心跳超时，主动断开链路`);
+                this.handleChannelDead(peerId);
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    /**
+     * 断线后调度重连。
+     * 规则：
+     *   1) 只有"持有对端 URL"的一侧才会重连（即作为客户端发起方），
+     *      服务端只是被动承接，不会去追客户端，避免对端不可达时一直占用资源。
+     *   2) 采用指数退避：reconnectIntervalMs * 2 * 2 * ...，封顶 reconnectMaxIntervalMs，
+     *      连接成功后由 onOutboundConnected 清空 reconnectDelays 计数恢复初始间隔。
+     */
+    scheduleReconnect(peerId) {
+        const config = this.peerConfigs.get(peerId);
+        if (!(config === null || config === void 0 ? void 0 : config.url)) {
+            // 没有对端 URL 表示本节点是"被连入"的服务端侧，不主动重连
+            return;
+        }
+        if (this.reconnectTimers.has(peerId)) {
+            return;
+        }
+        const currentDelay = this.reconnectDelays.get(peerId) || this.reconnectIntervalMs;
+        const timer = setTimeout(() => {
+            this.reconnectTimers.delete(peerId);
+            // 失败时下一次延时翻倍，封顶 reconnectMaxIntervalMs
+            const nextDelay = Math.min(currentDelay * 2, this.reconnectMaxIntervalMs);
+            this.reconnectDelays.set(peerId, nextDelay);
+            this.ensurePeerConnected(peerId);
+        }, currentDelay);
+        this.reconnectTimers.set(peerId, timer);
+    }
+    /**
+     * 心跳判死后清理链路。
+     * 注意：channel.close() 内部走的是 client.disconnect()/server.disconnectClient()，
+     *      为防止重复进入正常断开回调流程，这里需要手动完成 peerChannels 清理与重连调度。
+     *      - outbound 死链：client.disconnect() 已抹掉监听不会回调，需要主动 scheduleReconnect。
+     *      - inbound  死链：server 的 close 事件可能仍会触发 onInboundDisconnected，
+     *                       但由于已先一步删除 inboundLinkPeerMap 项，回调会因找不到 peerId 直接返回。
+     */
+    handleChannelDead(peerId) {
+        const channel = this.peerChannels.get(peerId);
+        if (!channel) {
+            return;
+        }
+        const direction = channel.direction;
+        channel.status = 'closed';
+        try {
+            channel.close();
+        }
+        catch (err) {
+            this.emitError(new Error(`关闭死链异常: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+        }
+        this.peerChannels.delete(peerId);
+        if (direction === 'inbound') {
+            // 反向清理 linkId → peerId 映射，避免悬挂条目
+            for (let [linkId, mappedPeer] of this.inboundLinkPeerMap.entries()) {
+                if (mappedPeer === peerId) {
+                    this.inboundLinkPeerMap.delete(linkId);
+                    break;
+                }
+            }
+        }
+        this.emit(NWSServiceHub.EventPeerDisconnected, peerId);
+        if (direction === 'outbound') {
+            // 只有作为发起方时才重连，与 onOutboundDisconnected 行为保持一致
+            this.scheduleReconnect(peerId);
+        }
+    }
+    parsePacket(raw) {
+        let str;
+        if (typeof raw === 'string') {
+            str = raw;
+        }
+        else if (Buffer.isBuffer(raw)) {
+            str = raw.toString();
+        }
+        else if (raw === null || raw === void 0 ? void 0 : raw.toString) {
+            str = raw.toString();
+        }
+        else {
+            return null;
+        }
+        try {
+            const packet = JSON.parse(str);
+            if (!packet.type || !packet.nodeId) {
+                return null;
+            }
+            return packet;
+        }
+        catch (_a) {
+            // 非协议消息直接忽略，避免单条脏数据影响主流程
+            return null;
+        }
+    }
+    sendBySocket(packet, send) {
+        try {
+            send(JSON.stringify(packet));
+            return true;
+        }
+        catch (err) {
+            this.emitError(new Error(`发送失败: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+            return false;
+        }
+    }
+    sendByClient(packet, client) {
+        try {
+            return client.send(JSON.stringify(packet));
+        }
+        catch (err) {
+            this.emitError(new Error(`发送失败: ${(err === null || err === void 0 ? void 0 : err.message) || err}`));
+            return false;
+        }
+    }
+    makeRouteKey(service, action) {
+        return `${service}:${action}`;
+    }
+    buildUrlWithToken(url, token) {
+        if (!token) {
+            return url;
+        }
+        const hasQuery = url.includes('?');
+        const sep = hasQuery ? '&' : '?';
+        return `${url}${sep}token=${encodeURIComponent(token)}`;
+    }
+    genTraceId() {
+        this.traceCounter++;
+        return `${this.nodeId}-${Date.now()}-${this.traceCounter}`;
+    }
+    logInfo(msg) {
+        if (this.log) {
+            console.log(`[NWSServiceHub] ${msg}`);
+        }
+    }
+    emitError(err) {
+        this.emit(NWSServiceHub.EventError, err);
+        this.logInfo(`错误: ${err.message}`);
+    }
+}
+NWSServiceHub.EventPeerConnected = 'peer_connected';
+NWSServiceHub.EventPeerDisconnected = 'peer_disconnected';
+NWSServiceHub.EventError = 'error';
+export default NWSServiceHub;