@lyrify/znl 0.5.2 → 0.6.0

package/src/ZNL.js

@@ -49,6 +49,7 @@ import {
   buildRegisterFrames,
   buildUnregisterFrames,
   buildHeartbeatFrames,
+  buildHeartbeatAckFrames,
   buildRequestFrames,
   buildResponseFrames,
   buildPublishFrames,
@@ -127,13 +128,19 @@ export class ZNL extends EventEmitter {
   /** @type {boolean} 是否启用 payload 摘要校验（安全模式用） */
   #enablePayloadDigest = DEFAULT_ENABLE_PAYLOAD_DIGEST;
 
+  /** @type {Map<string, string>} master 侧 authKey 配置表（按 slaveId） */
+  #authKeyMap = new Map();
+
+  /** @type {Map<string, { signKey: Buffer, encryptKey: Buffer }>} master 侧派生密钥缓存 */
+  #slaveKeyCache = new Map();
+
   // ─── PUB/SUB 状态 ────────────────────────────────────────────────────────
 
   /**
    * master 侧：已注册的在线 slave 表
    * key   = slaveId（字符串）
-   * value = { identity: Buffer, lastSeen: number }
-   * @type {Map<string, { identity: Buffer, lastSeen: number }>}
+   * value = { identity: Buffer, lastSeen: number, signKey: Buffer|null, encryptKey: Buffer|null }
+   * @type {Map<string, { identity: Buffer, lastSeen: number, signKey: Buffer|null, encryptKey: Buffer|null }>}
    */
   #slaves = new Map();
 
@@ -148,9 +155,24 @@ export class ZNL extends EventEmitter {
   /** 心跳间隔（ms），0 表示禁用；slave/master 共用同一配置 */
   #heartbeatInterval;
 
-  /** slave 侧发送心跳的定时器句柄 */
+  /** slave 侧单次心跳调度定时器句柄 */
   #heartbeatTimer = null;
 
+  /** slave 侧等待心跳应答的超时定时器句柄 */
+  #heartbeatAckTimer = null;
+
+  /** slave 侧当前是否存在未确认的心跳 */
+  #heartbeatWaitingAck = false;
+
+  /** slave 侧最近一次确认主节点在线的时间戳 */
+  #lastMasterSeenAt = 0;
+
+  /** slave 侧缓存的主节点在线状态 */
+  #masterOnline = false;
+
+  /** slave 侧正在进行的 Dealer 重连 Promise（防止并发重连） */
+  #dealerReconnectPromise = null;
+
   /** master 侧扫描死节点的定时器句柄 */
   #heartbeatCheckTimer = null;
 
@@ -185,6 +207,7 @@ export class ZNL extends EventEmitter {
    *   endpoints?         : { router?: string },
    *   maxPending?          : number,
    *   authKey?             : string,
+   *   authKeyMap?          : Record<string, string>,
    *   heartbeatInterval?   : number,
    *   heartbeatTimeoutMs?  : number,
    *   encrypted?           : boolean,
@@ -199,6 +222,7 @@ export class ZNL extends EventEmitter {
     endpoints = {},
     maxPending = DEFAULT_MAX_PENDING,
     authKey = "",
+    authKeyMap = null,
     heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL,
     heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS,
     encrypted = false,
@@ -220,16 +244,35 @@ export class ZNL extends EventEmitter {
     this.endpoints = { ...DEFAULT_ENDPOINTS, ...endpoints };
     this.authKey = authKey == null ? "" : String(authKey);
 
+    if (this.role === "master") {
+      if (authKeyMap != null) {
+        if (typeof authKeyMap !== "object") {
+          throw new TypeError(
+            "`authKeyMap` 必须是对象（slaveId -> authKey）。",
+          );
+        }
+        for (const [slaveId, key] of Object.entries(authKeyMap)) {
+          if (key == null) continue;
+          this.#authKeyMap.set(String(slaveId), String(key));
+        }
+      }
+    }
+
     this.encrypted = Boolean(encrypted);
     this.#secureEnabled = this.encrypted;
 
     if (this.#secureEnabled) {
-      if (!this.authKey) {
-        throw new Error("启用 encrypted=true 时，必须提供非空 authKey。");
+      const hasAuthMap = this.role === "master" && authKeyMap != null;
+      if (!this.authKey && !hasAuthMap) {
+        throw new Error(
+          "启用 encrypted=true 时，必须提供非空 authKey 或 authKeyMap。",
+        );
+      }
+      if (this.authKey) {
+        const { signKey, encryptKey } = deriveKeys(this.authKey);
+        this.#signKey = signKey;
+        this.#encryptKey = encryptKey;
       }
-      const { signKey, encryptKey } = deriveKeys(this.authKey);
-      this.#signKey = signKey;
-      this.#encryptKey = encryptKey;
     }
 
     this.#pending = new PendingManager(maxPending);
@@ -356,19 +399,34 @@ export class ZNL extends EventEmitter {
     if (this.#slaves.size === 0) return;
 
     const topicText = String(topic);
-    const payloadFrames = this.#sealPayloadFrames(
-      "publish",
-      topicText,
-      payload,
-    );
-    const authProof = this.#secureEnabled
-      ? this.#createAuthProof("publish", topicText, payloadFrames)
-      : "";
-
-    const frames = buildPublishFrames(topicText, payloadFrames, authProof);
 
     for (const [slaveId, entry] of this.#slaves) {
+      const keys = this.#secureEnabled ? this.#resolveSlaveKeys(slaveId) : null;
+      if (this.#secureEnabled && !keys) {
+        if (this.#slaves.delete(slaveId)) {
+          this.emit("slave_disconnected", slaveId);
+        }
+        continue;
+      }
+
+      const payloadFrames = this.#sealPayloadFrames(
+        "publish",
+        topicText,
+        payload,
+        keys?.encryptKey ?? null,
+      );
+      const authProof = this.#secureEnabled
+        ? this.#createAuthProof(
+            "publish",
+            topicText,
+            payloadFrames,
+            keys.signKey,
+          )
+        : "";
+
+      const frames = buildPublishFrames(topicText, payloadFrames, authProof);
       const idFrame = identityToBuffer(entry.identity);
+
       this.#sendQueue
         .enqueue("router", () => socket.send([idFrame, ...frames]))
         .catch(() => {
@@ -424,6 +482,84 @@ export class ZNL extends EventEmitter {
     return [...this.#slaves.keys()];
   }
 
+  /**
+   * 【Slave 侧】当前已确认的主节点在线状态
+   * - 仅在 slave 角色下有意义
+   * - 收到合法 heartbeat_ack / request / response / publish 时置为 true
+   * - 心跳应答超时、重连、stop 时置为 false
+   */
+  get masterOnline() {
+    return this.role === "slave" ? this.#masterOnline : false;
+  }
+
+  /**
+   * 【Slave 侧】查询当前主节点是否在线
+   * 说明：
+   * - 这是对外公开的轻量 API，适合业务层主动轮询
+   * - 返回值基于最近一次链路确认结果，而非一次实时网络探测
+   * @returns {boolean}
+   */
+  isMasterOnline() {
+    return this.masterOnline;
+  }
+
+  /**
+   * 【Master 侧】动态添加/更新某个 slave 的 authKey（立即生效）
+   * @param {string} slaveId
+   * @param {string} authKey
+   * @returns {this}
+   */
+  addAuthKey(slaveId, authKey) {
+    if (this.role !== "master") {
+      throw new Error("addAuthKey() 只能在 master 侧调用。");
+    }
+    const id = String(slaveId ?? "");
+    if (!id) {
+      throw new Error("slaveId 不能为空。");
+    }
+    const key = authKey == null ? "" : String(authKey);
+    if (!key) {
+      throw new Error("authKey 不能为空。");
+    }
+
+    this.#authKeyMap.set(id, key);
+
+    if (this.#secureEnabled) {
+      const derived = deriveKeys(key);
+      this.#slaveKeyCache.set(id, derived);
+      const entry = this.#slaves.get(id);
+      if (entry) {
+        entry.signKey = derived.signKey;
+        entry.encryptKey = derived.encryptKey;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * 【Master 侧】移除某个 slave 的 authKey（立即生效）
+   * @param {string} slaveId
+   * @returns {this}
+   */
+  removeAuthKey(slaveId) {
+    if (this.role !== "master") {
+      throw new Error("removeAuthKey() 只能在 master 侧调用。");
+    }
+    const id = String(slaveId ?? "");
+    if (!id) {
+      throw new Error("slaveId 不能为空。");
+    }
+
+    this.#authKeyMap.delete(id);
+    this.#slaveKeyCache.delete(id);
+
+    if (this.#slaves.has(id)) {
+      this.#slaves.delete(id);
+      this.emit("slave_disconnected", id);
+    }
+    return this;
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   //  生命周期内部实现
   // ═══════════════════════════════════════════════════════════════════════════
@@ -450,8 +586,13 @@ export class ZNL extends EventEmitter {
    */
   async #doStop() {
     if (this.role === "slave" && this.#sockets.dealer) {
-      clearInterval(this.#heartbeatTimer);
+      clearTimeout(this.#heartbeatTimer);
+      clearTimeout(this.#heartbeatAckTimer);
       this.#heartbeatTimer = null;
+      this.#heartbeatAckTimer = null;
+      this.#heartbeatWaitingAck = false;
+      this.#masterOnline = false;
+      this.#lastMasterSeenAt = 0;
 
       await this.#sendQueue
         .enqueue("dealer", () =>
@@ -470,9 +611,11 @@ export class ZNL extends EventEmitter {
    * 顺序：停止定时器 → 关闭 socket → 等待读循环退出 → 清空所有注册表
    */
   async #teardown() {
-    clearInterval(this.#heartbeatTimer);
+    clearTimeout(this.#heartbeatTimer);
+    clearTimeout(this.#heartbeatAckTimer);
     clearInterval(this.#heartbeatCheckTimer);
     this.#heartbeatTimer = null;
+    this.#heartbeatAckTimer = null;
     this.#heartbeatCheckTimer = null;
 
     for (const socket of Object.values(this.#sockets)) {
@@ -486,7 +629,12 @@ export class ZNL extends EventEmitter {
     this.#sockets = {};
     this.#sendQueue.clear();
     this.#slaves.clear();
+    this.#slaveKeyCache.clear();
     this.#masterNodeId = null;
+    this.#masterOnline = false;
+    this.#lastMasterSeenAt = 0;
+    this.#heartbeatWaitingAck = false;
+    this.#dealerReconnectPromise = null;
     this.#replayGuard.clear();
   }
 
@@ -498,7 +646,7 @@ export class ZNL extends EventEmitter {
    * 初始化 Master 侧 ROUTER socket（bind 模式），并启动读循环和死节点扫描定时器
    */
   async #startMasterSockets() {
-    const router = new zmq.Router();
+    const router = new zmq.Router({ handover: true });
     await router.bind(this.endpoints.router);
     this.#sockets.router = router;
 
@@ -511,23 +659,17 @@ export class ZNL extends EventEmitter {
    * 连接后立即发送注册帧，再启动心跳定时器
    */
   async #startSlaveSockets() {
-    const dealer = new zmq.Dealer({ routingId: this.id });
-    dealer.connect(this.endpoints.router);
-    this.#sockets.dealer = dealer;
-
-    this.#consume(dealer, (frames) => this.#handleDealerFrames(frames));
+    this.#masterOnline = false;
+    this.#lastMasterSeenAt = 0;
+    this.#heartbeatWaitingAck = false;
 
-    // 注册帧：
-    // - encrypted=true  : 发送签名证明令牌（放在 authKey 字段位）
-    // - encrypted=false : 不携带认证信息
-    const registerToken = this.#secureEnabled
-      ? this.#createAuthProof("register", "", [])
-      : "";
-
-    await this.#sendQueue.enqueue("dealer", () =>
-      dealer.send(buildRegisterFrames(registerToken)),
-    );
+    const dealer = this.#createDealerSocket();
+    this.#sockets.dealer = dealer;
 
+    // 注册帧改为“尽力发送”：
+    // - master 尚未上线时无需阻塞启动流程
+    // - 后续 heartbeat_ack 成功后仍可自然恢复在线状态
+    this.#trySendRegister();
     this.#startHeartbeat();
   }
 
@@ -554,42 +696,92 @@ export class ZNL extends EventEmitter {
 
     // ── 心跳 ────────────────────────────────────────────────────────────────
     if (parsed.kind === "heartbeat") {
+      let ackFrames = buildHeartbeatAckFrames();
+
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "heartbeat",
           proofToken: parsed.authProof,
           requestId: "",
           payloadFrames: [],
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
+
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+
+        ackFrames = buildHeartbeatAckFrames(
+          this.#createAuthProof("heartbeat_ack", "", [], keys.signKey),
+        );
+      } else {
+        // 心跳视为在线确认：必要时自动补注册
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
       }
 
-      // 心跳视为在线确认：必要时自动补注册
-      this.#ensureSlaveOnline(identityText, identity, { touch: true });
+      await this.#sendQueue
+        .enqueue("router", () =>
+          this.#sockets.router.send([identityToBuffer(identity), ...ackFrames]),
+        )
+        .catch(() => {});
       return;
     }
 
     // ── 注册 ────────────────────────────────────────────────────────────────
     if (parsed.kind === "register") {
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "register",
           proofToken: parsed.authKey, // register 复用 authKey 字段承载 proof
           requestId: "",
           payloadFrames: [],
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
           return;
         }
+
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
+        return;
       }
 
-      this.#slaves.set(identityText, { identity, lastSeen: Date.now() });
+      this.#slaves.set(identityText, {
+        identity,
+        lastSeen: Date.now(),
+        signKey: null,
+        encryptKey: null,
+      });
       this.emit("slave_connected", identityText);
       return;
     }
@@ -607,12 +799,22 @@ export class ZNL extends EventEmitter {
       let finalFrames = parsed.payloadFrames;
 
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "request",
           proofToken: parsed.authKey, // request 复用 authKey 字段承载 proof
           requestId: parsed.requestId,
           payloadFrames: parsed.payloadFrames,
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
@@ -620,7 +822,11 @@ export class ZNL extends EventEmitter {
         }
 
         // 认证通过后允许补注册（避免 master 重启后丢失在线表）
-        this.#ensureSlaveOnline(identityText, identity, { touch: true });
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
 
         if (this.encrypted) {
           try {
@@ -629,6 +835,7 @@ export class ZNL extends EventEmitter {
               parsed.requestId,
               parsed.payloadFrames,
               identityText,
+              keys.encryptKey,
             );
           } catch (error) {
             this.#emitAuthFailed(
@@ -663,12 +870,22 @@ export class ZNL extends EventEmitter {
       let finalFrames = parsed.payloadFrames;
 
       if (this.#secureEnabled) {
+        const keys = this.#resolveSlaveKeys(identityText);
+        if (!keys) {
+          this.#emitAuthFailed(event, "未配置该 slave 的 authKey。");
+          if (this.#slaves.delete(identityText)) {
+            this.emit("slave_disconnected", identityText);
+          }
+          return;
+        }
+
         const v = this.#verifyIncomingProof({
           kind: "response",
           proofToken: parsed.authProof,
           requestId: parsed.requestId,
           payloadFrames: parsed.payloadFrames,
           expectedNodeId: identityText,
+          signKey: keys.signKey,
         });
         if (!v.ok) {
           this.#emitAuthFailed(event, v.error);
@@ -676,7 +893,11 @@ export class ZNL extends EventEmitter {
         }
 
         // 认证通过后允许补注册（避免 master 重启后丢失在线表）
-        this.#ensureSlaveOnline(identityText, identity, { touch: true });
+        this.#ensureSlaveOnline(identityText, identity, {
+          touch: true,
+          signKey: keys.signKey,
+          encryptKey: keys.encryptKey,
+        });
 
         if (this.encrypted) {
           try {
@@ -685,6 +906,7 @@ export class ZNL extends EventEmitter {
               parsed.requestId,
               parsed.payloadFrames,
               identityText,
+              keys.encryptKey,
             );
           } catch (error) {
             this.#emitAuthFailed(
@@ -717,6 +939,28 @@ export class ZNL extends EventEmitter {
 
     const event = this.#buildAndEmit("dealer", frames, { payload, ...parsed });
 
+    // ── 心跳应答：master -> slave ──────────────────────────────────────────
+    if (parsed.kind === "heartbeat_ack") {
+      if (this.#secureEnabled) {
+        const v = this.#verifyIncomingProof({
+          kind: "heartbeat_ack",
+          proofToken: parsed.authProof,
+          requestId: "",
+          payloadFrames: [],
+          expectedNodeId: this.#masterNodeId,
+        });
+        if (!v.ok) {
+          this.#emitAuthFailed(event, v.error);
+          return;
+        }
+
+        if (!this.#masterNodeId) this.#masterNodeId = v.envelope.nodeId;
+      }
+
+      this.#confirmMasterReachable({ scheduleNextHeartbeat: true });
+      return;
+    }
+
     // ── PUB 广播：master -> slave ──────────────────────────────────────────
     if (parsed.kind === "publish") {
       let finalFrames = parsed.payloadFrames;
@@ -755,6 +999,8 @@ export class ZNL extends EventEmitter {
         }
       }
 
+      this.#confirmMasterReachable({ scheduleNextHeartbeat: true });
+
       const finalPayload = payloadFromFrames(finalFrames);
       const pubEvent = { topic: parsed.topic, payload: finalPayload };
 
@@ -808,6 +1054,8 @@ export class ZNL extends EventEmitter {
         }
       }
 
+      this.#confirmMasterReachable({ scheduleNextHeartbeat: true });
+
       const finalPayload = payloadFromFrames(finalFrames);
       const requestEvent = { ...event, payload: finalPayload };
       this.emit("request", requestEvent);
@@ -860,6 +1108,8 @@ export class ZNL extends EventEmitter {
         }
       }
 
+      this.#confirmMasterReachable({ scheduleNextHeartbeat: true });
+
       const finalPayload = payloadFromFrames(finalFrames);
       const responseEvent = { ...event, payload: finalPayload };
       const key = this.#pending.key(parsed.requestId);
@@ -927,13 +1177,21 @@ export class ZNL extends EventEmitter {
       identityText,
     );
 
+    const keys = this.#secureEnabled
+      ? this.#resolveSlaveKeys(identityText)
+      : null;
+    if (this.#secureEnabled && !keys) {
+      throw new Error(`未配置该 slave 的 authKey：${identityText}`);
+    }
+
     const payloadFrames = this.#sealPayloadFrames(
       "request",
       requestId,
       payload,
+      keys?.encryptKey ?? null,
     );
     const proofOrAuthKey = this.#secureEnabled
-      ? this.#createAuthProof("request", requestId, payloadFrames)
+      ? this.#createAuthProof("request", requestId, payloadFrames, keys.signKey)
       : "";
 
     const frames = buildRequestFrames(requestId, payloadFrames, proofOrAuthKey);
@@ -981,15 +1239,29 @@ export class ZNL extends EventEmitter {
    */
   async #replyTo(identity, requestId, payload) {
     const socket = this.#requireSocket("router", "ROUTER");
+    const identityText = identityToString(identity);
     const idFrame = identityToBuffer(identity);
 
+    const keys = this.#secureEnabled
+      ? this.#resolveSlaveKeys(identityText)
+      : null;
+    if (this.#secureEnabled && !keys) {
+      throw new Error(`未配置该 slave 的 authKey：${identityText}`);
+    }
+
     const payloadFrames = this.#sealPayloadFrames(
       "response",
       requestId,
       payload,
+      keys?.encryptKey ?? null,
     );
     const authProof = this.#secureEnabled
-      ? this.#createAuthProof("response", requestId, payloadFrames)
+      ? this.#createAuthProof(
+          "response",
+          requestId,
+          payloadFrames,
+          keys.signKey,
+        )
       : "";
 
     const frames = buildResponseFrames(requestId, payloadFrames, authProof);
@@ -1003,27 +1275,235 @@ export class ZNL extends EventEmitter {
   // ═══════════════════════════════════════════════════════════════════════════
 
   /**
-   * 启动 slave 侧心跳发送定时器
+   * 创建并初始化 slave 侧 Dealer socket
+   * 设计要点：
+   * - immediate=true：仅向已完成连接的 pipe 发送，避免离线期间无限积压旧消息
+   * - linger=0     ：关闭旧 socket 时直接丢弃残留发送队列，避免旧心跳回灌
+   * - sendTimeout=0：尽力发送，当前不可发时立即失败，不阻塞重连/启动流程
+   *
+   * @returns {import("zeromq").Dealer}
+   */
+  #createDealerSocket() {
+    const dealer = new zmq.Dealer({
+      routingId: this.id,
+      immediate: true,
+      linger: 0,
+      sendTimeout: 0,
+      reconnectInterval: 200,
+      reconnectMaxInterval: 1000,
+    });
+
+    dealer.connect(this.endpoints.router);
+    this.#consume(dealer, (frames) => this.#handleDealerFrames(frames));
+    return dealer;
+  }
+
+  /**
+   * 尝试发送注册帧
+   * 说明：
+   * - 该操作是“尽力发送”，不阻塞启动流程
+   * - master 未上线时允许静默失败，由后续 heartbeat_ack 驱动恢复
+   */
+  #trySendRegister() {
+    if (this.role !== "slave" || !this.running || !this.#sockets.dealer) return;
+
+    const registerToken = this.#secureEnabled
+      ? this.#createAuthProof("register", "", [])
+      : "";
+
+    this.#sendQueue
+      .enqueue("dealer", () =>
+        this.#sockets.dealer.send(buildRegisterFrames(registerToken)),
+      )
+      .catch(() => {});
+  }
+
+  /**
+   * 标记主节点已确认在线
+   */
+  #markMasterOnline() {
+    this.#masterOnline = true;
+    this.#lastMasterSeenAt = Date.now();
+  }
+
+  /**
+   * 标记主节点离线，并清理当前等待中的心跳状态
+   */
+  #markMasterOffline() {
+    this.#masterOnline = false;
+    this.#lastMasterSeenAt = 0;
+    this.#heartbeatWaitingAck = false;
+    clearTimeout(this.#heartbeatAckTimer);
+    this.#heartbeatAckTimer = null;
+  }
+
+  /**
+   * 确认链路已打通
+   * - heartbeat_ack 是最直接的确认信号
+   * - 其他来自 master 的合法业务帧同样证明链路可达
+   *
+   * @param {{ scheduleNextHeartbeat?: boolean }} [options]
+   */
+  #confirmMasterReachable({ scheduleNextHeartbeat = false } = {}) {
+    this.#markMasterOnline();
+
+    if (!this.#heartbeatWaitingAck) return;
+
+    this.#heartbeatWaitingAck = false;
+    clearTimeout(this.#heartbeatAckTimer);
+    this.#heartbeatAckTimer = null;
+
+    if (scheduleNextHeartbeat && this.#heartbeatInterval > 0) {
+      this.#scheduleNextHeartbeat();
+    }
+  }
+
+  /**
+   * 计算心跳应答超时时间
+   * - 优先复用用户配置的 heartbeatTimeoutMs
+   * - 未配置时回退到 interval × 2，且至少 1000ms
+   */
+  #resolveHeartbeatAckTimeoutMs() {
+    if (this.#heartbeatTimeoutMs > 0) return this.#heartbeatTimeoutMs;
+    return Math.max(this.#heartbeatInterval * 2, 1000);
+  }
+
+  /**
+   * 调度下一次心跳发送（单飞模式）
+   * - 任意时刻最多只允许一个未确认心跳在飞
+   * - 只有收到 heartbeat_ack 或其他合法回流后，才会进入下一轮
+   *
+   * @param {number} [delayMs=this.#heartbeatInterval]
+   */
+  #scheduleNextHeartbeat(delayMs = this.#heartbeatInterval) {
+    clearTimeout(this.#heartbeatTimer);
+    this.#heartbeatTimer = setTimeout(
+      () => {
+        this.#sendHeartbeatOnce().catch((error) => this.emit("error", error));
+      },
+      Math.max(0, Number(delayMs) || 0),
+    );
+  }
+
+  /**
+   * 启动 slave 侧心跳发送流程
+   * 实现方式：
+   * - 启动时立即发送第一帧心跳
+   * - 后续改为“发一条 → 等应答 → 再调度下一条”
    */
   #startHeartbeat() {
-    if (this.#heartbeatInterval <= 0) return;
+    if (this.role !== "slave" || this.#heartbeatInterval <= 0) return;
 
-    this.#heartbeatTimer = setInterval(() => {
-      if (!this.running || !this.#sockets.dealer) return;
+    this.#heartbeatWaitingAck = false;
+    clearTimeout(this.#heartbeatAckTimer);
+    this.#heartbeatAckTimer = null;
+    this.#scheduleNextHeartbeat(0);
+  }
 
-      const proof = this.#secureEnabled
-        ? this.#createAuthProof("heartbeat", "", [])
-        : "";
+  /**
+   * 发送单次心跳，并进入等待应答状态
+   */
+  async #sendHeartbeatOnce() {
+    if (
+      !this.running ||
+      this.role !== "slave" ||
+      this.#heartbeatInterval <= 0 ||
+      !this.#sockets.dealer ||
+      this.#heartbeatWaitingAck
+    ) {
+      return;
+    }
 
-      // plain 模式仍保持历史帧结构 [CONTROL_PREFIX, CONTROL_HEARTBEAT]
-      const frames = this.#secureEnabled
-        ? buildHeartbeatFrames(proof)
-        : [CONTROL_PREFIX, CONTROL_HEARTBEAT];
+    const proof = this.#secureEnabled
+      ? this.#createAuthProof("heartbeat", "", [])
+      : "";
 
-      this.#sendQueue
-        .enqueue("dealer", () => this.#sockets.dealer.send(frames))
-        .catch(() => {});
-    }, this.#heartbeatInterval);
+    // plain 模式仍保持历史帧结构 [CONTROL_PREFIX, CONTROL_HEARTBEAT]
+    const frames = this.#secureEnabled
+      ? buildHeartbeatFrames(proof)
+      : [CONTROL_PREFIX, CONTROL_HEARTBEAT];
+
+    this.#heartbeatWaitingAck = true;
+    clearTimeout(this.#heartbeatAckTimer);
+    this.#heartbeatAckTimer = setTimeout(() => {
+      this.#onHeartbeatAckTimeout();
+    }, this.#resolveHeartbeatAckTimeoutMs());
+
+    try {
+      await this.#sendQueue.enqueue("dealer", () =>
+        this.#sockets.dealer.send(frames),
+      );
+    } catch {
+      this.#onHeartbeatAckTimeout();
+    }
+  }
+
+  /**
+   * 心跳应答超时处理：
+   * - 将主节点状态置为离线
+   * - 主动重建 Dealer，丢弃旧连接残留消息
+   */
+  #onHeartbeatAckTimeout() {
+    if (!this.running || this.role !== "slave" || !this.#heartbeatWaitingAck) {
+      return;
+    }
+
+    this.#markMasterOffline();
+    this.#restartDealer("heartbeat_ack_timeout").catch((error) =>
+      this.emit("error", error),
+    );
+  }
+
+  /**
+   * 重建 slave 侧 Dealer 连接
+   * 设计目标：
+   * - 避免 master 重启后旧 socket 中残留的心跳/请求继续回灌
+   * - 将重连控制为单次串行过程，避免并发 close/connect 造成状态抖动
+   *
+   * @param {string} reason
+   * @returns {Promise<void>}
+   */
+  async #restartDealer(reason = "reconnect") {
+    if (this.role !== "slave" || !this.running) return;
+    if (this.#dealerReconnectPromise) return this.#dealerReconnectPromise;
+
+    this.#dealerReconnectPromise = (async () => {
+      clearTimeout(this.#heartbeatTimer);
+      clearTimeout(this.#heartbeatAckTimer);
+      this.#heartbeatTimer = null;
+      this.#heartbeatAckTimer = null;
+      this.#heartbeatWaitingAck = false;
+      this.#masterOnline = false;
+      this.#lastMasterSeenAt = 0;
+
+      this.#pending.rejectAll(
+        new Error(
+          `与主节点的连接已重建（reason=${String(reason)}），待处理请求已取消。`,
+        ),
+      );
+
+      const oldDealer = this.#sockets.dealer;
+      delete this.#sockets.dealer;
+
+      // slave 侧发送队列只服务 dealer，重建时直接清空可避免旧任务继续写入旧 socket
+      this.#sendQueue.clear();
+
+      if (oldDealer) {
+        try {
+          oldDealer.close();
+        } catch {}
+      }
+
+      const dealer = this.#createDealerSocket();
+      this.#sockets.dealer = dealer;
+
+      this.#trySendRegister();
+      this.#startHeartbeat();
+    })().finally(() => {
+      this.#dealerReconnectPromise = null;
+    });
+
+    return this.#dealerReconnectPromise;
   }
 
   /**
@@ -1056,13 +1536,14 @@ export class ZNL extends EventEmitter {
   /**
    * 生成签名证明令牌
    *
-   * @param {"register"|"heartbeat"|"request"|"response"|"publish"} kind
+   * @param {"register"|"heartbeat"|"heartbeat_ack"|"request"|"response"|"publish"} kind
    * @param {string} requestId
    * @param {Buffer[]} payloadFrames
    * @returns {string}
    */
-  #createAuthProof(kind, requestId, payloadFrames) {
-    if (!this.#secureEnabled || !this.#signKey) return "";
+  #createAuthProof(kind, requestId, payloadFrames, signKeyOverride = null) {
+    const signKey = signKeyOverride ?? this.#signKey;
+    if (!this.#secureEnabled || !signKey) return "";
 
     const envelope = {
       kind: String(kind),
@@ -1079,14 +1560,14 @@ export class ZNL extends EventEmitter {
     // 保留 canonical 文本，便于后续排障（签名实际在 token 内完成）
     canonicalSignInput(envelope);
 
-    return encodeAuthProofToken(this.#signKey, envelope);
+    return encodeAuthProofToken(signKey, envelope);
   }
 
   /**
    * 校验入站签名证明 + 防重放 + 摘要一致性
    *
    * @param {{
-   *   kind: "register"|"heartbeat"|"request"|"response"|"publish",
+   *   kind: "register"|"heartbeat"|"heartbeat_ack"|"request"|"response"|"publish",
    *   proofToken: string|null,
    *   requestId: string|null,
    *   payloadFrames: Buffer[],
@@ -1100,9 +1581,12 @@ export class ZNL extends EventEmitter {
     requestId,
     payloadFrames,
     expectedNodeId = null,
+    signKey = null,
   }) {
     if (!this.#secureEnabled) return { ok: true, envelope: null };
-    if (!this.#signKey) {
+
+    const verifyKey = signKey ?? this.#signKey;
+    if (!verifyKey) {
       return { ok: false, error: "签名密钥未初始化。" };
     }
 
@@ -1110,7 +1594,7 @@ export class ZNL extends EventEmitter {
       return { ok: false, error: "缺少认证证明（proofToken）。" };
     }
 
-    const decoded = decodeAuthProofToken(this.#signKey, proofToken, {
+    const decoded = decodeAuthProofToken(verifyKey, proofToken, {
       maxSkewMs: this.#maxTimeSkewMs,
       now: Date.now(),
     });
@@ -1167,13 +1651,14 @@ export class ZNL extends EventEmitter {
    * @param {*} payload
    * @returns {Buffer[]}
    */
-  #sealPayloadFrames(kind, requestId, payload) {
+  #sealPayloadFrames(kind, requestId, payload, encryptKeyOverride = null) {
     if (!this.encrypted) {
       // 非加密模式保持历史行为：沿用协议层的原始帧类型（string/Buffer）
       return normalizeFrames(payload);
     }
 
-    if (!this.#encryptKey) {
+    const encryptKey = encryptKeyOverride ?? this.#encryptKey;
+    if (!encryptKey) {
       throw new Error("加密密钥未初始化。");
     }
 
@@ -1183,11 +1668,7 @@ export class ZNL extends EventEmitter {
       "utf8",
     );
 
-    const { iv, ciphertext, tag } = encryptFrames(
-      this.#encryptKey,
-      rawFrames,
-      aad,
-    );
+    const { iv, ciphertext, tag } = encryptFrames(encryptKey, rawFrames, aad);
 
     // 用统一信封包装：version + iv + tag + ciphertext
     return [Buffer.from(SECURITY_ENVELOPE_VERSION), iv, tag, ciphertext];
@@ -1204,9 +1685,16 @@ export class ZNL extends EventEmitter {
    * @param {string} senderNodeId
    * @returns {Buffer[]}
    */
-  #openPayloadFrames(kind, requestId, payloadFrames, senderNodeId) {
+  #openPayloadFrames(
+    kind,
+    requestId,
+    payloadFrames,
+    senderNodeId,
+    encryptKeyOverride = null,
+  ) {
     if (!this.encrypted) return payloadFrames;
-    if (!this.#encryptKey) throw new Error("加密密钥未初始化。");
+    const encryptKey = encryptKeyOverride ?? this.#encryptKey;
+    if (!encryptKey) throw new Error("加密密钥未初始化。");
 
     if (!Array.isArray(payloadFrames) || payloadFrames.length !== 4) {
       throw new Error("加密信封格式非法：期望 4 帧。");
@@ -1222,7 +1710,7 @@ export class ZNL extends EventEmitter {
       "utf8",
     );
 
-    return decryptFrames(this.#encryptKey, iv, ciphertext, tag, aad);
+    return decryptFrames(encryptKey, iv, ciphertext, tag, aad);
   }
 
   /**
@@ -1247,7 +1735,11 @@ export class ZNL extends EventEmitter {
    * @param {Buffer|string|Uint8Array} identity
    * @param {{ touch?: boolean }} [options]
    */
-  #ensureSlaveOnline(identityText, identity, { touch = true } = {}) {
+  #ensureSlaveOnline(
+    identityText,
+    identity,
+    { touch = true, signKey = null, encryptKey = null } = {},
+  ) {
     const id = String(identityText ?? "");
     if (!id) return;
 
@@ -1255,16 +1747,55 @@ export class ZNL extends EventEmitter {
     const entry = this.#slaves.get(id);
     if (entry) {
       if (touch) entry.lastSeen = now;
+      if (signKey) entry.signKey = signKey;
+      if (encryptKey) entry.encryptKey = encryptKey;
       return;
     }
 
     this.#slaves.set(id, {
       identity: identityToBuffer(identity),
       lastSeen: now,
+      signKey: signKey ?? null,
+      encryptKey: encryptKey ?? null,
     });
     this.emit("slave_connected", id);
   }
 
+  /**
+   * master 侧解析某个 slave 的签名/加密密钥
+   * - 优先匹配 authKeyMap
+   * - 未命中时回退到 this.authKey（若提供）
+   *
+   * @param {string} slaveId
+   * @returns {{ signKey: Buffer, encryptKey: Buffer }|null}
+   */
+  #resolveSlaveKeys(slaveId) {
+    if (!this.#secureEnabled) return null;
+
+    const id = String(slaveId ?? "");
+    if (!id) return null;
+
+    const cached = this.#slaveKeyCache.get(id);
+    if (cached) return cached;
+
+    let key = this.#authKeyMap.get(id);
+    if (!key && this.authKey) {
+      key = this.authKey;
+    }
+    if (!key) return null;
+
+    const derived = deriveKeys(key);
+    this.#slaveKeyCache.set(id, derived);
+
+    const entry = this.#slaves.get(id);
+    if (entry) {
+      entry.signKey = derived.signKey;
+      entry.encryptKey = derived.encryptKey;
+    }
+
+    return derived;
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   //  工具方法
   // ═══════════════════════════════════════════════════════════════════════════