Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

3.2 KB
Raw Blame
import { EngineStatus } from '../../engine/interfaces/whatsapp-engine.interface';
import type { IngressRouteDescriptor } from './ingress.service';

export type PreflightRejection = { status: number; body: string; headers?: Record<string, string> };

/**
 * Retry-After on the session-alive 503. Presence is what buys the retry: the provider dispatchers that
 * matter re-attempt a 503 only when the header is set and do not parse its value (supabase/auth checks
 * `Get("retry-after") != ""`). A session that is merely still coming up already passes through to the
 * normal ack + enqueue path, so a rejection means no live engine or FAILED, and what bounds a provider
 * hammering a dead session is the per-instance bucket IngressService charges after verification, not
 * this number.
 */
const PREFLIGHT_RETRY_AFTER_SECONDS = 5;

/**
 * A refusal the provider is told to retry. Attached per rejection, not to every one: a future
 * non-retryable check must not inherit a header that tells the provider to come back.
 */
const retryable503 = (body: string): PreflightRejection => ({
  status: 503,
  body,
  headers: { 'Retry-After': String(PREFLIGHT_RETRY_AFTER_SECONDS) },
});

/**
 * The refusal for a delivery on a route that declares a response contract, to a plugin the boot restore has
 * not finished with. The provider wants to know now (an OTP delivered a minute late is useless), and no
 * worker can take the delivery yet, so it is told to retry. A route without a response contract is not
 * refused: its delivery is accepted and held until the plugin is up. IngressService answers this in the
 * same stage as the preflight, so it leaves no dedup row either.
 */
export const pluginRestoringRejection = (): PreflightRejection => retryable503('plugin restoring');

/**
 * Evaluates a route's host-side preflight checks. Returns null to PASS (proceed to dedup + ack + enqueue),
 * or a `{status, body}` to REJECT synchronously. Runs AFTER signature verify and BEFORE the dedup persist
 * (see IngressService.handle) — a rejection therefore writes no dedup row, so a provider retry on the 5xx
 * is treated as new (this is what avoids the dedup trap).
 *
 * `session-alive`: skipped for wildcard (null/'*') scopes and when sessionStatus is unwired; rejects 503
 * only when the concrete session has no live engine or is EngineStatus.FAILED. Recoverable statuses and
 * READY pass through to the normal ack + enqueue path so the worker can fail fast and the delivery stays durable.
 */
export function evaluatePreflight(
  route: IngressRouteDescriptor,
  sessionScope: string | null,
  sessionStatus: ((scope: string) => EngineStatus | undefined) | undefined,
): PreflightRejection | null {
  const checks = route.response?.preflight;
  if (!checks?.length) return null;
  for (const check of checks) {
    if (check.type === 'session-alive') {
      if (!sessionScope || sessionScope === '*') continue; // wildcard: no single session to probe
      if (!sessionStatus) continue; // unwired (pure unit mode): skip rather than false-reject
      const status = sessionStatus(sessionScope);
      if (status === undefined || status === EngineStatus.FAILED) return retryable503('session not ready');
    }
  }
  return null;
}