nstarter-http-request 0.1.1 → 0.1.3

package/src/client.ts

@@ -36,8 +36,10 @@ import {
 } from './utils';
 import {
     PassThrough,
+    pipeline,
     Readable
 } from 'node:stream';
+import { MetricsTransform } from './stream';
 
 /**
  * HTTP 客户端
@@ -349,7 +351,6 @@ export class NsHttpClient implements IHttpClient {
         ttfb: number
     ): HttpResponse<T> {
         const stream = response.data as any;
-        let bytesTransferred = 0;
 
         // 记录首次响应日志（流开始）
         this.logResponse(options, response, ttfb, {
@@ -366,20 +367,13 @@ export class NsHttpClient implements IHttpClient {
 
         // 所有适配器都返回 Node.js Readable
         const originalStream = stream as Readable;
+        const metrics = new MetricsTransform();
         const wrappedStream = new PassThrough();
 
-        // 监听数据事件统计字节数
-        originalStream.on('data', (chunk: Buffer) => {
-            bytesTransferred += chunk.length;
-            wrappedStream.write(chunk);
-        });
-
-        // 监听结束事件记录日志
-        originalStream.on('end', () => {
+        // 监听 wrappedStream 的结束事件记录日志
+        wrappedStream.on('end', () => {
             const totalDuration = Date.now() - requestStartTime;
-            wrappedStream.end();
-
-            // 记录流完成日志
+            const bytesTransferred = metrics.getBytesTransferred();
             this.logStreamCompleted(
                 options,
                 response,
@@ -389,9 +383,10 @@ export class NsHttpClient implements IHttpClient {
             );
         });
 
-        // 监听错误事件
-        originalStream.on('error', (error: Error) => {
+        // 监听 wrappedStream 的错误事件记录日志
+        wrappedStream.on('error', (error: Error) => {
             const totalDuration = Date.now() - requestStartTime;
+            const bytesTransferred = metrics.getBytesTransferred();
             this.logger.error('Stream read error', {
                 method: options.method,
                 url: options.url,
@@ -400,11 +395,10 @@ export class NsHttpClient implements IHttpClient {
                 bytesTransferred,
                 error: error.message
             });
-            wrappedStream.destroy(error);
         });
 
-        // 使用 pipe 连接流
-        originalStream.pipe(wrappedStream, { end: false });
+        // 使用 pipeline 连接流，自动处理错误传播和资源清理, 要求最后一个参数必须是回调函数
+        pipeline(originalStream, metrics, wrappedStream, () => {});
 
         // 返回包装后的响应
         return {

package/src/const/config.const.ts

@@ -18,8 +18,8 @@ export const MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟)
  */
 export const DEFAULT_SECURITY_CONFIG: SecurityConfig = {
     rejectUnauthorized: true,
-    enableDnsValidation: true,
-    enableIpValidation: true,
+    enableDnsValidation: false,
+    enableIpValidation: false,
     allowPrivateIp: false,
     whitelist: [],
     blacklist: [],

package/src/security/dns.validator.ts

@@ -73,6 +73,23 @@ export class DnsValidator {
                 // IPv6 解析失败
             }
 
+            // resolve4/resolve6 不拼接 search 域，在 ACK 等带集群后缀的环境会 ENOTFOUND；
+            // 失败时回退到 lookup（走 getaddrinfo，会按 resolv.conf 拼 search），与建连时行为一致
+            if (addresses.length === 0) {
+                try {
+                    const lookupResult = await CommonUtils.withTimeout(
+                        dns.lookup(hostname, { all: true }),
+                        this.resolveTimeout,
+                        'DNS lookup timed out'
+                    );
+                    for (const { address } of lookupResult) {
+                        addresses.push(address);
+                    }
+                } catch {
+                    // lookup 也失败，下面统一抛错
+                }
+            }
+
             if (addresses.length === 0) {
                 throw new Error(`Unable to resolve hostname: ${ hostname }`);
             }

package/src/stream/index.ts

@@ -0,0 +1,2 @@
+export { MetricsTransform } from './metrics.transform';
+

package/src/stream/metrics.transform.ts

@@ -0,0 +1,32 @@
+/**
+ * 流处理工具类
+ */
+
+import { Transform } from 'node:stream';
+
+/**
+ * 统计流数据大小的 Transform 流
+ */
+export class MetricsTransform extends Transform {
+    private bytesTransferred: number;
+
+    constructor() {
+        super();
+        this.bytesTransferred = 0;
+    }
+
+    public _transform(chunk: Buffer, encoding: string, callback: () => void): void {
+        this.bytesTransferred += chunk.length;
+        this.push(chunk);
+        callback();
+    }
+
+    /**
+     * 获取已传输的字节数
+     * @returns 已传输的字节数
+     */
+    public getBytesTransferred(): number {
+        return this.bytesTransferred;
+    }
+}
+

package/docs/adapters.md

@@ -1,53 +0,0 @@
-# 适配器切换
-
-## 支持的适配器
-
-本库支持多种 HTTP 客户端适配器，你可以根据场景选择最适合的：
-
-- **Axios** - 适合通用场景，功能丰富，生态完善
-- **Undici** - Node.js 原生高性能 HTTP 客户端，适合高并发场景
-
-## 切换适配器
-
-```typescript
-import { EClientAdapter } from 'nstarter-http-request';
-
-// 使用 Axios 适配器（适合通用场景）
-const axiosClient = new NsHttpClient().withAdapter(EClientAdapter.axios);
-
-// 使用 Undici 适配器（高性能，Node.js 原生）
-const undiciClient = new NsHttpClient().withAdapter(EClientAdapter.undici);
-```
-
-## 在初始化时指定适配器
-
-```typescript
-import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
-
-// 创建客户端实例时指定适配器
-const client = new NsHttpClient({
-  adapter: EClientAdapter.axios,
-  security: {
-    enableDnsValidation: true,
-    enableIpValidation: true,
-    allowPrivateIp: false
-  }
-});
-```
-
-## 适配器选择建议
-
-### 使用 Axios 的场景
-
-- 需要丰富的配置选项
-- 需要拦截器功能
-- 需要广泛的浏览器兼容性（通过 polyfill）
-- 团队熟悉 Axios API
-
-### 使用 Undici 的场景
-
-- 需要极致性能
-- 高并发场景
-- 纯 Node.js 环境
-- 希望减少依赖体积
-

package/docs/configuration.md

@@ -1,149 +0,0 @@
-# 完整配置示例
-
-以下是一个包含所有配置选项的完整示例：
-
-```typescript
-import { NsHttpClient, EClientAdapter } from 'nstarter-http-request';
-
-const client = new NsHttpClient({
-  // 适配器配置
-  adapter: EClientAdapter.axios,
-
-  // 安全配置
-  security: {
-    rejectUnauthorized: true,        // 是否验证 SSL 证书（生产环境建议 true）
-    enableDnsValidation: true,       // 开启 DNS 验证
-    enableIpValidation: true,        // 开启 IP 验证
-    allowPrivateIp: false,           // 是否允许访问私有 IP（内网地址）
-    whitelist: [                     // 域名白名单
-      'trusted.com', '*.trusted.com', // 匹配根域名和一级子域名
-      'api.example.com'               // 仅匹配该域名
-    ],
-    blacklist: [                     // 域名黑名单
-      'malicious.com', '*.malicious.com', // 根域名和一级子域名
-      'unsafe.net'
-    ],
-    dnsCacheTtl: 60000,              // DNS 缓存 TTL（毫秒，默认 60 秒）
-    dnsCacheMaxSize: 500             // DNS 缓存最大条目数（默认 500，使用 LRU 淘汰策略）
-  },
-
-  // 日志配置
-  logging: {
-    enabled: true,                   // 是否启用日志
-    logRequestBody: true,            // 是否记录请求体
-    logResponseBody: true,           // 是否记录响应体
-    bodyMaxLength: 1024 * 1024,      // 请求/响应体最大记录长度（字节，默认 1MB）
-    logger: customLogger,            // 自定义日志记录器（可选，实现 ILogger 接口）
-    httpLogger: customHttpLogger,    // 自定义 HTTP 日志记录器（可选，实现 IHttpClientLogger 接口）
-    filter: {                        // 日志过滤配置
-      methods: ['POST', 'PUT'],      // 只记录指定 HTTP 方法
-      urlPatterns: [                 // 只记录匹配的 URL（支持正则）
-        /\/api\//,
-        'https://api.example.com'
-      ],
-      scenarios: ['payment'],        // 只记录指定业务场景
-      statusCodes: [404, 500],       // 只记录指定状态码
-      statusCodeRanges: [            // 只记录指定状态码范围
-        { min: 400, max: 499 },      // 客户端错误
-        { min: 500, max: 599 }       // 服务端错误
-      ],
-      onlyFailed: false,             // 是否只记录失败请求
-      onlySuccess: false,            // 是否只记录成功请求
-      minDuration: 100,              // 只记录耗时超过指定毫秒的请求
-      customFilter: (options) => {   // 自定义过滤函数
-        return options.request.method === 'POST';
-      }
-    }
-  },
-
-  // 请求配置
-  request: {
-    timeout: 30000,                  // 请求超时（毫秒，默认 30 秒）
-    retries: 3,                      // 重试次数（默认 0）
-    retryDelay: 1000,                // 重试延迟（毫秒，默认 1 秒）
-    maxRedirects: 5,                 // 最大重定向次数（默认 5）
-    maxRequestBodySize: 10 * 1024 * 1024,   // 最大请求体大小（字节，默认 10MB）
-    maxResponseBodySize: 50 * 1024 * 1024,  // 最大响应体大小（字节，默认 50MB）
-    proxy: {                         // HTTP 代理配置（可选，不同于正向代理）
-      host: 'proxy.example.com',
-      port: 8080,
-      protocol: 'http',              // 'http' | 'https'
-      auth: {                        // 代理认证（可选）
-        username: 'user',
-        password: 'pass'
-      }
-    }
-  }
-});
-```
-
-## 配置说明
-
-### 适配器配置
-
-- `adapter`: 指定使用的 HTTP 客户端适配器，可选值：`EClientAdapter.axios` 或 `EClientAdapter.undici`
-
-### 安全配置
-
-详细说明请参考 [安全配置文档](./security.md)
-
-### 日志配置
-
-详细说明请参考 [日志配置文档](./logging.md)
-
-### 请求配置
-
-- `timeout`: 请求超时时间（毫秒）
-- `retries`: 请求失败时的重试次数
-- `retryDelay`: 重试延迟时间（毫秒）
-- `maxRedirects`: 最大重定向次数
-- `maxRequestBodySize`: 最大请求体大小限制（字节）
-- `maxResponseBodySize`: 最大响应体大小限制（字节）
-- `proxy`: HTTP 代理配置（注意：这与正向代理不同，详见 [代理配置文档](./proxy.md)）
-
-## 默认配置值
-
-以下是所有配置项的默认值，如果你不指定某个配置项，将使用以下默认值：
-
-### 适配器配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `adapter` | `EClientAdapter.axios` | 默认使用 Axios 适配器 |
-
-### 安全配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `rejectUnauthorized` | `true` | 默认验证 SSL 证书（生产环境建议保持为 true） |
-| `enableDnsValidation` | `true` | 默认启用 DNS 验证 |
-| `enableIpValidation` | `true` | 默认启用 IP 验证 |
-| `allowPrivateIp` | `false` | 默认禁止访问私有 IP（内网地址） |
-| `whitelist` | `[]` | 默认无白名单 |
-| `blacklist` | `[]` | 默认无黑名单 |
-| `dnsCacheTtl` | `60000` | DNS 缓存 TTL，默认 60 秒（60000 毫秒） |
-| `dnsCacheMaxSize` | `500` | DNS 缓存最大条目数，默认 500，使用 LRU 淘汰策略 |
-
-> **注意**：DNS 缓存最大 TTL 限制为 5 分钟（300000 毫秒），即使设置更大的值也会被限制为 5 分钟，避免过长的缓存时间导致内存积压。
-
-### 日志配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `true` | 默认启用日志 |
-| `logRequestBody` | `true` | 默认记录请求体 |
-| `logResponseBody` | `true` | 默认记录响应体 |
-| `bodyMaxLength` | `1048576` | 请求/响应体最大记录长度，默认 1MB（1024 * 1024 字节） |
-
-### 请求配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `timeout` | `30000` | 请求超时时间，默认 30 秒（30000 毫秒） |
-| `retries` | `0` | 默认不重试 |
-| `retryDelay` | `1000` | 重试延迟时间，默认 1 秒（1000 毫秒） |
-| `maxRedirects` | `5` | 最大重定向次数，默认 5 次 |
-| `maxRequestBodySize` | `10485760` | 最大请求体大小，默认 10MB（10 * 1024 * 1024 字节） |
-| `maxResponseBodySize` | `52428800` | 最大响应体大小，默认 50MB（50 * 1024 * 1024 字节） |
-| `proxy` | `undefined` | 默认不使用 HTTP 代理 |
-

package/docs/logging.md

@@ -1,70 +0,0 @@
-# 日志配置详解
-
-## 自定义日志记录器
-
-```typescript
-import { ILogger } from 'nstarter-http-request';
-
-const customLogger: ILogger = {
-  debug: (msg, meta) => console.debug(msg, meta),
-  info: (msg, meta) => console.info(msg, meta),
-  warn: (msg, meta) => console.warn(msg, meta),
-  error: (msg, meta) => console.error(msg, meta)
-};
-
-const client = new NsHttpClient({
-  logging: { logger: customLogger }
-});
-```
-
-## 日志过滤
-
-```typescript
-const client = new NsHttpClient({
-  logging: {
-    enabled: true,
-    filter: {
-      // 只记录失败的 POST 请求
-      methods: ['POST'],
-      onlyFailed: true,
-      minDuration: 1000  // 且耗时超过 1 秒
-    }
-  }
-});
-```
-
-## 完整日志配置示例
-
-```typescript
-const client = new NsHttpClient({
-  // 日志配置
-  logging: {
-    enabled: true,                   // 是否启用日志
-    logRequestBody: true,            // 是否记录请求体
-    logResponseBody: true,           // 是否记录响应体
-    bodyMaxLength: 1024 * 1024,      // 请求/响应体最大记录长度（字节，默认 1MB）
-    logger: customLogger,            // 自定义日志记录器（可选，实现 ILogger 接口）
-    httpLogger: customHttpLogger,    // 自定义 HTTP 日志记录器（可选，实现 IHttpClientLogger 接口）
-    filter: {                        // 日志过滤配置
-      methods: ['POST', 'PUT'],      // 只记录指定 HTTP 方法
-      urlPatterns: [                 // 只记录匹配的 URL（支持正则）
-        /\/api\//,
-        'https://api.example.com'
-      ],
-      scenarios: ['payment'],        // 只记录指定业务场景
-      statusCodes: [404, 500],       // 只记录指定状态码
-      statusCodeRanges: [            // 只记录指定状态码范围
-        { min: 400, max: 499 },      // 客户端错误
-        { min: 500, max: 599 }       // 服务端错误
-      ],
-      onlyFailed: false,             // 是否只记录失败请求
-      onlySuccess: false,             // 是否只记录成功请求
-      minDuration: 100,              // 只记录耗时超过指定毫秒的请求
-      customFilter: (options) => {   // 自定义过滤函数
-        return options.request.method === 'POST';
-      }
-    }
-  }
-});
-```
-

package/docs/proxy.md

@@ -1,44 +0,0 @@
-# 正向代理配置
-
-## 基础使用
-
-```typescript
-const client = new NsHttpClient()
-  .withForwardProxy({
-    enabled: true,
-    http_proxy: 'http://proxy.example.com:8080',
-    https_proxy: 'https://proxy.example.com:8443',
-    no_proxy: [          // 不使用代理的域名（支持传统模式）
-      'localhost',       // 精确匹配
-      '127.0.0.1',       // 精确匹配
-      '.internal.com',   // 后缀匹配（匹配所有子域名）
-      '.local',          // 后缀匹配
-      '192.168.'         // 前缀匹配（IP地址）
-    ]
-  });
-```
-
-## no_proxy 支持的模式
-
-- `example.com` - 精确匹配该域名
-- `.example.com` - 后缀匹配，匹配所有以 `.example.com` 结尾的域名（包括子域名）
-- `192.168.` - 前缀匹配，主要用于 IP 地址范围匹配
-
-## HTTP 代理配置（不同于正向代理）
-
-```typescript
-const client = new NsHttpClient({
-  request: {
-    proxy: {                         // HTTP 代理配置（可选，不同于正向代理）
-      host: 'proxy.example.com',
-      port: 8080,
-      protocol: 'http',              // 'http' | 'https'
-      auth: {                        // 代理认证（可选）
-        username: 'user',
-        password: 'pass'
-      }
-    }
-  }
-});
-```
-

package/docs/security.md

@@ -1,56 +0,0 @@
-# 安全配置详解
-
-## SSL 证书验证
-
-```typescript
-const client = new NsHttpClient({
-  security: {
-    rejectUnauthorized: true  // 生产环境必须为 true，开发环境可设为 false
-  }
-});
-```
-
-## SSRF 防护
-
-```typescript
-const client = new NsHttpClient({
-  security: {
-    enableDnsValidation: true,     // 启用 DNS 解析验证
-    enableIpValidation: true,      // 启用 IP 地址验证
-    allowPrivateIp: false,         // 禁止访问内网 IP（10.x.x.x, 192.168.x.x, 127.x.x.x 等）
-    whitelist: [                   // 白名单（支持以下模式）
-      'api.example.com',           // 1. 精确匹配
-      '*.safe.com',                // 2. 通配符匹配（只匹配一级子域名）
-      'trusted.com', '*.trusted.com' // 3. 组合使用：匹配根域名和一级子域名
-    ],
-    blacklist: ['malicious.com', '*.malicious.com'] // 黑名单：根域名 + 一级子域名
-  }
-});
-```
-
-## 支持的域名模式
-
-| 模式 | 匹配规则 | 示例 |
-|------|---------|------|
-| `example.com` | 精确匹配 | ✅ `example.com`<br>❌ `api.example.com` |
-| `*.example.com` | 通配符匹配<br>只匹配一级子域名（不含根域名） | ❌ `example.com`<br>✅ `api.example.com`<br>✅ `www.example.com`<br>❌ `v2.api.example.com`（多级不匹配） |
-| 组合使用<br>`['example.com', '*.example.com']` | 精确匹配 + 通配符匹配<br>匹配根域名和一级子域名 | ✅ `example.com`<br>✅ `api.example.com`<br>✅ `www.example.com`<br>❌ `v2.api.example.com`（多级不匹配） |
-
-## DNS 缓存机制
-
-为提升性能，DNS 解析结果会被缓存。缓存使用 [lru-cache](https://www.npmjs.com/package/lru-cache) 实现，具有以下特性：
-
-- ✅ **TTL 自动过期**：缓存条目到期后自动释放内存
-- ✅ **LRU 淘汰策略**：缓存满时自动淘汰最近最少使用的条目
-- ✅ **容量限制**：默认最多缓存 500 个域名解析结果
-- ✅ **可配置**：支持自定义 TTL 和缓存容量
-
-```typescript
-const client = new NsHttpClient({
-  security: {
-    dnsCacheTtl: 60000,       // 缓存时间：60 秒（默认）
-    dnsCacheMaxSize: 500      // 最大缓存条目数（默认）
-  }
-});
-```
-