mm_response 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# mm_response
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web 响应渲染中间件。为 `mm_web_server` 提供可挂载的响应写出器，并导出无状态响应工具函数（由原 `mm_web_server/lib/reply.js` 迁移而来）。
+
+## 功能特点
+
+- `Response` 通过 `web.setResponder(...)` 挂载，统一写出事件处理结果
+- 识别 HTML 文档字符串，以 `text/html; charset=utf-8` 输出
+- 支持 XML 响应：`{ type: 'xml' }` 或 `{ type: 'application/xml' | 'text/xml' }`
+- 支持图片、视频、音频响应：`body` 可为 Buffer / Uint8Array、可读流或物理文件路径
+- 错误统一写出 `500 { "error": 错误信息 }`
+- 导出 `isReply` / `getMediaType` / `sendHtml` / `sendText` / `sendJson` / `sendEmpty` / `sendXml` / `sendFile` / `sendMedia` / `sendImage` / `sendVideo` / `sendAudio` / `sendBody` / `sendResult`，可单独复用
+
+## 安装
+
+```bash
+npm install mm_response
+```
+
+## 快速开始
+
+```javascript
+const { WebServer } = require('mm_web_server');
+const { Response } = require('mm_response');
+
+const web = new WebServer({ name: 'web', port: 8080 });
+new Response().bind(web);
+await web.init();
+await web.start();
+```
+
+## API 文档
+
+### `Response`
+
+| 方法 | 说明 |
+| --- | --- |
+| `constructor(config?)` | 创建实例，`config` 当前无配置项 |
+| `bind(web)` | 调用 `web.setResponder(...)` 挂载响应写出器；`web` 缺少 `setResponder()` 时抛出 `TypeError` |
+| `isBound()` | 是否已挂载 |
+
+写出器签名为 `responder(ctx, result, options)`：
+
+1. `ctx.handled === true`、`res.writableEnded` 或缺少 `res` 时跳过；
+2. `res.headersSent` 为真时只结束响应；
+3. `ctx.error` 或 `options.error` 存在时写出 `500`；
+4. 其余结果交给 `sendResult`。
+
+### 响应工具函数
+
+| 函数 | 说明 |
+| --- | --- |
+| `isReply(value)` | 是否为响应描述对象（含 `status` 或 `body` 字段） |
+| `getMediaType(file_path)` | 按扩展名推断图片 / 视频 / 音频内容类型 |
+| `sendHtml(res, status, text)` | 写 `text/html` |
+| `sendText(res, status, text)` | 写 `text/plain` |
+| `sendJson(res, status, payload)` | 写 `application/json` |
+| `sendEmpty(res, status)` | 写空响应 |
+| `sendXml(res, status, text, content_type?)` | 写 XML，缺省 `application/xml; charset=utf-8` |
+| `sendFile(res, status, file_path, content_type)` | 流式写文件并带 `content-length`，文件不存在时为 `404` |
+| `sendMedia(res, status, body, content_type)` | 写二进制内容，支持 Buffer / Uint8Array、可读流、文件路径 |
+| `sendImage(res, status, body, content_type?)` | 写图片，缺省 `image/png`，文件路径按扩展名推断 |
+| `sendVideo(res, status, body, content_type?)` | 写视频，缺省 `video/mp4`，文件路径按扩展名推断 |
+| `sendAudio(res, status, body, content_type?)` | 写音频，缺省 `audio/mpeg`，文件路径按扩展名推断 |
+| `sendBody(res, status, body, type?, content_type?)` | 按 `type` / body 类型分派 |
+| `sendResult(res, result)` | 按事件结果约定写出 |
+
+支持的图片扩展名：`png / jpg / jpeg / gif / webp / svg / bmp / ico / avif`；视频扩展名：`mp4 / m4v / webm / ogv / mov / avi / mkv`；音频扩展名：`mp3 / wav / ogg / oga / m4a / aac / flac / opus / weba / mid / midi`。未知扩展名统一为 `application/octet-stream`。
+
+## 响应约定
+
+| 事件结果 | 响应 |
+| --- | --- |
+| `undefined` / `null` | `404 { "error": "not found" }` |
+| HTML 文档字符串 | `200` + `text/html` |
+| 普通字符串 | `200` + `text/plain` |
+| 普通对象 | `200` + `application/json` |
+| `{ status, body }` | 按 `status` 写出 |
+| `{ status, body, type: 'html' }` | `text/html` |
+| `{ body, type: 'xml' }` | `application/xml; charset=utf-8` |
+| `{ body, type: 'application/xml' \| 'text/xml' }` | 使用给定内容类型并补 `charset=utf-8` |
+| `{ body, type: 'image' }` | 图片，`content_type` 优先，否则按文件路径扩展名推断，缺省 `image/png` |
+| `{ body, type: 'video' }` | 视频，`content_type` 优先，否则按文件路径扩展名推断，缺省 `video/mp4` |
+| `{ body, type: 'audio' }` | 音频，`content_type` 优先，否则按文件路径扩展名推断，缺省 `audio/mpeg` |
+| `{ body, type: 'image/webp' }` | 直接使用给定 `image/*` / `video/*` / `audio/*` 内容类型 |
+| Buffer / Uint8Array（无 `type`） | `application/octet-stream` |
+| `{ status }`（无 `body`） | 空响应，未给 `status` 时为 `204` |
+
+图片、视频、音频的 `body` 支持三种形式：
+
+```js
+// Buffer
+sendResult(res, { type: 'image', body: fs.readFileSync('logo.png') });
+// 可读流（content_type 建议显式给出）
+sendResult(res, { type: 'video', body: fs.createReadStream('a.webm'), content_type: 'video/webm' });
+// 物理文件路径，按扩展名推断内容类型并流式写出
+sendResult(res, { type: 'audio', body: '/var/www/a.mp3' });
+```
+
+不解析 Range，视频、音频统一整段返回 `200`；如需分段请求，应交给静态文件处理（`mm_statics`）。
+
+## 静态文件
+
+`mm_response` 不处理静态文件。静态资源按事件中间件接入，见 `mm_web_server` 的 `example/demo.js`：
+
+```js
+const { statics } = require('mm_statics');
+
+const serve = statics({ name: 'static', root: path.join(__dirname, 'static'), path: '/' });
+events.add({ name: 'static', target: '*', stage: 'before', end: true }).main = async (params, ctx) => serve(ctx, async () => {});
+```
+
+## 使用示例
+
+[example/demo.js](example/demo.js) 演示如何挂载 `Response` 并覆盖各类响应：
+
+```bash
+npm start
+# 或 npm run demo
+# 打开 http://127.0.0.1:8080
+```
+
+| 路径 | 演示内容 |
+| --- | --- |
+| `/` | HTML 文档字符串 → `text/html` |
+| `/json` | 对象 → `application/json` |
+| `/text` | 普通字符串 → `text/plain` |
+| `/xml` | `{ type: 'xml' }` |
+| `/image` | `{ type: 'image', body: 文件路径 }`，按扩展名推断并流式写出 |
+| `/audio` | `{ type: 'audio', body: Buffer }`，输出 WAV |
+| `/empty` | `{ status: 204 }` 空响应 |
+| `/raw` | 事件内自行写出响应 |
+| `/error` | 抛出错误 → `500` |
+
+## 测试
+
+测试位于 `tests/` 目录，使用 Node.js 内置 `node:test`：
+
+```bash
+npm test          # 运行全部测试
+npm run coverage  # 输出覆盖率，并要求 index.js 与 lib/ 的行、分支、函数覆盖率均为 100%
+```
+
+## 许可证
+
+ISC License
+
+## 作者
+
+邱文武

package/example/demo.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const path = require('path');
+const { WebServer } = require('mm_web_server');
+const { Response } = require('..');
+
+/** 演示监听端口 */
+const DEMO_PORT = 8080;
+
+/** 演示音频采样率 */
+const SAMPLE_RATE = 8000;
+
+/** 演示音频时长（秒） */
+const DURATION_SECONDS = 0.5;
+
+/** 演示音频频率（赫兹） */
+const TONE_FREQUENCY = 440;
+
+/**
+ * 生成一段 WAV 音频数据（单声道、16 位、440Hz）
+ * @returns {Buffer} WAV 文件内容
+ */
+function createWavBuffer() {
+  const sample_count = Math.floor(SAMPLE_RATE * DURATION_SECONDS);
+  const data_size = sample_count * 2;
+  const buffer = Buffer.alloc(44 + data_size);
+
+  buffer.write('RIFF', 0);
+  buffer.writeUInt32LE(36 + data_size, 4);
+  buffer.write('WAVE', 8);
+  buffer.write('fmt ', 12);
+  buffer.writeUInt32LE(16, 16);
+  buffer.writeUInt16LE(1, 20);
+  buffer.writeUInt16LE(1, 22);
+  buffer.writeUInt32LE(SAMPLE_RATE, 24);
+  buffer.writeUInt32LE(SAMPLE_RATE * 2, 28);
+  buffer.writeUInt16LE(2, 32);
+  buffer.writeUInt16LE(16, 34);
+  buffer.write('data', 36);
+  buffer.writeUInt32LE(data_size, 40);
+
+  for (let i = 0; i < sample_count; i += 1) {
+    const value = Math.round(Math.sin((2 * Math.PI * TONE_FREQUENCY * i) / SAMPLE_RATE) * 0x3fff);
+    buffer.writeInt16LE(value, 44 + i * 2);
+  }
+
+  return buffer;
+}
+
+/**
+ * 生成演示首页 HTML
+ * @returns {string} HTML 文档
+ */
+function createIndexHtml() {
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <title>mm_response 示例</title>
+</head>
+<body>
+  <h1>mm_response 示例</h1>
+  <ul>
+    <li><a href="/json">/json</a> 对象 → application/json</li>
+    <li><a href="/text">/text</a> 普通字符串 → text/plain</li>
+    <li><a href="/xml">/xml</a> XML 响应</li>
+    <li><a href="/image">/image</a> 按文件路径流式输出 SVG</li>
+    <li><a href="/audio">/audio</a> Buffer 输出 WAV 音频</li>
+    <li><a href="/empty">/empty</a> 无 body 的空响应</li>
+    <li><a href="/raw">/raw</a> 事件内自行写出响应</li>
+    <li><a href="/error">/error</a> 抛出错误 → 500</li>
+  </ul>
+</body>
+</html>`;
+}
+
+/**
+ * 注册演示事件
+ * @param {Object} events 事件管理器
+ * @returns {void}
+ */
+function bindEvents(events) {
+  events.add({ name: 'index', target: '/', end: true }).main = async () => createIndexHtml();
+
+  events.add({ name: 'json', target: '/json', end: true }).main = async () => ({
+    name: 'mm_response',
+    type: 'json',
+    items: [1, 2, 3]
+  });
+
+  events.add({ name: 'text', target: '/text', end: true }).main = async () => '纯文本响应';
+
+  events.add({ name: 'xml', target: '/xml', end: true }).main = async () => ({
+    type: 'xml',
+    body: '<?xml version="1.0" encoding="UTF-8"?><response><status>ok</status></response>'
+  });
+
+  events.add({ name: 'image', target: '/image', end: true }).main = async () => ({
+    type: 'image',
+    body: path.join(__dirname, 'static', 'logo.svg')
+  });
+
+  events.add({ name: 'audio', target: '/audio', end: true }).main = async () => ({
+    type: 'audio',
+    body: createWavBuffer(),
+    content_type: 'audio/wav'
+  });
+
+  events.add({ name: 'empty', target: '/empty', end: true }).main = async () => ({ status: 204 });
+
+  events.add({ name: 'raw', target: '/raw', end: true }).main = (params, ctx) => {
+    ctx.res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+    ctx.res.end('事件自行写出的响应');
+  };
+
+  events.add({ name: 'error', target: '/error', end: true }).main = async () => {
+    throw new Error('示例错误');
+  };
+}
+
+/**
+ * 演示入口：启动服务器并打印访问地址
+ * @returns {Promise<void>} 无返回值
+ */
+async function main() {
+  const web = new WebServer({ name: 'mm_response-demo', port: DEMO_PORT });
+  bindEvents(web.getEventManager());
+  new Response().bind(web);
+
+  await web.init();
+  await web.start();
+
+  const address = web.getAddress();
+  console.log(`http://127.0.0.1:${address.port}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/example/static/logo.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="240" height="120" viewBox="0 0 240 120" role="img" aria-label="mm_response">
+  <rect width="240" height="120" rx="12" fill="#0f172a" />
+  <text x="120" y="58" fill="#38bdf8" font-family="Consolas, monospace" font-size="28" text-anchor="middle">mm_response</text>
+  <text x="120" y="86" fill="#94a3b8" font-family="Consolas, monospace" font-size="14" text-anchor="middle">response response middleware</text>
+</svg>

package/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const Response = require('./lib/response');
+const reply = require('./lib/reply');
+
+module.exports = {
+  Response,
+  ...reply
+};

package/lib/reply.js

@@ -0,0 +1,388 @@
+'use strict';
+
+const fs = require('fs');
+
+// 媒体扩展名与内容类型映射（图片 / 视频 / 音频）
+const MEDIA_TYPES = {
+  // 图片
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  bmp: 'image/bmp',
+  ico: 'image/x-icon',
+  avif: 'image/avif',
+  // 视频
+  mp4: 'video/mp4',
+  m4v: 'video/mp4',
+  webm: 'video/webm',
+  ogv: 'video/ogg',
+  mov: 'video/quicktime',
+  avi: 'video/x-msvideo',
+  mkv: 'video/x-matroska',
+  // 音频
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  oga: 'audio/ogg',
+  m4a: 'audio/mp4',
+  aac: 'audio/aac',
+  flac: 'audio/flac',
+  opus: 'audio/opus',
+  weba: 'audio/webm',
+  mid: 'audio/midi',
+  midi: 'audio/midi'
+};
+
+// 缺省图片内容类型
+const DEFAULT_IMAGE_TYPE = 'image/png';
+
+// 缺省视频内容类型
+const DEFAULT_VIDEO_TYPE = 'video/mp4';
+
+// 缺省音频内容类型
+const DEFAULT_AUDIO_TYPE = 'audio/mpeg';
+
+// 缺省 XML 内容类型
+const XML_TYPE = 'application/xml; charset=utf-8';
+
+// XML 内容类型集合
+const XML_MIME_TYPES = ['application/xml', 'text/xml'];
+
+// 未知二进制内容类型
+const OCTET_STREAM_TYPE = 'application/octet-stream';
+
+/**
+ * 判断值是否为响应描述对象（含 status 或 body 字段）
+ * @param {*} value 待判断的值
+ * @returns {boolean} 是否为响应描述对象
+ */
+function isReply(value) {
+  if (value === null || typeof value !== 'object') return false;
+  return 'status' in value || 'body' in value;
+}
+
+/**
+ * 判断值是否为二进制数据
+ * @param {*} value 待判断的值
+ * @returns {boolean} 是否为二进制数据
+ */
+function isBinary(value) {
+  return Buffer.isBuffer(value) || value instanceof Uint8Array;
+}
+
+/**
+ * 判断值是否为可读流
+ * @param {*} value 待判断的值
+ * @returns {boolean} 是否为可读流
+ */
+function isStream(value) {
+  return value !== null && typeof value === 'object' && typeof value.pipe === 'function';
+}
+
+/**
+ * 取文件路径的扩展名
+ * @param {string} file_path 文件路径
+ * @returns {string} 小写扩展名（不含点号），无扩展名时为空串
+ */
+function getExtname(file_path) {
+  const name = String(file_path || '');
+  const index = name.lastIndexOf('.');
+  if (index === -1) return '';
+  return name.slice(index + 1).toLowerCase();
+}
+
+/**
+ * 根据文件路径推断媒体内容类型（图片 / 视频 / 音频）
+ * @param {string} file_path 文件路径
+ * @returns {string} 内容类型，未知扩展名时返回 application/octet-stream
+ */
+function getMediaType(file_path) {
+  return MEDIA_TYPES[getExtname(file_path)] || OCTET_STREAM_TYPE;
+}
+
+/**
+ * 判断是否为媒体内容类型标记（含 image / video / audio 三类）
+ * @param {*} type 内容类型标记
+ * @returns {boolean} 是否为媒体内容类型
+ */
+function isMediaType(type) {
+  if (typeof type !== 'string') return false;
+  return type.startsWith('image/') || type.startsWith('video/') || type.startsWith('audio/');
+}
+
+/**
+ * 判断是否为 XML 内容类型
+ * @param {*} type 内容类型
+ * @returns {boolean} 是否为 XML 内容类型
+ */
+function isXmlType(type) {
+  return XML_MIME_TYPES.includes(type);
+}
+
+/**
+ * 发送 HTML 响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {string} text 响应文本
+ * @returns {void}
+ */
+function sendHtml(res, status, text) {
+  if (res.writableEnded) return;
+  res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+  res.end(text);
+}
+
+/**
+ * 发送纯文本响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {string} text 响应文本
+ * @returns {void}
+ */
+function sendText(res, status, text) {
+  if (res.writableEnded) return;
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end(text);
+}
+
+/**
+ * 发送 JSON 响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {Object} payload 响应体对象
+ * @returns {void}
+ */
+function sendJson(res, status, payload) {
+  if (res.writableEnded) return;
+  const text = JSON.stringify(payload);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(text);
+}
+
+/**
+ * 发送空响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @returns {void}
+ */
+function sendEmpty(res, status) {
+  if (res.writableEnded) return;
+  res.writeHead(status);
+  res.end();
+}
+
+/**
+ * 发送 XML 响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {string} text 响应文本
+ * @param {string} [content_type] 内容类型，缺省 application/xml; charset=utf-8
+ * @returns {void}
+ */
+function sendXml(res, status, text, content_type) {
+  if (res.writableEnded) return;
+  res.writeHead(status, { 'content-type': content_type || XML_TYPE });
+  res.end(text);
+}
+
+/**
+ * 以流式方式发送文件，文件不存在时返回 404
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {string} file_path 物理文件路径
+ * @param {string} content_type 内容类型
+ * @returns {void}
+ */
+function sendFile(res, status, file_path, content_type) {
+  if (res.writableEnded) return;
+
+  let stat = null;
+  try {
+    stat = fs.statSync(file_path);
+  } catch {
+    sendJson(res, 404, { error: 'not found' });
+    return;
+  }
+
+  if (!stat.isFile()) {
+    sendJson(res, 404, { error: 'not found' });
+    return;
+  }
+
+  res.writeHead(status, {
+    'content-type': content_type,
+    'content-length': stat.size
+  });
+  fs.createReadStream(file_path)
+    .on('error', () => res.destroy())
+    .pipe(res);
+}
+
+/**
+ * 发送二进制内容，支持二进制数据、可读流与物理文件路径
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {Buffer|Uint8Array|Object|string} body 二进制数据、可读流或文件路径
+ * @param {string} content_type 内容类型
+ * @returns {void}
+ */
+function sendMedia(res, status, body, content_type) {
+  if (res.writableEnded) return;
+
+  if (isBinary(body)) {
+    res.writeHead(status, {
+      'content-type': content_type,
+      'content-length': body.length
+    });
+    res.end(body);
+    return;
+  }
+
+  if (typeof body === 'string') {
+    sendFile(res, status, body, content_type);
+    return;
+  }
+
+  if (isStream(body)) {
+    res.writeHead(status, { 'content-type': content_type });
+    body.on('error', () => res.destroy());
+    body.pipe(res);
+  }
+}
+
+/**
+ * 发送图片响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {Buffer|Uint8Array|Object|string} body 图片数据、可读流或文件路径
+ * @param {string} [content_type] 内容类型，缺省按文件路径推断或使用 image/png
+ * @returns {void}
+ */
+function sendImage(res, status, body, content_type) {
+  const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_IMAGE_TYPE);
+  sendMedia(res, status, body, type);
+}
+
+/**
+ * 发送视频响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {Buffer|Uint8Array|Object|string} body 视频数据、可读流或文件路径
+ * @param {string} [content_type] 内容类型，缺省按文件路径推断或使用 video/mp4
+ * @returns {void}
+ */
+function sendVideo(res, status, body, content_type) {
+  const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_VIDEO_TYPE);
+  sendMedia(res, status, body, type);
+}
+
+/**
+ * 发送音频响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {Buffer|Uint8Array|Object|string} body 音频数据、可读流或文件路径
+ * @param {string} [content_type] 内容类型，缺省按文件路径推断或使用 audio/mpeg
+ * @returns {void}
+ */
+function sendAudio(res, status, body, content_type) {
+  const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_AUDIO_TYPE);
+  sendMedia(res, status, body, type);
+}
+
+/**
+ * 按响应体类型写出响应
+ * @param {Object} res 响应对象
+ * @param {number} status 状态码
+ * @param {*} body 响应体
+ * @param {string} [type] 内容类型标记（html / xml / image / video / audio，或对应 MIME 形式的内容类型），缺省按 body 类型推断
+ * @param {string} [content_type] 内容类型，type 为 image / video / audio 时优先使用
+ * @returns {void}
+ */
+function sendBody(res, status, body, type, content_type) {
+  if (type === 'html') {
+    sendHtml(res, status, body);
+    return;
+  }
+  if (type === 'xml') {
+    sendXml(res, status, body);
+    return;
+  }
+  if (isXmlType(type)) {
+    sendXml(res, status, body, `${type}; charset=utf-8`);
+    return;
+  }
+  if (type === 'image') {
+    sendImage(res, status, body, content_type);
+    return;
+  }
+  if (type === 'video') {
+    sendVideo(res, status, body, content_type);
+    return;
+  }
+  if (type === 'audio') {
+    sendAudio(res, status, body, content_type);
+    return;
+  }
+  if (isMediaType(type)) {
+    sendMedia(res, status, body, type);
+    return;
+  }
+  if (isBinary(body)) {
+    sendMedia(res, status, body, OCTET_STREAM_TYPE);
+    return;
+  }
+  if (typeof body === 'string') {
+    sendText(res, status, body);
+    return;
+  }
+  sendJson(res, status, body);
+}
+
+/**
+ * 写出事件处理结果：
+ * 已写出则跳过；无结果为 404；非描述对象按 200 写出；描述对象按 status/body/type/content_type 写出
+ * @param {Object} res 响应对象
+ * @param {*} result 事件处理结果
+ * @returns {void}
+ */
+function sendResult(res, result) {
+  if (res.writableEnded) return;
+
+  if (result === undefined || result === null) {
+    sendJson(res, 404, { error: 'not found' });
+    return;
+  }
+
+  if (!isReply(result)) {
+    sendBody(res, 200, result);
+    return;
+  }
+
+  const status = result.status === undefined ? 200 : result.status;
+  if (result.body === undefined || result.body === null) {
+    sendEmpty(res, result.status === undefined ? 204 : status);
+    return;
+  }
+
+  sendBody(res, status, result.body, result.type, result.content_type);
+}
+
+module.exports = {
+  isReply,
+  getMediaType,
+  sendHtml,
+  sendText,
+  sendJson,
+  sendEmpty,
+  sendXml,
+  sendFile,
+  sendMedia,
+  sendImage,
+  sendVideo,
+  sendAudio,
+  sendBody,
+  sendResult
+};

package/lib/response.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const { sendJson, sendResult } = require('./reply');
+
+/**
+ * HTML 文档开头标记正则（忽略前导空白，用于判定字符串是否为页面渲染结果）
+ * @type {RegExp}
+ */
+const HTML_PATTERN = /^\s*<(!doctype\s+html|html|head|body)(\s|>)/i;
+
+/**
+ * Response —— 响应渲染中间件（mm_response）。
+ *
+ * 作用：作为 WebServer 的响应写出器，把事件处理结果按约定写成 HTTP 响应：
+ *   - 错误：500 JSON；
+ *   - HTML 文档字符串：text/html；
+ *   - 普通字符串：text/plain；
+ *   - 其他对象：application/json；
+ *   - 无结果：404；响应描述对象无 body：204。
+ *
+ * 用法：
+ *   const { Response } = require('mm_response');
+ *   const web = new WebServer({ name: 'web', port: 8080 }, server);
+ *   new Response().bind(web);
+ *   await web.init();
+ *   await web.start();
+ */
+class Response {
+  /**
+   * 已挂载的 WebServer 实例，未挂载时为 null
+   * @type {Object|null}
+   */
+  #web = null;
+
+  /**
+   * 构造函数
+   * @param {Object} [config] 配置参数（预留，当前无配置项）
+   */
+  constructor(config = {}) {
+    /**
+     * 渲染配置
+     * @type {Object}
+     */
+    this.config = { ...config };
+  }
+
+  /**
+   * 挂载到 WebServer：注册响应写出器
+   * @param {Object} web 具备 setResponder(responder) 的 WebServer 实例
+   * @returns {Response} 当前实例
+   * @throws {TypeError} web 不具备 setResponder 方法时
+   */
+  bind(web) {
+    if (!web || typeof web.setResponder !== 'function') {
+      throw new TypeError('[Response] web must provide setResponder()');
+    }
+    this.#web = web;
+    web.setResponder((ctx, result, options) => this._respond(ctx, result, options));
+    return this;
+  }
+
+  /**
+   * 判断是否已挂载
+   * @returns {boolean} 是否已挂载到 WebServer
+   */
+  isBound() {
+    return this.#web !== null;
+  }
+
+  /**
+   * 写出响应：跳过已处理请求，优先写出错误，否则按结果类型写出
+   * @param {Object} ctx 请求上下文
+   * @param {*} result 事件处理结果
+   * @param {Object} [options] 事件运行选项，可能含 error
+   * @returns {void}
+   */
+  _respond(ctx, result, options) {
+    const res = ctx && ctx.res;
+    if (!res || ctx.handled === true || res.writableEnded) return;
+    if (res.headersSent) {
+      res.end();
+      return;
+    }
+    const error = ctx.error || (options && options.error);
+    if (error) {
+      sendJson(res, 500, { error: error.message || 'internal error' });
+      return;
+    }
+    sendResult(res, this._toReply(result));
+  }
+
+  /**
+   * 把符合 HTML 文档特征的字符串转为 html 响应描述对象
+   * @param {*} result 事件处理结果
+   * @returns {*} 转换后的结果；非 HTML 文档字符串原样返回
+   */
+  _toReply(result) {
+    if (!this._isHtml(result)) return result;
+    return { status: 200, type: 'html', body: result };
+  }
+
+  /**
+   * 判断值是否为 HTML 文档字符串
+   * @param {*} value 待判断的值
+   * @returns {boolean} 是否为 HTML 文档字符串
+   */
+  _isHtml(value) {
+    return typeof value === 'string' && HTML_PATTERN.test(value);
+  }
+}
+
+module.exports = Response;

package/package.json

@@ -1,6 +1,41 @@
 {
-  "name": "mm_response",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_response",
+    "version": "1.0.1",
+    "description": "Web 响应渲染中间件：为 mm_web_server 提供可挂载的响应写出器与响应工具函数。",
+    "main": "index.js",
+    "files": [
+        "index.js",
+        "lib",
+        "example"
+    ],
+    "engines": {
+        "node": ">=22.5.0"
+    },
+    "scripts": {
+        "start": "node example/demo.js",
+        "demo": "node example/demo.js",
+        "test": "node --test \"tests/*.test.js\"",
+        "coverage": "node --test --experimental-test-coverage --test-coverage-include=\"index.js\" --test-coverage-include=\"lib/**\" --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 \"tests/*.test.js\""
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_response.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_middleware",
+        "web",
+        "response",
+        "html",
+        "content-type"
+    ],
+    "layer": "middleware",
+    "group": "middleware",
+    "author": "邱文武",
+    "license": "ISC",
+    "bugs": {
+        "url": "https://gitee.com/qiuwenwu91/mm_response/issues"
+    },
+    "homepage": "https://gitee.com/qiuwenwu91/mm_response#readme",
+    "dependencies": {}
+}