nstarter-http-request 0.1.0

package/src/const/enum.const.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP请求客户端适配器枚举.
+ */
+export enum EClientAdapter {
+    'axios' = 'axios',
+    'undici' = 'undici',
+}
+
+/**
+ * 日志级别
+ */
+export enum ELogLevel {
+    DEBUG = 'debug',
+    INFO = 'info',
+    WARN = 'warn',
+    ERROR = 'error'
+}

package/src/const/index.ts

@@ -0,0 +1,4 @@
+export * from './ip.const';
+export * from './config.const';
+export * from './enum.const';
+export * from './dns.const';

package/src/const/ip.const.ts

@@ -0,0 +1,139 @@
+import {
+    compileIpv4Ranges,
+    compileIpv6Ranges,
+} from '../utils/ip.range';
+import type {
+    CompiledIpv4Range,
+    CompiledIpv6Range
+} from '../types';
+
+/**
+ * 私有 IP 地址范围（RFC 1918）
+ */
+const PRIVATE_IPV4_RANGES = [
+    '10.0.0.0/8',       // 10.0.0.0 - 10.255.255.255
+    '172.16.0.0/12',    // 172.16.0.0 - 172.31.255.255
+    '192.168.0.0/16',   // 192.168.0.0 - 192.168.255.255
+    '100.64.0.0/10'     // 100.64.0.0 - 100.127.255.255 (Shared Address Space, RFC 6598)
+];
+
+/**
+ * 私有 IPv6 地址范围
+ */
+const PRIVATE_IPV6_RANGES = [
+    'fc00::/7',         // Unique Local Address (ULA)
+    'fd00::/8'          // Unique Local Address (ULA)
+];
+
+/**
+ * 本地回环地址范围
+ */
+const LOOPBACK_IPV4_RANGES = [
+    '127.0.0.0/8'       // 127.0.0.0 - 127.255.255.255
+];
+
+const LOOPBACK_IPV6_RANGES = [
+    '::1/128'           // ::1
+];
+
+/**
+ * Link-Local 地址范围
+ */
+const LINK_LOCAL_IPV4_RANGES = [
+    '169.254.0.0/16'    // 169.254.0.0 - 169.254.255.255
+];
+
+const LINK_LOCAL_IPV6_RANGES = [
+    'fe80::/10'         // fe80:: - febf::
+];
+
+/**
+ * 组播地址范围
+ */
+const MULTICAST_IPV4_RANGES = [
+    '224.0.0.0/4'       // 224.0.0.0 - 239.255.255.255
+];
+
+const MULTICAST_IPV6_RANGES = [
+    'ff00::/8'          // ff00:: - ffff::
+];
+
+/**
+ * 其他保留地址范围
+ */
+const RESERVED_IPV4_RANGES = [
+    '0.0.0.0/8',        // Current network (RFC 1122)
+    '192.0.0.0/24',     // IETF Protocol Assignments (RFC 6890)
+    '192.0.2.0/24',     // TEST-NET-1 (RFC 5737)
+    '198.18.0.0/15',    // Benchmarking (RFC 2544)
+    '198.51.100.0/24',  // TEST-NET-2 (RFC 5737)
+    '203.0.113.0/24',   // TEST-NET-3 (RFC 5737)
+    '240.0.0.0/4',      // Reserved (RFC 1112)
+    '255.255.255.255/32' // Broadcast
+];
+
+const RESERVED_IPV6_RANGES = [
+    '::/128',           // Unspecified
+    '::ffff:0:0/96',    // IPv4-mapped IPv6
+    '64:ff9b::/96',     // IPv4/IPv6 translation (RFC 6052)
+    '100::/64',         // Discard prefix (RFC 6666)
+    '2001::/32',        // TEREDO (RFC 4380)
+    '2001:10::/28',     // Deprecated (RFC 4843)
+    '2001:db8::/32'     // Documentation (RFC 3849)
+];
+
+/**
+ * IPV4 校验地址范围（原始 CIDR 字符串）
+ */
+export const IPV4_RANGES = {
+    private: PRIVATE_IPV4_RANGES,
+    loopback: LOOPBACK_IPV4_RANGES,
+    linkLocal: LINK_LOCAL_IPV4_RANGES,
+    multicast: MULTICAST_IPV4_RANGES,
+    reserved: RESERVED_IPV4_RANGES
+};
+
+/**
+ * IPV6 校验地址范围（原始 CIDR 字符串）
+ */
+export const IPV6_RANGES = {
+    private: PRIVATE_IPV6_RANGES,
+    loopback: LOOPBACK_IPV6_RANGES,
+    linkLocal: LINK_LOCAL_IPV6_RANGES,
+    multicast: MULTICAST_IPV6_RANGES,
+    reserved: RESERVED_IPV6_RANGES
+};
+
+/**
+ * 预编译的 IPV4 校验地址范围（高性能版本）
+ */
+export const COMPILED_IPV4_RANGES: {
+    private: CompiledIpv4Range[],
+    loopback: CompiledIpv4Range[],
+    linkLocal: CompiledIpv4Range[],
+    multicast: CompiledIpv4Range[],
+    reserved: CompiledIpv4Range[]
+} = {
+    private: compileIpv4Ranges(PRIVATE_IPV4_RANGES),
+    loopback: compileIpv4Ranges(LOOPBACK_IPV4_RANGES),
+    linkLocal: compileIpv4Ranges(LINK_LOCAL_IPV4_RANGES),
+    multicast: compileIpv4Ranges(MULTICAST_IPV4_RANGES),
+    reserved: compileIpv4Ranges(RESERVED_IPV4_RANGES)
+};
+
+/**
+ * 预编译的 IPV6 校验地址范围（高性能版本）
+ */
+export const COMPILED_IPV6_RANGES: {
+    private: CompiledIpv6Range[],
+    loopback: CompiledIpv6Range[],
+    linkLocal: CompiledIpv6Range[],
+    multicast: CompiledIpv6Range[],
+    reserved: CompiledIpv6Range[]
+} = {
+    private: compileIpv6Ranges(PRIVATE_IPV6_RANGES),
+    loopback: compileIpv6Ranges(LOOPBACK_IPV6_RANGES),
+    linkLocal: compileIpv6Ranges(LINK_LOCAL_IPV6_RANGES),
+    multicast: compileIpv6Ranges(MULTICAST_IPV6_RANGES),
+    reserved: compileIpv6Ranges(RESERVED_IPV6_RANGES)
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './adapter';
+export * from './client';
+export * from './config';
+export * from './logger';
+export * from './security';
+export * from './types';
+export * from './utils';
+export * from './const';

package/src/logger/base.ts

@@ -0,0 +1,75 @@
+/**
+ * 日志记录器基础接口和实现
+ */
+
+import type { ILogger } from '../types';
+import { ELogLevel } from '../const';
+
+/**
+ * 抽象日志记录器基类
+ */
+export abstract class BaseLogger implements ILogger {
+    protected minLevel: ELogLevel;
+
+    constructor(minLevel: ELogLevel = ELogLevel.INFO) {
+        this.minLevel = minLevel;
+    }
+
+    /**
+     * 检查日志级别是否应该记录
+     * @param level 日志级别
+     * @returns 是否应该记录
+     */
+    protected shouldLog(level: ELogLevel): boolean {
+        const levels = [ELogLevel.DEBUG, ELogLevel.INFO, ELogLevel.WARN, ELogLevel.ERROR];
+        const minLevelIndex = levels.indexOf(this.minLevel);
+        const currentLevelIndex = levels.indexOf(level);
+        return currentLevelIndex >= minLevelIndex;
+    }
+
+    /**
+     * 设置最小日志级别
+     * @param level 最小日志级别
+     */
+    public setMinLevel(level: ELogLevel): void {
+        this.minLevel = level;
+    }
+
+    /**
+     * 获取当前最小日志级别
+     * @returns 最小日志级别
+     */
+    public getMinLevel(): ELogLevel {
+        return this.minLevel;
+    }
+
+    public abstract debug(message: string, meta?: Record<string, any>): void;
+
+    public abstract info(message: string, meta?: Record<string, any>): void;
+
+    public abstract warn(message: string, meta?: Record<string, any>): void;
+
+    public abstract error(message: string, meta?: Record<string, any>): void;
+}
+
+/**
+ * 空日志记录器（不记录任何日志）
+ */
+export class NullLogger implements ILogger {
+    public debug(): void {
+        // 不做任何事
+    }
+
+    public info(): void {
+        // 不做任何事
+    }
+
+    public warn(): void {
+        // 不做任何事
+    }
+
+    public error(): void {
+        // 不做任何事
+    }
+}
+

package/src/logger/http_client.logger.ts

@@ -0,0 +1,272 @@
+/**
+ * HTTP 客户端日志记录器实现
+ */
+
+import type {
+    IHttpClientLogger,
+    ILogger,
+    ILogFilter,
+    IResFailedOptions,
+    IResSuccessOptions,
+    LogFilterConfig,
+    HttpClientLoggerConfig
+} from '../types';
+import { LogFilter } from './log.filter';
+
+/**
+ * HTTP 客户端日志记录器
+ * 将通用 ILogger 包装成专门的 IHttpClientLogger
+ */
+export class NsHttpClientLogger implements IHttpClientLogger {
+    private logger: ILogger;
+    private filter?: ILogFilter;
+    private logRequestBody: boolean;
+    private logResponseBody: boolean;
+    private bodyMaxLength: number;
+
+    constructor(config: HttpClientLoggerConfig) {
+        this.logger = config.logger;
+        this.filter = config.filter;
+        this.logRequestBody = config.logRequestBody ?? false;
+        this.logResponseBody = config.logResponseBody ?? false;
+        this.bodyMaxLength = config.bodyMaxLength ?? 1024;
+    }
+
+    /**
+     * 记录失败的请求
+     */
+    public logFailed(
+        resOptions: Omit<IResFailedOptions, 'isSuccess' | 'timestamp'>
+    ): void {
+        const fullOptions: IResFailedOptions = {
+            ...resOptions,
+            isSuccess: false,
+            timestamp: Date.now()
+        };
+
+        // 应用过滤器
+        if (this.filter && !this.filter.shouldLog(fullOptions)) {
+            return;
+        }
+
+        const meta = this.buildLogMeta(fullOptions);
+
+        this.logger.error(
+            `HTTP request failed: ${ fullOptions.request.method } ${ fullOptions.request.url }`,
+            meta
+        );
+    }
+
+    /**
+     * 记录成功的请求
+     */
+    public logSuccess(
+        resOptions: Omit<IResSuccessOptions, 'isSuccess' | 'timestamp'>
+    ): void {
+        const fullOptions: IResSuccessOptions = {
+            ...resOptions,
+            isSuccess: true,
+            timestamp: Date.now()
+        };
+
+        // 应用过滤器
+        if (this.filter && !this.filter.shouldLog(fullOptions)) {
+            return;
+        }
+
+        const meta = this.buildLogMeta(fullOptions);
+
+        this.logger.info(
+            `HTTP request succeeded: ${ fullOptions.request.method } ${ fullOptions.request.url }`,
+            meta
+        );
+    }
+
+    /**
+     * 构建日志元数据
+     */
+    private buildLogMeta(
+        options: IResSuccessOptions | IResFailedOptions
+    ): Record<string, any> {
+        const meta: Record<string, any> = {
+            method: options.request.method,
+            url: options.request.url,
+            duration: options.duration,
+            timestamp: options.timestamp,
+            retryCount: options.retryCount
+        };
+
+        // 添加场景信息
+        if (options.request.scenario) {
+            meta.scenario = options.request.scenario;
+        }
+
+        // 添加请求元数据
+        if (options.request.meta) {
+            meta.requestMeta = options.request.meta;
+        }
+
+        if (options.isSuccess) {
+            // 成功的请求
+            meta.status = options.response.status;
+            meta.statusText = options.response.statusText;
+
+            // 记录流式响应指标
+            if (options.streamMetrics) {
+                meta.streamMetrics = {
+                    ttfb: options.streamMetrics.ttfb,
+                    completed: options.streamMetrics.completed
+                };
+
+                if (options.streamMetrics.completed) {
+                    meta.streamMetrics.totalDuration = options.streamMetrics.totalDuration;
+                    meta.streamMetrics.streamDuration =
+                        (options.streamMetrics.totalDuration ?? 0) - options.streamMetrics.ttfb;
+
+                    if (options.streamMetrics.bytesTransferred !== undefined) {
+                        meta.streamMetrics.bytesTransferred = options.streamMetrics.bytesTransferred;
+                        meta.streamMetrics.bytesTransferredHuman =
+                            this.formatBytes(options.streamMetrics.bytesTransferred);
+
+                        // 计算吞吐量
+                        const streamDuration = meta.streamMetrics.streamDuration;
+                        if (streamDuration > 0) {
+                            const throughputBps =
+                                options.streamMetrics.bytesTransferred / (streamDuration / 1000);
+                            meta.streamMetrics.throughput = `${ (throughputBps / 1024).toFixed(2) } KB/s`;
+                        }
+                    }
+                }
+            }
+
+            // 记录响应体（如果启用，且不是流式响应）
+            if (this.logResponseBody && !options.streamMetrics) {
+                meta.responseBody = this.truncateBody(options.response.data);
+            } else if (options.streamMetrics && !options.streamMetrics.completed) {
+                // 流式响应但未完成，标记为流
+                meta.responseBody = '# --- stream (in progress) --- #';
+            } else if (options.streamMetrics && options.streamMetrics.completed) {
+                // 流式响应已完成
+                meta.responseBody = '# --- stream (completed) --- #';
+            }
+        } else {
+            // 失败的请求
+            meta.error = options.error.message;
+            meta.errorCode = options.errorCode;
+
+            if (options.status !== undefined) {
+                meta.status = options.status;
+            }
+
+            if (options.response) {
+                meta.responseBody = this.truncateBody(options.response.data);
+            }
+        }
+
+        // 记录请求体（如果启用）
+        if (this.logRequestBody) {
+            meta.requestBody = this.truncateBody(options.request.body);
+        }
+
+        return meta;
+    }
+
+    /**
+     * 格式化字节数为人类可读格式
+     */
+    private formatBytes(bytes: number): string {
+        if (bytes === 0) {
+            return '0 Bytes';
+        }
+
+        const k = 1024;
+        const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+        return `${ parseFloat((bytes / Math.pow(k, i)).toFixed(2)) } ${ sizes[i] }`;
+    }
+
+    /**
+     * 截断请求/响应体到指定长度
+     * 对于特殊类型（Stream、Buffer等）返回标记文本
+     */
+    private truncateBody(body: any): any {
+        // 处理 null 和 undefined
+        if (body === null) {
+            return '# --- null --- #';
+        }
+        if (body === undefined) {
+            return '# --- undefined --- #';
+        }
+
+        // 处理基本类型
+        if (typeof body === 'number' || typeof body === 'boolean') {
+            return body;
+        }
+
+        // 处理字符串
+        if (typeof body === 'string') {
+            if (body.length <= this.bodyMaxLength) {
+                return body;
+            }
+            return body.substring(0, this.bodyMaxLength) + '... (truncated)';
+        }
+
+        // 处理 Buffer
+        if (Buffer.isBuffer(body)) {
+            return `# --- buffer (${ body.length } bytes) --- #`;
+        }
+
+        // 处理 Stream
+        if (typeof body === 'object' && typeof body.pipe === 'function') {
+            return '# --- stream --- #';
+        }
+
+        // 处理 ArrayBuffer
+        if (body instanceof ArrayBuffer ||
+            (typeof body === 'object' && body.constructor?.name === 'ArrayBuffer')) {
+            return `# --- arraybuffer (${ body.byteLength } bytes) --- #`;
+        }
+
+        // 处理 Blob (浏览器环境)
+        if (typeof body === 'object' && body.constructor?.name === 'Blob') {
+            return `# --- blob (${ body.size } bytes) --- #`;
+        }
+
+        // 处理普通对象和数组
+        try {
+            const bodyStr = JSON.stringify(body);
+            if (bodyStr.length <= this.bodyMaxLength) {
+                return body;
+            }
+            return bodyStr.substring(0, this.bodyMaxLength) + '... (truncated)';
+        } catch {
+            return '[unable to serialize body]';
+        }
+    }
+
+    /**
+     * 创建 HTTP 客户端日志记录器
+     * @param logger 底层日志记录器
+     * @param filterConfig 过滤器配置
+     * @param options 其他选项
+     */
+    public static create(
+        logger: ILogger,
+        filterConfig?: LogFilterConfig,
+        options?: {
+            logRequestBody?: boolean,
+            logResponseBody?: boolean,
+            bodyMaxLength?: number
+        }
+    ): NsHttpClientLogger {
+        return new NsHttpClientLogger({
+            logger,
+            filter: filterConfig ? new LogFilter(filterConfig) : undefined,
+            logRequestBody: options?.logRequestBody,
+            logResponseBody: options?.logResponseBody,
+            bodyMaxLength: options?.bodyMaxLength
+        });
+    }
+}
+

package/src/logger/index.ts

@@ -0,0 +1,3 @@
+export * from './base';
+export * from './http_client.logger';
+export * from './log.filter';

package/src/logger/log.filter.ts

@@ -0,0 +1,149 @@
+/**
+ * 日志过滤器实现
+ */
+
+import type {
+    ILogFilter,
+    LogFilterConfig,
+    IResSuccessOptions,
+    IResFailedOptions
+} from '../types';
+
+/**
+ * 默认日志过滤器
+ */
+export class LogFilter implements ILogFilter {
+    private config: LogFilterConfig;
+
+    constructor(config: LogFilterConfig = {}) {
+        this.config = config;
+    }
+
+    /**
+     * 判断是否应该记录此日志
+     * @param options 日志选项（成功或失败）
+     * @returns 是否应该记录
+     */
+    public shouldLog(options: IResSuccessOptions | IResFailedOptions): boolean {
+        return (
+            this.checkSuccessOrFailedFilter(options) &&
+            this.checkMethodFilter(options) &&
+            this.checkUrlPatternFilter(options) &&
+            this.checkScenarioFilter(options) &&
+            this.checkStatusCodeFilter(options) &&
+            this.checkDurationFilter(options) &&
+            this.checkCustomFilter(options)
+        );
+    }
+
+    /**
+     * 检查成功/失败过滤
+     */
+    private checkSuccessOrFailedFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.onlyFailed && options.isSuccess) {
+            return false;
+        }
+        if (this.config.onlySuccess && !options.isSuccess) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * 检查 HTTP 方法过滤
+     */
+    private checkMethodFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.methods && this.config.methods.length > 0) {
+            return this.config.methods.includes(options.request.method);
+        }
+        return true;
+    }
+
+    /**
+     * 检查 URL 模式过滤
+     */
+    private checkUrlPatternFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.urlPatterns && this.config.urlPatterns.length > 0) {
+            return this.config.urlPatterns.some(pattern => {
+                if (typeof pattern === 'string') {
+                    return options.request.url.includes(pattern);
+                }
+                return pattern.test(options.request.url);
+            });
+        }
+        return true;
+    }
+
+    /**
+     * 检查场景过滤
+     */
+    private checkScenarioFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.scenarios && this.config.scenarios.length > 0) {
+            return !!options.request.scenario && this.config.scenarios.includes(options.request.scenario);
+        }
+        return true;
+    }
+
+    /**
+     * 检查状态码过滤
+     */
+    private checkStatusCodeFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        const status = options.isSuccess ? options.response.status : options.status;
+        if (status === undefined) {
+            return true;
+        }
+
+        // 检查特定状态码
+        if (this.config.statusCodes && this.config.statusCodes.length > 0) {
+            if (!this.config.statusCodes.includes(status)) {
+                return false;
+            }
+        }
+
+        // 检查状态码范围
+        if (this.config.statusCodeRanges && this.config.statusCodeRanges.length > 0) {
+            return this.config.statusCodeRanges.some(
+                range => status >= range.min && status <= range.max
+            );
+        }
+
+        return true;
+    }
+
+    /**
+     * 检查请求耗时过滤
+     */
+    private checkDurationFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.minDuration !== undefined && options.duration !== undefined) {
+            return options.duration >= this.config.minDuration;
+        }
+        return true;
+    }
+
+    /**
+     * 检查自定义过滤函数
+     */
+    private checkCustomFilter(options: IResSuccessOptions | IResFailedOptions): boolean {
+        if (this.config.customFilter) {
+            return this.config.customFilter(options);
+        }
+        return true;
+    }
+
+    /**
+     * 更新过滤器配置
+     * @param config 新的配置
+     */
+    public updateConfig(config: LogFilterConfig): void {
+        this.config = { ...this.config, ...config };
+    }
+
+    /**
+     * 获取当前配置
+     * @returns 当前配置
+     */
+    public getConfig(): LogFilterConfig {
+        return { ...this.config };
+    }
+}
+