@push.rocks/smartproxy 15.0.2 → 16.0.2

package/ts/proxies/smart-proxy/utils/route-patterns.ts

@@ -0,0 +1,309 @@
+/**
+ * Route Patterns
+ * 
+ * This file provides pre-defined route patterns for common use cases.
+ * These patterns can be used as templates for creating route configurations.
+ */
+
+import type { IRouteConfig } from '../models/route-types.js';
+import { createHttpRoute, createHttpsTerminateRoute, createHttpsPassthroughRoute, createCompleteHttpsServer } from './route-helpers.js';
+import { mergeRouteConfigs } from './route-utils.js';
+
+/**
+ * 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 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 {
+  // Normalize apiBasePath to ensure it starts with / and doesn't end with /
+  const normalizedPath = apiBasePath.startsWith('/') 
+    ? apiBasePath 
+    : `/${apiBasePath}`;
+  
+  // Add wildcard to path to match all API endpoints
+  const apiPath = normalizedPath.endsWith('/') 
+    ? `${normalizedPath}*` 
+    : `${normalizedPath}/*`;
+  
+  // Create base route
+  const baseRoute = options.useTls
+    ? createHttpsTerminateRoute(domains, target, {
+        certificate: options.certificate || 'auto'
+      })
+    : createHttpRoute(domains, target);
+  
+  // Add API-specific configurations
+  const apiRoute: Partial<IRouteConfig> = {
+    match: {
+      ...baseRoute.match,
+      path: apiPath
+    },
+    name: options.name || `API Gateway: ${apiPath} -> ${Array.isArray(target.host) ? target.host.join(', ') : target.host}:${target.port}`,
+    priority: options.priority || 100 // Higher priority for specific path matching
+  };
+  
+  // Add CORS headers if requested
+  if (options.addCorsHeaders) {
+    apiRoute.headers = {
+      response: {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        'Access-Control-Max-Age': '86400'
+      }
+    };
+  }
+  
+  return mergeRouteConfigs(baseRoute, apiRoute);
+}
+
+/**
+ * Create a static file server route pattern
+ * @param domains Domain(s) to match
+ * @param rootDirectory Root directory for static files
+ * @param options Additional route options
+ * @returns Static file server route configuration
+ */
+export function createStaticFileServerRoute(
+  domains: string | string[],
+  rootDirectory: string,
+  options: {
+    useTls?: boolean;
+    certificate?: 'auto' | { key: string; cert: string };
+    indexFiles?: string[];
+    cacheControl?: string;
+    path?: string;
+    [key: string]: any;
+  } = {}
+): IRouteConfig {
+  // Create base route with static action
+  const baseRoute: IRouteConfig = {
+    match: {
+      domains,
+      ports: options.useTls ? 443 : 80,
+      path: options.path || '/'
+    },
+    action: {
+      type: 'static',
+      static: {
+        root: rootDirectory,
+        index: options.indexFiles || ['index.html', 'index.htm'],
+        headers: {
+          'Cache-Control': options.cacheControl || 'public, max-age=3600'
+        }
+      }
+    },
+    name: options.name || `Static Server: ${Array.isArray(domains) ? domains.join(', ') : domains}`,
+    priority: options.priority || 50
+  };
+  
+  // Add TLS configuration if requested
+  if (options.useTls) {
+    baseRoute.action.tls = {
+      mode: 'terminate',
+      certificate: options.certificate || 'auto'
+    };
+  }
+  
+  return baseRoute;
+}
+
+/**
+ * Create a WebSocket route pattern
+ * @param domains Domain(s) to match
+ * @param target WebSocket server host and port
+ * @param options Additional route options
+ * @returns WebSocket route configuration
+ */
+export function createWebSocketRoute(
+  domains: string | string[],
+  target: { host: string | string[]; port: number },
+  options: {
+    useTls?: boolean;
+    certificate?: 'auto' | { key: string; cert: string };
+    path?: string;
+    [key: string]: any;
+  } = {}
+): IRouteConfig {
+  // Create base route
+  const baseRoute = options.useTls
+    ? createHttpsTerminateRoute(domains, target, {
+        certificate: options.certificate || 'auto'
+      })
+    : createHttpRoute(domains, target);
+  
+  // Add WebSocket-specific configurations
+  const wsRoute: Partial<IRouteConfig> = {
+    match: {
+      ...baseRoute.match,
+      path: options.path || '/ws',
+      headers: {
+        'Upgrade': 'websocket'
+      }
+    },
+    action: {
+      ...baseRoute.action,
+      websocket: {
+        enabled: true,
+        pingInterval: options.pingInterval || 30000, // 30 seconds
+        pingTimeout: options.pingTimeout || 5000    // 5 seconds
+      }
+    },
+    name: options.name || `WebSocket: ${Array.isArray(domains) ? domains.join(', ') : domains} -> ${Array.isArray(target.host) ? target.host.join(', ') : target.host}:${target.port}`,
+    priority: options.priority || 100 // Higher priority for WebSocket routes
+  };
+  
+  return mergeRouteConfigs(baseRoute, wsRoute);
+}
+
+/**
+ * Create a load balancer route pattern
+ * @param domains Domain(s) to match
+ * @param backends Array of backend servers
+ * @param options Additional route options
+ * @returns Load balancer route configuration
+ */
+export function createLoadBalancerRoute(
+  domains: string | string[],
+  backends: Array<{ host: string; port: number }>,
+  options: {
+    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;
+  } = {}
+): IRouteConfig {
+  // Extract hosts and ensure all backends use the same port
+  const port = backends[0].port;
+  const hosts = backends.map(backend => backend.host);
+  
+  // Create route with multiple hosts for load balancing
+  const baseRoute = options.useTls
+    ? createHttpsTerminateRoute(domains, { host: hosts, port }, {
+        certificate: options.certificate || 'auto'
+      })
+    : createHttpRoute(domains, { host: hosts, port });
+  
+  // Add load balancing specific configurations
+  const lbRoute: Partial<IRouteConfig> = {
+    action: {
+      ...baseRoute.action,
+      loadBalancing: {
+        algorithm: options.algorithm || 'round-robin',
+        healthCheck: options.healthCheck
+      }
+    },
+    name: options.name || `Load Balancer: ${Array.isArray(domains) ? domains.join(', ') : domains}`,
+    priority: options.priority || 50
+  };
+  
+  return mergeRouteConfigs(baseRoute, lbRoute);
+}
+
+/**
+ * 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 function addRateLimiting(
+  baseRoute: IRouteConfig,
+  rateLimit: {
+    maxRequests: number;
+    window: number; // Time window in seconds
+    keyBy?: 'ip' | 'path' | 'header';
+    headerName?: string; // Required if keyBy is 'header'
+    errorMessage?: string;
+  }
+): IRouteConfig {
+  return mergeRouteConfigs(baseRoute, {
+    security: {
+      rateLimit: {
+        enabled: true,
+        maxRequests: rateLimit.maxRequests,
+        window: rateLimit.window,
+        keyBy: rateLimit.keyBy || 'ip',
+        headerName: rateLimit.headerName,
+        errorMessage: rateLimit.errorMessage || 'Rate limit exceeded. Please try again later.'
+      }
+    }
+  });
+}
+
+/**
+ * Create a basic authentication route pattern
+ * @param baseRoute Base route to add authentication to
+ * @param auth Authentication configuration
+ * @returns Route with basic authentication
+ */
+export function addBasicAuth(
+  baseRoute: IRouteConfig,
+  auth: {
+    users: Array<{ username: string; password: string }>;
+    realm?: string;
+    excludePaths?: string[];
+  }
+): IRouteConfig {
+  return mergeRouteConfigs(baseRoute, {
+    security: {
+      basicAuth: {
+        enabled: true,
+        users: auth.users,
+        realm: auth.realm || 'Restricted Area',
+        excludePaths: auth.excludePaths || []
+      }
+    }
+  });
+}
+
+/**
+ * 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 function addJwtAuth(
+  baseRoute: IRouteConfig,
+  jwt: {
+    secret: string;
+    algorithm?: string;
+    issuer?: string;
+    audience?: string;
+    expiresIn?: number; // Time in seconds
+    excludePaths?: string[];
+  }
+): IRouteConfig {
+  return mergeRouteConfigs(baseRoute, {
+    security: {
+      jwtAuth: {
+        enabled: true,
+        secret: jwt.secret,
+        algorithm: jwt.algorithm || 'HS256',
+        issuer: jwt.issuer,
+        audience: jwt.audience,
+        expiresIn: jwt.expiresIn,
+        excludePaths: jwt.excludePaths || []
+      }
+    }
+  });
+}

package/ts/proxies/smart-proxy/utils/route-utils.ts

@@ -0,0 +1,330 @@
+/**
+ * Route Utilities
+ * 
+ * This file provides utility functions for working with route configurations,
+ * including merging, finding, and managing route collections.
+ */
+
+import type { IRouteConfig, IRouteMatch } from '../models/route-types.js';
+import { validateRouteConfig } from './route-validators.js';
+
+/**
+ * Merge two route configurations
+ * The second route's properties will override the first route's properties where they exist
+ * @param baseRoute The base route configuration
+ * @param overrideRoute The route configuration with overriding properties
+ * @returns A new merged route configuration
+ */
+export function mergeRouteConfigs(
+  baseRoute: IRouteConfig,
+  overrideRoute: Partial<IRouteConfig>
+): IRouteConfig {
+  // Create deep copies to avoid modifying original objects
+  const mergedRoute: IRouteConfig = JSON.parse(JSON.stringify(baseRoute));
+
+  // Apply overrides at the top level
+  if (overrideRoute.id) mergedRoute.id = overrideRoute.id;
+  if (overrideRoute.name) mergedRoute.name = overrideRoute.name;
+  if (overrideRoute.enabled !== undefined) mergedRoute.enabled = overrideRoute.enabled;
+  if (overrideRoute.priority !== undefined) mergedRoute.priority = overrideRoute.priority;
+
+  // Merge match configuration
+  if (overrideRoute.match) {
+    mergedRoute.match = { ...mergedRoute.match };
+    
+    if (overrideRoute.match.ports !== undefined) {
+      mergedRoute.match.ports = overrideRoute.match.ports;
+    }
+    
+    if (overrideRoute.match.domains !== undefined) {
+      mergedRoute.match.domains = overrideRoute.match.domains;
+    }
+    
+    if (overrideRoute.match.path !== undefined) {
+      mergedRoute.match.path = overrideRoute.match.path;
+    }
+    
+    if (overrideRoute.match.headers !== undefined) {
+      mergedRoute.match.headers = overrideRoute.match.headers;
+    }
+  }
+
+  // Merge action configuration
+  if (overrideRoute.action) {
+    // If action types are different, replace the entire action
+    if (overrideRoute.action.type && overrideRoute.action.type !== mergedRoute.action.type) {
+      mergedRoute.action = JSON.parse(JSON.stringify(overrideRoute.action));
+    } else {
+      // Otherwise merge the action properties
+      mergedRoute.action = { ...mergedRoute.action };
+      
+      // Merge target
+      if (overrideRoute.action.target) {
+        mergedRoute.action.target = {
+          ...mergedRoute.action.target,
+          ...overrideRoute.action.target
+        };
+      }
+      
+      // Merge TLS options
+      if (overrideRoute.action.tls) {
+        mergedRoute.action.tls = {
+          ...mergedRoute.action.tls,
+          ...overrideRoute.action.tls
+        };
+      }
+      
+      // Merge redirect options
+      if (overrideRoute.action.redirect) {
+        mergedRoute.action.redirect = {
+          ...mergedRoute.action.redirect,
+          ...overrideRoute.action.redirect
+        };
+      }
+      
+      // Merge static options
+      if (overrideRoute.action.static) {
+        mergedRoute.action.static = {
+          ...mergedRoute.action.static,
+          ...overrideRoute.action.static
+        };
+      }
+    }
+  }
+
+  return mergedRoute;
+}
+
+/**
+ * Check if a route matches a domain
+ * @param route The route to check
+ * @param domain The domain to match against
+ * @returns True if the route matches the domain, false otherwise
+ */
+export function routeMatchesDomain(route: IRouteConfig, domain: string): boolean {
+  if (!route.match?.domains) {
+    return false;
+  }
+  
+  const domains = Array.isArray(route.match.domains) 
+    ? route.match.domains 
+    : [route.match.domains];
+  
+  return domains.some(d => {
+    // Handle wildcard domains
+    if (d.startsWith('*.')) {
+      const suffix = d.substring(2);
+      return domain.endsWith(suffix) && domain.split('.').length > suffix.split('.').length;
+    }
+    return d.toLowerCase() === domain.toLowerCase();
+  });
+}
+
+/**
+ * Check if a route matches a port
+ * @param route The route to check
+ * @param port The port to match against
+ * @returns True if the route matches the port, false otherwise
+ */
+export function routeMatchesPort(route: IRouteConfig, port: number): boolean {
+  if (!route.match?.ports) {
+    return false;
+  }
+
+  if (typeof route.match.ports === 'number') {
+    return route.match.ports === port;
+  }
+
+  if (Array.isArray(route.match.ports)) {
+    // Simple case - array of numbers
+    if (typeof route.match.ports[0] === 'number') {
+      return (route.match.ports as number[]).includes(port);
+    }
+
+    // Complex case - array of port ranges
+    if (typeof route.match.ports[0] === 'object') {
+      return (route.match.ports as Array<{ from: number; to: number }>).some(
+        range => port >= range.from && port <= range.to
+      );
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a route matches a path
+ * @param route The route to check
+ * @param path The path to match against
+ * @returns True if the route matches the path, false otherwise
+ */
+export function routeMatchesPath(route: IRouteConfig, path: string): boolean {
+  if (!route.match?.path) {
+    return true; // No path specified means it matches any path
+  }
+  
+  // Handle exact path
+  if (route.match.path === path) {
+    return true;
+  }
+  
+  // Handle path prefix with trailing slash (e.g., /api/)
+  if (route.match.path.endsWith('/') && path.startsWith(route.match.path)) {
+    return true;
+  }
+  
+  // Handle exact path match without trailing slash
+  if (!route.match.path.endsWith('/') && path === route.match.path) {
+    return true;
+  }
+  
+  // Handle wildcard paths (e.g., /api/*)
+  if (route.match.path.endsWith('*')) {
+    const prefix = route.match.path.slice(0, -1);
+    return path.startsWith(prefix);
+  }
+  
+  return false;
+}
+
+/**
+ * Check if a route matches headers
+ * @param route The route to check
+ * @param headers The headers to match against
+ * @returns True if the route matches the headers, false otherwise
+ */
+export function routeMatchesHeaders(
+  route: IRouteConfig, 
+  headers: Record<string, string>
+): boolean {
+  if (!route.match?.headers || Object.keys(route.match.headers).length === 0) {
+    return true; // No headers specified means it matches any headers
+  }
+  
+  // Check each header in the route's match criteria
+  return Object.entries(route.match.headers).every(([key, value]) => {
+    // If the header isn't present in the request, it doesn't match
+    if (!headers[key]) {
+      return false;
+    }
+    
+    // Handle exact match
+    if (typeof value === 'string') {
+      return headers[key] === value;
+    }
+    
+    // Handle regex match
+    if (value instanceof RegExp) {
+      return value.test(headers[key]);
+    }
+    
+    return false;
+  });
+}
+
+/**
+ * Find all routes that match the given criteria
+ * @param routes Array of routes to search
+ * @param criteria Matching criteria
+ * @returns Array of matching routes sorted by priority
+ */
+export function findMatchingRoutes(
+  routes: IRouteConfig[],
+  criteria: {
+    domain?: string;
+    port?: number;
+    path?: string;
+    headers?: Record<string, string>;
+  }
+): IRouteConfig[] {
+  // Filter routes that are enabled and match all provided criteria
+  const matchingRoutes = routes.filter(route => {
+    // Skip disabled routes
+    if (route.enabled === false) {
+      return false;
+    }
+    
+    // Check domain match if specified
+    if (criteria.domain && !routeMatchesDomain(route, criteria.domain)) {
+      return false;
+    }
+    
+    // Check port match if specified
+    if (criteria.port !== undefined && !routeMatchesPort(route, criteria.port)) {
+      return false;
+    }
+    
+    // Check path match if specified
+    if (criteria.path && !routeMatchesPath(route, criteria.path)) {
+      return false;
+    }
+    
+    // Check headers match if specified
+    if (criteria.headers && !routeMatchesHeaders(route, criteria.headers)) {
+      return false;
+    }
+    
+    return true;
+  });
+  
+  // Sort matching routes by priority (higher priority first)
+  return matchingRoutes.sort((a, b) => {
+    const priorityA = a.priority || 0;
+    const priorityB = b.priority || 0;
+    return priorityB - priorityA; // Higher priority first
+  });
+}
+
+/**
+ * Find the best matching route for the given criteria
+ * @param routes Array of routes to search
+ * @param criteria Matching criteria
+ * @returns The best matching route or undefined if no match
+ */
+export function findBestMatchingRoute(
+  routes: IRouteConfig[],
+  criteria: {
+    domain?: string;
+    port?: number;
+    path?: string;
+    headers?: Record<string, string>;
+  }
+): IRouteConfig | undefined {
+  const matchingRoutes = findMatchingRoutes(routes, criteria);
+  return matchingRoutes.length > 0 ? matchingRoutes[0] : undefined;
+}
+
+/**
+ * Create a route ID based on route properties
+ * @param route Route configuration
+ * @returns Generated route ID
+ */
+export function generateRouteId(route: IRouteConfig): string {
+  // Create a deterministic ID based on route properties
+  const domains = Array.isArray(route.match?.domains) 
+    ? route.match.domains.join('-') 
+    : route.match?.domains || 'any';
+    
+  let portsStr = 'any';
+  if (route.match?.ports) {
+    if (Array.isArray(route.match.ports)) {
+      portsStr = route.match.ports.join('-');
+    } else if (typeof route.match.ports === 'number') {
+      portsStr = route.match.ports.toString();
+    }
+  }
+    
+  const path = route.match?.path || 'any';
+  const action = route.action?.type || 'unknown';
+  
+  return `route-${domains}-${portsStr}-${path}-${action}`.replace(/[^a-zA-Z0-9-]/g, '-');
+}
+
+/**
+ * Clone a route configuration
+ * @param route Route to clone
+ * @returns Deep copy of the route
+ */
+export function cloneRoute(route: IRouteConfig): IRouteConfig {
+  return JSON.parse(JSON.stringify(route));
+}