chanjs 2.7.2 → 2.7.3

package/realtime/websocket.js

@@ -0,0 +1,540 @@
+/**
+ * WebSocket 管理器（基于 ws 库）
+ *
+ * ============================================================
+ * 特性
+ * ============================================================
+ * 1. 基于 ws 库（业界标准），Node 原生 WebSocket 仅为客户端
+ * 2. 房间（Room）机制：分组广播，支持单推/房间广播/全局广播
+ * 3. 心跳保活：默认 30s ping，自动踢除无响应连接
+ * 4. 鉴权钩子：可选的 verifyClient，按业务校验握手请求
+ * 5. 消息路由：on(type, handler) 按消息 type 字段路由
+ * 6. 优雅停机：shutdown() 关闭所有连接与服务端
+ *
+ * ============================================================
+ * 使用方法
+ * ============================================================
+ *
+ * // 1. 在 App.js 启动时自动 attach（推荐，配置驱动）
+ * // config.WEBSOCKET = { enabled: true, path: '/ws' }
+ * // chan.run() 时框架自动调用 websocket.attach(chan.server)
+ *
+ * // 2. 业务侧注册消息处理器
+ * import { websocket } from 'chanjs';
+ * websocket.on('chat', (socket, payload) => {
+ *   websocket.send(socket, { type: 'chat', data: 'echo: ' + payload.text });
+ * });
+ *
+ * // 3. 单推
+ * websocket.send(socketId, { type: 'notice', data: 'hello' });
+ *
+ * // 4. 广播到房间
+ * websocket.broadcast('room-1', { type: 'msg', data: 'hello room' });
+ *
+ * // 5. 全局广播
+ * websocket.broadcastAll({ type: 'ping', data: Date.now() });
+ *
+ * // 6. 鉴权（attach 时配置）
+ * websocket.attach(server, {
+ *   path: '/ws',
+ *   verifyClient: (info, cb) => {
+ *     const ok = checkToken(info.req.headers.token);
+ *     cb(ok ? undefined : new Error('auth failed'), ok ? 200 : 401);
+ *   },
+ * });
+ *
+ * // 7. 状态查询
+ * websocket.getStatus();  // { connections, rooms, uptime }
+ *
+ * ============================================================
+ * 消息协议（建议）
+ * ============================================================
+ * 客户端发送：JSON 字符串 { type: 'chat', data: {...} }
+ * 服务端 send/broadcast：自动 JSON.stringify
+ * 心跳由 ws 库内置 ping/pong 机制处理，对业务透明
+ */
+
+import { WebSocketServer } from 'ws';
+
+/**
+ * 默认心跳间隔（ping 间隔）
+ */
+const DEFAULT_HEARTBEAT_INTERVAL = 30000;
+
+/**
+ * WebSocket 管理器
+ * @class WebSocketManager
+ */
+class WebSocketManager {
+  constructor() {
+    /** @type {import('ws').WebSocketServer|null} ws 服务端 */
+    this._wss = null;
+    /** @type {Map<string, {socket: Object, rooms: Set<string>, joinedAt: number}>} 连接表 id -> client */
+    this._clients = new Map();
+    /** @type {Map<string, Set<string>>} 房间表 room -> Set<clientId> */
+    this._rooms = new Map();
+    /** @type {Map<string, Function>} 消息路由 type -> handler(socket, payload, clientId) */
+    this._handlers = new Map();
+    /** 心跳定时器 */
+    this._heartbeatTimer = null;
+    /** 心跳间隔 */
+    this._heartbeatInterval = DEFAULT_HEARTBEAT_INTERVAL;
+    /** 自增连接 id */
+    this._idSeq = 0;
+    /** 启动时间 */
+    this._startedAt = Date.now();
+    /** 是否已 shutdown */
+    this._shuttingDown = false;
+    /** 最大并发连接数上限，超出直接拒绝握手，防止连接洪泛耗尽内存 */
+    this._maxConnections = 10000;
+  }
+
+  /**
+   * 挂载到 HTTP 服务
+   * @param {Object} server - http.Server 实例（chan.server）
+   * @param {Object} [options]
+   * @param {string} [options.path] - 路径，默认 '/ws'
+   * @param {Function} [options.verifyClient] - 握手鉴权 (info, cb) => void
+   * @param {number} [options.heartbeatInterval] - 心跳间隔，默认 30000
+   * @param {Function} [options.onConnection] - 连接建立回调 (socket, req) => void
+   * @returns {Object} WebSocketServer 实例
+   */
+  attach(server, options = {}) {
+    if (this._wss) {
+      throw new Error('[WebSocket] 已存在 server，请先 shutdown 再 attach');
+    }
+    const {
+      path = '/ws',
+      verifyClient,
+      heartbeatInterval,
+      onConnection,
+    } = options;
+
+    this._wss = new WebSocketServer({
+      noServer: true,  // 不直接接管 server，手动处理 upgrade 以便与 Express 共存
+      verifyClient,
+    });
+
+    // 处理 upgrade 请求
+    // 1. 路径匹配 → 交给 ws 完成 WebSocket 握手
+    // 2. 路径不匹配 → 1 秒后断开，防止客户端挂起（其他模块可提前处理）
+    server.on('upgrade', (req, socket, head) => {
+      const url = new URL(req.url, 'http://localhost');
+      if (url.pathname === path) {
+        this._wss.handleUpgrade(req, socket, head, (ws) => {
+          this._wss.emit('connection', ws, req);
+        });
+        return;
+      }
+      // 非本模块路径：1 秒后兜底断开，避免连接挂起
+      const timer = setTimeout(() => {
+        try { socket.destroy(); } catch (e) {}
+      }, 1000);
+      socket.on('close', () => clearTimeout(timer));
+    });
+
+    // 连接建立
+    this._wss.on('connection', (socket, req) => {
+      this._handleConnection(socket, req);
+      onConnection?.(socket, req);
+    });
+
+    // 启动心跳
+    if (typeof heartbeatInterval === 'number' && heartbeatInterval > 0) {
+      this._heartbeatInterval = heartbeatInterval;
+    }
+    this._ensureHeartbeat();
+
+    console.log(`[WebSocket] 已挂载到路径 ${path}`);
+    return this._wss;
+  }
+
+  /**
+   * 注册消息处理器
+   * @param {string} type - 消息类型（对应 payload.type）
+   * @param {Function} handler - (socket, payload, clientId) => void
+   * @example
+   * websocket.on('chat', (socket, payload, clientId) => {
+   *   websocket.send(socket, { type: 'chat', data: payload.text });
+   * });
+   */
+  on(type, handler) {
+    if (typeof type !== 'string' || typeof handler !== 'function') {
+      throw new Error('[WebSocket] on(type, handler) 参数无效');
+    }
+    this._handlers.set(type, handler);
+  }
+
+  /**
+   * 移除消息处理器
+   * @param {string} type
+   */
+  off(type) {
+    return this._handlers.delete(type);
+  }
+
+  /**
+   * 将连接加入房间
+   * @param {Object|string} target - socket 或 clientId
+   * @param {string} room
+   * @returns {string|null} clientId
+   */
+  join(target, room) {
+    const clientId = this._resolveClientId(target);
+    if (!clientId) return null;
+    const client = this._clients.get(clientId);
+    if (!client) return null;
+
+    client.rooms.add(room);
+    if (!this._rooms.has(room)) this._rooms.set(room, new Set());
+    this._rooms.get(room).add(clientId);
+    return clientId;
+  }
+
+  /**
+   * 离开房间
+   * @param {Object|string} target
+   * @param {string} room
+   * @returns {boolean}
+   */
+  leave(target, room) {
+    const clientId = this._resolveClientId(target);
+    if (!clientId) return false;
+    const client = this._clients.get(clientId);
+    if (!client) return false;
+
+    client.rooms.delete(room);
+    const members = this._rooms.get(room);
+    if (members) {
+      members.delete(clientId);
+      if (members.size === 0) this._rooms.delete(room);
+    }
+    return true;
+  }
+
+  /**
+   * 向单个连接发送消息
+   * @param {Object|string} target - socket 或 clientId
+   * @param {*} data - 任意可序列化数据
+   * @returns {boolean} 是否发送成功
+   */
+  send(target, data) {
+    const clientId = this._resolveClientId(target);
+    if (!clientId) return false;
+    const client = this._clients.get(clientId);
+    if (!client) return false;
+
+    return this._safeSend(client.socket, data);
+  }
+
+  /**
+   * 广播到指定房间
+   * @param {string} room
+   * @param {*} data
+   * @param {Object} [options]
+   * @param {Object} [options.exclude] - 排除的 socket 或 clientId
+   * @returns {number} 实际送达数
+   */
+  broadcast(room, data, options = {}) {
+    const members = this._rooms.get(room);
+    if (!members || members.size === 0) return 0;
+
+    const excludeId = options.exclude
+      ? this._resolveClientId(options.exclude)
+      : null;
+
+    let sent = 0;
+    for (const clientId of members) {
+      if (clientId === excludeId) continue;
+      if (this.send(clientId, data)) sent++;
+    }
+    return sent;
+  }
+
+  /**
+   * 广播到所有连接
+   * @param {*} data
+   * @param {Object} [options]
+   * @param {Object} [options.exclude] - 排除的 socket 或 clientId
+   * @returns {number}
+   */
+  broadcastAll(data, options = {}) {
+    const excludeId = options.exclude
+      ? this._resolveClientId(options.exclude)
+      : null;
+
+    let sent = 0;
+    for (const clientId of this._clients.keys()) {
+      if (clientId === excludeId) continue;
+      if (this.send(clientId, data)) sent++;
+    }
+    return sent;
+  }
+
+  /**
+   * 获取当前连接数
+   * @returns {number}
+   */
+  size() {
+    return this._clients.size;
+  }
+
+  /**
+   * 获取指定房间连接数
+   * @param {string} room
+   * @returns {number}
+   */
+  roomSize(room) {
+    return this._rooms.get(room)?.size || 0;
+  }
+
+  /**
+   * 获取运行状态
+   * @returns {Object} { connections, rooms, uptime, path }
+   */
+  getStatus() {
+    return {
+      connections: this._clients.size,
+      rooms: this._rooms.size,
+      roomList: Array.from(this._rooms.keys()),
+      path: this._wss?.options?.path || null,
+      uptime: Date.now() - this._startedAt,
+    };
+  }
+
+  /**
+   * 优雅停机
+   */
+  shutdown() {
+    this._shuttingDown = true;
+
+    // 停止心跳
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+
+    // 关闭所有客户端连接
+    for (const [, client] of this._clients) {
+      try {
+        client.socket.terminate();
+      } catch (e) {
+        // 忽略
+      }
+    }
+    this._clients.clear();
+    this._rooms.clear();
+
+    // 关闭 ws 服务端
+    if (this._wss) {
+      try {
+        this._wss.close();
+      } catch (e) {
+        // 忽略
+      }
+      this._wss = null;
+    }
+
+    console.log(`[WebSocket] 已关闭所有 WebSocket 连接`);
+  }
+
+  // ============================================================
+  // 私有方法
+  // ============================================================
+
+  /**
+   * 处理新连接
+   * @private
+   */
+  _handleConnection(socket, req) {
+    if (this._shuttingDown) {
+      socket.terminate();
+      return;
+    }
+
+    // 连接数上限校验：超出直接拒绝握手，防止连接洪泛
+    if (this._clients.size >= this._maxConnections) {
+      console.error(`[WebSocket] 连接数已达上限 (${this._maxConnections})，拒绝新连接`);
+      try {
+        socket.close(1013, 'Maximum connections reached');  // 1013 = Try Again Later
+      } catch (e) {}
+      socket.terminate();
+      return;
+    }
+
+    const clientId = `ws_${++this._idSeq}_${Date.now()}`;
+    this._clients.set(clientId, {
+      socket,
+      rooms: new Set(),
+      joinedAt: Date.now(),
+    });
+
+    // 注入到 socket 便于业务侧使用
+    socket.clientId = clientId;
+    socket.join = (room) => this.join(socket, room);
+    socket.leave = (room) => this.leave(socket, room);
+    // 保存原生 send，再覆盖为业务便捷方法（避免 _safeSend 递归调用）
+    socket._rawSend = socket.send.bind(socket);
+    socket.send = (data) => this.send(socket, data);
+    socket.broadcast = (room, data) => this.broadcast(room, data, { exclude: socket });
+
+    // 消息路由
+    socket.on('message', (raw) => {
+      this._handleMessage(socket, clientId, raw);
+    });
+
+    // 连接关闭
+    socket.on('close', () => {
+      this._removeClient(clientId);
+    });
+
+    socket.on('error', (err) => {
+      console.error(`[WebSocket] 连接 ${clientId} 错误:`, err.message);
+    });
+
+    // pong 响应（心跳保活）
+    socket.on('pong', () => {
+      socket._isAlive = true;
+    });
+
+    socket._isAlive = true;
+  }
+
+  /**
+   * 处理收到的消息
+   * @private
+   */
+  _handleMessage(socket, clientId, raw) {
+    let payload;
+    try {
+      payload = JSON.parse(raw.toString());
+    } catch (e) {
+      // 非 JSON 消息，作为 raw 类型分发
+      payload = { type: 'raw', data: raw.toString() };
+    }
+
+    const type = payload?.type;
+    const handler = type ? this._handlers.get(type) : null;
+
+    if (handler) {
+      try {
+        handler(socket, payload, clientId);
+      } catch (err) {
+        console.error(`[WebSocket] 处理器 ${type} 异常:`, err.message);
+      }
+    } else if (this._handlers.has('*')) {
+      // 通配符处理器
+      try {
+        this._handlers.get('*')(socket, payload, clientId);
+      } catch (err) {
+        console.error(`[WebSocket] 通配符处理器异常:`, err.message);
+      }
+    }
+    // 无匹配处理器时静默丢弃，避免消息洪泛
+  }
+
+  /**
+   * 安全发送（处理连接已关闭/异常）
+   * @private
+   */
+  _safeSend(socket, data) {
+    if (socket.readyState !== 1 /* OPEN */) return false;
+    try {
+      const payload = typeof data === 'string' ? data : JSON.stringify(data);
+      // 用原生 send（_rawSend），避免调用被覆盖的 socket.send 导致递归
+      const sendFn = socket._rawSend || socket.send.bind(socket);
+      sendFn(payload);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /**
+   * 启动心跳（ping 检测，无响应则踢除）
+   * @private
+   */
+  _ensureHeartbeat() {
+    if (this._heartbeatTimer) return;
+
+    this._heartbeatTimer = setInterval(() => {
+      if (this._clients.size === 0) return;
+
+      for (const [clientId, client] of this._clients) {
+        if (client.socket._isAlive === false) {
+          // 上次 ping 无响应，踢除
+          client.socket.terminate();
+          this._removeClient(clientId);
+          continue;
+        }
+        client.socket._isAlive = false;
+        try {
+          client.socket.ping();
+        } catch (e) {
+          // 忽略
+        }
+      }
+    }, this._heartbeatInterval);
+
+    if (this._heartbeatTimer.unref) this._heartbeatTimer.unref();
+  }
+
+  /**
+   * 移除客户端（清理房间索引）
+   * @private
+   */
+  _removeClient(clientId) {
+    const client = this._clients.get(clientId);
+    if (!client) return;
+
+    for (const room of client.rooms) {
+      const members = this._rooms.get(room);
+      if (members) {
+        members.delete(clientId);
+        if (members.size === 0) this._rooms.delete(room);
+      }
+    }
+    this._clients.delete(clientId);
+  }
+
+  /**
+   * 解析 clientId（接受 socket 或 clientId）
+   * @private
+   */
+  _resolveClientId(target) {
+    if (typeof target === 'string') return target;
+    if (target?.clientId) return target.clientId;
+    return null;
+  }
+}
+
+// 全局单例（懒加载：首次访问属性时才实例化，避免 import 即实例化浪费内存）
+let _wsInstance = null;
+const getWSInstance = () => {
+  if (!_wsInstance) _wsInstance = new WebSocketManager();
+  return _wsInstance;
+};
+
+// 用 Proxy 保持 `import { websocket } from 'chanjs'` API 兼容，访问任意属性时才实例化
+const websocket = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      const inst = getWSInstance();
+      const val = inst[prop];
+      return typeof val === 'function' ? val.bind(inst) : val;
+    },
+    set(_target, prop, value) {
+      getWSInstance()[prop] = value;
+      return true;
+    },
+    has(_target, prop) {
+      return prop in getWSInstance();
+    },
+    getPrototypeOf() {
+      return WebSocketManager.prototype;
+    },
+  }
+);
+
+export { websocket as default, websocket, WebSocketManager, DEFAULT_HEARTBEAT_INTERVAL as WS_DEFAULT_HEARTBEAT_INTERVAL };

package/response/index.js

@@ -0,0 +1,12 @@
+/**
+ * 响应格式化模块 - 统一响应结构 + 数据库错误解析
+ * 响应码体系：0 成功 / 1xxx 业务 / 5xxx 系统 / 6xxx 数据库
+ */
+export {
+  success,
+  fail,
+  error,
+  parseDatabaseError,
+  notFoundResponse,
+  errorResponse,
+} from "./response.js";