@push.rocks/smartproxy 27.22.0 → 28.1.0

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

@@ -8,6 +8,10 @@
 // Export route validator (class-based and functional API)
 export * from './route-validator.js';
 
+// Export the error SmartProxy throws when it refuses a route set
+export { RouteValidationError } from './route-validation-error.js';
+export type { IRouteValidationErrorEntry } from './route-validation-error.js';
+
 // Export route utilities for route operations
 export * from './route-utils.js';
 

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

@@ -0,0 +1,60 @@
+/**
+ * The validation failures of one route, as the route validators report them.
+ */
+export interface IRouteValidationErrorEntry {
+  /** The route's position in the validated route list. */
+  index: number;
+  /**
+   * The route's label from `RouteValidator.getRouteLabels()`: its name, else its id,
+   * else `route[<index>]`; a name or id that several routes share gets `[<index>]` appended.
+   */
+  route: string;
+  /** Every reason the route was rejected. */
+  messages: string[];
+}
+
+const MAX_ROUTES_IN_MESSAGE = 10;
+const MAX_MESSAGES_PER_ROUTE_IN_MESSAGE = 5;
+const MAX_TEXT_LENGTH_IN_MESSAGE = 200;
+
+function truncateText(textArg: string): string {
+  return textArg.length > MAX_TEXT_LENGTH_IN_MESSAGE
+    ? `${textArg.slice(0, MAX_TEXT_LENGTH_IN_MESSAGE)}…`
+    : textArg;
+}
+
+function formatEntry(entryArg: IRouteValidationErrorEntry): string {
+  const shownMessages = entryArg.messages
+    .slice(0, MAX_MESSAGES_PER_ROUTE_IN_MESSAGE)
+    .map(truncateText);
+  const hiddenMessageCount = entryArg.messages.length - shownMessages.length;
+  if (hiddenMessageCount > 0) {
+    shownMessages.push(`and ${hiddenMessageCount} more`);
+  }
+  return `route '${truncateText(entryArg.route)}': ${shownMessages.join('; ')}`;
+}
+
+function formatMessage(summaryArg: string, errorsArg: IRouteValidationErrorEntry[]): string {
+  const shownRoutes = errorsArg.slice(0, MAX_ROUTES_IN_MESSAGE).map(formatEntry);
+  const hiddenRouteCount = errorsArg.length - shownRoutes.length;
+  if (hiddenRouteCount > 0) {
+    shownRoutes.push(`and ${hiddenRouteCount} more route(s)`);
+  }
+  return `${summaryArg}: ${errorsArg.length} route(s) have errors: ${shownRoutes.join(' | ')}`;
+}
+
+/**
+ * Thrown when SmartProxy refuses a route set because it failed validation.
+ *
+ * `errors` lists every rejected route with all its reasons. The message names the
+ * first routes and reasons only, so a large route set cannot produce an unbounded message.
+ */
+export class RouteValidationError extends Error {
+  public readonly errors: IRouteValidationErrorEntry[];
+
+  constructor(summaryArg: string, errorsArg: IRouteValidationErrorEntry[]) {
+    super(formatMessage(summaryArg, errorsArg));
+    this.name = 'RouteValidationError';
+    this.errors = errorsArg;
+  }
+}

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

@@ -1,12 +1,13 @@
 import { logger } from '../../../core/utils/logger.js';
 import type { IInboundProxyProtocolPolicy, IRouteConfig, IRouteMatch, IRouteAction, TPortRange, TTransportProtocol } from '../models/route-types.js';
+import { RouteValidationError, type IRouteValidationErrorEntry } from './route-validation-error.js';
 
 /**
  * Validates route configurations for correctness and safety
  */
 export class RouteValidator {
   private static readonly VALID_TLS_MODES = ['terminate', 'passthrough', 'terminate-and-reencrypt'];
-  private static readonly VALID_ACTION_TYPES = ['forward', 'socket-handler'];
+  private static readonly VALID_ACTION_TYPES = ['forward', 'socket-handler', 'respond'];
   private static readonly VALID_PROTOCOLS = ['tcp', 'http', 'https', 'ws', 'wss', 'udp', 'quic', 'http3'];
   private static readonly MAX_PORTS = 100;
   private static readonly MAX_DOMAINS = 1000;
@@ -149,6 +150,14 @@ export class RouteValidator {
         }
       }
 
+      // Validate fixed response
+      if (route.action.type === 'respond') {
+        errors.push(...getRespondActionErrors(route.action));
+        if (route.match) {
+          errors.push(...getRespondMatchErrors(route.match));
+        }
+      }
+
       // Validate forward target
       if (route.action.type === 'forward') {
         if (!route.action.targets || route.action.targets.length === 0) {
@@ -315,62 +324,84 @@ export class RouteValidator {
   }
 
   /**
-   * Validate multiple route configurations
+   * Label every route for validation reports: its name, else its id, else `route[<index>]`.
+   * A name or id that several routes share gets `[<index>]` appended, so every label is unique.
+   */
+  public static getRouteLabels(routes: IRouteConfig[]): string[] {
+    const baseLabels = routes.map((route, index) => route.name || route.id || `route[${index}]`);
+    const labelCounts = new Map<string, number>();
+    for (const label of baseLabels) {
+      labelCounts.set(label, (labelCounts.get(label) ?? 0) + 1);
+    }
+    return baseLabels.map((label, index) => (labelCounts.get(label)! > 1 ? `${label}[${index}]` : label));
+  }
+
+  /**
+   * Validate multiple route configurations.
+   *
+   * `entries` lists every invalid route by position and label; `errors` maps the same
+   * labels to the reasons.
    */
-  public static validateRoutes(routes: IRouteConfig[]): { valid: boolean; errors: Map<string, string[]> } {
-    const errorMap = new Map<string, string[]>();
-    let valid = true;
+  public static validateRoutes(routes: IRouteConfig[]): {
+    valid: boolean;
+    errors: Map<string, string[]>;
+    entries: IRouteValidationErrorEntry[];
+  } {
+    const messagesByIndex: string[][] = routes.map(() => []);
 
     // Check for duplicate route names
     const routeNames = new Set<string>();
-    for (const route of routes) {
+    routes.forEach((route, index) => {
       if (route.name && routeNames.has(route.name)) {
-        const existingErrors = errorMap.get(route.name) || [];
-        existingErrors.push('Duplicate route name');
-        errorMap.set(route.name, existingErrors);
-        valid = false;
+        messagesByIndex[index].push('Duplicate route name');
       }
       if (route.name) {
         routeNames.add(route.name);
       }
-    }
+    });
 
     // Validate each route
-    for (const route of routes) {
-      const result = this.validateRoute(route);
-      if (!result.valid) {
-        errorMap.set(route.name || 'unnamed', result.errors);
-        valid = false;
-      }
-    }
+    routes.forEach((route, index) => {
+      messagesByIndex[index].push(...this.validateRoute(route).errors);
+    });
+
+    const labels = this.getRouteLabels(routes);
 
     // Check for conflicting routes
-    const conflicts = this.findRouteConflicts(routes);
-    if (conflicts.length > 0) {
-      for (const conflict of conflicts) {
-        const existingErrors = errorMap.get(conflict.route) || [];
-        existingErrors.push(conflict.message);
-        errorMap.set(conflict.route, existingErrors);
-      }
-      valid = false;
+    for (const conflict of this.findRouteConflicts(routes, labels)) {
+      messagesByIndex[conflict.index].push(conflict.message);
     }
 
-    return { valid, errors: errorMap };
+    const entries: IRouteValidationErrorEntry[] = [];
+    messagesByIndex.forEach((messages, index) => {
+      if (messages.length > 0) {
+        entries.push({ index, route: labels[index], messages });
+      }
+    });
+
+    return {
+      valid: entries.length === 0,
+      errors: new Map(entries.map((entry) => [entry.route, entry.messages])),
+      entries,
+    };
   }
 
   /**
    * Find potential conflicts between routes
    */
-  private static findRouteConflicts(routes: IRouteConfig[]): Array<{ route: string; message: string }> {
-    const conflicts: Array<{ route: string; message: string }> = [];
-    
-    // Group routes by port
-    const portMap = new Map<number, IRouteConfig[]>();
-    
-    for (const route of routes) {
+  private static findRouteConflicts(
+    routes: IRouteConfig[],
+    labels: string[],
+  ): Array<{ index: number; message: string }> {
+    const conflicts: Array<{ index: number; message: string }> = [];
+
+    // Group route indices by port
+    const portMap = new Map<number, number[]>();
+
+    routes.forEach((route, index) => {
       if (route.match?.ports) {
         const ports = Array.isArray(route.match.ports) ? route.match.ports : [route.match.ports];
-        
+
         // Expand port ranges to individual ports
         const expandedPorts: number[] = [];
         for (const port of ports) {
@@ -382,25 +413,25 @@ export class RouteValidator {
             }
           }
         }
-        
+
         for (const port of expandedPorts) {
           const routesOnPort = portMap.get(port) || [];
-          routesOnPort.push(route);
+          routesOnPort.push(index);
           portMap.set(port, routesOnPort);
         }
       }
-    }
+    });
 
     // Check for conflicting catch-all routes on the same port
     for (const [port, routesOnPort] of portMap) {
-      const catchAllRoutes = routesOnPort.filter(r => 
-        this.isCatchAllDomainMatch(r.match) && !this.hasSourceScope(r.match)
+      const catchAllRoutes = routesOnPort.filter((index) =>
+        this.isCatchAllDomainMatch(routes[index].match) && !this.hasSourceScope(routes[index].match)
       );
-      
+
       if (catchAllRoutes.length > 1) {
-        for (const route of catchAllRoutes) {
+        for (const index of catchAllRoutes) {
           conflicts.push({
-            route: route.name || 'unnamed',
+            index,
             message: `Multiple catch-all routes on port ${port}`
           });
         }
@@ -411,9 +442,9 @@ export class RouteValidator {
     // a shorthand for the full port/transport listener policy, so every route
     // sharing that listener must either all omit it or all use an identical one.
     const listenerPolicies = new Map<string, { route: string; fingerprint: string }>();
-    for (const route of routes) {
+    routes.forEach((route, index) => {
       if (!route.match?.ports) {
-        continue;
+        return;
       }
 
       for (const port of this.expandPorts(route.match.ports)) {
@@ -423,18 +454,18 @@ export class RouteValidator {
           const existing = listenerPolicies.get(key);
           if (!existing) {
             listenerPolicies.set(key, {
-              route: route.name || 'unnamed',
+              route: labels[index],
               fingerprint,
             });
           } else if (existing.fingerprint !== fingerprint) {
             conflicts.push({
-              route: route.name || 'unnamed',
+              index,
               message: `Conflicting inbound PROXY protocol policy on ${transport} port ${port} (differs from ${existing.route})`,
             });
           }
         }
       }
-    }
+    });
 
     return conflicts;
   }
@@ -719,6 +750,120 @@ export function validateRouteMatch(match: IRouteMatch): { valid: boolean; errors
   };
 }
 
+/** Largest fixed-response body a `respond` route may carry, in UTF-8 bytes. */
+export const MAX_FIXED_RESPONSE_BODY_BYTES = 65536;
+
+/** Hop-by-hop or computed headers a fixed response must not set. */
+const FIXED_RESPONSE_FORBIDDEN_HEADERS = [
+  'connection',
+  'keep-alive',
+  'transfer-encoding',
+  'upgrade',
+  'te',
+  'trailer',
+  'proxy-connection',
+  'content-length',
+];
+
+const HTTP_TOKEN_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const HTTP_HEADER_VALUE_PATTERN = /^[\t\x20-\x7E]*$/;
+
+/**
+ * Returns the action-level errors of a `respond` route: the fixed response itself,
+ * and the forwarding, handler, UDP and TLS options a fixed response cannot use.
+ */
+function getRespondActionErrors(action: IRouteAction): string[] {
+  const errors: string[] = [];
+
+  if (action.targets !== undefined) {
+    errors.push('respond action must not define targets');
+  }
+  if (action.socketHandler !== undefined || action.datagramHandler !== undefined) {
+    errors.push('respond action must not define a socketHandler or datagramHandler');
+  }
+  if (action.forwardingEngine !== undefined || action.nftables !== undefined) {
+    errors.push('respond action must not define forwardingEngine or nftables options');
+  }
+  if (action.udp !== undefined) {
+    errors.push('respond action does not support UDP or HTTP/3 (action.udp)');
+  }
+  if (action.tls && action.tls.mode !== 'terminate') {
+    errors.push(`respond action supports only TLS mode "terminate", got "${action.tls.mode}"`);
+  }
+
+  const response = action.response;
+  if (!response || typeof response !== 'object') {
+    errors.push('respond action requires a response object');
+    return errors;
+  }
+
+  if (!Number.isInteger(response.status) || response.status < 200 || response.status > 599) {
+    errors.push(`response.status must be an integer from 200 to 599, got ${response.status}`);
+  }
+
+  const seenHeaders = new Set<string>();
+  let hasContentType = false;
+  if (response.headers !== undefined) {
+    if (!response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
+      errors.push('response.headers must be an object of header names to string values');
+    } else {
+      for (const [name, value] of Object.entries(response.headers)) {
+        const lowerName = name.toLowerCase();
+        if (!HTTP_TOKEN_PATTERN.test(name)) {
+          errors.push(`response.headers has an invalid header name: ${name}`);
+          continue;
+        }
+        if (FIXED_RESPONSE_FORBIDDEN_HEADERS.includes(lowerName)) {
+          errors.push(`response.headers must not set ${lowerName}`);
+        }
+        if (seenHeaders.has(lowerName)) {
+          errors.push(`response.headers sets ${lowerName} more than once`);
+        }
+        seenHeaders.add(lowerName);
+        if (typeof value !== 'string' || !HTTP_HEADER_VALUE_PATTERN.test(value)) {
+          errors.push(`response.headers.${name} must be a string of visible ASCII characters`);
+        }
+        if (lowerName === 'content-type') {
+          hasContentType = true;
+        }
+      }
+    }
+  }
+
+  if (response.body !== undefined) {
+    if (typeof response.body !== 'string') {
+      errors.push('response.body must be a string');
+    } else if (response.body.length > 0) {
+      const bodyBytes = new TextEncoder().encode(response.body).length;
+      if (bodyBytes > MAX_FIXED_RESPONSE_BODY_BYTES) {
+        errors.push(`response.body is ${bodyBytes} bytes, the maximum is ${MAX_FIXED_RESPONSE_BODY_BYTES}`);
+      }
+      if (response.status === 204 || response.status === 304) {
+        errors.push(`response.status ${response.status} must not carry a body`);
+      }
+      if (!hasContentType) {
+        errors.push('response.body requires an explicit content-type header');
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Returns the match-level errors of a `respond` route: a fixed response is HTTP over TCP only.
+ */
+function getRespondMatchErrors(match: IRouteMatch): string[] {
+  const errors: string[] = [];
+  if (match.transport === 'udp' || match.transport === 'all') {
+    errors.push(`respond routes support only TCP transport, got "${match.transport}"`);
+  }
+  if (match.protocol !== undefined && match.protocol !== 'http') {
+    errors.push(`respond routes support only protocol "http", got "${match.protocol}"`);
+  }
+  return errors;
+}
+
 /**
  * Validates a route action configuration
  * @param action Route action configuration to validate
@@ -729,10 +874,14 @@ export function validateRouteAction(action: IRouteAction): { valid: boolean; err
 
   if (!action.type) {
     errors.push('Action type is required');
-  } else if (!['forward', 'socket-handler'].includes(action.type)) {
+  } else if (!['forward', 'socket-handler', 'respond'].includes(action.type)) {
     errors.push(`Invalid action type: ${action.type}`);
   }
 
+  if (action.type === 'respond') {
+    errors.push(...getRespondActionErrors(action));
+  }
+
   if (action.type === 'forward') {
     if (!action.targets || !Array.isArray(action.targets) || action.targets.length === 0) {
       errors.push('Targets array is required for forward action');
@@ -836,6 +985,10 @@ export function validateRouteConfig(route: IRouteConfig): { valid: boolean; erro
     }
   }
 
+  if (route.match && route.action?.type === 'respond') {
+    errors.push(...getRespondMatchErrors(route.match).map(err => `Match: ${err}`));
+  }
+
   return {
     valid: errors.length === 0,
     errors
@@ -889,6 +1042,8 @@ export function hasRequiredPropertiesForAction(route: IRouteConfig, actionType:
     case 'socket-handler':
       return (!!route.action.socketHandler && typeof route.action.socketHandler === 'function') ||
              (!!route.action.datagramHandler && typeof route.action.datagramHandler === 'function');
+    case 'respond':
+      return !!route.action.response && typeof route.action.response.status === 'number';
     default:
       return false;
   }
@@ -899,12 +1054,14 @@ export function hasRequiredPropertiesForAction(route: IRouteConfig, actionType:
  * Useful for immediate validation when creating routes
  * @param route Route configuration to validate
  * @returns The validated route configuration
- * @throws Error if the route configuration is invalid
+ * @throws RouteValidationError if the route configuration is invalid
  */
 export function assertValidRoute(route: IRouteConfig): IRouteConfig {
   const validation = validateRouteConfig(route);
   if (!validation.valid) {
-    throw new Error(`Invalid route configuration: ${validation.errors.join(', ')}`);
+    throw new RouteValidationError('Invalid route configuration', [
+      { index: 0, route: RouteValidator.getRouteLabels([route])[0], messages: validation.errors },
+    ]);
   }
   return route;
 }