mm_websocket_server 1.0.2 → 2.0.1

package/README.md

@@ -1,159 +1,128 @@
 # mm_websocket_server
 
-WebSocket 服务器入站适配器模块。继承 [mm_corejs](https://gitee.com/qiuwenwu91/mm_corejs) 的 `Mod` 基类，基于 `ws` 独立监听模式，提供连接管理、消息处理管道与 JSON-RPC 2.0 消息插件，可脱离完整框架独立运行。
+最薄的 WebSocket 服务器入站适配器。继承 `mm_mod` 的 `Mod`，把 `ws` 的每条消息直接交给 `mm_event` 的事件管理器处理，不做路由表、不做插件、不加载脚本。
 
 - 入口：`index.js`（CommonJS）
-- 导出：`WebSocketServer`（服务器模块）、`MessagePlugin`（JSON-RPC 消息插件）
-- 运行时依赖：`mm_corejs`、`ws`
-- 测试覆盖率：100%（`jest.config.js` 四项阈值）
+- 导出：`WebSocketServer`、`admin`、`websocketServerAdmin`
+- 运行时依赖：`mm_mod`、`mm_event`、`mm_corejs`、`ws`
 
-## 特性
+## 消息路径
 
-- **独立监听**：`WebSocket.Server` 按 `host / port / path` 直接监听，仅处理升级握手，不提供普通 HTTP 服务。
-- **生命周期**：`init`（校验服务器设置）→ `start`（监听）→ `stop`（终止全部连接并关闭服务）→ `dispose`（清空注册表），状态机由 `mm_corejs` 驱动。
-- **消息管道**：入站消息经 `Handle` 的 `before / check / main / render` 阶段处理，管道产出 `result` 时自动回发来源客户端；`getHandle()` 可注册业务钩子（echo、鉴权、改写等）。
-- **连接管理**：`Store` 登记在线客户端，支持 `send / broadcast / closeClient / listClients（条件查询与分页）/ hasClient / setClientOptions`。
-- **JSON-RPC 2.0 插件**：`MessagePlugin` 挂载后接管 RPC 请求，支持请求-响应、通知回推、主动推送与服务器反向调用客户端方法。
-- **选项透传**：连接级 `options`（user_id / device_id / agent_id 等）随每条入站消息透传给管道钩子与 RPC 处理函数，适配多用户 / 多设备 / 多智能体场景。
-
-## 安装
-
-```bash
-npm install mm_websocket_server
 ```
+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 时，后一条消息会等前一条处理完再开始，避免响应乱序。
 
-- Node.js >= 22.5.0
-- 模块规范：CommonJS
+二进制帧保持 `Buffer` 原样传给事件（`ctx.is_binary` 为 `true`），不参与 `json` 解析；事件返回 `Buffer` 时也按二进制帧回发。文本帧走 `json` / UTF-8 文本逻辑。
 
 ## 快速开始
 
 ```js
 'use strict';
 
-const { WebSocketServer, MessagePlugin } = require('mm_websocket_server');
+const { WebSocketServer } = require('mm_websocket_server');
 
-/** 最小 Server 容器：满足 Base 契约即可（见 example/demo.js 完整实现） */
-const server = {
-  services: new Map(),
-  getService(name) { return this.services.get(name); },
-  hasService(name) { return this.services.has(name); },
-  setService(name, instance) { this.services.set(name, instance); return this; },
-  getManager() { return undefined; },
-  hasManager() { return false; }
-};
+const websocket = new WebSocketServer({ name: 'websocket', host: '127.0.0.1', port: 8090 });
+const events = websocket.getEventManager();
 
-const wss = new WebSocketServer({
-  name: 'websocket',
-  host: '127.0.0.1',
-  port: 9200,
-  path: '/',
-  json: true
-}, server);
-
-// 业务钩子：非 RPC 消息直接回发 echo
-wss.getHandle().on('main', (ctx, params) => ({ type: 'echo', data: params.data }), 200, 'echo');
-
-// JSON-RPC 插件：登记方法
-const rpc = new MessagePlugin();
-wss.use(rpc);
-rpc.addMethod('sum', (params) => params.reduce((a, b) => a + b, 0));
-
-// 事件
-wss.on('connection', (client) => wss.setClientOptions(client.id, { user_id: 'u1' }));
-wss.on('message', (client_id, data) => console.log(client_id, data));
-wss.on('close', (client_id) => console.log('断开', client_id));
-wss.on('error', (err) => console.error(err.message));
-
-await wss.init();
-await wss.start();
-
-// 主动操作
-await wss.run({}, { action: 'list' });
-await wss.run({}, { action: 'broadcast', data: { type: 'notice', text: 'hello all' } });
-
-await wss.stop();
-await wss.dispose();
-```
+events.add({ name: 'echo', target: '/echo', end: true }).main = async (params, ctx) => ({
+  client_id: ctx.client_id,
+  data: params.data
+});
+
+await websocket.init();
+await websocket.start();
 
-## 服务器配置（config）
+console.log(websocket.getAddress());
+```
 
-顶层 `config` 字段即服务器设置，`init` 阶段统一校验。
+## 服务器配置
 
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `name` | string | `'websocket'` | 模块名称（必填） |
+| `name` | string | `'os'` | 模块名称（必填） |
+| `title` | string | `'WebSocket服务器模块'` | 模块标题 |
+| `description` | string | — | 模块描述 |
+| `version` | string | `'2.0.0'` | 版本号 |
 | `host` | string | `'0.0.0.0'` | 监听地址 |
-| `port` | integer | `8090` | 监听端口（1-65535） |
-| `path` | string | `'/'` | 升级路径，须以 `/` 开头 |
-| `json` | boolean | `true` | 为 `true` 时入站尝试 JSON 解析（失败回落原文），出站对象自动序列化 |
+| `port` | number | `8090` | 监听端口 |
+| `json` | boolean | `true` | 入站尝试 JSON 解析，出站对象自动序列化 |
+| `scope` | string | `'websocket'` | 事件管理器作用域，多实例可用不同 scope 隔离事件 |
+| `params` | object | `{ action }` | `main` 的参数约定 |
 
-## API
+不限制升级路径，任何路径都可连接，路径即事件 `target`。
 
-### WebSocketServer
+## API
 
 | 成员 | 说明 |
 | --- | --- |
-| `run(ctx, params)` | 主动操作入口，`params.action` 派发：`send`（需 `client_id` / `data`）、`broadcast`（需 `data`）、`close`（需 `client_id`）、`list`（可选 `query` 条件查询） |
-| `send(client_id, data)` | 向指定客户端发送数据，返回是否成功（连接非 OPEN 视为失败） |
-| `broadcast(data)` | 向全部在线客户端广播，返回送达数 |
-| `closeClient(client_id)` | 关闭指定连接，返回是否发起（登记移除与 `close` 事件由关闭回调完成） |
-| `listClients(query)` | 在线客户端列表（`{ id, address }`），支持 Store 条件 / 分页 / keyword |
-| `hasClient(client_id)` | 是否在线 |
-| `setClientOptions(client_id, options)` | 绑定连接级选项（`null` 清空），随入站消息透传 |
-| `use(plugin)` | 挂载插件（需实现 `bind(server)`） |
-| `getHandle()` | 消息管道，注册 `before / check / main / render` 等钩子；钩子产出 `result` 自动回发 |
+| `init()` / `start()` / `stop()` / `dispose()` | `Mod` 生命周期模板方法 |
+| `onInit()` / `onStart()` / `onStop()` / `onDispose()` | 生命周期钩子，子类可覆盖 |
+| `getEventManager()` | 获取 `mm_event` 上 `scope` 作用域的事件管理器（默认 `websocket`，其他实例共享同一作用域），用于注册事件 |
+| `setEventManager(manager)` | 注入外部事件管理器，需提供 `run()` |
 | `getAddress()` | 实际监听地址，未启动为 `null` |
+| `run(params, ctx, options)` | 主动操作入口，`params.action` 派发 `send` / `broadcast` / `close` / `list` |
+| `send(client_id, data)` | 向指定连接发送数据，返回是否成功 |
+| `broadcast(data)` | 向全部在线连接广播，返回送达数 |
+| `closeClient(client_id)` | 关闭指定连接，返回是否发起 |
+| `listClients()` | 在线连接列表 `{ id, path, address }` |
+| `hasClient(client_id)` | 是否在线 |
+| `setClientOptions(client_id, options)` | 绑定连接级选项，随入站消息作为 `options` 透传（`null` 清空） |
 
-### 事件
+## 请求上下文（ctx）
 
-| 事件 | 参数 | 触发时机 |
-| --- | --- | --- |
-| `connection` | `(client)` | 新连接接入，`client` 为 `{ id, name, address, ws }` |
-| `message` | `(client_id, data)` | 入站消息经管道内置 `emit_message` 钩子分发 |
-| `close` | `(client_id)` | 连接关闭 |
-| `error` | `(err)` | 底层服务器 / 连接 / 钩子错误 |
+| 字段 | 说明 |
+| --- | --- |
+| `client_id` | 连接编号，形如 `ws_1` |
+| `path` | 握手请求路径，`?` 之后已截断 |
+| `scope` | 当前实例的事件管理器作用域 |
+| `is_binary` | 是否为二进制帧 |
+| `ws` | 原生 ws 连接，事件可直接写出 |
 
-### 消息管道
+## 事件处理函数
 
-每条入站消息以 `{ client_id, data }` 为 `params`、连接级 `options` 为第三参进入管道：
+签名固定为 `(params, ctx, options)`：
 
-```
-before → check → main（业务钩子按 sort 依次执行）→ render
+```js
+events.add({ name: 'echo', target: '/echo', end: true }).main = async (params, ctx, options) => {
+  return { data: params.data };
+};
 ```
 
-任一阶段产出非 `undefined` 的 `result` 即回发来源客户端；`check` / `before` 产出时短路后续阶段。内置 `emit_message` 钩子（sort 1000）只分发 `message` 事件、不产出结果。
+返回非 `undefined` / `null` 的结果会按 `json` 配置编码后回发来源连接；返回 `undefined` 则不回发。事件也可直接用 `ctx.ws` 写出。
 
-## MessagePlugin（JSON-RPC 2.0）
-
-挂载后接管 `jsonrpc` 形态消息（非 RPC 消息透传给业务钩子）：
+## 主动操作
 
 ```js
-const rpc = new MessagePlugin();
-wss.use(rpc);
-rpc.addMethod('echo', (params, extra, options) => params); // extra.client_id，options 为连接级选项
+await websocket.run({ action: 'send', client_id: 'ws_1', data: 'hi' });
+await websocket.run({ action: 'broadcast', data: { type: 'notice' } });
+await websocket.run({ action: 'close', client_id: 'ws_1' });
+await websocket.run({ action: 'list' });
 ```
 
-| 成员 | 说明 |
-| --- | --- |
-| `addMethod(name, handler)` / `delMethod(name)` / `listMethods(query)` | 方法表管理，处理函数签名 `(params, extra, options)` |
-| `push(client_id, data)` | 任意时刻向客户端回推数据（如异步任务完成后） |
-| `call(client_id, method, params, options)` | 反向调用客户端方法并等待其反馈，`options.timeout_ms` 缺省 30000 |
-| `bind(server)` / `isBound()` | 挂载与状态查询 |
+`action` 仅支持上述四种，其他值直接抛 `unsupported action` 错误。
+
+## 生命周期
+
+`onStart` 先挂 `error` / `connection` 监听再等待 `listening`，创建并监听 `WebSocket.Server`；`onStop` 断开全部连接并关闭服务器。启动失败（如端口被占用）时会先回滚已创建的服务器与连接表再抛错，模块进入 `error` 状态，可 `dispose()` 释放。
 
-协议行为：请求（含 `id`）返回响应对象；通知（无 `id`）处理函数有返回值时回推服务器发起的通知 `{ jsonrpc, method, params }`；客户端把响应形态消息（含 `result` / `error`、无 `method`）发回即结算对应的反向调用。
+事件管理器取自 `mm_event` 上 `scope` 指定的作用域（默认 `websocket`），由全局 `Admin` 共享，停止时不清理；多个实例需要不同作用域时，配置不同的 `scope` 即可。
 
 ## 示例
 
 ```bash
-npm run demo   # 启动 WebSocket 演示服务器（127.0.0.1:8090），见 example/demo.js
+npm run demo   # 启动演示服务器（127.0.0.1:8090），见 example/demo.js
 ```
 
 ## 测试
 
 ```bash
-npm test       # jest --coverage，四项覆盖率阈值均为 100%
+npm test       # node --test
 ```
 
 ## 许可证

package/example/demo.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { WebSocketServer } = require('..');
+
+/** 演示监听端口 */
+const DEMO_PORT = 8090;
+
+/**
+ * 注册演示事件：握手路径即事件 target
+ * @param {Object} events 事件管理器
+ * @returns {void}
+ */
+function bindEvents(events) {
+  events.add({ name: 'echo', target: '/echo', end: true }).main = async (params, ctx) => ({
+    type: 'echo',
+    client_id: ctx.client_id,
+    data: params.data
+  });
+
+  events.add({ name: 'time', target: '/time', end: true }).main = async () => ({
+    time: new Date().toISOString()
+  });
+
+  events.add({ name: 'error', target: '/error', end: true }).main = async () => {
+    throw new Error('boom');
+  };
+}
+
+/**
+ * 演示入口：启动服务器并打印监听地址
+ * @returns {Promise<void>} 无返回值
+ */
+async function main() {
+  const websocket = new WebSocketServer({ name: 'demo', host: '127.0.0.1', port: DEMO_PORT });
+
+  bindEvents(websocket.getEventManager());
+  websocket.on('error', (err) => console.error(`[demo] 错误: ${err.message}`));
+
+  await websocket.init();
+  await websocket.start();
+
+  const address = websocket.getAddress();
+  console.log(`ws://127.0.0.1:${address.port}/echo`);
+  console.log(`ws://127.0.0.1:${address.port}/time`);
+  console.log('连接后发送任意内容，结果由事件返回并自动回发');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/index.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const WebSocketServer = require('./lib/websocket');
-const MessagePlugin = require('./lib/message');
 const Admin = require('mm_corejs').Admin;
 
 let admin = new Admin();
@@ -9,11 +8,10 @@ admin.setClass(WebSocketServer);
 
 module.exports = {
   WebSocketServer,
-  MessagePlugin,
   admin,
   /**
    * 获取指定作用域的 WebSocket 服务器
-   * @param {string} [scope='sys'] 作用域名称
+   * @param {string} [scope='os'] 作用域名称
    * @param {object} [config] 配置参数
    * @returns {WebSocketServer} WebSocket 服务器实例
    */
@@ -21,6 +19,6 @@ module.exports = {
     if (!scope) {
       scope = 'os';
     }
-    return admin.get(scope, { name: scope, ...config });
+    return admin.get(scope, config);
   }
 };

package/lib/websocket.js

@@ -1,47 +1,33 @@
 'use strict';
 
 const WebSocket = require('ws');
-const { Mod, Store } = require('mm_corejs');
-const { Handle } = require('mm_handle');
+const { Mod } = require('mm_mod');
+const { eventAdmin } = require('mm_event');
 
 /**
- * 服务器设置校验 schema（校验对象为顶层 config）
+ * 获取请求路径（在 ? 处截断，不解析查询串）
+ * @param {string} url 原始请求地址
+ * @returns {string} 请求路径
  */
-const SERVER_SCHEMA = {
-  type: 'object',
-  properties: {
-    host: { type: 'string', min_length: 1 },
-    port: { type: 'integer', minimum: 1, maximum: 65535 },
-    path: { type: 'string', pattern: '^/' },
-    json: { type: 'boolean' }
-  }
-};
+function getPath(url) {
+  const index = url.indexOf('?');
+  return index === -1 ? url : url.slice(0, index);
+}
 
 /**
- * WebSocketServer —— 纯 WebSocket 服务器（入站适配器模块）。
- *
- * 继承 mm_corejs 的 Mod：生命周期由 Lifecycle 模板方法驱动，
- * 调用参数校验由 config.params 声明式定义；
- * 服务器设置（host / port / path / json）为顶层 config 字段，
- * 在 onInit 阶段按 SERVER_SCHEMA 统一校验。
+ * WebSocketServer —— 最薄的 WebSocket 传输层（入站适配器模块）。
  *
- * 采用 ws 独立监听模式（standalone）：直接按 host / port 监听，
- * 仅处理 WebSocket 升级握手，不提供普通 HTTP 服务。
- *
- * 职责：
- *   1. 监听：onStart 创建 WebSocket.Server 并按 host / port / path 独立监听；
- *   2. 连接管理：#clients 使用 Store 登记在线客户端（主键 id，支持条件查询与分页）；
- *   3. 消息管道：收到的消息经 Handle 的 before/check/main/render 阶段处理，
- *      管道产出 result 时自动回发来源客户端；getHandle() 可注册自定义钩子；
- *   4. 事件分发：connection / message / close / error 经 EventEmitter 向外广播；
- *   5. 主动操作：run(ctx, params) 按 params.action 派发 send / broadcast / close / list。
+ * 只做三件事：
+ *   1. 生命周期：由 Mod 的 init / start / stop 驱动 WebSocket.Server；
+ *   2. 消息转交：以握手请求路径为 target，直接调用
+ *      EventManager.run(path, params, ctx, options)，不做路由、不做插件；
+ *   3. 结果回发：事件返回非空结果时回发来源客户端，事件也可用 ctx.ws 自行写出。
  *
  * 用法：
- *   const wss = new WebSocketServer({ name: 'websocket', host: '127.0.0.1', port: 8090 }, server);
- *   wss.getHandle().on('main', (ctx, params) => ({ type: 'echo', data: params.data }), 100, 'echo');
+ *   const wss = new WebSocketServer({ name: 'websocket', port: 8090 });
+ *   wss.getEventManager().add({ name: 'echo', target: '*' }).main = async (params) => params.data;
  *   await wss.init();
  *   await wss.start();
- *   await wss.run({}, { action: 'list' });
  */
 class WebSocketServer extends Mod {
   /**
@@ -50,82 +36,94 @@ class WebSocketServer extends Mod {
   static config = {
     name: 'os',
     title: 'WebSocket服务器模块',
-    description: 'WebSocket 服务器，管理连接并分发消息',
-    version: '1.0.0',
+    description: 'WebSocket 传输层：消息直达事件管理器，不做路由与插件',
+    version: '2.0.0',
     host: '0.0.0.0',
     port: 8090,
-    path: '/',
     json: true,
-    options: {},
+    scope: 'websocket',
     params: {
       type: 'object',
       required: ['action'],
       properties: {
         action: { type: 'string', enum: ['send', 'broadcast', 'close', 'list'] },
         client_id: { type: 'string', min_length: 1 },
-        data: {},
-        query: { type: 'object' }
+        data: {}
       }
     }
   };
 
   /**
-   * ws 协议层实例（独立监听模式，内部自管 HTTP 升级）
+   * ws 服务器实例
    */
   #wss = null;
 
   /**
-   * 连接注册表：Store 存储，主键 id、名称字段 name
+   * 事件管理器（取自 mm_event 的 websocket 作用域，与其他实例共享）
    */
-  #clients = new Store({ key: 'id', name: 'name' });
+  #events = null;
 
   /**
-   * 消息处理管道（before/check/main/render/error/success/after）
-   * 每个实例独立 Handle，避免多实例共享管道导致钩子泄漏
+   * 在线连接表：client_id -> 连接信息
    */
-  #handle = new Handle();
+  #clients = new Map();
 
   /**
    * 客户端编号自增计数器
    */
   #counter = 0;
 
-  // ---------- 生命周期钩子 ----------
   /**
-   * 初始化钩子：校验服务器设置并装配消息管道
+   * 构造函数
+   * @param {Object} config 模块配置
+   * @param {Object} server 框架实例
    */
-  async onInit() {
-    await this._validateConfig();
-    this._initHandle();
+  constructor(config, server) {
+    super(config, server);
+    this.#events = eventAdmin(this.config.scope);
   }
 
+  // ---------- 生命周期钩子 ----------
   /**
-   * 启动钩子：创建 ws 独立服务器并开始监听
+   * 启动钩子：创建 ws 服务器并开始监听，失败时回滚已创建的资源
+   * @returns {Promise<void>} 无返回值
    */
   async onStart() {
-    const host = this.config.host;
-    const port = this.config.port;
-    const path = this.config.path;
-    const wss = new WebSocket.Server({ host, port, path });
-    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 onStop() {
-    this._closeAllClients();
-    await this._closeServer();
+  async _rollbackStart() {
+    try {
+      this._closeAllClients();
+      await this._closeServer();
+    } catch (err) {
+      this._emitError(err);
+    }
   }
 
   /**
-   * 释放钩子：清空连接注册表
+   * 停止钩子：断开全部连接并关闭服务器（事件管理器与其他实例共享，不清理）
+   * @returns {Promise<void>} 无返回值
    */
-  async onDispose() {
-    this.#clients.clear();
+  async onStop() {
+    this._closeAllClients();
+    await this._closeServer();
   }
 
   // ---------- 执行入口 ----------
@@ -135,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(params);
+    if (action === 'list') return this._actionList();
+    throw new Error(`${this._label()} unsupported action: ${action}`);
   }
 
   /**
@@ -158,7 +158,7 @@ class WebSocketServer extends Mod {
   /**
    * 执行广播操作
    * @param {Object} params 调用参数，含 data
-   * @returns {Object} 操作结果，count 为送达客户端数
+   * @returns {Object} 操作结果，count 为送达连接数
    */
   _actionBroadcast(params) {
     const count = this.broadcast(params.data);
@@ -178,177 +178,226 @@ class WebSocketServer extends Mod {
 
   /**
    * 执行列出连接操作
-   * @param {Object} params 调用参数，可含 query 查询条件（Store 条件/分页）
-   * @returns {Object} 操作结果，clients 为在线客户端列表
+   * @returns {Object} 操作结果，clients 为在线连接列表
+   */
+  _actionList() {
+    return { action: 'list', clients: this.listClients() };
+  }
+
+  // ---------- 事件管理器 ----------
+  /**
+   * 获取事件管理器，用于注册事件
+   * @returns {Object} 事件管理器实例
+   */
+  getEventManager() {
+    return this.#events;
+  }
+
+  /**
+   * 注入外部事件管理器
+   * @param {Object} manager 事件管理器实例
+   * @returns {WebSocketServer} 当前实例
+   * @throws {TypeError} manager 不具备 run 方法时
+   */
+  setEventManager(manager) {
+    if (!manager || typeof manager.run !== 'function') {
+      throw new TypeError(`${this._label()} manager must provide run()`);
+    }
+    this.#events = manager;
+    return this;
+  }
+
+  /**
+   * 获取实际监听地址
+   * @returns {Object|null} 监听地址信息，未启动时为 null
    */
-  _actionList(params) {
-    return { action: 'list', clients: this.listClients(params.query) };
+  getAddress() {
+    const wss = this.#wss;
+    return wss ? wss.address() : null;
   }
 
   // ---------- 公开操作 ----------
   /**
-   * 向指定客户端发送数据
+   * 向指定连接发送数据
    * @param {string} client_id 客户端 ID
    * @param {string|Object} data 待发送数据
    * @returns {boolean} 是否发送成功
    */
   send(client_id, data) {
-    const client = this.#clients.getById(client_id);
+    const client = this.#clients.get(client_id);
     if (!client) return false;
-    const payload = this._encodeData(data);
-    return this._sendToClient(client, payload);
+    return this._sendToClient(client, this._encodeData(data));
   }
 
   /**
-   * 向全部在线客户端广播数据
+   * 向全部在线连接广播数据
    * @param {string|Object} data 待广播数据
-   * @returns {number} 送达的客户端数量
+   * @returns {number} 送达的连接数量
    */
   broadcast(data) {
     const payload = this._encodeData(data);
     let count = 0;
-    for (const client of this.#clients.list()) {
+    for (const client of this.#clients.values()) {
       if (this._sendToClient(client, payload)) count += 1;
     }
     return count;
   }
 
   /**
-   * 关闭指定客户端连接（登记移除与 close 事件由连接关闭回调完成）
+   * 关闭指定连接（连接表由关闭回调清理）
    * @param {string} client_id 客户端 ID
    * @returns {boolean} 是否发起关闭
    */
   closeClient(client_id) {
-    const client = this.#clients.getById(client_id);
+    const client = this.#clients.get(client_id);
     if (!client) return false;
     client.ws.close();
     return true;
   }
 
   /**
-   * 列出在线客户端（支持 Store 条件查询与分页）
-   * @param {Object} query 查询条件，可含 page_now / page_size / keyword
-   * @returns {Array<Object>} 客户端信息列表，含 id 与 address
+   * 列出在线连接
+   * @returns {Array<Object>} 连接信息列表，含 id、path 与 address
    */
-  listClients(query) {
-    return this.#clients.list(query).map((client) => ({ id: client.id, address: client.address }));
+  listClients() {
+    const list = [];
+    for (const client of this.#clients.values()) {
+      list.push({ id: client.id, path: client.path, address: client.address });
+    }
+    return list;
   }
 
   /**
-   * 判断客户端是否在线
+   * 判断连接是否在线
    * @param {string} client_id 客户端 ID
    * @returns {boolean} 是否在线
    */
   hasClient(client_id) {
-    return !!this.#clients.getById(client_id);
+    return this.#clients.has(client_id);
   }
 
   /**
-   * 绑定连接级选项（如 user_id / device_id / agent_id），入站消息将作为管道 options 透传给钩子与 RPC 处理函数
+   * 绑定连接级选项，入站消息将作为 options 透传给事件
    * @param {string} client_id 客户端 ID
    * @param {Object|null} options 选项对象，null 时清空
-   * @returns {boolean} 是否设置成功（客户端不在线时失败）
+   * @returns {boolean} 是否设置成功（连接不在线时失败）
    */
   setClientOptions(client_id, options) {
-    const client = this.#clients.getById(client_id);
+    const client = this.#clients.get(client_id);
     if (!client) return false;
     client.options = options || null;
     return true;
   }
 
+  // ---------- 连接处理 ----------
   /**
-   * 读取连接级选项，未绑定时返回空对象
-   * @param {string} client_id 客户端 ID
-   * @returns {Object} 连接级选项
+   * 登记新的连接并绑定回调
+   * @param {Object} ws ws 连接实例
+   * @param {Object} req 握手请求对象
    */
-  _clientOptions(client_id) {
-    const client = this.#clients.getById(client_id);
-    if (!client || !client.options) return {};
-    return client.options;
+  _handleConnection(ws, req) {
+    this.#counter += 1;
+    const client_id = `ws_${this.#counter}`;
+    const client = {
+      id: client_id,
+      path: getPath(req.url || '/'),
+      address: this._remoteAddress(req),
+      ws,
+      options: null,
+      queue: Promise.resolve()
+    };
+    this.#clients.set(client_id, client);
+    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));
   }
 
   /**
-   * 挂载插件：调用 plugin.bind(this)，由插件自行向管道注册钩子；
-   * 如 MessagePlugin 挂载后接管 JSON-RPC 请求
-   * @param {Object} plugin 具备 bind(server) 方法的插件实例
-   * @returns {WebsocketServer} 当前实例
-   * @throws {TypeError} plugin 不具备 bind 方法时
+   * 接收消息并排入该连接的串行队列
+   * @param {string} client_id 客户端 ID
+   * @param {Object} data 消息内容，文本帧为 Buffer，二进制帧为 Buffer
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {void}
    */
-  use(plugin) {
-    if (!plugin || typeof plugin.bind !== 'function') {
-      throw new TypeError(`${this._label()} plugin must provide bind()`);
-    }
-    plugin.bind(this);
-    return this;
+  _handleMessage(client_id, data, is_binary) {
+    const client = this.#clients.get(client_id);
+    if (!client) return;
+    this._enqueue(client, () => this._processMessage(client, data, is_binary));
   }
 
   /**
-   * 获取消息处理管道，供外部注册 before/check/main/render 等钩子；
-   * 钩子产出 result 时自动回发来源客户端
-   * @returns {Handle} 消息管道实例
+   * 把任务追加到连接的串行队列，保证同一连接的消息顺序执行
+   * @param {Object} client 连接信息
+   * @param {Function} task 待执行任务
+   * @returns {void}
    */
-  getHandle() {
-    return this.#handle;
+  _enqueue(client, task) {
+    client.queue = client.queue
+      .then(() => task())
+      .catch((err) => this._emitError(err));
   }
 
   /**
-   * 获取实际监听地址
-   * @returns {Object|null} 监听地址信息，未启动时为 null
+   * 处理入站消息：解码后交给事件管理器，返回非空结果时回发来源连接
+   * @param {Object} client 连接信息
+   * @param {Object} data 消息内容
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Promise<void>} 无返回值
    */
-  getAddress() {
-    const wss = this.#wss;
-    return wss ? wss.address() : null;
+  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);
+    } catch (err) {
+      this._emitError(err);
+    }
   }
 
-  // ---------- 连接处理 ----------
   /**
-   * 登记新的 WebSocket 连接并绑定事件
-   * @param {Object} ws ws 连接实例
-   * @param {Object} req 升级请求对象
+   * 构建事件执行参数
+   * @param {Object} client 连接信息
+   * @param {Object} data 消息内容
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Object} 参数对象
    */
-  _handleConnection(ws, req) {
-    this.#counter += 1;
-    const client_id = `ws_${this.#counter}`;
-    const client = {
-      id: client_id,
-      name: client_id,
-      address: this._remoteAddress(req),
-      ws
-    };
-    this.#clients.add(client);
-    ws.on('message', (buf) => this._handleMessage(client_id, buf));
-    ws.on('close', () => this._handleClose(client_id));
-    ws.on('error', (err) => this._emitError(err));
-    this._safeEmit('connection', client);
+  _buildParams(client, data, is_binary) {
+    return { client_id: client.id, data: this._decodeData(data, is_binary) };
   }
 
   /**
-   * 处理收到的消息：解码后进入消息管道，产出 result 时自动回发
-   * @param {string} client_id 客户端 ID
-   * @param {Object} buf 数据缓冲区
-   * @returns {Promise<void>} 无返回值
+   * 构建事件执行上下文
+   * @param {Object} client 连接信息
+   * @param {boolean} is_binary 是否为二进制帧
+   * @returns {Object} 上下文对象
    */
-  async _handleMessage(client_id, buf) {
-    const decoded = this._decodeData(buf);
-    const params = { client_id, data: decoded };
-    const ctx = { client_id };
-    const done = await this.#handle.run(ctx, params, this._clientOptions(client_id));
-    if (done.error) this._emitError(done.error);
-    if (done.result !== undefined) this.send(client_id, done.result);
+  _buildContext(client, is_binary) {
+    return {
+      client_id: client.id,
+      path: client.path,
+      scope: this.config.scope,
+      is_binary,
+      ws: client.ws
+    };
   }
 
   /**
-   * 处理连接关闭
-   * @param {string} client_id 客户端 ID
+   * 获取连接级选项（复制一份，避免事件管理器回写）
+   * @param {Object} client 连接信息
+   * @returns {Object} 选项对象
    */
-  _handleClose(client_id) {
-    const existed = this.#clients.delById(client_id);
-    if (existed) this._safeEmit('close', client_id);
+  _clientOptions(client) {
+    if (!client.options) return {};
+    return { ...client.options };
   }
 
   /**
    * 获取远端地址字符串
-   * @param {Object} req 升级请求对象
+   * @param {Object} req 握手请求对象
    * @returns {string} 形如 ip:port 的地址
    */
   _remoteAddress(req) {
@@ -357,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);
   }
@@ -393,8 +445,8 @@ class WebSocketServer extends Mod {
 
   // ---------- 发送与清理 ----------
   /**
-   * 向单个客户端发送已编码数据
-   * @param {Object} client 客户端信息
+   * 向单个连接发送已编码数据
+   * @param {Object} client 连接信息
    * @param {string} payload 已编码数据
    * @returns {boolean} 是否发送成功
    */
@@ -405,10 +457,10 @@ class WebSocketServer extends Mod {
   }
 
   /**
-   * 关闭全部客户端连接并清空注册表
+   * 断开全部连接并清空连接表
    */
   _closeAllClients() {
-    for (const client of this.#clients.list()) {
+    for (const client of this.#clients.values()) {
       client.ws.terminate();
     }
     this.#clients.clear();
@@ -430,7 +482,7 @@ class WebSocketServer extends Mod {
   }
 
   /**
-   * 关闭 ws 服务器（含内部 HTTP 升级服务与残留连接）
+   * 关闭 ws 服务器（连接已在之前全部终止）
    * @returns {Promise<void>} 无返回值
    */
   _closeServer() {
@@ -438,35 +490,15 @@ class WebSocketServer extends Mod {
     this.#wss = null;
     if (!wss) return Promise.resolve();
     return new Promise((resolve) => {
-      const http_server = wss.httpServer;
-      if (http_server && typeof http_server.closeAllConnections === 'function') {
-        http_server.closeAllConnections();
+      try {
+        wss.close(() => resolve());
+      } catch {
+        resolve();
       }
-      wss.close(resolve);
     });
   }
 
   // ---------- 校验辅助 ----------
-  /**
-   * 装配消息管道：内置 main 钩子负责分发 message 事件（sort 置后，
-   * 不返回值，业务钩子产出的 result 由 _handleMessage 统一回发）
-   */
-  _initHandle() {
-    this.#handle.on('main', (params, ctx) => {
-      this._safeEmit('message', params.client_id, params.data);
-    }, 1000, 'emit_message');
-  }
-
-  /**
-   * 校验顶层 config 中的服务器设置
-   * @returns {Promise<void>} 无返回值
-   * @throws {Error} 校验不通过时
-   */
-  async _validateConfig() {
-    const tip = await this._validate(this.config, SERVER_SCHEMA);
-    if (tip) throw new Error(`${this._label()} invalid config: ${tip}`);
-  }
-
   /**
    * 断言调用参数含 client_id
    * @param {Object} params 调用参数

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mm_websocket_server",
-  "version": "1.0.2",
-  "description": "WebSocket 服务器入站适配器模块，继承 mm_corejs 的 Mod 基类，支持独立运行。",
+  "version": "2.0.1",
+  "description": "最薄的 WebSocket 服务器入站适配器：消息直达 mm_event 事件管理器，不做路由与插件。",
   "keywords": [
     "超级美眉",
     "入站适配器",
@@ -21,7 +21,8 @@
   "main": "index.js",
   "files": [
     "index.js",
-    "lib"
+    "lib",
+    "example"
   ],
   "engines": {
     "node": ">=22.5.0"
@@ -37,13 +38,12 @@
   "scripts": {
     "start": "node example/demo.js",
     "demo": "node example/demo.js",
-    "test": "jest --coverage"
+    "test": "node --test \"test/*.test.js\""
   },
   "dependencies": {
     "mm_corejs": "^1.1.4",
+    "mm_event": "^2.2.2",
+    "mm_mod": "^1.0.1",
     "ws": "^8.22.0"
-  },
-  "devDependencies": {
-    "jest": "^30.5.2"
   }
 }

package/lib/message.js

@@ -1,150 +0,0 @@
-'use strict';
-
-const { JsonRpc } = require('mm_corejs');
-
-/**
- * MessagePlugin —— JSON-RPC 2.0 消息插件（mm_websocket_server 的可选业务组件）。
- *
- * 职责：
- *   1. 方法表：内部持有 JsonRpc 核心，addMethod / delMethod / listMethods 登记可调用方法；
- *   2. 管道挂载：bind(websocket) 后向消息管道注册 main 钩子 "json_rpc"（sort 100，
- *      先于内置 emit_message 执行），命中 JSON-RPC 请求时以响应对象作为管道 result，
- *      由 WebSocketServer 自动回发来源客户端；
- *   3. 通知回推：通知（无 id）处理函数返回非 undefined 结果时，产出服务器发起的
- *      通知对象 { jsonrpc, method, params: result } 回推来源客户端；无结果或出错时
- *      不产出；非 JSON-RPC 消息（解析失败、缺 jsonrpc 字段）透传，控制权交还管道；
- *   4. 主动推送：push(client_id, data) 委托 WebSocketServer.send，处理函数或服务器代码
- *      可在任意时刻（如异步任务完成后）向指定客户端回推结果；
- *   5. 反向调用：call(client_id, method, params, options) 向客户端发起 JSON-RPC 请求
- *      并等待其反馈；入站消息为响应形态（含 result/error、无 method）时被优先识别
- *      并结算待响应调用，实现服务器实时调用客户端方法；
- *   6. 编码适配：json 模式产出对象（由 send 序列化），文本模式字符串原样、其余 JSON 序列化。
- *
- * 用法：
- *   const ws = new WebSocketServer({ name: 'websocket', port: 9200, json: true }, server);
- *   const rpc = new MessagePlugin();
- *   ws.use(rpc);
- *   rpc.addMethod('echo', (params) => params);
- *   await ws.init();
- *   await ws.start();
- */
-class MessagePlugin {
-  /**
-   * JSON-RPC 协议核心
-   */
-  #rpc = new JsonRpc();
-
-  /**
-   * 已挂载的 WebSocketServer 实例，未挂载时为 null
-   */
-  #server = null;
-
-  /**
-   * 挂载到 WebSocketServer 的消息管道，注册内置 main 钩子
-   * @param {Object} server 具备 getHandle() 的 WebSocketServer 实例
-   * @returns {MessagePlugin} 当前实例
-   * @throws {TypeError} server 不具备 getHandle 方法时
-   */
-  bind(server) {
-    if (!server || typeof server.getHandle !== 'function') {
-      throw new TypeError('[MessagePlugin] server must provide getHandle()');
-    }
-    this.#server = server;
-    server.getHandle().on('main', (params, ctx, options) => {
-      return this._execute(params, ctx, options);
-    }, 100, 'json_rpc');
-    return this;
-  }
-
-  /**
-   * 判断是否已挂载
-   * @returns {boolean} 是否已挂载到 WebSocketServer
-   */
-  isBound() {
-    return this.#server !== null;
-  }
-
-  /**
-   * 登记 RPC 方法
-   * @param {string} name 方法名
-   * @param {Function} handler 处理函数，签名 handler(params, extra, options)，extra 含 client_id，options 为管道请求选项
-   * @returns {MessagePlugin} 当前实例
-   */
-  addMethod(name, handler) {
-    this.#rpc.addMethod(name, handler);
-    return this;
-  }
-
-  /**
-   * 删除 RPC 方法
-   * @param {string} name 方法名
-   * @returns {boolean} 是否删除成功
-   */
-  delMethod(name) {
-    return this.#rpc.delMethod(name);
-  }
-
-  /**
-   * 列出 RPC 方法（支持 Store 条件查询与分页）
-   * @param {Object} [query] 查询条件，缺省时列出全部
-   * @returns {Array<Object>} 方法列表，含 name
-   */
-  listMethods(query) {
-    return this.#rpc.listMethods(query);
-  }
-
-  /**
-   * 主动推送：向指定客户端回推数据（可用于异步任务完成后通知）
-   * @param {string} client_id 目标客户端 ID
-   * @param {string|Object} data 待推送数据，对象时按编码模式序列化
-   * @returns {boolean} 是否发送成功
-   * @throws {Error} 插件尚未挂载到服务器时
-   */
-  push(client_id, data) {
-    if (!this.#server) throw new Error('[MessagePlugin] not bound to a server');
-    const payload = this._format(data);
-    return this.#server.send(client_id, payload);
-  }
-
-  /**
-   * 实时调用客户端方法：发送 JSON-RPC 请求并等待客户端反馈 result
-   * @param {string} client_id 目标客户端 ID
-   * @param {string} method 客户端方法名
-   * @param {*} [params] 调用参数
-   * @param {Object} [options] 选项，含 timeout_ms（缺省 30000，0 为不超时）
-   * @returns {Promise<*>} 客户端反馈的 result；错误响应、送达失败或超时时 reject
-   * @throws {Error} 插件尚未挂载到服务器时
-   */
-  call(client_id, method, params, options = {}) {
-    if (!this.#server) throw new Error('[MessagePlugin] not bound to a server');
-    return this.#rpc.call((request) => this.#server.send(client_id, this._format(request)), method, params, options);
-  }
-
-  /**
-   * 内置 main 钩子逻辑：优先识别客户端反馈，其次执行 RPC 请求并格式化响应
-   * @param {Object} params 消息参数，含 client_id 与 data
-   * @param {Object} ctx 执行上下文
-   * @param {Object} [options] 管道请求选项（连接级，如 user_id / device_id / agent_id），透传给处理函数
-   * @returns {Promise<Object|string|undefined>} 响应对象或 JSON 字符串；反馈、透传与无结果通知时为 undefined
-   */
-  async _execute(params, ctx, options) {
-    if (this.#rpc.acceptResponse(params.data)) return undefined;
-    const extra = { client_id: params.client_id };
-    const response = await this.#rpc.handle(params.data, extra, options);
-    if (response === undefined) return undefined;
-    return this._format(response);
-  }
-
-  /**
-   * 按服务器 json 配置格式化数据
-   * @param {Object|string} data 响应对象或待推送数据
-   * @returns {Object|string} json 模式返回原值，文本模式字符串原样、其余 JSON 序列化
-   */
-  _format(data) {
-    if (this.#server.config.json) return data;
-    if (typeof data === 'string') return data;
-    return JSON.stringify(data);
-  }
-}
-
-module.exports = MessagePlugin;