@push.rocks/smartproxy 28.0.0 → 28.1.0

package/ts/proxies/smart-proxy/rust-proxy-bridge.ts

@@ -1,14 +1,17 @@
 import * as plugins from '../../plugins.js';
 import { logger } from '../../core/utils/logger.js';
-import type {
-  IRustCertificateStatus,
-  IRustChallengeOptions,
-  IRustMetricsSnapshot,
-  IRustProxyOptions,
-  IRustMetricsHistory,
-  IRustRouteConfig,
-  IRustStatistics,
+import {
+  RUST_ROUTE_VALIDATION_ERROR_CODE,
+  type IRustCertificateStatus,
+  type IRustChallengeOptions,
+  type IRustMetricsSnapshot,
+  type IRustProxyOptions,
+  type IRustMetricsHistory,
+  type IRustRouteConfig,
+  type IRustRouteValidationErrorData,
+  type IRustStatistics,
 } from './models/rust-types.js';
+import { RouteValidationError } from './utils/route-validation-error.js';
 import type { IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage, ISmartProxySecurityPolicy } from './models/interfaces.js';
 
 const MAXIMUM_RUST_CONNECTION_ID = 18_446_744_073_709_551_615n;
@@ -26,6 +29,69 @@ function validateActiveConnectionSnapshotOptions(options: IActiveConnectionSnaps
   }
 }
 
+function isRustRouteValidationErrorData(
+  data: unknown,
+  sentRouteCount: number,
+): data is IRustRouteValidationErrorData {
+  if (
+    typeof data !== 'object'
+    || data === null
+    || !('routes' in data)
+    || !Array.isArray(data.routes)
+    || data.routes.length === 0
+  ) {
+    return false;
+  }
+  return data.routes.every((issue: unknown) =>
+    typeof issue === 'object'
+    && issue !== null
+    && 'index' in issue
+    && typeof issue.index === 'number'
+    && Number.isSafeInteger(issue.index)
+    && issue.index >= 0
+    && issue.index < sentRouteCount
+    && 'route' in issue
+    && typeof issue.route === 'string'
+    && 'messages' in issue
+    && Array.isArray(issue.messages)
+    && issue.messages.every((message: unknown) => typeof message === 'string'),
+  );
+}
+
+/**
+ * Turn a Rust `ROUTE_VALIDATION` refusal into a `RouteValidationError` carrying the
+ * per-route reasons from its `errorData`. Any other error is returned unchanged.
+ *
+ * `routeLabels` holds `RouteValidator.getRouteLabels()` of the caller's routes, one per sent
+ * route. Entries are relabelled by index: the preprocessor names unnamed routes for Rust, so
+ * the engine's own labels can differ from the ones the caller sees.
+ */
+export function toRouteValidationError(error: unknown, routeLabels: string[]): unknown {
+  if (
+    !(error instanceof plugins.smartrust.RustBridgeRequestError)
+    || error.responseErrorCode !== RUST_ROUTE_VALIDATION_ERROR_CODE
+  ) {
+    return error;
+  }
+  if (!isRustRouteValidationErrorData(error.responseErrorData, routeLabels.length)) {
+    return new Error(`RustProxy sent a route validation refusal with malformed errorData: ${error.message}`, {
+      cause: error,
+    });
+  }
+  return new RouteValidationError(
+    'Route validation failed',
+    error.responseErrorData.routes.map(({ index, messages }) => ({ index, route: routeLabels[index], messages })),
+  );
+}
+
+function assertOneLabelPerRoute(routes: IRustRouteConfig[], routeLabels: string[]): void {
+  if (routes.length !== routeLabels.length) {
+    throw new Error(
+      `RustProxyBridge got ${routeLabels.length} route label(s) for ${routes.length} route(s); they must match one to one`,
+    );
+  }
+}
+
 /**
  * Type-safe command definitions for the Rust proxy IPC protocol.
  */
@@ -97,6 +163,14 @@ function buildLocalPaths(): string[] {
   return paths;
 }
 
+export interface IRustProxyBridgeOptions {
+  /**
+   * Explicit path to the RustProxy binary. When set, it is the only candidate:
+   * `spawn()` rejects with a `RustBinaryLocatorError` if it is missing or not executable.
+   */
+  binaryPath?: string;
+}
+
 /**
  * Bridge between TypeScript SmartProxy and the Rust binary.
  * Wraps @push.rocks/smartrust's RustBridge with type-safe command definitions.
@@ -104,11 +178,12 @@ function buildLocalPaths(): string[] {
 export class RustProxyBridge extends plugins.EventEmitter {
   private bridge: plugins.smartrust.RustBridge<TSmartProxyCommands>;
 
-  constructor() {
+  constructor(options: IRustProxyBridgeOptions = {}) {
     super();
 
     this.bridge = new plugins.smartrust.RustBridge<TSmartProxyCommands>({
       binaryName: 'rustproxy',
+      binaryPath: options.binaryPath,
       envVarName: 'SMARTPROXY_RUST_BINARY',
       platformPackagePrefix: '@push.rocks/smartproxy',
       localPaths: buildLocalPaths(),
@@ -155,16 +230,34 @@ export class RustProxyBridge extends plugins.EventEmitter {
 
   // --- Convenience methods for each management command ---
 
-  public async startProxy(config: IRustProxyOptions): Promise<void> {
-    await this.bridge.sendCommand('start', { config });
+  /**
+   * @param routeLabels `RouteValidator.getRouteLabels()` of the routes before preprocessing,
+   *   used to label a route validation refusal.
+   */
+  public async startProxy(config: IRustProxyOptions, routeLabels: string[]): Promise<void> {
+    assertOneLabelPerRoute(config.routes, routeLabels);
+    try {
+      await this.bridge.sendCommand('start', { config });
+    } catch (error) {
+      throw toRouteValidationError(error, routeLabels);
+    }
   }
 
   public async stopProxy(): Promise<void> {
     await this.bridge.sendCommand('stop', {} as Record<string, never>);
   }
 
-  public async updateRoutes(routes: IRustRouteConfig[]): Promise<void> {
-    await this.bridge.sendCommand('updateRoutes', { routes });
+  /**
+   * @param routeLabels `RouteValidator.getRouteLabels()` of the routes before preprocessing,
+   *   used to label a route validation refusal.
+   */
+  public async updateRoutes(routes: IRustRouteConfig[], routeLabels: string[]): Promise<void> {
+    assertOneLabelPerRoute(routes, routeLabels);
+    try {
+      await this.bridge.sendCommand('updateRoutes', { routes });
+    } catch (error) {
+      throw toRouteValidationError(error, routeLabels);
+    }
   }
 
   public async setSecurityPolicy(policy: ISmartProxySecurityPolicy): Promise<void> {

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

@@ -12,6 +12,7 @@ import { RustMetricsAdapter } from './rust-metrics-adapter.js';
 // Route management
 import { SharedRouteManager as RouteManager } from '../../core/routing/route-manager.js';
 import { RouteValidator } from './utils/route-validator.js';
+import { RouteValidationError, type IRouteValidationErrorEntry } from './utils/route-validation-error.js';
 import { buildRustProxyOptions } from './utils/rust-config.js';
 import { generateDefaultCertificate } from './utils/default-cert-generator.js';
 import { Mutex } from './utils/mutex.js';
@@ -107,7 +108,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const validation = RouteValidator.validateRoutes(this.settings.routes);
       if (!validation.valid) {
         RouteValidator.logValidationErrors(validation.errors);
-        throw new Error(`Initial route validation failed: ${validation.errors.size} route(s) have errors`);
+        throw new RouteValidationError('Initial route validation failed', validation.entries);
       }
     }
 
@@ -126,7 +127,7 @@ export class SmartProxy extends plugins.EventEmitter {
       routes: this.settings.routes,
     });
 
-    this.bridge = new RustProxyBridge();
+    this.bridge = new RustProxyBridge({ binaryPath: this.settings.rustBinaryPath });
     this.preprocessor = new RoutePreprocessor();
     this.metricsAdapter = new RustMetricsAdapter(
       this.bridge,
@@ -216,7 +217,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const config = this.buildRustConfig(rustRoutes, acmeForRust);
 
       // Start the Rust proxy
-      await this.bridge.startProxy(config);
+      await this.bridge.startProxy(config, RouteValidator.getRouteLabels(this.settings.routes));
 
       // Now that Rust proxy is running, configure socket handler relay
       if (this.socketHandlerServer) {
@@ -370,7 +371,7 @@ export class SmartProxy extends plugins.EventEmitter {
       const validation = RouteValidator.validateRoutes(newRoutes);
       if (!validation.valid) {
         RouteValidator.logValidationErrors(validation.errors);
-        throw new Error(`Route validation failed: ${validation.errors.size} route(s) have errors`);
+        throw new RouteValidationError('Route validation failed', validation.entries);
       }
 
       const hasChallengeRoutes = this.hasChallengeRoutes(newRoutes);
@@ -389,7 +390,7 @@ export class SmartProxy extends plugins.EventEmitter {
         }
 
         // Send to Rust
-        await this.bridge.updateRoutes(rustRoutes);
+        await this.bridge.updateRoutes(rustRoutes, RouteValidator.getRouteLabels(newRoutes));
       } catch (err) {
         if (hasChallengeRoutes && !challengeRelayWasStarted && this.challengeProviderRelayServer) {
           await this.bridge.setChallengeProviderRelay('').catch(() => undefined);
@@ -729,10 +730,11 @@ export class SmartProxy extends plugins.EventEmitter {
 
   private async validateChallengeRoutes(routes: IRouteConfig[]): Promise<void> {
     const manifestCache = new Map<string, plugins.smartchallenge.IChallengeProviderManifest>();
-    const errors: string[] = [];
+    const labels = RouteValidator.getRouteLabels(routes);
+    const entries: IRouteValidationErrorEntry[] = [];
 
-    for (const route of routes) {
-      const routeName = route.name || route.id || 'unnamed route';
+    for (const [index, route] of routes.entries()) {
+      const errors: string[] = [];
       const challengeEntries: Array<{
         path: string;
         challenge: plugins.smartchallenge.IRouteChallengeConfig;
@@ -758,50 +760,50 @@ export class SmartProxy extends plugins.EventEmitter {
       if (challengeEntries.length === 0) continue;
 
       if (!route.name && !route.id) {
-        errors.push(`${routeName}: challenge routes must set a stable route name or id`);
+        errors.push('challenge routes must set a stable route name or id');
       }
       if (route.action.type !== 'forward') {
-        errors.push(`${routeName}: challenge routes must use forward actions`);
+        errors.push('challenge routes must use forward actions');
       }
       if (route.action.forwardingEngine === 'nftables') {
-        errors.push(`${routeName}: challenge routes cannot use nftables forwarding`);
+        errors.push('challenge routes cannot use nftables forwarding');
       }
       if (route.action.tls?.mode === 'passthrough') {
-        errors.push(`${routeName}: challenge routes cannot use TLS passthrough`);
+        errors.push('challenge routes cannot use TLS passthrough');
       }
       for (const target of route.action.targets || []) {
         if (typeof target.host === 'function' || typeof target.port === 'function') {
-          errors.push(`${routeName}: challenge routes cannot use dynamic target host or port functions`);
+          errors.push('challenge routes cannot use dynamic target host or port functions');
         }
         if (target.tls?.mode === 'passthrough') {
-          errors.push(`${routeName}: challenge routes cannot use target TLS passthrough`);
+          errors.push('challenge routes cannot use target TLS passthrough');
         }
       }
       const hasHttp3Transport = route.match.transport === 'all'
         && route.action.udp?.quic?.enableHttp3 === true;
       if (route.match.transport === 'udp') {
-        errors.push(`${routeName}: challenge routes cannot use pure UDP transport`);
+        errors.push('challenge routes cannot use pure UDP transport');
       }
       if (route.match.transport === 'all' && !hasHttp3Transport) {
-        errors.push(`${routeName}: challenge routes using transport 'all' must enable HTTP/3 with action.udp.quic.enableHttp3`);
+        errors.push(`challenge routes using transport 'all' must enable HTTP/3 with action.udp.quic.enableHttp3`);
       }
       if (route.match.protocol !== 'http') {
-        errors.push(`${routeName}: challenge routes must set match.protocol to 'http'`);
+        errors.push(`challenge routes must set match.protocol to 'http'`);
       }
 
       for (const { path, challenge } of challengeEntries) {
         if (!challenge.providerId || typeof challenge.providerId !== 'string') {
-          errors.push(`${routeName}: ${path}.providerId must be a non-empty string`);
+          errors.push(`${path}.providerId must be a non-empty string`);
         }
         if (!challenge.challengeType || typeof challenge.challengeType !== 'string') {
-          errors.push(`${routeName}: ${path}.challengeType must be a non-empty string`);
+          errors.push(`${path}.challengeType must be a non-empty string`);
         }
-        this.validateChallengeIntentShape(challenge, errors, routeName, path);
-        this.collectForbiddenChallengeKeys(challenge, path, errors, routeName);
+        this.validateChallengeIntentShape(challenge, errors, path);
+        this.collectForbiddenChallengeKeys(challenge, path, errors);
 
         const provider = this.challengeProviders.get(challenge.providerId);
         if (!provider) {
-          errors.push(`${routeName}: challenge provider '${challenge.providerId}' is not registered`);
+          errors.push(`challenge provider '${challenge.providerId}' is not registered`);
           continue;
         }
         let manifest = manifestCache.get(challenge.providerId);
@@ -810,24 +812,27 @@ export class SmartProxy extends plugins.EventEmitter {
           manifestCache.set(challenge.providerId, manifest);
         }
         if (!manifest.challengeTypes.some((type) => type.challengeType === challenge.challengeType)) {
-          errors.push(`${routeName}: challenge provider '${challenge.providerId}' does not support type '${challenge.challengeType}'`);
+          errors.push(`challenge provider '${challenge.providerId}' does not support type '${challenge.challengeType}'`);
         }
       }
+
+      if (errors.length > 0) {
+        entries.push({ index, route: labels[index], messages: errors });
+      }
     }
 
-    if (errors.length > 0) {
-      throw new Error(`Challenge route validation failed:\n${errors.map((error) => `- ${error}`).join('\n')}`);
+    if (entries.length > 0) {
+      throw new RouteValidationError('Challenge route validation failed', entries);
     }
   }
 
   private validateChallengeIntentShape(
     challengeArg: unknown,
     errors: string[],
-    routeName: string,
     challengePath = 'security.challenge',
   ): void {
     if (!this.isPlainRecord(challengeArg)) {
-      errors.push(`${routeName}: ${challengePath} must be an object`);
+      errors.push(`${challengePath} must be an object`);
       return;
     }
 
@@ -836,25 +841,23 @@ export class SmartProxy extends plugins.EventEmitter {
       challengePath,
       new Set(['providerId', 'challengeType', 'policyRef', 'settings', 'applyTo', 'clearance']),
       errors,
-      routeName,
     );
 
     const settings = challengeArg.settings;
     if (settings !== undefined && !this.isPlainRecord(settings)) {
-      errors.push(`${routeName}: ${challengePath}.settings must be an object when set`);
+      errors.push(`${challengePath}.settings must be an object when set`);
     }
 
     const applyTo = challengeArg.applyTo;
     if (applyTo !== undefined) {
       if (!this.isPlainRecord(applyTo)) {
-        errors.push(`${routeName}: ${challengePath}.applyTo must be an object when set`);
+        errors.push(`${challengePath}.applyTo must be an object when set`);
       } else {
         this.validateAllowedChallengeKeys(
           applyTo,
           `${challengePath}.applyTo`,
           new Set(['methods', 'browserNavigationsOnly', 'includePaths', 'excludePaths']),
           errors,
-          routeName,
         );
       }
     }
@@ -862,14 +865,13 @@ export class SmartProxy extends plugins.EventEmitter {
     const clearance = challengeArg.clearance;
     if (clearance !== undefined) {
       if (!this.isPlainRecord(clearance)) {
-        errors.push(`${routeName}: ${challengePath}.clearance must be an object when set`);
+        errors.push(`${challengePath}.clearance must be an object when set`);
       } else {
         this.validateAllowedChallengeKeys(
           clearance,
           `${challengePath}.clearance`,
           new Set(['ttlSeconds', 'bindToHost', 'bindToRoute', 'bindToIp']),
           errors,
-          routeName,
         );
       }
     }
@@ -880,11 +882,10 @@ export class SmartProxy extends plugins.EventEmitter {
     pathArg: string,
     allowedKeysArg: Set<string>,
     errors: string[],
-    routeName: string,
   ): void {
     for (const key of Object.keys(valueArg)) {
       if (!allowedKeysArg.has(key)) {
-        errors.push(`${routeName}: ${pathArg}.${key} is not part of the persisted challenge intent shape`);
+        errors.push(`${pathArg}.${key} is not part of the persisted challenge intent shape`);
       }
     }
   }
@@ -895,19 +896,19 @@ export class SmartProxy extends plugins.EventEmitter {
       && !Array.isArray(valueArg);
   }
 
-  private collectForbiddenChallengeKeys(value: unknown, path: string, errors: string[], routeName: string): void {
+  private collectForbiddenChallengeKeys(value: unknown, path: string, errors: string[]): void {
     if (!value || typeof value !== 'object') return;
     const forbiddenKeyPattern = /(endpoint|url|uri|host|hostname|address|ipAddress|port|secret|token|password|credential|apiKey|apikey|accessKey|privateKey|keyfile|certfile|deployment|container|socketPath)/i;
     for (const [key, nestedValue] of Object.entries(value as Record<string, unknown>)) {
       const childPath = `${path}.${key}`;
       if (forbiddenKeyPattern.test(key) && !['providerId', 'challengeType', 'policyRef', 'bindToHost', 'bindToIp', 'includePaths', 'excludePaths'].includes(key)) {
-        errors.push(`${routeName}: ${childPath} looks like runtime wiring or secret material and must not be stored in route config`);
+        errors.push(`${childPath} looks like runtime wiring or secret material and must not be stored in route config`);
       }
       if (typeof nestedValue === 'string' && this.looksLikeRuntimeChallengeValue(nestedValue) && !['includePaths', 'excludePaths'].includes(key)) {
-        errors.push(`${routeName}: ${childPath} contains endpoint/IP-style runtime wiring and must not be stored in route config`);
+        errors.push(`${childPath} contains endpoint/IP-style runtime wiring and must not be stored in route config`);
       }
       if (nestedValue && typeof nestedValue === 'object') {
-        this.collectForbiddenChallengeKeys(nestedValue, childPath, errors, routeName);
+        this.collectForbiddenChallengeKeys(nestedValue, childPath, errors);
       }
     }
   }

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;
+  }
+}