nstarter-http-request 0.1.0

package/src/types/trace.ts

@@ -0,0 +1,35 @@
+/**
+ * Trace 标志位
+ */
+export enum TraceFlags {
+    /** 未采样 */
+    NONE = 0x00,
+    /** 已采样 */
+    SAMPLED = 0x01
+}
+
+/**
+ * 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;
+}

package/src/utils/common.ts

@@ -0,0 +1,28 @@
+/**
+ * 延迟函数
+ * @param ms 延迟毫秒数
+ */
+export function delay(ms: number): Promise<void> {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+
+/**
+ * 超时函数
+ * @param promise 原始 Promise
+ * @param ms 超时毫秒数
+ * @param message 超时错误消息
+ * @returns 超时后的 Promise
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message = 'Operation timed out'): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(message));
+        }, ms);
+
+        promise
+            .then(resolve, reject)
+            .finally(() => clearTimeout(timer));
+    });
+}

package/src/utils/domain.ts

@@ -0,0 +1,78 @@
+import escapeRegexp from 'escape-string-regexp';
+
+/**
+ * 根据域名模式列表生成正则表达式数组（通配符模式）
+ * 支持规则：
+ *  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 const createDomainMatchers = (patterns: string[]): RegExp[] => {
+    return patterns.map((pattern) => {
+        const trimmedPattern = pattern.trim();
+
+        // 通配符模式：*.example.com
+        // 只匹配一级子域名（如 api.example.com, www.example.com）
+        // 不匹配根域名（example.com）和多级子域名（test.api.example.com）
+        if (trimmedPattern.startsWith('*.')) {
+            const domain = trimmedPattern.slice(2); // 移除 *. 前缀
+            const escapedDomain = escapeRegexp(domain);
+            // 匹配：一个或多个非点字符（一级子域名）+ 点 + 域名
+            return new RegExp(`^[^.]+\\.${ escapedDomain }$`, 'i');
+        }
+
+        // 精确匹配：example.com
+        // 仅匹配指定的域名
+        const escapedPattern = escapeRegexp(trimmedPattern);
+        return new RegExp(`^${ escapedPattern }$`, 'i');
+    });
+};
+
+/**
+ * 根据域名模式列表生成正则表达式数组（传统模式，用于正向代理等场景）
+ * @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 const createLegacyDomainMatchers = (patterns: string[]): RegExp[] => {
+    return patterns.map((pattern) => {
+        const lowerPattern = pattern.toLowerCase();
+
+        // 以 . 开头，生成后缀匹配正则（如 .example.com 匹配所有子域名）
+        if (lowerPattern.startsWith('.')) {
+            return new RegExp(`${ escapeRegexp(pattern) }$`, 'i');
+        }
+
+        // 以 . 结尾，生成前缀匹配正则（如 172.168.0. 匹配 172.168.0.x）
+        if (lowerPattern.endsWith('.')) {
+            return new RegExp(`^${ escapeRegexp(pattern) }`, 'i');
+        }
+
+        // 字符串完全匹配
+        return new RegExp(`^${ escapeRegexp(pattern) }$`, 'i');
+    });
+};
+

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * as IpRangeUtils from './ip.range';
+export * as CommonUtils from './common';
+export * as DomainUtils from './domain';
+export * as TraceContextUtils from './trace.context';
+
+// 导出 TraceContext 类供外部直接使用
+export { TraceContext } from './trace.context';

package/src/utils/ip.range.ts

@@ -0,0 +1,218 @@
+/**
+ * IP 地址范围工具
+ */
+
+import type {
+    CompiledIpv4Range,
+    CompiledIpv6Range
+} from '../types';
+
+/**
+ * 将 IPv4 地址转换为数字
+ */
+export function ipv4ToNumber(ip: string): number {
+    const parts = ip.split('.');
+    return (
+        (parseInt(parts[0], 10) << 24) +
+        (parseInt(parts[1], 10) << 16) +
+        (parseInt(parts[2], 10) << 8) +
+        parseInt(parts[3], 10)
+    ) >>> 0; // 无符号右移确保为正数
+}
+
+/**
+ * 预编译 IPv4 CIDR 范围
+ * @param cidr CIDR 表示法，如 "192.168.0.0/16"
+ */
+export function compileIpv4Range(cidr: string): CompiledIpv4Range {
+    const [network, prefixStr] = cidr.split('/');
+    const prefix = parseInt(prefixStr, 10);
+
+    if (prefix < 0 || prefix > 32) {
+        throw new Error(`Invalid CIDR prefix: ${ prefix }`);
+    }
+
+    const networkNum = ipv4ToNumber(network);
+    const mask = (0xffffffff << (32 - prefix)) >>> 0;
+
+    return {
+        network: networkNum & mask,
+        mask,
+        cidr
+    };
+}
+
+/**
+ * 检查 IPv4 地址是否在预编译的范围内（高性能版本）
+ * @param ip IP 地址
+ * @param compiledRange 预编译的范围
+ */
+export function isIpv4InCompiledRange(ip: string, compiledRange: CompiledIpv4Range): boolean {
+    const ipNum = ipv4ToNumber(ip);
+    return (ipNum & compiledRange.mask) === compiledRange.network;
+}
+
+/**
+ * 将 IPv6 地址转换为 BigInt 数组（高 64 位和低 64 位）
+ */
+export function ipv6ToBigInt(ip: string): [bigint, bigint] {
+    // 标准化 IPv6 地址
+    const normalized = normalizeIpv6(ip);
+    const parts = normalized.split(':');
+
+    let high = BigInt(0);
+    let low = BigInt(0);
+
+    for (let i = 0; i < 4; i++) {
+        high = (high << BigInt(16)) | BigInt(parseInt(parts[i], 16));
+    }
+
+    for (let i = 4; i < 8; i++) {
+        low = (low << BigInt(16)) | BigInt(parseInt(parts[i], 16));
+    }
+
+    return [high, low];
+}
+
+/**
+ * 标准化 IPv6 地址（展开缩写）
+ */
+export function normalizeIpv6(ip: string): string {
+    // 移除区域 ID（如 fe80::1%eth0 中的 %eth0）
+    const cleaned = ip.split('%')[0];
+
+    // 处理 :: 缩写
+    const parts = cleaned.split(':');
+    const filled: string[] = [];
+
+    let doubleColonIndex = -1;
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i] === '') {
+            if (doubleColonIndex === -1) {
+                doubleColonIndex = i;
+            }
+        } else {
+            filled.push(parts[i].padStart(4, '0'));
+        }
+    }
+
+    // 填充 :: 省略的部分
+    if (doubleColonIndex !== -1) {
+        const missing = 8 - filled.length;
+        const before = filled.slice(0, doubleColonIndex === 0 ? 0 : doubleColonIndex);
+        const after = filled.slice(doubleColonIndex === 0 ? 0 : doubleColonIndex);
+        const zeros = Array(missing).fill('0000');
+        return [...before, ...zeros, ...after].join(':');
+    }
+
+    return filled.join(':');
+}
+
+/**
+ * 预编译 IPv6 CIDR 范围
+ * @param cidr CIDR 表示法，如 "fe80::/10"
+ */
+export function compileIpv6Range(cidr: string): CompiledIpv6Range {
+    const [network, prefixStr] = cidr.split('/');
+    const prefix = parseInt(prefixStr, 10);
+
+    if (prefix < 0 || prefix > 128) {
+        throw new Error(`Invalid IPv6 CIDR prefix: ${ prefix }`);
+    }
+
+    const [netHigh, netLow] = ipv6ToBigInt(network);
+
+    let maskHigh: bigint;
+    let maskLow: bigint;
+
+    if (prefix <= 64) {
+        // 只需要掩码高 64 位
+        maskHigh = (BigInt(0xffffffffffffffffn) << BigInt(64 - prefix)) & BigInt(0xffffffffffffffffn);
+        maskLow = BigInt(0);
+    } else {
+        // 高 64 位全部掩码，低 64 位部分掩码
+        maskHigh = BigInt(0xffffffffffffffffn);
+        maskLow = (BigInt(0xffffffffffffffffn) << BigInt(128 - prefix)) & BigInt(0xffffffffffffffffn);
+    }
+
+    return {
+        networkHigh: netHigh & maskHigh,
+        networkLow: netLow & maskLow,
+        maskHigh,
+        maskLow,
+        prefix,
+        cidr
+    };
+}
+
+/**
+ * 检查 IPv6 地址是否在预编译的范围内（高性能版本）
+ * @param ip IPv6 地址
+ * @param compiledRange 预编译的范围
+ */
+export function isIpv6InCompiledRange(ip: string, compiledRange: CompiledIpv6Range): boolean {
+    const [ipHigh, ipLow] = ipv6ToBigInt(ip);
+
+    if (compiledRange.prefix <= 64) {
+        // 只需要比较高 64 位
+        return (ipHigh & compiledRange.maskHigh) === compiledRange.networkHigh;
+    } else {
+        // 高 64 位必须完全匹配，低 64 位部分匹配
+        return (ipHigh & compiledRange.maskHigh) === compiledRange.networkHigh &&
+            (ipLow & compiledRange.maskLow) === compiledRange.networkLow;
+    }
+}
+
+/**
+ * 批量预编译 IPv4 CIDR 范围列表
+ * @param cidrs CIDR 范围列表
+ */
+export function compileIpv4Ranges(cidrs: string[]): CompiledIpv4Range[] {
+    return cidrs.map(cidr => compileIpv4Range(cidr));
+}
+
+/**
+ * 批量预编译 IPv6 CIDR 范围列表
+ * @param cidrs CIDR 范围列表
+ */
+export function compileIpv6Ranges(cidrs: string[]): CompiledIpv6Range[] {
+    return cidrs.map(cidr => compileIpv6Range(cidr));
+}
+
+/**
+ * 检查 IPv4 地址是否匹配任一预编译范围（高性能版本）
+ * @param ip IPv4 地址
+ * @param compiledRanges 预编译的范围列表
+ */
+export function isIpv4InAnyCompiledRange(ip: string, compiledRanges: CompiledIpv4Range[]): boolean {
+    const ipNum = ipv4ToNumber(ip);
+    for (const range of compiledRanges) {
+        if ((ipNum & range.mask) === range.network) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * 检查 IPv6 地址是否匹配任一预编译范围（高性能版本）
+ * @param ip IPv6 地址
+ * @param compiledRanges 预编译的范围列表
+ */
+export function isIpv6InAnyCompiledRange(ip: string, compiledRanges: CompiledIpv6Range[]): boolean {
+    const [ipHigh, ipLow] = ipv6ToBigInt(ip);
+    for (const range of compiledRanges) {
+        if (range.prefix <= 64) {
+            if ((ipHigh & range.maskHigh) === range.networkHigh) {
+                return true;
+            }
+        } else {
+            if ((ipHigh & range.maskHigh) === range.networkHigh &&
+                (ipLow & range.maskLow) === range.networkLow) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+

package/src/utils/trace.context.ts

@@ -0,0 +1,240 @@
+/**
+ * W3C Trace Context 工具
+ * 实现 W3C Trace Context 规范：https://www.w3.org/TR/trace-context/
+ */
+
+import type {
+    TraceParent,
+    TraceParentOptions
+} from '../types';
+import {
+    TraceFlags
+} from '../types';
+
+/**
+ * 生成随机十六进制字符串
+ * @param length 字符串长度
+ * @returns 十六进制字符串
+ */
+function generateRandomHex(length: number): string {
+    const bytes = Math.ceil(length / 2);
+    const buffer = new Uint8Array(bytes);
+
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        crypto.getRandomValues(buffer);
+    } else {
+        // Fallback for Node.js environment
+        for (let i = 0; i < bytes; i++) {
+            buffer[i] = Math.floor(Math.random() * 256);
+        }
+    }
+
+    return Array.from(buffer)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, length);
+}
+
+/**
+ * 生成符合 W3C 规范的 Trace ID（32位十六进制）
+ * @returns Trace ID
+ */
+export function generateTraceId(): string {
+    return generateRandomHex(32);
+}
+
+/**
+ * 生成符合 W3C 规范的 Span ID（16位十六进制）
+ * @returns Span ID
+ */
+export function generateSpanId(): string {
+    return generateRandomHex(16);
+}
+
+/**
+ * 验证 Trace ID 格式
+ * @param traceId Trace ID
+ * @returns 是否有效
+ */
+export function isValidTraceId(traceId: string): boolean {
+    // Trace ID 必须是32位十六进制字符串，且不能全为0
+    return /^[0-9a-f]{32}$/i.test(traceId) && traceId !== '00000000000000000000000000000000';
+}
+
+/**
+ * 验证 Span ID 格式
+ * @param spanId Span ID
+ * @returns 是否有效
+ */
+export function isValidSpanId(spanId: string): boolean {
+    // Span ID 必须是16位十六进制字符串，且不能全为0
+    return /^[0-9a-f]{16}$/i.test(spanId) && spanId !== '0000000000000000';
+}
+
+/**
+ * 验证 Trace Flags 格式
+ * @param flags Trace Flags
+ * @returns 是否有效
+ */
+export function isValidTraceFlags(flags: string): boolean {
+    // Trace Flags 必须是2位十六进制字符串
+    return /^[0-9a-f]{2}$/i.test(flags);
+}
+
+/**
+ * 生成 traceparent 头值
+ * @param options 生成选项
+ * @returns traceparent 字符串
+ */
+export function generateTraceParent(options: TraceParentOptions = {}): string {
+    const traceId = options.traceId || generateTraceId();
+    const parentId = options.parentId || generateSpanId();
+    const sampled = options.sampled !== false;
+    const traceFlags = sampled ? '01' : '00';
+
+    // 验证参数
+    if (!isValidTraceId(traceId)) {
+        throw new Error(`Invalid trace ID: ${ traceId }. Must be 32 hex characters and not all zeros.`);
+    }
+    if (!isValidSpanId(parentId)) {
+        throw new Error(`Invalid span ID: ${ parentId }. Must be 16 hex characters and not all zeros.`);
+    }
+
+    return `00-${ traceId }-${ parentId }-${ traceFlags }`;
+}
+
+/**
+ * 解析 traceparent 头值
+ * @param traceparent traceparent 字符串
+ * @returns 解析后的对象，解析失败返回 null
+ */
+export function parseTraceParent(traceparent: string): TraceParent | null {
+    if (!traceparent || typeof traceparent !== 'string') {
+        return null;
+    }
+
+    // 规范格式：version-trace-id-parent-id-trace-flags
+    const parts = traceparent.trim().split('-');
+
+    if (parts.length !== 4) {
+        return null;
+    }
+
+    const [version, traceId, parentId, traceFlags] = parts;
+
+    // 验证版本号（当前只支持 00）
+    if (version !== '00') {
+        return null;
+    }
+
+    // 验证各部分格式
+    if (!isValidTraceId(traceId) || !isValidSpanId(parentId) || !isValidTraceFlags(traceFlags)) {
+        return null;
+    }
+
+    return {
+        version,
+        traceId: traceId.toLowerCase(),
+        parentId: parentId.toLowerCase(),
+        traceFlags: traceFlags.toLowerCase()
+    };
+}
+
+/**
+ * 验证 traceparent 头值是否符合规范
+ * @param traceparent traceparent 字符串
+ * @returns 是否有效
+ */
+export function isValidTraceParent(traceparent: string): boolean {
+    return parseTraceParent(traceparent) !== null;
+}
+
+/**
+ * 从现有 traceparent 创建子 span
+ * @param parentTraceParent 父级 traceparent 字符串
+ * @param sampled 是否采样（不提供则继承父级）
+ * @returns 新的 traceparent 字符串
+ */
+export function createChildSpan(parentTraceParent: string, sampled?: boolean): string {
+    const parsed = parseTraceParent(parentTraceParent);
+
+    if (!parsed) {
+        throw new Error(`Invalid parent traceparent: ${ parentTraceParent }`);
+    }
+
+    // 继承 trace ID，生成新的 span ID
+    const newSpanId = generateSpanId();
+
+    // 继承或指定采样标志
+    const parentSampled = parseInt(parsed.traceFlags, 16) & TraceFlags.SAMPLED;
+    const newSampled = sampled !== undefined ? sampled : !!parentSampled;
+    const newFlags = newSampled ? '01' : '00';
+
+    return `00-${ parsed.traceId }-${ newSpanId }-${ newFlags }`;
+}
+
+/**
+ * 检查 traceparent 是否已采样
+ * @param traceparent traceparent 字符串
+ * @returns 是否采样
+ */
+export function isSampled(traceparent: string): boolean {
+    const parsed = parseTraceParent(traceparent);
+    if (!parsed) {
+        return false;
+    }
+
+    const flags = parseInt(parsed.traceFlags, 16);
+    return !!(flags & TraceFlags.SAMPLED);
+}
+
+/**
+ * Trace Context 工具类
+ */
+export class TraceContext {
+    /**
+     * 生成 traceparent
+     */
+    public static generate = generateTraceParent;
+
+    /**
+     * 解析 traceparent
+     */
+    public static parse = parseTraceParent;
+
+    /**
+     * 验证 traceparent
+     */
+    public static isValid = isValidTraceParent;
+
+    /**
+     * 创建子 span
+     */
+    public static createChild = createChildSpan;
+
+    /**
+     * 检查是否采样
+     */
+    public static isSampled = isSampled;
+
+    /**
+     * 生成 Trace ID
+     */
+    public static generateTraceId = generateTraceId;
+
+    /**
+     * 生成 Span ID
+     */
+    public static generateSpanId = generateSpanId;
+
+    /**
+     * 验证 Trace ID
+     */
+    public static isValidTraceId = isValidTraceId;
+
+    /**
+     * 验证 Span ID
+     */
+    public static isValidSpanId = isValidSpanId;
+}
+