@lyrify/znl 0.5.6 → 0.6.0

package/README.md

@@ -1,22 +1,22 @@
 # ZNL
 
-基于 ZeroMQ `ROUTER/DEALER` 模式的 Node.js 通信库，提供开箱即用的双向 RPC 与 PUB/SUB 广播能力。
+基于 ZeroMQ `ROUTER / DEALER` 模式的 Node.js 通信库，提供双向 RPC、广播、在线状态感知，以及可选的签名认证与透明加密能力。
 
 ## 特性
 
-- 基于 `ROUTER/DEALER` 同时实现 RPC 请求-响应与 PUB/SUB 广播，一套连接两种模式
-- 自动处理并发消息匹配、自动处理心跳包、超时控制、最大并发限制
-- 支持 Master → Slave 主动发起请求（双向 RPC）
-- 基于 ROUTER 实现 PUB/SUB 广播，无需额外 socket 或端口
-- Slave 自动注册/注销，Master 实时感知在线节点
-- 支持可选加密认证（签名 + 防重放 + AES-256-GCM 透明加密）
-- 加密开关 `encrypted`：
-  - `false`：明文模式（不签名/不加密）
-  - `true`：签名 + 防重放 + payload 透明加密（AES-256-GCM）
-- 可选关闭 payload 摘要校验（`enablePayloadDigest=false`）以提升性能
-  - 建议 master/slave 两端保持一致配置，避免认证不一致
-- `authKey` 或 `authKeyMap` 仅在 `encrypted=true` 时必填
-- `authKeyMap` 支持 master 按 `slaveId` 配置不同 key（未命中时会回退到 `authKey`）
+- 基于单连接实现双向 RPC 与广播
+- 支持 `Master -> Slave` 与 `Slave -> Master` 双向主动请求
+- `Slave` 自动注册 / 注销，`Master` 实时维护在线节点列表
+- 支持请求超时控制与最大并发限制
+- 心跳采用 `heartbeat -> heartbeat_ack` 应答机制
+- `Slave` 提供主节点在线状态查询 API：`masterOnline` / `isMasterOnline()`
+- 支持安全模式：
+  - HMAC 签名
+  - 时间戳校验
+  - nonce 防重放
+  - AES-256-GCM 透明加密
+  - 可选 payload 摘要校验
+- 支持 `authKeyMap`，允许 `Master` 按 `slaveId` 使用不同密钥
 - Payload 支持 `string`、`Buffer`、`Uint8Array` 及其数组（多帧）
 
 ## 安装
@@ -25,7 +25,7 @@
 pnpm add @lyrify/znl
 ```
 
-本地开发克隆仓库后：
+本地开发：
 
 ```bash
 pnpm install
@@ -33,7 +33,7 @@ pnpm install
 
 ## 快速开始
 
-### Master 节点
+### Master
 
 ```js
 import { ZNL } from "@lyrify/znl";
@@ -41,29 +41,36 @@ import { ZNL } from "@lyrify/znl";
 const master = new ZNL({
   role: "master",
   id: "master-1",
-  endpoints: { router: "tcp://127.0.0.1:6003" },
+  endpoints: {
+    router: "tcp://127.0.0.1:6003",
+  },
   authKey: "your-shared-key",
-  encrypted: true, // 推荐：透明加密 + 防重放
+  encrypted: true,
 });
 
-// RPC：自动回复 slave 的请求
+// 注册自动回复处理器
 master.ROUTER(async ({ identityText, payload }) => {
   const text = Buffer.isBuffer(payload) ? payload.toString() : String(payload);
   return `已收到来自 ${identityText} 的消息：${text}`;
 });
 
-// PUB/SUB：感知节点上下线
-master.on("slave_connected",    (id) => console.log(`${id} 上线，在线：${master.slaves}`));
-master.on("slave_disconnected", (id) => console.log(`${id} 下线，在线：${master.slaves}`));
+// 监听节点上下线
+master.on("slave_connected", (id) => {
+  console.log(`${id} 上线，当前在线：${master.slaves.join(", ")}`);
+});
+
+master.on("slave_disconnected", (id) => {
+  console.log(`${id} 下线，当前在线：${master.slaves.join(", ")}`);
+});
 
 await master.start();
 
-// PUB/SUB：广播消息（fire-and-forget）
+// 广播消息
 master.publish("news", "今日头条：ZNL 正式发布");
 master.publish("system", JSON.stringify({ status: "ok", time: Date.now() }));
 ```
 
-### Slave 节点
+### Slave
 
 ```js
 import { ZNL } from "@lyrify/znl";
@@ -71,26 +78,29 @@ import { ZNL } from "@lyrify/znl";
 const slave = new ZNL({
   role: "slave",
   id: "slave-001",
-  endpoints: { router: "tcp://127.0.0.1:6003" },
+  endpoints: {
+    router: "tcp://127.0.0.1:6003",
+  },
   authKey: "your-shared-key",
-  encrypted: true, // 需与 master 一致
+  encrypted: true,
 });
 
-// PUB/SUB：精确订阅（可在 start 前调用）
+// 订阅指定 topic
 slave.subscribe("news", ({ payload }) => {
   console.log("收到新闻：", payload.toString());
 });
 
-// PUB/SUB：兜底监听所有 topic
+// 兜底监听所有广播
 slave.on("publish", ({ topic, payload }) => {
   console.log(`[${topic}]`, payload.toString());
 });
 
 await slave.start();
 
-// RPC：向 master 发请求并等待响应
-const reply = await slave.DEALER("hello master", { timeoutMs: 4000 });
-console.log(reply.toString());
+if (slave.isMasterOnline()) {
+  const reply = await slave.DEALER("hello master", { timeoutMs: 4000 });
+  console.log(reply.toString());
+}
 ```
 
 ## 构造函数
@@ -114,112 +124,384 @@ new ZNL({
 });
 ```
 
+## 参数说明
+
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `role` | ✓ | 节点角色，`"master"` 或 `"slave"` |
-| `id` | ✓ | 节点唯一标识；slave 端同时作为 ZMQ `routingId` |
-| `endpoints.router` | | ROUTER 端点，默认 `tcp://127.0.0.1:6003` |
-| `maxPending` | | 最大并发 RPC 请求数，默认 `1000`；`0` 表示不限制 |
-| `authKey` | | 共享认证 Key；与 `authKeyMap` 二选一（`encrypted=true` 时至少提供一个） |
-| `authKeyMap` | | master 侧 slaveId → authKey 映射；未命中时回退到 `authKey` |
-| `heartbeatInterval` | | 心跳间隔（毫秒），默认 `3000`，`0` 表示禁用心跳 |
-| `heartbeatTimeoutMs` | | 心跳超时时间（毫秒），默认 `0` 表示使用 `heartbeatInterval × 3` |
-| `encrypted` | | 是否启用加密：`false`（默认，明文） / `true`（签名+防重放+透明加密） |
-| `enablePayloadDigest` | | 是否启用 payload 摘要校验，默认 `true`（关闭可提升性能） |
-| `maxTimeSkewMs` | | 时间戳最大允许偏移（毫秒），默认 `30000`，用于防重放校验 |
-| `replayWindowMs` | | nonce 重放缓存窗口（毫秒），默认 `120000` |
+| `id` | ✓ | 节点唯一标识；`slave` 侧同时作为 ZMQ `routingId` |
+| `endpoints.router` |  | ROUTER 端点，默认 `tcp://127.0.0.1:6003` |
+| `maxPending` |  | 最大并发 RPC 请求数，默认 `1000`；`0` 表示不限制 |
+| `authKey` |  | 共享认证 Key；与 `authKeyMap` 二选一（`encrypted=true` 时至少提供一个） |
+| `authKeyMap` |  | `master` 侧 `slaveId -> authKey` 映射；未命中时回退到 `authKey` |
+| `heartbeatInterval` |  | 心跳间隔（毫秒），默认 `3000`；`0` 表示禁用心跳 |
+| `heartbeatTimeoutMs` |  | 心跳超时时间（毫秒），默认 `0` 表示使用 `heartbeatInterval × 3` |
+| `encrypted` |  | 是否启用安全模式：`false`（默认，明文） / `true`（签名、防重放、透明加密） |
+| `enablePayloadDigest` |  | 是否启用 payload 摘要校验，默认 `true`；关闭可提升性能 |
+| `maxTimeSkewMs` |  | 时间戳最大允许偏移（毫秒），默认 `30000` |
+| `replayWindowMs` |  | nonce 重放缓存窗口（毫秒），默认 `120000` |
+
+## 使用建议
+
+- `master` 与 `slave` 两端应保持一致的 `encrypted` 配置
+- 若使用 `enablePayloadDigest=false`，两端也应保持一致
+- `encrypted=true` 时必须提供非空 `authKey`，或在 `master` 侧提供 `authKeyMap`
 
 ## API
 
-### `start()`
+### 生命周期
+
+#### `start()`
+
+启动节点。
 
-启动节点：
+`master` 侧：
 
-- `master`：绑定（bind）ROUTER socket
-- `slave`：连接（connect）DEALER socket，并自动向 master 发送注册帧
+- 绑定 ROUTER socket
+- 启动在线节点心跳检测
 
-重复调用安全，若正在启动中则等待同一个 Promise。
+`slave` 侧：
 
-### `stop()`
+- 连接 DEALER socket
+- 自动尝试发送注册帧
+- 启动心跳流程
+- 发送 `heartbeat` 后等待 `heartbeat_ack`
+- 收到 `heartbeat_ack` 后调度下一次心跳
 
-停止节点：
+#### `stop()`
 
-- `slave`：先向 master 发送注销帧，再关闭 socket
-- `master`：清空在线节点表，关闭 socket，立即 reject 所有 pending RPC 请求
+停止节点。
 
-### `DEALER(payloadOrHandler, options?)`
+`slave` 侧：
 
-**Slave 侧调用：**
+- 停止心跳
+- 发送注销帧
+- 关闭 socket
 
-- `payloadOrHandler` 为 payload 时：向 Master 发送 RPC 请求并等待响应，返回 `Promise<Buffer | Array>`
-- `payloadOrHandler` 为函数时：注册 slave 侧自动回复处理器（Master 主动发来 RPC 请求时触发）
+`master` 侧：
 
-### `ROUTER(identityOrHandler, payload?, options?)`
+- 清空在线节点表
+- 关闭 socket
+- reject 所有 pending RPC 请求
 
-**Master 侧调用：**
+### 双向 RPC
 
-- `identityOrHandler` 为函数时：注册 master 侧自动回复处理器（Slave 发来 RPC 请求时触发）
-- `identityOrHandler` 为 identity（slave ID）时：Master 主动向指定 Slave 发送 RPC 请求并等待响应，返回 `Promise<Buffer | Array>`
+#### `DEALER(payloadOrHandler, options?)`
 
-### `addAuthKey(slaveId, authKey)`
+仅 `slave` 侧使用。
 
-**Master 侧调用：**
+- 当 `payloadOrHandler` 为 payload 时，向 `Master` 发起 RPC 请求，返回 `Promise<Buffer | Array>`
+- 当 `payloadOrHandler` 为函数时，注册 `slave` 侧自动回复处理器，用于处理 `Master` 主动发来的请求
 
-- 动态添加/更新某个 slave 的 authKey（立即生效）
+#### `ROUTER(identityOrHandler, payload?, options?)`
 
-### `removeAuthKey(slaveId)`
+仅 `master` 侧使用。
 
-**Master 侧调用：**
+- 当 `identityOrHandler` 为函数时，注册 `master` 侧自动回复处理器，用于处理 `Slave` 发来的请求
+- 当 `identityOrHandler` 为某个 `slaveId` 时，`Master` 主动向指定 `Slave` 发起 RPC 请求，返回 `Promise<Buffer | Array>`
 
-- 移除某个 slave 的 authKey（立即生效），并触发 `slave_disconnected`
+#### `options.timeoutMs`
 
-### `options.timeoutMs`
+单次 RPC 请求超时时间，默认 `5000` 毫秒。
 
-单次 RPC 请求超时时间，默认 `5000` ms。
+### 广播与订阅
 
-### `publish(topic, payload)`
+#### `publish(topic, payload)`
 
-**Master 侧调用**，向所有当前在线的 slave 广播消息（fire-and-forget，无需 await）。
+仅 `master` 侧使用。
 
-- `topic`：消息主题字符串，slave 侧可按 topic 精确过滤
-- `payload`：同 RPC，支持 `string`、`Buffer`、`Uint8Array` 或其数组
-- 若某个 slave 发送失败，自动将其从在线列表移除并触发 `slave_disconnected`
+向所有当前在线的 `slave` 广播消息（fire-and-forget，无需 `await`）。
+
+- `topic`：消息主题
+- `payload`：支持 `string`、`Buffer`、`Uint8Array` 或其数组
+- 若某个 `slave` 发送失败，会自动将其移出在线列表并触发 `slave_disconnected`
 
 ```js
 master.publish("news", "breaking news!");
 master.publish("metrics", JSON.stringify({ cpu: 0.42 }));
 ```
 
-### `subscribe(topic, handler)`
+#### `subscribe(topic, handler)`
+
+仅 `slave` 侧使用。
 
-**Slave 侧调用**，订阅指定 topic，master 广播时触发 handler。
+订阅指定 topic。
 
-- 可在 `start()` 前后任意时刻调用，订阅信息跨 stop/start 周期保留
+- 可在 `start()` 前后调用
+- 订阅关系跨 `stop()/start()` 周期保留
 - 同一 topic 重复订阅会覆盖旧 handler
-- 支持链式调用（返回 `this`）
+- 返回 `this`，支持链式调用
 
 ```js
 slave
-  .subscribe("news",    ({ topic, payload }) => { /* ... */ })
-  .subscribe("metrics", ({ topic, payload }) => { /* ... */ });
+  .subscribe("news", ({ topic, payload }) => {
+    // ...
+  })
+  .subscribe("metrics", ({ topic, payload }) => {
+    // ...
+  });
 ```
 
-### `unsubscribe(topic)`
+#### `unsubscribe(topic)`
 
-**Slave 侧调用**，取消订阅指定 topic，支持链式调用。
+仅 `slave` 侧使用。
+
+取消订阅指定 topic。
 
 ```js
 slave.unsubscribe("news");
 ```
 
-### `slaves`
+### 在线状态与节点管理
+
+#### `slaves`
 
-**Master 侧只读属性**，返回当前所有在线 slave ID 的快照数组。
+仅 `master` 侧只读属性。
+
+返回当前所有在线 `slaveId` 的快照数组。
+
+```js
+console.log(master.slaves);
+```
+
+#### `masterOnline`
+
+仅 `slave` 侧只读属性。
+
+表示最近一次链路确认结果。
+
+- `true`：最近收到合法的 `heartbeat_ack`，或收到来自 `master` 的合法业务帧
+- `false`：尚未建立有效链路、心跳应答超时、或节点已停止
 
 ```js
-console.log(master.slaves); // ["slave-001", "slave-002"]
+console.log(slave.masterOnline);
+```
+
+#### `isMasterOnline()`
+
+仅 `slave` 侧方法。
+
+返回当前主节点在线状态。该值基于最近一次链路确认结果，不会主动发起实时网络探测。
+
+```js
+if (slave.isMasterOnline()) {
+  console.log("master 在线");
+}
+```
+
+#### `addAuthKey(slaveId, authKey)`
+
+仅 `master` 侧使用。
+
+动态添加或更新某个 `slave` 的 `authKey`，立即生效。
+
+#### `removeAuthKey(slaveId)`
+
+仅 `master` 侧使用。
+
+移除某个 `slave` 的 `authKey`，立即生效，并触发 `slave_disconnected`。
+
+## 心跳机制
+
+ZNL 使用 `heartbeat -> heartbeat_ack` 进行链路确认。
+
+流程如下：
+
+1. `slave` 发送一条 `heartbeat`
+2. `master` 收到并验证通过后，立即返回 `heartbeat_ack`
+3. `slave` 收到 `heartbeat_ack` 后，调度下一次 heartbeat
+4. 若超过应答超时时间仍未收到 `heartbeat_ack``
+   - `slave` 将 `masterOnline` 置为 `false`
+   - 主动重建 `Dealer`
+   - 丢弃旧连接残留消息
+   - 尝试恢复连接与注册
+
+## 安全机制
+
+当 `encrypted=true` 时，ZNL 启用安全模式：
+
+- HMAC 签名
+- 时间戳校验
+- nonce 防重放
+- AES-256-GCM 透明加密
+- 可选 payload 摘要校验
+
+### 安全建议
+
+- `authKey` 不要硬编码到公开仓库
+- `master` 与 `slave` 必须使用匹配的密钥配置
+- 若使用 `authKeyMap`，建议按 `slaveId` 做最小权限配置
+- 生产环境建议开启：
+  - `encrypted: true`
+  - `enablePayloadDigest: true`
+
+## 底层帧协议
+
+本节说明 ZNL 在 ZeroMQ 上层定义的控制帧结构，用于协议对接、调试与抓包分析。
+
+### 总体说明
+
+`master` 侧 ROUTER 收包结构：
+
+```text
+[identity, ...控制帧]
+```
+
+`slave` 侧 DEALER 收包结构：
+
+```text
+[...控制帧]
+```
+
+控制帧统一前缀：
+
+```text
+__znl_v1__
+```
+
+认证字段标记：
+
+```text
+__znl_v1_auth__
+```
+
+### 控制帧类型
+
+| 类型 | 方向 | 作用 |
+|------|------|------|
+| `register` | `slave -> master` | 注册上线 |
+| `unregister` | `slave -> master` | 主动下线 |
+| `heartbeat` | `slave -> master` | 心跳请求 |
+| `heartbeat_ack` | `master -> slave` | 心跳应答 |
+| `req` | 双向 | RPC 请求 |
+| `res` | 双向 | RPC 响应 |
+| `pub` | `master -> slave` | 广播消息 |
+
+### 各类帧结构
+
+#### `register`
+
+```text
+[PREFIX, "register", (AUTH_MARKER, authProof)?]
+```
+
+示例：
+
+```text
+["__znl_v1__", "register"]
+["__znl_v1__", "register", "__znl_v1_auth__", "<proof-token>"]
+```
+
+#### `unregister`
+
+```text
+[PREFIX, "unregister"]
+```
+
+示例：
+
+```text
+["__znl_v1__", "unregister"]
+```
+
+#### `heartbeat`
+
+```text
+[PREFIX, "heartbeat", (AUTH_MARKER, authProof)?]
+```
+
+示例：
+
+```text
+["__znl_v1__", "heartbeat"]
+["__znl_v1__", "heartbeat", "__znl_v1_auth__", "<proof-token>"]
+```
+
+#### `heartbeat_ack`
+
+```text
+[PREFIX, "heartbeat_ack", (AUTH_MARKER, authProof)?]
+```
+
+示例：
+
+```text
+["__znl_v1__", "heartbeat_ack"]
+["__znl_v1__", "heartbeat_ack", "__znl_v1_auth__", "<proof-token>"]
+```
+
+#### `req`
+
+```text
+[PREFIX, "req", requestId, (AUTH_MARKER, authProof)?, ...payloadFrames]
+```
+
+示例：
+
+```text
+["__znl_v1__", "req", "<requestId>", ...payloadFrames]
+["__znl_v1__", "req", "<requestId>", "__znl_v1_auth__", "<proof-token>", ...payloadFrames]
+```
+
+#### `res`
+
+```text
+[PREFIX, "res", requestId, (AUTH_MARKER, authProof)?, ...payloadFrames]
+```
+
+示例：
+
+```text
+["__znl_v1__", "res", "<requestId>", ...payloadFrames]
+["__znl_v1__", "res", "<requestId>", "__znl_v1_auth__", "<proof-token>", ...payloadFrames]
+```
+
+#### `pub`
+
+```text
+[PREFIX, "pub", topic, (AUTH_MARKER, authProof)?, ...payloadFrames]
+```
+
+示例：
+
+```text
+["__znl_v1__", "pub", "news", ...payloadFrames]
+["__znl_v1__", "pub", "news", "__znl_v1_auth__", "<proof-token>", ...payloadFrames]
 ```
 
+### 认证令牌字段
+
+安全模式下，认证令牌内部包含以下字段：
+
+- `kind`
+- `nodeId`
+- `requestId`
+- `timestamp`
+- `nonce`
+- `payloadDigest`
+
+校验时会验证：
+
+- 帧类型是否匹配
+- 节点 ID 是否匹配
+- 请求 ID 是否匹配
+- 时间戳是否在允许偏差内
+- nonce 是否重复
+- payload 摘要是否一致
+
+### 明文模式与安全模式
+
+#### 明文模式 `encrypted=false`
+
+- 不签名
+- 不加密
+- 帧结构更轻量
+
+#### 安全模式 `encrypted=true`
+
+- 控制帧会附带认证证明
+- 业务 payload 会被透明加密
+
 ## 事件
 
 通过 `node.on(eventName, handler)` 监听：
@@ -231,9 +513,9 @@ console.log(master.slaves); // ["slave-001", "slave-002"]
 | `request` | 两者 | 解析出 RPC 请求帧（认证通过后） |
 | `response` | 两者 | 解析出 RPC 响应帧 |
 | `message` | 两者 | 所有解析消息的统一事件 |
-| `publish` | Slave | 收到 master 广播，携带 `{ topic, payload }` |
-| `slave_connected` | Master | slave 注册成功上线，携带 `slaveId` |
-| `slave_disconnected` | Master | slave 注销或发送失败下线，携带 `slaveId` |
+| `publish` | Slave | 收到 `master` 广播，携带 `{ topic, payload }` |
+| `slave_connected` | Master | `slave` 注册成功上线，携带 `slaveId` |
+| `slave_disconnected` | Master | `slave` 注销或发送失败下线，携带 `slaveId` |
 | `auth_failed` | Master / Slave | 认证失败（签名校验失败、重放检测失败、解密失败等），请求已被丢弃 |
 | `error` | 两者 | 内部错误 |
 
@@ -250,7 +532,15 @@ node test/slave/index.js slave-001
 
 ## 集成测试
 
-在同一进程内启动 Master / Slave，自动验证 RPC、并发、认证、超时、PUB/SUB 等全部功能：
+在同一进程内启动 `Master / Slave`，自动验证：
+
+- RPC
+- 并发
+- 认证
+- 超时
+- PUB/SUB
+- 心跳恢复
+- 在线状态 API
 
 ```bash
 pnpm test
@@ -258,6 +548,8 @@ pnpm test
 
 ## 并发压测
 
+### 明文模式
+
 ```bash
 # 终端 1：启动 Echo 服务端（plain）
 pnpm test:echo
@@ -266,7 +558,7 @@ pnpm test:echo
 pnpm test:100 -- 100 10000 slave-001
 ```
 
-启用安全模式示例：
+### 安全模式
 
 ```bash
 # 终端 1：加密模式启动 Echo 服务端
@@ -276,14 +568,26 @@ ZNL_AUTH_KEY=my-secret ZNL_ENCRYPTED=true pnpm test:echo
 pnpm test:100 -- 100 10000 slave-001 my-secret true
 ```
 
-参数说明：
+### 参数说明
 
 - 总请求数
 - 超时时间（毫秒）
-- Slave 节点 ID
+- `Slave` 节点 ID
+
+## 常见问题
+
+### 为什么 `slave.start()` 后立刻发送第一条请求可能失败？
+
+当前版本对 `Dealer` 的发送策略更严格。建议先等待 `slave.isMasterOnline() === true`，再发送首个业务请求。
+
+### 为什么会出现“令牌已过期或时间戳异常”？
+
+常见原因：
+
+- 主从机器时间差过大
+- 节点时间被手动修改
+- 历史旧消息在较晚时间才被投递
 
-## 发布前检查
+### `masterOnline=true` 是否表示此刻网络一定可用？
 
-1. 更新 `package.json` 中的 `name`、`version`、`author`、`repository`
-2. 确认 README 中的包名与 import 路径
-3. 按需更新 `LICENSE` 中的版权信息
+不是。该值表示最近一次链路确认成功，适合作为业务层在线状态参考，但不是一次即时网络探针。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyrify/znl",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "ZNL - ZeroMQ Node Link",
   "type": "module",
   "main": "./index.js",

package/src/ZNL.js

@@ -49,6 +49,7 @@ import {
   buildRegisterFrames,
   buildUnregisterFrames,
   buildHeartbeatFrames,
+  buildHeartbeatAckFrames,
   buildRequestFrames,
   buildResponseFrames,
   buildPublishFrames,
@@ -154,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;
 
@@ -466,6 +482,27 @@ 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
@@ -549,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", () =>
@@ -569,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)) {
@@ -587,6 +631,10 @@ export class ZNL extends EventEmitter {
     this.#slaves.clear();
     this.#slaveKeyCache.clear();
     this.#masterNodeId = null;
+    this.#masterOnline = false;
+    this.#lastMasterSeenAt = 0;
+    this.#heartbeatWaitingAck = false;
+    this.#dealerReconnectPromise = null;
     this.#replayGuard.clear();
   }
 
@@ -611,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));
-
-    // 注册帧：
-    // - encrypted=true  : 发送签名证明令牌（放在 authKey 字段位）
-    // - encrypted=false : 不携带认证信息
-    const registerToken = this.#secureEnabled
-      ? this.#createAuthProof("register", "", [])
-      : "";
+    this.#masterOnline = false;
+    this.#lastMasterSeenAt = 0;
+    this.#heartbeatWaitingAck = false;
 
-    await this.#sendQueue.enqueue("dealer", () =>
-      dealer.send(buildRegisterFrames(registerToken)),
-    );
+    const dealer = this.#createDealerSocket();
+    this.#sockets.dealer = dealer;
 
+    // 注册帧改为“尽力发送”：
+    // - master 尚未上线时无需阻塞启动流程
+    // - 后续 heartbeat_ack 成功后仍可自然恢复在线状态
+    this.#trySendRegister();
     this.#startHeartbeat();
   }
 
@@ -654,6 +696,8 @@ export class ZNL extends EventEmitter {
 
     // ── 心跳 ────────────────────────────────────────────────────────────────
     if (parsed.kind === "heartbeat") {
+      let ackFrames = buildHeartbeatAckFrames();
+
       if (this.#secureEnabled) {
         const keys = this.#resolveSlaveKeys(identityText);
         if (!keys) {
@@ -682,11 +726,20 @@ export class ZNL extends EventEmitter {
           signKey: keys.signKey,
           encryptKey: keys.encryptKey,
         });
-        return;
+
+        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;
     }
 
@@ -886,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;
@@ -924,6 +999,8 @@ export class ZNL extends EventEmitter {
         }
       }
 
+      this.#confirmMasterReachable({ scheduleNextHeartbeat: true });
+
       const finalPayload = payloadFromFrames(finalFrames);
       const pubEvent = { topic: parsed.topic, payload: finalPayload };
 
@@ -977,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);
@@ -1029,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);
@@ -1194,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;
   }
 
   /**
@@ -1247,7 +1536,7 @@ 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}
@@ -1278,7 +1567,7 @@ export class ZNL extends EventEmitter {
    * 校验入站签名证明 + 防重放 + 摘要一致性
    *
    * @param {{
-   *   kind: "register"|"heartbeat"|"request"|"response"|"publish",
+   *   kind: "register"|"heartbeat"|"heartbeat_ack"|"request"|"response"|"publish",
    *   proofToken: string|null,
    *   requestId: string|null,
    *   payloadFrames: Buffer[],

package/src/constants.js

@@ -18,6 +18,9 @@ export const CONTROL_AUTH = "__znl_v1_auth__";
 /** slave 保活心跳帧标识符（slave → master，定时发送） */
 export const CONTROL_HEARTBEAT = "heartbeat";
 
+/** master 心跳应答帧标识符（master → slave，用于确认链路可达） */
+export const CONTROL_HEARTBEAT_ACK = "heartbeat_ack";
+
 /** slave 上线注册帧标识符（slave → master，start 时自动发送） */
 export const CONTROL_REGISTER = "register";
 

package/src/protocol.js

@@ -4,11 +4,13 @@
  * 负责所有帧的构建与解析，全部为纯函数，无副作用。
  *
  * 控制帧格式：
- *   注册帧：  [PREFIX, "register", (AUTH_MARKER, authKey)?]
- *   注销帧：  [PREFIX, "unregister"]
- *   请求帧：  [PREFIX, "req", requestId, (AUTH_MARKER, authKey)?, ...payload]
- *   响应帧：  [PREFIX, "res", requestId, ...payload]
- *   广播帧：  [PREFIX, "pub", topic, ...payload]
+ *   注册帧：     [PREFIX, "register", (AUTH_MARKER, authKey)?]
+ *   注销帧：     [PREFIX, "unregister"]
+ *   心跳帧：     [PREFIX, "heartbeat", (AUTH_MARKER, authProof)?]
+ *   心跳应答帧： [PREFIX, "heartbeat_ack", (AUTH_MARKER, authProof)?]
+ *   请求帧：     [PREFIX, "req", requestId, (AUTH_MARKER, authKey)?, ...payload]
+ *   响应帧：     [PREFIX, "res", requestId, ...payload]
+ *   广播帧：     [PREFIX, "pub", topic, ...payload]
  *   Router 侧额外在最前面加一帧：[identity, ...]
  */
 
@@ -21,6 +23,7 @@ import {
   CONTROL_UNREGISTER,
   CONTROL_PUB,
   CONTROL_HEARTBEAT,
+  CONTROL_HEARTBEAT_ACK,
   EMPTY_BUFFER,
 } from "./constants.js";
 
@@ -180,22 +183,37 @@ export function buildHeartbeatFrames(authProof = "") {
   return frames;
 }
 
+/**
+ * 构建心跳应答控制帧数组（master → slave）
+ * 帧结构：[PREFIX, "heartbeat_ack", (AUTH_MARKER, authProof)?]
+ *
+ * @param {string} [authProof] - 可选认证证明
+ * @returns {Array}
+ */
+export function buildHeartbeatAckFrames(authProof = "") {
+  const frames = [CONTROL_PREFIX, CONTROL_HEARTBEAT_ACK];
+  if (authProof) frames.push(CONTROL_AUTH, authProof);
+  return frames;
+}
+
 // ─── 帧解析 ───────────────────────────────────────────────────────────────────
 
 /**
  * 解析 ZMQ 原始帧，识别控制帧并提取语义字段
  *
  * 返回 kind 说明：
- * - "register"   → slave 上线注册（携带可选 authKey）
- * - "unregister" → slave 主动下线注销
- * - "publish"    → master 广播消息（携带 topic）
- * - "request"    → 对端主动发起的 RPC 请求
- * - "response"   → 对端返回的 RPC 响应（匹配 pending 请求）
- * - "message"    → 非控制帧，普通消息透传
+ * - "register"      → slave 上线注册（携带可选 authKey）
+ * - "unregister"    → slave 主动下线注销
+ * - "heartbeat"     → slave 发起保活心跳
+ * - "heartbeat_ack" → master 返回心跳应答
+ * - "publish"       → master 广播消息（携带 topic）
+ * - "request"       → 对端主动发起的 RPC 请求
+ * - "response"      → 对端返回的 RPC 响应（匹配 pending 请求）
+ * - "message"       → 非控制帧，普通消息透传
  *
  * @param {Array} frames - 不含 identity 帧的帧数组
  * @returns {{
- *   kind         : "register"|"unregister"|"heartbeat"|"publish"|"request"|"response"|"message",
+ *   kind         : "register"|"unregister"|"heartbeat"|"heartbeat_ack"|"publish"|"request"|"response"|"message",
  *   requestId    : string|null,
  *   authKey      : string|null,
  *   authProof    : string|null,
@@ -263,6 +281,23 @@ export function parseControlFrames(frames) {
     };
   }
 
+  // ── 心跳应答帧：[PREFIX, "heartbeat_ack"] ─────────────────────────────────
+  if (action === CONTROL_HEARTBEAT_ACK) {
+    let authProof = null;
+    if (frames.length >= 4 && frames[2]?.toString() === CONTROL_AUTH) {
+      authProof = frames[3]?.toString() ?? "";
+    }
+
+    return {
+      kind: "heartbeat_ack",
+      requestId: null,
+      authKey: null,
+      authProof,
+      topic: null,
+      payloadFrames: [],
+    };
+  }
+
   // ── 广播帧：[PREFIX, "pub", topic, ...payloadFrames] ─────────────────────
   if (action === CONTROL_PUB && frames.length >= 3) {
     const topic = frames[2]?.toString() ?? "";