@push.rocks/smartproxy
Version:
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.
219 lines (218 loc) • 7.58 kB
TypeScript
import * as plugins from '../../plugins.js';
import { ConnectionManager } from './connection-manager.js';
import { SecurityManager } from './security-manager.js';
import { TlsManager } from './tls-manager.js';
import { HttpProxyBridge } from './http-proxy-bridge.js';
import { TimeoutManager } from './timeout-manager.js';
import { SharedRouteManager as RouteManager } from '../../core/routing/route-manager.js';
import { RouteConnectionHandler } from './route-connection-handler.js';
import { NFTablesManager } from './nftables-manager.js';
import { SmartCertManager, type ICertStatus } from './certificate-manager.js';
import type { ISmartProxyOptions } from './models/interfaces.js';
import type { IRouteConfig } from './models/route-types.js';
import { AcmeStateManager } from './acme-state-manager.js';
import { MetricsCollector } from './metrics-collector.js';
import type { IMetrics } from './models/metrics-types.js';
/**
* SmartProxy - Pure route-based API
*
* SmartProxy is a unified proxy system that works with routes to define connection handling behavior.
* Each route contains matching criteria (ports, domains, etc.) and an action to take (forward, redirect, block).
*
* Configuration is provided through a set of routes, with each route defining:
* - What to match (ports, domains, paths, client IPs)
* - What to do with matching traffic (forward, redirect, block)
* - How to handle TLS (passthrough, terminate, terminate-and-reencrypt)
* - Security settings (IP restrictions, connection limits)
* - Advanced options (timeout, headers, etc.)
*/
export declare class SmartProxy extends plugins.EventEmitter {
private portManager;
private connectionLogger;
private isShuttingDown;
connectionManager: ConnectionManager;
securityManager: SecurityManager;
tlsManager: TlsManager;
httpProxyBridge: HttpProxyBridge;
timeoutManager: TimeoutManager;
routeManager: RouteManager;
routeConnectionHandler: RouteConnectionHandler;
nftablesManager: NFTablesManager;
certManager: SmartCertManager | null;
private globalChallengeRouteActive;
private routeUpdateLock;
acmeStateManager: AcmeStateManager;
metricsCollector: MetricsCollector;
private portUsageMap;
/**
* Constructor for SmartProxy
*
* @param settingsArg Configuration options containing routes and other settings
* Routes define how traffic is matched and handled, with each route having:
* - match: criteria for matching traffic (ports, domains, paths, IPs)
* - action: what to do with matched traffic (forward, redirect, block)
*
* Example:
* ```ts
* const proxy = new SmartProxy({
* routes: [
* {
* match: {
* ports: 443,
* domains: ['example.com', '*.example.com']
* },
* action: {
* type: 'forward',
* target: { host: '10.0.0.1', port: 8443 },
* tls: { mode: 'passthrough' }
* }
* }
* ],
* defaults: {
* target: { host: 'localhost', port: 8080 },
* security: { ipAllowList: ['*'] }
* }
* });
* ```
*/
constructor(settingsArg: ISmartProxyOptions);
/**
* The settings for the SmartProxy
*/
settings: ISmartProxyOptions;
/**
* Helper method to create and configure certificate manager
* This ensures consistent setup including the required ACME callback
*/
private createCertificateManager;
/**
* Initialize certificate manager
*/
private initializeCertificateManager;
/**
* Check if we have routes with static certificates
*/
private hasStaticCertRoutes;
/**
* Start the proxy server with support for both configuration types
*/
start(): Promise<void>;
/**
* Extract domain configurations from routes for certificate provisioning
*
* Note: This method has been removed as we now work directly with routes
*/
/**
* Stop the proxy server
*/
stop(): Promise<void>;
/**
* Updates the domain configurations for the proxy
*
* Note: This legacy method has been removed. Use updateRoutes instead.
*/
updateDomainConfigs(): Promise<void>;
/**
* Verify the challenge route has been properly removed from routes
*/
private verifyChallengeRouteRemoved;
/**
* Update routes with new configuration
*
* This method replaces the current route configuration with the provided routes.
* It also provisions certificates for routes that require TLS termination and have
* `certificate: 'auto'` set in their TLS configuration.
*
* @param newRoutes Array of route configurations to use
*
* Example:
* ```ts
* proxy.updateRoutes([
* {
* match: { ports: 443, domains: 'secure.example.com' },
* action: {
* type: 'forward',
* target: { host: '10.0.0.1', port: 8443 },
* tls: { mode: 'terminate', certificate: 'auto' }
* }
* }
* ]);
* ```
*/
updateRoutes(newRoutes: IRouteConfig[]): Promise<void>;
/**
* Manually provision a certificate for a route
*/
provisionCertificate(routeName: string): Promise<void>;
/**
* Update the port usage map based on the provided routes
*
* This tracks which ports are used by which routes, allowing us to
* detect when a port is no longer needed and can be released.
*/
private updatePortUsageMap;
/**
* Find ports that have no routes in the new configuration
*/
private findOrphanedPorts;
/**
* Force renewal of a certificate
*/
renewCertificate(routeName: string): Promise<void>;
/**
* Get certificate status for a route
*/
getCertificateStatus(routeName: string): ICertStatus | undefined;
/**
* Get proxy metrics with clean API
*
* @returns IMetrics interface with grouped metrics methods
*/
getMetrics(): IMetrics;
/**
* Validates if a domain name is valid for certificate issuance
*/
private isValidDomain;
/**
* Add a new listening port without changing the route configuration
*
* This allows you to add a port listener without updating routes.
* Useful for preparing to listen on a port before adding routes for it.
*
* @param port The port to start listening on
* @returns Promise that resolves when the port is listening
*/
addListeningPort(port: number): Promise<void>;
/**
* Stop listening on a specific port without changing the route configuration
*
* This allows you to stop a port listener without updating routes.
* Useful for temporary maintenance or port changes.
*
* @param port The port to stop listening on
* @returns Promise that resolves when the port is closed
*/
removeListeningPort(port: number): Promise<void>;
/**
* Get a list of all ports currently being listened on
*
* @returns Array of port numbers
*/
getListeningPorts(): number[];
/**
* Get statistics about current connections
*/
getStatistics(): any;
/**
* Get a list of eligible domains for ACME certificates
*/
getEligibleDomainsForCertificates(): string[];
/**
* Get NFTables status
*/
getNfTablesStatus(): Promise<Record<string, any>>;
/**
* Validate ACME configuration
*/
private validateAcmeConfiguration;
}