mm_response 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -151,3 +151,12 @@ ISC License
151
151
  ## 作者
152
152
 
153
153
  邱文武
154
+
155
+ ## 工具契约(LLM 可调用)
156
+
157
+ 本模块 `tool/` 下登记以下工具契约,实现位于 `lib/tools/<name>/`,`tool/<name>/index.js` 仅为薄适配层。
158
+ 其它模块可直接 `require('<pkg>').tools.<name>` 复用实现,无需经过工具注册面。
159
+
160
+ | 工具名 | 标题 | 说明 |
161
+ | --- | --- | --- |
162
+ | `reply` | 响应内容协商 | 媒体类型推导与 reply 结构判定 |
@@ -0,0 +1,38 @@
1
+ {
2
+ "MEDIA_TYPES": {
3
+ "png": "image/png",
4
+ "jpg": "image/jpeg",
5
+ "jpeg": "image/jpeg",
6
+ "gif": "image/gif",
7
+ "webp": "image/webp",
8
+ "svg": "image/svg+xml",
9
+ "bmp": "image/bmp",
10
+ "ico": "image/x-icon",
11
+ "avif": "image/avif",
12
+ "mp4": "video/mp4",
13
+ "m4v": "video/mp4",
14
+ "webm": "video/webm",
15
+ "ogv": "video/ogg",
16
+ "mov": "video/quicktime",
17
+ "avi": "video/x-msvideo",
18
+ "mkv": "video/x-matroska",
19
+ "mp3": "audio/mpeg",
20
+ "wav": "audio/wav",
21
+ "ogg": "audio/ogg",
22
+ "oga": "audio/ogg",
23
+ "m4a": "audio/mp4",
24
+ "aac": "audio/aac",
25
+ "flac": "audio/flac",
26
+ "opus": "audio/opus",
27
+ "weba": "audio/webm",
28
+ "mid": "audio/midi",
29
+ "midi": "audio/midi"
30
+ },
31
+ "DEFAULT_IMAGE_TYPE": "image/png",
32
+ "DEFAULT_VIDEO_TYPE": "video/mp4",
33
+ "DEFAULT_AUDIO_TYPE": "audio/mpeg",
34
+ "JSON_TYPE": "application/json; charset=utf-8",
35
+ "XML_TYPE": "application/xml; charset=utf-8",
36
+ "XML_MIME_TYPES": ["application/xml", "text/xml"],
37
+ "OCTET_STREAM_TYPE": "application/octet-stream"
38
+ }
package/index.js CHANGED
@@ -1,7 +1,5 @@
1
- 'use strict';
2
-
3
- const Response = require('./lib/response');
4
- const reply = require('./lib/reply');
1
+ const Response = require('./lib/response.js');
2
+ const reply = require('./lib/reply.js');
5
3
 
6
4
  module.exports = {
7
5
  Response,
package/lib/reply.js CHANGED
@@ -1,61 +1,9 @@
1
1
  'use strict';
2
2
 
3
3
  const fs = require('fs');
4
+ const { constAdmin } = require('mm_consts');
4
5
 
5
- // 媒体扩展名与内容类型映射(图片 / 视频 / 音频)
6
- const MEDIA_TYPES = {
7
- // 图片
8
- png: 'image/png',
9
- jpg: 'image/jpeg',
10
- jpeg: 'image/jpeg',
11
- gif: 'image/gif',
12
- webp: 'image/webp',
13
- svg: 'image/svg+xml',
14
- bmp: 'image/bmp',
15
- ico: 'image/x-icon',
16
- avif: 'image/avif',
17
- // 视频
18
- mp4: 'video/mp4',
19
- m4v: 'video/mp4',
20
- webm: 'video/webm',
21
- ogv: 'video/ogg',
22
- mov: 'video/quicktime',
23
- avi: 'video/x-msvideo',
24
- mkv: 'video/x-matroska',
25
- // 音频
26
- mp3: 'audio/mpeg',
27
- wav: 'audio/wav',
28
- ogg: 'audio/ogg',
29
- oga: 'audio/ogg',
30
- m4a: 'audio/mp4',
31
- aac: 'audio/aac',
32
- flac: 'audio/flac',
33
- opus: 'audio/opus',
34
- weba: 'audio/webm',
35
- mid: 'audio/midi',
36
- midi: 'audio/midi'
37
- };
38
-
39
- // 缺省图片内容类型
40
- const DEFAULT_IMAGE_TYPE = 'image/png';
41
-
42
- // 缺省视频内容类型
43
- const DEFAULT_VIDEO_TYPE = 'video/mp4';
44
-
45
- // 缺省音频内容类型
46
- const DEFAULT_AUDIO_TYPE = 'audio/mpeg';
47
-
48
- // 缺省 JSON 内容类型
49
- const JSON_TYPE = 'application/json; charset=utf-8';
50
-
51
- // 缺省 XML 内容类型
52
- const XML_TYPE = 'application/xml; charset=utf-8';
53
-
54
- // XML 内容类型集合
55
- const XML_MIME_TYPES = ['application/xml', 'text/xml'];
56
-
57
- // 未知二进制内容类型
58
- const OCTET_STREAM_TYPE = 'application/octet-stream';
6
+ require('mm_consts').loadSync('response', require('path').join(__dirname, '..', 'data'));
59
7
 
60
8
  /**
61
9
  * 判断值是否为响应描述对象(含 status 或 body 字段)
@@ -91,8 +39,8 @@ function isStream(value) {
91
39
  * @returns {string} 小写扩展名(不含点号),无扩展名时为空串
92
40
  */
93
41
  function getExtname(file_path) {
94
- const name = String(file_path || '');
95
- const index = name.lastIndexOf('.');
42
+ let name = String(file_path || '');
43
+ let index = name.lastIndexOf('.');
96
44
  if (index === -1) return '';
97
45
  return name.slice(index + 1).toLowerCase();
98
46
  }
@@ -103,7 +51,8 @@ function getExtname(file_path) {
103
51
  * @returns {string} 内容类型,未知扩展名时返回 application/octet-stream
104
52
  */
105
53
  function getMediaType(file_path) {
106
- return MEDIA_TYPES[getExtname(file_path)] || OCTET_STREAM_TYPE;
54
+ let consts = constAdmin('response');
55
+ return consts.get('MEDIA_TYPES')[getExtname(file_path)] || consts.get('OCTET_STREAM_TYPE');
107
56
  }
108
57
 
109
58
  /**
@@ -122,7 +71,7 @@ function isMediaType(type) {
122
71
  * @returns {boolean} 是否为 XML 内容类型
123
72
  */
124
73
  function isXmlType(type) {
125
- return XML_MIME_TYPES.includes(type);
74
+ return constAdmin('response').get('XML_MIME_TYPES').includes(type);
126
75
  }
127
76
 
128
77
  /**
@@ -170,8 +119,8 @@ function sendText(res, status, text) {
170
119
  */
171
120
  function sendJson(res, status, payload) {
172
121
  if (res.writableEnded) return;
173
- const text = JSON.stringify(payload);
174
- res.writeHead(status, { 'content-type': JSON_TYPE });
122
+ let text = JSON.stringify(payload);
123
+ res.writeHead(status, { 'content-type': constAdmin('response').get('JSON_TYPE') });
175
124
  res.end(text);
176
125
  }
177
126
 
@@ -184,8 +133,8 @@ function sendJson(res, status, payload) {
184
133
  */
185
134
  function sendJsonBody(res, status, body) {
186
135
  if (res.writableEnded) return;
187
- const text = typeof body === 'string' ? body : JSON.stringify(body);
188
- res.writeHead(status, { 'content-type': JSON_TYPE });
136
+ let text = typeof body === 'string' ? body : JSON.stringify(body);
137
+ res.writeHead(status, { 'content-type': constAdmin('response').get('JSON_TYPE') });
189
138
  res.end(text);
190
139
  }
191
140
 
@@ -211,7 +160,7 @@ function sendEmpty(res, status) {
211
160
  */
212
161
  function sendXml(res, status, text, content_type) {
213
162
  if (res.writableEnded) return;
214
- res.writeHead(status, { 'content-type': content_type || XML_TYPE });
163
+ res.writeHead(status, { 'content-type': content_type || constAdmin('response').get('XML_TYPE') });
215
164
  res.end(text);
216
165
  }
217
166
 
@@ -289,7 +238,7 @@ function sendMedia(res, status, body, content_type) {
289
238
  * @returns {void}
290
239
  */
291
240
  function sendImage(res, status, body, content_type) {
292
- const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_IMAGE_TYPE);
241
+ let type = content_type || (typeof body === 'string' ? getMediaType(body) : constAdmin('response').get('DEFAULT_IMAGE_TYPE'));
293
242
  sendMedia(res, status, body, type);
294
243
  }
295
244
 
@@ -302,7 +251,7 @@ function sendImage(res, status, body, content_type) {
302
251
  * @returns {void}
303
252
  */
304
253
  function sendVideo(res, status, body, content_type) {
305
- const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_VIDEO_TYPE);
254
+ let type = content_type || (typeof body === 'string' ? getMediaType(body) : constAdmin('response').get('DEFAULT_VIDEO_TYPE'));
306
255
  sendMedia(res, status, body, type);
307
256
  }
308
257
 
@@ -315,7 +264,7 @@ function sendVideo(res, status, body, content_type) {
315
264
  * @returns {void}
316
265
  */
317
266
  function sendAudio(res, status, body, content_type) {
318
- const type = content_type || (typeof body === 'string' ? getMediaType(body) : DEFAULT_AUDIO_TYPE);
267
+ let type = content_type || (typeof body === 'string' ? getMediaType(body) : constAdmin('response').get('DEFAULT_AUDIO_TYPE'));
319
268
  sendMedia(res, status, body, type);
320
269
  }
321
270
 
@@ -362,7 +311,7 @@ function sendBody(res, status, body, type, content_type) {
362
311
  return;
363
312
  }
364
313
  if (isBinary(body)) {
365
- sendMedia(res, status, body, OCTET_STREAM_TYPE);
314
+ sendMedia(res, status, body, constAdmin('response').get('OCTET_STREAM_TYPE'));
366
315
  return;
367
316
  }
368
317
  if (typeof body === 'string') {
@@ -372,9 +321,27 @@ function sendBody(res, status, body, type, content_type) {
372
321
  sendJson(res, status, body);
373
322
  }
374
323
 
324
+ /**
325
+ * 解析非描述对象结果的 HTTP 状态码:
326
+ * code >= 50000 表示服务端故障(脚本异常等),映射为 HTTP 500,
327
+ * 与「路由不存在」(10000) 等业务级错误区分,保证 5xx 真实可见、可被监控告警。
328
+ * (与 mm_web_server 的 _statusOf 同一约定:错误码分段契约,两处实现互为兜底)
329
+ * @param {*} result 事件处理结果
330
+ * @returns {number} HTTP 状态码
331
+ */
332
+ function statusOfResult(result) {
333
+ if (result !== null && typeof result === 'object') {
334
+ let code = result.error && result.error.code;
335
+ if (typeof code === 'number' && code >= 50000) {
336
+ return 500;
337
+ }
338
+ }
339
+ return 200;
340
+ }
341
+
375
342
  /**
376
343
  * 写出事件处理结果:
377
- * 已写出则跳过;无结果为 404;非描述对象按 200 写出;描述对象按 status/body/type/content_type 写出
344
+ * 已写出则跳过;无结果为 404;非描述对象按错误码约定写出状态;描述对象按 status/body/type/content_type 写出
378
345
  * @param {Object} res 响应对象
379
346
  * @param {*} result 事件处理结果
380
347
  * @returns {void}
@@ -388,11 +355,11 @@ function sendResult(res, result) {
388
355
  }
389
356
 
390
357
  if (!isReply(result)) {
391
- sendBody(res, 200, result);
358
+ sendBody(res, statusOfResult(result), result);
392
359
  return;
393
360
  }
394
361
 
395
- const status = result.status === undefined ? 200 : result.status;
362
+ let status = result.status === undefined ? 200 : result.status;
396
363
  if (result.body === undefined || result.body === null) {
397
364
  sendEmpty(res, result.status === undefined ? 204 : status);
398
365
  return;
package/lib/response.js CHANGED
@@ -2,12 +2,6 @@
2
2
 
3
3
  const { sendJson, sendResult } = require('./reply');
4
4
 
5
- /**
6
- * HTML 文档开头标记正则(忽略前导空白,用于判定字符串是否为页面渲染结果)
7
- * @type {RegExp}
8
- */
9
- const HTML_PATTERN = /^\s*<(!doctype\s+html|html|head|body)(\s|>)/i;
10
-
11
5
  /**
12
6
  * Response —— 响应渲染中间件(mm_response)。
13
7
  *
@@ -26,6 +20,12 @@ const HTML_PATTERN = /^\s*<(!doctype\s+html|html|head|body)(\s|>)/i;
26
20
  * await web.start();
27
21
  */
28
22
  class Response {
23
+ /**
24
+ * HTML 文档开头标记正则(忽略前导空白,用于判定字符串是否为页面渲染结果)
25
+ * @type {RegExp}
26
+ */
27
+ static #html_pattern = /^\s*<(!doctype\s+html|html|head|body)(\s|>)/i;
28
+
29
29
  /**
30
30
  * 已挂载的 WebServer 实例,未挂载时为 null
31
31
  * @type {Object|null}
@@ -75,13 +75,13 @@ class Response {
75
75
  * @returns {void}
76
76
  */
77
77
  _respond(ctx, result, options) {
78
- const res = ctx && ctx.res;
78
+ let res = ctx && ctx.res;
79
79
  if (!res || ctx.handled === true || res.writableEnded) return;
80
80
  if (res.headersSent) {
81
81
  res.end();
82
82
  return;
83
83
  }
84
- const error = ctx.error || (options && options.error);
84
+ let error = ctx.error || (options && options.error);
85
85
  if (error) {
86
86
  sendJson(res, 500, { error: error.message || 'internal error' });
87
87
  return;
@@ -105,7 +105,7 @@ class Response {
105
105
  * @returns {boolean} 是否为 HTML 文档字符串
106
106
  */
107
107
  _isHtml(value) {
108
- return typeof value === 'string' && HTML_PATTERN.test(value);
108
+ return typeof value === 'string' && Response.#html_pattern.test(value);
109
109
  }
110
110
  }
111
111
 
package/package.json CHANGED
@@ -1,41 +1,46 @@
1
1
  {
2
- "name": "mm_response",
3
- "version": "1.1.0",
4
- "description": "Web 响应渲染中间件:为 mm_web_server 提供可挂载的响应写出器与响应工具函数。",
5
- "main": "index.js",
6
- "files": [
7
- "index.js",
8
- "lib",
9
- "example"
10
- ],
11
- "engines": {
12
- "node": ">=22.5.0"
13
- },
14
- "scripts": {
15
- "start": "node example/demo.js",
16
- "demo": "node example/demo.js",
17
- "test": "node --test \"tests/*.test.js\"",
18
- "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\""
19
- },
20
- "repository": {
21
- "type": "git",
22
- "url": "git+https://gitee.com/qiuwenwu91/mm_response.git"
23
- },
24
- "keywords": [
25
- "mm_mod",
26
- "mm_middleware",
27
- "web",
28
- "response",
29
- "html",
30
- "content-type"
31
- ],
32
- "layer": "middleware",
33
- "group": "middleware",
34
- "author": "邱文武",
35
- "license": "ISC",
36
- "bugs": {
37
- "url": "https://gitee.com/qiuwenwu91/mm_response/issues"
38
- },
39
- "homepage": "https://gitee.com/qiuwenwu91/mm_response#readme",
40
- "dependencies": {}
2
+ "name": "mm_response",
3
+ "version": "1.1.1",
4
+ "description": "Web 响应渲染中间件:为 mm_web_server 提供可挂载的响应写出器与响应工具函数。",
5
+ "main": "index.js",
6
+ "files": [
7
+ "index.js",
8
+ "lib",
9
+ "example",
10
+ "tool",
11
+ "data"
12
+ ],
13
+ "engines": {
14
+ "node": ">=22.5.0"
15
+ },
16
+ "scripts": {
17
+ "start": "node example/demo.js",
18
+ "demo": "node example/demo.js",
19
+ "test": "node --test \"tests/*.test.js\"",
20
+ "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\""
21
+ },
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "git+https://gitee.com/qiuwenwu91/mm_response.git"
25
+ },
26
+ "keywords": [
27
+ "mm_mod",
28
+ "mm_event_api",
29
+ "web",
30
+ "response",
31
+ "html",
32
+ "content-type"
33
+ ],
34
+ "layer": "action",
35
+ "group": "base",
36
+ "author": "邱文武",
37
+ "license": "ISC",
38
+ "bugs": {
39
+ "url": "https://gitee.com/qiuwenwu91/mm_response/issues"
40
+ },
41
+ "homepage": "https://gitee.com/qiuwenwu91/mm_response#readme",
42
+ "dependencies": {
43
+ "mm_consts": "^1.1.3",
44
+ "mm_files": "^1.4.2"
45
+ }
41
46
  }
@@ -0,0 +1,38 @@
1
+ 'use strict';
2
+ /**
3
+ * reply —— 响应内容协商工具
4
+ * 直接复用模块 lib/reply 的纯函数,不复制媒体类型映射表。
5
+ */
6
+ const { getMediaType, isJsonType, isReply } = require('../../index.js');
7
+
8
+ async function main(params, ctx, options) {
9
+ void options;
10
+ const p = params || {};
11
+ const action = p.action || 'media_type';
12
+ const done = (data) => { ctx.output = data; return data; };
13
+
14
+ try {
15
+ if (action === 'media_type') {
16
+ if (!p.file_path) throw new TypeError('file_path 不能为空');
17
+ const media_type = getMediaType(p.file_path);
18
+ return done({ code: 0, msg: '成功', media_type });
19
+ }
20
+
21
+ if (action === 'json_type') {
22
+ if (!p.type) throw new TypeError('type 不能为空');
23
+ const is_json = isJsonType(p.type);
24
+ return done({ code: 0, msg: is_json ? 'JSON 类型' : '非 JSON 类型', is_json });
25
+ }
26
+
27
+ if (action === 'is_reply') {
28
+ const yes = isReply(p.value);
29
+ return done({ code: 0, msg: yes ? '标准 reply 结构' : '非标准 reply 结构', is_reply: yes });
30
+ }
31
+
32
+ return done({ code: 10001, msg: '不支持的操作: ' + action });
33
+ } catch (error) {
34
+ return done({ code: 10000, msg: '执行失败:' + error.message, error: { name: error.name, message: error.message } });
35
+ }
36
+ }
37
+
38
+ module.exports = { main };
@@ -0,0 +1,68 @@
1
+ {
2
+ "name": "reply",
3
+ "title": "响应内容协商",
4
+ "description": "基于 mm_response 的纯函数能力:按文件名推导 Content-Type、判断内容类型是否 JSON、判断对象是否已是标准 reply 结构。适用场景:写响应前先确认媒体类型、校验回包结构、区分文本与二进制回包。",
5
+ "category": "HTTP 响应",
6
+ "group": "http",
7
+ "type": "function",
8
+ "main": "./index.js",
9
+ "params": {
10
+ "type": "object",
11
+ "properties": {
12
+ "action": {
13
+ "type": "string",
14
+ "description": "操作类型: media_type(按文件名取 Content-Type)/json_type(判断类型是否 JSON)/is_reply(判断是否标准 reply 结构)",
15
+ "enum": [
16
+ "media_type",
17
+ "json_type",
18
+ "is_reply"
19
+ ],
20
+ "default": "media_type"
21
+ },
22
+ "file_path": {
23
+ "type": "string",
24
+ "description": "文件路径或扩展名(media_type 必填),如 report.mp4 或 png"
25
+ },
26
+ "type": {
27
+ "type": "string",
28
+ "description": "内容类型标记(json_type 必填),如 application/json 或 json"
29
+ },
30
+ "value": {
31
+ "description": "待判断的对象(is_reply 必填)"
32
+ }
33
+ },
34
+ "required": [
35
+ "action"
36
+ ]
37
+ },
38
+ "returns": {
39
+ "type": "object",
40
+ "properties": {
41
+ "code": {
42
+ "type": "number",
43
+ "description": "0 表示成功"
44
+ },
45
+ "msg": {
46
+ "type": "string",
47
+ "description": "结果描述"
48
+ },
49
+ "media_type": {
50
+ "type": "string",
51
+ "description": "推导出的 Content-Type"
52
+ },
53
+ "is_json": {
54
+ "type": "boolean",
55
+ "description": "是否为 JSON 内容类型"
56
+ },
57
+ "is_reply": {
58
+ "type": "boolean",
59
+ "description": "是否标准 reply 结构"
60
+ },
61
+ "error": {
62
+ "type": "object",
63
+ "description": "异常对象 { name, message }"
64
+ }
65
+ }
66
+ },
67
+ "handler": "manager"
68
+ }