mm_socket_server 1.0.2 → 3.0.0

package/lib/socket.js

@@ -2,45 +2,69 @@
 
 const net = require('net');
 const dgram = require('dgram');
-const { Mod, Store } = require('mm_corejs');
-const { Handle } = require('mm_handle');
+const { Mod } = require('mm_mod');
+const { eventAdmin } = require('mm_event');
 
 /**
- * 服务器设置校验 schema（校验对象为顶层 config，而非 run 时选项）
+ * 长度前缀帧的头部字节数：2 字节 topic 长度 + 4 字节 payload 长度
  */
-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' }
-  }
-};
+const LENGTH_HEADER_SIZE = 6;
 
 /**
- * SocketServer —— TCP/UDP 套接字服务器（入站适配器模块）。
- *
- * 继承 mm_corejs 的 Mod：生命周期由 Lifecycle 模板方法驱动，
- * 调用参数校验由 config.params 声明式定义；
- * 服务器设置（protocol / host / port / encoding / json）为顶层 config 字段，
- * 在 onInit 阶段按 SERVER_SCHEMA 统一校验。
+ * 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. 监听：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。
+ *   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. 结果回发：事件返回非空结果时按同一帧格式回发来源客户端。
+ *
+ * 帧格式：
+ *   line   —— `topic<空格>payload\n`，TCP 按换行分帧，payload 不能含换行；
+ *   length —— `[2字节 topic 长度][4字节 payload 长度][topic][payload]`，二进制安全；
+ *   none   —— 不分帧，target 回落为连接协议名（tcp / udp），保持旧行为。
  *
  * 用法：
- *   const socket = new SocketServer({ name: 'socket', host: '127.0.0.1', port: 9000 }, server);
- *   socket.getHandle().on('main', (ctx, params) => `echo: ${params.data}`, 100, 'echo');
+ *   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();
- *   await socket.run({}, { action: 'list' });
  */
 class SocketServer extends Mod {
   /**
@@ -49,81 +73,144 @@ class SocketServer extends Mod {
   static config = {
     name: 'os',
     title: 'Socket服务器模块',
-    description: 'TCP/UDP 套接字服务器，管理连接并分发消息',
-    version: '1.0.0',
+    description: 'TCP/UDP 传输层：按 topic 帧直达事件管理器，不做插件',
+    version: '3.0.0',
     protocol: 'tcp',
     host: '0.0.0.0',
     port: 9000,
     encoding: 'utf8',
     json: false,
-    options: {},
+    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 },
-        data: {},
-        query: { type: 'object' }
+        topic: { type: 'string', min_length: 1 },
+        data: {}
       }
     }
   };
 
   /**
-   * 底层服务器实例（net.Server 或 dgram.Socket）
+   * 底层服务器实例，按协议分槽存放
    */
-  #server = null;
+  #servers = { tcp: null, udp: null };
 
   /**
-   * 连接注册表：Store 存储，主键 id、名称字段 name
+   * 事件管理器（取自 mm_event 的 socket 作用域，与其他实例共享）
    */
-  #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;
 
+  /**
+   * UDP 过期连接清理定时器
+   */
+  #udp_timer = null;
+
+  /**
+   * 构造函数
+   * @param {Object} config 模块配置
+   * @param {Object} server 框架实例
+   */
+  constructor(config, server) {
+    super(config, server);
+    this.#events = eventAdmin(this.config.scope);
+  }
+
   // ---------- 生命周期钩子 ----------
   /**
-   * 初始化钩子：校验服务器设置并装配消息管道
+   * 初始化钩子：校验协议与帧格式配置
+   * @returns {Promise<void>} 无返回值
+   * @throws {Error} protocol 或 framing 不受支持时
    */
   async onInit() {
-    await this._validateConfig();
-    this._initHandle();
+    this._validateConfig();
   }
 
   /**
-   * 启动钩子：按协议创建底层服务器并开始监听
+   * 校验配置项
+   * @returns {void}
+   * @throws {Error} protocol 或 framing 不受支持时
    */
-  async onStart() {
+  _validateConfig() {
     const protocol = this.config.protocol;
-    if (protocol === 'udp') {
-      await this._startUdp();
-      return;
+    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}`);
     }
-    await this._startTcp();
   }
 
   /**
-   * 停止钩子：断开全部连接并关闭底层服务器
+   * 启动钩子：按 protocol 逐个创建底层服务器，任一失败则全部回滚
+   * @returns {Promise<void>} 无返回值
    */
-  async onStop() {
-    this._closeAllClients();
-    await this._closeServer();
+  async onStart() {
+    try {
+      for (const protocol of this._enabledProtocols()) {
+        await this._startServer(protocol);
+      }
+    } catch (err) {
+      await this._rollbackStart();
+      throw err;
+    }
   }
 
   /**
-   * 释放钩子：清空连接注册表
+   * 列出本次需要监听的协议
+   * @returns {Array<string>} 协议名列表
    */
-  async onDispose() {
-    this.#clients.clear();
+  _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);
+    }
+  }
+
+  /**
+   * 停止钩子：断开全部连接并关闭服务器（事件管理器与其他实例共享，不清理）
+   * @returns {Promise<void>} 无返回值
+   */
+  async onStop() {
+    this._closeAllClients();
+    await this._closeServers();
   }
 
   // ---------- 执行入口 ----------
@@ -133,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(params);
+    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 };
   }
 
@@ -176,62 +265,108 @@ class SocketServer extends Mod {
 
   /**
    * 执行列出连接操作
-   * @param {Object} params 调用参数，可含 query 查询条件（Store 条件/分页）
    * @returns {Object} 操作结果，clients 为在线客户端列表
    */
-  _actionList(params) {
-    return { action: 'list', clients: this.listClients(params.query) };
+  _actionList() {
+    return { action: 'list', clients: this.listClients() };
+  }
+
+  // ---------- 事件管理器 ----------
+  /**
+   * 获取事件管理器，用于注册事件
+   * @returns {Object} 事件管理器实例
+   */
+  getEventManager() {
+    return this.#events;
+  }
+
+  /**
+   * 注入外部事件管理器
+   * @param {Object} manager 事件管理器实例
+   * @returns {SocketServer} 当前实例
+   * @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;
+  }
+
+  /**
+   * 获取实际监听地址
+   * @param {string} [protocol] 协议名，省略时取首个已启用协议
+   * @returns {Object|null} 监听地址信息，未监听时为 null
+   */
+  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) {
-    const client = this.#clients.getById(client_id);
+  send(client_id, data, topic) {
+    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._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.list()) {
+    for (const client of this.#clients.values()) {
       if (this._sendToClient(client, payload)) count += 1;
     }
     return count;
   }
 
   /**
-   * 关闭指定客户端连接
+   * 关闭指定客户端连接（TCP 销毁套接字，UDP 仅移出连接表）
    * @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;
+    this.#clients.delete(client_id);
     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
+   * 列出在线客户端
+   * @returns {Array<Object>} 客户端信息列表，含 id、protocol 与 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, protocol: client.protocol, address: client.address });
+    }
+    return list;
   }
 
   /**
@@ -240,64 +375,30 @@ class SocketServer extends Mod {
    * @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} 是否设置成功（客户端不在线时失败）
    */
   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} 连接级选项
-   */
-  _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 方法时
+   * 获取连接级选项（复制一份，避免事件管理器回写）
+   * @param {Object} client 连接信息
+   * @returns {Object} 选项对象
    */
-  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;
+  _clientOptions(client) {
+    if (!client.options) return {};
+    return { ...client.options };
   }
 
   // ---------- TCP ----------
@@ -307,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));
   }
@@ -330,7 +431,7 @@ class SocketServer extends Mod {
   }
 
   /**
-   * 登记新的 TCP 连接并绑定事件
+   * 登记新的 TCP 连接并绑定回调
    * @param {Object} socket 套接字实例
    */
   _handleConnection(socket) {
@@ -338,40 +439,298 @@ class SocketServer extends Mod {
     const client_id = `tcp_${this.#counter}`;
     const client = {
       id: client_id,
-      name: client_id,
+      protocol: 'tcp',
       address: this._remoteAddress(socket),
       socket,
-      rinfo: null
+      rinfo: null,
+      options: null,
+      buffer: Buffer.alloc(0),
+      queue: Promise.resolve()
     };
-    this.#clients.add(client);
+    this.#clients.set(client_id, client);
     socket.on('data', (buf) => this._handleData(client_id, buf));
-    socket.on('close', () => this._handleClose(client_id));
+    socket.on('close', () => this.#clients.delete(client_id));
     socket.on('error', (err) => this._emitError(err));
-    this._safeEmit('connection', client);
   }
 
   /**
-   * 处理 TCP 收到的数据：解码后进入消息管道，产出 result 时自动回发
+   * 接收 TCP 数据并排入该连接的串行队列
    * @param {string} client_id 客户端 ID
    * @param {Object} buf 数据缓冲区
+   * @returns {void}
+   */
+  _handleData(client_id, buf) {
+    const client = this.#clients.get(client_id);
+    if (!client) return;
+    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 _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);
+  async _processTcpData(client, buf) {
+    await this._processInbound(client, buf, false);
   }
 
+  // ---------- 分帧与派发 ----------
   /**
-   * 处理 TCP 连接关闭
-   * @param {string} client_id 客户端 ID
+   * 统一入站处理：按 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(topic, params, ctx, options);
+      const error = ctx.error || options.error;
+      if (error) this._emitError(error);
+      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 含换行符时（行帧无法表达）
    */
-  _handleClose(client_id) {
-    const existed = this.#clients.delById(client_id);
-    if (existed) this._safeEmit('close', client_id);
+  _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]);
   }
 
   /**
@@ -390,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();
   }
 
   /**
@@ -414,31 +774,86 @@ class SocketServer extends Mod {
   }
 
   /**
-   * 处理 UDP 报文：首见远端地址登记为客户端并触发 connection
+   * 处理 UDP 报文：首见远端地址登记为客户端，之后排入该客户端的串行队列
    * @param {Object} buf 数据缓冲区
    * @param {Object} rinfo 远端地址信息
+   * @returns {void}
    */
   _handleUdpMessage(buf, rinfo) {
+    const client = this._ensureUdpClient(rinfo);
+    this._enqueue(client, () => this._processUdpData(client, buf));
+  }
+
+  /**
+   * 处理 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 is_new = !this.#clients.getById(client_id);
+    const existed = this.#clients.get(client_id);
+    if (existed) {
+      existed.last_seen = Date.now();
+      return existed;
+    }
     const client = {
       id: client_id,
-      name: client_id,
+      protocol: 'udp',
       address: client_id,
       socket: null,
-      rinfo
+      rinfo,
+      options: null,
+      last_seen: Date.now(),
+      queue: Promise.resolve()
     };
-    if (is_new) {
-      this.#clients.add(client);
-      this._safeEmit('connection', client);
+    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);
     }
-    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);
-    });
+  }
+
+  /**
+   * 停止 UDP 过期连接清理定时器
+   * @returns {void}
+   */
+  _clearUdpTimer() {
+    if (!this.#udp_timer) return;
+    clearInterval(this.#udp_timer);
+    this.#udp_timer = null;
   }
 
   // ---------- 数据编解码 ----------
@@ -486,6 +901,7 @@ class SocketServer extends Mod {
    */
   _sendToClient(client, payload) {
     if (client.socket) {
+      if (client.socket.destroyed) return false;
       client.socket.write(payload);
       return true;
     }
@@ -499,54 +915,61 @@ 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;
   }
 
   /**
-   * 断开全部客户端连接并清空注册表
+   * 断开全部客户端连接并清空连接表
    */
   _closeAllClients() {
-    for (const client of this.#clients.list()) {
+    for (const client of this.#clients.values()) {
       if (client.socket) client.socket.destroy();
     }
     this.#clients.clear();
   }
 
   /**
-   * 关闭底层服务器
+   * 关闭全部底层服务器并停止 UDP 清理定时器
    * @returns {Promise<void>} 无返回值
    */
-  _closeServer() {
-    const server = this.#server;
-    if (!server) return Promise.resolve();
-    this.#server = null;
-    return new Promise((resolve) => {
-      server.close(resolve);
-    });
+  async _closeServers() {
+    this._clearUdpTimer();
+    const servers = this.#servers;
+    this.#servers = { tcp: null, udp: null };
+    await this._closeOne(servers.tcp);
+    await this._closeOne(servers.udp);
   }
 
-  // ---------- 校验辅助 ----------
   /**
-   * 装配消息管道：内置 main 钩子负责分发 message 事件（sort 置后，
-   * 不返回值，业务钩子产出的 result 由 _handleData 统一回发）
+   * 关闭单个底层服务器
+   * @param {Object|null} server net.Server 或 dgram.Socket 实例
+   * @returns {Promise<void>} 无返回值
    */
-  _initHandle() {
-    this.#handle.on('main', (params, ctx) => {
-      this._safeEmit('message', params.client_id, params.data);
-    }, 1000, 'emit_message');
+  _closeOne(server) {
+    if (!server) return Promise.resolve();
+    return new Promise((resolve) => {
+      try {
+        server.close(() => resolve());
+      } catch {
+        resolve();
+      }
+    });
   }
 
+  // ---------- 校验辅助 ----------
   /**
-   * 校验顶层 config 中的服务器设置
-   * @returns {Promise<void>} 无返回值
-   * @throws {Error} 校验不通过时
+   * 断言 topic 非空（framing 非 none 时帧必须携带 topic）
+   * @param {string} topic 目标主题
+   * @returns {void}
+   * @throws {Error} topic 为空时
    */
-  async _validateConfig() {
-    const tip = await this._validate(this.config, SERVER_SCHEMA);
-    if (tip) throw new Error(`${this._label()} invalid config: ${tip}`);
+  _requireTopic(topic) {
+    if (!topic) {
+      throw new Error(`${this._label()} topic required when framing is ${this.config.framing}`);
+    }
   }
 
   /**