nstarter-http-request 0.1.0

package/src/types/adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * 适配器相关类型定义
+ */
+
+import type {
+    HttpRequestOptions,
+    HttpResponse
+} from './request_response';
+import type { RequestConfig } from './config';
+import type { EClientAdapter } from '../const';
+
+/**
+ * HTTP 适配器接口
+ */
+export interface IHttpAdapter {
+    /** 适配器名称 */
+    readonly name: EClientAdapter;
+
+    /**
+     * 发送 HTTP 请求
+     * @param options 请求选项
+     * @returns 响应结果
+     */
+    request: <T = any>(options: HttpRequestOptions) => Promise<HttpResponse<T>>;
+
+    /**
+     * 检查适配器是否可用
+     * @returns 是否可用
+     */
+    isAvailable: () => boolean;
+
+    /**
+     * 更新适配器配置
+     * @param config 请求配置
+     */
+    updateConfig: (config: Partial<RequestConfig>) => void;
+}
+

package/src/types/client.ts

@@ -0,0 +1,119 @@
+/**
+ * 客户端相关类型定义
+ */
+
+import type {
+    HttpRequestOptions,
+    HttpResponse
+} from './request_response';
+import type { EClientAdapter } from '../const';
+
+/**
+ * 正向代理配置
+ */
+export interface IForwardProxy {
+    enabled: boolean;
+    https_proxy: string;
+    http_proxy: string;
+    no_proxy: string[];
+}
+
+/**
+ * HTTP 客户端接口
+ */
+export interface IHttpClient {
+    /**
+     * 挂载适配器.
+     * @param adapter
+     * @returns this
+     */
+    withAdapter: (adapter: EClientAdapter) => this;
+
+    /**
+     * 挂载正向代理.
+     * @param proxy
+     * @returns this
+     */
+    withForwardProxy: (proxy: IForwardProxy) => this;
+
+    /**
+     * 发送 HTTP 请求
+     * @param options 请求选项
+     * @returns 响应结果
+     */
+    request: <T = any>(options: HttpRequestOptions) => Promise<HttpResponse<T>>;
+
+    /**
+     * GET 请求
+     * @param url 请求 URL
+     * @param options 其他请求选项
+     * @returns 响应结果
+     */
+    get: <T = any>(
+        url: string,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url'>>
+    ) => Promise<HttpResponse<T>>;
+
+    /**
+     * POST 请求
+     * @param url 请求 URL
+     * @param body 请求体
+     * @param options 其他请求选项
+     * @returns 响应结果
+     */
+    post: <T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ) => Promise<HttpResponse<T>>;
+
+    /**
+     * PUT 请求
+     * @param url 请求 URL
+     * @param body 请求体
+     * @param options 其他请求选项
+     * @returns 响应结果
+     */
+    put: <T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ) => Promise<HttpResponse<T>>;
+
+    /**
+     * DELETE 请求
+     * @param url 请求 URL
+     * @param options 其他请求选项
+     * @returns 响应结果
+     */
+    delete: <T = any>(
+        url: string,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url'>>
+    ) => Promise<HttpResponse<T>>;
+
+    /**
+     * PATCH 请求
+     * @param url 请求 URL
+     * @param body 请求体
+     * @param options 其他请求选项
+     * @returns 响应结果
+     */
+    patch: <T = any>(
+        url: string,
+        body?: any,
+        options?: Partial<Omit<HttpRequestOptions, 'method' | 'url' | 'body'>>
+    ) => Promise<HttpResponse<T>>;
+
+
+    /**
+     * 清空 DNS 缓存
+     */
+    clearDnsCache: () => void;
+
+    /**
+     * 获取 DNS 缓存大小
+     * @returns 缓存条目数量
+     */
+    getDnsCacheSize: () => number;
+}
+

package/src/types/config.ts

@@ -0,0 +1,110 @@
+/**
+ * 配置相关类型定义
+ */
+
+import type {
+    ILogger,
+    IHttpClientLogger,
+    LogFilterConfig,
+} from './logger';
+import type { EClientAdapter } from '../const';
+
+/**
+ * 代理配置
+ */
+export interface ProxyConfig {
+    host: string;
+    port: number;
+    protocol: 'http' | 'https';
+    auth?: {
+        username: string,
+        password: string
+    };
+}
+
+/**
+ * 安全配置
+ */
+export interface SecurityConfig {
+    /** 证书校验 **/
+    rejectUnauthorized: boolean;
+    /** 启用 DNS 验证 */
+    enableDnsValidation: boolean;
+    /** 启用 IP 地址验证 */
+    enableIpValidation: boolean;
+    /** 允许访问私有 IP */
+    allowPrivateIp: boolean;
+    /** 域名白名单（支持通配符，如 *.example.com 匹配一级子域名） */
+    whitelist: string[];
+    /** 域名黑名单（支持通配符，如 *.example.com 匹配一级子域名） */
+    blacklist: string[];
+    /** DNS 缓存 TTL（毫秒） */
+    dnsCacheTtl: number;
+    /** DNS 缓存最大条目数 */
+    dnsCacheMaxSize: number;
+}
+
+/**
+ * 日志配置
+ */
+export interface LoggingConfig {
+    /** 启用日志 */
+    enabled: boolean;
+    /** 自定义日志记录器（通用） */
+    logger?: ILogger;
+    /** 自定义 HTTP 客户端日志记录器 */
+    httpLogger?: IHttpClientLogger;
+    /** 记录请求体 */
+    logRequestBody: boolean;
+    /** 记录响应体 */
+    logResponseBody: boolean;
+    /** 响应体最大记录长度（字节） */
+    bodyMaxLength: number;
+    /** 日志过滤器配置 */
+    filter?: LogFilterConfig;
+}
+
+/**
+ * 请求配置
+ */
+export interface RequestConfig {
+    /** 超时时间（毫秒） */
+    timeout: number;
+    /** 重试次数 */
+    retries: number;
+    /** 重试延迟（毫秒） */
+    retryDelay: number;
+    /** 代理配置 */
+    proxy?: ProxyConfig;
+    /** 最大重定向次数 */
+    maxRedirects: number;
+    /** 最大请求体大小（字节） */
+    maxRequestBodySize: number;
+    /** 最大响应体大小（字节） */
+    maxResponseBodySize: number;
+}
+
+/**
+ * HTTP 客户端配置
+ */
+export interface HttpClientConfig {
+    /** 适配器类型 */
+    adapter: EClientAdapter;
+    /** 安全配置 */
+    security: SecurityConfig;
+    /** 日志配置 */
+    logging: LoggingConfig;
+    /** 请求配置 */
+    request: RequestConfig;
+}
+
+/**
+ * 部分 HTTP 客户端配置（用于创建实例时）
+ */
+export interface PartialHttpClientConfig {
+    adapter?: EClientAdapter;
+    security?: Partial<SecurityConfig>;
+    logging?: Partial<LoggingConfig>;
+    request?: Partial<RequestConfig>;
+}
+

package/src/types/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * 错误类型定义
+ */
+
+import type { HttpRequestOptions, HttpResponse } from './request_response';
+
+/**
+ * HTTP 错误
+ */
+export class HttpError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+        public readonly status?: number,
+        public readonly response?: HttpResponse,
+        public readonly request?: HttpRequestOptions
+    ) {
+        super(message);
+        this.name = 'HttpError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * 安全验证错误
+ */
+export class SecurityError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+        public readonly url?: string
+    ) {
+        super(message);
+        this.name = 'SecurityError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+

package/src/types/index.ts

@@ -0,0 +1,27 @@
+// 请求和响应
+export * from './request_response';
+
+// 配置相关
+export * from './config';
+
+// 错误类
+export * from './errors';
+
+// 安全和验证
+export * from './security';
+
+// IP 相关
+export * from './ip';
+
+// 日志相关
+export * from './logger';
+
+// 适配器相关
+export * from './adapter';
+
+// 客户端相关
+export * from './client';
+
+// trace 相关
+export * from './trace';
+

package/src/types/ip.ts

@@ -0,0 +1,34 @@
+/**
+ * IP 相关类型定义
+ */
+
+/**
+ * 预编译的 IPv4 CIDR 范围
+ */
+export interface CompiledIpv4Range {
+    /** 网络地址（数字形式） */
+    network: number;
+    /** 子网掩码（数字形式） */
+    mask: number;
+    /** 原始 CIDR 字符串 */
+    cidr: string;
+}
+
+/**
+ * 预编译的 IPv6 CIDR 范围
+ */
+export interface CompiledIpv6Range {
+    /** 网络地址高 64 位 */
+    networkHigh: bigint;
+    /** 网络地址低 64 位 */
+    networkLow: bigint;
+    /** 子网掩码高 64 位 */
+    maskHigh: bigint;
+    /** 子网掩码低 64 位 */
+    maskLow: bigint;
+    /** CIDR 前缀长度 */
+    prefix: number;
+    /** 原始 CIDR 字符串 */
+    cidr: string;
+}
+

package/src/types/logger.ts

@@ -0,0 +1,150 @@
+/**
+ * 日志相关类型定义
+ */
+
+import type {
+    HttpRequestOptions,
+    HttpResponse
+} from './request_response';
+
+/**
+ * 日志记录器接口
+ */
+export interface ILogger {
+    debug: (message: string, meta?: Record<string, any>) => void;
+    info: (message: string, meta?: Record<string, any>) => void;
+    warn: (message: string, meta?: Record<string, any>) => void;
+    error: (message: string, meta?: Record<string, any>) => void;
+}
+
+/**
+ * 请求失败选项
+ */
+export interface IResFailedOptions {
+    /** 是否成功 */
+    isSuccess: false;
+    /** 时间戳 */
+    timestamp: number;
+    /** 请求选项 */
+    request: HttpRequestOptions;
+    /** 错误信息 */
+    error: Error;
+    /** 错误码 */
+    errorCode?: string;
+    /** HTTP 状态码（如果有响应） */
+    status?: number;
+    /** 响应对象（如果有） */
+    response?: HttpResponse;
+    /** 请求耗时（毫秒） */
+    duration?: number;
+    /** 重试次数 */
+    retryCount?: number;
+}
+
+/**
+ * 流式响应相关指标.
+ */
+export interface IStreamMetrics {
+    /** 首次响应时间（TTFB - Time To First Byte，毫秒） */
+    ttfb: number;
+    /** 流是否已完成 */
+    completed: boolean;
+    /** 流完成总耗时（毫秒，仅在流完成时有值） */
+    totalDuration?: number;
+    /** 流传输的字节数（如果可统计） */
+    bytesTransferred?: number;
+}
+
+/**
+ * 请求成功选项
+ */
+export interface IResSuccessOptions {
+    /** 是否成功 */
+    isSuccess: true;
+    /** 时间戳 */
+    timestamp: number;
+    /** 请求选项 */
+    request: HttpRequestOptions;
+    /** 响应对象 */
+    response: HttpResponse;
+    /** 请求耗时（毫秒） */
+    duration: number;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 流式响应相关指标（仅当 responseType 为 stream 时） */
+    streamMetrics?: IStreamMetrics;
+}
+
+/**
+ * 日志过滤器接口
+ */
+export interface ILogFilter {
+    /**
+     * 判断是否应该记录此日志
+     * @param options 日志选项（成功或失败）
+     * @returns 是否应该记录
+     */
+    shouldLog: (options: IResSuccessOptions | IResFailedOptions) => boolean;
+}
+
+/**
+ * 日志过滤器配置
+ */
+export interface LogFilterConfig {
+    /** 只记录特定 HTTP 方法 */
+    methods?: string[];
+    /** 只记录特定 URL 模式（支持正则表达式） */
+    urlPatterns?: (string | RegExp)[];
+    /** 只记录特定场景 */
+    scenarios?: string[];
+    /** 只记录特定状态码 */
+    statusCodes?: number[];
+    /** 只记录特定状态码范围 */
+    statusCodeRanges?: Array<{ min: number, max: number }>;
+    /** 只记录失败的请求 */
+    onlyFailed?: boolean;
+    /** 只记录成功的请求 */
+    onlySuccess?: boolean;
+    /** 只记录耗时超过指定毫秒数的请求 */
+    minDuration?: number;
+    /** 自定义过滤函数 */
+    customFilter?: (options: IResSuccessOptions | IResFailedOptions) => boolean;
+}
+
+/**
+ * HTTP 客户端日志记录器
+ */
+export interface IHttpClientLogger {
+    /**
+     * 记录失败的请求
+     * @param resOptions 请求失败选项
+     */
+    logFailed: (
+        resOptions: Omit<IResFailedOptions, 'isSuccess' | 'timestamp'>
+    ) => void;
+
+    /**
+     * 记录成功的请求
+     * @param resOptions 请求成功选项
+     */
+    logSuccess: (
+        resOptions: Omit<IResSuccessOptions, 'isSuccess' | 'timestamp'>
+    ) => void;
+}
+
+
+/**
+ * HTTP 客户端日志记录器配置
+ */
+export interface HttpClientLoggerConfig {
+    /** 底层日志记录器 */
+    logger: ILogger;
+    /** 日志过滤器（可选） */
+    filter?: ILogFilter;
+    /** 是否记录请求体 */
+    logRequestBody?: boolean;
+    /** 是否记录响应体 */
+    logResponseBody?: boolean;
+    /** 响应体最大记录长度（字节） */
+    bodyMaxLength?: number;
+}

package/src/types/request_response.ts

@@ -0,0 +1,65 @@
+/**
+ * 请求和响应类型定义
+ */
+
+/**
+ * HTTP 方法
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+/**
+ * 响应类型.
+ */
+export type ResponseType =
+    | 'arraybuffer'
+    | 'blob'
+    | 'document'
+    | 'json'
+    | 'text'
+    | 'stream'
+    | 'formdata';
+
+/**
+ * HTTP 请求选项
+ */
+export interface HttpRequestOptions {
+    /** HTTP 方法 */
+    method: HttpMethod;
+    /** 请求 URL */
+    url: string;
+    /** 请求头 */
+    headers?: Record<string, string | number>;
+    /** URL 查询参数 */
+    params?: Record<string, string | number | boolean>;
+    /** 请求体 */
+    body?: any;
+    /** 请求超时（毫秒，覆盖全局配置） */
+    timeout?: number;
+    /** 重试次数（覆盖全局配置） */
+    retries?: number;
+    /** 业务场景标识 */
+    scenario?: string;
+    /** 业务元数据 */
+    meta?: Record<string, any>;
+    /** 响应类型 */
+    responseType?: ResponseType;
+    /** W3C Trace Context traceparent 头（用于分布式链路追踪） */
+    traceparent?: string;
+}
+
+/**
+ * HTTP 响应
+ */
+export interface HttpResponse<T = any> {
+    /** 响应状态码 */
+    status: number;
+    /** 响应状态文本 */
+    statusText: string;
+    /** 响应头 */
+    headers: Record<string, string>;
+    /** 响应体 */
+    data: T;
+    /** 请求配置 */
+    config: HttpRequestOptions;
+}
+

package/src/types/security.ts

@@ -0,0 +1,126 @@
+/**
+ * 安全和验证相关类型定义
+ */
+
+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;
+}
+
+