mm_socket_server 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # mm_socket_server
 
-最薄的 TCP/UDP 套接字服务器入站适配器。继承 `mm_mod` 的 `Mod`，把每条报文直接交给 `mm_event` 的事件管理器处理，不做路由表、不做插件、不加载脚本。
+最薄的 TCP/UDP 套接字服务器入站适配器。继承 `mm_mod` 的 `Mod`，把按 topic 分帧后的报文以 topic 为 `target` 交给 `mm_event` 的事件管理器处理，不做路由表、不做插件、不加载脚本。`protocol` 可选 `tcp`、`udp` 或 `both`（同端口同时监听）。
 
 - 入口：`index.js`（CommonJS）
 - 导出：`SocketServer`、`admin`、`socketServerAdmin`
@@ -9,12 +9,27 @@
 ## 消息路径
 
 ```
-net / dgram → connection / message → ctx = { client_id, protocol, address, socket | rinfo }
-            → eventManager.run(protocol, params, ctx, options)
-            → 结果非空时回发来源客户端
+net / dgram → connection / data / message → 按 framing 切出 { topic, payload }
+            → ctx = { client_id, topic, protocol, address, scope, socket | rinfo }
+            → eventManager.run(topic, params, ctx, options)（同一连接的消息串行执行）
+            → 结果非空时按同一帧格式回发来源客户端
 ```
 
-事件 `target` 取协议名：`tcp` 或 `udp`。`params` 为 `{ client_id, data }`，`data` 在 `json: true` 时尝试 `JSON.parse`（失败回落原文）。
+事件 `target` 取帧内的 topic（如 `chat/1`），因此可按主题精细分发，也支持 `mm_event` 的 `*` 通配（前缀、后缀、包含）。`params` 为 `{ client_id, topic, data }`，`data` 在 `json: true` 时尝试 `JSON.parse`（失败回落原文）。
+
+### 帧格式
+
+| `framing` | 帧格式 | 说明 |
+| --- | --- | --- |
+| `line`（默认） | `topic<空格>payload\n` | 以 `0x0a` 分帧，兼容剥除 `\r\n`；payload 不能含换行，否则发送时报错 |
+| `length` | `[uint16BE topic 长度][uint32BE payload 长度][topic][payload]` | 二进制安全，TCP 按长度拼包，UDP 用于校验完整性 |
+| `none` | 不分帧 | `target` 回落为协议名 `tcp` / `udp`，保持旧行为 |
+
+topic 一律按 utf8 编解码，`encoding` 只作用于 payload。缺少 topic 的帧会被丢弃并通过 `error` 事件上报 `invalid frame: missing topic`；UDP 长度帧不完整时上报 `invalid frame: truncated`。
+
+> **TCP 是字节流，没有天然消息边界。** 模块按 `framing` 做连接级缓冲与拼包/拆包，因此 `line` / `length` 下可安全处理粘包与拆包；UDP 保留数据报边界，一次报文即一帧。
+
+同一连接的消息按到达顺序串行执行：事件处理函数返回 Promise 时，后一条消息会等前一条处理完再开始，避免响应乱序。
 
 ## 快速开始
 
@@ -23,18 +38,15 @@ net / dgram → connection / message → ctx = { client_id, protocol, address, s
 
 const { SocketServer } = require('mm_socket_server');
 
-const socket = new SocketServer({ name: 'socket', host: '127.0.0.1', port: 9000 });
+const socket = new SocketServer({ name: 'socket', protocol: 'both', host: '127.0.0.1', port: 9000 });
 const events = socket.getEventManager();
 
-events.add({ name: 'echo', target: 'tcp', end: true }).main = async (params, ctx) => ({
-  client_id: ctx.client_id,
-  data: params.data
-});
+events.add({ name: 'echo', target: 'chat/echo', end: true }).main = async (params) => params.data;
 
 await socket.init();
 await socket.start();
 
-console.log(socket.getAddress());
+console.log(socket.getAddresses());
 ```
 
 ## 服务器配置
@@ -44,13 +56,16 @@ console.log(socket.getAddress());
 | `name` | string | `'os'` | 模块名称（必填） |
 | `title` | string | `'Socket服务器模块'` | 模块标题 |
 | `description` | string | — | 模块描述 |
-| `version` | string | `'2.0.0'` | 版本号 |
-| `protocol` | string | `'tcp'` | 传输协议：`tcp` 或 `udp` |
+| `version` | string | `'3.0.0'` | 版本号 |
+| `protocol` | string | `'tcp'` | 监听协议，接受 `tcp` / `udp` / `both`，其他值在 `init()` 时抛错 |
+| `framing` | string | `'line'` | 帧格式，接受 `line` / `length` / `none`，其他值在 `init()` 时抛错 |
 | `host` | string | `'0.0.0.0'` | 监听地址 |
 | `port` | number | `9000` | 监听端口 |
-| `encoding` | string | `'utf8'` | 入站解码字符集 |
+| `encoding` | string | `'utf8'` | payload 解码字符集（topic 始终 utf8） |
 | `json` | boolean | `false` | 入站尝试 JSON 解析，出站对象自动序列化 |
-| `params` | object | `{ action }` | `main` 的参数约定 |
+| `scope` | string | `'socket'` | 事件管理器作用域，多实例可用不同 scope 隔离事件 |
+| `udp_ttl` | number | `300000` | UDP 客户端空闲多久（毫秒）后移出连接表，`<= 0` 关闭清理 |
+| `params` | object | `{ action }` | `main` 的参数约定（`action` / `client_id` / `topic` / `data`） |
 
 ## API
 
@@ -58,12 +73,13 @@ console.log(socket.getAddress());
 | --- | --- |
 | `init()` / `start()` / `stop()` / `dispose()` | `Mod` 生命周期模板方法 |
 | `onInit()` / `onStart()` / `onStop()` / `onDispose()` | 生命周期钩子，子类可覆盖 |
-| `getEventManager()` | 获取 `mm_event` 的 `socket` 作用域事件管理器（与其他实例共享），用于注册事件 |
+| `getEventManager()` | 获取 `mm_event` 上 `scope` 作用域的事件管理器（默认 `socket`，其他实例共享同一作用域），用于注册事件 |
 | `setEventManager(manager)` | 注入外部事件管理器，需提供 `run()` |
-| `getAddress()` | 实际监听地址，未启动为 `null` |
+| `getAddress(protocol)` | 指定协议的实际监听地址，未启动为 `null`；省略 `protocol` 时取首个已启用协议 |
+| `getAddresses()` | 返回 `{ tcp, udp }` 两个协议各自的监听地址 |
 | `run(params, ctx, options)` | 主动操作入口，`params.action` 派发 `send` / `broadcast` / `close` / `list` |
-| `send(client_id, data)` | 向指定客户端发送数据，返回是否成功 |
-| `broadcast(data)` | 向全部在线客户端广播，返回送达数 |
+| `send(client_id, data, topic)` | 向指定客户端发送数据，`framing` 非 `none` 时 `topic` 必填，返回是否成功 |
+| `broadcast(data, topic)` | 向全部在线客户端广播，`framing` 非 `none` 时 `topic` 必填，返回送达数 |
 | `closeClient(client_id)` | 关闭指定客户端（TCP 销毁套接字，UDP 仅移出连接表） |
 | `listClients()` | 在线客户端列表 `{ id, protocol, address }` |
 | `hasClient(client_id)` | 是否在线 |
@@ -74,8 +90,10 @@ console.log(socket.getAddress());
 | 字段 | 说明 |
 | --- | --- |
 | `client_id` | 客户端编号，TCP 形如 `tcp_1`，UDP 形如 `udp_127.0.0.1:5000` |
+| `topic` | 当前帧的 topic，即事件的 `target` |
 | `protocol` | 当前协议，`tcp` 或 `udp` |
 | `address` | 远端地址，形如 `ip:port` |
+| `scope` | 当前实例的事件管理器作用域 |
 | `socket` | TCP 连接（UDP 报文无此字段），事件可直接写出 |
 | `rinfo` | UDP 远端地址信息（TCP 消息无此字段） |
 
@@ -84,25 +102,31 @@ console.log(socket.getAddress());
 签名固定为 `(params, ctx, options)`：
 
 ```js
-events.add({ name: 'echo', target: 'tcp', end: true }).main = async (params, ctx, options) => {
-  return { data: params.data };
+events.add({ name: 'echo', target: 'chat/echo', end: true }).main = async (params, ctx, options) => {
+  return params.data;
 };
 ```
 
-返回非 `undefined` / `null` 的结果会按 `json` 配置编码后回发来源客户端；返回 `undefined` 则不回发。事件也可直接用 `ctx.socket` 写出。
+返回非 `undefined` / `null` 的结果会按 `framing` 与原 topic 编码后回发来源客户端；返回 `{ topic, data }` 则改发到指定 topic；返回 `undefined` 则不回发。事件也可直接用 `ctx.socket` 写出。
 
 ## 主动操作
 
 ```js
-await socket.run({ action: 'send', client_id: 'tcp_1', data: 'hi' });
-await socket.run({ action: 'broadcast', data: { type: 'notice' } });
+await socket.run({ action: 'send', client_id: 'tcp_1', topic: 'chat/echo', data: 'hi' });
+await socket.run({ action: 'broadcast', topic: 'notice', data: { type: 'notice' } });
 await socket.run({ action: 'close', client_id: 'tcp_1' });
 await socket.run({ action: 'list' });
 ```
 
+`action` 仅支持上述四种，其他值直接抛 `unsupported action` 错误。`framing` 非 `none` 时 `send` / `broadcast` 必须给出 `topic`。
+
 ## 生命周期
 
-`onStart` 按 `protocol` 创建并监听 `net.Server` 或 `dgram.Socket`，`onStop` 断开全部连接并关闭服务器。事件管理器取自 `mm_event` 的 `socket` 作用域，由全局 `Admin` 共享，停止时不清理。端口被占用时 `start()` 抛错，模块进入 `error` 状态，可 `dispose()` 释放。
+`onInit` 校验 `protocol` 只能是 `tcp` / `udp` / `both`、`framing` 只能是 `line` / `length` / `none`；`onStart` 按 `protocol` 创建并监听 `net.Server` 或 `dgram.Socket`（`both` 时两者同端口并行，TCP 与 UDP 端口空间互不影响），`onStop` 断开全部连接并关闭服务器。启动失败（如端口被占用）时会先回滚已创建的服务器与连接表再抛错，模块进入 `error` 状态，可 `dispose()` 释放；`both` 模式下任一协议启动失败也会回滚另一协议。
+
+事件管理器取自 `mm_event` 上 `scope` 指定的作用域（默认 `socket`），由全局 `Admin` 共享，停止时不清理；多个实例需要不同作用域时，配置不同的 `scope` 即可。
+
+UDP 没有连接概念，首次收到某远端地址的报文时登记为客户端，之后超过 `udp_ttl` 未再收到报文会被定时清理。
 
 ## 示例
 

package/example/demo.js

@@ -6,22 +6,35 @@ const { SocketServer } = require('..');
 const DEMO_PORT = 9000;
 
 /**
- * 注册演示事件：协议名即事件 target
+ * 注册演示事件：帧内 topic 即事件 target
  * @param {Object} events 事件管理器
  * @returns {void}
  */
 function bindEvents(events) {
-  events.add({ name: 'echo', target: 'tcp', end: true }).main = async (params, ctx) => ({
+  events.add({ name: 'echo', target: 'chat/echo', end: true }).main = async (params, ctx) => ({
     type: 'echo',
     client_id: ctx.client_id,
     data: params.data
   });
 
-  events.add({ name: 'time', target: 'udp', end: true }).main = async () => ({
+  events.add({ name: 'time', target: 'chat/time', end: true }).main = async () => ({
     time: new Date().toISOString()
   });
 }
 
+/**
+ * 打印两种协议的监听地址
+ * @param {Object} socket 套接字服务器实例
+ * @returns {void}
+ */
+function printAddresses(socket) {
+  const addresses = socket.getAddresses();
+  for (const protocol of Object.keys(addresses)) {
+    const address = addresses[protocol];
+    if (address) console.log(`${protocol}://127.0.0.1:${address.port}`);
+  }
+}
+
 /**
  * 演示入口：启动服务器并打印监听地址
  * @returns {Promise<void>} 无返回值
@@ -31,7 +44,7 @@ async function main() {
     name: 'demo',
     host: '127.0.0.1',
     port: DEMO_PORT,
-    protocol: 'tcp'
+    protocol: 'both'
   });
 
   bindEvents(socket.getEventManager());
@@ -40,9 +53,8 @@ async function main() {
   await socket.init();
   await socket.start();
 
-  const address = socket.getAddress();
-  console.log(`tcp://127.0.0.1:${address.port}`);
-  console.log('发送任意内容，结果由 target 为 tcp 的事件返回并自动回发');
+  printAddresses(socket);
+  console.log('发送 `chat/echo hello\\n`，事件返回结果会以同一 topic 回发');
 }
 
 main().catch((err) => {

package/lib/socket.js

@@ -6,17 +6,63 @@ const { Mod } = require('mm_mod');
 const { eventAdmin } = require('mm_event');
 
 /**
- * SocketServer —— 最薄的 TCP/UDP 传输层（入站适配器模块）。
+ * 长度前缀帧的头部字节数：2 字节 topic 长度 + 4 字节 payload 长度
+ */
+const LENGTH_HEADER_SIZE = 6;
+
+/**
+ * topic 长度的字节数
+ */
+const TOPIC_LENGTH_SIZE = 2;
+
+/**
+ * 换行符字节
+ */
+const LINE_FEED = 0x0a;
+
+/**
+ * 回车符字节
+ */
+const CARRIAGE_RETURN = 0x0d;
+
+/**
+ * 空格字节，行协议中分隔 topic 与 payload
+ */
+const SPACE = 0x20;
+
+/**
+ * 支持的协议
+ */
+const PROTOCOLS = ['tcp', 'udp'];
+
+/**
+ * 支持的协议配置值
+ */
+const PROTOCOL_MODES = ['tcp', 'udp', 'both'];
+
+/**
+ * 支持的帧格式
+ */
+const FRAMINGS = ['line', 'length', 'none'];
+
+/**
+ * SocketServer —— TCP/UDP 传输层（入站适配器模块）。
+ *
+ * 职责：
+ *   1. 生命周期：由 Mod 的 init / start / stop 驱动 net.Server / dgram.Socket，
+ *      protocol 支持 tcp、udp 或 both（同端口同时监听两种传输层）；
+ *   2. 消息转交：按 framing 把字节流还原成 { topic, payload } 帧，以 topic 为 target
+ *      调用 EventManager.run(topic, params, ctx, options)，支持 mm_event 的 `*` 通配；
+ *   3. 结果回发：事件返回非空结果时按同一帧格式回发来源客户端。
  *
- * 只做三件事：
- *   1. 生命周期：由 Mod 的 init / start / stop 驱动 net.Server 或 dgram.Socket；
- *   2. 消息转交：以协议名（tcp / udp）为 target，直接调用
- *      EventManager.run(target, params, ctx, options)，不做路由、不做插件；
- *   3. 结果回发：事件返回非空结果时回发来源客户端，事件也可用 ctx.socket 自行写出。
+ * 帧格式：
+ *   line   —— `topic<空格>payload\n`，TCP 按换行分帧，payload 不能含换行；
+ *   length —— `[2字节 topic 长度][4字节 payload 长度][topic][payload]`，二进制安全；
+ *   none   —— 不分帧，target 回落为连接协议名（tcp / udp），保持旧行为。
  *
  * 用法：
- *   const socket = new SocketServer({ name: 'socket', protocol: 'tcp', port: 9000 });
- *   socket.getEventManager().add({ name: 'echo', target: 'tcp' }).main = async (params) => params.data;
+ *   const socket = new SocketServer({ name: 'socket', protocol: 'both', port: 9000 });
+ *   socket.getEventManager().add({ name: 'echo', target: 'chat/*' }).main = async (params) => params.data;
  *   await socket.init();
  *   await socket.start();
  */
@@ -27,28 +73,32 @@ class SocketServer extends Mod {
   static config = {
     name: 'os',
     title: 'Socket服务器模块',
-    description: 'TCP/UDP 传输层：消息直达事件管理器，不做路由与插件',
-    version: '2.0.0',
+    description: 'TCP/UDP 传输层：按 topic 帧直达事件管理器，不做插件',
+    version: '3.0.0',
     protocol: 'tcp',
     host: '0.0.0.0',
     port: 9000,
     encoding: 'utf8',
     json: false,
+    scope: 'socket',
+    framing: 'line',
+    udp_ttl: 300000,
     params: {
       type: 'object',
       required: ['action'],
       properties: {
         action: { type: 'string', enum: ['send', 'broadcast', 'close', 'list'] },
         client_id: { type: 'string', min_length: 1 },
+        topic: { type: 'string', min_length: 1 },
         data: {}
       }
     }
   };
 
   /**
-   * 底层服务器实例（net.Server 或 dgram.Socket）
+   * 底层服务器实例，按协议分槽存放
    */
-  #server = null;
+  #servers = { tcp: null, udp: null };
 
   /**
    * 事件管理器（取自 mm_event 的 socket 作用域，与其他实例共享）
@@ -65,6 +115,11 @@ class SocketServer extends Mod {
    */
   #counter = 0;
 
+  /**
+   * UDP 过期连接清理定时器
+   */
+  #udp_timer = null;
+
   /**
    * 构造函数
    * @param {Object} config 模块配置
@@ -72,20 +127,81 @@ class SocketServer extends Mod {
    */
   constructor(config, server) {
     super(config, server);
-    this.#events = eventAdmin('socket');
+    this.#events = eventAdmin(this.config.scope);
   }
 
   // ---------- 生命周期钩子 ----------
   /**
-   * 启动钩子：按协议创建底层服务器并开始监听
+   * 初始化钩子：校验协议与帧格式配置
+   * @returns {Promise<void>} 无返回值
+   * @throws {Error} protocol 或 framing 不受支持时
+   */
+  async onInit() {
+    this._validateConfig();
+  }
+
+  /**
+   * 校验配置项
+   * @returns {void}
+   * @throws {Error} protocol 或 framing 不受支持时
+   */
+  _validateConfig() {
+    const protocol = this.config.protocol;
+    if (!PROTOCOL_MODES.includes(protocol)) {
+      throw new Error(`${this._label()} unsupported protocol: ${protocol}`);
+    }
+    const framing = this.config.framing;
+    if (!FRAMINGS.includes(framing)) {
+      throw new Error(`${this._label()} unsupported framing: ${framing}`);
+    }
+  }
+
+  /**
+   * 启动钩子：按 protocol 逐个创建底层服务器，任一失败则全部回滚
    * @returns {Promise<void>} 无返回值
    */
   async onStart() {
-    if (this.config.protocol === 'udp') {
-      await this._startUdp();
-      return;
+    try {
+      for (const protocol of this._enabledProtocols()) {
+        await this._startServer(protocol);
+      }
+    } catch (err) {
+      await this._rollbackStart();
+      throw err;
+    }
+  }
+
+  /**
+   * 列出本次需要监听的协议
+   * @returns {Array<string>} 协议名列表
+   */
+  _enabledProtocols() {
+    const protocol = this.config.protocol;
+    if (protocol === 'both') return PROTOCOLS.slice();
+    return [protocol];
+  }
+
+  /**
+   * 按协议启动对应的底层服务器
+   * @param {string} protocol 协议名，tcp 或 udp
+   * @returns {Promise<void>} 无返回值
+   */
+  async _startServer(protocol) {
+    if (protocol === 'udp') return this._startUdp();
+    return this._startTcp();
+  }
+
+  /**
+   * 启动失败时回滚已创建的资源
+   * @returns {Promise<void>} 无返回值
+   */
+  async _rollbackStart() {
+    try {
+      this._closeAllClients();
+      await this._closeServers();
+    } catch (err) {
+      this._emitError(err);
     }
-    await this._startTcp();
   }
 
   /**
@@ -94,7 +210,7 @@ class SocketServer extends Mod {
    */
   async onStop() {
     this._closeAllClients();
-    await this._closeServer();
+    await this._closeServers();
   }
 
   // ---------- 执行入口 ----------
@@ -104,33 +220,35 @@ class SocketServer 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}`);
   }
 
   /**
    * 执行发送操作
-   * @param {Object} params 调用参数，含 client_id 与 data
+   * @param {Object} params 调用参数，含 client_id、data 与 topic
    * @returns {Object} 操作结果
    */
   _actionSend(params) {
     this._requireClientId(params);
-    const success = this.send(params.client_id, params.data);
+    const success = this.send(params.client_id, params.data, params.topic);
     return { action: 'send', client_id: params.client_id, success };
   }
 
   /**
    * 执行广播操作
-   * @param {Object} params 调用参数，含 data
+   * @param {Object} params 调用参数，含 data 与 topic
    * @returns {Object} 操作结果，count 为送达客户端数
    */
   _actionBroadcast(params) {
-    const count = this.broadcast(params.data);
+    const count = this.broadcast(params.data, params.topic);
     return { action: 'broadcast', count };
   }
 
@@ -178,33 +296,47 @@ class SocketServer extends Mod {
 
   /**
    * 获取实际监听地址
-   * @returns {Object|null} 监听地址信息，未启动时为 null
+   * @param {string} [protocol] 协议名，省略时取首个已启用协议
+   * @returns {Object|null} 监听地址信息，未监听时为 null
    */
-  getAddress() {
-    const server = this.#server;
+  getAddress(protocol) {
+    const key = protocol || this._enabledProtocols()[0];
+    const server = this.#servers[key];
     return server ? server.address() : null;
   }
 
+  /**
+   * 获取各协议的监听地址
+   * @returns {Object} 形如 { tcp, udp } 的地址表，未监听为 null
+   */
+  getAddresses() {
+    return { tcp: this.getAddress('tcp'), udp: this.getAddress('udp') };
+  }
+
   // ---------- 公开操作 ----------
   /**
    * 向指定客户端发送数据
    * @param {string} client_id 客户端 ID
-   * @param {string|Object} data 待发送数据
+   * @param {string|Object|Buffer} data 待发送数据
+   * @param {string} [topic] 目标主题，framing 非 none 时必填
    * @returns {boolean} 是否发送成功
+   * @throws {Error} framing 非 none 且缺少 topic 时
    */
-  send(client_id, data) {
+  send(client_id, data, topic) {
     const client = this.#clients.get(client_id);
     if (!client) return false;
-    return this._sendToClient(client, this._encodeData(data));
+    return this._sendToClient(client, this._encodeFrame(topic, data));
   }
 
   /**
    * 向全部在线客户端广播数据
-   * @param {string|Object} data 待广播数据
+   * @param {string|Object|Buffer} data 待广播数据
+   * @param {string} [topic] 目标主题，framing 非 none 时必填
    * @returns {number} 送达的客户端数量
+   * @throws {Error} framing 非 none 且缺少 topic 时
    */
-  broadcast(data) {
-    const payload = this._encodeData(data);
+  broadcast(data, topic) {
+    const payload = this._encodeFrame(topic, data);
     let count = 0;
     for (const client of this.#clients.values()) {
       if (this._sendToClient(client, payload)) count += 1;
@@ -276,7 +408,7 @@ class SocketServer extends Mod {
    */
   async _startTcp() {
     const server = net.createServer((socket) => this._handleConnection(socket));
-    this.#server = server;
+    this.#servers.tcp = server;
     await this._listenTcp(server);
     server.on('error', (err) => this._emitError(err));
   }
@@ -311,7 +443,9 @@ class SocketServer extends Mod {
       address: this._remoteAddress(socket),
       socket,
       rinfo: null,
-      options: null
+      options: null,
+      buffer: Buffer.alloc(0),
+      queue: Promise.resolve()
     };
     this.#clients.set(client_id, client);
     socket.on('data', (buf) => this._handleData(client_id, buf));
@@ -320,32 +454,285 @@ class SocketServer extends Mod {
   }
 
   /**
-   * 处理 TCP 收到的数据：解码后交给事件管理器，返回非空结果时回发来源客户端
+   * 接收 TCP 数据并排入该连接的串行队列
    * @param {string} client_id 客户端 ID
    * @param {Object} buf 数据缓冲区
-   * @returns {Promise<void>} 无返回值
+   * @returns {void}
    */
-  async _handleData(client_id, buf) {
+  _handleData(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,
-      protocol: client.protocol,
-      address: client.address,
-      socket: client.socket
-    };
+    this._enqueue(client, () => this._processTcpData(client, buf));
+  }
+
+  /**
+   * 把任务追加到连接的串行队列，保证同一连接的消息顺序执行
+   * @param {Object} client 连接信息
+   * @param {Function} task 待执行任务
+   * @returns {void}
+   */
+  _enqueue(client, task) {
+    client.queue = client.queue
+      .then(() => task())
+      .catch((err) => this._emitError(err));
+  }
+
+  /**
+   * 处理 TCP 数据：数据是字节流，需按帧格式累积切分
+   * @param {Object} client 连接信息
+   * @param {Object} buf 数据缓冲区
+   * @returns {Promise<void>} 无返回值
+   */
+  async _processTcpData(client, buf) {
+    await this._processInbound(client, buf, false);
+  }
+
+  // ---------- 分帧与派发 ----------
+  /**
+   * 统一入站处理：按 framing 还原帧，逐帧派发给事件管理器
+   * @param {Object} client 连接信息
+   * @param {Object} buf 本次收到的数据
+   * @param {boolean} is_complete 数据是否自带边界（UDP 为 true，TCP 为 false）
+   * @returns {Promise<void>} 无返回值
+   */
+  async _processInbound(client, buf, is_complete) {
+    if (this.config.framing === 'none') {
+      await this._dispatchMessage(client, client.protocol, this._decodeData(buf));
+      return;
+    }
+    const buffer = is_complete ? buf : Buffer.concat([client.buffer, buf]);
+    const { frames, rest } = this._extractFrames(buffer);
+    if (!is_complete) client.buffer = Buffer.from(rest);
+    for (const frame of frames) {
+      await this._dispatchMessage(client, frame.topic, this._decodeData(frame.payload));
+    }
+    if (is_complete && rest.length > 0) {
+      this._emitError(new Error(`${this._label()} invalid frame: truncated`));
+    }
+  }
+
+  /**
+   * 按当前帧格式切分缓冲区
+   * @param {Object} buffer 数据缓冲区
+   * @returns {Object} 形如 { frames, rest } 的结果，rest 为未成帧的剩余字节
+   */
+  _extractFrames(buffer) {
+    if (this.config.framing === 'length') return this._extractLengthFrames(buffer);
+    return this._extractLineFrames(buffer);
+  }
+
+  /**
+   * 按换行切分帧
+   * @param {Object} buffer 数据缓冲区
+   * @returns {Object} 形如 { frames, rest } 的结果
+   */
+  _extractLineFrames(buffer) {
+    const frames = [];
+    let start = 0;
+    let index = buffer.indexOf(LINE_FEED, start);
+    while (index !== -1) {
+      let end = index;
+      if (end > start && buffer[end - 1] === CARRIAGE_RETURN) end -= 1;
+      this._appendLineFrame(frames, buffer.subarray(start, end));
+      start = index + 1;
+      index = buffer.indexOf(LINE_FEED, start);
+    }
+    return { frames, rest: buffer.subarray(start) };
+  }
+
+  /**
+   * 解析单行帧并追加到结果集，缺少 topic 时丢弃并上报错误
+   * @param {Array<Object>} frames 帧结果集
+   * @param {Object} line 行数据
+   * @returns {void}
+   */
+  _appendLineFrame(frames, line) {
+    if (line.length === 0) return;
+    const frame = this._splitLineFrame(line);
+    if (!frame) {
+      this._emitError(new Error(`${this._label()} invalid frame: missing topic`));
+      return;
+    }
+    frames.push(frame);
+  }
+
+  /**
+   * 把一行拆成 topic 与 payload
+   * @param {Object} line 行数据
+   * @returns {Object|null} 形如 { topic, payload } 的帧，缺少 topic 时为 null
+   */
+  _splitLineFrame(line) {
+    const index = line.indexOf(SPACE);
+    if (index <= 0) return null;
+    const topic = line.subarray(0, index).toString('utf8');
+    return { topic, payload: line.subarray(index + 1) };
+  }
+
+  /**
+   * 按长度前缀切分帧
+   * @param {Object} buffer 数据缓冲区
+   * @returns {Object} 形如 { frames, rest } 的结果
+   */
+  _extractLengthFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (buffer.length - offset >= LENGTH_HEADER_SIZE) {
+      const topic_length = buffer.readUInt16BE(offset);
+      const payload_length = buffer.readUInt32BE(offset + TOPIC_LENGTH_SIZE);
+      const total = LENGTH_HEADER_SIZE + topic_length + payload_length;
+      if (buffer.length - offset < total) break;
+      const topic_start = offset + LENGTH_HEADER_SIZE;
+      const payload_start = topic_start + topic_length;
+      const topic = buffer.subarray(topic_start, payload_start).toString('utf8');
+      const payload = buffer.subarray(payload_start, offset + total);
+      if (topic_length === 0) {
+        this._emitError(new Error(`${this._label()} invalid frame: missing topic`));
+      } else {
+        frames.push({ topic, payload });
+      }
+      offset += total;
+    }
+    return { frames, rest: buffer.subarray(offset) };
+  }
+
+  /**
+   * 把入站帧派发给事件管理器，以 topic 作为 target
+   * @param {Object} client 连接信息
+   * @param {string} topic 帧主题
+   * @param {string|Object} data 解码后的数据
+   * @returns {Promise<void>} 无返回值
+   */
+  async _dispatchMessage(client, topic, data) {
+    const params = this._buildParams(client, topic, data);
+    const ctx = this._buildContext(client, topic);
     const options = this._clientOptions(client);
     try {
-      const result = await this.#events.run(this.config.protocol, params, ctx, options);
+      const result = await this.#events.run(topic, params, ctx, options);
       const error = ctx.error || options.error;
       if (error) this._emitError(error);
-      if (result !== undefined && result !== null) this.send(client_id, result);
+      this._reply(client, topic, result);
     } catch (err) {
       this._emitError(err);
     }
   }
 
+  /**
+   * 构建事件执行参数
+   * @param {Object} client 连接信息
+   * @param {string} topic 帧主题
+   * @param {string|Object} data 解码后的数据
+   * @returns {Object} 参数对象
+   */
+  _buildParams(client, topic, data) {
+    return { client_id: client.id, topic, data };
+  }
+
+  /**
+   * 构建事件执行上下文
+   * @param {Object} client 连接信息
+   * @param {string} topic 帧主题
+   * @returns {Object} 上下文对象
+   */
+  _buildContext(client, topic) {
+    const ctx = {
+      client_id: client.id,
+      topic,
+      protocol: client.protocol,
+      address: client.address,
+      scope: this.config.scope
+    };
+    if (client.rinfo) ctx.rinfo = client.rinfo;
+    if (client.socket) ctx.socket = client.socket;
+    return ctx;
+  }
+
+  /**
+   * 按事件返回值回发数据：{ topic, data } 视为重发描述，其余沿用来源 topic
+   * @param {Object} client 连接信息
+   * @param {string} topic 来源主题
+   * @param {*} result 事件返回值
+   * @returns {void}
+   */
+  _reply(client, topic, result) {
+    if (result === undefined || result === null) return;
+    if (this._isReplyDescriptor(result)) {
+      this.send(client.id, result.data, result.topic);
+      return;
+    }
+    this.send(client.id, result, topic);
+  }
+
+  /**
+   * 判断事件返回值是否为重发描述
+   * @param {*} result 事件返回值
+   * @returns {boolean} 是否为形如 { topic, data } 的描述
+   */
+  _isReplyDescriptor(result) {
+    if (!result || typeof result !== 'object' || Buffer.isBuffer(result)) return false;
+    if (typeof result.topic !== 'string' || result.topic.length === 0) return false;
+    return Object.prototype.hasOwnProperty.call(result, 'data');
+  }
+
+  // ---------- 建帧与编码 ----------
+  /**
+   * 按当前帧格式把 topic 与数据打包成可发送的缓冲区
+   * @param {string} topic 目标主题，framing 非 none 时必填
+   * @param {string|Object|Buffer} data 待发送数据
+   * @returns {Object} 待发送缓冲区
+   * @throws {Error} framing 非 none 且缺少 topic 时
+   */
+  _encodeFrame(topic, data) {
+    const payload = this._encodePayload(data);
+    if (this.config.framing === 'none') return payload;
+    this._requireTopic(topic);
+    if (this.config.framing === 'length') return this._buildLengthFrame(topic, payload);
+    return this._buildLineFrame(topic, payload);
+  }
+
+  /**
+   * 把数据编码成缓冲区，Buffer 原样返回
+   * @param {string|Object|Buffer} data 待编码数据
+   * @returns {Object} 数据缓冲区
+   */
+  _encodePayload(data) {
+    if (Buffer.isBuffer(data)) return data;
+    return Buffer.from(this._encodeData(data), this.config.encoding);
+  }
+
+  /**
+   * 构建行帧：`topic<空格>payload\n`
+   * @param {string} topic 主题
+   * @param {Object} payload 数据缓冲区
+   * @returns {Object} 帧缓冲区
+   * @throws {Error} payload 含换行符时（行帧无法表达）
+   */
+  _buildLineFrame(topic, payload) {
+    if (payload.indexOf(LINE_FEED) !== -1) {
+      throw new Error(`${this._label()} line framing payload cannot contain newline`);
+    }
+    const head = Buffer.from(`${topic} `, 'utf8');
+    const tail = Buffer.from([LINE_FEED]);
+    return Buffer.concat([head, payload, tail]);
+  }
+
+  /**
+   * 构建长度前缀帧：`[2字节 topic 长度][4字节 payload 长度][topic][payload]`
+   * @param {string} topic 主题
+   * @param {Object} payload 数据缓冲区
+   * @returns {Object} 帧缓冲区
+   * @throws {Error} topic 超出 65535 字节时
+   */
+  _buildLengthFrame(topic, payload) {
+    const topic_buf = Buffer.from(topic, 'utf8');
+    if (topic_buf.length > 0xffff) {
+      throw new Error(`${this._label()} topic too long`);
+    }
+    const header = Buffer.alloc(LENGTH_HEADER_SIZE);
+    header.writeUInt16BE(topic_buf.length, 0);
+    header.writeUInt32BE(payload.length, TOPIC_LENGTH_SIZE);
+    return Buffer.concat([header, topic_buf, payload]);
+  }
+
   /**
    * 获取远端地址字符串
    * @param {Object} socket 套接字实例
@@ -362,10 +749,11 @@ class SocketServer extends Mod {
    */
   async _startUdp() {
     const socket = dgram.createSocket('udp4');
-    this.#server = socket;
+    this.#servers.udp = socket;
     await this._bindUdp(socket);
     socket.on('message', (buf, rinfo) => this._handleUdpMessage(buf, rinfo));
     socket.on('error', (err) => this._emitError(err));
+    this._startUdpTimer();
   }
 
   /**
@@ -386,52 +774,88 @@ class SocketServer extends Mod {
   }
 
   /**
-   * 处理 UDP 报文：首见远端地址登记为客户端，之后交给事件管理器
+   * 处理 UDP 报文：首见远端地址登记为客户端，之后排入该客户端的串行队列
    * @param {Object} buf 数据缓冲区
    * @param {Object} rinfo 远端地址信息
-   * @returns {Promise<void>} 无返回值
+   * @returns {void}
    */
-  async _handleUdpMessage(buf, rinfo) {
+  _handleUdpMessage(buf, rinfo) {
     const client = this._ensureUdpClient(rinfo);
-    const params = { client_id: client.id, data: this._decodeData(buf) };
-    const ctx = {
-      client_id: client.id,
-      protocol: client.protocol,
-      address: client.address,
-      rinfo
-    };
-    const options = this._clientOptions(client);
-    try {
-      const result = await this.#events.run(this.config.protocol, 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);
-    }
+    this._enqueue(client, () => this._processUdpData(client, buf));
   }
 
   /**
-   * 登记 UDP 客户端（同一远端地址复用同一 client_id）
+   * 处理 UDP 报文：数据报自带边界，按帧格式解析后派发
+   * @param {Object} client 连接信息
+   * @param {Object} buf 数据缓冲区
+   * @returns {Promise<void>} 无返回值
+   */
+  async _processUdpData(client, buf) {
+    await this._processInbound(client, buf, true);
+  }
+
+  /**
+   * 登记 UDP 客户端（同一远端地址复用同一 client_id），并刷新活跃时间
    * @param {Object} rinfo 远端地址信息
    * @returns {Object} 客户端信息
    */
   _ensureUdpClient(rinfo) {
     const client_id = `udp_${rinfo.address}:${rinfo.port}`;
     const existed = this.#clients.get(client_id);
-    if (existed) return existed;
+    if (existed) {
+      existed.last_seen = Date.now();
+      return existed;
+    }
     const client = {
       id: client_id,
       protocol: 'udp',
       address: client_id,
       socket: null,
       rinfo,
-      options: null
+      options: null,
+      last_seen: Date.now(),
+      queue: Promise.resolve()
     };
     this.#clients.set(client_id, client);
     return client;
   }
 
+  /**
+   * 启动 UDP 过期连接清理定时器，udp_ttl <= 0 时关闭清理
+   * @returns {void}
+   */
+  _startUdpTimer() {
+    const ttl = this.config.udp_ttl;
+    if (!ttl || ttl <= 0) return;
+    const interval = Math.max(1000, Math.min(ttl, 60000));
+    this.#udp_timer = setInterval(() => this._pruneUdpClients(), interval);
+    if (typeof this.#udp_timer.unref === 'function') this.#udp_timer.unref();
+  }
+
+  /**
+   * 清理超过 udp_ttl 未活动的 UDP 客户端
+   * @returns {void}
+   */
+  _pruneUdpClients() {
+    const ttl = this.config.udp_ttl;
+    if (!ttl || ttl <= 0) return;
+    const deadline = Date.now() - ttl;
+    for (const [client_id, client] of this.#clients) {
+      if (client.protocol !== 'udp') continue;
+      if (client.last_seen <= deadline) this.#clients.delete(client_id);
+    }
+  }
+
+  /**
+   * 停止 UDP 过期连接清理定时器
+   * @returns {void}
+   */
+  _clearUdpTimer() {
+    if (!this.#udp_timer) return;
+    clearInterval(this.#udp_timer);
+    this.#udp_timer = null;
+  }
+
   // ---------- 数据编解码 ----------
   /**
    * 编码待发送数据
@@ -491,7 +915,7 @@ class SocketServer extends Mod {
    * @returns {boolean} 是否发送成功
    */
   _sendUdp(client, payload) {
-    const socket = this.#server;
+    const socket = this.#servers.udp;
     if (!socket || !client.rinfo) return false;
     socket.send(payload, client.rinfo.port, client.rinfo.address);
     return true;
@@ -508,19 +932,46 @@ class SocketServer extends Mod {
   }
 
   /**
-   * 关闭底层服务器
+   * 关闭全部底层服务器并停止 UDP 清理定时器
    * @returns {Promise<void>} 无返回值
    */
-  _closeServer() {
-    const server = this.#server;
+  async _closeServers() {
+    this._clearUdpTimer();
+    const servers = this.#servers;
+    this.#servers = { tcp: null, udp: null };
+    await this._closeOne(servers.tcp);
+    await this._closeOne(servers.udp);
+  }
+
+  /**
+   * 关闭单个底层服务器
+   * @param {Object|null} server net.Server 或 dgram.Socket 实例
+   * @returns {Promise<void>} 无返回值
+   */
+  _closeOne(server) {
     if (!server) return Promise.resolve();
-    this.#server = null;
     return new Promise((resolve) => {
-      server.close(() => resolve());
+      try {
+        server.close(() => resolve());
+      } catch {
+        resolve();
+      }
     });
   }
 
   // ---------- 校验辅助 ----------
+  /**
+   * 断言 topic 非空（framing 非 none 时帧必须携带 topic）
+   * @param {string} topic 目标主题
+   * @returns {void}
+   * @throws {Error} topic 为空时
+   */
+  _requireTopic(topic) {
+    if (!topic) {
+      throw new Error(`${this._label()} topic required when framing is ${this.config.framing}`);
+    }
+  }
+
   /**
    * 断言调用参数含 client_id
    * @param {Object} params 调用参数

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mm_socket_server",
-  "version": "2.0.0",
-  "description": "最薄的 TCP/UDP 套接字服务器入站适配器：消息直达 mm_event 事件管理器，不做路由与插件。",
+  "version": "3.0.0",
+  "description": "最薄的 TCP/UDP 套接字服务器入站适配器：按 topic 分帧后直达 mm_event 事件管理器，不做路由与插件。",
   "keywords": [
     "超级美眉",
     "入站适配器",