@lyrify/znl 0.4.1 → 0.5.2

package/README.md

@@ -5,11 +5,17 @@
 ## 特性
 
 - 基于 `ROUTER/DEALER` 同时实现 RPC 请求-响应与 PUB/SUB 广播，一套连接两种模式
-- 内置请求 ID 匹配、超时控制、最大并发限制
+- 自动处理并发消息匹配、自动处理心跳包、超时控制、最大并发限制
 - 支持 Master → Slave 主动发起请求（双向 RPC）
 - 基于 ROUTER 实现 PUB/SUB 广播，无需额外 socket 或端口
 - Slave 自动注册/注销，Master 实时感知在线节点
-- 可选的认证 Key 校验（注册与 RPC 请求均校验）
+- 支持可选加密认证（签名 + 防重放 + AES-256-GCM 透明加密）
+- 加密开关 `encrypted`：
+  - `false`：明文模式（不签名/不加密）
+  - `true`：签名 + 防重放 + payload 透明加密（AES-256-GCM）
+- 可选关闭 payload 摘要校验（`enablePayloadDigest=false`）以提升性能
+  - 建议 master/slave 两端保持一致配置，避免认证不一致
+- `authKey` 仅在 `encrypted=true` 时必填
 - Payload 支持 `string`、`Buffer`、`Uint8Array` 及其数组（多帧）
 
 ## 安装
@@ -36,6 +42,7 @@ const master = new ZNL({
   id: "master-1",
   endpoints: { router: "tcp://127.0.0.1:6003" },
   authKey: "your-shared-key",
+  encrypted: true, // 推荐：透明加密 + 防重放
 });
 
 // RPC：自动回复 slave 的请求
@@ -65,6 +72,7 @@ const slave = new ZNL({
   id: "slave-001",
   endpoints: { router: "tcp://127.0.0.1:6003" },
   authKey: "your-shared-key",
+  encrypted: true, // 需与 master 一致
 });
 
 // PUB/SUB：精确订阅（可在 start 前调用）
@@ -93,8 +101,14 @@ new ZNL({
   endpoints: {
     router: "tcp://127.0.0.1:6003",
   },
-  maxPending: 0,
+  maxPending: 1000,
   authKey: "",
+  heartbeatInterval: 3000,
+  heartbeatTimeoutMs: 0,
+  encrypted: false,
+  enablePayloadDigest: true,
+  maxTimeSkewMs: 30000,
+  replayWindowMs: 120000,
 });
 ```
 
@@ -103,8 +117,14 @@ new ZNL({
 | `role` | ✓ | 节点角色，`"master"` 或 `"slave"` |
 | `id` | ✓ | 节点唯一标识；slave 端同时作为 ZMQ `routingId` |
 | `endpoints.router` | | ROUTER 端点，默认 `tcp://127.0.0.1:6003` |
-| `maxPending` | | 最大并发 RPC 请求数，`0` 表示不限制 |
-| `authKey` | | 可选共享认证 Key；master 开启后校验注册帧与 RPC 请求 |
+| `maxPending` | | 最大并发 RPC 请求数，默认 `1000`；`0` 表示不限制 |
+| `authKey` | | 共享认证 Key；仅在 `encrypted=true` 时必填（用于签名/加密） |
+| `heartbeatInterval` | | 心跳间隔（毫秒），默认 `3000`，`0` 表示禁用心跳 |
+| `heartbeatTimeoutMs` | | 心跳超时时间（毫秒），默认 `0` 表示使用 `heartbeatInterval × 3` |
+| `encrypted` | | 是否启用加密：`false`（默认，明文） / `true`（签名+防重放+透明加密） |
+| `enablePayloadDigest` | | 是否启用 payload 摘要校验，默认 `true`（关闭可提升性能） |
+| `maxTimeSkewMs` | | 时间戳最大允许偏移（毫秒），默认 `30000`，用于防重放校验 |
+| `replayWindowMs` | | nonce 重放缓存窗口（毫秒），默认 `120000` |
 
 ## API
 
@@ -199,7 +219,7 @@ console.log(master.slaves); // ["slave-001", "slave-002"]
 | `publish` | Slave | 收到 master 广播，携带 `{ topic, payload }` |
 | `slave_connected` | Master | slave 注册成功上线，携带 `slaveId` |
 | `slave_disconnected` | Master | slave 注销或发送失败下线，携带 `slaveId` |
-| `auth_failed` | Master | 认证失败（注册或 RPC），请求已被丢弃 |
+| `auth_failed` | Master / Slave | 认证失败（签名校验失败、重放检测失败、解密失败等），请求已被丢弃 |
 | `error` | 两者 | 内部错误 |
 
 ## 本地示例
@@ -224,13 +244,23 @@ pnpm test
 ## 并发压测
 
 ```bash
-# 终端 1：启动 Echo 服务端
+# 终端 1：启动 Echo 服务端（plain）
 pnpm test:echo
 
-# 终端 2：发起并发压测
+# 终端 2：发起并发压测（plain）
 pnpm test:100 -- 100 10000 slave-001
 ```
 
+启用安全模式示例：
+
+```bash
+# 终端 1：加密模式启动 Echo 服务端
+ZNL_AUTH_KEY=my-secret ZNL_ENCRYPTED=true pnpm test:echo
+
+# 终端 2：加密模式压测
+pnpm test:100 -- 100 10000 slave-001 my-secret true
+```
+
 参数说明：
 
 - 总请求数

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyrify/znl",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "description": "ZNL - ZeroMQ Node Link",
   "type": "module",
   "main": "./index.js",
@@ -35,12 +35,24 @@
   "dependencies": {
     "zeromq": "^6.5.0"
   },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.8.1"
+  },
   "scripts": {
     "example:master": "node test/master/index.js",
     "example:slave": "node test/slave/index.js",
     "test": "node test/run.js",
+    "test:unit": "node --test \"test/unit/**/*.test.js\"",
+    "test:all": "pnpm test && pnpm test:unit",
     "test:echo": "node test/master/test-echo-server.js",
     "test:100": "node test/slave/test-100-concurrent.js",
-    "check": "node --check index.js && node --check src/constants.js && node --check src/protocol.js && node --check src/PendingManager.js && node --check src/SendQueue.js && node --check src/ZNL.js && node --check test/master/index.js && node --check test/slave/index.js && node --check test/master/test-echo-server.js && node --check test/slave/test-100-concurrent.js && node --check test/run.js"
+    "test:capture": "node test/capture-frames.js",
+    "check": "node --check index.js && node --check src/constants.js && node --check src/protocol.js && node --check src/security.js && node --check src/PendingManager.js && node --check src/SendQueue.js && node --check src/ZNL.js && node --check test/master/index.js && node --check test/slave/index.js && node --check test/master/test-echo-server.js && node --check test/slave/test-100-concurrent.js && node --check test/run.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --check",
+    "format:write": "prettier . --write"
   }
 }

package/src/SendQueue.js

@@ -6,17 +6,15 @@
  * 虽然 zeromq.js v6 在 JS 层做了一定保护，但显式串行化更安全可靠。
  *
  * 实现原理：
- * 为每个 socket 通道维护一条 Promise 链（队列尾指针）。
- * 每次入队时，新任务追加在当前链尾，前一个任务完成后自动触发。
- * 无论前一个任务成功或失败，队列都会继续执行下一个任务。
+ * 为每个 socket 通道维护一个任务队列与独立消费循环。
+ * 通过单线程 async loop 串行执行，避免长 Promise 链增长。
  */
-
 export class SendQueue {
   /**
-   * 各通道的队列尾指针
-   * @type {Map<string, Promise<void>>}
+   * 通道级队列与运行状态
+   * @type {Map<string, { queue: Array<{ task: Function, resolve: Function, reject: Function }>, running: boolean }>}
    */
-  #tails = new Map();
+  #channels = new Map();
 
   /**
    * 将发送任务追加到指定通道的队列尾部
@@ -26,22 +24,58 @@ export class SendQueue {
    * @returns {Promise<void>} 本次任务的 Promise（可用于错误捕获）
    */
   enqueue(channel, task) {
-    const tail = this.#tails.get(channel) ?? Promise.resolve();
-
-    // 无论前一个任务成功或失败，都继续执行当前任务
-    const run = tail.then(task, task);
+    const name = String(channel);
+    const entry = this.#ensureChannel(name);
 
-    // 更新队尾（吞掉错误，防止产生 UnhandledRejection）
-    this.#tails.set(channel, run.catch(() => {}));
-
-    return run;
+    return new Promise((resolve, reject) => {
+      entry.queue.push({ task, resolve, reject });
+      if (!entry.running) this.#drain(name, entry);
+    });
   }
 
   /**
    * 清空所有通道的队列引用（节点停止时调用）
-   * 注意：已入队但未执行的任务不会被取消，仅释放尾指针引用
+   * 注意：已入队但未执行的任务不会被取消，仅释放引用
    */
   clear() {
-    this.#tails.clear();
+    this.#channels.clear();
+  }
+
+  /**
+   * 确保通道数据结构存在
+   * @param {string} name
+   * @returns {{ queue: Array, running: boolean }}
+   */
+  #ensureChannel(name) {
+    let entry = this.#channels.get(name);
+    if (!entry) {
+      entry = { queue: [], running: false };
+      this.#channels.set(name, entry);
+    }
+    return entry;
+  }
+
+  /**
+   * 串行消费队列
+   * @param {string} name
+   * @param {{ queue: Array, running: boolean }} entry
+   */
+  async #drain(name, entry) {
+    entry.running = true;
+
+    while (entry.queue.length > 0) {
+      const { task, resolve, reject } = entry.queue.shift();
+      try {
+        await task();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    }
+
+    entry.running = false;
+
+    // 清理空通道，避免 Map 无限增长
+    if (entry.queue.length === 0) this.#channels.delete(name);
   }
 }