mm_web_server 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,190 @@
+# mm_web
+
+HTTP Web 服务器入站端口模块。继承 [mm_corejs](https://gitee.com/qiuwenwu91/mm_corejs) 的 `Mod` 基类，只实现**传输机制**（监听、请求解析、管道执行、统一应答），路由、跨域、身份提取等**策略**由可选插件挂载，可脱离完整框架独立运行。
+
+- 入口：`index.js`（CommonJS）
+- 导出：`WebServer`（传输层）、`RoutePlugin`（路由）、`CorsPlugin`（跨域）、`IdentityPlugin`（身份提取）
+- 运行时依赖：`mm_corejs`
+- 测试覆盖率：100%（`jest.config.js` 四项阈值）
+
+## 特性
+
+- **纯传输层**：零第三方依赖，基于 Node 内置 `http`；不感知路由与跨域约定，策略全部插件化。
+- **请求管道**：每个请求（含 `OPTIONS`）经 `Handle` 的 `before / check / main / render` 阶段处理，内置 `after` 钩子统一写出响应；`getHandle()` 可注册日志（before）、鉴权（check）、接管路由（main + `end`）等钩子。
+- **请求解析**：URL / 查询串 / 请求体（JSON、表单、原文）自动解析，`body_limit` 作为安全边界。
+- **兜底行为**：管道无人产出结果时触发 `request` 事件，事件内也未接管则返回 404。
+- **可选插件**：`RoutePlugin`（Store 路由表 + `dispatch_route` 主钩子）、`CorsPlugin`（`before` 钩子设跨域头并短路预检）、`IdentityPlugin`（`before` 钩子按请求头填充请求选项）。
+- **选项透传**：每个请求携带独立的可变 `options` 对象进入管道，随第三参透传给钩子与路由处理函数，适配多用户 / 多设备 / 多智能体场景。
+
+## 安装
+
+```bash
+npm install mm_web_server
+```
+
+## 环境要求
+
+- Node.js >= 22.5.0
+- 模块规范：CommonJS
+
+## 快速开始
+
+```js
+'use strict';
+
+const { WebServer, RoutePlugin, CorsPlugin, IdentityPlugin } = require('mm_web_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 web = new WebServer(server, { name: 'web', host: '127.0.0.1', port: 8080 });
+
+web.use(new CorsPlugin({ origin: '*', max_age: 600 }));
+web.use(new IdentityPlugin());
+
+const router = new RoutePlugin();
+web.use(router);
+router.addRoute('GET', '/hello', (ctx, params) => ({ hello: params.query.name || 'world' }));
+router.addRoute('POST', '/echo', (ctx, params) => ({ echo: params.body }));
+
+// 鉴权：check 阶段产出即短路整条管道
+web.getHandle().on('check', (ctx, params) => {
+  if (!params.path.startsWith('/secure')) return;
+  if (params.headers['x-token'] === 'secret') return;
+  return { status: 401, body: { error: 'unauthorized' } };
+}, 100, 'auth');
+
+web.on('request', (params) => console.log('未命中路由:', params.method, params.path));
+web.on('response', (status) => console.log('响应:', status));
+web.on('error', (err) => console.error(err.message));
+
+await web.init();
+await web.start();
+
+console.log(await web.run({}, { action: 'status' }));
+
+await web.stop();
+await web.dispose();
+```
+
+## 服务器配置（config）
+
+顶层 `config` 字段即服务器设置，`init` 阶段统一校验。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | `'web'` | 模块名称（必填） |
+| `host` | string | `'0.0.0.0'` | 监听地址 |
+| `port` | integer | `8080` | 监听端口（1-65535） |
+| `body_limit` | integer | `1048576` | 请求体字节上限，超限抛错并销毁连接 |
+
+## API
+
+### WebServer
+
+| 成员 | 说明 |
+| --- | --- |
+| `run(ctx, params)` | 主动操作入口，`params.action` 目前仅 `status`（返回 `{ running, address }`） |
+| `use(plugin)` | 挂载插件（需实现 `bind(web)`） |
+| `getHandle()` | 请求管道，注册 `before / check / main / render` 等钩子 |
+| `getAddress()` | 实际监听地址，未启动为 `null` |
+
+### 请求参数（params）
+
+管道与路由处理函数第二参 `params`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `method` | 请求方法 |
+| `path` | 路径（不含查询串） |
+| `query` | 查询串解析结果（对象） |
+| `headers` | 请求头 |
+| `body` | 请求体：JSON / 表单自动解析，其余为原文，无请求体为 `null` |
+| `remote` | 来源地址 |
+
+### 响应写法
+
+管道任一阶段产出的 `result` 由内置 `after` 钩子统一写出：
+
+| `result` 形态 | 响应 |
+| --- | --- |
+| `{ status, body }` | 指定状态码；`body` 为字符串按 `text/plain`，对象按 `application/json`；`body` 缺省/为 `null` 时返回空响应（未给 `status` 则 204） |
+| 字符串 | `200` + `text/plain` |
+| 其余值 | `200` + `application/json` |
+| 无人产出 | 触发 `request` 事件；`ctx.handled` 未置真则 `404 { error: 'not found' }` |
+| 钩子抛错 | `500 { error: 错误信息 }`，并经 `error` 事件通知 |
+
+### 事件
+
+| 事件 | 参数 | 触发时机 |
+| --- | --- | --- |
+| `request` | `(params, ctx)` | 内置兜底 `main` 钩子（sort 9999）触发；在事件内自行写响应并置 `ctx.handled = true` 即接管 |
+| `response` | `(status, payload)` | 内置 `after` 钩子写出 JSON / 文本响应后 |
+| `error` | `(err)` | 管道钩子错误、请求体超限、`clientError` |
+
+### 管道顺序
+
+```
+IdentityPlugin.before(50) → CorsPlugin.before(100) → 用户钩子 → RoutePlugin.main(1000, end)
+→ 内置兜底 main(9999, end) → after(1000) 统一写响应
+```
+
+## 插件
+
+### RoutePlugin
+
+```js
+const router = new RoutePlugin();
+web.use(router);
+router.addRoute('GET', '/hello', (ctx, params, options) => ({ hello: params.query.name }));
+router.addRoute('*', '/any', () => ({ ok: true })); // '*' 通配方法
+```
+
+| 成员 | 说明 |
+| --- | --- |
+| `addRoute(method, path, handler)` | 注册路由（同 `method + path` 重复注册覆盖），处理函数签名 `(ctx, params, options)` |
+| `delRoute(method, path)` | 删除路由 |
+| `listRoutes(query)` | 路由列表（`{ method, path }`），支持 Store 条件 / 分页 |
+| `bind(web)` / `isBound()` | 挂载与状态查询 |
+
+匹配规则：先精确方法，再 `'*'` 通配；未命中返回 `undefined` 放行给后续钩子与兜底逻辑。
+
+### CorsPlugin
+
+```js
+web.use(new CorsPlugin({ origin: '*', methods: ['GET', 'POST'], headers: 'content-type', max_age: 600, credentials: false }));
+```
+
+`before` 钩子（sort 100）为每个响应设置 `access-control-*` 头；`OPTIONS` 请求短路返回 `204`。不挂载即无跨域头。
+
+### IdentityPlugin
+
+```js
+web.use(new IdentityPlugin());                                        // x-user-id / x-device-id / x-agent-id
+web.use(new IdentityPlugin({ headers: { 'x-tenant': 'tenant_id' } })); // 自定义映射
+```
+
+`before` 钩子（sort 50，先于 CORS 与鉴权）把请求头中的身份原地写入管道 `options`，后续钩子与路由处理函数经第三参读取。不挂载即无身份约定。
+
+## 示例
+
+```bash
+npm run demo   # 启动 Web 演示服务器（127.0.0.1:8080），见 example/demo.js
+```
+
+## 测试
+
+```bash
+npm test       # jest --coverage，四项覆盖率阈值均为 100%
+```
+
+## 许可证
+
+ISC

package/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const WebServer = require('./lib/web');
+const RoutePlugin = require('./lib/route');
+const CorsPlugin = require('./lib/cors');
+const IdentityPlugin = require('./lib/identity');
+
+module.exports = {
+  WebServer,
+  RoutePlugin,
+  CorsPlugin,
+  IdentityPlugin
+};

package/lib/cors.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * 默认允许的跨域请求方法集合
+ */
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+
+/**
+ * CorsPlugin —— CORS 跨域策略插件（mm_web 的可选业务组件）。
+ *
+ * 职责：
+ *   1. 响应头：bind(web) 后向 WebServer 的请求管道注册 before 钩子 "cors"，
+ *      为每个响应设置 access-control-* 头（在 check/main 短路前已生效）；
+ *   2. 预检短路：OPTIONS 请求由 before 钩子产出 { status: 204 } 短路整条管道，
+ *      响应由 WebServer 内置 after 钩子统一写出；
+ *   3. 不挂载即无 CORS：传输层不感知跨域策略。
+ *
+ * 用法：
+ *   const web = new WebServer(server, { name: 'web', port: 8080 });
+ *   web.use(new CorsPlugin({ origin: '*', max_age: 600 }));
+ *   await web.init();
+ *   await web.start();
+ */
+class CorsPlugin {
+  /**
+   * 跨域策略配置
+   */
+  #config = {
+    origin: '*',
+    methods: DEFAULT_METHODS,
+    headers: 'content-type',
+    max_age: 600,
+    credentials: false
+  };
+
+  /**
+   * 已挂载的 WebServer 实例，未挂载时为 null
+   */
+  #web = null;
+
+  /**
+   * 构造函数
+   * @param {Object} [config] 跨域策略配置，含 origin / methods / headers / max_age / credentials
+   */
+  constructor(config = {}) {
+    this.#config = { ...this.#config, ...config };
+  }
+
+  /**
+   * 挂载到 WebServer 的请求管道，注册 before 钩子
+   * @param {Object} web 具备 getHandle() 的 WebServer 实例
+   * @returns {CorsPlugin} 当前实例
+   * @throws {TypeError} web 不具备 getHandle 方法时
+   */
+  bind(web) {
+    if (!web || typeof web.getHandle !== 'function') {
+      throw new TypeError('[CorsPlugin] web must provide getHandle()');
+    }
+    this.#web = web;
+    web.getHandle().on('before', (ctx, params) => {
+      return this._handle(ctx, params);
+    }, 100, 'cors');
+    return this;
+  }
+
+  /**
+   * 判断是否已挂载
+   * @returns {boolean} 是否已挂载到 WebServer
+   */
+  isBound() {
+    return this.#web !== null;
+  }
+
+  /**
+   * 内置 before 钩子逻辑：设置跨域响应头；OPTIONS 预检短路返回 204
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 请求参数
+   * @returns {Object|undefined} 预检请求返回 204 描述对象；其余请求返回 undefined 放行
+   */
+  _handle(ctx, params) {
+    this._setHeaders(ctx.res);
+    if (params.method !== 'OPTIONS') return;
+    return { status: 204 };
+  }
+
+  /**
+   * 按配置设置 access-control-* 响应头
+   * @param {Object} res 响应对象
+   */
+  _setHeaders(res) {
+    const config = this.#config;
+    res.setHeader('access-control-allow-origin', config.origin);
+    res.setHeader('access-control-allow-methods', config.methods.join(', '));
+    res.setHeader('access-control-allow-headers', config.headers);
+    res.setHeader('access-control-max-age', String(config.max_age));
+    if (config.credentials) {
+      res.setHeader('access-control-allow-credentials', 'true');
+    }
+  }
+}
+
+module.exports = CorsPlugin;

package/lib/identity.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * 缺省的身份请求头到请求选项字段的映射
+ */
+const DEFAULT_HEADERS = {
+  'x-user-id': 'user_id',
+  'x-device-id': 'device_id',
+  'x-agent-id': 'agent_id'
+};
+
+/**
+ * 身份提取 before 钩子的排序（先于 CorsPlugin 的 100，保证鉴权钩子可读身份）
+ */
+const HOOK_SORT = 50;
+
+/**
+ * IdentityPlugin —— 请求身份提取插件（mm_web 的可选业务组件）。
+ *
+ * 职责：
+ *   1. 身份映射：按 headers 配置（请求头 → options 字段）从请求头提取调用方身份；
+ *   2. 选项写入：bind(web) 后向请求管道注册 before 钩子 "identity"（sort 50），
+ *      把提取结果原地写入管道 options，后续钩子与路由处理函数经第三参读取；
+ *   3. 不挂载即无身份：传输层不感知身份请求头约定，映射可由使用方自定义。
+ *
+ * 用法：
+ *   const web = new WebServer(server, { name: 'web', port: 8080 });
+ *   web.use(new IdentityPlugin());
+ *   web.use(new IdentityPlugin({ headers: { 'x-tenant': 'tenant_id' } }));
+ *   router.addRoute('GET', '/whoami', (ctx, params, options) => options);
+ *   await web.init();
+ *   await web.start();
+ */
+class IdentityPlugin {
+  /**
+   * 身份映射配置：请求头名 → options 字段名
+   */
+  #headers = DEFAULT_HEADERS;
+
+  /**
+   * 已挂载的 WebServer 实例，未挂载时为 null
+   */
+  #web = null;
+
+  /**
+   * 构造函数
+   * @param {Object} [config] 配置，含 headers（请求头 → options 字段映射，缺省用 DEFAULT_HEADERS）
+   */
+  constructor(config = {}) {
+    if (config.headers) this.#headers = { ...config.headers };
+  }
+
+  /**
+   * 挂载到 WebServer 的请求管道，注册身份提取 before 钩子
+   * @param {Object} web 具备 getHandle() 的 WebServer 实例
+   * @returns {IdentityPlugin} 当前实例
+   * @throws {TypeError} web 不具备 getHandle 方法时
+   */
+  bind(web) {
+    if (!web || typeof web.getHandle !== 'function') {
+      throw new TypeError('[IdentityPlugin] web must provide getHandle()');
+    }
+    this.#web = web;
+    web.getHandle().on('before', (ctx, params, options) => {
+      this._extract(params, options);
+    }, HOOK_SORT, 'identity');
+    return this;
+  }
+
+  /**
+   * 判断是否已挂载
+   * @returns {boolean} 是否已挂载到 WebServer
+   */
+  isBound() {
+    return this.#web !== null;
+  }
+
+  /**
+   * 按映射从请求头提取身份，原地写入管道 options（不返回值，避免 before 短路）
+   * @param {Object} params 请求参数，含 headers
+   * @param {Object} options 请求选项对象（管道同一引用，后续钩子与处理函数可见）
+   */
+  _extract(params, options) {
+    const headers = params.headers;
+    const names = Object.keys(this.#headers);
+    for (const name of names) {
+      const header_value = headers[name];
+      if (header_value) options[this.#headers[name]] = header_value;
+    }
+  }
+}
+
+module.exports = IdentityPlugin;

package/lib/route.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const { Store } = require('mm_corejs');
+
+/**
+ * RoutePlugin —— HTTP 路由插件（mm_web 的可选业务组件）。
+ *
+ * 职责：
+ *   1. 路由表：#routes 使用 Store 存储（主键 "METHOD /path"），支持条件查询与分页；
+ *   2. 管道挂载：bind(web) 后向 WebServer 的请求管道注册内置 main 钩子
+ *      "dispatch_route"（sort 1000、end 标记），命中路由时以处理函数返回值作为响应；
+ *   3. 未命中放行：无匹配路由时钩子返回 undefined，控制权交还管道
+ *      （由 WebServer 的 request 事件兜底或后续钩子接管）；
+ *   4. 选项透传：管道第三参 options（身份请求头提取的请求选项）
+ *      原样透传给路由处理函数第三参。
+ *
+ * 用法：
+ *   const web = new WebServer(server, { name: 'web', port: 8080 });
+ *   const router = new RoutePlugin();
+ *   web.use(router);
+ *   router.addRoute('GET', '/hello', (ctx, params, options) => ({ hello: params.query.name }));
+ *   await web.init();
+ *   await web.start();
+ */
+class RoutePlugin {
+  /**
+   * 路由表：Store 存储，主键 "METHOD /path"、名称字段 path
+   */
+  #routes = new Store({ key: 'id', name: 'path' });
+
+  /**
+   * 已挂载的 WebServer 实例，未挂载时为 null
+   */
+  #web = null;
+
+  /**
+   * 挂载到 WebServer 的请求管道，注册内置路由分发钩子
+   * @param {Object} web 具备 getHandle() 的 WebServer 实例
+   * @returns {RoutePlugin} 当前实例
+   * @throws {TypeError} web 不具备 getHandle 方法时
+   */
+  bind(web) {
+    if (!web || typeof web.getHandle !== 'function') {
+      throw new TypeError('[RoutePlugin] web must provide getHandle()');
+    }
+    this.#web = web;
+    web.getHandle().on('main', (ctx, params, options) => {
+      return this._dispatch(ctx, params, options);
+    }, 1000, 'dispatch_route', { end: true });
+    return this;
+  }
+
+  /**
+   * 判断是否已挂载
+   * @returns {boolean} 是否已挂载到 WebServer
+   */
+  isBound() {
+    return this.#web !== null;
+  }
+
+  /**
+   * 注册路由（同 method + path 重复注册时覆盖）
+   * @param {string} method 请求方法，'*' 表示通配
+   * @param {string} path 路径，以 / 开头
+   * @param {Function} handler 处理函数，签名 handler(ctx, params, options)，返回值决定响应；options 为请求选项（身份请求头提取的 user_id / device_id / agent_id 等）
+   * @returns {RoutePlugin} 当前实例
+   * @throws {TypeError} handler 不是函数时
+   */
+  addRoute(method, path, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('[RoutePlugin] handler must be a function');
+    }
+    const key = this._routeKey(method, path);
+    this.#routes.delById(key);
+    this.#routes.add({ id: key, name: path, method, path, handler });
+    return this;
+  }
+
+  /**
+   * 删除路由
+   * @param {string} method 请求方法
+   * @param {string} path 路径
+   * @returns {boolean} 是否删除成功
+   */
+  delRoute(method, path) {
+    const key = this._routeKey(method, path);
+    return this.#routes.delById(key);
+  }
+
+  /**
+   * 列出路由（支持 Store 条件查询与分页）
+   * @param {Object} [query] 查询条件，缺省时列出全部
+   * @returns {Array<Object>} 路由列表，含 method 与 path
+   */
+  listRoutes(query) {
+    return this.#routes.list(query).map((route) => ({ method: route.method, path: route.path }));
+  }
+
+  /**
+   * 内置 main 钩子逻辑：命中路由调用处理函数，未命中返回 undefined 放行
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 请求参数
+   * @param {Object} options 请求选项，透传给处理函数第三参
+   * @returns {Promise<*>} 处理函数返回值（作为管道 result）；未命中时为 undefined
+   */
+  async _dispatch(ctx, params, options) {
+    const route = this._matchRoute(params.method, params.path);
+    if (!route) return undefined;
+    return await route.handler(ctx, params, options);
+  }
+
+  /**
+   * 匹配路由：先精确方法，再 '*' 通配
+   * @param {string} method 请求方法
+   * @param {string} path 请求路径
+   * @returns {Object|null} 命中的路由项（含 handler），未命中返回 null
+   */
+  _matchRoute(method, path) {
+    const exact = this.#routes.getById(this._routeKey(method, path));
+    if (exact) return exact;
+    const wildcard = this.#routes.getById(this._routeKey('*', path));
+    return wildcard || null;
+  }
+
+  /**
+   * 组装路由表键
+   * @param {string} method 请求方法
+   * @param {string} path 请求路径
+   * @returns {string} 形如 "GET /hello" 的键
+   */
+  _routeKey(method, path) {
+    return `${method} ${path}`;
+  }
+}
+
+module.exports = RoutePlugin;

package/lib/web.js

@@ -0,0 +1,445 @@
+'use strict';
+
+const http = require('http');
+const { URL, URLSearchParams } = require('url');
+const { Mod, Handle } = require('mm_corejs');
+
+/**
+ * 服务器设置校验 schema（校验对象为顶层 config）
+ */
+const SERVER_SCHEMA = {
+  type: 'object',
+  properties: {
+    host: { type: 'string', min_length: 1 },
+    port: { type: 'integer', minimum: 1, maximum: 65535 },
+    body_limit: { type: 'integer', minimum: 1 }
+  }
+};
+
+/**
+ * WebServer —— HTTP Web 传输层（入站端口模块）。
+ *
+ * 继承 mm_corejs 的 Mod：生命周期由 Lifecycle 模板方法驱动，
+ * 调用参数校验由 config.params 声明式定义；
+ * 服务器设置（host / port / body_limit）为顶层 config 字段，
+ * 在 onInit 阶段按 SERVER_SCHEMA 统一校验。
+ *
+ * 职责（仅传输机制，路由 / CORS 等策略由插件挂载）：
+ *   1. 监听：onStart 创建 http.Server 并按 host / port 监听；
+ *   2. 请求解析：URL、查询串、请求体读取与解析（body_limit 为安全边界）；
+ *   3. 请求管道：每个请求（含 OPTIONS）经 Handle 的 before/check/main/render
+ *      阶段处理，内置 after 钩子统一写响应（result 为 {status,body} 描述对象、
+ *      字符串或 JSON）；getHandle() 可注册鉴权（check）、日志（before）等钩子；
+ *   4. 插件挂载：use(plugin) 调用 plugin.bind(this)，
+ *      如 RoutePlugin 注册 main 钩子做路由分发、CorsPlugin 注册 before 钩子
+ *      设跨域头并短路 OPTIONS 预检、IdentityPlugin 注册 before 钩子提取身份；
+ *   5. 兜底行为：管道无人产出时触发 request 事件，仍无人接管则返回 404；
+ *   6. 主动操作：run(ctx, params) 按 params.action 派发 status；
+ *   7. 请求选项：每个请求以独立的可变 options 对象进入管道，随第三参透传给
+ *      钩子与路由处理函数；身份提取等填充逻辑由插件承担（如 IdentityPlugin
+ *      的 before 钩子按请求头写入 user_id / device_id / agent_id）。
+ *
+ * 用法：
+ *   const web = new WebServer(server, { name: 'web', port: 8080 });
+ *   web.use(new CorsPlugin({ origin: '*' }));
+ *   web.use(new IdentityPlugin());
+ *   const router = new RoutePlugin();
+ *   web.use(router);
+ *   router.addRoute('GET', '/hello', (ctx, params, options) => ({ hello: params.query.name || 'world' }));
+ *   web.getHandle().on('check', (ctx, params) => {
+ *     if (params.headers['x-token'] !== 'secret') return { status: 401, body: { error: 'unauthorized' } };
+ *   }, 100, 'auth');
+ *   await web.init();
+ *   await web.start();
+ *   await web.run({}, { action: 'status' });
+ */
+class WebServer extends Mod {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'web',
+    title: 'Web服务器模块',
+    description: 'HTTP Web 传输层：解析请求、执行处理管道并统一应答，路由与跨域等策略由插件挂载',
+    version: '1.0.0',
+    host: '0.0.0.0',
+    port: 8080,
+    body_limit: 1048576,
+    options: {},
+    params: {
+      type: 'object',
+      required: ['action'],
+      properties: {
+        action: { type: 'string', enum: ['status'] }
+      }
+    }
+  };
+
+  /**
+   * 底层 HTTP 服务器实例
+   */
+  #server = null;
+
+  /**
+   * 请求处理管道（before/check/main/render/error/success/after）
+   */
+  #handle = new Handle();
+
+  // ---------- 生命周期钩子 ----------
+  /**
+   * 初始化钩子：校验服务器设置并装配请求管道
+   */
+  async onInit() {
+    await this._validateConfig();
+    this._initHandle();
+  }
+
+  /**
+   * 启动钩子：创建 HTTP 服务器并开始监听
+   */
+  async onStart() {
+    const server = http.createServer((req, res) => {
+      this._handleRequest(req, res).catch((err) => this._emitError(err));
+    });
+    this.#server = server;
+    await this._listen(server);
+    server.on('clientError', (err) => this._emitError(err));
+  }
+
+  /**
+   * 停止钩子：关闭服务器并断开残留连接
+   */
+  async onStop() {
+    await this._closeServer();
+  }
+
+  // ---------- 执行入口 ----------
+  /**
+   * 模块主逻辑：按 action 派发传输层操作
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 调用参数，含 action 及操作所需字段
+   * @param {Object} options 合并后的选项
+   * @returns {Promise<Object>} 操作结果
+   */
+  async main(ctx, params, options) {
+    return this._actionStatus();
+  }
+
+  /**
+   * 执行状态查询操作
+   * @returns {Object} 操作结果，含运行状态与监听地址
+   */
+  _actionStatus() {
+    const address = this.getAddress();
+    return {
+      action: 'status',
+      running: this.isRunning(),
+      address: address ? `${address.address}:${address.port}` : null
+    };
+  }
+
+  // ---------- 插件挂载 ----------
+  /**
+   * 挂载插件：调用 plugin.bind(this)，由插件自行向管道注册钩子；
+   * 如 RoutePlugin 挂载后接管路由分发、IdentityPlugin 挂载后填充请求 options
+   * @param {Object} plugin 具备 bind(web) 方法的插件实例
+   * @returns {WebServer} 当前实例
+   * @throws {TypeError} plugin 不具备 bind 方法时
+   */
+  use(plugin) {
+    if (!plugin || typeof plugin.bind !== 'function') {
+      throw new TypeError(`${this._label()} plugin must provide bind()`);
+    }
+    plugin.bind(this);
+    return this;
+  }
+
+  /**
+   * 获取请求处理管道，供外部注册 before/check/main/render 等钩子；
+   * main 钩子产出 result 时接管响应（建议以 { end: true } 登记跳过后续处理器）
+   * @returns {Handle} 请求管道实例
+   */
+  getHandle() {
+    return this.#handle;
+  }
+
+  /**
+   * 获取实际监听地址
+   * @returns {Object|null} 监听地址信息，未启动时为 null
+   */
+  getAddress() {
+    const server = this.#server;
+    return server ? server.address() : null;
+  }
+
+  // ---------- 请求处理 ----------
+  /**
+   * 处理单个 HTTP 请求：解析后统一交由管道分发
+   * @param {Object} req 请求对象
+   * @param {Object} res 响应对象
+   * @returns {Promise<void>} 无返回值
+   */
+  async _handleRequest(req, res) {
+    const parsed = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const body = await this._readBody(req);
+    const params = this._buildParams(req, parsed, body);
+    const ctx = this._buildCtx(req, res, parsed, params);
+    await this._dispatch(ctx, params, {});
+  }
+
+  /**
+   * 分发请求：整条请求经 Handle 管道处理，响应由内置 after 钩子统一写出
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 请求参数
+   * @param {Object} options 请求选项（管道同一引用，插件钩子可原地填充，透传给后续钩子与路由处理函数）
+   * @returns {Promise<void>} 无返回值
+   */
+  async _dispatch(ctx, params, options) {
+    const done = await this.#handle.run(ctx, params, options);
+    if (done.error) this._emitError(done.error);
+  }
+
+  /**
+   * 构建调用方参数对象
+   * @param {Object} req 请求对象
+   * @param {Object} parsed 解析后的 URL
+   * @param {string} body 请求体原文
+   * @returns {Object} 含 method / path / query / headers / body / remote 的参数
+   */
+  _buildParams(req, parsed, body) {
+    return {
+      method: req.method,
+      path: parsed.pathname,
+      query: Object.fromEntries(parsed.searchParams),
+      headers: req.headers,
+      body: this._parseBody(body, req.headers['content-type']),
+      remote: req.socket.remoteAddress
+    };
+  }
+
+  /**
+   * 构建处理函数上下文
+   * @param {Object} req 请求对象
+   * @param {Object} res 响应对象
+   * @param {Object} parsed 解析后的 URL
+   * @param {Object} params 调用方参数
+   * @returns {Object} 上下文对象
+   */
+  _buildCtx(req, res, parsed, params) {
+    return {
+      req,
+      res,
+      url: parsed.href,
+      params,
+      handled: false
+    };
+  }
+
+  /**
+   * 解析请求体：JSON 优先，表单其次，其余保持原文
+   * @param {string} body 请求体原文
+   * @param {string} contentType 内容类型头
+   * @returns {*} 解析结果
+   */
+  _parseBody(body, contentType) {
+    if (!body) return null;
+    if (contentType && contentType.includes('application/json')) {
+      return this._parseJson(body);
+    }
+    if (contentType && contentType.includes('application/x-www-form-urlencoded')) {
+      return Object.fromEntries(new URLSearchParams(body));
+    }
+    return body;
+  }
+
+  /**
+   * 尝试将文本解析为 JSON
+   * @param {string} text 文本内容
+   * @returns {Object|string} 解析结果，失败时返回原文
+   */
+  _parseJson(text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  /**
+   * 读取请求体全文
+   * @param {Object} req 请求对象
+   * @returns {Promise<string>} 请求体文本
+   */
+  _readBody(req) {
+    const limit = this.config.body_limit;
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      let length = 0;
+      req.on('data', (chunk) => {
+        length += chunk.length;
+        if (length > limit) {
+          reject(new Error(`${this._label()} body too large`));
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+      req.on('error', reject);
+    });
+  }
+
+  // ---------- 请求管道 ----------
+  /**
+   * 装配内置管道钩子：main 兜底触发 request 事件，after 统一写响应
+   */
+  _initHandle() {
+    this.#handle.on('main', (ctx, params) => {
+      return this._fallbackRequest(ctx, params);
+    }, 9999, 'fallback_request', { end: true });
+    this.#handle.on('after', (ctx) => {
+      this._writeResponse(ctx);
+    }, 1000, 'write_response');
+  }
+
+  /**
+   * 内置 main 兜底钩子逻辑：管道无人产出时触发 request 事件，仍未接管则 404
+   * @param {Object} ctx 执行上下文
+   * @param {Object} params 请求参数
+   * @returns {Object|undefined} 响应描述对象；事件已接管时为 undefined
+   */
+  _fallbackRequest(ctx, params) {
+    this._safeEmit('request', params, ctx);
+    if (ctx.handled) return undefined;
+    return { status: 404, body: { error: 'not found' } };
+  }
+
+  /**
+   * 内置 after 钩子逻辑：按 ctx.result / ctx.error 写出响应
+   * @param {Object} ctx 执行上下文
+   */
+  _writeResponse(ctx) {
+    const res = ctx.res;
+    if (ctx.handled || res.headersSent) return;
+    if (ctx.error) {
+      this._sendJson(res, 500, { error: ctx.error.message || 'internal error' });
+      return;
+    }
+    const result = ctx.result;
+    if (result === undefined) return;
+    if (!this._isResponse(result)) {
+      this._replyBody(res, 200, result);
+      return;
+    }
+    const status = result.status === undefined ? 200 : result.status;
+    if (result.body === undefined || result.body === null) {
+      this._sendEmpty(res, result.status === undefined ? 204 : status);
+      return;
+    }
+    this._replyBody(res, status, result.body);
+  }
+
+  /**
+   * 判断值是否为响应描述对象（含 status 或 body 字段）
+   * @param {*} value 待判断的值
+   * @returns {boolean} 是否为响应描述对象
+   */
+  _isResponse(value) {
+    if (value === null || typeof value !== 'object') return false;
+    return 'status' in value || 'body' in value;
+  }
+
+  /**
+   * 按响应体类型写出响应
+   * @param {Object} res 响应对象
+   * @param {number} status 状态码
+   * @param {*} body 响应体
+   */
+  _replyBody(res, status, body) {
+    if (typeof body === 'string') {
+      this._sendText(res, status, body);
+      return;
+    }
+    this._sendJson(res, status, body);
+  }
+
+  /**
+   * 发送 JSON 响应
+   * @param {Object} res 响应对象
+   * @param {number} status 状态码
+   * @param {Object} payload 响应体对象
+   */
+  _sendJson(res, status, payload) {
+    const text = JSON.stringify(payload);
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(text);
+    this._safeEmit('response', status, payload);
+  }
+
+  /**
+   * 发送纯文本响应
+   * @param {Object} res 响应对象
+   * @param {number} status 状态码
+   * @param {string} text 响应文本
+   */
+  _sendText(res, status, text) {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(text);
+    this._safeEmit('response', status, text);
+  }
+
+  /**
+   * 发送空响应
+   * @param {Object} res 响应对象
+   * @param {number} status 状态码
+   */
+  _sendEmpty(res, status) {
+    res.writeHead(status);
+    res.end();
+  }
+
+  // ---------- 监听与清理 ----------
+  /**
+   * 等待 HTTP 服务器监听成功
+   * @param {Object} server http.Server 实例
+   * @returns {Promise<void>} 无返回值
+   */
+  _listen(server) {
+    const host = this.config.host;
+    const port = this.config.port;
+    return new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen({ host, port }, () => {
+        server.removeListener('error', reject);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * 关闭 HTTP 服务器并断开残留连接
+   * @returns {Promise<void>} 无返回值
+   */
+  _closeServer() {
+    const server = this.#server;
+    if (!server) return Promise.resolve();
+    this.#server = null;
+    return new Promise((resolve) => {
+      if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+      server.close(resolve);
+    });
+  }
+
+  // ---------- 校验辅助 ----------
+  /**
+   * 校验顶层 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}`);
+  }
+}
+
+module.exports = WebServer;

package/package.json

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