lz-nframe 1.0.0

package/lib/NWSServiceHub.d.ts

@@ -0,0 +1,301 @@
+/*******************************************************************************
+文件: 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.路由
+*******************************************************************************/
+import { EventEmitter } from 'events';
+/**
+ * 协议名说明（PacketType）：
+ *
+ *  - 'hello'：握手请求。用于建立连接时，主动方向发起，包含节点身份与鉴权信息。
+ *  - 'hello_ack'：握手响应。收到 'hello' 后回复，表明握手/鉴权通过。
+ *  - 'request'：请求。发起业务请求，需服务端处理并返回响应。
+ *  - 'response'：响应。对应 'request'，携带结果返回发起方。
+ *  - 'push'：推送消息。用于无应答的单向推送，不需要业务响应。
+ *  - 'ping'：心跳检测。定期发送以检测链路活跃状态并防止断线。
+ *  - 'pong'：心跳响应。收到 'ping' 后回复，以确认链接正常。
+ */
+type PacketType = 'hello' | 'hello_ack' | 'request' | 'response' | 'push' | 'ping' | 'pong';
+export interface NWSServiceHubOptions {
+    /** 当前节点唯一标识（用于仲裁单连接） */
+    nodeId: string;
+    /** 记录日志 */
+    log?: boolean;
+    /** 默认请求超时时间 */
+    requestTimeoutMs?: number;
+    /** 心跳间隔（毫秒） */
+    heartbeatIntervalMs?: number;
+    /** 重连初始间隔（毫秒），首次断线后等待的时间 */
+    reconnectIntervalMs?: number;
+    /** 重连最大间隔（毫秒），指数退避封顶值，避免对端长时间宕机时高频重试 */
+    reconnectMaxIntervalMs?: number;
+    /** 心跳判死倍数：连续 N 个心跳周期未收到任何数据则视为死链，默认 3 */
+    heartbeatDeadFactor?: number;
+}
+/** 对端配置 */
+export interface NWSServicePeerConfig {
+    /** 对端节点唯一标识 */
+    nodeId: string;
+    /** 对端服务地址（例如 http://127.0.0.1:9001） */
+    url?: string;
+    /** 对端鉴权 token（握手时发送与校验） */
+    token?: string;
+}
+/**
+ * NWS 内部协议包。
+ * 泛型 T 表示 payload 的类型:
+ *   - request/push 时通常是业务请求体或推送数据体
+ *   - response 时通常是业务返回值
+ *   - hello_ack 等控制包也可放少量控制信息
+ */
+interface NWSProtocolPacket<T = any> {
+    /** 包类型, 决定 onPacket 后续分发到哪个处理流程 */
+    type: PacketType;
+    /** 发包方节点 id, 用于识别对端身份以及建立 peerId 映射 */
+    nodeId: string;
+    /** 发包时间戳(毫秒), 主要用于排查日志和链路观测 */
+    ts: number;
+    /** 请求追踪 id, request/response 必填; push/心跳/握手通常不需要 */
+    traceId?: string;
+    /** 业务服务名, request/response/push 路由的一部分 */
+    service?: string;
+    /** 业务动作名, request/response/push 路由的一部分 */
+    action?: string;
+    /** 协议携带的数据体, 由不同 PacketType 决定具体含义 */
+    payload?: T;
+    /** 响应状态码, response 使用; 0 表示成功, 非 0 表示失败 */
+    code?: number;
+    /** 响应或错误描述, response 使用; 对端异常时只传精简 message */
+    message?: string;
+    /** 握手鉴权 token, hello 使用 */
+    token?: string;
+}
+/**
+ * 请求处理器类型(对应 'request' 包)。
+ *   - payload     对端发来的请求体
+ *   - ctx.peerId  发起方节点 id
+ *   - ctx.service 路由 service 名
+ *   - ctx.action  路由 action 名
+ *   - ctx.traceId 本次请求的追踪 id, 与对端 pendingRequest 一一对应
+ *   - 返回值      可同步返回, 也可返回 Promise; 抛异常会被 catch 后以 code=500 回 response
+ */
+type RequestHandler = (payload: any, ctx: {
+    peerId: string;
+    service: string;
+    action: string;
+    traceId: string;
+}) => Promise<any> | any;
+/**
+ * 推送处理器类型(对应 'push' 包, 单向, 无响应)。
+ *   - payload     对端推送的数据体
+ *   - ctx.peerId  发起方节点 id
+ *   - ctx.service 路由 service 名
+ *   - ctx.action  路由 action 名
+ *   - 没有 traceId, 因为 push 不需要回包匹配
+ *   - 同一路由可注册多个 handler, 按注册顺序依次回调; 单个 handler 抛错会被框架捕获并通过 EventError 抛出, 不影响其它 handler
+ */
+type PushHandler = (payload: any, ctx: {
+    peerId: string;
+    service: string;
+    action: string;
+}) => void;
+export default class NWSServiceHub extends EventEmitter {
+    static EventPeerConnected: string;
+    static EventPeerDisconnected: string;
+    static EventError: string;
+    /** 节点唯一标识 */
+    private readonly nodeId;
+    /** 是否记录日志 */
+    private readonly log;
+    /** 请求超时时间 */
+    private readonly requestTimeoutMs;
+    /** 心跳间隔 */
+    private readonly heartbeatIntervalMs;
+    /** 重连初始间隔 */
+    private readonly reconnectIntervalMs;
+    /** 重连最大间隔（指数退避封顶） */
+    private readonly reconnectMaxIntervalMs;
+    /** 心跳判死倍数 */
+    private readonly heartbeatDeadFactor;
+    private server;
+    private readonly peerConfigs;
+    private readonly clients;
+    private readonly peerChannels;
+    private readonly inboundLinkPeerMap;
+    private readonly pendingRequests;
+    private readonly requestHandlers;
+    private readonly pushHandlers;
+    private readonly reconnectTimers;
+    /** 当前每个 peer 的下一次重连等待时长（毫秒），用于指数退避 */
+    private readonly reconnectDelays;
+    private heartbeatTimer;
+    /** 请求追踪计数器 */
+    private traceCounter;
+    constructor(options: NWSServiceHubOptions);
+    registerService(config: NWSServicePeerConfig): void;
+    /**
+     * 注销已注册的对端服务, 完成完整资源释放:
+     *   - 删除静态配置 peerConfigs(避免后续被 connectAll 再次拉起)
+     *   - 取消该对端的重连定时器并清空退避计数
+     *   - 关闭并丢弃 NWSClient 实例(包括其 EventEmitter 监听)
+     *   - 关闭当前 channel(无论 inbound/outbound), 并清理 inboundLinkPeerMap 反查项
+     *   - 拒绝该 peer 所有挂起请求, 防止永远等不到响应
+     *   - 触发一次 EventPeerDisconnected, 便于上层做联动清理
+     * @returns 是否真的存在并被清理过(全部不存在时返回 false)
+     */
+    unregisterService(peerId: string): boolean;
+    /** 启动当前节点的 WS 服务端能力，用于承接其他节点主动连入 */
+    startServer(port: number, host?: string): void;
+    /** 停止当前节点的 WS 服务端能力（不影响已注册配置） */
+    stopServer(): void;
+    /** 按静态配置连接所有对端节点，并启动心跳 */
+    connectAll(): void;
+    /** 关闭 hub 的所有能力（客户端连接、服务端监听、定时器、挂起请求） */
+    disconnect(): void;
+    /**
+     * 向指定 peer 发起请求并等待响应。
+     * 泛型:
+     *   - TRes  返回值类型, 默认 any。建议显式指定以获得调用处的类型推导。
+     *   - TReq  请求体类型, 默认 any。一般可由 payload 自动推断, 必要时显式指定。
+     * 用法: const user = await hub.request<UserInfo>('nodeB', 'user', 'get', { id: 1 });
+     */
+    request<TRes = any, TReq = any>(peerId: string, service: string, action: string, payload: TReq, timeoutMs?: number): Promise<TRes>;
+    /** 向指定 peer 发送 push 消息（单向，不等待响应） */
+    send(peerId: string, service: string, action: string, payload: any): boolean;
+    /** 发送底层协议包（高级接口） */
+    sendToPeer(peerId: string, packet: NWSProtocolPacket): boolean;
+    /** 注册请求处理器，匹配键为 service:action */
+    onRequest(service: string, action: string, handler: RequestHandler): void;
+    /**
+     * 注销请求处理器(同 onRequest 一对)。
+     * @returns 之前是否注册过该路由(false 表示不存在, 不会报错)
+     */
+    offRequest(service: string, action: string): boolean;
+    /** 注册 push 处理器，支持同一路由多个订阅者 */
+    onPush(service: string, action: string, handler: PushHandler): void;
+    /**
+     * 注销 push 处理器:
+     *   - 传入 handler: 仅移除该具体 handler(若注册过多次会全部移除, 与 EventEmitter.off 习惯一致)
+     *   - 不传 handler: 移除该路由下所有 handler
+     * @returns 实际被移除的 handler 数量(0 表示无对应注册)
+     */
+    offPush(service: string, action: string, handler?: PushHandler): number;
+    private ensurePeerConnected;
+    /** 处理客户端连接成功 */
+    private onOutboundConnected;
+    private onOutboundDisconnected;
+    private onOutboundMessage;
+    /** 处理客户端消息 */
+    private onInboundMessage;
+    /** 处理客户端断开连接 */
+    private onInboundDisconnected;
+    /** 安装或仲裁客户端连接 */
+    private installOrArbitrateChannel;
+    /** 是否保持 outbound 连接 */
+    private shouldKeepOutbound;
+    private onPacket;
+    private handleHello;
+    private handleRequest;
+    private handleResponse;
+    private handlePush;
+    private sendResponse;
+    private replyPong;
+    private startHeartbeat;
+    /**
+     * 断线后调度重连。
+     * 规则：
+     *   1) 只有"持有对端 URL"的一侧才会重连（即作为客户端发起方），
+     *      服务端只是被动承接，不会去追客户端，避免对端不可达时一直占用资源。
+     *   2) 采用指数退避：reconnectIntervalMs * 2 * 2 * ...，封顶 reconnectMaxIntervalMs，
+     *      连接成功后由 onOutboundConnected 清空 reconnectDelays 计数恢复初始间隔。
+     */
+    private scheduleReconnect;
+    /**
+     * 心跳判死后清理链路。
+     * 注意：channel.close() 内部走的是 client.disconnect()/server.disconnectClient()，
+     *      为防止重复进入正常断开回调流程，这里需要手动完成 peerChannels 清理与重连调度。
+     *      - outbound 死链：client.disconnect() 已抹掉监听不会回调，需要主动 scheduleReconnect。
+     *      - inbound  死链：server 的 close 事件可能仍会触发 onInboundDisconnected，
+     *                       但由于已先一步删除 inboundLinkPeerMap 项，回调会因找不到 peerId 直接返回。
+     */
+    private handleChannelDead;
+    private parsePacket;
+    private sendBySocket;
+    private sendByClient;
+    private makeRouteKey;
+    private buildUrlWithToken;
+    private genTraceId;
+    private logInfo;
+    private emitError;
+}
+export {};