@lyrify/znl 0.5.1 → 0.5.2

package/README.md

@@ -13,6 +13,8 @@
 - 加密开关 `encrypted`：
   - `false`：明文模式（不签名/不加密）
   - `true`：签名 + 防重放 + payload 透明加密（AES-256-GCM）
+- 可选关闭 payload 摘要校验（`enablePayloadDigest=false`）以提升性能
+  - 建议 master/slave 两端保持一致配置，避免认证不一致
 - `authKey` 仅在 `encrypted=true` 时必填
 - Payload 支持 `string`、`Buffer`、`Uint8Array` 及其数组（多帧）
 
@@ -99,9 +101,12 @@ 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,
 });
@@ -112,9 +117,12 @@ new ZNL({
 | `role` | ✓ | 节点角色，`"master"` 或 `"slave"` |
 | `id` | ✓ | 节点唯一标识；slave 端同时作为 ZMQ `routingId` |
 | `endpoints.router` | | ROUTER 端点，默认 `tcp://127.0.0.1:6003` |
-| `maxPending` | | 最大并发 RPC 请求数，`0` 表示不限制 |
+| `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` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyrify/znl",
-  "version": "0.5.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/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"
+    "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);
   }
 }

package/src/ZNL.js

@@ -20,7 +20,8 @@
  * 心跳机制：
  *  - slave 每隔 heartbeatInterval ms 向 master 发送一帧心跳
  *  - master 每隔 heartbeatInterval ms 扫描一次在线列表
- *  - 超过 heartbeatInterval × 3 ms 未收到心跳，判定 slave 已崩溃并移除
+ *  - 超过 heartbeatTimeoutMs 未收到心跳，判定 slave 已崩溃并移除
+ *    （heartbeatTimeoutMs <= 0 时，默认按 heartbeatInterval × 3 计算）
  */
 
 import { randomUUID } from "node:crypto";
@@ -30,6 +31,9 @@ import * as zmq from "zeromq";
 import {
   DEFAULT_ENDPOINTS,
   DEFAULT_HEARTBEAT_INTERVAL,
+  DEFAULT_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_MAX_PENDING,
+  DEFAULT_ENABLE_PAYLOAD_DIGEST,
   CONTROL_PREFIX,
   CONTROL_HEARTBEAT,
   SECURITY_ENVELOPE_VERSION,
@@ -59,7 +63,6 @@ import {
   generateNonce,
   nowMs,
   canonicalSignInput,
-  signText,
   encodeAuthProofToken,
   decodeAuthProofToken,
   encryptFrames,
@@ -118,6 +121,12 @@ export class ZNL extends EventEmitter {
   /** @type {Function|null} slave 侧收到 master 请求时的自动回复处理器 */
   #dealerAutoHandler = null;
 
+  /** @type {number} 心跳超时时间（ms），0 表示使用 interval × 3 */
+  #heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS;
+
+  /** @type {boolean} 是否启用 payload 摘要校验（安全模式用） */
+  #enablePayloadDigest = DEFAULT_ENABLE_PAYLOAD_DIGEST;
+
   // ─── PUB/SUB 状态 ────────────────────────────────────────────────────────
 
   /**
@@ -174,22 +183,26 @@ export class ZNL extends EventEmitter {
    *   role               : "master"|"slave",
    *   id                 : string,
    *   endpoints?         : { router?: string },
-   *   maxPending?        : number,
-   *   authKey?           : string,
-   *   heartbeatInterval? : number,
-   *   encrypted?         : boolean,
-   *   maxTimeSkewMs?     : number,
-   *   replayWindowMs?    : number,
+   *   maxPending?          : number,
+   *   authKey?             : string,
+   *   heartbeatInterval?   : number,
+   *   heartbeatTimeoutMs?  : number,
+   *   encrypted?           : boolean,
+   *   enablePayloadDigest? : boolean,
+   *   maxTimeSkewMs?       : number,
+   *   replayWindowMs?      : number,
    * }} options
    */
   constructor({
     role,
     id,
     endpoints = {},
-    maxPending = 0,
+    maxPending = DEFAULT_MAX_PENDING,
     authKey = "",
     heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL,
+    heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS,
     encrypted = false,
+    enablePayloadDigest = DEFAULT_ENABLE_PAYLOAD_DIGEST,
     maxTimeSkewMs = MAX_TIME_SKEW_MS,
     replayWindowMs = REPLAY_WINDOW_MS,
   } = {}) {
@@ -224,6 +237,15 @@ export class ZNL extends EventEmitter {
     this.#heartbeatInterval =
       this.#normalizeHeartbeatInterval(heartbeatInterval);
 
+    // 是否启用 payload 摘要校验（安全模式用）
+    this.#enablePayloadDigest = Boolean(enablePayloadDigest);
+
+    // 心跳超时：<=0 则由 heartbeatInterval 推导
+    this.#heartbeatTimeoutMs = this.#normalizePositiveInt(
+      heartbeatTimeoutMs,
+      DEFAULT_HEARTBEAT_TIMEOUT_MS,
+    );
+
     this.#maxTimeSkewMs = this.#normalizePositiveInt(
       maxTimeSkewMs,
       MAX_TIME_SKEW_MS,
@@ -546,8 +568,8 @@ export class ZNL extends EventEmitter {
         }
       }
 
-      const entry = this.#slaves.get(identityText);
-      if (entry) entry.lastSeen = Date.now();
+      // 心跳视为在线确认：必要时自动补注册
+      this.#ensureSlaveOnline(identityText, identity, { touch: true });
       return;
     }
 
@@ -597,6 +619,9 @@ export class ZNL extends EventEmitter {
           return;
         }
 
+        // 认证通过后允许补注册（避免 master 重启后丢失在线表）
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
+
         if (this.encrypted) {
           try {
             finalFrames = this.#openPayloadFrames(
@@ -613,6 +638,9 @@ export class ZNL extends EventEmitter {
             return;
           }
         }
+      } else {
+        // 明文模式同样补注册
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
       }
 
       const finalPayload = payloadFromFrames(finalFrames);
@@ -647,6 +675,9 @@ export class ZNL extends EventEmitter {
           return;
         }
 
+        // 认证通过后允许补注册（避免 master 重启后丢失在线表）
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
+
         if (this.encrypted) {
           try {
             finalFrames = this.#openPayloadFrames(
@@ -663,6 +694,9 @@ export class ZNL extends EventEmitter {
             return;
           }
         }
+      } else {
+        // 明文模式同样补注册
+        this.#ensureSlaveOnline(identityText, identity, { touch: true });
       }
 
       const finalPayload = payloadFromFrames(finalFrames);
@@ -998,7 +1032,11 @@ export class ZNL extends EventEmitter {
   #startHeartbeatCheck() {
     if (this.#heartbeatInterval <= 0) return;
 
-    const timeout = this.#heartbeatInterval * 3;
+    // 心跳超时：优先使用配置值，<=0 则回退到 interval × 3
+    const timeout =
+      this.#heartbeatTimeoutMs > 0
+        ? this.#heartbeatTimeoutMs
+        : this.#heartbeatInterval * 3;
 
     this.#heartbeatCheckTimer = setInterval(() => {
       const now = Date.now();
@@ -1032,7 +1070,10 @@ export class ZNL extends EventEmitter {
       requestId: String(requestId ?? ""),
       timestamp: nowMs(),
       nonce: generateNonce(),
-      payloadDigest: digestFrames(payloadFrames),
+      // 可选 payload 摘要：关闭时写空串以提升性能
+      payloadDigest: this.#enablePayloadDigest
+        ? digestFrames(payloadFrames)
+        : "",
     };
 
     // 保留 canonical 文本，便于后续排障（签名实际在 token 内完成）
@@ -1100,12 +1141,15 @@ export class ZNL extends EventEmitter {
       };
     }
 
-    const currentDigest = digestFrames(payloadFrames);
-    if (String(envelope.payloadDigest) !== currentDigest) {
-      return { ok: false, error: "payload 摘要不一致，疑似篡改。" };
+    if (this.#enablePayloadDigest) {
+      const currentDigest = digestFrames(payloadFrames);
+      if (String(envelope.payloadDigest) !== currentDigest) {
+        return { ok: false, error: "payload 摘要不一致，疑似篡改。" };
+      }
     }
 
-    const replayKey = `${envelope.kind}|${envelope.nodeId}|${envelope.nonce}`;
+    // 重放 key 加入 requestId，降低 nonce 碰撞误杀风险
+    const replayKey = `${envelope.kind}|${envelope.nodeId}|${envelope.requestId}|${envelope.nonce}`;
     if (this.#replayGuard.seenOrAdd(replayKey)) {
       return { ok: false, error: "检测到重放请求（nonce 重复）。" };
     }
@@ -1194,6 +1238,33 @@ export class ZNL extends EventEmitter {
     });
   }
 
+  /**
+   * master 侧确保某个 slave 已登记在线
+   * - 仅在认证通过后调用
+   * - 支持心跳/请求/响应等路径的自动补注册
+   *
+   * @param {string} identityText
+   * @param {Buffer|string|Uint8Array} identity
+   * @param {{ touch?: boolean }} [options]
+   */
+  #ensureSlaveOnline(identityText, identity, { touch = true } = {}) {
+    const id = String(identityText ?? "");
+    if (!id) return;
+
+    const now = Date.now();
+    const entry = this.#slaves.get(id);
+    if (entry) {
+      if (touch) entry.lastSeen = now;
+      return;
+    }
+
+    this.#slaves.set(id, {
+      identity: identityToBuffer(identity),
+      lastSeen: now,
+    });
+    this.emit("slave_connected", id);
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   //  工具方法
   // ═══════════════════════════════════════════════════════════════════════════

package/src/constants.js

@@ -36,6 +36,15 @@ export const DEFAULT_TIMEOUT_MS = 5000;
 /** 默认心跳间隔（毫秒），0 表示禁用心跳 */
 export const DEFAULT_HEARTBEAT_INTERVAL = 3000;
 
+/** 默认心跳超时时间（毫秒），0 表示采用 heartbeatInterval × 3 */
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 0;
+
+/** 默认最大并发请求数（0 表示不限制） */
+export const DEFAULT_MAX_PENDING = 1000;
+
+/** 默认是否启用 payload 摘要（安全模式用） */
+export const DEFAULT_ENABLE_PAYLOAD_DIGEST = true;
+
 /** 默认端点配置 */
 export const DEFAULT_ENDPOINTS = {
   router: "tcp://127.0.0.1:6003",

package/src/security.js

@@ -385,11 +385,29 @@ export function decodeAuthProofToken(
 
 /**
  * 计算 payload 帧摘要（sha256 hex）
+ * 说明：按协议顺序增量写入，避免一次性拼接大 Buffer
  * @param {Buffer[]} frames
  * @returns {string}
  */
 export function digestFrames(frames) {
-  return createHash("sha256").update(encodeFrames(frames)).digest("hex");
+  const safeFrames = Array.isArray(frames) ? frames : [];
+  const hash = createHash("sha256");
+
+  // 写入帧数量（u32be）
+  const head = Buffer.allocUnsafe(4);
+  head.writeUInt32BE(safeFrames.length, 0);
+  hash.update(head);
+
+  // 逐帧写入长度与内容（u32be + bytes）
+  for (const frame of safeFrames) {
+    const buf = toBuffer(frame);
+    const len = Buffer.allocUnsafe(4);
+    len.writeUInt32BE(buf.length, 0);
+    hash.update(len);
+    if (buf.length > 0) hash.update(buf);
+  }
+
+  return hash.digest("hex");
 }
 
 /**