@push.rocks/smartproxy/dist_ts/proxies/smart-proxy/utils/route-helpers.d.ts

A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.

/**
 * Route Helper Functions
 *
 * This file provides utility functions for creating route configurations for common scenarios.
 * These functions aim to simplify the creation of route configurations for typical use cases.
 *
 * This module includes helper functions for creating:
 * - HTTP routes (createHttpRoute)
 * - HTTPS routes with TLS termination (createHttpsTerminateRoute)
 * - HTTP to HTTPS redirects (createHttpToHttpsRedirect)
 * - HTTPS passthrough routes (createHttpsPassthroughRoute)
 * - Complete HTTPS servers with redirects (createCompleteHttpsServer)
 * - Load balancer routes (createLoadBalancerRoute)
 * - API routes (createApiRoute)
 * - WebSocket routes (createWebSocketRoute)
 * - Port mapping routes (createPortMappingRoute, createOffsetPortMappingRoute)
 * - Dynamic routing (createDynamicRoute, createSmartLoadBalancer)
 * - NFTables routes (createNfTablesRoute, createNfTablesTerminateRoute)
 */
import * as plugins from '../../../plugins.js';
import type { IRouteConfig, TPortRange, IRouteContext } from '../models/route-types.js';
/**
 * Create an HTTP-only route configuration
 * @param domains Domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createHttpRoute(domains: string | string[], target: {
    host: string | string[];
    port: number;
}, options?: Partial<IRouteConfig>): IRouteConfig;
/**
 * Create an HTTPS route with TLS termination (including HTTP redirect to HTTPS)
 * @param domains Domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createHttpsTerminateRoute(domains: string | string[], target: {
    host: string | string[];
    port: number;
}, options?: {
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    httpPort?: number | number[];
    httpsPort?: number | number[];
    reencrypt?: boolean;
    name?: string;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create an HTTP to HTTPS redirect route
 * @param domains Domain(s) to match
 * @param httpsPort HTTPS port to redirect to (default: 443)
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createHttpToHttpsRedirect(domains: string | string[], httpsPort?: number, options?: Partial<IRouteConfig>): IRouteConfig;
/**
 * Create an HTTPS passthrough route (SNI-based forwarding without TLS termination)
 * @param domains Domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createHttpsPassthroughRoute(domains: string | string[], target: {
    host: string | string[];
    port: number;
}, options?: Partial<IRouteConfig>): IRouteConfig;
/**
 * Create a complete HTTPS server with HTTP to HTTPS redirects
 * @param domains Domain(s) to match
 * @param target Target host and port
 * @param options Additional configuration options
 * @returns Array of two route configurations (HTTPS and HTTP redirect)
 */
export declare function createCompleteHttpsServer(domains: string | string[], target: {
    host: string | string[];
    port: number;
}, options?: {
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    httpPort?: number | number[];
    httpsPort?: number | number[];
    reencrypt?: boolean;
    name?: string;
    [key: string]: any;
}): IRouteConfig[];
/**
 * Create a load balancer route (round-robin between multiple backend hosts)
 * @param domains Domain(s) to match
 * @param backendsOrHosts Array of backend servers OR array of host strings (legacy)
 * @param portOrOptions Port number (legacy) OR options object
 * @param options Additional route options (legacy)
 * @returns Route configuration object
 */
export declare function createLoadBalancerRoute(domains: string | string[], backendsOrHosts: Array<{
    host: string;
    port: number;
}> | string[], portOrOptions?: number | {
    tls?: {
        mode: 'passthrough' | 'terminate' | 'terminate-and-reencrypt';
        certificate?: 'auto' | {
            key: string;
            cert: string;
        };
    };
    useTls?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    algorithm?: 'round-robin' | 'least-connections' | 'ip-hash';
    healthCheck?: {
        path: string;
        interval: number;
        timeout: number;
        unhealthyThreshold: number;
        healthyThreshold: number;
    };
    [key: string]: any;
}, options?: {
    tls?: {
        mode: 'passthrough' | 'terminate' | 'terminate-and-reencrypt';
        certificate?: 'auto' | {
            key: string;
            cert: string;
        };
    };
    [key: string]: any;
}): IRouteConfig;
/**
 * Create an API route configuration
 * @param domains Domain(s) to match
 * @param apiPath API base path (e.g., "/api")
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createApiRoute(domains: string | string[], apiPath: string, target: {
    host: string | string[];
    port: number;
}, options?: {
    useTls?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    addCorsHeaders?: boolean;
    httpPort?: number | number[];
    httpsPort?: number | number[];
    name?: string;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a WebSocket route configuration
 * @param domains Domain(s) to match
 * @param targetOrPath Target server OR WebSocket path (legacy)
 * @param targetOrOptions Target server (legacy) OR options
 * @param options Additional route options (legacy)
 * @returns Route configuration object
 */
export declare function createWebSocketRoute(domains: string | string[], targetOrPath: {
    host: string | string[];
    port: number;
} | string, targetOrOptions?: {
    host: string | string[];
    port: number;
} | {
    useTls?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    path?: string;
    httpPort?: number | number[];
    httpsPort?: number | number[];
    pingInterval?: number;
    pingTimeout?: number;
    name?: string;
    [key: string]: any;
}, options?: {
    useTls?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    httpPort?: number | number[];
    httpsPort?: number | number[];
    pingInterval?: number;
    pingTimeout?: number;
    name?: string;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a helper function that applies a port offset
 * @param offset The offset to apply to the matched port
 * @returns A function that adds the offset to the matched port
 */
export declare function createPortOffset(offset: number): (context: IRouteContext) => number;
/**
 * Create a port mapping route with context-based port function
 * @param options Port mapping route options
 * @returns Route configuration object
 */
export declare function createPortMappingRoute(options: {
    sourcePortRange: TPortRange;
    targetHost: string | string[] | ((context: IRouteContext) => string | string[]);
    portMapper: (context: IRouteContext) => number;
    name?: string;
    domains?: string | string[];
    priority?: number;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a simple offset port mapping route
 * @param options Offset port mapping route options
 * @returns Route configuration object
 */
export declare function createOffsetPortMappingRoute(options: {
    ports: TPortRange;
    targetHost: string | string[];
    offset: number;
    name?: string;
    domains?: string | string[];
    priority?: number;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a dynamic route with context-based host and port mapping
 * @param options Dynamic route options
 * @returns Route configuration object
 */
export declare function createDynamicRoute(options: {
    ports: TPortRange;
    targetHost: (context: IRouteContext) => string | string[];
    portMapper: (context: IRouteContext) => number;
    name?: string;
    domains?: string | string[];
    path?: string;
    clientIp?: string[];
    priority?: number;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a smart load balancer with dynamic domain-based backend selection
 * @param options Smart load balancer options
 * @returns Route configuration object
 */
export declare function createSmartLoadBalancer(options: {
    ports: TPortRange;
    domainTargets: Record<string, string | string[]>;
    portMapper: (context: IRouteContext) => number;
    name?: string;
    defaultTarget?: string | string[];
    priority?: number;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create an NFTables-based route for high-performance packet forwarding
 * @param nameOrDomains Name or domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createNfTablesRoute(nameOrDomains: string | string[], target: {
    host: string;
    port: number | 'preserve';
}, options?: {
    ports?: TPortRange;
    protocol?: 'tcp' | 'udp' | 'all';
    preserveSourceIP?: boolean;
    ipAllowList?: string[];
    ipBlockList?: string[];
    maxRate?: string;
    priority?: number;
    useTls?: boolean;
    tableName?: string;
    useIPSets?: boolean;
    useAdvancedNAT?: boolean;
}): IRouteConfig;
/**
 * Create an NFTables-based TLS termination route
 * @param nameOrDomains Name or domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createNfTablesTerminateRoute(nameOrDomains: string | string[], target: {
    host: string;
    port: number | 'preserve';
}, options?: {
    ports?: TPortRange;
    protocol?: 'tcp' | 'udp' | 'all';
    preserveSourceIP?: boolean;
    ipAllowList?: string[];
    ipBlockList?: string[];
    maxRate?: string;
    priority?: number;
    tableName?: string;
    useIPSets?: boolean;
    useAdvancedNAT?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
}): IRouteConfig;
/**
 * Create a complete NFTables-based HTTPS setup with HTTP redirect
 * @param nameOrDomains Name or domain(s) to match
 * @param target Target host and port
 * @param options Additional route options
 * @returns Array of two route configurations (HTTPS and HTTP redirect)
 */
export declare function createCompleteNfTablesHttpsServer(nameOrDomains: string | string[], target: {
    host: string;
    port: number | 'preserve';
}, options?: {
    httpPort?: TPortRange;
    httpsPort?: TPortRange;
    protocol?: 'tcp' | 'udp' | 'all';
    preserveSourceIP?: boolean;
    ipAllowList?: string[];
    ipBlockList?: string[];
    maxRate?: string;
    priority?: number;
    tableName?: string;
    useIPSets?: boolean;
    useAdvancedNAT?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
}): IRouteConfig[];
/**
 * Create a socket handler route configuration
 * @param domains Domain(s) to match
 * @param ports Port(s) to listen on
 * @param handler Socket handler function
 * @param options Additional route options
 * @returns Route configuration object
 */
export declare function createSocketHandlerRoute(domains: string | string[], ports: TPortRange, handler: (socket: plugins.net.Socket) => void | Promise<void>, options?: {
    name?: string;
    priority?: number;
    path?: string;
}): IRouteConfig;
/**
 * Pre-built socket handlers for common use cases
 */
export declare const SocketHandlers: {
    /**
     * Simple echo server handler
     */
    echo: (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * TCP proxy handler
     */
    proxy: (targetHost: string, targetPort: number) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * Line-based protocol handler
     */
    lineProtocol: (handler: (line: string, socket: plugins.net.Socket) => void) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * Simple HTTP response handler (for testing)
     */
    httpResponse: (statusCode: number, body: string) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * Block connection immediately
     */
    block: (message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * HTTP block response
     */
    httpBlock: (statusCode?: number, message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * HTTP redirect handler
     * Now uses the centralized detection module for HTTP parsing
     */
    httpRedirect: (locationTemplate: string, statusCode?: number) => (socket: plugins.net.Socket, context: IRouteContext) => void;
    /**
     * HTTP server handler for ACME challenges and other HTTP needs
     * Now uses the centralized detection module for HTTP parsing
     */
    httpServer: (handler: (req: {
        method: string;
        url: string;
        headers: Record<string, string>;
        body?: string;
    }, res: {
        status: (code: number) => void;
        header: (name: string, value: string) => void;
        send: (data: string) => void;
        end: () => void;
    }) => void) => (socket: plugins.net.Socket, context: IRouteContext) => void;
};
/**
 * Create an API Gateway route pattern
 * @param domains Domain(s) to match
 * @param apiBasePath Base path for API endpoints (e.g., '/api')
 * @param target Target host and port
 * @param options Additional route options
 * @returns API route configuration
 */
export declare function createApiGatewayRoute(domains: string | string[], apiBasePath: string, target: {
    host: string | string[];
    port: number;
}, options?: {
    useTls?: boolean;
    certificate?: 'auto' | {
        key: string;
        cert: string;
    };
    addCorsHeaders?: boolean;
    [key: string]: any;
}): IRouteConfig;
/**
 * Create a rate limiting route pattern
 * @param baseRoute Base route to add rate limiting to
 * @param rateLimit Rate limiting configuration
 * @returns Route with rate limiting
 */
export declare function addRateLimiting(baseRoute: IRouteConfig, rateLimit: {
    maxRequests: number;
    window: number;
    keyBy?: 'ip' | 'path' | 'header';
    headerName?: string;
    errorMessage?: string;
}): IRouteConfig;
/**
 * Create a basic authentication route pattern
 * @param baseRoute Base route to add authentication to
 * @param auth Authentication configuration
 * @returns Route with basic authentication
 */
export declare function addBasicAuth(baseRoute: IRouteConfig, auth: {
    users: Array<{
        username: string;
        password: string;
    }>;
    realm?: string;
    excludePaths?: string[];
}): IRouteConfig;
/**
 * Create a JWT authentication route pattern
 * @param baseRoute Base route to add JWT authentication to
 * @param jwt JWT authentication configuration
 * @returns Route with JWT authentication
 */
export declare function addJwtAuth(baseRoute: IRouteConfig, jwt: {
    secret: string;
    algorithm?: string;
    issuer?: string;
    audience?: string;
    expiresIn?: number;
    excludePaths?: string[];
}): IRouteConfig;