@lyrify/znl 0.4.1

package/src/constants.js

@@ -0,0 +1,42 @@
+/**
+ * 协议常量与默认配置
+ * 集中管理所有魔法字符串和默认值，避免散落在业务代码中
+ */
+
+/** 控制帧版本前缀，用于区分控制帧与业务帧 */
+export const CONTROL_PREFIX = "__znl_v1__";
+
+/** 请求类型标识符 */
+export const CONTROL_REQ = "req";
+
+/** 响应类型标识符 */
+export const CONTROL_RES = "res";
+
+/** 认证 Key 帧标识符（位于 req 帧中） */
+export const CONTROL_AUTH = "__znl_v1_auth__";
+
+/** slave 保活心跳帧标识符（slave → master，定时发送） */
+export const CONTROL_HEARTBEAT = "heartbeat";
+
+/** slave 上线注册帧标识符（slave → master，start 时自动发送） */
+export const CONTROL_REGISTER = "register";
+
+/** slave 下线注销帧标识符（slave → master，stop 时自动发送） */
+export const CONTROL_UNREGISTER = "unregister";
+
+/** 广播推送帧标识符（master → slave，publish 时发送） */
+export const CONTROL_PUB = "pub";
+
+/** 空 Buffer（全局复用，避免重复分配） */
+export const EMPTY_BUFFER = Buffer.alloc(0);
+
+/** 默认请求超时时间（毫秒） */
+export const DEFAULT_TIMEOUT_MS = 5000;
+
+/** 默认心跳间隔（毫秒），0 表示禁用心跳 */
+export const DEFAULT_HEARTBEAT_INTERVAL = 3000;
+
+/** 默认端点配置 */
+export const DEFAULT_ENDPOINTS = {
+  router: "tcp://127.0.0.1:6003",
+};

package/src/protocol.js

@@ -0,0 +1,277 @@
+/**
+ * ZMQ 帧协议层
+ *
+ * 负责所有帧的构建与解析，全部为纯函数，无副作用。
+ *
+ * 控制帧格式：
+ *   注册帧：  [PREFIX, "register", (AUTH_MARKER, authKey)?]
+ *   注销帧：  [PREFIX, "unregister"]
+ *   请求帧：  [PREFIX, "req", requestId, (AUTH_MARKER, authKey)?, ...payload]
+ *   响应帧：  [PREFIX, "res", requestId, ...payload]
+ *   广播帧：  [PREFIX, "pub", topic, ...payload]
+ *   Router 侧额外在最前面加一帧：[identity, ...]
+ */
+
+import {
+  CONTROL_PREFIX,
+  CONTROL_REQ,
+  CONTROL_RES,
+  CONTROL_AUTH,
+  CONTROL_REGISTER,
+  CONTROL_UNREGISTER,
+  CONTROL_PUB,
+  CONTROL_HEARTBEAT,
+  EMPTY_BUFFER,
+} from "./constants.js";
+
+// ─── Identity 工具 ────────────────────────────────────────────────────────────
+
+/**
+ * 将 identity 帧转换为可读字符串（用于日志和 Map key）
+ * @param {Buffer|string} identity
+ * @returns {string}
+ */
+export function identityToString(identity) {
+  return Buffer.isBuffer(identity) ? identity.toString() : String(identity);
+}
+
+/**
+ * 将 identity 转换为 Buffer（ZMQ 帧要求 Buffer 格式）
+ * @param {Buffer|Uint8Array|string} identity
+ * @returns {Buffer}
+ */
+export function identityToBuffer(identity) {
+  if (Buffer.isBuffer(identity)) return identity;
+  if (identity instanceof Uint8Array) return Buffer.from(identity);
+  return Buffer.from(String(identity));
+}
+
+// ─── Payload 工具 ─────────────────────────────────────────────────────────────
+
+/**
+ * 标准化单个帧为 ZMQ 可传输的格式
+ * - null/undefined → 空 Buffer
+ * - string         → 原样保留
+ * - Buffer         → 原样保留
+ * - Uint8Array     → 转为 Buffer
+ * - 其他           → 抛出 TypeError
+ * @param {string|Buffer|Uint8Array|null|undefined} frame
+ * @returns {string|Buffer}
+ */
+export function normalizeFrame(frame) {
+  if (frame == null) return EMPTY_BUFFER;
+  if (typeof frame === "string") return frame;
+  if (Buffer.isBuffer(frame)) return frame;
+  if (frame instanceof Uint8Array) return Buffer.from(frame);
+  throw new TypeError(
+    "payload 仅支持 string / Buffer / Uint8Array（或它们的数组）。",
+  );
+}
+
+/**
+ * 将 payload 标准化为帧数组
+ * 数组类型逐项标准化，非数组包装成单元素数组
+ * @param {string|Buffer|Uint8Array|Array} payload
+ * @returns {Array<string|Buffer>}
+ */
+export function normalizeFrames(payload) {
+  if (Array.isArray(payload)) return payload.map(normalizeFrame);
+  return [normalizeFrame(payload)];
+}
+
+/**
+ * 从帧数组中提取 payload
+ * - 空帧组 → 空 Buffer
+ * - 单帧   → 直接返回（避免不必要的数组包装）
+ * - 多帧   → 返回数组（多帧 payload 原样保留）
+ * @param {Array} frames
+ * @returns {Buffer|Array}
+ */
+export function payloadFromFrames(frames) {
+  if (!frames?.length) return EMPTY_BUFFER;
+  return frames.length === 1 ? frames[0] : frames;
+}
+
+// ─── 帧构建 ───────────────────────────────────────────────────────────────────
+
+/**
+ * 构建注册控制帧数组（slave → master，连接时自动发送）
+ * 帧结构：[PREFIX, "register", (AUTH_MARKER, authKey)?]
+ * @param {string} [authKey] - 可选认证 Key
+ * @returns {Array}
+ */
+export function buildRegisterFrames(authKey = "") {
+  const frames = [CONTROL_PREFIX, CONTROL_REGISTER];
+  if (authKey) frames.push(CONTROL_AUTH, authKey);
+  return frames;
+}
+
+/**
+ * 构建注销控制帧数组（slave → master，断开时自动发送）
+ * 帧结构：[PREFIX, "unregister"]
+ * @returns {Array}
+ */
+export function buildUnregisterFrames() {
+  return [CONTROL_PREFIX, CONTROL_UNREGISTER];
+}
+
+/**
+ * 构建请求控制帧数组
+ * 帧结构：[PREFIX, "req", requestId, (AUTH_MARKER, authKey)?, ...payloadFrames]
+ * @param {string} requestId - UUID
+ * @param {Array<string|Buffer>} payloadFrames - 已标准化的 payload 帧
+ * @param {string} [authKey] - 可选认证 Key
+ * @returns {Array}
+ */
+export function buildRequestFrames(requestId, payloadFrames, authKey = "") {
+  const header = [CONTROL_PREFIX, CONTROL_REQ, requestId];
+  if (authKey) header.push(CONTROL_AUTH, authKey);
+  return [...header, ...payloadFrames];
+}
+
+/**
+ * 构建响应控制帧数组
+ * 帧结构：[PREFIX, "res", requestId, ...payloadFrames]
+ * @param {string} requestId
+ * @param {Array<string|Buffer>} payloadFrames
+ * @returns {Array}
+ */
+export function buildResponseFrames(requestId, payloadFrames) {
+  return [CONTROL_PREFIX, CONTROL_RES, String(requestId), ...payloadFrames];
+}
+
+/**
+ * 构建广播控制帧数组（master → slave）
+ * 帧结构：[PREFIX, "pub", topic, ...payloadFrames]
+ * @param {string} topic - 消息主题
+ * @param {Array<string|Buffer>} payloadFrames - 已标准化的 payload 帧
+ * @returns {Array}
+ */
+export function buildPublishFrames(topic, payloadFrames) {
+  return [CONTROL_PREFIX, CONTROL_PUB, String(topic), ...payloadFrames];
+}
+
+// ─── 帧解析 ───────────────────────────────────────────────────────────────────
+
+/**
+ * 解析 ZMQ 原始帧，识别控制帧并提取语义字段
+ *
+ * 返回 kind 说明：
+ * - "register"   → slave 上线注册（携带可选 authKey）
+ * - "unregister" → slave 主动下线注销
+ * - "publish"    → master 广播消息（携带 topic）
+ * - "request"    → 对端主动发起的 RPC 请求
+ * - "response"   → 对端返回的 RPC 响应（匹配 pending 请求）
+ * - "message"    → 非控制帧，普通消息透传
+ *
+ * @param {Array} frames - 不含 identity 帧的帧数组
+ * @returns {{
+ *   kind        : "register"|"unregister"|"publish"|"request"|"response"|"message",
+ *   requestId   : string|null,
+ *   authKey     : string|null,
+ *   topic       : string|null,
+ *   payloadFrames: Array
+ * }}
+ */
+export function parseControlFrames(frames) {
+  // 至少需要 2 帧且首帧匹配前缀才能识别控制帧
+  if (frames.length < 2 || frames[0]?.toString() !== CONTROL_PREFIX) {
+    return {
+      kind: "message",
+      requestId: null,
+      authKey: null,
+      topic: null,
+      payloadFrames: frames,
+    };
+  }
+
+  const action = frames[1]?.toString();
+
+  // ── 注册帧：[PREFIX, "register", (AUTH_MARKER, authKey)?] ─────────────────
+  if (action === CONTROL_REGISTER) {
+    let authKey = null;
+    if (frames.length >= 4 && frames[2]?.toString() === CONTROL_AUTH) {
+      authKey = frames[3]?.toString() ?? "";
+    }
+    return {
+      kind: "register",
+      requestId: null,
+      authKey,
+      topic: null,
+      payloadFrames: [],
+    };
+  }
+
+  // ── 注销帧：[PREFIX, "unregister"] ────────────────────────────────────────
+  if (action === CONTROL_UNREGISTER) {
+    return {
+      kind: "unregister",
+      requestId: null,
+      authKey: null,
+      topic: null,
+      payloadFrames: [],
+    };
+  }
+
+  // ── 心跳帧：[PREFIX, "heartbeat"] ─────────────────────────────────────────
+  if (action === CONTROL_HEARTBEAT) {
+    return {
+      kind: "heartbeat",
+      requestId: null,
+      authKey: null,
+      topic: null,
+      payloadFrames: [],
+    };
+  }
+
+  // ── 广播帧：[PREFIX, "pub", topic, ...payloadFrames] ─────────────────────
+  if (action === CONTROL_PUB && frames.length >= 3) {
+    const topic = frames[2]?.toString() ?? "";
+    return {
+      kind: "publish",
+      requestId: null,
+      authKey: null,
+      topic,
+      payloadFrames: frames.slice(3),
+    };
+  }
+
+  // ── 请求 / 响应帧：[PREFIX, "req"/"res", requestId, ...] ─────────────────
+  if (
+    (action === CONTROL_REQ || action === CONTROL_RES) &&
+    frames.length >= 3
+  ) {
+    const requestId = frames[2]?.toString();
+    if (requestId) {
+      let payloadStart = 3;
+      let authKey = null;
+
+      // 请求帧中可能携带认证 Key（仅 CONTROL_REQ 有此结构）
+      if (
+        action === CONTROL_REQ &&
+        frames.length >= 5 &&
+        frames[3]?.toString() === CONTROL_AUTH
+      ) {
+        authKey = frames[4]?.toString() ?? "";
+        payloadStart = 5;
+      }
+
+      return {
+        kind: action === CONTROL_REQ ? "request" : "response",
+        requestId,
+        authKey,
+        topic: null,
+        payloadFrames: frames.slice(payloadStart),
+      };
+    }
+  }
+
+  // ── 无法识别：透传为普通消息 ──────────────────────────────────────────────
+  return {
+    kind: "message",
+    requestId: null,
+    authKey: null,
+    topic: null,
+    payloadFrames: frames,
+  };
+}