@push.rocks/smartproxy 27.21.0 → 28.0.0

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

@@ -25,6 +25,10 @@ import type { IRustCertificateStatus, IRustChallengeOptions, IRustProxyOptions,
 
 type TChallengeProvider = plugins.smartchallenge.IChallengeProvider;
 
+/** What one certProvisionFunction call amounted to, in the order each sweep logs the tally. */
+const certProvisionOutcomes = ['loaded', 'http01', 'deferred', 'failed', 'stopped', 'unrecognized'] as const;
+type TCertProvisionOutcome = (typeof certProvisionOutcomes)[number];
+
 /**
  * SmartProxy - Rust-backed proxy engine with TypeScript configuration API.
  *
@@ -489,6 +493,24 @@ export class SmartProxy extends plugins.EventEmitter {
     return this.bridge.getCertificateStatus(routeName);
   }
 
+  /**
+   * Lift the provisioning failure cooldown of one domain, so the next sweep
+   * (`updateRoutes()` or the renewal check) calls `certProvisionFunction` for it
+   * again instead of waiting out `certProvisionFailureCooldownMs`. Use it when the
+   * cause of a failure was resolved outside SmartProxy, for example after a
+   * certificate for the domain was issued out of band.
+   *
+   * @param domain The provisioning domain exactly as `certProvisionFunction`
+   *   receives it and `certificate-failed` reports it.
+   * @returns true if the domain was cooling down, false if it was not (never
+   *   failed, or its cooldown had already elapsed).
+   */
+  public invalidateCertProvisionCooldown(domain: string): boolean {
+    const wasCoolingDown = this.isInFailureCooldown(domain, Date.now());
+    this.certFailureAt.delete(domain);
+    return wasCoolingDown;
+  }
+
   /**
    * Get the metrics interface.
    */
@@ -558,7 +580,7 @@ export class SmartProxy extends plugins.EventEmitter {
     for (const route of this.settings.routes || []) {
       if (!route.match.domains) continue;
       if (
-        route.action.type !== 'forward' ||
+        (route.action.type !== 'forward' && route.action.type !== 'respond') ||
         !route.action.tls ||
         route.action.tls.mode === 'passthrough' ||
         route.action.tls.certificate !== 'auto'
@@ -985,6 +1007,7 @@ export class SmartProxy extends plugins.EventEmitter {
    * For routes with certificate: 'auto', call certProvisionFunction if set.
    * If the callback returns a cert object, load it into Rust.
    * If it returns 'http01', let Rust handle ACME.
+   * If it returns 'defer', leave the domain for the next sweep.
    */
   private async provisionCertificatesViaCallback(skipDomains: Set<string> = new Set()): Promise<void> {
     const provisionFn = this.settings.certProvisionFunction;
@@ -1045,16 +1068,28 @@ export class SmartProxy extends plugins.EventEmitter {
     const concurrency = this.settings.certProvisionConcurrency ?? 4;
     const semaphore = new ConcurrencySemaphore(concurrency);
 
-    const promises = tasks.map(async ({ domain, route }) => {
+    const promises = tasks.map(async ({ domain, route }): Promise<TCertProvisionOutcome> => {
       await semaphore.acquire();
       try {
-        await this.provisionSingleDomain(domain, route, provisionFn);
+        return await this.provisionSingleDomain(domain, route, provisionFn);
       } finally {
         semaphore.release();
       }
     });
 
-    await Promise.allSettled(promises);
+    // provisionSingleDomain settles provisioning errors itself; it rejects only
+    // when a certificate-failed listener throws, after the failure was recorded.
+    const settled = await Promise.allSettled(promises);
+    const tally = new Map<TCertProvisionOutcome, number>();
+    for (const result of settled) {
+      const outcome = result.status === 'fulfilled' ? result.value : 'failed';
+      tally.set(outcome, (tally.get(outcome) ?? 0) + 1);
+    }
+    const summary = certProvisionOutcomes
+      .filter((outcome) => tally.has(outcome))
+      .map((outcome) => `${tally.get(outcome)} ${outcome}`)
+      .join(', ');
+    logger.log('info', `Cert provisioning sweep finished: ${summary}`, { component: 'smart-proxy' });
   }
 
   /**
@@ -1065,8 +1100,8 @@ export class SmartProxy extends plugins.EventEmitter {
     domain: string,
     route: IRouteConfig,
     provisionFn: (domain: string, eventComms: ICertProvisionEventComms) => Promise<TSmartProxyCertProvisionObject>,
-  ): Promise<void> {
-    if (this.stopping) return;
+  ): Promise<TCertProvisionOutcome> {
+    if (this.stopping) return 'stopped';
 
     let expiryDate: string | undefined;
     let source = 'certProvisionFunction';
@@ -1088,7 +1123,13 @@ export class SmartProxy extends plugins.EventEmitter {
         `Certificate provisioning timed out for ${domain} after ${timeoutMs}ms`,
       );
 
-      if (this.stopping) return;
+      if (this.stopping) return 'stopped';
+
+      // A deferral is not a failure: no cooldown, no event, no ACME fallback.
+      if (result === 'defer') {
+        logger.log('info', `Certificate provisioning deferred for ${domain}; the next sweep retries it`, { component: 'smart-proxy' });
+        return 'deferred';
+      }
 
       if (result === 'http01') {
         if (route.name) {
@@ -1100,11 +1141,11 @@ export class SmartProxy extends plugins.EventEmitter {
               'Note: Rust ACME is disabled when certProvisionFunction is set.', { component: 'smart-proxy' });
           }
         }
-        return;
+        return 'http01';
       }
 
       if (result && typeof result === 'object') {
-        if (this.stopping) return;
+        if (this.stopping) return 'stopped';
 
         const certObj = result as ISmartProxyCertProvisionCertificate;
         await this.bridge.loadCertificate(
@@ -1135,7 +1176,9 @@ export class SmartProxy extends plugins.EventEmitter {
           expiryDate: expiryDate || (certObj.validUntil ? new Date(certObj.validUntil).toISOString() : undefined),
           source,
         } satisfies ICertificateIssuedEvent);
+        return 'loaded';
       }
+      return 'unrecognized';
     } catch (err: any) {
       logger.log('warn', `certProvisionFunction failed for ${domain}: ${err.message}`, { component: 'smart-proxy' });
 
@@ -1161,6 +1204,7 @@ export class SmartProxy extends plugins.EventEmitter {
               : ' — default self-signed fallback cert will be used'), { component: 'smart-proxy' });
         }
       }
+      return 'failed';
     }
   }
 

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

@@ -6,7 +6,7 @@ import type { IInboundProxyProtocolPolicy, IRouteConfig, IRouteMatch, IRouteActi
  */
 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 +149,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) {
@@ -719,6 +727,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 +851,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 +962,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 +1019,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;
   }