@lzpong/httpm 1.2.1 → 1.2.3

package/README.md

@@ -122,9 +122,11 @@ app.use((err, req, res, next) => {
 | `req.body` | 请求体（JSON/URL-encoded 自动解析） |
 | `req.formData` | 表单数据（multipart 解析后） |
 | `req.cookies` | Cookie 对象 |
+| `req.signedCookies` | 签名 Cookie 对象（需配置 `cookieParserSecret`） |
 | `req.get(name)` | 获取请求头（不区分大小写） |
 | `req.headers` | 请求头对象 |
 | `req.ip` | 客户端 IP |
+| `req.hostname` | 请求域名 |
 | `req.protocol` | 协议（http/https） |
 
 ## 响应对象 (res)
@@ -134,13 +136,14 @@ app.use((err, req, res, next) => {
 | `res.status(code)` | 设置状态码，链式调用 |
 | `res.json(obj)` | 发送 JSON 响应 |
 | `res.send(data)` | 发送响应（自动识别类型；`null`→`"null"`，`undefined`→空响应） |
-| `res.sendFile(path, opts)` | 发送文件 |
-| `res.download(path, name)` | 下载文件 |
+| `res.sendFile(path, opts)` | 发送文件，opts 支持 `{ root, contentType }` |
+| `res.download(path, [name], [opts])` | 下载文件，兼容 Express 签名：opts 传递给 sendFile |
 | `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()` | 设置响应头（set 支持对象批量） |
-| `res.get(name)` / `res.getHeader()` | 获取响应头 |
+| `res.set(name, value)` / `res.setHeader()` | 设置响应头（set 支持对象批量；setHeader 为底层方法，功能相同） |
+| `res.get(name)` / `res.getHeader()` | 获取响应头（get 为 Express 兼容方法，功能相同） |
+| `res.removeHeader(name)` | 移除已设置的响应头 |
 | `res.type(type)` | 设置 Content-Type（支持简写：html→text/html） |
 | `res.on(event, fn)` | 监听响应事件（finish/close 等） |
 | `res.sse()` | 创建 SSE 实例 |

package/httpm.js

@@ -2,7 +2,7 @@
  * httpm - 基于 Node.js 原生模块的单文件、零依赖 HTTP 服务库
  *
  * @name        httpm
- * @version     1.2.1
+ * @version     1.2.3
  * @description 兼容 Express API，内置路由、中间件、静态文件服务、
  *              WebSocket、SSE、流式上传、日志系统等功能
  * @license     MIT
@@ -164,8 +164,7 @@ const MIME_TYPES = {
  * 根据文件后缀匹配标准 MIME 类型
  */
 function getMimeType(ext) {
-  if (!ext) return 'application/octet-stream';
-  const lower = ext.toLowerCase();
+  const lower = ext?.toString().toLowerCase();
   return MIME_TYPES[lower] || 'application/octet-stream';
 }
 
@@ -773,7 +772,12 @@ class Response {
       }
 
       const mime = getMimeType(path.extname(fullPath));
-      this.setHeader('Content-Type', mime);
+      // Content-Type 优先级：options.contentType > 已设置的 Content-Type > 自动检测
+      if (options.contentType) {
+        this.setHeader('Content-Type', options.contentType);
+      } else if (!this.getHeader('Content-Type')) {
+        this.setHeader('Content-Type', mime);
+      }
       this.setHeader('Accept-Ranges', 'bytes');
 
       // ETag 缓存校验
@@ -872,10 +876,19 @@ class Response {
   /**
    * 触发浏览器文件下载，支持大文件进度展示
    */
-  download(filePath, filename) {
-    const name = filename || path.basename(filePath);
+  download(filePath, filename, options) {
+    // Express 兼容签名：download(path), download(path, filename), download(path, filename, options), download(path, options)
+    let name = filename;
+    let opts = options;
+    if (typeof filename === 'object' && filename !== null) {
+      // download(path, options) 形式
+      opts = filename;
+      name = null;
+    }
+    name = name || path.basename(filePath);
+    opts = opts || {};
     this.setHeader('Content-Disposition', `attachment; filename="${encodeURIComponent(name)}"`);
-    this.sendFile(filePath);
+    this.sendFile(filePath, opts);
   }
 
   /**
@@ -1045,8 +1058,6 @@ class WebSocket {
     this._handlers = {};
     // 最大帧负载大小（默认 100MB，防止恶意超大帧耗尽内存）
     this._maxPayload = options.maxPayload || 100 * 1024 * 1024;
-    // 写入背压标记
-    this._writeBacklogged = false;
     // 帧解析状态：缓存不完整帧数据
     this._frameBuffer = Buffer.alloc(0);
     // 分片帧状态
@@ -1090,7 +1101,7 @@ class WebSocket {
     while (this._frameBuffer.length >= 2) {
       const result = this._decodeFrame(this._frameBuffer);
       if (result === null) break; // 数据不完整，等待更多数据
-      this._frameBuffer = this._frameBuffer.slice(result.bytesConsumed);
+      this._frameBuffer = this._frameBuffer.subarray(result.bytesConsumed);
       this._processFrame(result.opcode, result.payload, result.fin, result.oversize);
     }
   }
@@ -1129,7 +1140,7 @@ class WebSocket {
     let mask = null;
     if (isMasked) {
       if (buf.length < offset + 4) return null;
-      mask = buf.slice(offset, offset + 4);
+      mask = buf.subarray(offset, offset + 4);
       offset += 4;
     }
 
@@ -1142,7 +1153,7 @@ class WebSocket {
     }
 
     // 提取负载
-    let payload = buf.slice(offset, offset + payloadLength);
+    let payload = buf.subarray(offset, offset + payloadLength);
     if (isMasked && mask) {
       for (let i = 0; i < payload.length; i++) {
         payload[i] ^= mask[i % 4];
@@ -1174,7 +1185,7 @@ class WebSocket {
         code = payload.readUInt16BE(0);
         // RFC 6455 Section 7.4: 状态码 0-999 为非法，1005 表示无状态码
         if (code < 1000) code = 1005;
-        reason = payload.length > 2 ? payload.slice(2).toString('utf8') : '';
+        reason = payload.length > 2 ? payload.subarray(2).toString('utf8') : '';
       }
       // 如果正在关闭握手中，对端已回复 Close 帧，完成握手
       if (this._closing) {
@@ -1282,11 +1293,7 @@ class WebSocket {
     frames.push(payload);
     const frame = Buffer.concat(frames);
     try {
-      const canWrite = this.socket.write(frame);
-      // 写入缓冲区满时记录警告（WebSocket 不像 HTTP 可暂停请求流，只能记录）
-      if (!canWrite) {
-        this._writeBacklogged = true;
-      }
+      this.socket.write(frame);
     } catch (e) {
       this.connected = false;
       // 发送失败时触发 error 事件，便于用户感知和处理
@@ -1692,10 +1699,8 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
   let cleanupOnError = false;
   let paused = false;
 
-  // 确保临时目录存在
-  if (!fs.existsSync(tempDir)) {
-    fs.mkdirSync(tempDir, { recursive: true });
-  }
+  // 确保临时目录存在（recursive: true 时目录已存在不报错，无需 existsSync）
+  fs.mkdirSync(tempDir, { recursive: true });
 
   function processBuffer() {
     while (buffer.length > 0) {
@@ -1705,14 +1710,14 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
         if (idx === -1) {
           // 保留尾部回看字节，防止分隔符跨 chunk 截断
           if (buffer.length > lookBehind) {
-            buffer = buffer.slice(buffer.length - lookBehind);
+            buffer = buffer.subarray(buffer.length - lookBehind);
           }
           break;
         }
-        buffer = buffer.slice(idx + delimiter.length);
+        buffer = buffer.subarray(idx + delimiter.length);
         // 跳过 \r\n
         if (buffer.length >= 2 && buffer[0] === 0x0D && buffer[1] === 0x0A) {
-          buffer = buffer.slice(2);
+          buffer = buffer.subarray(2);
         }
         state = 'HEADERS';
         partHeadersBuf = Buffer.alloc(0);
@@ -1725,8 +1730,8 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
           buffer = Buffer.alloc(0);
           break;
         }
-        partHeadersBuf = Buffer.concat([partHeadersBuf, buffer.slice(0, headerEnd)]);
-        buffer = buffer.slice(headerEnd + 4);
+        partHeadersBuf = Buffer.concat([partHeadersBuf, buffer.subarray(0, headerEnd)]);
+        buffer = buffer.subarray(headerEnd + 4);
         const partHeaders = partHeadersBuf.toString('utf8');
 
         // 解析 Content-Disposition
@@ -1761,7 +1766,7 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
           // 保留尾部回看字节，防止分隔符跨 chunk 截断
           const safeLen = Math.max(0, buffer.length - lookBehind);
           const chunk = buffer.toString('utf8', 0, safeLen);
-          fieldSize += chunk.length;
+          fieldSize += safeLen;
           if (fieldSize > maxFieldSize) {
             const err = new Error(`Field exceeds maximum size of ${fmtSize(maxFieldSize)}`, { cause: { actual: fieldSize, maxSize: maxFieldSize } });
             err.status = 413;
@@ -1769,12 +1774,12 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
             return;
           }
           currentField.value += chunk;
-          buffer = buffer.slice(safeLen);
+          buffer = buffer.subarray(safeLen);
           break;
         }
         // 字段结束
         const chunk = buffer.toString('utf8', 0, idx);
-        fieldSize += chunk.length;
+        fieldSize += idx;
         if (fieldSize > maxFieldSize) {
           const err = new Error(`Field exceeds maximum size of ${fmtSize(maxFieldSize)}`, { cause: { actual: fieldSize, maxSize: maxFieldSize } });
           err.status = 413;
@@ -1787,10 +1792,10 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
           currentField.value = currentField.value.slice(0, -2);
         }
         req.formData.fields[currentField.name] = currentField.value;
-        buffer = buffer.slice(idx + delimiter.length);
+        buffer = buffer.subarray(idx + delimiter.length);
         // 跳过 \r\n
         if (buffer.length >= 2 && buffer[0] === 0x0D && buffer[1] === 0x0A) {
-          buffer = buffer.slice(2);
+          buffer = buffer.subarray(2);
         }
         state = 'HEADERS';
         partHeadersBuf = Buffer.alloc(0);
@@ -1801,7 +1806,7 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
           // 还没结束，写入临时文件
           // 保留尾部回看字节，防止分隔符跨 chunk 截断
           const safeLen = Math.max(0, buffer.length - lookBehind);
-          const writeData = buffer.slice(0, safeLen);
+          const writeData = buffer.subarray(0, safeLen);
           if (!currentFile.stream) {
             currentFile.stream = fs.createWriteStream(currentFile.path);
             // 背压处理：写入流满时暂停请求读取，drain 后恢复
@@ -1827,14 +1832,14 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
             next(err);
             return;
           }
-          buffer = buffer.slice(safeLen);
+          buffer = buffer.subarray(safeLen);
           break;
         }
         // 文件结束
-        const fileData = buffer.slice(0, idx);
+        const fileData = buffer.subarray(0, idx);
         // 去掉文件数据前的 \r\n
         const trimmedData = fileData.length >= 2 && fileData.at(-2) === 0x0D && fileData.at(-1) === 0x0A
-          ? fileData.slice(0, -2)
+          ? fileData.subarray(0, -2)
           : fileData;
 
         if (!currentFile.stream) {
@@ -1862,10 +1867,10 @@ function _parseMultipart(req, boundary, maxFileSize, maxFieldSize, next) {
 
         // 清理上传进度条目
         cleanupOnError = false;
-        buffer = buffer.slice(idx + delimiter.length);
+        buffer = buffer.subarray(idx + delimiter.length);
         // 跳过 \r\n
         if (buffer.length >= 2 && buffer[0] === 0x0D && buffer[1] === 0x0A) {
-          buffer = buffer.slice(2);
+          buffer = buffer.subarray(2);
         }
         state = 'HEADERS';
         partHeadersBuf = Buffer.alloc(0);
@@ -2318,18 +2323,20 @@ class Application extends Router {
       }
 
       if (stat.isDirectory()) {
-        // 目录：查找 index.html
+        // 目录：查找 index.html（异步检查避免阻塞事件循环）
         const indexPath = path.join(fullPath, 'index.html');
-        if (fs.existsSync(indexPath)) {
-          res.sendFile(path.relative(rootPath, indexPath), { root: rootPath });
-          return;
-        }
-        // 展示目录列表
-        if (this.settings.showDir) {
-          this._serveDirectory(req, res, fullPath, requestPath);
-        } else {
-          res.status(404).json({ error: 'Not Found', status: 404 });
-        }
+        fs.stat(indexPath, (idxErr) => {
+          if (!idxErr) {
+            res.sendFile(path.relative(rootPath, indexPath), { root: rootPath });
+            return;
+          }
+          // 展示目录列表
+          if (this.settings.showDir) {
+            this._serveDirectory(req, res, fullPath, requestPath);
+          } else {
+            res.status(404).json({ error: 'Not Found', status: 404 });
+          }
+        });
         return;
       }
 
@@ -2349,35 +2356,37 @@ class Application extends Router {
         return;
       }
 
-      const items = entries.map(entry => {
-        try {
-          // 目录只需名称和类型，文件需要额外 stat 获取大小和修改时间
-          if (entry.isDirectory()) {
-            return { name: entry.name, isDirectory: true, size: 0, modified: '' };
-          }
-          const stat = fs.statSync(path.join(dirPath, entry.name));
-          return {
+      // 异步获取文件信息，避免同步阻塞事件循环
+      const tasks = entries.map(entry => {
+        if (entry.isDirectory()) {
+          return Promise.resolve({ name: entry.name, isDirectory: true, size: 0, modified: '' });
+        }
+        return fs.promises.stat(path.join(dirPath, entry.name))
+          .then(stat => ({
             name: entry.name,
             isDirectory: false,
             size: stat.size,
             modified: stat.mtime.toISOString()
-          };
-        } catch (e) {
-          return null;
-        }
-      }).filter(Boolean);
-
-      // 排序：目录在前
-      items.sort((a, b) => {
-        if (a.isDirectory && !b.isDirectory) return -1;
-        if (!a.isDirectory && b.isDirectory) return 1;
-        return a.name.localeCompare(b.name);
+          }))
+          .catch(() => null);
       });
 
-      // 生成 HTML 目录列表
-      const html = this._renderDirectoryHTML(requestPath, items);
-      res.setHeader('Content-Type', 'text/html; charset=utf-8');
-      res.send(html);
+      Promise.all(tasks).then(results => {
+        const items = results.filter(Boolean);
+        // 排序：目录在前
+        items.sort((a, b) => {
+          if (a.isDirectory && !b.isDirectory) return -1;
+          if (!a.isDirectory && b.isDirectory) return 1;
+          return a.name.localeCompare(b.name);
+        });
+
+        // 生成 HTML 目录列表
+        const html = this._renderDirectoryHTML(requestPath, items);
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.send(html);
+      }).catch(() => {
+        res.status(500).send('Internal Server Error');
+      });
     });
   }
 
@@ -2388,18 +2397,21 @@ class Application extends Router {
     // requestPath 已去掉前导 /，空字符串表示根目录
     // 根目录时显示 '/'，否则显示请求路径
     const displayPath = requestPath || '/';
+    // 构建链接前缀：确保以 / 开头并以 / 结尾，用于生成绝对路径 href
+    const prefix = '/' + (requestPath ? requestPath.replace(/\/+$/, '') + '/' : '');
     let html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Directory: ${escapeHtml(displayPath)}</title>`;
     html += `<style>body{font-family:-apple-system,sans-serif;margin:20px;background:#f5f5f5}h1{font-size:18px;color:#333}table{width:100%;border-collapse:collapse;background:#fff;box-shadow:0 1px 3px rgba(0,0,0,.1)}th{text-align:left;padding:10px 12px;background:#f8f8f8;border-bottom:2px solid #ddd;font-size:13px;color:#666}td{padding:8px 12px;border-bottom:1px solid #eee;font-size:13px}a{color:#0066cc;text-decoration:none}a:hover{text-decoration:underline}.dir{font-weight:bold}.size{color:#999}</style>`;
     html += `</head><body><h1>Directory: ${escapeHtml(displayPath)}</h1><table><tr><th>Name</th><th>Size</th><th>Modified</th></tr>`;
 
-    // 父目录链接：使用相对路径 .. 返回上一级（根目录时不显示）
+    // 父目录链接：使用绝对路径返回上一级（根目录时不显示）
     if (requestPath && requestPath !== '/') {
-      html += `<tr><td><a href=".." class="dir">../</a></td><td class="size">-</td><td>-</td></tr>`;
+      const parentHref = prefix + '..';
+      html += `<tr><td><a href="${escapeHtml(parentHref)}" class="dir">../</a></td><td class="size">-</td><td>-</td></tr>`;
     }
 
     for (const item of items) {
-      // 仅使用文件名作为相对 href，页面 URL 本身已包含目录路径
-      const href = item.name;
+      // 使用绝对路径 href，避免 URL 缺少尾部斜杠时解析错误
+      const href = prefix + item.name;
       const name = item.isDirectory ? item.name + '/' : item.name;
       const size = item.isDirectory ? '-' : fmtSize(item.size);
       const cls = item.isDirectory ? 'dir' : '';
@@ -2414,6 +2426,18 @@ class Application extends Router {
    * 处理 WebSocket 升级请求
    */
   _handleUpgrade(req, socket, head) {
+    // 防御性检查：_wss 在 listen() 中初始化，正常流程不会为 null
+    if (!this._wss) {
+      this._logger.warn('WebSocket server not initialized (call listen() first)');
+      socket.destroy();
+      return;
+    }
+    // 校验 Upgrade 头必须为 websocket
+    if (req.headers['upgrade']?.toLowerCase() !== 'websocket') {
+      this._logger.warn('Invalid upgrade header:', req.headers['upgrade'], 'expected: websocket');
+      socket.destroy();
+      return;
+    }
     const ws = this._wss.handleUpgrade(req, socket, head);
     if (!ws) return;
 
@@ -2599,13 +2623,16 @@ function staticMiddleware(rootPath, options = {}) {
         return next();
       }
       if (stat.isDirectory()) {
-        // 目录：尝试 index.html
+        // 目录：尝试 index.html（异步检查避免阻塞事件循环）
         const indexPath = path.join(fullPath, 'index.html');
-        if (fs.existsSync(indexPath)) {
-          res.sendFile(path.relative(root, indexPath), { root });
-          return;
-        }
-        return next();
+        fs.stat(indexPath, (idxErr) => {
+          if (!idxErr) {
+            res.sendFile(path.relative(root, indexPath), { root });
+            return;
+          }
+          return next();
+        });
+        return;
       }
       res.sendFile(requestPath, { root });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzpong/httpm",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "基于 Node.js 原生模块的单文件、零依赖 HTTP 服务库，兼容 Express API",
   "main": "httpm.js",
   "files": [