surgio/build/provider/Provider.d.ts

Generating rules for Surge, Clash, Quantumult like a PRO

import { IncomingHttpHeaders } from 'http';
import { ProviderConfig, SubsciptionCacheItem, SupportProviderEnum } from '../types';
import { DefaultProviderRequestHeaders, GetNodeListFunction, GetNodeListV2Function, GetSubscriptionUserInfoFunction } from './types';
export default abstract class Provider {
    name: string;
    readonly type: SupportProviderEnum;
    readonly config: ProviderConfig;
    supportGetSubscriptionUserInfo: boolean;
    private passGatewayRequestHeaders;
    protected constructor(name: string, config: ProviderConfig);
    /**
     * Generate a cache key for a provider resource based on an identifier.
     *
     * @param identifier - A unique identifier for the resource (typically user-agent + URL)
     * @returns MD5-hashed cache key
     */
    static getResourceCacheKey(...identifiers: (string | Record<string, unknown>)[]): string;
    /**
     * Fetch a cacheable resource from a URL with specified headers.
     * Returns cached response if available within the cache TTL.
     *
     * @param url - The subscription URL to fetch
     * @param headers - HTTP headers to include in the request
     * @param cacheKey - Cache key for storing/retrieving the response (auto-generated if not provided)
     * @returns Subscription data including body and optional user info
     */
    static requestCacheableResource(url: string, headers: DefaultProviderRequestHeaders, cacheKey?: string): Promise<SubsciptionCacheItem>;
    /**
     * Determine the HTTP headers to use for provider requests.
     * Filters headers based on the gateway's passRequestHeaders configuration.
     *
     * @param requestUserAgent - Optional User-Agent from the gateway request
     * @param requestHeaders - Optional custom headers from the gateway request
     * @returns Filtered headers object with required user-agent
     *
     * @remarks
     * - Always includes the user-agent header
     * - If user doesn't want to pass the user-agent header from the gateway request, a
     *   default user-agent from the provider config will be used
     * - The requestUserAgent parameter takes priority over requestHeaders['user-agent']
     * - Filters additional headers based on passGatewayRequestHeaders allowlist
     * - If passGatewayRequestHeaders is empty, only user-agent is returned
     * - The returned object always contains 'user-agent' regardless of configuration
     *
     * @example
     * ```typescript
     * // With passGatewayRequestHeaders: ['accept-language']
     * const headers = provider.determineRequestHeaders(
     *   'custom-ua',
     *   { 'accept-language': 'en-US', 'x-custom': 'value' }
     * )
     * // Returns: { 'user-agent': 'custom-ua', 'accept-language': 'en-US' }
     * // Note: 'x-custom' is filtered out
     * ```
     */
    determineRequestHeaders(requestUserAgent?: string | undefined, requestHeaders?: IncomingHttpHeaders | undefined): DefaultProviderRequestHeaders;
    get nextPort(): number;
    getSubscriptionUserInfo: GetSubscriptionUserInfoFunction;
    abstract getNodeList: GetNodeListFunction;
    /**
     * Get node list and subscription user info in a single call.
     * This is the recommended method over separate getNodeList and getSubscriptionUserInfo calls.
     *
     * Providers must implement this to efficiently fetch both data when they come from the same source.
     */
    abstract getNodeListV2: GetNodeListV2Function;
}