mm_websocket_server 2.0.0 → 2.0.1

package/README.md

@@ -9,13 +9,17 @@
 ## 消息路径
 
 ```
-WebSocket.Server → connection → ctx = { client_id, path, ws }
-                 → eventManager.run(path, params, ctx, options)
+WebSocket.Server → connection → ctx = { client_id, path, scope, ws }
+                 → eventManager.run(path, params, ctx, options)（同一连接的消息串行执行）
                  → 结果非空时回发来源连接
 ```
 
 事件 `target` 取握手请求路径（第一个 `?` 之前）。`params` 为 `{ client_id, data }`，`data` 在 `json: true` 时尝试 `JSON.parse`（失败回落原文）。
 
+同一连接的消息按到达顺序串行执行：事件处理函数返回 Promise 时，后一条消息会等前一条处理完再开始，避免响应乱序。
+
+二进制帧保持 `Buffer` 原样传给事件（`ctx.is_binary` 为 `true`），不参与 `json` 解析；事件返回 `Buffer` 时也按二进制帧回发。文本帧走 `json` / UTF-8 文本逻辑。
+
 ## 快速开始
 
 ```js
@@ -48,6 +52,7 @@ console.log(websocket.getAddress());
 | `host` | string | `'0.0.0.0'` | 监听地址 |
 | `port` | number | `8090` | 监听端口 |
 | `json` | boolean | `true` | 入站尝试 JSON 解析，出站对象自动序列化 |
+| `scope` | string | `'websocket'` | 事件管理器作用域，多实例可用不同 scope 隔离事件 |
 | `params` | object | `{ action }` | `main` 的参数约定 |
 
 不限制升级路径，任何路径都可连接，路径即事件 `target`。
@@ -58,7 +63,7 @@ console.log(websocket.getAddress());
 | --- | --- |
 | `init()` / `start()` / `stop()` / `dispose()` | `Mod` 生命周期模板方法 |
 | `onInit()` / `onStart()` / `onStop()` / `onDispose()` | 生命周期钩子，子类可覆盖 |
-| `getEventManager()` | 获取 `mm_event` 的 `websocket` 作用域事件管理器（与其他实例共享），用于注册事件 |
+| `getEventManager()` | 获取 `mm_event` 上 `scope` 作用域的事件管理器（默认 `websocket`，其他实例共享同一作用域），用于注册事件 |
 | `setEventManager(manager)` | 注入外部事件管理器，需提供 `run()` |
 | `getAddress()` | 实际监听地址，未启动为 `null` |
 | `run(params, ctx, options)` | 主动操作入口，`params.action` 派发 `send` / `broadcast` / `close` / `list` |
@@ -75,6 +80,8 @@ console.log(websocket.getAddress());
 | --- | --- |
 | `client_id` | 连接编号，形如 `ws_1` |
 | `path` | 握手请求路径，`?` 之后已截断 |
+| `scope` | 当前实例的事件管理器作用域 |
+| `is_binary` | 是否为二进制帧 |
 | `ws` | 原生 ws 连接，事件可直接写出 |
 
 ## 事件处理函数
@@ -98,9 +105,13 @@ await websocket.run({ action: 'close', client_id: 'ws_1' });
 await websocket.run({ action: 'list' });
 ```
 
+`action` 仅支持上述四种，其他值直接抛 `unsupported action` 错误。
+
 ## 生命周期
 
-`onStart` 创建并监听 `WebSocket.Server`，`onStop` 断开全部连接并关闭服务器。事件管理器取自 `mm_event` 的 `websocket` 作用域，由全局 `Admin` 共享，停止时不清理。端口被占用时 `start()` 抛错，模块进入 `error` 状态，可 `dispose()` 释放。
+`onStart` 先挂 `error` / `connection` 监听再等待 `listening`，创建并监听 `WebSocket.Server`；`onStop` 断开全部连接并关闭服务器。启动失败（如端口被占用）时会先回滚已创建的服务器与连接表再抛错，模块进入 `error` 状态，可 `dispose()` 释放。
+
+事件管理器取自 `mm_event` 上 `scope` 指定的作用域（默认 `websocket`），由全局 `Admin` 共享，停止时不清理；多个实例需要不同作用域时，配置不同的 `scope` 即可。
 
 ## 示例
 

package/lib/websocket.js

@@ -41,6 +41,7 @@ class WebSocketServer extends Mod {
     host: '0.0.0.0',
     port: 8090,
     json: true,
+    scope: 'websocket',
     params: {
       type: 'object',
       required: ['action'],
@@ -79,23 +80,41 @@ class WebSocketServer extends Mod {
    */
   constructor(config, server) {
     super(config, server);
-    this.#events = eventAdmin('websocket');
+    this.#events = eventAdmin(this.config.scope);
   }
 
   // ---------- 生命周期钩子 ----------
   /**
-   * 启动钩子：创建 ws 服务器并开始监听
+   * 启动钩子：创建 ws 服务器并开始监听，失败时回滚已创建的资源
    * @returns {Promise<void>} 无返回值
    */
   async onStart() {
-    const wss = new WebSocket.Server({
-      host: this.config.host,
-      port: this.config.port
-    });
-    this.#wss = wss;
-    await this._listen(wss);
-    wss.on('error', (err) => this._emitError(err));
-    wss.on('connection', (ws, req) => this._handleConnection(ws, req));
+    try {
+      const wss = new WebSocket.Server({
+        host: this.config.host,
+        port: this.config.port
+      });
+      this.#wss = wss;
+      wss.on('error', (err) => this._emitError(err));
+      wss.on('connection', (ws, req) => this._handleConnection(ws, req));
+      await this._listen(wss);
+    } catch (err) {
+      await this._rollbackStart();
+      throw err;
+    }
+  }
+
+  /**
+   * 启动失败时回滚已创建的资源
+   * @returns {Promise<void>} 无返回值
+   */
+  async _rollbackStart() {
+    try {
+      this._closeAllClients();
+      await this._closeServer();
+    } catch (err) {
+      this._emitError(err);
+    }
   }
 
   /**
@@ -114,13 +133,15 @@ class WebSocketServer extends Mod {
    * @param {Object} ctx 执行上下文
    * @param {Object} options 合并后的选项
    * @returns {Promise<Object>} 操作结果
+   * @throws {Error} action 不受支持时
    */
   async main(params, ctx, options) {
     const action = params.action;
     if (action === 'send') return this._actionSend(params);
     if (action === 'broadcast') return this._actionBroadcast(params);
     if (action === 'close') return this._actionClose(params);
-    return this._actionList();
+    if (action === 'list') return this._actionList();
+    throw new Error(`${this._label()} unsupported action: ${action}`);
   }
 
   /**
@@ -282,36 +303,88 @@ class WebSocketServer extends Mod {
       path: getPath(req.url || '/'),
       address: this._remoteAddress(req),
       ws,
-      options: null
+      options: null,
+      queue: Promise.resolve()
     };
     this.#clients.set(client_id, client);
-    ws.on('message', (buf) => this._handleMessage(client_id, buf));
+    ws.on('message', (data, is_binary) => this._handleMessage(client_id, data, is_binary));
     ws.on('close', () => this.#clients.delete(client_id));
     ws.on('error', (err) => this._emitError(err));
   }
 
   /**
-   * 处理入站消息：解码后交给事件管理器，返回非空结果时回发来源连接
+   * 接收消息并排入该连接的串行队列
    * @param {string} client_id 客户端 ID
-   * @param {Object} buf 数据缓冲区
-   * @returns {Promise<void>} 无返回值
+   * @param {Object} data 消息内容，文本帧为 Buffer，二进制帧为 Buffer
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {void}
    */
-  async _handleMessage(client_id, buf) {
+  _handleMessage(client_id, data, is_binary) {
     const client = this.#clients.get(client_id);
     if (!client) return;
-    const params = { client_id, data: this._decodeData(buf) };
-    const ctx = { client_id, path: client.path, ws: client.ws };
+    this._enqueue(client, () => this._processMessage(client, data, is_binary));
+  }
+
+  /**
+   * 把任务追加到连接的串行队列，保证同一连接的消息顺序执行
+   * @param {Object} client 连接信息
+   * @param {Function} task 待执行任务
+   * @returns {void}
+   */
+  _enqueue(client, task) {
+    client.queue = client.queue
+      .then(() => task())
+      .catch((err) => this._emitError(err));
+  }
+
+  /**
+   * 处理入站消息：解码后交给事件管理器，返回非空结果时回发来源连接
+   * @param {Object} client 连接信息
+   * @param {Object} data 消息内容
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Promise<void>} 无返回值
+   */
+  async _processMessage(client, data, is_binary) {
+    const params = this._buildParams(client, data, is_binary);
+    const ctx = this._buildContext(client, is_binary);
     const options = this._clientOptions(client);
     try {
       const result = await this.#events.run(client.path, params, ctx, options);
       const error = ctx.error || options.error;
       if (error) this._emitError(error);
-      if (result !== undefined && result !== null) this.send(client_id, result);
+      if (result !== undefined && result !== null) this.send(client.id, result);
     } catch (err) {
       this._emitError(err);
     }
   }
 
+  /**
+   * 构建事件执行参数
+   * @param {Object} client 连接信息
+   * @param {Object} data 消息内容
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Object} 参数对象
+   */
+  _buildParams(client, data, is_binary) {
+    return { client_id: client.id, data: this._decodeData(data, is_binary) };
+  }
+
+  /**
+   * 构建事件执行上下文
+   * @param {Object} client 连接信息
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Object} 上下文对象
+   */
+  _buildContext(client, is_binary) {
+    return {
+      client_id: client.id,
+      path: client.path,
+      scope: this.config.scope,
+      is_binary,
+      ws: client.ws
+    };
+  }
+
   /**
    * 获取连接级选项（复制一份，避免事件管理器回写）
    * @param {Object} client 连接信息
@@ -333,23 +406,26 @@ class WebSocketServer extends Mod {
 
   // ---------- 数据编解码 ----------
   /**
-   * 编码待发送数据
-   * @param {string|Object} data 待编码数据
-   * @returns {string} 编码后的字符串
+   * 编码待发送数据，Buffer 原样发送（二进制帧），其余按配置序列化
+   * @param {string|Object|Buffer} data 待编码数据
+   * @returns {string|Buffer} 编码后的内容
    */
   _encodeData(data) {
+    if (Buffer.isBuffer(data)) return data;
     if (this.config.json) return JSON.stringify(data);
     if (typeof data === 'string') return data;
     return String(data);
   }
 
   /**
-   * 解码收到的数据
-   * @param {Object} buf 数据缓冲区
-   * @returns {string|Object} 解码后的数据，json 模式下解析失败时返回原文
+   * 解码收到的数据，二进制帧保持 Buffer 原样
+   * @param {Object} data 消息内容
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {string|Object|Buffer} 解码后的数据，json 模式下解析失败时返回原文
    */
-  _decodeData(buf) {
-    const text = buf.toString('utf8');
+  _decodeData(data, is_binary) {
+    if (is_binary) return data;
+    const text = data.toString('utf8');
     if (!this.config.json) return text;
     return this._parseJson(text);
   }
@@ -414,7 +490,11 @@ class WebSocketServer extends Mod {
     this.#wss = null;
     if (!wss) return Promise.resolve();
     return new Promise((resolve) => {
-      wss.close(() => resolve());
+      try {
+        wss.close(() => resolve());
+      } catch {
+        resolve();
+      }
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mm_websocket_server",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "最薄的 WebSocket 服务器入站适配器：消息直达 mm_event 事件管理器，不做路由与插件。",
   "keywords": [
     "超级美眉",