mm_socket_server 1.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

@@ -0,0 +1,157 @@
+# mm_socket
+
+TCP/UDP 套接字服务器入站端口模块。继承 [mm_corejs](https://gitee.com/qiuwenwu91/mm_corejs) 的 `Mod` 基类，提供连接管理、消息处理管道与 JSON-RPC 2.0 消息插件，可脱离完整框架独立运行。
+
+- 入口：`index.js`（CommonJS）
+- 导出：`SocketServer`（服务器模块）、`MessagePlugin`（JSON-RPC 消息插件）
+- 运行时依赖：`mm_corejs`
+- 测试覆盖率：100%（`jest.config.js` 四项阈值）
+
+## 特性
+
+- **双协议**：`protocol: 'tcp' | 'udp'`，TCP 按连接登记客户端，UDP 按远端地址首见登记。
+- **生命周期**：`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_socket_server
+```
+
+## 环境要求
+
+- Node.js >= 22.5.0
+- 模块规范：CommonJS
+
+## 快速开始
+
+```js
+'use strict';
+
+const net = require('net');
+const { SocketServer, MessagePlugin } = require('mm_socket_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 socket = new SocketServer(server, { name: 'socket', host: '127.0.0.1', port: 9100 });
+
+// 业务钩子：文本消息直接回发 echo
+socket.getHandle().on('main', (ctx, params) => `echo: ${params.data}`, 100, 'echo');
+
+// JSON-RPC 插件：登记方法
+const rpc = new MessagePlugin();
+socket.use(rpc);
+rpc.addMethod('sum', (params) => params.reduce((a, b) => a + b, 0));
+
+// 事件
+socket.on('connection', (client) => socket.setClientOptions(client.id, { user_id: 'u1' }));
+socket.on('message', (client_id, data) => console.log(client_id, data));
+socket.on('close', (client_id) => console.log('断开', client_id));
+socket.on('error', (err) => console.error(err.message));
+
+await socket.init();
+await socket.start();
+
+// 主动操作
+await socket.run({}, { action: 'list' });
+await socket.run({}, { action: 'broadcast', data: 'hello all' });
+
+await socket.stop();
+await socket.dispose();
+```
+
+## 服务器配置（config）
+
+顶层 `config` 字段即服务器设置，`init` 阶段统一校验。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | `'socket'` | 模块名称（必填） |
+| `protocol` | `'tcp' \| 'udp'` | `'tcp'` | 传输协议 |
+| `host` | string | `'0.0.0.0'` | 监听地址 |
+| `port` | integer | `9000` | 监听端口（1-65535） |
+| `encoding` | `'utf8' \| 'hex' \| 'base64'` | `'utf8'` | 入站数据解码方式 |
+| `json` | boolean | `false` | 为 `true` 时入站尝试 JSON 解析（失败回落原文），出站对象自动序列化 |
+
+## API
+
+### SocketServer
+
+| 成员 | 说明 |
+| --- | --- |
+| `run(ctx, params)` | 主动操作入口，`params.action` 派发：`send`（需 `client_id` / `data`）、`broadcast`（需 `data`）、`close`（需 `client_id`）、`list`（可选 `query` 条件查询） |
+| `send(client_id, data)` | 向指定客户端发送数据，返回是否成功 |
+| `broadcast(data)` | 向全部在线客户端广播，返回送达数 |
+| `closeClient(client_id)` | 关闭指定连接，返回是否发起 |
+| `listClients(query)` | 在线客户端列表（`{ id, address }`），支持 Store 条件 / 分页 / keyword |
+| `hasClient(client_id)` | 是否在线 |
+| `setClientOptions(client_id, options)` | 绑定连接级选项（`null` 清空），随入站消息透传 |
+| `use(plugin)` | 挂载插件（需实现 `bind(server)`） |
+| `getHandle()` | 消息管道，注册 `before / check / main / render` 等钩子；钩子产出 `result` 自动回发 |
+| `getAddress()` | 实际监听地址，未启动为 `null` |
+
+### 事件
+
+| 事件 | 参数 | 触发时机 |
+| --- | --- | --- |
+| `connection` | `(client)` | 新连接接入（UDP 为首见远端地址） |
+| `message` | `(client_id, data)` | 入站消息经管道内置 `emit_message` 钩子分发 |
+| `close` | `(client_id)` | 连接关闭 |
+| `error` | `(err)` | 底层服务器 / 套接字 / 钩子错误 |
+
+### 消息管道
+
+每条入站消息以 `{ client_id, data }` 为 `params`、连接级 `options` 为第三参进入管道：
+
+```
+before → check → main（业务钩子按 sort 依次执行）→ render
+```
+
+任一阶段产出非 `undefined` 的 `result` 即回发来源客户端；`check` / `before` 产出时短路后续阶段。
+
+## MessagePlugin（JSON-RPC 2.0）
+
+挂载后接管 `jsonrpc` 形态消息（非 RPC 消息透传给业务钩子）：
+
+```js
+const rpc = new MessagePlugin();
+socket.use(rpc);
+rpc.addMethod('echo', (params, extra, options) => params); // extra.client_id，options 为连接级选项
+```
+
+| 成员 | 说明 |
+| --- | --- |
+| `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()` | 挂载与状态查询 |
+
+协议行为：请求（含 `id`）返回响应对象；通知（无 `id`）处理函数有返回值时回推服务器发起的通知 `{ jsonrpc, method, params }`；客户端把响应形态消息（含 `result` / `error`、无 `method`）发回即结算对应的反向调用。
+
+## 示例
+
+```bash
+npm run demo   # 启动 TCP 演示服务器（127.0.0.1:9100），见 example/demo.js
+```
+
+## 测试
+
+```bash
+npm test       # jest --coverage，四项覆盖率阈值均为 100%
+```
+
+## 许可证
+
+ISC

package/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const SocketServer = require('./lib/socket');
+const MessagePlugin = require('./lib/message');
+
+module.exports = {
+  SocketServer,
+  MessagePlugin
+};

package/lib/message.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const { JsonRpc } = require('mm_corejs');
+
+/**
+ * MessagePlugin —— JSON-RPC 2.0 消息插件（mm_socket 的可选业务组件）。
+ *
+ * 职责：
+ *   1. 方法表：内部持有 JsonRpc 核心，addMethod / delMethod / listMethods 登记可调用方法；
+ *   2. 管道挂载：bind(socket) 后向消息管道注册 main 钩子 "json_rpc"（sort 100，
+ *      先于内置 emit_message 执行），命中 JSON-RPC 请求时以响应对象作为管道 result，
+ *      由 SocketServer 自动回发来源客户端；
+ *   3. 通知回推：通知（无 id）处理函数返回非 undefined 结果时，产出服务器发起的
+ *      通知对象 { jsonrpc, method, params: result } 回推来源客户端；无结果或出错时
+ *      不产出；非 JSON-RPC 消息（解析失败、缺 jsonrpc 字段）透传，控制权交还管道；
+ *   4. 主动推送：push(client_id, data) 委托 SocketServer.send，处理函数或服务器代码
+ *      可在任意时刻（如异步任务完成后）向指定客户端回推结果；
+ *   5. 反向调用：call(client_id, method, params, options) 向客户端发起 JSON-RPC 请求
+ *      并等待其反馈；入站消息为响应形态（含 result/error、无 method）时被优先识别
+ *      并结算待响应调用，实现服务器实时调用客户端方法；
+ *   6. 编码适配：json 模式产出对象（由 send 序列化），文本模式字符串原样、其余 JSON 序列化。
+ *
+ * 用法：
+ *   const socket = new SocketServer(server, { name: 'socket', port: 9100, json: true });
+ *   const rpc = new MessagePlugin();
+ *   socket.use(rpc);
+ *   rpc.addMethod('echo', (params) => params);
+ *   await socket.init();
+ *   await socket.start();
+ */
+class MessagePlugin {
+  /**
+   * JSON-RPC 协议核心
+   */
+  #rpc = new JsonRpc();
+
+  /**
+   * 已挂载的 SocketServer 实例，未挂载时为 null
+   */
+  #server = null;
+
+  /**
+   * 挂载到 SocketServer 的消息管道，注册内置 main 钩子
+   * @param {Object} server 具备 getHandle() 的 SocketServer 实例
+   * @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', (ctx, params, options) => {
+      return this._execute(ctx, params, options);
+    }, 100, 'json_rpc');
+    return this;
+  }
+
+  /**
+   * 判断是否已挂载
+   * @returns {boolean} 是否已挂载到 SocketServer
+   */
+  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} ctx 执行上下文
+   * @param {Object} params 消息参数，含 client_id 与 data
+   * @param {Object} [options] 管道请求选项（连接级，如 user_id / device_id / agent_id），透传给处理函数
+   * @returns {Promise<Object|string|undefined>} 响应对象或 JSON 字符串；反馈、透传与无结果通知时为 undefined
+   */
+  async _execute(ctx, params, 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;

package/lib/socket.js

@@ -0,0 +1,562 @@
+'use strict';
+
+const net = require('net');
+const dgram = require('dgram');
+const { Mod, Handle, Store } = require('mm_corejs');
+
+/**
+ * 服务器设置校验 schema（校验对象为顶层 config，而非 run 时选项）
+ */
+const SERVER_SCHEMA = {
+  type: 'object',
+  properties: {
+    protocol: { type: 'string', enum: ['tcp', 'udp'] },
+    host: { type: 'string', min_length: 1 },
+    port: { type: 'integer', minimum: 1, maximum: 65535 },
+    encoding: { type: 'string', enum: ['utf8', 'hex', 'base64'] },
+    json: { type: 'boolean' }
+  }
+};
+
+/**
+ * SocketServer —— TCP/UDP 套接字服务器（入站端口模块）。
+ *
+ * 继承 mm_corejs 的 Mod：生命周期由 Lifecycle 模板方法驱动，
+ * 调用参数校验由 config.params 声明式定义；
+ * 服务器设置（protocol / host / port / encoding / json）为顶层 config 字段，
+ * 在 onInit 阶段按 SERVER_SCHEMA 统一校验。
+ *
+ * 职责：
+ *   1. 监听：onStart 按 protocol 创建 net.Server 或 dgram.Socket 并监听；
+ *   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。
+ *
+ * 用法：
+ *   const socket = new SocketServer(server, { name: 'socket', host: '127.0.0.1', port: 9000 });
+ *   socket.getHandle().on('main', (ctx, params) => `echo: ${params.data}`, 100, 'echo');
+ *   await socket.init();
+ *   await socket.start();
+ *   await socket.run({}, { action: 'list' });
+ */
+class SocketServer extends Mod {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'socket',
+    title: 'Socket服务器模块',
+    description: 'TCP/UDP 套接字服务器，管理连接并分发消息',
+    version: '1.0.0',
+    protocol: 'tcp',
+    host: '0.0.0.0',
+    port: 9000,
+    encoding: 'utf8',
+    json: false,
+    options: {},
+    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' }
+      }
+    }
+  };
+
+  /**
+   * 底层服务器实例（net.Server 或 dgram.Socket）
+   */
+  #server = null;
+
+  /**
+   * 连接注册表：Store 存储，主键 id、名称字段 name
+   */
+  #clients = new Store({ key: 'id', name: 'name' });
+
+  /**
+   * 消息处理管道（before/check/main/render/error/success/after）
+   */
+  #handle = new Handle();
+
+  /**
+   * 客户端编号自增计数器
+   */
+  #counter = 0;
+
+  // ---------- 生命周期钩子 ----------
+  /**
+   * 初始化钩子：校验服务器设置并装配消息管道
+   */
+  async onInit() {
+    await this._validateConfig();
+    this._initHandle();
+  }
+
+  /**
+   * 启动钩子：按协议创建底层服务器并开始监听
+   */
+  async onStart() {
+    const protocol = this.config.protocol;
+    if (protocol === 'udp') {
+      await this._startUdp();
+      return;
+    }
+    await this._startTcp();
+  }
+
+  /**
+   * 停止钩子：断开全部连接并关闭底层服务器
+   */
+  async onStop() {
+    this._closeAllClients();
+    await this._closeServer();
+  }
+
+  /**
+   * 释放钩子：清空连接注册表
+   */
+  async onDispose() {
+    this.#clients.clear();
+  }
+
+  // ---------- 执行入口 ----------
+  /**
+   * 模块主逻辑：按 action 派发操作
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 调用参数，含 action 及操作所需字段
+   * @param {Object} options 合并后的选项
+   * @returns {Promise<Object>} 操作结果
+   */
+  async main(ctx, params, 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);
+  }
+
+  /**
+   * 执行发送操作
+   * @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 };
+  }
+
+  /**
+   * 执行列出连接操作
+   * @param {Object} params 调用参数，可含 query 查询条件（Store 条件/分页）
+   * @returns {Object} 操作结果，clients 为在线客户端列表
+   */
+  _actionList(params) {
+    return { action: 'list', clients: this.listClients(params.query) };
+  }
+
+  // ---------- 公开操作 ----------
+  /**
+   * 向指定客户端发送数据
+   * @param {string} client_id 客户端 ID
+   * @param {string|Object} data 待发送数据
+   * @returns {boolean} 是否发送成功
+   */
+  send(client_id, data) {
+    const client = this.#clients.getById(client_id);
+    if (!client) return false;
+    const payload = this._encodeData(data);
+    return this._sendToClient(client, payload);
+  }
+
+  /**
+   * 向全部在线客户端广播数据
+   * @param {string|Object} data 待广播数据
+   * @returns {number} 送达的客户端数量
+   */
+  broadcast(data) {
+    const payload = this._encodeData(data);
+    let count = 0;
+    for (const client of this.#clients.list()) {
+      if (this._sendToClient(client, payload)) count += 1;
+    }
+    return count;
+  }
+
+  /**
+   * 关闭指定客户端连接
+   * @param {string} client_id 客户端 ID
+   * @returns {boolean} 是否关闭成功
+   */
+  closeClient(client_id) {
+    const client = this.#clients.getById(client_id);
+    if (!client) return false;
+    if (client.socket) client.socket.destroy();
+    this.#clients.delById(client_id);
+    this._safeEmit('close', client_id);
+    return true;
+  }
+
+  /**
+   * 列出在线客户端（支持 Store 条件查询与分页）
+   * @param {Object} query 查询条件，可含 page_now / page_size / keyword
+   * @returns {Array<Object>} 客户端信息列表，含 id 与 address
+   */
+  listClients(query) {
+    return this.#clients.list(query).map((client) => ({ id: client.id, address: client.address }));
+  }
+
+  /**
+   * 判断客户端是否在线
+   * @param {string} client_id 客户端 ID
+   * @returns {boolean} 是否在线
+   */
+  hasClient(client_id) {
+    return !!this.#clients.getById(client_id);
+  }
+
+  /**
+   * 绑定连接级选项（如 user_id / device_id / agent_id），入站消息将作为管道 options 透传给钩子与 RPC 处理函数
+   * @param {string} client_id 客户端 ID
+   * @param {Object|null} options 选项对象，null 时清空
+   * @returns {boolean} 是否设置成功（客户端不在线时失败）
+   */
+  setClientOptions(client_id, options) {
+    const client = this.#clients.getById(client_id);
+    if (!client) return false;
+    client.options = options || null;
+    return true;
+  }
+
+  /**
+   * 读取连接级选项，未绑定时返回空对象
+   * @param {string} client_id 客户端 ID
+   * @returns {Object} 连接级选项
+   */
+  _clientOptions(client_id) {
+    const client = this.#clients.getById(client_id);
+    if (!client || !client.options) return {};
+    return client.options;
+  }
+
+  /**
+   * 挂载插件：调用 plugin.bind(this)，由插件自行向管道注册钩子；
+   * 如 MessagePlugin 挂载后接管 JSON-RPC 请求
+   * @param {Object} plugin 具备 bind(server) 方法的插件实例
+   * @returns {SocketServer} 当前实例
+   * @throws {TypeError} plugin 不具备 bind 方法时
+   */
+  use(plugin) {
+    if (!plugin || typeof plugin.bind !== 'function') {
+      throw new TypeError(`${this._label()} plugin must provide bind()`);
+    }
+    plugin.bind(this);
+    return this;
+  }
+
+  /**
+   * 获取消息处理管道，供外部注册 before/check/main/render 等钩子；
+   * 钩子产出 result 时自动回发来源客户端
+   * @returns {Handle} 消息管道实例
+   */
+  getHandle() {
+    return this.#handle;
+  }
+
+  /**
+   * 获取实际监听地址
+   * @returns {Object|null} 监听地址信息，未启动时为 null
+   */
+  getAddress() {
+    const server = this.#server;
+    return server ? server.address() : null;
+  }
+
+  // ---------- TCP ----------
+  /**
+   * 启动 TCP 服务器
+   * @returns {Promise<void>} 无返回值
+   */
+  async _startTcp() {
+    const server = net.createServer((socket) => this._handleConnection(socket));
+    this.#server = server;
+    await this._listenTcp(server);
+    server.on('error', (err) => this._emitError(err));
+  }
+
+  /**
+   * 等待 TCP 服务器监听成功
+   * @param {Object} server net.Server 实例
+   * @returns {Promise<void>} 无返回值
+   */
+  _listenTcp(server) {
+    const host = this.config.host;
+    const port = this.config.port;
+    return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen({ host, port }, () => {
+        server.removeListener('error', reject);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * 登记新的 TCP 连接并绑定事件
+   * @param {Object} socket 套接字实例
+   */
+  _handleConnection(socket) {
+    this.#counter += 1;
+    const client_id = `tcp_${this.#counter}`;
+    const client = {
+      id: client_id,
+      name: client_id,
+      address: this._remoteAddress(socket),
+      socket,
+      rinfo: null
+    };
+    this.#clients.add(client);
+    socket.on('data', (buf) => this._handleData(client_id, buf));
+    socket.on('close', () => this._handleClose(client_id));
+    socket.on('error', (err) => this._emitError(err));
+    this._safeEmit('connection', client);
+  }
+
+  /**
+   * 处理 TCP 收到的数据：解码后进入消息管道，产出 result 时自动回发
+   * @param {string} client_id 客户端 ID
+   * @param {Object} buf 数据缓冲区
+   * @returns {Promise<void>} 无返回值
+   */
+  async _handleData(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);
+  }
+
+  /**
+   * 处理 TCP 连接关闭
+   * @param {string} client_id 客户端 ID
+   */
+  _handleClose(client_id) {
+    const existed = this.#clients.delById(client_id);
+    if (existed) this._safeEmit('close', client_id);
+  }
+
+  /**
+   * 获取远端地址字符串
+   * @param {Object} socket 套接字实例
+   * @returns {string} 形如 ip:port 的地址
+   */
+  _remoteAddress(socket) {
+    return `${socket.remoteAddress}:${socket.remotePort}`;
+  }
+
+  // ---------- UDP ----------
+  /**
+   * 启动 UDP 服务器
+   * @returns {Promise<void>} 无返回值
+   */
+  async _startUdp() {
+    const socket = dgram.createSocket('udp4');
+    this.#server = socket;
+    await this._bindUdp(socket);
+    socket.on('message', (buf, rinfo) => this._handleUdpMessage(buf, rinfo));
+    socket.on('error', (err) => this._emitError(err));
+  }
+
+  /**
+   * 等待 UDP 套接字绑定成功
+   * @param {Object} socket dgram.Socket 实例
+   * @returns {Promise<void>} 无返回值
+   */
+  _bindUdp(socket) {
+    const host = this.config.host;
+    const port = this.config.port;
+    return new Promise((resolve, reject) => {
+      socket.once('error', reject);
+      socket.bind({ address: host, port }, () => {
+        socket.removeListener('error', reject);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * 处理 UDP 报文：首见远端地址登记为客户端并触发 connection
+   * @param {Object} buf 数据缓冲区
+   * @param {Object} rinfo 远端地址信息
+   */
+  _handleUdpMessage(buf, rinfo) {
+    const client_id = `udp_${rinfo.address}:${rinfo.port}`;
+    const is_new = !this.#clients.getById(client_id);
+    const client = {
+      id: client_id,
+      name: client_id,
+      address: client_id,
+      socket: null,
+      rinfo
+    };
+    if (is_new) {
+      this.#clients.add(client);
+      this._safeEmit('connection', client);
+    }
+    const decoded = this._decodeData(buf);
+    const params = { client_id, data: decoded };
+    const ctx = { client_id };
+    this.#handle.run(ctx, params, this._clientOptions(client_id)).then((done) => {
+      if (done.error) this._emitError(done.error);
+      if (done.result !== undefined) this.send(client_id, done.result);
+    });
+  }
+
+  // ---------- 数据编解码 ----------
+  /**
+   * 编码待发送数据
+   * @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(this.config.encoding);
+    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.socket) {
+      client.socket.write(payload);
+      return true;
+    }
+    return this._sendUdp(client, payload);
+  }
+
+  /**
+   * 向 UDP 客户端发送数据
+   * @param {Object} client 客户端信息，含 rinfo
+   * @param {string} payload 已编码数据
+   * @returns {boolean} 是否发送成功
+   */
+  _sendUdp(client, payload) {
+    const socket = this.#server;
+    if (!socket || !client.rinfo) return false;
+    socket.send(payload, client.rinfo.port, client.rinfo.address);
+    return true;
+  }
+
+  /**
+   * 断开全部客户端连接并清空注册表
+   */
+  _closeAllClients() {
+    for (const client of this.#clients.list()) {
+      if (client.socket) client.socket.destroy();
+    }
+    this.#clients.clear();
+  }
+
+  /**
+   * 关闭底层服务器
+   * @returns {Promise<void>} 无返回值
+   */
+  _closeServer() {
+    const server = this.#server;
+    if (!server) return Promise.resolve();
+    this.#server = null;
+    return new Promise((resolve) => {
+      server.close(resolve);
+    });
+  }
+
+  // ---------- 校验辅助 ----------
+  /**
+   * 装配消息管道：内置 main 钩子负责分发 message 事件（sort 置后，
+   * 不返回值，业务钩子产出的 result 由 _handleData 统一回发）
+   */
+  _initHandle() {
+    this.#handle.on('main', (ctx, params) => {
+      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 调用参数
+   * @throws {Error} 缺少 client_id 时
+   */
+  _requireClientId(params) {
+    if (!params.client_id) {
+      throw new Error(`${this._label()} params.client_id required`);
+    }
+  }
+}
+
+module.exports = SocketServer;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mm_socket_server",
+  "version": "1.0.0",
+  "description": "TCP/UDP 套接字服务器入站端口模块，继承 mm_corejs 的 Mod 基类，支持独立运行。",
+  "keywords": [
+    "超级美眉",
+    "入站端口",
+    "mm_mod",
+    "mm_in_port",
+    "mm_receiver",
+    "socket",
+    "tcp",
+    "udp",
+    "server"
+  ],
+  "license": "ISC",
+  "author": "qww",
+  "type": "commonjs",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_socket.git"
+  },
+  "homepage": "https://gitee.com/qiuwenwu91/mm_socket",
+  "bugs": {
+    "url": "https://gitee.com/qiuwenwu91/mm_socket/issues"
+  },
+  "scripts": {
+    "start": "node example/demo.js",
+    "demo": "node example/demo.js",
+    "test": "jest --coverage"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.0"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}