@push.rocks/smartproxy 21.1.7 → 22.6.0

package/ts/proxies/smart-proxy/socket-handler-server.ts

@@ -0,0 +1,279 @@
+import * as plugins from '../../plugins.js';
+import { logger } from '../../core/utils/logger.js';
+import type { IRouteConfig, IRouteContext } from './models/route-types.js';
+import type { RoutePreprocessor } from './route-preprocessor.js';
+
+/**
+ * Unix domain socket server that receives relayed connections from the Rust proxy.
+ *
+ * When Rust encounters a route of type `socket-handler`, it connects to this
+ * Unix socket, sends a JSON metadata line, then proxies the raw TCP bytes.
+ * This server reads the metadata, finds the original JS handler, builds an
+ * IRouteContext, and hands the socket to the handler.
+ */
+export class SocketHandlerServer {
+  private server: plugins.net.Server | null = null;
+  private socketPath: string;
+  private preprocessor: RoutePreprocessor;
+  private activeSockets = new Set<plugins.net.Socket>();
+
+  constructor(preprocessor: RoutePreprocessor) {
+    this.preprocessor = preprocessor;
+    this.socketPath = `/tmp/smartproxy-relay-${process.pid}.sock`;
+  }
+
+  /**
+   * The Unix socket path this server listens on.
+   */
+  public getSocketPath(): string {
+    return this.socketPath;
+  }
+
+  /**
+   * Start listening for relayed connections from Rust.
+   */
+  public async start(): Promise<void> {
+    // Clean up stale socket file
+    try {
+      await plugins.fs.promises.unlink(this.socketPath);
+    } catch {
+      // Ignore if doesn't exist
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      this.server = plugins.net.createServer((socket) => {
+        this.activeSockets.add(socket);
+        socket.on('close', () => this.activeSockets.delete(socket));
+        this.handleConnection(socket);
+      });
+
+      this.server.on('error', (err) => {
+        logger.log('error', `SocketHandlerServer error: ${err.message}`, { component: 'socket-handler-server' });
+      });
+
+      this.server.listen(this.socketPath, () => {
+        logger.log('info', `SocketHandlerServer listening on ${this.socketPath}`, { component: 'socket-handler-server' });
+        resolve();
+      });
+
+      this.server.on('error', reject);
+    });
+  }
+
+  /**
+   * Stop the server and clean up.
+   */
+  public async stop(): Promise<void> {
+    // Destroy all active connections first
+    for (const socket of this.activeSockets) {
+      socket.destroy();
+    }
+    this.activeSockets.clear();
+
+    if (this.server) {
+      return new Promise<void>((resolve) => {
+        this.server!.close(() => {
+          this.server = null;
+          // Clean up socket file
+          plugins.fs.unlink(this.socketPath, () => resolve());
+        });
+      });
+    }
+  }
+
+  /**
+   * Handle an incoming relayed connection from Rust.
+   *
+   * Protocol: Rust sends a single JSON line with metadata, then raw bytes follow.
+   * JSON format: { "routeKey": "my-route", "remoteIP": "1.2.3.4", "remotePort": 12345,
+   *                "localPort": 443, "isTLS": true, "domain": "example.com" }
+   */
+  private handleConnection(socket: plugins.net.Socket): void {
+    let metadataBuffer = '';
+    let metadataParsed = false;
+
+    const onData = (chunk: Buffer) => {
+      if (metadataParsed) return;
+
+      metadataBuffer += chunk.toString('utf8');
+      const newlineIndex = metadataBuffer.indexOf('\n');
+
+      if (newlineIndex === -1) {
+        // Haven't received full metadata line yet
+        if (metadataBuffer.length > 8192) {
+          logger.log('error', 'Socket handler metadata too large, closing', { component: 'socket-handler-server' });
+          socket.destroy();
+        }
+        return;
+      }
+
+      metadataParsed = true;
+      socket.removeListener('data', onData);
+      socket.pause(); // Prevent data loss between handler removal and pipe setup
+
+      const metadataJson = metadataBuffer.slice(0, newlineIndex);
+      const remainingData = metadataBuffer.slice(newlineIndex + 1);
+
+      let metadata: any;
+      try {
+        metadata = JSON.parse(metadataJson);
+      } catch {
+        logger.log('error', `Invalid socket handler metadata JSON: ${metadataJson.slice(0, 200)}`, { component: 'socket-handler-server' });
+        socket.destroy();
+        return;
+      }
+
+      this.dispatchToHandler(socket, metadata, remainingData);
+    };
+
+    socket.on('data', onData);
+    socket.on('error', (err) => {
+      logger.log('error', `Socket handler relay error: ${err.message}`, { component: 'socket-handler-server' });
+    });
+  }
+
+  /**
+   * Dispatch a relayed connection to the appropriate JS handler.
+   */
+  private dispatchToHandler(socket: plugins.net.Socket, metadata: any, remainingData: string): void {
+    const routeKey = metadata.routeKey as string;
+    if (!routeKey) {
+      logger.log('error', 'Socket handler relay missing routeKey', { component: 'socket-handler-server' });
+      socket.destroy();
+      return;
+    }
+
+    const originalRoute = this.preprocessor.getOriginalRoute(routeKey);
+    if (!originalRoute) {
+      logger.log('error', `No handler found for route: ${routeKey}`, { component: 'socket-handler-server' });
+      socket.destroy();
+      return;
+    }
+
+    // Build route context
+    const context: IRouteContext = {
+      port: metadata.localPort || 0,
+      domain: metadata.domain,
+      clientIp: metadata.remoteIP || 'unknown',
+      serverIp: '0.0.0.0',
+      path: metadata.path,
+      isTls: metadata.isTLS || false,
+      tlsVersion: metadata.tlsVersion,
+      routeName: originalRoute.name,
+      routeId: originalRoute.id,
+      timestamp: Date.now(),
+      connectionId: metadata.connectionId || `relay-${Date.now()}`,
+    };
+
+    // If there was remaining data after the metadata line, push it back
+    if (remainingData.length > 0) {
+      socket.unshift(Buffer.from(remainingData, 'utf8'));
+    }
+
+    const handler = originalRoute.action.socketHandler;
+    if (handler) {
+      // Route has an explicit socket handler callback
+      try {
+        const result = handler(socket, context);
+        // If the handler is async, wait for it to finish setup before resuming.
+        // This prevents data loss when async handlers need to do work before
+        // attaching their `data` listeners.
+        if (result && typeof (result as any).then === 'function') {
+          (result as any).then(() => {
+            socket.resume();
+          }).catch((err: any) => {
+            logger.log('error', `Async socket handler rejected for route ${routeKey}: ${err.message}`, { component: 'socket-handler-server' });
+            socket.destroy();
+          });
+        } else {
+          // Synchronous handler — listeners are already attached, safe to resume.
+          socket.resume();
+        }
+      } catch (err: any) {
+        logger.log('error', `Socket handler threw for route ${routeKey}: ${err.message}`, { component: 'socket-handler-server' });
+        socket.destroy();
+      }
+      return;
+    }
+
+    // Route has dynamic host/port functions - resolve and forward
+    if (originalRoute.action.targets && originalRoute.action.targets.length > 0) {
+      this.forwardDynamicRoute(socket, originalRoute, context);
+      return;
+    }
+
+    logger.log('error', `Route ${routeKey} has no socketHandler and no targets`, { component: 'socket-handler-server' });
+    socket.destroy();
+  }
+
+  /**
+   * Forward a connection to a dynamically resolved target.
+   * Used for routes with function-based host/port that Rust cannot handle.
+   */
+  private forwardDynamicRoute(socket: plugins.net.Socket, route: IRouteConfig, context: IRouteContext): void {
+    const targets = route.action.targets!;
+    // Pick a target (round-robin would be ideal, but simple random for now)
+    const target = targets[Math.floor(Math.random() * targets.length)];
+
+    // Resolve host
+    let host: string;
+    if (typeof target.host === 'function') {
+      try {
+        const result = target.host(context);
+        host = Array.isArray(result) ? result[Math.floor(Math.random() * result.length)] : result;
+      } catch (err: any) {
+        logger.log('error', `Dynamic host function failed: ${err.message}`, { component: 'socket-handler-server' });
+        socket.destroy();
+        return;
+      }
+    } else if (typeof target.host === 'string') {
+      host = target.host;
+    } else if (Array.isArray(target.host)) {
+      host = target.host[Math.floor(Math.random() * target.host.length)];
+    } else {
+      host = 'localhost';
+    }
+
+    // Resolve port
+    let port: number;
+    if (typeof target.port === 'function') {
+      try {
+        port = target.port(context);
+      } catch (err: any) {
+        logger.log('error', `Dynamic port function failed: ${err.message}`, { component: 'socket-handler-server' });
+        socket.destroy();
+        return;
+      }
+    } else if (typeof target.port === 'number') {
+      port = target.port;
+    } else {
+      port = context.port;
+    }
+
+    logger.log('debug', `Dynamic forward: ${context.clientIp} -> ${host}:${port}`, { component: 'socket-handler-server' });
+
+    // Connect to the resolved target
+    const backend = plugins.net.connect(port, host, () => {
+      // Pipe bidirectionally
+      socket.pipe(backend);
+      backend.pipe(socket);
+    });
+
+    backend.on('error', (err) => {
+      logger.log('error', `Dynamic forward backend error: ${err.message}`, { component: 'socket-handler-server' });
+      socket.destroy();
+    });
+
+    socket.on('error', () => {
+      backend.destroy();
+    });
+
+    socket.on('close', () => {
+      backend.destroy();
+    });
+
+    backend.on('close', () => {
+      socket.destroy();
+    });
+  }
+}

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

@@ -8,8 +8,8 @@
 // Export route helpers for creating route configurations
 export * from './route-helpers.js';
 
-// Export route validators for validating route configurations
-export * from './route-validators.js';
+// Export route validator (class-based and functional API)
+export * from './route-validator.js';
 
 // Export route utilities for route operations
 export * from './route-utils.js';
@@ -20,6 +20,4 @@ export {
   addRateLimiting,
   addBasicAuth,
   addJwtAuth
-} from './route-helpers.js';
-
-// Migration utilities have been removed as they are no longer needed
+} from './route-helpers.js';

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

@@ -0,0 +1,144 @@
+/**
+ * API Route Helper Functions
+ *
+ * This module provides utility functions for creating API route configurations.
+ */
+
+import type { IRouteConfig, IRouteMatch, IRouteAction } from '../../models/route-types.js';
+import { mergeRouteConfigs } from '../route-utils.js';
+import { createHttpRoute } from './http-helpers.js';
+import { createHttpsTerminateRoute } from './https-helpers.js';
+
+/**
+ * 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 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 {
+  // Normalize API path
+  const normalizedPath = apiPath.startsWith('/') ? apiPath : `/${apiPath}`;
+  const pathWithWildcard = normalizedPath.endsWith('/')
+    ? `${normalizedPath}*`
+    : `${normalizedPath}/*`;
+
+  // Create route match
+  const match: IRouteMatch = {
+    ports: options.useTls
+      ? (options.httpsPort || 443)
+      : (options.httpPort || 80),
+    domains,
+    path: pathWithWildcard
+  };
+
+  // Create route action
+  const action: IRouteAction = {
+    type: 'forward',
+    targets: [target]
+  };
+
+  // Add TLS configuration if using HTTPS
+  if (options.useTls) {
+    action.tls = {
+      mode: 'terminate',
+      certificate: options.certificate || 'auto'
+    };
+  }
+
+  // Add CORS headers if requested
+  const headers: Record<string, Record<string, string>> = {};
+  if (options.addCorsHeaders) {
+    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'
+    };
+  }
+
+  // Create the route config
+  return {
+    match,
+    action,
+    headers: Object.keys(headers).length > 0 ? headers : undefined,
+    name: options.name || `API Route ${normalizedPath} for ${Array.isArray(domains) ? domains.join(', ') : domains}`,
+    priority: options.priority || 100, // Higher priority for specific path matches
+    ...options
+  };
+}
+
+/**
+ * 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);
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Dynamic Route Helper Functions
+ *
+ * This module provides utility functions for creating dynamic routes
+ * with context-based host and port mapping.
+ */
+
+import type { IRouteConfig, IRouteMatch, IRouteAction, TPortRange, IRouteContext } from '../../models/route-types.js';
+
+/**
+ * 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 function createPortOffset(offset: number): (context: IRouteContext) => number {
+  return (context: IRouteContext) => context.port + offset;
+}
+
+/**
+ * Create a port mapping route with context-based port function
+ * @param options Port mapping route options
+ * @returns Route configuration object
+ */
+export 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 route match
+  const match: IRouteMatch = {
+    ports: options.sourcePortRange,
+    domains: options.domains
+  };
+
+  // Create route action
+  const action: IRouteAction = {
+    type: 'forward',
+    targets: [{
+      host: options.targetHost,
+      port: options.portMapper
+    }]
+  };
+
+  // Create the route config
+  return {
+    match,
+    action,
+    name: options.name || `Port Mapping Route for ${options.domains || 'all domains'}`,
+    priority: options.priority,
+    ...options
+  };
+}
+
+/**
+ * Create a simple offset port mapping route
+ * @param options Offset port mapping route options
+ * @returns Route configuration object
+ */
+export function createOffsetPortMappingRoute(options: {
+  ports: TPortRange;
+  targetHost: string | string[];
+  offset: number;
+  name?: string;
+  domains?: string | string[];
+  priority?: number;
+  [key: string]: any;
+}): IRouteConfig {
+  return createPortMappingRoute({
+    sourcePortRange: options.ports,
+    targetHost: options.targetHost,
+    portMapper: (context) => context.port + options.offset,
+    name: options.name || `Offset Mapping (${options.offset > 0 ? '+' : ''}${options.offset}) for ${options.domains || 'all domains'}`,
+    domains: options.domains,
+    priority: options.priority,
+    ...options
+  });
+}
+
+/**
+ * Create a dynamic route with context-based host and port mapping
+ * @param options Dynamic route options
+ * @returns Route configuration object
+ */
+export 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 route match
+  const match: IRouteMatch = {
+    ports: options.ports,
+    domains: options.domains,
+    path: options.path,
+    clientIp: options.clientIp
+  };
+
+  // Create route action
+  const action: IRouteAction = {
+    type: 'forward',
+    targets: [{
+      host: options.targetHost,
+      port: options.portMapper
+    }]
+  };
+
+  // Create the route config
+  return {
+    match,
+    action,
+    name: options.name || `Dynamic Route for ${options.domains || 'all domains'}`,
+    priority: options.priority,
+    ...options
+  };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * HTTP Route Helper Functions
+ *
+ * This module provides utility functions for creating HTTP route configurations.
+ */
+
+import type { IRouteConfig, IRouteMatch, IRouteAction } 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 function createHttpRoute(
+  domains: string | string[],
+  target: { host: string | string[]; port: number },
+  options: Partial<IRouteConfig> = {}
+): IRouteConfig {
+  // Create route match
+  const match: IRouteMatch = {
+    ports: options.match?.ports || 80,
+    domains
+  };
+
+  // Create route action
+  const action: IRouteAction = {
+    type: 'forward',
+    targets: [target]
+  };
+
+  // Create the route config
+  return {
+    match,
+    action,
+    name: options.name || `HTTP Route for ${Array.isArray(domains) ? domains.join(', ') : domains}`,
+    ...options
+  };
+}