mm_mqtt_server 1.0.1 → 2.0.0

package/README.md

@@ -1,158 +1,121 @@
 # mm_mqtt_server
 
-MQTT 代理服务器入站端口模块。继承 [mm_corejs](https://gitee.com/qiuwenwu91/mm_corejs) 的 `Mod` 基类，基于 [aedes](https://www.npmjs.com/package/aedes) 实现 MQTT Broker，提供连接管理、消息处理管道与 JSON-RPC 2.0 消息插件，可脱离完整框架独立运行。
+最薄的 MQTT 代理服务器入站适配器。继承 `mm_mod` 的 `Mod`，基于 [aedes](https://www.npmjs.com/package/aedes) 提供 Broker，把每条入站发布直接交给 `mm_event` 的事件管理器处理，不做路由表、不做插件、不加载脚本。
 
 - 入口：`index.js`（CommonJS）
-- 导出：`MqttServer`（代理模块）、`MessagePlugin`（JSON-RPC 消息插件）
-- 运行时依赖：`mm_corejs`、`aedes`
-- 测试覆盖率：100%（`jest.config.js` 四项阈值）
+- 导出：`MqttServer`、`admin`、`mqttServerAdmin`
+- 运行时依赖：`mm_mod`、`mm_event`、`mm_corejs`、`aedes`
 
-## 特性
+## 消息路径
 
-- **标准 Broker**：`net.Server` + `aedes` 监听 TCP 1883，支持订阅、发布、QoS 0-2 与保留消息。
-- **认证策略**：`allow_anonymous` 放行匿名连接；配置 `username` 后校验用户名与口令，失败以 `returnCode 5` 拒绝。
-- **消息管道**：入站发布消息经 `Handle` 的 `before / check / main / render` 阶段处理，管道产出 `{ topic, payload }` 时由代理重新发布（可用于改写、应答）；`getHandle()` 可注册主题守卫等钩子。
-- **连接管理**：`Store` 登记在线客户端，支持 `publish / closeClient / listClients（条件查询与分页）/ hasClient / setClientOptions`。
-- **JSON-RPC 2.0 插件**：`MessagePlugin` 挂载后接管 RPC 形态报文，应答发布到「请求主题 + 后缀」，支持通知回推、主动推送与服务器反向调用客户端方法。
-- **选项透传**：连接级 `options`（user_id / device_id / agent_id 等）随每条入站消息透传给管道钩子与 RPC 处理函数，适配多用户 / 多设备 / 多智能体场景。
-
-## 安装
-
-```bash
-npm install mm_mqtt_server
+```
+net → aedes → publish(topic, packet) → ctx = { client_id, topic, qos, retain, packet, client, broker }
+           → eventManager.run(topic, params, ctx, options)
+           → 结果形如 { topic, payload } 时由代理重发
 ```
 
-## 环境要求
-
-- Node.js >= 22.5.0
-- 模块规范：CommonJS
+事件 `target` 即发布主题；`mm_event` 按字符串级 `*` 匹配（如 `sensor/*`、`*/temp`），不支持 `#`。`params` 为 `{ client_id, topic, payload, qos, retain }`，`payload` 已按 UTF-8 转为字符串。
 
 ## 快速开始
 
 ```js
 'use strict';
 
-const { MqttServer, MessagePlugin } = require('mm_mqtt_server');
+const { MqttServer } = require('mm_mqtt_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 mqtt = new MqttServer({ name: 'mqtt_server', host: '127.0.0.1', port: 1883 }, server);
-
-// 主题守卫：check 阶段产出即短路
-mqtt.getHandle().on('check', (ctx, params) => {
-  if (params.topic.startsWith('blocked/')) return { dropped: true };
-}, 100, 'guard');
+const mqtt = new MqttServer({ name: 'mqtt', host: '127.0.0.1', port: 1883 });
+const events = mqtt.getEventManager();
 
-// JSON-RPC 插件
-const rpc = new MessagePlugin({ reply_suffix: '/response', qos: 0 });
-mqtt.use(rpc);
-rpc.addMethod('sum', (params, extra) => ({ sum: params.reduce((a, b) => a + b, 0), from: extra.topic }));
-
-// 事件
-mqtt.on('connection', (client) => mqtt.setClientOptions(client.id, { device_id: 'd1' }));
-mqtt.on('message', (client_id, info) => console.log(client_id, info.topic, info.payload));
-mqtt.on('subscribe', (client_id, topics) => console.log(client_id, topics));
-mqtt.on('close', (client_id) => console.log('断开', client_id));
-mqtt.on('error', (err) => console.error(err.message));
+events.add({ name: 'echo', target: 'demo/echo', end: true }).main = async (params) => ({
+  topic: 'demo/echo/out',
+  payload: params.payload
+});
 
 await mqtt.init();
 await mqtt.start();
 
-// 主动操作
-await mqtt.run({}, { action: 'publish', topic: 'mm/test', payload: 'hello' });
-await mqtt.run({}, { action: 'list_clients' });
-
-await mqtt.stop();
-await mqtt.dispose();
+console.log(mqtt.getAddress());
 ```
 
-## 服务器配置（config）
-
-顶层 `config` 字段即服务器设置，`init` 阶段统一校验。
+## 服务器配置
 
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `name` | string | `'mqtt_server'` | 模块名称（必填） |
+| `name` | string | `'os'` | 模块名称（必填） |
+| `title` | string | `'MQTT代理服务器模块'` | 模块标题 |
+| `description` | string | — | 模块描述 |
+| `version` | string | `'2.0.0'` | 版本号 |
 | `host` | string | `'0.0.0.0'` | 监听地址 |
-| `port` | integer | `1883` | 监听端口（1-65535） |
+| `port` | number | `1883` | 监听端口 |
 | `allow_anonymous` | boolean | `true` | 未配置 `username` 时放行匿名连接 |
 | `username` | string | `''` | 认证用户名，非空时启用口令认证 |
 | `password` | string | `''` | 认证口令 |
+| `options` | object | `{}` | 透传给 `Aedes.createBroker` 的额外选项（`authenticate` 固定由本模块提供） |
+| `params` | object | `{ action }` | `main` 的参数约定 |
 
 ## API
 
-### MqttServer
-
 | 成员 | 说明 |
 | --- | --- |
-| `run(ctx, params)` | 主动操作入口，`params.action` 派发：`publish`（需 `topic`，可带 `payload` / `qos` / `retain`）、`close_client`（需 `client_id`）、`list_clients`（可选 `query` 条件查询） |
+| `init()` / `start()` / `stop()` / `dispose()` | `Mod` 生命周期模板方法 |
+| `onInit()` / `onStart()` / `onStop()` / `onDispose()` | 生命周期钩子，子类可覆盖 |
+| `getEventManager()` | 获取 mm_event 的 `mqtt` 作用域事件管理器（与其他实例共享），用于注册事件 |
+| `setEventManager(manager)` | 注入外部事件管理器，需提供 `run()` |
+| `getAddress()` | 实际监听地址，未启动为 `null` |
+| `run(params, ctx, options)` | 主动操作入口，`params.action` 派发 `publish` / `close` / `list` |
 | `publish(topic, payload, opts)` | 代理端发布消息（进入正常路由，订阅者可收到），返回是否成功 |
 | `closeClient(client_id)` | 关闭指定客户端连接，返回是否发起 |
-| `listClients(query)` | 在线客户端列表（`{ id, address }`），支持 Store 条件 / 分页 / keyword |
+| `listClients()` | 在线客户端列表 `{ id, address }` |
 | `hasClient(client_id)` | 是否在线 |
-| `setClientOptions(client_id, options)` | 绑定连接级选项（`null` 清空），随入站消息透传 |
-| `use(plugin)` | 挂载插件（需实现 `bind(server)`） |
-| `getHandle()` | 消息管道，注册 `before / check / main / render` 等钩子；产出 `{ topic, payload }` 时代理重发 |
-| `getAddress()` | 实际监听地址，未启动为 `null` |
+| `setClientOptions(client_id, options)` | 绑定连接级选项，随入站消息作为 `options` 透传（`null` 清空） |
 
-### 事件
+## 请求上下文（ctx）
 
-| 事件 | 参数 | 触发时机 |
-| --- | --- | --- |
-| `connection` | `(client)` | 客户端接入，`client` 为 `{ id, address }` |
-| `message` | `(client_id, info)` | 入站发布消息经管道内置 `emit_message` 钩子分发，`info` 为 `{ topic, payload, qos, retain }` |
-| `subscribe` | `(client_id, topics)` | 客户端订阅主题 |
-| `unsubscribe` | `(client_id, topics)` | 客户端取消订阅 |
-| `close` | `(client_id)` | 客户端断开 |
-| `error` | `(err)` | TCP / broker / 管道钩子错误 |
+| 字段 | 说明 |
+| --- | --- |
+| `client_id` | 发布者客户端 ID |
+| `topic` | 发布主题 |
+| `qos` / `retain` | 发布报文的服务质量与保留标记 |
+| `packet` | aedes 原始发布报文 |
+| `client` | aedes 客户端实例，可直接调用其方法 |
+| `broker` | aedes broker 实例，可自行发布或操作会话 |
 
-### 消息管道
+## 事件处理函数
 
-每条入站发布消息以 `{ client_id, topic, payload, qos, retain }` 为 `params`、连接级 `options` 为第三参进入管道：
+签名固定为 `(params, ctx, options)`：
 
-```
-before → check → main（业务钩子按 sort 依次执行）→ render
+```js
+events.add({ name: 'relay', target: 'sensor/*', end: true }).main = async (params, ctx, options) => {
+  return { topic: 'archive/sensor', payload: params.payload };
+};
 ```
 
-产出 `{ topic, payload }` 时由代理重新发布该消息；代理自身重发的报文 `client` 为空，不再进入管道，因此无回环。
+返回 `{ topic, payload }` 时由代理重发该消息（可带 `qos` / `retain`）；返回其他值或 `undefined` 时不重发。事件也可直接用 `ctx.broker.publish()` 或 `ctx.client` 自行处理。代理自身重发的报文 `client` 为空，不会再次进入事件，因此无回环。
 
-## MessagePlugin（JSON-RPC 2.0）
+事件抛出的异常由 `mm_event` 记入 `options.error`，本模块再通过 `error` 事件上报，不会中断 broker。
 
-挂载后接管 RPC 形态报文（非 RPC 消息透传给业务钩子）：
+## 主动操作
 
 ```js
-const rpc = new MessagePlugin({ reply_suffix: '/response', push_prefix: 'rpc/push', call_prefix: 'rpc/call', qos: 0, retain: false });
-mqtt.use(rpc);
-rpc.addMethod('echo', (params, extra, options) => params); // extra.client_id / extra.topic
+await mqtt.run({ action: 'publish', topic: 'sys/notice', payload: 'hi' });
+await mqtt.run({ action: 'close', client_id: 'device_1' });
+await mqtt.run({ action: 'list' });
 ```
 
-| 成员 | 说明 |
-| --- | --- |
-| `addMethod(name, handler)` / `delMethod(name)` / `listMethods(query)` | 方法表管理，处理函数签名 `(params, extra, options)` |
-| `push(client_id, data, options)` | 发布数据到 `options.topic`（缺省 `push_prefix/client_id`），客户端订阅即接收 |
-| `call(client_id, method, params, options)` | 发布 JSON-RPC 请求到 `options.topic`（缺省 `call_prefix/client_id`）并等待客户端反馈，`options.timeout_ms` 缺省 30000 |
-| `bind(server)` / `isBound()` | 挂载与状态查询 |
+## 生命周期
 
-协议行为：请求（含 `id`）应答发布到「请求主题 + `reply_suffix`」；通知（无 `id`）处理函数有返回值时，把服务器发起的通知 `{ jsonrpc, method, params }` 发布到应答主题；客户端把响应形态报文（含 `result` / `error`、无 `method`）发布回 RPC 主题即结算对应的反向调用。
+`onStart` 创建 aedes broker 与 `net.Server` 并开始监听，绑定连接表与入站发布；`onStop` 断开全部客户端、关闭服务器与 broker。事件管理器取自 mm_event 的 `mqtt` 作用域，由全局 `Admin` 共享，停止时不清理。端口被占用时 `start()` 抛错，模块进入 `error` 状态，可 `dispose()` 释放。
 
 ## 示例
 
 ```bash
-npm run demo   # 启动 MQTT 代理演示服务器（127.0.0.1:1883），见 example/demo.js
+npm run demo   # 启动演示代理（127.0.0.1:1883），见 example/demo.js
 ```
 
 ## 测试
 
 ```bash
-npm test       # jest --coverage，四项覆盖率阈值均为 100%
+npm test       # node --test
 ```
 
 ## 许可证

package/example/demo.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { MqttServer } = require('..');
+
+/** 演示监听端口 */
+const DEMO_PORT = 1883;
+
+/**
+ * 注册演示事件：发布主题即事件 target
+ * @param {Object} events 事件管理器
+ * @returns {void}
+ */
+function bindEvents(events) {
+  events.add({ name: 'echo', target: 'demo/echo', end: true }).main = async (params) => ({
+    topic: 'demo/echo/out',
+    payload: params.payload
+  });
+
+  events.add({ name: 'time', target: 'demo/time', end: true }).main = async () => ({
+    topic: 'demo/time/out',
+    payload: new Date().toISOString()
+  });
+
+  events.add({ name: 'upper', target: 'demo/upper', end: true }).main = async (params) => ({
+    topic: 'demo/lower',
+    payload: String(params.payload).toLowerCase()
+  });
+}
+
+/**
+ * 演示入口：启动 MQTT 代理并打印监听地址
+ * @returns {Promise<void>} 无返回值
+ */
+async function main() {
+  const mqtt = new MqttServer({
+    name: 'demo',
+    host: '127.0.0.1',
+    port: DEMO_PORT
+  });
+
+  bindEvents(mqtt.getEventManager());
+  mqtt.on('error', (err) => console.error(`[demo] 错误: ${err.message}`));
+
+  await mqtt.init();
+  await mqtt.start();
+
+  const address = mqtt.getAddress();
+  console.log(`mqtt://127.0.0.1:${address.port}`);
+  console.log('订阅 demo/echo/out 后发布到 demo/echo，事件返回的 { topic, payload } 会被代理重发');
+  console.log('demo/time 返回当前时间，demo/upper 把内容转小写后发到 demo/lower');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/index.js

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

package/lib/mqtt_server.js

@@ -2,58 +2,37 @@
 
 const net = require('net');
 const { Aedes } = require('aedes');
-const { Mod, Handle, Store } = require('mm_corejs');
+const { Mod } = require('mm_mod');
+const { eventAdmin } = require('mm_event');
 
 /**
- * 服务器设置校验 schema（校验对象为顶层 config）
- */
-const SERVER_SCHEMA = {
-  type: 'object',
-  properties: {
-    host: { type: 'string', min_length: 1 },
-    port: { type: 'integer', minimum: 1, maximum: 65535 },
-    allow_anonymous: { type: 'boolean' },
-    username: { type: 'string' },
-    password: { type: 'string' }
-  }
-};
-
-/**
- * MqttServer —— MQTT 代理服务器（入站端口模块）。
+ * MqttServer —— 最薄的 MQTT 代理传输层（入站适配器模块）。
  *
- * 继承 mm_corejs 的 Mod：生命周期由 Lifecycle 模板方法驱动，
- * 调用参数校验由 config.params 声明式定义；
- * 服务器设置（host / port / allow_anonymous / username / password）为顶层 config 字段，
- * 在 onInit 阶段按 SERVER_SCHEMA 统一校验。
- *
- * 职责：
- *   1. 监听：onStart 创建 aedes broker 与 net.Server，按 host / port 监听 MQTT 连接；
- *   2. 连接管理：#clients 使用 Store 登记在线客户端（主键 id，支持条件查询与分页）；
- *   3. 消息管道：入站发布消息经 Handle 的 before/check/main/render 阶段处理，
- *      内置 main 钩子发 message 事件保持兼容；管道产出 { topic, payload } 时
- *      由代理重新发布该消息；getHandle() 可注册自定义钩子（如主题黑名单）；
- *   4. 事件分发：connection / message / subscribe / unsubscribe / close / error；
- *   5. 主动操作：run(ctx, params) 按 params.action 派发 publish / close_client / list_clients。
+ * 只做三件事：
+ *   1. 生命周期：由 Mod 的 init / start / stop 驱动 aedes broker 与 net.Server；
+ *   2. 消息转交：以发布主题为 target，直接调用
+ *      EventManager.run(topic, params, ctx, options)，不做路由、不做插件；
+ *   3. 结果重发：事件返回 { topic, payload } 时由代理重新发布，事件也可用
+ *      ctx.broker / ctx.client 自行处理。
  *
  * 用法：
- *   const mqtt = new MqttServer({ name: 'mqtt_server', host: '127.0.0.1', port: 1883 }, server);
- *   mqtt.getHandle().on('check', (ctx, params) => {
- *     if (params.topic.startsWith('blocked/')) return { dropped: true };
- *   }, 100, 'guard');
- *   mqtt.on('message', (client_id, info) => console.log(client_id, info.topic, info.payload));
+ *   const mqtt = new MqttServer({ name: 'mqtt', port: 1883 });
+ *   mqtt.getEventManager().add({ name: 'echo', target: 'mm/*' }).main = async (params) => ({
+ *     topic: params.topic,
+ *     payload: params.payload
+ *   });
  *   await mqtt.init();
  *   await mqtt.start();
- *   await mqtt.run({}, { action: 'publish', topic: 'mm/test', payload: 'hello' });
  */
 class MqttServer extends Mod {
   /**
    * 模块默认配置
    */
   static config = {
-    name: 'mqtt_server',
+    name: 'os',
     title: 'MQTT代理服务器模块',
-    description: '基于 aedes 的 MQTT 代理：管理客户端连接、主题订阅与消息路由',
-    version: '1.0.0',
+    description: 'MQTT 传输层：消息直达事件管理器，不做路由与插件',
+    version: '2.0.0',
     host: '0.0.0.0',
     port: 1883,
     allow_anonymous: true,
@@ -64,13 +43,12 @@ class MqttServer extends Mod {
       type: 'object',
       required: ['action'],
       properties: {
-        action: { type: 'string', enum: ['publish', 'close_client', 'list_clients'] },
+        action: { type: 'string', enum: ['publish', 'close', 'list'] },
         client_id: { type: 'string', min_length: 1 },
         topic: { type: 'string', min_length: 1 },
         payload: { type: 'string' },
         qos: { type: 'integer', minimum: 0, maximum: 2 },
-        retain: { type: 'boolean' },
-        query: { type: 'object' }
+        retain: { type: 'boolean' }
       }
     }
   };
@@ -86,26 +64,29 @@ class MqttServer extends Mod {
   #server = null;
 
   /**
-   * 连接注册表：Store 存储，主键 id、名称字段 name
+   * 事件管理器（取自 mm_event 的 mqtt 作用域，与其他实例共享）
    */
-  #clients = new Store({ key: 'id', name: 'name' });
+  #events = null;
 
   /**
-   * 消息处理管道（before/check/main/render/error/success/after）
+   * 在线连接表：client_id -> 连接信息
    */
-  #handle = new Handle();
+  #clients = new Map();
 
-  // ---------- 生命周期钩子 ----------
   /**
-   * 初始化钩子：校验服务器设置并装配消息管道
+   * 构造函数
+   * @param {Object} config 模块配置
+   * @param {Object} server 框架实例
    */
-  async onInit() {
-    await this._validateConfig();
-    this._initHandle();
+  constructor(config, server) {
+    super(config, server);
+    this.#events = eventAdmin('mqtt');
   }
 
+  // ---------- 生命周期钩子 ----------
   /**
    * 启动钩子：创建 broker 与 TCP 服务器并开始监听
+   * @returns {Promise<void>} 无返回值
    */
   async onStart() {
     const broker = await this._createBroker();
@@ -118,7 +99,8 @@ class MqttServer extends Mod {
   }
 
   /**
-   * 停止钩子：断开全部客户端，关闭 TCP 服务器与 broker
+   * 停止钩子：断开全部连接、关闭服务器与 broker（事件管理器与其他实例共享，不清理）
+   * @returns {Promise<void>} 无返回值
    */
   async onStop() {
     this._closeAllClients();
@@ -126,26 +108,19 @@ class MqttServer extends Mod {
     await this._closeBroker();
   }
 
-  /**
-   * 释放钩子：清空连接注册表
-   */
-  async onDispose() {
-    this.#clients.clear();
-  }
-
   // ---------- 执行入口 ----------
   /**
    * 模块主逻辑：按 action 派发操作
-   * @param {Object} ctx 执行上下文
    * @param {Object} params 调用参数，含 action 及操作所需字段
+   * @param {Object} ctx 执行上下文
    * @param {Object} options 合并后的选项
    * @returns {Promise<Object>} 操作结果
    */
-  async main(ctx, params, options) {
+  async main(params, ctx, options) {
     const action = params.action;
     if (action === 'publish') return this._actionPublish(params);
-    if (action === 'close_client') return this._actionCloseClient(params);
-    return this._actionListClients(params);
+    if (action === 'close') return this._actionClose(params);
+    return this._actionList();
   }
 
   /**
@@ -164,19 +139,50 @@ class MqttServer extends Mod {
    * @param {Object} params 调用参数，含 client_id
    * @returns {Object} 操作结果
    */
-  _actionCloseClient(params) {
+  _actionClose(params) {
     this._requireClientId(params);
     const success = this.closeClient(params.client_id);
-    return { action: 'close_client', client_id: params.client_id, success };
+    return { action: 'close', client_id: params.client_id, success };
   }
 
   /**
-   * 执行列出客户端操作
-   * @param {Object} params 调用参数，可含 query 查询条件（Store 条件/分页）
+   * 执行列出连接操作
    * @returns {Object} 操作结果，clients 为在线客户端列表
    */
-  _actionListClients(params) {
-    return { action: 'list_clients', clients: this.listClients(params.query) };
+  _actionList() {
+    return { action: 'list', clients: this.listClients() };
+  }
+
+  // ---------- 事件管理器 ----------
+  /**
+   * 获取事件管理器，用于注册事件
+   * @returns {Object} 事件管理器实例
+   */
+  getEventManager() {
+    return this.#events;
+  }
+
+  /**
+   * 注入外部事件管理器
+   * @param {Object} manager 事件管理器实例
+   * @returns {MqttServer} 当前实例
+   * @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 server = this.#server;
+    return server ? server.address() : null;
   }
 
   // ---------- 公开操作 ----------
@@ -184,7 +190,7 @@ class MqttServer extends Mod {
    * 代理端发布消息到指定主题
    * @param {string} topic 主题
    * @param {string|Buffer} payload 消息内容
-   * @param {Object} opts 发布选项，含 qos 与 retain
+   * @param {Object} [opts] 发布选项，含 qos 与 retain
    * @returns {Promise<boolean>} 是否发布成功
    */
   publish(topic, payload, opts = {}) {
@@ -203,48 +209,27 @@ class MqttServer extends Mod {
   }
 
   /**
-   * 关闭指定客户端连接
+   * 关闭指定客户端连接（连接表由 broker 的断开回调清理）
    * @param {string} client_id 客户端 ID
    * @returns {boolean} 是否发起关闭
    */
   closeClient(client_id) {
-    const entry = this.#clients.getById(client_id);
-    if (!entry) return false;
-    entry.client.close();
+    const client = this.#clients.get(client_id);
+    if (!client) return false;
+    client.client.close();
     return true;
   }
 
   /**
-   * 列出在线客户端（支持 Store 条件查询与分页）
-   * @param {Object} [query] 查询条件，缺省时列出全部
+   * 列出在线客户端
    * @returns {Array<Object>} 客户端信息列表，含 id 与 address
    */
-  listClients(query) {
-    return this.#clients.list(query).map((entry) => ({ id: entry.id, address: entry.address }));
-  }
-
-  /**
-   * 绑定连接级选项（如 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 entry = this.#clients.getById(client_id);
-    if (!entry) return false;
-    entry.options = options || null;
-    return true;
-  }
-
-  /**
-   * 读取连接级选项，未绑定时返回空对象
-   * @param {string} client_id 客户端 ID
-   * @returns {Object} 连接级选项
-   */
-  _clientOptions(client_id) {
-    const entry = this.#clients.getById(client_id);
-    if (!entry || !entry.options) return {};
-    return entry.options;
+  listClients() {
+    const list = [];
+    for (const client of this.#clients.values()) {
+      list.push({ id: client.id, address: client.address });
+    }
+    return list;
   }
 
   /**
@@ -253,40 +238,31 @@ class MqttServer extends Mod {
    * @returns {boolean} 是否在线
    */
   hasClient(client_id) {
-    return !!this.#clients.getById(client_id);
+    return this.#clients.has(client_id);
   }
 
   /**
-   * 挂载插件：调用 plugin.bind(this)，由插件自行向管道注册钩子；
-   * 如 MessagePlugin 挂载后接管 JSON-RPC 请求并应答到请求主题 + 后缀
-   * @param {Object} plugin 具备 bind(server) 方法的插件实例
-   * @returns {MqttServer} 当前实例
-   * @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 等钩子；
-   * 钩子产出 { topic, payload } 时由代理重新发布该消息
-   * @returns {Handle} 消息管道实例
+   * 绑定连接级选项，入站消息将作为 options 透传给事件
+   * @param {string} client_id 客户端 ID
+   * @param {Object|null} options 选项对象，null 时清空
+   * @returns {boolean} 是否设置成功（客户端不在线时失败）
    */
-  getHandle() {
-    return this.#handle;
+  setClientOptions(client_id, options) {
+    const client = this.#clients.get(client_id);
+    if (!client) return false;
+    client.options = options || null;
+    return true;
   }
 
   /**
-   * 获取实际监听地址
-   * @returns {Object|null} 监听地址信息，未启动时为 null
+   * 获取连接级选项（复制一份，避免事件管理器回写）
+   * @param {string} client_id 客户端 ID
+   * @returns {Object} 选项对象
    */
-  getAddress() {
-    const server = this.#server;
-    return server ? server.address() : null;
+  _clientOptions(client_id) {
+    const client = this.#clients.get(client_id);
+    if (!client || !client.options) return {};
+    return { ...client.options };
   }
 
   // ---------- broker 装配 ----------
@@ -295,50 +271,44 @@ class MqttServer extends Mod {
    * @returns {Promise<Object>} broker 实例
    */
   async _createBroker() {
-    const broker = await Aedes.createBroker({
+    return Aedes.createBroker({
+      ...this.config.options,
       authenticate: (client, username, password, done) => {
         this._authenticate(client, username, password, done);
       }
     });
-    return broker;
   }
 
   /**
-   * 把 broker 事件映射为模块事件，并维护连接注册表
+   * 绑定 broker 事件：维护连接表并把入站发布转交事件管理器
    * @param {Object} broker aedes broker 实例
    */
   _bindBrokerEvents(broker) {
-    broker.on('client', (client) => {
-      this.#clients.delById(client.id);
-      this.#clients.add({
-        id: client.id,
-        name: client.id,
-        address: this._remoteAddress(client),
-        client
-      });
-      this._safeEmit('connection', this._clientInfo(client));
-    });
-    broker.on('clientDisconnect', (client) => {
-      const existed = this.#clients.delById(client.id);
-      if (existed) this._safeEmit('close', client.id);
-    });
+    broker.on('client', (client) => this._registerClient(client));
+    broker.on('clientDisconnect', (client) => this.#clients.delete(client.id));
     broker.on('publish', (packet, client) => {
       if (!client) return;
-      this._handlePublish(client, packet).catch((err) => this._emitError(err));
-    });
-    broker.on('subscribe', (subscriptions, client) => {
-      const topics = subscriptions.map((item) => item.topic);
-      this._safeEmit('subscribe', client.id, topics);
-    });
-    broker.on('unsubscribe', (topics, client) => {
-      this._safeEmit('unsubscribe', client.id, topics);
+      this._handlePublish(client, packet);
     });
     broker.on('clientError', (client, err) => this._emitError(err));
     broker.on('connectionError', (client, err) => this._emitError(err));
   }
 
   /**
-   * 入站发布消息经管道处理：错误上抛，产出 { topic, payload } 时代理重发
+   * 登记在线客户端
+   * @param {Object} client aedes client 实例
+   */
+  _registerClient(client) {
+    this.#clients.set(client.id, {
+      id: client.id,
+      address: this._remoteAddress(client),
+      client,
+      options: null
+    });
+  }
+
+  /**
+   * 处理入站发布消息：交给事件管理器，返回发布描述时由代理重发
    * @param {Object} client aedes client 实例
    * @param {Object} packet aedes 发布报文
    * @returns {Promise<void>} 无返回值
@@ -351,17 +321,31 @@ class MqttServer extends Mod {
       qos: packet.qos,
       retain: packet.retain
     };
-    const ctx = { client_id: client.id };
-    const done = await this.#handle.run(ctx, params, this._clientOptions(client.id));
-    if (done.error) this._emitError(done.error);
-    if (this._isRepublish(done.result)) {
-      await this.publish(done.result.topic, done.result.payload, done.result);
+    const ctx = {
+      client_id: client.id,
+      topic: packet.topic,
+      qos: packet.qos,
+      retain: packet.retain,
+      packet,
+      client,
+      broker: this.#broker
+    };
+    const options = this._clientOptions(client.id);
+    try {
+      const result = await this.#events.run(packet.topic, params, ctx, options);
+      const error = ctx.error || options.error;
+      if (error) this._emitError(error);
+      if (this._isRepublish(result)) {
+        await this.publish(result.topic, result.payload, result);
+      }
+    } catch (err) {
+      this._emitError(err);
     }
   }
 
   /**
-   * 判断管道产出是否为待重发的发布描述（须含 topic 与 payload）
-   * @param {*} result 管道产出的结果
+   * 判断事件结果是否为待重发的发布描述（须含 topic 与 payload）
+   * @param {*} result 事件结果
    * @returns {boolean} 是否为发布描述
    */
   _isRepublish(result) {
@@ -398,8 +382,7 @@ class MqttServer extends Mod {
    * @returns {boolean} 是否放行
    */
   _checkAnonymous() {
-    const anonymous = this.config.allow_anonymous && !this.config.username;
-    return anonymous;
+    return !!(this.config.allow_anonymous && !this.config.username);
   }
 
   /**
@@ -437,24 +420,12 @@ class MqttServer extends Mod {
     return {
       cmd: 'publish',
       topic,
-      payload: Buffer.from(String(payload)),
+      payload: Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload)),
       qos: opts.qos || 0,
       retain: opts.retain || false
     };
   }
 
-  /**
-   * 提取客户端信息
-   * @param {Object} client aedes client 实例
-   * @returns {Object} 含 id 与 address 的信息
-   */
-  _clientInfo(client) {
-    return {
-      id: client.id,
-      address: this._remoteAddress(client)
-    };
-  }
-
   /**
    * 获取远端地址字符串
    * @param {Object} client aedes client 实例
@@ -485,11 +456,11 @@ class MqttServer extends Mod {
   }
 
   /**
-   * 断开全部客户端连接并清空注册表
+   * 断开全部客户端连接并清空连接表
    */
   _closeAllClients() {
-    for (const entry of this.#clients.list()) {
-      entry.client.close();
+    for (const client of this.#clients.values()) {
+      client.client.close();
     }
     this.#clients.clear();
   }
@@ -503,7 +474,7 @@ class MqttServer extends Mod {
     this.#server = null;
     if (!server) return Promise.resolve();
     return new Promise((resolve) => {
-      server.close(resolve);
+      server.close(() => resolve());
     });
   }
 
@@ -516,36 +487,11 @@ class MqttServer extends Mod {
     this.#broker = null;
     if (!broker) return Promise.resolve();
     return new Promise((resolve) => {
-      broker.close(resolve);
+      broker.close(() => resolve());
     });
   }
 
-  // ---------- 消息管道 ----------
-  /**
-   * 装配内置管道钩子：main 发 message 事件保持向后兼容
-   */
-  _initHandle() {
-    this.#handle.on('main', (ctx, params) => {
-      this._safeEmit('message', params.client_id, {
-        topic: params.topic,
-        payload: params.payload,
-        qos: params.qos,
-        retain: params.retain
-      });
-    }, 1000, 'emit_message');
-  }
-
   // ---------- 校验辅助 ----------
-  /**
-   * 校验顶层 config 中的服务器设置
-   * @returns {Promise<void>} 无返回值
-   * @throws {Error} 校验不通过时
-   */
-  async _validateConfig() {
-    const tip = await this._validate(this.config, SERVER_SCHEMA);
-    if (tip) throw new Error(`${this._label()} invalid config: ${tip}`);
-  }
-
   /**
    * 断言调用参数含 client_id
    * @param {Object} params 调用参数

package/package.json

@@ -1,25 +1,29 @@
 {
   "name": "mm_mqtt_server",
-  "version": "1.0.1",
-  "description": "MQTT 代理服务器入站端口模块，基于 aedes，继承 mm_corejs 的 Mod 基类，支持独立运行。",
+  "version": "2.0.0",
+  "description": "最薄的 MQTT 代理服务器入站适配器：消息直达 mm_event 事件管理器，不做路由与插件。",
   "keywords": [
     "超级美眉",
-    "入站端口",
+    "入站适配器",
     "mm_mod",
-    "mm_in_port",
+    "mm_adapter",
+    "mm_in_adapter",
     "mm_receiver",
     "mqtt",
     "broker",
     "aedes",
     "server"
   ],
+  "layer": "adapter",
+  "group": "in_adapter",
   "license": "ISC",
   "author": "qww",
   "type": "commonjs",
   "main": "index.js",
   "files": [
     "index.js",
-    "lib"
+    "lib",
+    "example"
   ],
   "engines": {
     "node": ">=22.5.0"
@@ -35,13 +39,15 @@
   "scripts": {
     "start": "node example/demo.js",
     "demo": "node example/demo.js",
-    "test": "jest --coverage"
+    "test": "node --test \"test/*.test.js\""
   },
   "dependencies": {
     "aedes": "^1.2.0",
-    "mm_corejs": "^1.1.0"
+    "mm_corejs": "^1.1.4",
+    "mm_event": "^2.2.2",
+    "mm_mod": "^1.0.1"
   },
   "devDependencies": {
-    "jest": "^30.5.2"
+    "mqtt-packet": "^9.0.2"
   }
 }

package/lib/message.js

@@ -1,197 +0,0 @@
-'use strict';
-
-const { JsonRpc } = require('mm_corejs');
-
-/**
- * 默认应答主题后缀
- */
-const DEFAULT_REPLY_SUFFIX = '/response';
-
-/**
- * 默认主动推送主题前缀（完整主题为 前缀/客户端ID）
- */
-const DEFAULT_PUSH_PREFIX = 'rpc/push';
-
-/**
- * 默认反向调用主题前缀（完整主题为 前缀/客户端ID，客户端订阅后接收调用请求）
- */
-const DEFAULT_CALL_PREFIX = 'rpc/call';
-
-/**
- * MessagePlugin —— JSON-RPC 2.0 消息插件（mm_mqtt_server 的可选业务组件）。
- *
- * 职责：
- *   1. 方法表：内部持有 JsonRpc 核心，addMethod / delMethod / listMethods 登记可调用方法；
- *   2. 管道挂载：bind(mqtt) 后向消息管道注册 main 钩子 "json_rpc"（sort 100，
- *      先于内置 emit_message 执行），命中 JSON-RPC 请求时产出重发描述
- *      { topic: 请求主题 + reply_suffix, payload: 响应 JSON }，由代理发布应答；
- *   3. 通知回推：通知（无 id）处理函数返回非 undefined 结果时，产出服务器发起的
- *      通知对象 { jsonrpc, method, params: result } 并发布到应答主题；无结果或出错时
- *      不产出；非 JSON-RPC 消息（解析失败、缺 jsonrpc 字段）透传，控制权交还管道；
- *   4. 主动推送：push(client_id, data, options) 发布到 options.topic
- *      （缺省为 push_prefix/client_id），处理函数或客户端可在任意时刻
- *      （如异步任务完成后）向订阅该主题的客户端回推结果；
- *   5. 反向调用：call(client_id, method, params, options) 发布 JSON-RPC 请求到
- *      options.topic（缺省为 call_prefix/client_id）并等待反馈；客户端把响应
- *      （含 result/error、无 method）发布回 RPC 服务主题，入站时被优先识别并结算；
- *   6. 无回环：代理重发的应答 client 为空，不进入消息管道。
- *
- * 用法：
- *   const mqtt = new MqttServer({ name: 'mqtt_server', port: 1883 }, server);
- *   const rpc = new MessagePlugin({ reply_suffix: '/response', push_prefix: 'rpc/push' });
- *   mqtt.use(rpc);
- *   rpc.addMethod('echo', (params) => params);
- *   await mqtt.init();
- *   await mqtt.start();
- */
-class MessagePlugin {
-  /**
-   * JSON-RPC 协议核心
-   */
-  #rpc = new JsonRpc();
-
-  /**
-   * 已挂载的 MqttServer 实例，未挂载时为 null
-   */
-  #server = null;
-
-  /**
-   * 应答策略配置
-   */
-  #config = {
-    reply_suffix: DEFAULT_REPLY_SUFFIX,
-    push_prefix: DEFAULT_PUSH_PREFIX,
-    call_prefix: DEFAULT_CALL_PREFIX,
-    qos: 0,
-    retain: false
-  };
-
-  /**
-   * 构造函数
-   * @param {Object} [config] 应答策略配置，含 reply_suffix / push_prefix / call_prefix / qos / retain
-   */
-  constructor(config = {}) {
-    this.#config = { ...this.#config, ...config };
-  }
-
-  /**
-   * 挂载到 MqttServer 的消息管道，注册内置 main 钩子
-   * @param {Object} server 具备 getHandle() 的 MqttServer 实例
-   * @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} 是否已挂载到 MqttServer
-   */
-  isBound() {
-    return this.#server !== null;
-  }
-
-  /**
-   * 登记 RPC 方法
-   * @param {string} name 方法名
-   * @param {Function} handler 处理函数，签名 handler(params, extra, options)，extra 含 client_id 与 topic，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);
-  }
-
-  /**
-   * 主动推送：发布数据到指定主题（缺省为 push_prefix/client_id，客户端订阅后接收）
-   * @param {string} client_id 目标客户端 ID，用于组装缺省主题
-   * @param {string|Object} data 待推送数据，对象时 JSON 序列化
-   * @param {Object} [options] 推送选项，含 topic（覆盖缺省主题）
-   * @returns {Promise<boolean>} 是否发布成功
-   * @throws {Error} 插件尚未挂载到服务器时
-   */
-  push(client_id, data, options = {}) {
-    if (!this.#server) throw new Error('[MessagePlugin] not bound to a server');
-    const config = this.#config;
-    const topic = options.topic || `${config.push_prefix}/${client_id}`;
-    const payload = typeof data === 'string' ? data : JSON.stringify(data);
-    return this.#server.publish(topic, payload, { qos: config.qos, retain: config.retain });
-  }
-
-  /**
-   * 实时调用客户端方法：发布 JSON-RPC 请求并等待客户端反馈 result
-   * @param {string} client_id 目标客户端 ID，用于组装缺省调用主题
-   * @param {string} method 客户端方法名
-   * @param {*} [params] 调用参数
-   * @param {Object} [options] 选项，含 topic（覆盖缺省调用主题）与 timeout_ms（缺省 30000）
-   * @returns {Promise<*>} 客户端反馈的 result；错误响应、送达失败或超时时 reject
-   * @throws {Error} 插件尚未挂载到服务器时
-   */
-  call(client_id, method, params, options = {}) {
-    if (!this.#server) throw new Error('[MessagePlugin] not bound to a server');
-    const config = this.#config;
-    const topic = options.topic || `${config.call_prefix}/${client_id}`;
-    /** 发送函数：把调用请求发布到调用主题 */
-    const send = (request) => this.#server.publish(topic, JSON.stringify(request), { qos: config.qos, retain: false });
-    return this.#rpc.call(send, method, params, options);
-  }
-
-  /**
-   * 内置 main 钩子逻辑：优先识别客户端反馈，其次执行 RPC 请求并产出应答重发描述
-   * @param {Object} ctx 执行上下文
-   * @param {Object} params 消息参数，含 client_id / topic / payload
-   * @param {Object} [options] 管道请求选项（连接级，如 user_id / device_id / agent_id），透传给处理函数
-   * @returns {Promise<Object|undefined>} 重发描述 { topic, payload, qos, retain }；反馈、透传与无结果通知时为 undefined
-   */
-  async _execute(ctx, params, options) {
-    if (this.#rpc.acceptResponse(params.payload)) return undefined;
-    const extra = { client_id: params.client_id, topic: params.topic };
-    const response = await this.#rpc.handle(params.payload, extra, options);
-    if (response === undefined) return undefined;
-    return this._buildReply(params.topic, response);
-  }
-
-  /**
-   * 组装应答重发描述
-   * @param {string} topic 请求主题
-   * @param {Object} response 响应对象
-   * @returns {Object} 重发描述，payload 为响应 JSON 字符串
-   */
-  _buildReply(topic, response) {
-    const config = this.#config;
-    return {
-      topic: `${topic}${config.reply_suffix}`,
-      payload: JSON.stringify(response),
-      qos: config.qos,
-      retain: config.retain
-    };
-  }
-}
-
-module.exports = MessagePlugin;