nstarter-http-request 0.1.0

package/src/client.ts

@@ -0,0 +1,552 @@
+/**
+ * HTTP 客户端核心类
+ */
+
+import type {
+    HttpClientConfig,
+    PartialHttpClientConfig,
+    HttpRequestOptions,
+    HttpResponse,
+    IHttpAdapter,
+    IHttpClient,
+    ILogger,
+    IHttpClientLogger,
+    IForwardProxy,
+    ISsrfGuard,
+    IStreamMetrics
+} from './types';
+import {
+    mergeConfig,
+    validateConfig
+} from './config';
+import { SsrfGuard } from './security';
+import {
+    AxiosAdapter,
+    UndiciAdapter
+} from './adapter';
+import {
+    NullLogger,
+    NsHttpClientLogger
+} from './logger';
+import { EClientAdapter } from './const';
+import { HttpError } from './types';
+import {
+    DomainUtils,
+    TraceContextUtils
+} from './utils';
+import {
+    PassThrough,
+    Readable
+} from 'node:stream';
+
+/**
+ * HTTP 客户端
+ */
+export class NsHttpClient implements IHttpClient {
+    private config: HttpClientConfig;
+    private adapter: IHttpAdapter;
+    private ssrfGuard: ISsrfGuard;
+    private logger: ILogger;
+    private httpLogger?: IHttpClientLogger;
+    private forwardProxy?: IForwardProxy;
+
+    constructor(userConfig: PartialHttpClientConfig = {}) {
+        // 合并配置
+        this.config = mergeConfig(userConfig);
+
+        // 验证配置
+        validateConfig(this.config);
+
+        // 初始化日志记录器
+        this.logger = this.initLogger();
+        this.httpLogger = this.initHttpLogger();
+
+        // 初始化 SSRF 防护
+        this.ssrfGuard = new SsrfGuard(this.config.security);
+
+        // 初始化适配器
+        this.adapter = this.initAdapter();
+
+        this.logger.debug('NsHttpClient initialized', {
+            adapter: this.config.adapter,
+            security: {
+                enableDnsValidation: this.config.security.enableDnsValidation,
+                enableIpValidation: this.config.security.enableIpValidation,
+                allowPrivateIp: this.config.security.allowPrivateIp
+            }
+        });
+    }
+
+    /**
+     * 从配置创建 HTTP 客户端
+     * @param config
+     */
+    public static fromHttpClientConfig(config: PartialHttpClientConfig = {}): NsHttpClient {
+        return new NsHttpClient(config);
+    }
+
+    /**
+     * 挂载适配器.
+     * @param adapter
+     */
+    public withAdapter(adapter: EClientAdapter): this {
+        this.config.adapter = adapter;
+        this.adapter = this.initAdapter();
+        return this;
+    }
+
+    /**
+     * 挂载正向代理.
+     * @param proxy
+     */
+    public withForwardProxy(proxy: IForwardProxy): this {
+        this.forwardProxy = proxy;
+        this.logger.info('Forward proxy configured', {
+            enabled: proxy.enabled,
+            http_proxy: proxy.http_proxy,
+            https_proxy: proxy.https_proxy,
+            no_proxy_count: proxy.no_proxy?.length || 0
+        });
+        return this;
+    }
+
+    /**
+     * 初始化日志记录器
+     */
+    private initLogger(): ILogger {
+        if (!this.config.logging.enabled) {
+            return new NullLogger();
+        }
+
+        return this.config.logging.logger || new NullLogger();
+    }
+
+    /**
+     * 初始化 HTTP 客户端日志记录器
+     */
+    private initHttpLogger(): IHttpClientLogger | undefined {
+        if (!this.config.logging.enabled) {
+            return undefined;
+        }
+
+        // 如果用户提供了自定义的 httpLogger，直接使用
+        if (this.config.logging.httpLogger) {
+            return this.config.logging.httpLogger;
+        }
+
+        // 否则，使用 NsHttpClientLogger 包装通用的 logger
+        return NsHttpClientLogger.create(
+            this.logger,
+            this.config.logging.filter,
+            {
+                logRequestBody: this.config.logging.logRequestBody,
+                logResponseBody: this.config.logging.logResponseBody,
+                bodyMaxLength: this.config.logging.bodyMaxLength
+            }
+        );
+    }
+
+    /**
+     * 初始化适配器
+     */
+    private initAdapter(): IHttpAdapter {
+        const adapter = this.config.adapter === EClientAdapter.axios
+            ? new AxiosAdapter(this.config.request, this.config.security, this.logger)
+            : new UndiciAdapter(this.config.request, this.config.security, this.logger);
+
+        if (!adapter.isAvailable()) {
+            throw new Error(
+                `Adapter "${ this.config.adapter }" is not available. ` +
+                `Please install it: npm install ${ this.config.adapter }`
+            );
+        }
+
+        return adapter;
+    }
+
+    /**
+     * 发送 HTTP 请求
+     * @param options 请求选项
+     * @returns 响应结果
+     */
+    public async request<T = any>(options: HttpRequestOptions): Promise<HttpResponse<T>> {
+        const startTime = Date.now();
+
+        try {
+            // 安全验证
+            const { safeUrl, result: ssrfResult } = await this.ssrfGuard.validateAndGetSafeUrl(options.url);
+
+            this.logger.debug('URL validation passed', {
+                originalUrl: options.url,
+                safeUrl,
+                resolvedIps: ssrfResult.resolvedIps,
+                scenario: options.scenario
+            });
+
+            // 使用安全的 URL 发起请求
+            const safeOptions: HttpRequestOptions = {
+                ...options,
+                url: safeUrl
+            };
+
+            // 如果 URL 被替换为 IP，需要设置 Host 头
+            if (ssrfResult.safeIp && ssrfResult.hostname !== ssrfResult.safeIp) {
+                safeOptions.headers = {
+                    ...safeOptions.headers,
+                    Host: ssrfResult.hostname
+                };
+            }
+
+            // 处理 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)
+                    });
+                }
+            }
+
+            // 应用正向代理配置
+            if (this.forwardProxy) {
+                this.applyForwardProxy(safeOptions);
+            }
+
+            // 发起请求
+            const response = await this.adapter.request<T>(safeOptions);
+
+            // 首次响应时间（TTFB）
+            const ttfb = Date.now() - startTime;
+
+            // 如果是流式响应，包装流对象以追踪完整生命周期
+            if (options.responseType === 'stream' && this.isStreamResponse(response.data)) {
+                return this.wrapStreamResponse(safeOptions, response, startTime, ttfb);
+            }
+
+            // 记录非流式响应日志
+            this.logResponse(safeOptions, response, ttfb);
+
+            return response;
+        } catch (error) {
+            // 记录错误日志
+            this.logError(options, error, Date.now() - startTime);
+            throw error;
+        }
+    }
+
+    /**
+     * 便捷方法：GET 请求
+     */
+    public async get<T = any>(
+        url: string,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url'>>
+    ): Promise<HttpResponse<T>> {
+        return this.request<T>({ ...options, method: 'GET', url });
+    }
+
+    /**
+     * 便捷方法：POST 请求
+     */
+    public async post<T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ): Promise<HttpResponse<T>> {
+        return this.request<T>({ ...options, method: 'POST', url, body });
+    }
+
+    /**
+     * 便捷方法：PUT 请求
+     */
+    public async put<T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ): Promise<HttpResponse<T>> {
+        return this.request<T>({ ...options, method: 'PUT', url, body });
+    }
+
+    /**
+     * 便捷方法：DELETE 请求
+     */
+    public async delete<T = any>(
+        url: string,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url'>>
+    ): Promise<HttpResponse<T>> {
+        return this.request<T>({ ...options, method: 'DELETE', url });
+    }
+
+    /**
+     * 便捷方法：PATCH 请求
+     */
+    public async patch<T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ): Promise<HttpResponse<T>> {
+        return this.request<T>({ ...options, method: 'PATCH', url, body });
+    }
+
+    /**
+     * 记录响应日志
+     */
+    private logResponse(
+        options: HttpRequestOptions,
+        response: HttpResponse,
+        duration: number,
+        streamMetrics?: IStreamMetrics
+    ): void {
+        if (!this.httpLogger) {
+            return;
+        }
+
+        // 计算实际重试次数
+        const retryCount = options.retries ?? this.config.request.retries;
+
+        this.httpLogger.logSuccess({
+            request: {
+                method: options.method,
+                url: options.url,
+                headers: options.headers,
+                body: options.body,
+                scenario: options.scenario,
+                meta: options.meta
+            },
+            response,
+            duration,
+            retryCount,
+            streamMetrics
+        });
+    }
+
+    /**
+     * 判断响应数据是否为流对象（Node.js Readable）
+     */
+    private isStreamResponse(data: any): boolean {
+        // undici 和 axios 都返回 Node.js Readable
+        return data instanceof Readable;
+    }
+
+    /**
+     * 包装流式响应，追踪流的完整生命周期
+     */
+
+    /* eslint-disable max-lines-per-function */
+    private wrapStreamResponse<T>(
+        options: HttpRequestOptions,
+        response: HttpResponse<T>,
+        requestStartTime: number,
+        ttfb: number
+    ): HttpResponse<T> {
+        const stream = response.data as any;
+        let bytesTransferred = 0;
+
+        // 记录首次响应日志（流开始）
+        this.logResponse(options, response, ttfb, {
+            ttfb,
+            completed: false
+        });
+
+        this.logger.debug('Stream response started', {
+            method: options.method,
+            url: options.url,
+            ttfb,
+            status: response.status
+        });
+
+        // 所有适配器都返回 Node.js Readable
+        const originalStream = stream as Readable;
+        const wrappedStream = new PassThrough();
+
+        // 监听数据事件统计字节数
+        originalStream.on('data', (chunk: Buffer) => {
+            bytesTransferred += chunk.length;
+            wrappedStream.write(chunk);
+        });
+
+        // 监听结束事件记录日志
+        originalStream.on('end', () => {
+            const totalDuration = Date.now() - requestStartTime;
+            wrappedStream.end();
+
+            // 记录流完成日志
+            this.logStreamCompleted(
+                options,
+                response,
+                ttfb,
+                totalDuration,
+                bytesTransferred
+            );
+        });
+
+        // 监听错误事件
+        originalStream.on('error', (error: Error) => {
+            const totalDuration = Date.now() - requestStartTime;
+            this.logger.error('Stream read error', {
+                method: options.method,
+                url: options.url,
+                ttfb,
+                totalDuration,
+                bytesTransferred,
+                error: error.message
+            });
+            wrappedStream.destroy(error);
+        });
+
+        // 使用 pipe 连接流
+        originalStream.pipe(wrappedStream, { end: false });
+
+        // 返回包装后的响应
+        return {
+            ...response,
+            data: wrappedStream as T
+        };
+    }
+
+    /**
+     * 记录流完成日志
+     */
+    private logStreamCompleted(
+        options: HttpRequestOptions,
+        response: HttpResponse,
+        ttfb: number,
+        totalDuration: number,
+        bytesTransferred: number
+    ): void {
+        // 记录流完成日志
+        this.logResponse(options, response, totalDuration, {
+            ttfb,
+            completed: true,
+            totalDuration,
+            bytesTransferred
+        });
+
+        this.logger.debug('Stream response completed', {
+            method: options.method,
+            url: options.url,
+            ttfb,
+            totalDuration,
+            streamDuration: totalDuration - ttfb,
+            bytesTransferred,
+            throughput: bytesTransferred > 0 && totalDuration > ttfb
+                ? `${ (bytesTransferred / 1024 / ((totalDuration - ttfb) / 1000)).toFixed(2) } KB/s`
+                : 'N/A'
+        });
+    }
+
+    /**
+     * 记录错误日志
+     */
+    private logError(options: HttpRequestOptions, error: any, duration: number): void {
+        if (!this.httpLogger) {
+            return;
+        }
+
+        // 计算实际重试次数
+        const retryCount = options.retries ?? this.config.request.retries;
+
+        const httpError = error instanceof HttpError ? error : undefined;
+
+        this.httpLogger.logFailed({
+            request: {
+                method: options.method,
+                url: options.url,
+                headers: options.headers,
+                body: options.body,
+                scenario: options.scenario,
+                meta: options.meta
+            },
+            error: error instanceof Error ? error : new Error(String(error)),
+            errorCode: httpError?.code || 'UNKNOWN_ERROR',
+            status: httpError?.status,
+            response: httpError?.response,
+            duration,
+            retryCount
+        });
+    }
+
+    /**
+     * 应用正向代理配置
+     * @param options 请求选项
+     */
+    private applyForwardProxy(options: HttpRequestOptions): void {
+        if (!this.forwardProxy || !this.forwardProxy.enabled) {
+            return;
+        }
+
+        const { https_proxy, http_proxy, no_proxy } = this.forwardProxy;
+
+        // 解析目标 URL
+        const targetUrl = new URL(options.url);
+        const hostname = targetUrl.hostname;
+
+        // 检查 no_proxy 规则（使用传统匹配模式）
+        const noProxyRegExps = DomainUtils.createLegacyDomainMatchers(no_proxy ?? []);
+        if (noProxyRegExps.length > 0 && hostname) {
+            for (const noProxyRegex of noProxyRegExps) {
+                if (noProxyRegex.test(hostname)) {
+                    this.logger.debug('Skip proxy for no_proxy matched host', {
+                        hostname,
+                        pattern: noProxyRegex.source
+                    });
+                    return;
+                }
+            }
+        }
+
+        const protocol = targetUrl.protocol || 'http:';
+        const isHttps = /https:?/.test(protocol);
+        const proxyUrl = isHttps ? https_proxy : http_proxy;
+
+        if (!proxyUrl) {
+            this.logger.warn('Forward proxy enabled but proxy URL not configured', {
+                protocol
+            });
+            return;
+        }
+
+        // 将代理信息附加到请求元数据中，由适配器处理
+        options.meta = {
+            ...options.meta,
+            __forwardProxy: {
+                proxyUrl,
+                isHttps,
+                protocol
+            }
+        };
+
+        this.logger.debug('Applied forward proxy', {
+            url: options.url,
+            proxyUrl,
+            isHttps
+        });
+    }
+
+
+    /**
+     * 清空 DNS 缓存
+     */
+    public clearDnsCache(): void {
+        this.ssrfGuard.clearDnsCache();
+        this.logger.debug('DNS cache cleared');
+    }
+
+    /**
+     * 获取 DNS 缓存大小
+     * @returns 缓存条目数量
+     */
+    public getDnsCacheSize(): number {
+        return this.ssrfGuard.getDnsCacheSize();
+    }
+}
+

package/src/config.ts

@@ -0,0 +1,86 @@
+import type {
+    HttpClientConfig,
+    PartialHttpClientConfig
+} from './types';
+import {
+    DEFAULT_HTTP_CLIENT_CONFIG,
+    DEFAULT_LOGGING_CONFIG,
+    DEFAULT_REQUEST_CONFIG,
+    DEFAULT_SECURITY_CONFIG,
+    MAX_DNS_CACHE_TTL
+} from './const';
+
+/**
+ * 合并配置
+ * @param userConfig 用户配置
+ * @returns 完整配置
+ */
+export function mergeConfig(userConfig: PartialHttpClientConfig = {}): HttpClientConfig {
+    return {
+        adapter: userConfig.adapter ?? DEFAULT_HTTP_CLIENT_CONFIG.adapter,
+        security: {
+            ...DEFAULT_SECURITY_CONFIG,
+            ...userConfig.security
+        },
+        logging: {
+            ...DEFAULT_LOGGING_CONFIG,
+            ...userConfig.logging
+        },
+        request: {
+            ...DEFAULT_REQUEST_CONFIG,
+            ...userConfig.request
+        }
+    };
+}
+
+/**
+ * 验证配置
+ * @param config 配置
+ * @throws {Error} 配置无效时抛出错误
+ */
+export function validateConfig(config: HttpClientConfig): void {
+    // 验证适配器
+    if (!['axios', 'undici'].includes(config.adapter)) {
+        throw new Error(`Invalid adapter: ${ config.adapter }. Must be 'axios' or 'undici'.`);
+    }
+
+    // 验证安全配置
+    if (config.security.dnsCacheTtl < 0) {
+        throw new Error('DNS cache TTL must be non-negative.');
+    }
+
+    if (config.security.dnsCacheTtl > MAX_DNS_CACHE_TTL) {
+        throw new Error(`DNS cache TTL must not exceed ${ MAX_DNS_CACHE_TTL }ms (24 hours) to prevent memory buildup.`);
+    }
+
+    // 验证请求配置
+    if (config.request.timeout <= 0) {
+        throw new Error('Timeout must be positive.');
+    }
+
+    if (config.request.retries < 0) {
+        throw new Error('Retries must be non-negative.');
+    }
+
+    if (config.request.retryDelay < 0) {
+        throw new Error('Retry delay must be non-negative.');
+    }
+
+    if (config.request.maxRedirects < 0) {
+        throw new Error('Max redirects must be non-negative.');
+    }
+
+    if (config.request.maxRequestBodySize <= 0) {
+        throw new Error('Max request body size must be positive.');
+    }
+
+    if (config.request.maxResponseBodySize <= 0) {
+        throw new Error('Max response body size must be positive.');
+    }
+
+    // 验证日志配置
+    if (config.logging.bodyMaxLength <= 0) {
+        throw new Error('Body max length must be positive.');
+    }
+}
+

package/src/const/config.const.ts

@@ -0,0 +1,60 @@
+import type {
+    HttpClientConfig,
+    LoggingConfig,
+    RequestConfig,
+    SecurityConfig
+} from '../types';
+import { EClientAdapter } from './enum.const';
+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 DEFAULT_SECURITY_CONFIG: SecurityConfig = {
+    rejectUnauthorized: true,
+    enableDnsValidation: true,
+    enableIpValidation: true,
+    allowPrivateIp: false,
+    whitelist: [],
+    blacklist: [],
+    dnsCacheTtl: DEFAULT_DNS_CACHE_TTL,
+    dnsCacheMaxSize: DEFAULT_DNS_CACHE_MAX_SIZE
+};
+
+/**
+ * 默认日志配置
+ */
+export const DEFAULT_LOGGING_CONFIG: LoggingConfig = {
+    enabled: true,
+    logRequestBody: true,
+    logResponseBody: true,
+    bodyMaxLength: 1024 * 1024 // 1MB
+};
+
+/**
+ * 默认请求配置
+ */
+export const DEFAULT_REQUEST_CONFIG: RequestConfig = {
+    timeout: 30000, // 30 秒
+    retries: 0,
+    retryDelay: 1000, // 1 秒
+    maxRedirects: 5,
+    maxRequestBodySize: 10 * 1024 * 1024, // 10MB
+    maxResponseBodySize: 50 * 1024 * 1024 // 50MB
+};
+
+/**
+ * 默认 HTTP 客户端配置
+ */
+export const DEFAULT_HTTP_CLIENT_CONFIG: HttpClientConfig = {
+    adapter: EClientAdapter.axios,
+    security: DEFAULT_SECURITY_CONFIG,
+    logging: DEFAULT_LOGGING_CONFIG,
+    request: DEFAULT_REQUEST_CONFIG
+};

package/src/const/dns.const.ts

@@ -0,0 +1,15 @@
+/**
+ * 默认 DNS 缓存 TTL（毫秒）- 60 秒
+ */
+export const DEFAULT_DNS_CACHE_TTL = 60000;
+
+/**
+ * 默认 DNS 解析超时时间（毫秒）- 3 秒
+ */
+export const DEFAULT_DNS_RESOLVE_TIMEOUT = 3000;
+
+/**
+ * 默认 DNS 缓存最大条目数
+ */
+export const DEFAULT_DNS_CACHE_MAX_SIZE = 500;
+