@isdk/proxy 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -1,4 +1,30 @@
-import { KeyvCacheableMemoryOptions } from '@cacheable/memory';
+import { CommonError, ErrorCode } from '@isdk/common-error';
+
+/**
+ * 错误类型定义
+ */
+
+/**
+ * Offline 缓存未命中错误代码
+ *
+ * 当处于 offline 模式且请求的 URL 没有对应缓存时抛出。
+ * 这帮助调用者区分：
+ * - 网络请求失败（其他错误类型）
+ * - offline 模式下缓存不存在（本错误）
+ */
+declare const OfflineCacheMissErrorCode = ErrorCode.OfflineCacheMiss;
+/**
+ * Offline 缓存未命中错误
+ *
+ * @example
+* throw new OfflineCacheMissError('http://example.com/data')
+*
+* @extends CommonError
+*/
+declare class OfflineCacheMissError extends CommonError {
+    static code: ErrorCode;
+    constructor(url: string | number, name?: string | Record<string, any>);
+}
 
 /**
  * 缓存键过滤配置
@@ -6,25 +32,107 @@ import { KeyvCacheableMemoryOptions } from '@cacheable/memory';
  * 用于定义在生成缓存指纹时，哪些字段应该被包含或排除。
  */
 interface KeyFilterConfig {
-    /** 仅包含（白名单）：如果设置，只有这些字段会参与 Key 的计算 */
-    include?: string[];
-    /** 排除（黑名单）：用于排除像 `timestamp`、`nonce` 等干扰缓存命中的动态字段 */
-    exclude?: string[];
+    /** 仅包含（白名单）：如果设置，只有这些字段会参与 Key 的计算。支持字符串、Glob 模式或正则表达式。 */
+    include?: (string | RegExp)[];
+    /** 排除（黑名单）：用于排除像 `timestamp`、`nonce` 等干扰缓存命中的动态字段。支持字符串、Glob 模式或正则表达式。 */
+    exclude?: (string | RegExp)[];
+}
+interface BodyFilterConfig extends KeyFilterConfig {
+    /**
+     * 用于非 JSON (文本) Body 的提取正则表达式。
+     * 如果包含捕获组，则提取捕获组内容作为指纹；否则提取整个匹配部分。
+     */
+    extract?: string | RegExp;
+    /**
+     * 是否对提取出的捕获组进行排序。
+     * 开启后可解决 Body 中参数顺序不一致导致的指纹失效问题。
+     */
+    sort?: boolean;
+    /** 用于正则匹配/提取 Body 时的最大长度限制，默认 1024 (1KB) */
+    maxLength?: number;
+}
+/**
+ * 精细化缓存匹配规则
+ *
+ * 用于在 `methods` 过滤的基础上，进一步限定哪些具体的请求路径或参数需要被缓存。
+ * 多个规则之间是 **OR (逻辑或)** 关系，即请求只需匹配其中一条规则即可。
+ * 在单个规则对象内部，各字段之间是 **AND (逻辑与)** 关系。
+ */
+interface CacheRule {
+    /**
+     * 匹配的方法 (如 "POST")。
+     * 如果指定，则必须方法完全一致；如果不指定，则匹配所有 `methods` 中允许的方法。
+     */
+    method?: string;
+    /**
+     * 路径匹配。
+     * - 字符串: 默认进行 Glob 模式匹配（支持 `!` 否定），若非 Glob 且非正则字符串则退化为前缀匹配。
+     * - 正则表达式: 检查 `url.pathname` 是否匹配。
+     */
+    /**
+     * 路径匹配。
+     * - 字符串: 默认进行 Glob 模式匹配（支持 `!` 否定），若非 Glob 且非正则字符串则退化为前缀匹配。
+     * - 正则表达式: 检查 `url.pathname` 是否匹配。
+     * - 数组: 支持传入多个模式（含否定模式），只要其中一个匹配即可。
+     */
+    path?: string | RegExp | (string | RegExp)[];
+    /**
+     * Query 参数匹配规则。
+     * - 键名: 支持字符串、Glob 或正则。
+     * - 值:
+     *   - 字符串: 支持 Glob 模式匹配。
+     *   - 正则表达式: 检查参数值是否匹配。
+     *   - `true`: 要求该参数必须存在于 URL 中。
+     *   - `false`: 要求该参数必须 **不** 存在于 URL 中。
+     */
+    query?: Record<string, string | boolean | RegExp>;
+    /**
+     * 强制指定 Body 类型。
+     * 如果不指定，则根据 `Content-Type` 自动判断。
+     */
+    bodyType?: 'json' | 'text' | 'binary';
+    /**
+     * Body 内容匹配。
+     * 仅当 Body 为文本或 JSON 时有效。
+     * - 字符串: 支持 Glob 模式匹配。
+     * - 正则表达式: 检查 Body 内容是否匹配。
+     * - 数组: 支持传入多个模式。
+     */
+    body?: string | RegExp | (string | RegExp)[];
 }
 /**
  * 站点级缓存配置
  */
 interface SiteCacheConfig {
-    /** Query 参数过滤配置 */
+    /**
+     * 允许缓存的 HTTP 方法列表。
+     * 默认值: ['GET', 'HEAD']。
+     * 若要缓存 POST/PUT，必须在此显式添加，并确保后端响应满足缓存条件（或开启 `forceCache`）。
+     */
+    methods?: string[];
+    /**
+     * 精细化缓存规则列表。
+     * 如果配置了此项，请求必须匹配其中至少一条规则才会被允许进入缓存流程。
+     * 适用于只希望缓存特定 API 接口的场景。
+     */
+    cacheRules?: CacheRule[];
+    /** Query 参数过滤配置：决定哪些查询参数参与缓存指纹 (Cache Key) 的计算 */
     query?: KeyFilterConfig;
-    /** 请求头过滤配置 */
+    /** 请求头过滤配置：决定哪些 Header 参与缓存指纹计算 */
     headers?: KeyFilterConfig;
-    /** Cookie 过滤配置 */
+    /** Cookie 过滤配置：决定哪些 Cookie 字段参与缓存指纹计算 */
     cookies?: KeyFilterConfig;
-    /** 当后端请求失败且存在旧缓存时，是否强制返回旧缓存（容错机制） */
+    /**
+     * 请求体过滤配置 (仅限 JSON 类型)。
+     * 当方法为 POST/PUT/PATCH 且为 JSON 格式时，用于从 Body 中提取特定字段参与指纹计算。
+     */
+    body?: BodyFilterConfig;
+    /** 容错机制：当后端请求失败（网络错误或 5xx）且存在旧缓存时，是否强制返回旧缓存 */
     staleIfError?: boolean;
-    /** 是否强制缓存一切响应（无视 no-store 等不缓存指令），用于极端的离线可用容错场景 */
+    /** 强制缓存：是否忽略 `Cache-Control: no-store` 等指令强制入库。 */
     forceCache?: boolean;
+    /** 严格离线模式：不发起任何网络请求，只读缓存。缓存未命中时抛出 OfflineCacheMissError */
+    offline?: boolean;
 }
 /**
  * 缓存元数据
@@ -75,11 +183,28 @@ interface SmartCacheOptions {
     storagePath?: string;
     /** 内存缓存阈值（字节）。响应体大小超过此值时，Body 将只存入磁盘，而 Meta 仍保留在内存。默认 1MB。 */
     maxMemorySize?: number;
-    /** 透传给 L1 (Memory) 的高级配置 */
-    memoryOptions?: Partial<KeyvCacheableMemoryOptions>;
+    /** 内存缓存总大小阈值（字节）。默认 100MB。超过此值将清空内存缓存。 */
+    maxTotalMemorySize?: number;
+    /** 透传给 L1 (Memory) 的高级配置 (secondary-cache LRUCache options) */
+    memoryOptions?: {
+        capacity?: number;
+        expires?: number;
+        cleanInterval?: number;
+        [key: string]: any;
+    };
 }
 /**
- * 智能混合缓存类 (Hybrid Cache)
+ * 智能混合缓存类 (Hybrid Multi-tier Cache)
+ *
+ * 该类实现了 L1 (内存) 和 L2 (磁盘) 的双层混合存储架构，旨在提供高性能且大容量的缓存能力。
+ *
+ * ### 核心特性：
+ * - **双层架构**: L1 使用 LRU 内存缓存（基于 `secondary-cache` 的 LRUCache），L2 使用持久化磁盘缓存（基于 `cacache`）。
+ * - **大小感知存储**: 自动识别响应体大小。小于阈值的文件同时存于内存和磁盘；超过阈值的文件仅存于磁盘，但其元数据仍保留在内存中。
+ * - **元数据驻留 (Meta-Residency)**: 无论 Body 多大，Headers、Status、Policy 等信息始终优先从内存读取，确保缓存判定性能。
+ * - **流式支持**: 支持通过 `setStream` 和 `getStream` 直接操作大数据流，防止 OOM。
+ * - **一致性保障**: 在并发写入时自动清理内存，确保后续读取不会拿到被污染的旧数据。
+ * - **内存限制**: 通过 `maxTotalMemorySize` 控制 L1 缓存的总内存占用。
  */
 declare class SmartCache {
     private memory;
@@ -88,27 +213,97 @@ declare class SmartCache {
     constructor(options?: SmartCacheOptions);
     /**
      * 获取缓存条目
-     * 如果是小文件，返回带 Buffer 的 Entry；如果是大文件，返回带 ReadStream 的 Entry。
+     *
+     * 逻辑：
+     * 1. 首先尝试从 L1 内存获取。
+     * 2. 如果内存中有 Body，直接返回（Buffer 类型）。
+     * 3. 如果内存中只有 Meta（大文件），则从 L2 磁盘创建并返回 ReadStream。
+     * 4. 如果内存完全未命中，从磁盘 L2 检索，并根据大小决定是否回填 L1。
+     *
+     * @param key - 缓存指纹键
+     * @returns 完整的缓存条目（带 Buffer 或 Stream 的 Body），未命中返回 null
      */
     get(key: string): Promise<CacheEntry | null>;
     /**
-     * 写入缓存
+     * 写入缓存条目 (原子写入)
+     *
+     * 适用于已知长度的小型数据块。该操作会同时写入磁盘并回填内存（如果大小未超标）。
+     *
+     * @param key - 缓存指纹键
+     * @param body - 响应体数据 Buffer
+     * @param metadata - 响应元数据（不含 size，由本方法自动计算）
      */
     set(key: string, body: Buffer, metadata: Omit<CacheMetadata, 'size'>): Promise<void>;
     /**
      * 内部方法：处理内存回填
      */
     private saveToMemory;
+    /**
+     * 获取磁盘读取流
+     *
+     * 允许直接从 L2 磁盘层以流的形式读取数据，适用于大文件代理。
+     *
+     * @param key - 缓存指纹键
+     * @returns Node.js 可读流
+     */
     getStream(key: string): NodeJS.ReadableStream;
+    /**
+     * 获取磁盘写入流 (流式缓存)
+     *
+     * 该方法用于支持真正的流式代理。它会执行以下一致性操作：
+     * 1. 立即清除 L1 内存中的对应键，防止读到旧数据。
+     * 2. 返回一个可写流，数据将直接流入磁盘。
+     * 3. **一致性修复**: 在流写入完成（finish）时再次清理内存，防止写入期间的并发读取将旧数据再次回填进内存。
+     *
+     * @param key - 缓存指纹键
+     * @param metadata - 响应元数据
+     * @returns Node.js 可写流
+     */
     setStream(key: string, metadata: Omit<CacheMetadata, 'size'>): NodeJS.WritableStream;
-    delete(key: string): Promise<void>;
-    clear(): Promise<void>;
+    /**
+     * Deletes the cache entry for the specified key.
+     * @param key - The cache key to delete
+     * @param [clearPersistent=true] - Whether to also delete the entry from persistent (disk) storage. Defaults to `true`.
+     */
+    delete(key: string, clearPersistent?: boolean): Promise<void>;
+    /**
+     * Clears the cache. By default, both the in-memory cache and the persistent disk cache are cleared.
+     * @param [clearPersistent=true] - Whether to clear the persistent (disk) cache. Defaults to `true` for backward compatibility.
+     */
+    clear(clearPersistent?: boolean): Promise<void>;
 }
 
 /**
- * 根据 Request 和配置生成唯一的缓存键
+ * 根据 Request 对象和站点配置生成唯一的缓存指纹 (异步)
+ *
+ * 该函数是缓存系统的核心组件，用于将复杂的 HTTP 请求对象转换为唯一的 SHA-256 字符串。
+ * 它实现了高度可定制的提取逻辑，允许通过配置排除掉请求中不稳定的因素（如时间戳、Nonce 等）。
+ *
+ * ### 生成指纹包含的要素：
+ * 1. **Method**: 请求方法（统一转为大写）。
+ * 2. **Host & Path**: 请求的域名和路径。
+ * 3. **Query Params**: URL 查询参数，受 `config.query` 过滤影响。
+ * 4. **Headers**: 请求头信息，受 `config.headers` 过滤影响。默认排除 `cookie` 头。
+ * 5. **Cookies**: 特别提取的 Cookie 字段，受 `config.cookies` 过滤影响。
+ * 6. **Request Body**:
+ *    - 对于 `POST`, `PUT`, `PATCH` 请求，会自动尝试读取 Body。
+ *    - **JSON 类型**: 如果 `Content-Type` 包含 `application/json`，则解析为对象并应用 `config.body` 过滤。
+ *    - **非 JSON/流类型**: 回退到对原始 Body 字节流进行 SHA-256 哈希计算。
+ *    - **安全性**: 使用 `req.clone()` 读取 Body，确保不影响后续真实的 Fetch 请求流消费。
+ *
+ * @param req - 原始 Web 标准 Request 对象。
+ * @param config - 站点级缓存配置，决定了哪些字段参与指纹计算。
+ * @returns 返回一个 64 位十六进制的 SHA-256 哈希字符串作为缓存键。
+ *
+ * @example
+ * ```typescript
+ * const cacheKey = await generateCacheKey(request, {
+ *   query: { exclude: ['timestamp'] },
+ *   body: { include: ['id', 'action'] }
+ * });
+ * ```
  */
-declare const generateCacheKey: (req: Request, config: SiteCacheConfig) => string;
+declare function generateCacheKey(req: Request, config: SiteCacheConfig): Promise<string>;
 
 /**
  * fetchWithCache 选项
@@ -126,12 +321,10 @@ interface FetchWithCacheOptions {
     generateKey?: typeof generateCacheKey;
     /**
      * 并发写入任务追踪器
-     * 传入一个外部维护的 Map，用于在跨请求、跨实例时防止针对同一文件的并发重复下载。
-     * Map 的 Key 是缓存 Key，Value 是一个代表写入完成的 Promise。
      */
     activeCacheWrites?: Map<string, Promise<void>>;
 }
-/** 内部流水线上下文，合并了入参和计算出的关键状态 */
+/** 内部流水线上下文 */
 interface FetchWithCacheContext extends FetchWithCacheOptions {
     request: Request;
     fetcher: (req: Request) => Promise<Response>;
@@ -139,15 +332,21 @@ interface FetchWithCacheContext extends FetchWithCacheOptions {
     activeCacheWrites: Map<string, Promise<void>>;
 }
 /**
- * 核心协调函数 (Fetcher Orchestrator)
+ * 核心协调函数：协调请求、缓存命中、并发控制和 SWR
  *
- * 实现了基于流的混合缓存代理核心逻辑，主要机制包括：
- * - **大文件流式处理**：底层完全通过 Streams 实现，代理大文件时自动写入磁盘且防 OOM。
- * - **SWR (Stale-While-Revalidate)**：后台静默更新机制。
- * - **并发防击穿 (Request Coalescing)**：利用 `activeCacheWrites` 将并发请求合并。
- * - **强制离线容灾**：支持 `staleIfError` 和 `forceCache`（无视 Cache-Control 强制入库）。
+ * 流程如下：
+ * 1. 初始化上下文并生成缓存键。
+ * 2. 检查离线模式：若开启则强读取，未命中直接抛错。
+ * 3. 检查请求是否符合缓存规则 (isCacheable)。
+ * 4. 尝试读取缓存并判定状态 (HIT / STALE)。
+ * 5. 处理 SWR (后台更新)。
+ * 6. 处理请求合并 (Request Coalescing)，防止缓存击穿。
+ * 7. 若缓存缺失，发起网络请求并流式写入。
  *
- * 并且会在响应头中自动注入 `x-proxy-cache` 标明缓存命中状态 (`HIT`, `STALE`, `MISS`, `STALE_IF_ERROR`)。
+ * @param request - 标准 Web Request 对象
+ * @param fetcher - 底层发起真实请求的函数
+ * @param options - 缓存协调配置项
+ * @returns 标准 Web Response 对象 (带 x-proxy-cache 标头)
  */
 declare function fetchWithCache(request: Request, fetcher: (req: Request) => Promise<Response>, options: FetchWithCacheOptions): Promise<Response>;
 
@@ -181,33 +380,167 @@ declare function createFetchWithCache(activeCacheWrites?: Map<string, Promise<vo
  */
 declare function createCachedFetch(defaultOptions: FetchWithCacheOptions): (request: Request, fetcher: (req: Request) => Promise<Response>, overrideOptions?: Partial<FetchWithCacheOptions>) => Promise<Response>;
 
+/**
+ * 预缓存请求选项
+ */
+interface PrefetchRequest {
+    /** 请求 URL */
+    url: string;
+    /** 可选的请求配置（method, headers, body 等） */
+    request?: RequestInit;
+}
+interface PrefetchOptions {
+    /** 要预缓存的 URL 列表及其请求选项 */
+    urls: PrefetchRequest[];
+    /** 完整的代理配置 */
+    config: ProxyConfig;
+    /** SmartCache 实例 */
+    cache: SmartCache;
+    /** 自定义 fetcher，默认使用 globalThis.fetch */
+    fetcher?: (req: Request) => Promise<Response>;
+    /** 并发数，默认 3 */
+    concurrency?: number;
+    /** 进度回调 (completed, total, url) */
+    onProgress?: (completed: number, total: number, url: string) => void;
+    /** 取消信号 */
+    signal?: AbortSignal;
+}
+interface PrefetchResult {
+    /** 成功数量 */
+    succeeded: number;
+    /** 失败数量 */
+    failed: number;
+    /** 失败详情 */
+    errors?: Array<{
+        url: string;
+        error: Error;
+    }>;
+}
+/**
+ * 预缓存函数
+ *
+ * 提前将指定的 URL 列表内容存入缓存，支持并发控制和进度回调。
+ * 复用了 `createCachedFetch` 的完整逻辑，自动支持：
+ * - GET/POST/PUT/PATCH/DELETE 等所有方法
+ * - POST body 过滤和缓存键生成
+ * - 站点级配置
+ *
+ * @param options - 预缓存选项
+ * @returns 预缓存结果，包含成功/失败数量和错误详情
+ */
+declare function prefetch(options: PrefetchOptions): Promise<PrefetchResult>;
+
+/**
+ * 判断当前请求是否满足可缓存的基础条件
+ */
+declare function isCacheable(request: Request, config: SiteCacheConfig): Promise<boolean>;
+
 /**
  * 从源对象中根据过滤配置提取数据并标准化。
  *
  * 此函数主要用于生成缓存指纹。它会：
- * 1. 根据 `config` (include/exclude) 过滤键。
+ * 1. 根据 `config` (include/exclude) 过滤键，调用 `isAllowed` 判断每个键是否允许。
  * 2. 对键进行排序以保证指纹的一致性。
  * 3. 将所有键转换为小写。
  * 4. 将值统一包装为数组并进行排序，消除数组项顺序差异。
  *
+ * **关于 `defaultAllowed` 参数**：
+ * - 只有当没有配置 `include` 和 `exclude` 时，`defaultAllowed` 才会生效。
+ * - 如果配置了 `include`（即使为空数组），`defaultAllowed` 也不会生效。
+ * - 详见 `isAllowed` 函数的优先级逻辑。
+ *
  * @param source 原始数据对象 (如 QueryParams, Headers, Cookies)
- * @param config 过滤配置 (白名单或黑名单)
- * @returns 标准化后的数据 Map，键为小写，值为字符串数组
+ * @param config 过滤配置，支持 `include`（白名单）和 `exclude`（黑名单）
+ * @param defaultAllowed 当没有配置时的默认值（默认 `false`，即不提取任何键）
+ * @returns 标准化后的数据 Map，键为小写，值为排序后的字符串数组
+ *
+ * @example
+ * ```typescript
+ * const headers = { 'Content-Type': 'application/json', 'X-Request-Id': '123' };
+ *
+ * // 默认不提取任何键
+ * extractData(headers); // {}
+ *
+ * // 提取所有键
+ * extractData(headers, undefined, true); // { 'content-type': ['application/json'], 'x-request-id': ['123'] }
+ *
+ * // 白名单
+ * extractData(headers, { include: ['content-type'] }); // { 'content-type': ['application/json'] }
+ *
+ * // 黑名单（需要 include 或 defaultAllowed）
+ * extractData(headers, { include: ['*'], exclude: ['x-request-id'] }, true); // { 'content-type': ['application/json'] }
+ * ```
  */
-declare const extractData: (source: Record<string, any>, config?: KeyFilterConfig) => Record<string, string[]>;
+declare const extractData: (source: Record<string, any>, config?: KeyFilterConfig, defaultAllowed?: boolean) => Record<string, string[]>;
 
 /**
  * 判断给定的键是否允许参与缓存指纹计算。
  *
- * 优先级逻辑：
- * 1. 如果配置了 `include` (白名单)，则只有存在于 `include` 中的键才会被允许。
- * 2. 否则，如果配置了 `exclude` (黑名单)，则存在于 `exclude` 中的键将被拒绝。
- * 3. 如果都没有配置，默认允许所有键。
+ * **优先级逻辑**：
+ * 1. `exclude` 命中 → 返回 `false`（优先级最高，会覆盖前面的结果）
+ * 2. `include` 存在且命中 → 返回 `true`
+ * 3. `include` 存在但不命中 → 返回 `false`
+ * 4. 都没有配置 → 使用 `defaultAllowed`（未传则返回 `undefined`）
+ *
+ * **注意**：`include` 和 `exclude` 可以同时配置，此时 `exclude` 优先级更高。
  *
  * @param key 要检查的键名
- * @param config 过滤配置
- * @returns 是否允许
+ * @param config 过滤配置，支持 `include`（白名单）和 `exclude`（黑名单）
+ * @param defaultAllowed 当没有配置或配置未命中时的默认值（可选）
+ * @returns 是否允许。返回 `boolean` 或 `undefined`（当没有配置且未传 defaultAllowed 时）
+ *
+ * @example
+ * ```typescript
+ * // 无配置
+ * isAllowed('key'); // undefined
+ *
+ * // 白名单
+ * isAllowed('id', { include: ['id', 'name'] }); // true
+ * isAllowed('email', { include: ['id', 'name'] }); // false
+ *
+ * // 黑名单
+ * isAllowed('password', { exclude: ['password'] }); // false
+ * isAllowed('name', { exclude: ['password'] }); // undefined
+ *
+ * // 设置默认值
+ * isAllowed('name', { exclude: ['password'] }, true); // true
+ * ```
+ */
+declare function isAllowed(key: string, config?: KeyFilterConfig, defaultAllowed?: boolean): boolean;
+
+/**
+ * 判断一个模式是否为 Glob 模式
+ */
+declare function isGlob(str: string): boolean;
+/**
+ * 通用匹配函数
+ *
+ * 逻辑优先级：
+ * 1. 如果 pattern 是数组，遵循：(匹配任一正向模式) 且 (不匹配任一负向模式)。
+ * 2. 如果 pattern 是 RegExp 对象，直接使用 regex.test(value)。
+ * 3. 如果 pattern 是 "/regex/flags" 格式的字符串，转为 RegExp 后使用 test。
+ * 4. 如果 pattern 是 Glob 字符串，使用 picomatch 进行匹配。
+ * 5. 否则，根据 usePrefix 参数进行前缀匹配或精确匹配。
+ *
+ * @param pattern 匹配模式 (RegExp 或 字符串 或 数组)
+ * @param value 要匹配的值
+ * @param usePrefix 是否在普通字符串匹配时启用前缀匹配 (默认为 false，即精确匹配)
+ */
+declare function isMatch(pattern: string | RegExp | (string | RegExp)[], value: string, usePrefix?: boolean): boolean;
+
+/**
+ * 根据 URL 获取对应的站点缓存配置
+ *
+ * 匹配逻辑：
+ * 1. 遍历 sites 中的所有 key。
+ * 2. 如果 key 是正则或 Glob 格式字符串，则对完整 URL 进行匹配。
+ * 3. 如果 key 是普通字符串，则作为 URL 前缀进行匹配。
+ * 4. 返回第一个匹配到的配置；若均未匹配，则返回 defaultConfig。
+ *
+ * @param urlString 请求的完整 URL
+ * @param proxyConfig 全局代理配置
+ * @returns 匹配到的站点配置
  */
-declare function isAllowed(key: string, config?: KeyFilterConfig): boolean;
+declare function getSiteConfig(urlString: string, proxyConfig: ProxyConfig): SiteCacheConfig;
 
-export { type CacheEntry, type CacheMetadata, type FetchWithCacheContext, type FetchWithCacheOptions, type KeyFilterConfig, type ProxyConfig, type SiteCacheConfig, SmartCache, type SmartCacheOptions, createCachedFetch, createFetchWithCache, extractData, fetchWithCache, generateCacheKey, isAllowed };
+export { type BodyFilterConfig, type CacheEntry, type CacheMetadata, type CacheRule, type FetchWithCacheContext, type FetchWithCacheOptions, type KeyFilterConfig, OfflineCacheMissError, OfflineCacheMissErrorCode, type PrefetchOptions, type PrefetchRequest, type PrefetchResult, type ProxyConfig, type SiteCacheConfig, SmartCache, type SmartCacheOptions, createCachedFetch, createFetchWithCache, extractData, fetchWithCache, generateCacheKey, getSiteConfig, isAllowed, isCacheable, isGlob, isMatch, prefetch };