nstarter-http-request 0.1.0

package/dist/types/types/security.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 安全和验证相关类型定义
+ */
+import type { SecurityConfig } from './config';
+/**
+ * DNS 解析结果
+ */
+export interface DnsResult {
+    /** 域名 */
+    hostname: string;
+    /** 解析到的 IP 地址列表 */
+    addresses: string[];
+    /** 解析时间戳 */
+    timestamp: number;
+    /** TTL */
+    ttl: number;
+}
+/**
+ * IP 验证结果
+ */
+export interface IpValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** IP 地址 */
+    ip: string;
+    /** 是否为私有 IP */
+    isPrivate: boolean;
+    /** 是否为回环地址 */
+    isLoopback: boolean;
+    /** 是否为 Link-Local */
+    isLinkLocal: boolean;
+    /** 是否为组播地址 */
+    isMulticast: boolean;
+    /** 是否为保留地址 */
+    isReserved: boolean;
+    /** 原因（当 valid 为 false 时） */
+    reason?: string;
+}
+/**
+ * URL 验证结果
+ */
+export interface UrlValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** URL */
+    url: string;
+    /** 是否在白名单中 */
+    inWhitelist: boolean;
+    /** 是否在黑名单中 */
+    inBlacklist: boolean;
+    /** 原因（当 valid 为 false 时） */
+    reason?: string;
+}
+/**
+ * SSRF 防护结果
+ */
+export interface SsrfGuardResult {
+    /** 是否通过验证 */
+    passed: boolean;
+    /** 原始 URL */
+    originalUrl: string;
+    /** 解析后的主机名 */
+    hostname: string;
+    /** 解析后的 IP 地址列表（如果进行了 DNS 解析） */
+    resolvedIps?: string[];
+    /** 安全的 IP 地址（如果进行了 DNS 解析且通过验证） */
+    safeIp?: string;
+    /** 失败原因 */
+    reason?: string;
+}
+/**
+ * SSRF 防护接口
+ */
+export interface ISsrfGuard {
+    /**
+     * 验证 URL 是否安全
+     * @param url 要验证的 URL
+     * @returns 验证结果
+     */
+    validate: (url: string) => Promise<SsrfGuardResult>;
+    /**
+     * 验证并返回安全的 URL
+     * @param url 要验证的 URL
+     * @returns 安全的 URL 和验证结果
+     * @throws {SecurityError} 验证失败时抛出错误
+     */
+    validateAndGetSafeUrl: (url: string) => Promise<{
+        safeUrl: string;
+        result: SsrfGuardResult;
+    }>;
+    /**
+     * 更新配置
+     * @param config 新的安全配置
+     */
+    updateConfig: (config: Partial<SecurityConfig>) => void;
+    /**
+     * 清空 DNS 缓存
+     */
+    clearDnsCache: () => void;
+    /**
+     * 获取 DNS 缓存大小
+     * @returns 缓存条目数量
+     */
+    getDnsCacheSize: () => number;
+    /**
+     * 清理过期的 DNS 缓存
+     */
+    cleanExpiredDnsCache: () => void;
+    /**
+     * 获取当前配置
+     * @returns 安全配置副本
+     */
+    getConfig: () => SecurityConfig;
+}
+//# sourceMappingURL=security.d.ts.map

package/dist/types/types/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../src/types/security.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,SAAS;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,eAAe;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,qBAAqB;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,UAAU;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAGD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,aAAa;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,qBAAqB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAE9F;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAExD;;OAEG;IACH,aAAa,EAAE,MAAM,IAAI,CAAC;IAE1B;;;OAGG;IACH,eAAe,EAAE,MAAM,MAAM,CAAC;IAE9B;;OAEG;IACH,oBAAoB,EAAE,MAAM,IAAI,CAAC;IAEjC;;;OAGG;IACH,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC"}

package/dist/types/types/trace.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Trace 标志位
+ */
+export declare enum TraceFlags {
+    /** 未采样 */
+    NONE = 0,
+    /** 已采样 */
+    SAMPLED = 1
+}
+/**
+ * Traceparent 接口
+ */
+export interface TraceParent {
+    /** 版本号（当前固定为 00） */
+    version: string;
+    /** Trace ID（32位十六进制字符串） */
+    traceId: string;
+    /** Parent ID/Span ID（16位十六进制字符串） */
+    parentId: string;
+    /** Trace 标志位（2位十六进制字符串） */
+    traceFlags: string;
+}
+/**
+ * Traceparent 生成选项
+ */
+export interface TraceParentOptions {
+    /** 自定义 Trace ID（不提供则自动生成） */
+    traceId?: string;
+    /** 自定义 Parent ID（不提供则自动生成） */
+    parentId?: string;
+    /** 是否采样（默认 true） */
+    sampled?: boolean;
+}
+//# sourceMappingURL=trace.d.ts.map

package/dist/types/types/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../../src/types/trace.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,UAAU;IAClB,UAAU;IACV,IAAI,IAAO;IACX,UAAU;IACV,OAAO,IAAO;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/types/utils/common.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 延迟函数
+ * @param ms 延迟毫秒数
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * 超时函数
+ * @param promise 原始 Promise
+ * @param ms 超时毫秒数
+ * @param message 超时错误消息
+ * @returns 超时后的 Promise
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+//# sourceMappingURL=common.d.ts.map

package/dist/types/utils/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/utils/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,SAAwB,GAAG,OAAO,CAAC,CAAC,CAAC,CAU3G"}

package/dist/types/utils/domain.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 根据域名模式列表生成正则表达式数组（通配符模式）
+ * 支持规则：
+ *  1. 通配符匹配 eg `*.example.com`（只匹配一级子域名，不包括根域名和多级子域名）
+ *  2. 精确匹配 eg `example.com`（仅匹配指定域名）
+ *
+ * @param patterns 域名模式列表
+ * @returns 正则表达式数组
+ *
+ * @example
+ * ```typescript
+ * const regexps = createDomainMatchers(['example.com', '*.example.com']);
+ * regexps[0].test('example.com');          // true - 精确匹配
+ * regexps[1].test('api.example.com');      // true - 通配符匹配一级子域名
+ * regexps[1].test('test.api.example.com'); // false - 不匹配多级子域名
+ * regexps[1].test('example.com');          // false - 不匹配根域名
+ * ```
+ */
+export declare const createDomainMatchers: (patterns: string[]) => RegExp[];
+/**
+ * 根据域名模式列表生成正则表达式数组（传统模式，用于正向代理等场景）
+ * @TODO 需要存量用户跑完正向代理兼容后切换到通配符模式.
+ * 支持规则：
+ *  1. 完全匹配 eg `www.example.com`
+ *  2. 后缀匹配 eg `.example.com`（匹配所有子域名）
+ *  3. 前缀匹配 eg `172.168.0.`（主要用于 IP 地址匹配）
+ *
+ * @param patterns 域名模式列表
+ * @returns 正则表达式数组
+ *
+ * @example
+ * ```typescript
+ * const regexps = createLegacyDomainMatchers(['example.com', '.example.com']);
+ * regexps[0].test('example.com');  // true - 完全匹配
+ * regexps[1].test('api.example.com');  // true - 后缀匹配
+ * ```
+ */
+export declare const createLegacyDomainMatchers: (patterns: string[]) => RegExp[];
+//# sourceMappingURL=domain.d.ts.map

package/dist/types/utils/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/utils/domain.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,KAAG,MAAM,EAmB/D,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,MAAM,EAAE,KAAG,MAAM,EAiBrE,CAAC"}

package/dist/types/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * as IpRangeUtils from './ip.range';
+export * as CommonUtils from './common';
+export * as DomainUtils from './domain';
+export * as TraceContextUtils from './trace.context';
+export { TraceContext } from './trace.context';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,WAAW,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,WAAW,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,iBAAiB,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/utils/ip.range.d.ts

@@ -0,0 +1,61 @@
+/**
+ * IP 地址范围工具
+ */
+import type { CompiledIpv4Range, CompiledIpv6Range } from '../types';
+/**
+ * 将 IPv4 地址转换为数字
+ */
+export declare function ipv4ToNumber(ip: string): number;
+/**
+ * 预编译 IPv4 CIDR 范围
+ * @param cidr CIDR 表示法，如 "192.168.0.0/16"
+ */
+export declare function compileIpv4Range(cidr: string): CompiledIpv4Range;
+/**
+ * 检查 IPv4 地址是否在预编译的范围内（高性能版本）
+ * @param ip IP 地址
+ * @param compiledRange 预编译的范围
+ */
+export declare function isIpv4InCompiledRange(ip: string, compiledRange: CompiledIpv4Range): boolean;
+/**
+ * 将 IPv6 地址转换为 BigInt 数组（高 64 位和低 64 位）
+ */
+export declare function ipv6ToBigInt(ip: string): [bigint, bigint];
+/**
+ * 标准化 IPv6 地址（展开缩写）
+ */
+export declare function normalizeIpv6(ip: string): string;
+/**
+ * 预编译 IPv6 CIDR 范围
+ * @param cidr CIDR 表示法，如 "fe80::/10"
+ */
+export declare function compileIpv6Range(cidr: string): CompiledIpv6Range;
+/**
+ * 检查 IPv6 地址是否在预编译的范围内（高性能版本）
+ * @param ip IPv6 地址
+ * @param compiledRange 预编译的范围
+ */
+export declare function isIpv6InCompiledRange(ip: string, compiledRange: CompiledIpv6Range): boolean;
+/**
+ * 批量预编译 IPv4 CIDR 范围列表
+ * @param cidrs CIDR 范围列表
+ */
+export declare function compileIpv4Ranges(cidrs: string[]): CompiledIpv4Range[];
+/**
+ * 批量预编译 IPv6 CIDR 范围列表
+ * @param cidrs CIDR 范围列表
+ */
+export declare function compileIpv6Ranges(cidrs: string[]): CompiledIpv6Range[];
+/**
+ * 检查 IPv4 地址是否匹配任一预编译范围（高性能版本）
+ * @param ip IPv4 地址
+ * @param compiledRanges 预编译的范围列表
+ */
+export declare function isIpv4InAnyCompiledRange(ip: string, compiledRanges: CompiledIpv4Range[]): boolean;
+/**
+ * 检查 IPv6 地址是否匹配任一预编译范围（高性能版本）
+ * @param ip IPv6 地址
+ * @param compiledRanges 预编译的范围列表
+ */
+export declare function isIpv6InAnyCompiledRange(ip: string, compiledRanges: CompiledIpv6Range[]): boolean;
+//# sourceMappingURL=ip.range.d.ts.map

package/dist/types/utils/ip.range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip.range.d.ts","sourceRoot":"","sources":["../../../src/utils/ip.range.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACR,iBAAiB,EACjB,iBAAiB,EACpB,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAgBhE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAG3F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CA6BhD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA+BhE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAW3F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAEtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAQjG;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAejG"}

package/dist/types/utils/trace.context.d.ts

@@ -0,0 +1,106 @@
+/**
+ * W3C Trace Context 工具
+ * 实现 W3C Trace Context 规范：https://www.w3.org/TR/trace-context/
+ */
+import type { TraceParent, TraceParentOptions } from '../types';
+/**
+ * 生成符合 W3C 规范的 Trace ID（32位十六进制）
+ * @returns Trace ID
+ */
+export declare function generateTraceId(): string;
+/**
+ * 生成符合 W3C 规范的 Span ID（16位十六进制）
+ * @returns Span ID
+ */
+export declare function generateSpanId(): string;
+/**
+ * 验证 Trace ID 格式
+ * @param traceId Trace ID
+ * @returns 是否有效
+ */
+export declare function isValidTraceId(traceId: string): boolean;
+/**
+ * 验证 Span ID 格式
+ * @param spanId Span ID
+ * @returns 是否有效
+ */
+export declare function isValidSpanId(spanId: string): boolean;
+/**
+ * 验证 Trace Flags 格式
+ * @param flags Trace Flags
+ * @returns 是否有效
+ */
+export declare function isValidTraceFlags(flags: string): boolean;
+/**
+ * 生成 traceparent 头值
+ * @param options 生成选项
+ * @returns traceparent 字符串
+ */
+export declare function generateTraceParent(options?: TraceParentOptions): string;
+/**
+ * 解析 traceparent 头值
+ * @param traceparent traceparent 字符串
+ * @returns 解析后的对象，解析失败返回 null
+ */
+export declare function parseTraceParent(traceparent: string): TraceParent | null;
+/**
+ * 验证 traceparent 头值是否符合规范
+ * @param traceparent traceparent 字符串
+ * @returns 是否有效
+ */
+export declare function isValidTraceParent(traceparent: string): boolean;
+/**
+ * 从现有 traceparent 创建子 span
+ * @param parentTraceParent 父级 traceparent 字符串
+ * @param sampled 是否采样（不提供则继承父级）
+ * @returns 新的 traceparent 字符串
+ */
+export declare function createChildSpan(parentTraceParent: string, sampled?: boolean): string;
+/**
+ * 检查 traceparent 是否已采样
+ * @param traceparent traceparent 字符串
+ * @returns 是否采样
+ */
+export declare function isSampled(traceparent: string): boolean;
+/**
+ * Trace Context 工具类
+ */
+export declare class TraceContext {
+    /**
+     * 生成 traceparent
+     */
+    static generate: typeof generateTraceParent;
+    /**
+     * 解析 traceparent
+     */
+    static parse: typeof parseTraceParent;
+    /**
+     * 验证 traceparent
+     */
+    static isValid: typeof isValidTraceParent;
+    /**
+     * 创建子 span
+     */
+    static createChild: typeof createChildSpan;
+    /**
+     * 检查是否采样
+     */
+    static isSampled: typeof isSampled;
+    /**
+     * 生成 Trace ID
+     */
+    static generateTraceId: typeof generateTraceId;
+    /**
+     * 生成 Span ID
+     */
+    static generateSpanId: typeof generateSpanId;
+    /**
+     * 验证 Trace ID
+     */
+    static isValidTraceId: typeof isValidTraceId;
+    /**
+     * 验证 Span ID
+     */
+    static isValidSpanId: typeof isValidSpanId;
+}
+//# sourceMappingURL=trace.context.d.ts.map

package/dist/types/utils/trace.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.context.d.ts","sourceRoot":"","sources":["../../../src/utils/trace.context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACR,WAAW,EACX,kBAAkB,EACrB,MAAM,UAAU,CAAC;AA6BlB;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAe5E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA8BxE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAgBpF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQtD;AAED;;GAEG;AACH,qBAAa,YAAY;IACrB;;OAEG;IACH,OAAc,QAAQ,6BAAuB;IAE7C;;OAEG;IACH,OAAc,KAAK,0BAAoB;IAEvC;;OAEG;IACH,OAAc,OAAO,4BAAsB;IAE3C;;OAEG;IACH,OAAc,WAAW,yBAAmB;IAE5C;;OAEG;IACH,OAAc,SAAS,mBAAa;IAEpC;;OAEG;IACH,OAAc,eAAe,yBAAmB;IAEhD;;OAEG;IACH,OAAc,cAAc,wBAAkB;IAE9C;;OAEG;IACH,OAAc,cAAc,wBAAkB;IAE9C;;OAEG;IACH,OAAc,aAAa,uBAAiB;CAC/C"}

package/docs/adapters.md

@@ -0,0 +1,53 @@
+# 适配器切换
+
+## 支持的适配器
+
+本库支持多种 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

@@ -0,0 +1,149 @@
+# 完整配置示例
+
+以下是一个包含所有配置选项的完整示例：
+
+```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 代理 |
+