nstarter-http-request 0.1.11 → 0.1.13

package/src/adapter/undici.adapter.ts

@@ -4,10 +4,12 @@
 
 import type {
     HttpRequestOptions,
-    HttpResponse,
-    ResponseType,
+    HttpResponse
+} from '../types';
+import {
+    HttpError,
+    ResponseTooLargeError
 } from '../types';
-import { HttpError } from '../types';
 import { BaseHttpAdapter } from './base';
 import undici, {
     Agent,
@@ -16,6 +18,7 @@ import undici, {
 } from 'undici';
 import { STATUS_CODES } from 'http';
 import { EClientAdapter } from '../const';
+import { RedirectUtils } from '../utils';
 
 interface RequestTimeoutState {
     signal?: AbortSignal;
@@ -50,7 +53,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
         const headers = this.prepareHeaders(options.headers);
         const body = this.prepareBody(options.body, headers);
         const timeoutState = this.createRequestTimeoutState(options);
-        const dispatcher = this.buildDispatcher(options, timeoutState.timeout);
+        const dispatcher = this.buildDispatcher(options);
         const undiciOptions = this.buildUndiciOptions(options, headers, body, dispatcher, timeoutState);
 
         try {
@@ -69,7 +72,8 @@ export class UndiciAdapter extends BaseHttpAdapter {
                 timeoutState.cleanup();
             }
 
-            const data = await this.readResponseBody<T>(response, options.responseType);
+            // 读取过程中会按 maxResponseBodySize 提前拒绝/中断，超限时不会把完整响应体读入内存
+            const data = await this.readResponseBody<T>(response, options);
 
             const httpResponse: HttpResponse<T> = {
                 status: response.statusCode,
@@ -79,7 +83,6 @@ export class UndiciAdapter extends BaseHttpAdapter {
                 config: options
             };
 
-            this.ensureResponseBodySize(httpResponse, options.responseType);
             this.ensureSuccessStatus(httpResponse);
 
             return httpResponse;
@@ -96,6 +99,8 @@ export class UndiciAdapter extends BaseHttpAdapter {
             throw this.handleUndiciError(error, options);
         } finally {
             timeoutState.cleanup();
+            // buildDispatcher 为每个请求单独创建 Agent/ProxyAgent，用完需要关闭，否则连接池与 keep-alive 连接会一直保留。
+            dispatcher?.close().catch(() => undefined);
         }
     }
 
@@ -153,15 +158,15 @@ export class UndiciAdapter extends BaseHttpAdapter {
     /**
      * 构建 Dispatcher（代理或 TLS 配置）
      * @param options 请求选项
-     * @param timeout 请求总超时时间
      */
-    private buildDispatcher(options: HttpRequestOptions, timeout?: number): Dispatcher | undefined {
+    private buildDispatcher(options: HttpRequestOptions): Dispatcher | undefined {
         let dispatcher: Dispatcher | undefined;
+        const timeout = this.resolveUndiciTimeout(options);
 
         // 如果 rejectUnauthorized 为 false，需要创建 Agent 来设置 TLS 选项
         if (!this.securityConfig.rejectUnauthorized) {
             dispatcher = new Agent({
-                ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
+                connectTimeout: timeout,
                 connect: {
                     rejectUnauthorized: false
                 }
@@ -198,7 +203,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
 
         const agent = new ProxyAgent({
             uri: proxyUrl,
-            ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
+            connectTimeout: timeout,
             connect: {
                 rejectUnauthorized: this.securityConfig.rejectUnauthorized
             }
@@ -222,7 +227,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
     private createForwardProxyAgent(proxyUrl: string, timeout?: number): ProxyAgent {
         const agent = new ProxyAgent({
             uri: proxyUrl,
-            ...(this.isPositiveTimeout(timeout) ? { connectTimeout: timeout } : {}),
+            connectTimeout: timeout,
             connect: {
                 rejectUnauthorized: this.securityConfig.rejectUnauthorized
             }
@@ -246,7 +251,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
         dispatcher?: Dispatcher,
         timeoutState?: RequestTimeoutState
     ): Parameters<typeof undici.request>[1] {
-        const timeout = this.resolveTimeout(options);
+        const timeout = this.resolveUndiciTimeout(options);
         return {
             method: options.method as Dispatcher.HttpMethod,
             headers,
@@ -267,6 +272,7 @@ export class UndiciAdapter extends BaseHttpAdapter {
         const timeout = this.resolveTimeout(options);
         if (!this.isPositiveTimeout(timeout)) {
             return {
+                timeout,
                 timedOut: false,
                 cleanup: () => {}
             };
@@ -293,10 +299,18 @@ export class UndiciAdapter extends BaseHttpAdapter {
     /**
      * 获取请求级超时时间。
      */
-    private resolveTimeout(options: HttpRequestOptions): number {
+    private resolveTimeout(options: HttpRequestOptions): number | undefined {
         return options.timeout ?? this.requestConfig.timeout;
     }
 
+    /**
+     * 获取传给 undici 的阶段超时时间。0 用于内部禁用 undici 默认阶段超时。
+     */
+    private resolveUndiciTimeout(options: HttpRequestOptions): number {
+        const timeout = this.resolveTimeout(options);
+        return this.isPositiveTimeout(timeout) ? timeout : 0;
+    }
+
     /**
      * 判断超时时间是否启用。
      */
@@ -329,10 +343,14 @@ export class UndiciAdapter extends BaseHttpAdapter {
     }
 
     /**
-     * 按 axios 默认行为处理非 2xx 状态码。
+     * 2xx 和 304 作为成功结果返回。undici 未跟跳的 3xx 交回调用方。
      */
     private ensureSuccessStatus(response: HttpResponse): void {
-        if (response.status >= 200 && response.status < 300) {
+        if (
+            (response.status >= 200 && response.status < 300)
+            || response.status === 304
+            || RedirectUtils.isRedirectStatus(response.status)
+        ) {
             return;
         }
 
@@ -346,119 +364,122 @@ export class UndiciAdapter extends BaseHttpAdapter {
     }
 
     /**
-     * 按 axios maxContentLength 行为限制非流式响应体大小。
+     * 解析 Content-Length 响应头。仅接受合法的非负整数，重复头/非法值视为未知。
      */
-    private ensureResponseBodySize(response: HttpResponse, responseType?: ResponseType): void {
-        if (responseType === 'stream') {
-            return;
-        }
-        const maxResponseBodySize = this.requestConfig.maxResponseBodySize;
-        if (
-            typeof maxResponseBodySize !== 'number' ||
-            !Number.isFinite(maxResponseBodySize) ||
-            maxResponseBodySize <= 0
-        ) {
-            // NsHttpClient 会先做配置合并和校验；这里防御直接实例化 Adapter 的异常配置。
-            return;
-        }
-        const bodySize = this.getBodySize(response.data);
-        if (bodySize <= maxResponseBodySize) {
-            return;
+    private parseContentLength(value: string | string[] | undefined): number | undefined {
+        if (typeof value !== 'string' || !/^\d+$/.test(value.trim())) {
+            return undefined;
         }
-        throw new HttpError(
-            `maxContentLength size of ${ maxResponseBodySize } exceeded`,
-            'ERR_BAD_RESPONSE',
-            response.status,
-            response,
-            response.config
-        );
+        const length = Number(value.trim());
+        return Number.isSafeInteger(length) ? length : undefined;
     }
 
     /**
-     * 计算已读取响应体的字节大小。
+     * 丢弃未读完的响应体并终止下载。
+     * undici 的 BodyReadable.destroy() 不带错误时会以 RequestAbortedError 触发 error 事件，
+     * 没有监听器会变成未捕获异常，因此先挂空监听器。
      */
-    private getBodySize(body: any): number {
-        if (body === undefined || body === null) {
-            return 0;
-        }
-        if (Buffer.isBuffer(body)) {
-            return body.byteLength;
-        }
-        if (body instanceof ArrayBuffer) {
-            return body.byteLength;
-        }
-        if (ArrayBuffer.isView(body)) {
-            return body.byteLength;
+    private discardBody(response: Dispatcher.ResponseData): void {
+        response.body.on('error', () => undefined);
+        response.body.destroy();
+    }
+
+    /**
+     * 带大小上限地读取非流式响应体。
+     *
+     * 1. Content-Length 预检：响应头已声明超限时，不读取响应体，直接销毁并拒绝。
+     * 2. 逐分块累计字节数，累计值超过上限（等于上限放行）立即销毁响应流并拒绝，后续数据不再下载；
+     *    该行为对齐 axios（Node http 适配器）的 maxContentLength。
+     */
+    private async readBodyWithLimit(response: Dispatcher.ResponseData, options: HttpRequestOptions): Promise<Buffer> {
+        const maxRespBodySize = this.resolveMaxResponseBodySize();
+
+        // HEAD / 204 / 304 没有响应体，其 Content-Length 描述的是对应实体而不是本次响应体：
+        // 不能用于预检；服务端携带时 undici 还会一直等待并不存在的响应体，因此不进入读取，直接丢弃。
+        if (options.method === 'HEAD' || response.statusCode === 204 || response.statusCode === 304) {
+            this.discardBody(response);
+            return Buffer.alloc(0);
         }
-        if (typeof Blob !== 'undefined' && body instanceof Blob) {
-            return body.size;
+
+        if (maxRespBodySize !== undefined) {
+            const contentLength = this.parseContentLength(response.headers['content-length']);
+            if (contentLength !== undefined && contentLength > maxRespBodySize) {
+                this.discardBody(response);
+                throw new ResponseTooLargeError(maxRespBodySize, options, response.statusCode);
+            }
         }
-        if (typeof body === 'string') {
-            return Buffer.byteLength(body);
+
+        const chunks: Buffer[] = [];
+        let total = 0;
+        for await (const chunk of response.body) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.byteLength;
+            if (maxRespBodySize !== undefined && total > maxRespBodySize) {
+                this.discardBody(response);
+                throw new ResponseTooLargeError(maxRespBodySize, options, response.statusCode);
+            }
+            chunks.push(buffer);
         }
-        return Buffer.byteLength(JSON.stringify(body));
+        return Buffer.concat(chunks, total);
+    }
+
+    /**
+     * 基于已读取（已受大小限制）的字节构造 Response，复用运行时的 blob/formData 解析逻辑。
+     */
+    private toFetchResponse(buffer: Buffer, response: Dispatcher.ResponseData): Response {
+        const contentType = response.headers['content-type'];
+        return new Response(buffer, {
+            headers: typeof contentType === 'string' ? { 'content-type': contentType } : undefined
+        });
     }
 
     /**
      * 读取响应体
      * @param response Undici 响应对象
-     * @param responseType 响应类型
+     * @param options 请求选项
      */
-    private async readResponseBody<T>(response: Dispatcher.ResponseData, responseType?: ResponseType): Promise<T> {
+    private async readResponseBody<T>(response: Dispatcher.ResponseData, options: HttpRequestOptions): Promise<T> {
+        if (options.responseType === 'stream') {
+            // undici 返回 BodyReadable (继承自 Node.js Readable)，流式响应由调用方自行消费，不受 maxResponseBodySize 限制
+            return response.body as T;
+        }
+
         try {
-            switch (responseType) {
+            const buffer = await this.readBodyWithLimit(response, options);
+            const decoder = new TextDecoder();
+            switch (options.responseType) {
                 case 'text': {
-                    return (await response.body.text()) as T;
+                    return decoder.decode(buffer) as T;
                 }
                 case 'arraybuffer': {
-                    return Buffer.from(await response.body.arrayBuffer()) as T;
-                }
-                case 'stream': {
-                    // undici 返回 BodyReadable (继承自 Node.js Readable)
-                    return response.body as T;
+                    return buffer as T;
                 }
                 case 'blob': {
-                    return (await response.body.blob()) as T;
+                    return (await this.toFetchResponse(buffer, response).blob()) as T;
                 }
                 case 'formdata': {
-                    return (await response.body.formData()) as T;
-                }
-                case 'json': {
-                    return await this.readJsonResponseBody<T>(response);
+                    return (await this.toFetchResponse(buffer, response).formData()) as T;
                 }
+                case 'json':
                 default: {
-                    const text = await response.body.text();
+                    // 按 axios 的默认兼容行为：空响应体或非 JSON 文本不应让成功状态码请求因为解析失败变成异常
+                    const text = decoder.decode(buffer);
                     try {
                         return JSON.parse(text) as T;
                     } catch {
-                        // 如果不是有效的 JSON，返回原文本
                         return text as T;
                     }
                 }
-
             }
         } catch (error) {
+            // 响应体超限错误需要原样抛出，保留错误码、文案与不可重试标记
+            if (error instanceof ResponseTooLargeError) {
+                throw error;
+            }
             throw new Error(`Failed to read response body: ${ error instanceof Error ? error.message : String(error) }`);
         }
     }
 
-    /**
-     * 按 axios 的默认兼容行为读取 JSON 响应。
-     * 空响应体或非 JSON 文本不应让成功状态码请求因为解析失败变成异常。
-     */
-    private async readJsonResponseBody<T>(response: Dispatcher.ResponseData): Promise<T> {
-        const text = await response.body.text();
-        if (!text) {
-            return text as T;
-        }
-
-        try {
-            return JSON.parse(text) as T;
-        } catch {
-            return text as T;
-        }
-    }
-
     /**
      * 获取状态文本
      * @param statusCode 状态码

package/src/client.ts

@@ -32,6 +32,7 @@ import { EClientAdapter } from './const';
 import { HttpError } from './types';
 import {
     DomainUtils,
+    RedirectUtils,
     TraceContextUtils
 } from './utils';
 import {
@@ -39,6 +40,7 @@ import {
     pipeline,
     Readable
 } from 'node:stream';
+import { finished } from 'node:stream/promises';
 import { MetricsTransform } from './stream';
 
 type ForwardProxyDecision = {
@@ -189,84 +191,120 @@ export class NsHttpClient implements IHttpClient {
         const startTime = Date.now();
 
         try {
-            const forwardProxyDecision = this.resolveForwardProxyDecision(options.url);
-
-            // 安全验证
-            const { safeUrl, result: ssrfResult } = await this.ssrfGuard.validateAndGetSafeUrl(
-                options.url,
-                {
-                    skipDnsValidation: forwardProxyDecision.shouldProxy,
-                    skipDnsValidationReason: forwardProxyDecision.shouldProxy ? 'forward_proxy' : undefined
-                }
-            );
+            return await this.safeRequest<T>(options, this.config.request.maxRedirects);
+        } catch (error) {
+            // 记录错误日志
+            this.logError(options, error, Date.now() - startTime);
+            throw error;
+        }
+    }
 
-            this.logger.debug('URL validation passed', {
-                originalUrl: options.url,
-                safeUrl,
-                resolvedIps: ssrfResult.resolvedIps,
-                dnsValidationSkipped: ssrfResult.dnsValidationSkipped,
-                dnsValidationSkipReason: ssrfResult.dnsValidationSkipReason,
-                scenario: options.scenario
-            });
+    /**
+     * 
+     * @param options 请求选项
+     * @param remainedRedirects 剩余可重定向次数
+     * @returns 响应结果
+     */
+    private async safeRequest<T>(options: HttpRequestOptions, remainedRedirects: number): Promise<HttpResponse<T>> {
+        const startTime = Date.now();
+        const forwardProxyDecision = this.resolveForwardProxyDecision(options.url);
 
-            if (ssrfResult.dnsValidationSkipped && forwardProxyDecision.shouldProxy) {
-                this.logger.debug('Skipped target DNS validation because request uses forward proxy', {
-                    hostname: forwardProxyDecision.hostname,
-                    proxyUrl: forwardProxyDecision.proxyUrl
-                });
+        // 安全验证
+        const { safeUrl, result: ssrfResult } = await this.ssrfGuard.validateAndGetSafeUrl(
+            options.url,
+            {
+                skipDnsValidation: forwardProxyDecision.shouldProxy,
+                skipDnsValidationReason: forwardProxyDecision.shouldProxy ? 'forward_proxy' : undefined
             }
+        );
 
-            // 使用安全的 URL 发起请求
-            const safeOptions: HttpRequestOptions = {
-                ...options,
-                url: safeUrl
-            };
+        this.logger.debug('URL validation passed', {
+            originalUrl: options.url,
+            safeUrl,
+            resolvedIps: ssrfResult.resolvedIps,
+            dnsValidationSkipped: ssrfResult.dnsValidationSkipped,
+            dnsValidationSkipReason: ssrfResult.dnsValidationSkipReason,
+            scenario: options.scenario
+        });
 
-            // 处理 W3C Trace Context traceparent 头
-            if (options.traceparent) {
-                // 验证 traceparent 格式
-                if (!TraceContextUtils.isValidTraceParent(options.traceparent)) {
-                    this.logger.warn('Invalid traceparent format, ignoring', {
-                        traceparent: options.traceparent
-                    });
-                } else {
-                    safeOptions.headers = {
-                        ...safeOptions.headers,
-                        traceparent: options.traceparent
-                    };
+        if (ssrfResult.dnsValidationSkipped && forwardProxyDecision.shouldProxy) {
+            this.logger.debug('Skipped target DNS validation because request uses forward proxy', {
+                hostname: forwardProxyDecision.hostname,
+                proxyUrl: forwardProxyDecision.proxyUrl
+            });
+        }
 
-                    this.logger.debug('Traceparent header added', {
-                        traceparent: options.traceparent,
-                        sampled: TraceContextUtils.isSampled(options.traceparent)
-                    });
-                }
-            }
+        // 使用安全的 URL 发起请求
+        const safeOptions: HttpRequestOptions = {
+            ...options,
+            url: safeUrl
+        };
 
-            // 应用正向代理配置
-            if (this.forwardProxy) {
-                this.applyForwardProxy(safeOptions, forwardProxyDecision);
+        // 处理 W3C Trace Context traceparent 头
+        if (options.traceparent) {
+            // 验证 traceparent 格式
+            if (!TraceContextUtils.isValidTraceParent(options.traceparent)) {
+                this.logger.warn('Invalid traceparent format, ignoring', {
+                    traceparent: options.traceparent
+                });
+            } else {
+                safeOptions.headers = {
+                    ...safeOptions.headers,
+                    traceparent: options.traceparent
+                };
+
+                this.logger.debug('Traceparent header added', {
+                    traceparent: options.traceparent,
+                    sampled: TraceContextUtils.isSampled(options.traceparent)
+                });
             }
+        }
 
-            // 发起请求
-            const response = await this.adapter.request<T>(safeOptions);
+        // 应用正向代理配置
+        if (this.forwardProxy) {
+            this.applyForwardProxy(safeOptions, forwardProxyDecision);
+        }
 
-            // 首次响应时间（TTFB）
-            const ttfb = Date.now() - startTime;
+        // 发起请求
+        const response = await this.adapter.request<T>(safeOptions);
 
-            // 如果是流式响应，包装流对象以追踪完整生命周期
-            if (options.responseType === 'stream' && this.isStreamResponse(response.data)) {
-                return this.wrapStreamResponse(safeOptions, response, startTime, ttfb);
+        // 需要重定向时，继续跟跳
+        if (RedirectUtils.isRedirectStatus(response.status)) {
+            try {
+                if (remainedRedirects === undefined || remainedRedirects <= 0) {
+                    throw new Error('max redirects');
+                }
+                const redirectOptions = RedirectUtils.buildRedirectOptions(
+                    safeOptions,
+                    response,
+                    this.adapter.name,
+                    this.config.request.timeout
+                );
+                if (redirectOptions) {
+                    RedirectUtils.consumeRedirectTimeout(redirectOptions, startTime);
+                    // 下一跳前，把中间响应的流先丢掉，以免占用连接
+                    await this.discardResponseStream(response);
+                    const nextRemainedRedirects = remainedRedirects - 1;
+                    return await this.safeRequest<T>(redirectOptions, nextRemainedRedirects);
+                }
+            } catch (error) {
+                await this.discardResponseStream(response);
+                throw error;
             }
+        }
 
-            // 记录非流式响应日志
-            this.logResponse(safeOptions, response, ttfb);
+        // 首次响应时间（TTFB）
+        const ttfb = Date.now() - startTime;
 
-            return response;
-        } catch (error) {
-            // 记录错误日志
-            this.logError(options, error, Date.now() - startTime);
-            throw error;
+        // 如果是流式响应，包装流对象以追踪完整生命周期
+        if (options.responseType === 'stream' && this.isStreamResponse(response.data)) {
+            return this.wrapStreamResponse(safeOptions, response, startTime, ttfb);
         }
+
+        // 记录非流式响应日志
+        this.logResponse(safeOptions, response, ttfb);
+
+        return response;
     }
 
     /**
@@ -354,6 +392,19 @@ export class NsHttpClient implements IHttpClient {
         });
     }
 
+    /**
+     * 销毁不再交给调用方的响应流
+     */
+    private async discardResponseStream(response: HttpResponse): Promise<void> {
+        const data = response.data;
+        if (!(data instanceof Readable) || data.destroyed) {
+            return;
+        }
+        const done = finished(data);
+        data.destroy();
+        await done.catch(() => undefined);
+    }
+
     /**
      * 判断响应数据是否为流对象（Node.js Readable）
      */

package/src/config.ts

@@ -70,7 +70,7 @@ export function validateConfig(config: HttpClientConfig): void {
     }
 
     // 验证请求配置
-    if (config.request.timeout <= 0) {
+    if (config.request.timeout !== undefined && config.request.timeout <= 0) {
         throw new Error('Timeout must be positive.');
     }
 

package/src/const/config.const.ts

@@ -11,7 +11,7 @@ import { DEFAULT_DNS_CACHE_TTL, DEFAULT_DNS_CACHE_MAX_SIZE } from './dns.const';
  * DNS 缓存最大 TTL（毫秒）- 5 分钟
  * 避免过长的缓存时间导致内存积压
  */
-export const MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟) 
+export const MAX_DNS_CACHE_TTL = 5 * 60 * 1000; // 300000ms (5 分钟)
 
 /**
  * 默认安全配置
@@ -41,7 +41,6 @@ export const DEFAULT_LOGGING_CONFIG: LoggingConfig = {
  * 默认请求配置
  */
 export const DEFAULT_REQUEST_CONFIG: RequestConfig = {
-    timeout: 30000, // 30 秒
     retries: 0,
     retryDelay: 1000, // 1 秒
     maxRedirects: 5,
@@ -49,6 +48,13 @@ export const DEFAULT_REQUEST_CONFIG: RequestConfig = {
     maxResponseBodySize: 50 * 1024 * 1024 // 50MB
 };
 
+/**
+ * 响应体大小预检的线上长度容差比例。
+ * axios 的 onDownloadProgress.total 是压缩后的 Content-Length，而 maxContentLength 按解压后计数；
+ * 不可压缩数据经 gzip 等压缩后可能略大于解压大小，预检仅在超过上限该比例时提前中止。
+ */
+export const MAX_RESPONSE_SIZE_TOLERANCE_RATIO = 0.01;
+
 /**
  * 默认 HTTP 客户端配置
  */

package/src/types/config.ts

@@ -68,8 +68,8 @@ export interface LoggingConfig {
  * 请求配置
  */
 export interface RequestConfig {
-    /** 超时时间（毫秒） */
-    timeout: number;
+    /** 超时时间（毫秒）；不配置表示不限制请求超时 */
+    timeout?: number;
     /** 重试次数 */
     retries: number;
     /** 重试延迟（毫秒） */
@@ -107,4 +107,3 @@ export interface PartialHttpClientConfig {
     logging?: Partial<LoggingConfig>;
     request?: Partial<RequestConfig>;
 }
-