@lzpong/httpm 1.0.3 → 1.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -8,7 +8,7 @@
 - **零第三方依赖** — 仅使用 Node.js 内置模块（`http`、`https`、`fs`、`path`、`crypto`、`zlib`）
 - **Express 兼容** — 路由、中间件、请求/响应 API 对齐 Express 语法
 - **静态文件服务** — Range 断点续传、ETag/Last-Modified 缓存、Gzip 压缩
-- **WebSocket** — 路径分组、心跳保活、广播、文本/二进制子事件
+- **WebSocket** — 路径分组、心跳保活、广播、文本/二进制子事件、分片帧支持、动态参数路由
 - **SSE** — 服务端推送事件，支持 event/data/retry/comment
 - **流式文件上传** — multipart/form-data 解析，内存零占用，临时文件自动清理
 - **日志系统** — 彩色控制台输出 + 文件持久化，按级别过滤
@@ -66,6 +66,9 @@ app.all('/any', (req, res) => res.json({ method: req.method }));
 
 路由匹配优先级：精准静态路由 > 动态参数路由 > ALL 通用路由 > 静态文件服务。
 
+- **HEAD 请求**：自动匹配 GET 路由，仅返回响应头（Express 兼容）
+- **OPTIONS 请求**：自动返回 `Allow` 头和 CORS 预检响应，动态查询该路径支持的方法
+
 路由处理器返回 `false` 时，请求进入静态文件兜底：
 
 ```javascript
@@ -119,10 +122,10 @@ app.use((err, req, res, next) => {
 | `req.body` | 请求体（JSON/URL-encoded 自动解析） |
 | `req.formData` | 表单数据（multipart 解析后） |
 | `req.cookies` | Cookie 对象 |
+| `req.get(name)` | 获取请求头（不区分大小写） |
 | `req.headers` | 请求头对象 |
 | `req.ip` | 客户端 IP |
 | `req.protocol` | 协议（http/https） |
-| `req.get(name)` | 获取请求头 |
 
 ## 响应对象 (res)
 
@@ -130,16 +133,16 @@ app.use((err, req, res, next) => {
 |------|------|
 | `res.status(code)` | 设置状态码，链式调用 |
 | `res.json(obj)` | 发送 JSON 响应 |
-| `res.send(data)` | 发送响应（自动识别类型） |
+| `res.send(data)` | 发送响应（自动识别类型；`null`→`"null"`，`undefined`→空响应） |
 | `res.sendFile(path, opts)` | 发送文件 |
 | `res.download(path, name)` | 下载文件 |
-| `res.redirect(url)` | 重定向（默认 302） |
-| `res.redirect(code, url)` | 重定向（指定状态码） |
+| `res.redirect([code,] url)` | 重定向，兼容 Express 签名：`redirect(url)` 默认 302，`redirect(status, url)` 指定状态码 |
 | `res.cookie(name, value, opts)` | 设置 Cookie |
 | `res.clearCookie(name, opts)` | 清除 Cookie |
-| `res.set(name, value)` / `res.setHeader()` | 设置响应头 |
+| `res.set(name, value)` / `res.setHeader()` | 设置响应头（set 支持对象批量） |
 | `res.get(name)` / `res.getHeader()` | 获取响应头 |
-| `res.type(type)` | 设置 Content-Type |
+| `res.type(type)` | 设置 Content-Type（支持简写：html→text/html） |
+| `res.on(event, fn)` | 监听响应事件（finish/close 等） |
 | `res.sse()` | 创建 SSE 实例 |
 
 ### Cookie 签名
@@ -160,10 +163,12 @@ req.cookies.token; // 'abc123'（签名验证通过）
 const app = httpm({ rootPath: './public', showDir: true, enableGzip: true, enableCache: true });
 ```
 
-或使用内置中间件：
+或使用内置中间件（支持目录自动查找 index.html）：
 
 ```javascript
 app.use(httpm.static('./public'));
+// 允许访问隐藏文件
+app.use(httpm.static('./public', { allowAccessToAllFiles: true }));
 ```
 
 | 配置项 | 默认值 | 说明 |
@@ -198,31 +203,28 @@ app.post('/upload', (req, res) => {
 ### 简化注册
 
 ```javascript
+// 静态路径
 app.ws('/chat', (ws, req) => {
   ws.send('Welcome!');
 
   ws.on('text', msg => {
-    app.wsServer.broadcast('/chat', msg, ws.id);
-  });
-
-  ws.on('binary', data => {
-    // 处理二进制数据
+    app.wss.broadcast('/chat', msg, ws);
   });
+});
 
-  ws.on('close', () => {
-    console.log('Client disconnected');
-  });
+// 动态参数路径
+app.ws('/chat/:room', (ws, req) => {
+  console.log('Room:', req.params.room);
+  ws.send(`Welcome to room ${req.params.room}!`);
 });
 ```
 
 ### WebSocketServer API
 
 ```javascript
-const wss = app.wsServer;
-
-wss.broadcast('/chat', 'Hello everyone');         // 按路径分组广播
-wss.broadcast('/chat', 'Hello', excludeWsId);     // 排除指定连接
-wss.getConnections();                              // 获取所有连接
+app.wss.broadcast('/chat', 'Hello everyone');       // 按路径分组广播
+app.wss.broadcast('/chat', 'Hello', ws);            // 排除指定连接（传 ws 对象）
+app.wss.getConnections();                            // 获取所有连接
 ```
 
 ### WebSocket 事件
@@ -232,7 +234,7 @@ wss.getConnections();                              // 获取所有连接
 | `data` | 接收消息（`{ type: 'text'/'binary', data }`） |
 | `text` | 接收文本消息 |
 | `binary` | 接收二进制消息 |
-| `close` | 连接关闭 |
+| `close` | 连接关闭，回调参数 `(code, reason)` |
 | `error` | 连接错误 |
 
 ### data 事件使用
@@ -334,9 +336,11 @@ const app = httpm({ svrPort: 3000 }); // svrPort=3000, enableGzip=true(来自app
 | `tempDir` | `'tempupdir'` | 上传临时文件目录 |
 | `maxFileSize` | `134217728` | 单文件大小限制（128MB） |
 | `maxFieldSize` | `1048576` | 表单字段大小限制（1MB） |
+| `maxBodySize` | `134217728` | 请求体大小限制（128MB） |
 | `svrPort` | `80` | 服务端口 |
 | `svrIP` | `null` | 绑定 IP（null=所有接口） |
 | `showDir` | `false` | 显示目录列表 |
+| `allowAccessToAllFiles` | `false` | 允许访问隐藏文件（.env、.git 等） |
 | `enableCache` | `false` | 启用缓存 |
 | `enableGzip` | `false` | 启用 Gzip 压缩 |
 | `enableRange` | `true` | 启用断点续传 |
@@ -352,6 +356,10 @@ const app = httpm({ svrPort: 3000 }); // svrPort=3000, enableGzip=true(来自app
 | `useCookieParser` | `true` | 自动解析 Cookie |
 | `bodyParserOptions` | `{}` | bodyParser 选项 |
 | `cookieParserSecret` | `null` | Cookie 签名密钥 |
+| `wsMaxPayload` | `104857600` | WebSocket 最大帧负载（100MB） |
+| `wsAllowedOrigins` | `null` | WebSocket 允许的 Origin 列表 |
+| `wsHeartbeatInterval` | `30000` | WebSocket 心跳检测间隔（毫秒） |
+| `wsHeartbeatTimeout` | `30000` | WebSocket 心跳超时时间（毫秒） |
 
 ## HTTPS / HTTP2
 
@@ -404,12 +412,13 @@ httpm.fmtTime
 httpm.isPathSafe
 httpm.generateETag
 httpm.parseRange
-httpm.WebSocketHandShark
+httpm.escapeHtml
+httpm.WebSocketHandShak
 ```
 
 ## 运行要求
 
-- Node.js >= 14.0.0
+- Node.js >= 18.0.0
 - 零第三方依赖
 
 ## 测试