mm_websocket_server 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Admin
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# mm_websocket_server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+最薄的 WebSocket 服务器入站适配器。继承 `mm_mod` 的 `Mod`，把 `ws` 的每条消息直接交给 `mm_event` 的事件管理器处理，不做路由表、不做插件、不加载脚本。
+
+- 入口：`index.js`（CommonJS）
+- 导出：`WebSocketServer`、`admin`、`websocketServerAdmin`
+- 运行时依赖：`mm_mod`、`mm_event`、`mm_corejs`、`ws`
+
+## 消息路径
+
+```
+WebSocket.Server → connection → ctx = { client_id, path, ws }
+                 → eventManager.run(path, params, ctx, options)
+                 → 结果非空时回发来源连接
+```
+
+事件 `target` 取握手请求路径（第一个 `?` 之前）。`params` 为 `{ client_id, data }`，`data` 在 `json: true` 时尝试 `JSON.parse`（失败回落原文）。
+
+## 快速开始
+
+```js
+'use strict';
+
+const { WebSocketServer } = require('mm_websocket_server');
+
+const websocket = new WebSocketServer({ name: 'websocket', host: '127.0.0.1', port: 8090 });
+const events = websocket.getEventManager();
+
+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();
+
+console.log(websocket.getAddress());
+```
+
+## 服务器配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | `'os'` | 模块名称（必填） |
+| `title` | string | `'WebSocket服务器模块'` | 模块标题 |
+| `description` | string | — | 模块描述 |
+| `version` | string | `'2.0.0'` | 版本号 |
+| `host` | string | `'0.0.0.0'` | 监听地址 |
+| `port` | number | `8090` | 监听端口 |
+| `json` | boolean | `true` | 入站尝试 JSON 解析，出站对象自动序列化 |
+| `params` | object | `{ action }` | `main` 的参数约定 |
+
+不限制升级路径，任何路径都可连接，路径即事件 `target`。
+
+## API
+
+| 成员 | 说明 |
+| --- | --- |
+| `init()` / `start()` / `stop()` / `dispose()` | `Mod` 生命周期模板方法 |
+| `onInit()` / `onStart()` / `onStop()` / `onDispose()` | 生命周期钩子，子类可覆盖 |
+| `getEventManager()` | 获取 `mm_event` 的 `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）
+
+| 字段 | 说明 |
+| --- | --- |
+| `client_id` | 连接编号，形如 `ws_1` |
+| `path` | 握手请求路径，`?` 之后已截断 |
+| `ws` | 原生 ws 连接，事件可直接写出 |
+
+## 事件处理函数
+
+签名固定为 `(params, ctx, options)`：
+
+```js
+events.add({ name: 'echo', target: '/echo', end: true }).main = async (params, ctx, options) => {
+  return { data: params.data };
+};
+```
+
+返回非 `undefined` / `null` 的结果会按 `json` 配置编码后回发来源连接；返回 `undefined` 则不回发。事件也可直接用 `ctx.ws` 写出。
+
+## 主动操作
+
+```js
+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' });
+```
+
+## 生命周期
+
+`onStart` 创建并监听 `WebSocket.Server`，`onStop` 断开全部连接并关闭服务器。事件管理器取自 `mm_event` 的 `websocket` 作用域，由全局 `Admin` 共享，停止时不清理。端口被占用时 `start()` 抛错，模块进入 `error` 状态，可 `dispose()` 释放。
+
+## 示例
+
+```bash
+npm run demo   # 启动演示服务器（127.0.0.1:8090），见 example/demo.js
+```
+
+## 测试
+
+```bash
+npm test       # node --test
+```
+
+## 许可证
+
+ISC

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

@@ -0,0 +1,24 @@
+'use strict';
+
+const WebSocketServer = require('./lib/websocket');
+const Admin = require('mm_corejs').Admin;
+
+let admin = new Admin();
+admin.setClass(WebSocketServer);
+
+module.exports = {
+  WebSocketServer,
+  admin,
+  /**
+   * 获取指定作用域的 WebSocket 服务器
+   * @param {string} [scope='os'] 作用域名称
+   * @param {object} [config] 配置参数
+   * @returns {WebSocketServer} WebSocket 服务器实例
+   */
+  websocketServerAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/websocket.js

@@ -0,0 +1,434 @@
+'use strict';
+
+const WebSocket = require('ws');
+const { Mod } = require('mm_mod');
+const { eventAdmin } = require('mm_event');
+
+/**
+ * 获取请求路径（在 ? 处截断，不解析查询串）
+ * @param {string} url 原始请求地址
+ * @returns {string} 请求路径
+ */
+function getPath(url) {
+  const index = url.indexOf('?');
+  return index === -1 ? url : url.slice(0, index);
+}
+
+/**
+ * WebSocketServer —— 最薄的 WebSocket 传输层（入站适配器模块）。
+ *
+ * 只做三件事：
+ *   1. 生命周期：由 Mod 的 init / start / stop 驱动 WebSocket.Server；
+ *   2. 消息转交：以握手请求路径为 target，直接调用
+ *      EventManager.run(path, params, ctx, options)，不做路由、不做插件；
+ *   3. 结果回发：事件返回非空结果时回发来源客户端，事件也可用 ctx.ws 自行写出。
+ *
+ * 用法：
+ *   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();
+ */
+class WebSocketServer extends Mod {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'os',
+    title: 'WebSocket服务器模块',
+    description: 'WebSocket 传输层：消息直达事件管理器，不做路由与插件',
+    version: '2.0.0',
+    host: '0.0.0.0',
+    port: 8090,
+    json: true,
+    params: {
+      type: 'object',
+      required: ['action'],
+      properties: {
+        action: { type: 'string', enum: ['send', 'broadcast', 'close', 'list'] },
+        client_id: { type: 'string', min_length: 1 },
+        data: {}
+      }
+    }
+  };
+
+  /**
+   * ws 服务器实例
+   */
+  #wss = null;
+
+  /**
+   * 事件管理器（取自 mm_event 的 websocket 作用域，与其他实例共享）
+   */
+  #events = null;
+
+  /**
+   * 在线连接表：client_id -> 连接信息
+   */
+  #clients = new Map();
+
+  /**
+   * 客户端编号自增计数器
+   */
+  #counter = 0;
+
+  /**
+   * 构造函数
+   * @param {Object} config 模块配置
+   * @param {Object} server 框架实例
+   */
+  constructor(config, server) {
+    super(config, server);
+    this.#events = eventAdmin('websocket');
+  }
+
+  // ---------- 生命周期钩子 ----------
+  /**
+   * 启动钩子：创建 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));
+  }
+
+  /**
+   * 停止钩子：断开全部连接并关闭服务器（事件管理器与其他实例共享，不清理）
+   * @returns {Promise<void>} 无返回值
+   */
+  async onStop() {
+    this._closeAllClients();
+    await this._closeServer();
+  }
+
+  // ---------- 执行入口 ----------
+  /**
+   * 模块主逻辑：按 action 派发操作
+   * @param {Object} params 调用参数，含 action 及操作所需字段
+   * @param {Object} ctx 执行上下文
+   * @param {Object} options 合并后的选项
+   * @returns {Promise<Object>} 操作结果
+   */
+  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();
+  }
+
+  /**
+   * 执行发送操作
+   * @param {Object} params 调用参数，含 client_id 与 data
+   * @returns {Object} 操作结果
+   */
+  _actionSend(params) {
+    this._requireClientId(params);
+    const success = this.send(params.client_id, params.data);
+    return { action: 'send', client_id: params.client_id, success };
+  }
+
+  /**
+   * 执行广播操作
+   * @param {Object} params 调用参数，含 data
+   * @returns {Object} 操作结果，count 为送达连接数
+   */
+  _actionBroadcast(params) {
+    const count = this.broadcast(params.data);
+    return { action: 'broadcast', count };
+  }
+
+  /**
+   * 执行关闭连接操作
+   * @param {Object} params 调用参数，含 client_id
+   * @returns {Object} 操作结果
+   */
+  _actionClose(params) {
+    this._requireClientId(params);
+    const success = this.closeClient(params.client_id);
+    return { action: 'close', client_id: params.client_id, success };
+  }
+
+  /**
+   * 执行列出连接操作
+   * @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
+   */
+  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.get(client_id);
+    if (!client) return false;
+    return this._sendToClient(client, this._encodeData(data));
+  }
+
+  /**
+   * 向全部在线连接广播数据
+   * @param {string|Object} data 待广播数据
+   * @returns {number} 送达的连接数量
+   */
+  broadcast(data) {
+    const payload = this._encodeData(data);
+    let count = 0;
+    for (const client of this.#clients.values()) {
+      if (this._sendToClient(client, payload)) count += 1;
+    }
+    return count;
+  }
+
+  /**
+   * 关闭指定连接（连接表由关闭回调清理）
+   * @param {string} client_id 客户端 ID
+   * @returns {boolean} 是否发起关闭
+   */
+  closeClient(client_id) {
+    const client = this.#clients.get(client_id);
+    if (!client) return false;
+    client.ws.close();
+    return true;
+  }
+
+  /**
+   * 列出在线连接
+   * @returns {Array<Object>} 连接信息列表，含 id、path 与 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.has(client_id);
+  }
+
+  /**
+   * 绑定连接级选项，入站消息将作为 options 透传给事件
+   * @param {string} client_id 客户端 ID
+   * @param {Object|null} options 选项对象，null 时清空
+   * @returns {boolean} 是否设置成功（连接不在线时失败）
+   */
+  setClientOptions(client_id, options) {
+    const client = this.#clients.get(client_id);
+    if (!client) return false;
+    client.options = options || null;
+    return true;
+  }
+
+  // ---------- 连接处理 ----------
+  /**
+   * 登记新的连接并绑定回调
+   * @param {Object} ws ws 连接实例
+   * @param {Object} req 握手请求对象
+   */
+  _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
+    };
+    this.#clients.set(client_id, client);
+    ws.on('message', (buf) => this._handleMessage(client_id, buf));
+    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>} 无返回值
+   */
+  async _handleMessage(client_id, buf) {
+    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 };
+    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);
+    }
+  }
+
+  /**
+   * 获取连接级选项（复制一份，避免事件管理器回写）
+   * @param {Object} client 连接信息
+   * @returns {Object} 选项对象
+   */
+  _clientOptions(client) {
+    if (!client.options) return {};
+    return { ...client.options };
+  }
+
+  /**
+   * 获取远端地址字符串
+   * @param {Object} req 握手请求对象
+   * @returns {string} 形如 ip:port 的地址
+   */
+  _remoteAddress(req) {
+    return `${req.socket.remoteAddress}:${req.socket.remotePort}`;
+  }
+
+  // ---------- 数据编解码 ----------
+  /**
+   * 编码待发送数据
+   * @param {string|Object} data 待编码数据
+   * @returns {string} 编码后的字符串
+   */
+  _encodeData(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 模式下解析失败时返回原文
+   */
+  _decodeData(buf) {
+    const text = buf.toString('utf8');
+    if (!this.config.json) return text;
+    return this._parseJson(text);
+  }
+
+  /**
+   * 尝试将文本解析为 JSON
+   * @param {string} text 文本内容
+   * @returns {Object|string} 解析结果，失败时返回原文
+   */
+  _parseJson(text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  // ---------- 发送与清理 ----------
+  /**
+   * 向单个连接发送已编码数据
+   * @param {Object} client 连接信息
+   * @param {string} payload 已编码数据
+   * @returns {boolean} 是否发送成功
+   */
+  _sendToClient(client, payload) {
+    if (client.ws.readyState !== WebSocket.OPEN) return false;
+    client.ws.send(payload);
+    return true;
+  }
+
+  /**
+   * 断开全部连接并清空连接表
+   */
+  _closeAllClients() {
+    for (const client of this.#clients.values()) {
+      client.ws.terminate();
+    }
+    this.#clients.clear();
+  }
+
+  /**
+   * 等待 ws 服务器监听成功
+   * @param {Object} wss WebSocket.Server 实例
+   * @returns {Promise<void>} 无返回值
+   */
+  _listen(wss) {
+    return new Promise((resolve, reject) => {
+      wss.once('error', reject);
+      wss.once('listening', () => {
+        wss.removeListener('error', reject);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * 关闭 ws 服务器（连接已在之前全部终止）
+   * @returns {Promise<void>} 无返回值
+   */
+  _closeServer() {
+    const wss = this.#wss;
+    this.#wss = null;
+    if (!wss) return Promise.resolve();
+    return new Promise((resolve) => {
+      wss.close(() => resolve());
+    });
+  }
+
+  // ---------- 校验辅助 ----------
+  /**
+   * 断言调用参数含 client_id
+   * @param {Object} params 调用参数
+   * @throws {Error} 缺少 client_id 时
+   */
+  _requireClientId(params) {
+    if (!params.client_id) {
+      throw new Error(`${this._label()} params.client_id required`);
+    }
+  }
+}
+
+module.exports = WebSocketServer;

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "mm_websocket_server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "最薄的 WebSocket 服务器入站适配器：消息直达 mm_event 事件管理器，不做路由与插件。",
+  "keywords": [
+    "超级美眉",
+    "入站适配器",
+    "mm_mod",
+    "mm_adapter",
+    "mm_in_adapter",
+    "mm_receiver",
+    "websocket",
+    "ws",
+    "server"
+  ],
+  "layer": "adapter",
+  "group": "in_adapter",
+  "license": "ISC",
+  "author": "qww",
+  "type": "commonjs",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "example"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_websocket_server.git"
+  },
+  "homepage": "https://gitee.com/qiuwenwu91/mm_websocket_server",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_websocket_server/issues"
+  },
+  "scripts": {
+    "start": "node example/demo.js",
+    "demo": "node example/demo.js",
+    "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"
+  }
+}