@vivero/stoma 0.1.0-rc.10

package/dist/policies/resilience/circuit-breaker.js

@@ -0,0 +1,280 @@
+import { GatewayError } from "../../core/errors";
+import {
+  Priority,
+  policyDebug,
+  resolveConfig,
+  safeCall,
+  setDebugHeader,
+  withSkip
+} from "../sdk";
+function defaultSnapshot() {
+  return {
+    state: "closed",
+    failureCount: 0,
+    successCount: 0,
+    lastFailureTime: 0,
+    lastStateChange: Date.now()
+  };
+}
+class InMemoryCircuitBreakerStore {
+  circuits = /* @__PURE__ */ new Map();
+  getOrCreate(key) {
+    let snap = this.circuits.get(key);
+    if (!snap) {
+      snap = defaultSnapshot();
+      this.circuits.set(key, snap);
+    }
+    return snap;
+  }
+  async getState(key) {
+    return { ...this.getOrCreate(key) };
+  }
+  async recordSuccess(key) {
+    const snap = this.getOrCreate(key);
+    snap.successCount++;
+    return { ...snap };
+  }
+  async recordFailure(key) {
+    const snap = this.getOrCreate(key);
+    snap.failureCount++;
+    snap.lastFailureTime = Date.now();
+    return { ...snap };
+  }
+  async transition(key, to) {
+    const snap = this.getOrCreate(key);
+    snap.state = to;
+    snap.lastStateChange = Date.now();
+    if (to === "closed") {
+      snap.failureCount = 0;
+      snap.successCount = 0;
+    }
+    if (to === "half-open") {
+      snap.successCount = 0;
+    }
+    return { ...snap };
+  }
+  async reset(key) {
+    this.circuits.delete(key);
+  }
+  /** Remove all circuits (for testing) */
+  clear() {
+    this.circuits.clear();
+  }
+  /** Release all state. */
+  destroy() {
+    this.circuits.clear();
+  }
+}
+async function transitionAndNotify(resolvedStore, key, from, to, onStateChange, debug) {
+  await safeCall(
+    () => resolvedStore.transition(key, to),
+    void 0,
+    debug,
+    "store.transition()"
+  );
+  if (onStateChange) {
+    await safeCall(
+      () => Promise.resolve(onStateChange(key, from, to)),
+      void 0,
+      debug,
+      "onStateChange()"
+    );
+  }
+}
+function circuitBreaker(config) {
+  const resolved = resolveConfig(
+    {
+      failureThreshold: 5,
+      resetTimeoutMs: 3e4,
+      halfOpenMax: 1,
+      failureOn: [500, 502, 503, 504],
+      openStatusCode: 503
+    },
+    config
+  );
+  let store = config?.store;
+  if (!store) {
+    store = new InMemoryCircuitBreakerStore();
+  }
+  const resolvedStore = store;
+  const onStateChange = config?.onStateChange;
+  const halfOpenProbes = /* @__PURE__ */ new Map();
+  const handler = async (c, next) => {
+    const debug = policyDebug(c, "circuit-breaker");
+    const key = config?.key ? config.key(c) : new URL(c.req.url).pathname;
+    const snap = await safeCall(
+      () => resolvedStore.getState(key),
+      defaultSnapshot(),
+      debug,
+      "store.getState()"
+    );
+    const now = Date.now();
+    setDebugHeader(c, "x-stoma-circuit-key", key);
+    setDebugHeader(c, "x-stoma-circuit-state", snap.state);
+    setDebugHeader(c, "x-stoma-circuit-failures", snap.failureCount);
+    if (snap.state === "open") {
+      if (now - snap.lastStateChange >= resolved.resetTimeoutMs) {
+        debug(`open -> half-open (key=${key})`);
+        await transitionAndNotify(
+          resolvedStore,
+          key,
+          "open",
+          "half-open",
+          onStateChange,
+          debug
+        );
+        halfOpenProbes.set(key, 0);
+      } else {
+        const retryAfter = Math.ceil(
+          (resolved.resetTimeoutMs - (now - snap.lastStateChange)) / 1e3
+        );
+        throw new GatewayError(
+          resolved.openStatusCode,
+          "circuit_open",
+          "Service temporarily unavailable",
+          { "retry-after": String(retryAfter) }
+        );
+      }
+    }
+    if (snap.state === "half-open" || snap.state === "open" && now - snap.lastStateChange >= resolved.resetTimeoutMs) {
+      const inFlight = halfOpenProbes.get(key) ?? 0;
+      if (inFlight >= resolved.halfOpenMax) {
+        throw new GatewayError(
+          resolved.openStatusCode,
+          "circuit_open",
+          "Service temporarily unavailable",
+          { "retry-after": String(Math.ceil(resolved.resetTimeoutMs / 1e3)) }
+        );
+      }
+      halfOpenProbes.set(key, inFlight + 1);
+      try {
+        await next();
+        const isFailure = resolved.failureOn.includes(c.res.status);
+        if (isFailure) {
+          debug(
+            `half-open probe failed (key=${key}, status=${c.res.status}) -> open`
+          );
+          await safeCall(
+            () => resolvedStore.recordFailure(key),
+            void 0,
+            debug,
+            "store.recordFailure()"
+          );
+          await transitionAndNotify(
+            resolvedStore,
+            key,
+            "half-open",
+            "open",
+            onStateChange,
+            debug
+          );
+        } else {
+          debug(`half-open probe succeeded (key=${key}) -> closed`);
+          await safeCall(
+            () => resolvedStore.recordSuccess(key),
+            void 0,
+            debug,
+            "store.recordSuccess()"
+          );
+          await transitionAndNotify(
+            resolvedStore,
+            key,
+            "half-open",
+            "closed",
+            onStateChange,
+            debug
+          );
+          halfOpenProbes.delete(key);
+        }
+      } catch (err) {
+        debug(`half-open probe threw (key=${key}) -> open`);
+        await safeCall(
+          () => resolvedStore.recordFailure(key),
+          void 0,
+          debug,
+          "store.recordFailure()"
+        );
+        await transitionAndNotify(
+          resolvedStore,
+          key,
+          "half-open",
+          "open",
+          onStateChange,
+          debug
+        );
+        throw err;
+      } finally {
+        const current = halfOpenProbes.get(key) ?? 1;
+        if (current <= 1) {
+          halfOpenProbes.delete(key);
+        } else {
+          halfOpenProbes.set(key, current - 1);
+        }
+      }
+      return;
+    }
+    try {
+      await next();
+    } catch (err) {
+      const updated = await safeCall(
+        () => resolvedStore.recordFailure(key),
+        null,
+        debug,
+        "store.recordFailure()"
+      );
+      if (updated && updated.failureCount >= resolved.failureThreshold) {
+        debug(
+          `closed -> open (key=${key}, failures=${updated.failureCount}/${resolved.failureThreshold})`
+        );
+        await transitionAndNotify(
+          resolvedStore,
+          key,
+          "closed",
+          "open",
+          onStateChange,
+          debug
+        );
+      }
+      throw err;
+    }
+    if (resolved.failureOn.includes(c.res.status)) {
+      const updated = await safeCall(
+        () => resolvedStore.recordFailure(key),
+        null,
+        debug,
+        "store.recordFailure()"
+      );
+      if (updated && updated.failureCount >= resolved.failureThreshold) {
+        debug(
+          `closed -> open (key=${key}, failures=${updated.failureCount}/${resolved.failureThreshold})`
+        );
+        await transitionAndNotify(
+          resolvedStore,
+          key,
+          "closed",
+          "open",
+          onStateChange,
+          debug
+        );
+      }
+    } else {
+      await safeCall(
+        () => resolvedStore.recordSuccess(key),
+        void 0,
+        debug,
+        "store.recordSuccess()"
+      );
+    }
+  };
+  return {
+    name: "circuit-breaker",
+    priority: Priority.CIRCUIT_BREAKER,
+    handler: withSkip(config?.skip, handler),
+    httpOnly: true
+  };
+}
+export {
+  InMemoryCircuitBreakerStore,
+  circuitBreaker
+};
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/policies/resilience/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/resilience/circuit-breaker.ts"],"sourcesContent":["/**\n * Circuit breaker policy - protect upstream services from cascading failures.\n *\n * Implements the three-state circuit breaker pattern (closed / open / half-open)\n * with pluggable state storage via {@link CircuitBreakerStore}.\n *\n * @module circuit-breaker\n */\nimport type { Context } from \"hono\";\nimport { GatewayError } from \"../../core/errors\";\nimport type { DebugLogger } from \"../../utils/debug\";\nimport {\n  Priority,\n  policyDebug,\n  resolveConfig,\n  safeCall,\n  setDebugHeader,\n  withSkip,\n} from \"../sdk\";\nimport type { Policy, PolicyConfig } from \"../types\";\n\n// --- Store interface ---\n\n/** The three states of the circuit breaker state machine. */\nexport type CircuitState = \"closed\" | \"open\" | \"half-open\";\n\n/** Point-in-time snapshot of a circuit's state and counters. */\nexport interface CircuitBreakerSnapshot {\n  /** Current circuit state. */\n  state: CircuitState;\n  /** Number of consecutive failures since last reset. */\n  failureCount: number;\n  /** Number of successful probes in half-open state. */\n  successCount: number;\n  /** Epoch ms of the most recent failure. `0` if no failures recorded. */\n  lastFailureTime: number;\n  /** Epoch ms of the most recent state transition. */\n  lastStateChange: number;\n}\n\n/**\n * Pluggable storage backend for circuit breaker state.\n *\n * Implement this interface to store circuit state in Durable Objects,\n * KV, or any shared datastore for multi-instance deployments.\n */\nexport interface CircuitBreakerStore {\n  /** Read the current snapshot for a circuit key. */\n  getState(key: string): Promise<CircuitBreakerSnapshot>;\n  /** Record a successful request and return the updated snapshot. */\n  recordSuccess(key: string): Promise<CircuitBreakerSnapshot>;\n  /** Record a failed request and return the updated snapshot. */\n  recordFailure(key: string): Promise<CircuitBreakerSnapshot>;\n  /** Transition the circuit to a new state and return the updated snapshot. */\n  transition(key: string, to: CircuitState): Promise<CircuitBreakerSnapshot>;\n  /** Fully reset a circuit, removing all state. */\n  reset(key: string): Promise<void>;\n  /** Optional cleanup - release timers, close connections, etc. */\n  destroy?(): void;\n}\n\n// --- In-memory default ---\n\nfunction defaultSnapshot(): CircuitBreakerSnapshot {\n  return {\n    state: \"closed\",\n    failureCount: 0,\n    successCount: 0,\n    lastFailureTime: 0,\n    lastStateChange: Date.now(),\n  };\n}\n\nexport class InMemoryCircuitBreakerStore implements CircuitBreakerStore {\n  private circuits = new Map<string, CircuitBreakerSnapshot>();\n\n  private getOrCreate(key: string): CircuitBreakerSnapshot {\n    let snap = this.circuits.get(key);\n    if (!snap) {\n      snap = defaultSnapshot();\n      this.circuits.set(key, snap);\n    }\n    return snap;\n  }\n\n  async getState(key: string): Promise<CircuitBreakerSnapshot> {\n    return { ...this.getOrCreate(key) };\n  }\n\n  async recordSuccess(key: string): Promise<CircuitBreakerSnapshot> {\n    const snap = this.getOrCreate(key);\n    snap.successCount++;\n    return { ...snap };\n  }\n\n  async recordFailure(key: string): Promise<CircuitBreakerSnapshot> {\n    const snap = this.getOrCreate(key);\n    snap.failureCount++;\n    snap.lastFailureTime = Date.now();\n    return { ...snap };\n  }\n\n  async transition(\n    key: string,\n    to: CircuitState\n  ): Promise<CircuitBreakerSnapshot> {\n    const snap = this.getOrCreate(key);\n    snap.state = to;\n    snap.lastStateChange = Date.now();\n    if (to === \"closed\") {\n      snap.failureCount = 0;\n      snap.successCount = 0;\n    }\n    if (to === \"half-open\") {\n      snap.successCount = 0;\n    }\n    return { ...snap };\n  }\n\n  async reset(key: string): Promise<void> {\n    this.circuits.delete(key);\n  }\n\n  /** Remove all circuits (for testing) */\n  clear(): void {\n    this.circuits.clear();\n  }\n\n  /** Release all state. */\n  destroy(): void {\n    this.circuits.clear();\n  }\n}\n\n// --- Policy ---\n\nexport interface CircuitBreakerConfig extends PolicyConfig {\n  /** Number of failures before opening the circuit. Default: 5. */\n  failureThreshold?: number;\n  /** Time in ms before transitioning from open → half-open. Default: 30000. */\n  resetTimeoutMs?: number;\n  /** Max concurrent probes allowed in half-open state. Default: 1. */\n  halfOpenMax?: number;\n  /** Status codes considered failures. Default: [500, 502, 503, 504]. */\n  failureOn?: number[];\n  /** Storage backend. Default: InMemoryCircuitBreakerStore. */\n  store?: CircuitBreakerStore;\n  /** Key extractor. Default: request URL pathname. */\n  key?: (c: Context) => string;\n  /** HTTP status code when the circuit is open. Default: 503. */\n  openStatusCode?: number;\n  /**\n   * Callback invoked on every state transition.\n   *\n   * Called via `safeCall` so errors are swallowed - a failing callback\n   * never blocks traffic. Useful for metrics, logging, or alerting.\n   *\n   * @param key - The circuit key that transitioned.\n   * @param from - The previous circuit state.\n   * @param to - The new circuit state.\n   */\n  onStateChange?: (\n    key: string,\n    from: CircuitState,\n    to: CircuitState\n  ) => void | Promise<void>;\n}\n\n/**\n * Transition the circuit and invoke the onStateChange callback (if configured).\n *\n * Both the store transition and the callback are wrapped in safeCall so\n * failures are swallowed - a broken store or callback never blocks traffic.\n */\nasync function transitionAndNotify(\n  resolvedStore: CircuitBreakerStore,\n  key: string,\n  from: CircuitState,\n  to: CircuitState,\n  onStateChange: CircuitBreakerConfig[\"onStateChange\"],\n  debug: DebugLogger\n): Promise<void> {\n  await safeCall(\n    () => resolvedStore.transition(key, to),\n    undefined,\n    debug,\n    \"store.transition()\"\n  );\n  if (onStateChange) {\n    await safeCall(\n      () => Promise.resolve(onStateChange(key, from, to)),\n      undefined,\n      debug,\n      \"onStateChange()\"\n    );\n  }\n}\n\n/**\n * Protect upstream services by breaking the circuit on repeated failures.\n *\n * Implements the three-state circuit breaker pattern:\n * - **Closed** - requests flow normally; failures are counted.\n * - **Open** - requests are immediately rejected with 503; a `Retry-After` header is set.\n * - **Half-open** - a limited number of probe requests are allowed through to test recovery.\n *\n * State transitions: `closed → open` when failures reach the threshold,\n * `open → half-open` after the reset timeout, `half-open → closed` on\n * probe success or `half-open → open` on probe failure.\n *\n * @param config - Failure threshold, reset timeout, and storage backend.\n * @returns A {@link Policy} at priority 30.\n *\n * @example\n * ```ts\n * // Open after 5 failures, retry after 30s\n * circuitBreaker();\n *\n * // Tighter threshold with custom store\n * circuitBreaker({\n *   failureThreshold: 3,\n *   resetTimeoutMs: 10_000,\n *   failureOn: [500, 502, 503],\n *   store: new InMemoryCircuitBreakerStore(),\n * });\n *\n * // With state change notifications\n * circuitBreaker({\n *   failureThreshold: 5,\n *   onStateChange: (key, from, to) => {\n *     console.log(`Circuit ${key}: ${from} -> ${to}`);\n *   },\n * });\n * ```\n */\nexport function circuitBreaker(config?: CircuitBreakerConfig): Policy {\n  const resolved = resolveConfig<CircuitBreakerConfig>(\n    {\n      failureThreshold: 5,\n      resetTimeoutMs: 30_000,\n      halfOpenMax: 1,\n      failureOn: [500, 502, 503, 504],\n      openStatusCode: 503,\n    },\n    config\n  );\n\n  let store = config?.store;\n  if (!store) {\n    store = new InMemoryCircuitBreakerStore();\n  }\n  const resolvedStore = store;\n  const onStateChange = config?.onStateChange;\n\n  // Track half-open probes in flight (per key)\n  const halfOpenProbes = new Map<string, number>();\n\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    const debug = policyDebug(c, \"circuit-breaker\");\n    const key = config?.key ? config.key(c) : new URL(c.req.url).pathname;\n\n    // Resilient to store failures - fail-open (assume closed) if the\n    // store is unreachable, so a broken store never blocks traffic.\n    const snap = await safeCall(\n      () => resolvedStore.getState(key),\n      defaultSnapshot(),\n      debug,\n      \"store.getState()\"\n    );\n    const now = Date.now();\n    setDebugHeader(c, \"x-stoma-circuit-key\", key);\n    setDebugHeader(c, \"x-stoma-circuit-state\", snap.state);\n    setDebugHeader(c, \"x-stoma-circuit-failures\", snap.failureCount);\n\n    // --- OPEN ---\n    if (snap.state === \"open\") {\n      if (now - snap.lastStateChange >= resolved.resetTimeoutMs!) {\n        // Transition to half-open\n        debug(`open -> half-open (key=${key})`);\n        await transitionAndNotify(\n          resolvedStore,\n          key,\n          \"open\",\n          \"half-open\",\n          onStateChange,\n          debug\n        );\n        halfOpenProbes.set(key, 0);\n      } else {\n        const retryAfter = Math.ceil(\n          (resolved.resetTimeoutMs! - (now - snap.lastStateChange)) / 1000\n        );\n        throw new GatewayError(\n          resolved.openStatusCode!,\n          \"circuit_open\",\n          \"Service temporarily unavailable\",\n          { \"retry-after\": String(retryAfter) }\n        );\n      }\n    }\n\n    // --- HALF-OPEN: limit concurrent probes ---\n    if (\n      snap.state === \"half-open\" ||\n      (snap.state === \"open\" &&\n        now - snap.lastStateChange >= resolved.resetTimeoutMs!)\n    ) {\n      const inFlight = halfOpenProbes.get(key) ?? 0;\n      if (inFlight >= resolved.halfOpenMax!) {\n        throw new GatewayError(\n          resolved.openStatusCode!,\n          \"circuit_open\",\n          \"Service temporarily unavailable\",\n          { \"retry-after\": String(Math.ceil(resolved.resetTimeoutMs! / 1000)) }\n        );\n      }\n      halfOpenProbes.set(key, inFlight + 1);\n\n      try {\n        await next();\n\n        const isFailure = resolved.failureOn!.includes(c.res.status);\n        if (isFailure) {\n          debug(\n            `half-open probe failed (key=${key}, status=${c.res.status}) -> open`\n          );\n          await safeCall(\n            () => resolvedStore.recordFailure(key),\n            undefined,\n            debug,\n            \"store.recordFailure()\"\n          );\n          await transitionAndNotify(\n            resolvedStore,\n            key,\n            \"half-open\",\n            \"open\",\n            onStateChange,\n            debug\n          );\n        } else {\n          debug(`half-open probe succeeded (key=${key}) -> closed`);\n          await safeCall(\n            () => resolvedStore.recordSuccess(key),\n            undefined,\n            debug,\n            \"store.recordSuccess()\"\n          );\n          await transitionAndNotify(\n            resolvedStore,\n            key,\n            \"half-open\",\n            \"closed\",\n            onStateChange,\n            debug\n          );\n          halfOpenProbes.delete(key);\n        }\n      } catch (err) {\n        debug(`half-open probe threw (key=${key}) -> open`);\n        await safeCall(\n          () => resolvedStore.recordFailure(key),\n          undefined,\n          debug,\n          \"store.recordFailure()\"\n        );\n        await transitionAndNotify(\n          resolvedStore,\n          key,\n          \"half-open\",\n          \"open\",\n          onStateChange,\n          debug\n        );\n        throw err;\n      } finally {\n        const current = halfOpenProbes.get(key) ?? 1;\n        if (current <= 1) {\n          halfOpenProbes.delete(key);\n        } else {\n          halfOpenProbes.set(key, current - 1);\n        }\n      }\n      return;\n    }\n\n    // --- CLOSED ---\n    try {\n      await next();\n    } catch (err) {\n      // If recordFailure fails, skip the threshold check entirely -\n      // we have no snapshot to compare against.\n      const updated = await safeCall(\n        () => resolvedStore.recordFailure(key),\n        null,\n        debug,\n        \"store.recordFailure()\"\n      );\n      if (updated && updated.failureCount >= resolved.failureThreshold!) {\n        debug(\n          `closed -> open (key=${key}, failures=${updated.failureCount}/${resolved.failureThreshold})`\n        );\n        await transitionAndNotify(\n          resolvedStore,\n          key,\n          \"closed\",\n          \"open\",\n          onStateChange,\n          debug\n        );\n      }\n      throw err;\n    }\n\n    if (resolved.failureOn!.includes(c.res.status)) {\n      const updated = await safeCall(\n        () => resolvedStore.recordFailure(key),\n        null,\n        debug,\n        \"store.recordFailure()\"\n      );\n      if (updated && updated.failureCount >= resolved.failureThreshold!) {\n        debug(\n          `closed -> open (key=${key}, failures=${updated.failureCount}/${resolved.failureThreshold})`\n        );\n        await transitionAndNotify(\n          resolvedStore,\n          key,\n          \"closed\",\n          \"open\",\n          onStateChange,\n          debug\n        );\n      }\n    } else {\n      await safeCall(\n        () => resolvedStore.recordSuccess(key),\n        undefined,\n        debug,\n        \"store.recordSuccess()\"\n      );\n    }\n  };\n\n  return {\n    name: \"circuit-breaker\",\n    priority: Priority.CIRCUIT_BREAKER,\n    handler: withSkip(config?.skip, handler),\n    httpOnly: true,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/policies/resilience/latency-injection.d.ts

@@ -0,0 +1,35 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface LatencyInjectionConfig extends PolicyConfig {
+    /** Base delay in milliseconds. Required. */
+    delayMs: number;
+    /** Jitter proportion (0 to 1). Actual delay varies by +/- jitter * delayMs. Default: 0. */
+    jitter?: number;
+    /** Probability of injecting latency (0 to 1). Default: 1 (always). */
+    probability?: number;
+}
+/**
+ * Inject artificial latency into the pipeline for chaos/resilience testing.
+ *
+ * When active, pauses execution for a configurable duration before calling
+ * `next()`. Supports jitter to vary the delay and a probability setting to
+ * inject latency only a fraction of the time.
+ *
+ * @param config - Delay duration, jitter, and injection probability.
+ * @returns A {@link Policy} at priority 5 (early pipeline).
+ *
+ * @example
+ * ```ts
+ * // Fixed 100ms delay on every request
+ * latencyInjection({ delayMs: 100 });
+ *
+ * // 200ms +/- 50% jitter, injected 30% of the time
+ * latencyInjection({ delayMs: 200, jitter: 0.5, probability: 0.3 });
+ * ```
+ */
+declare const latencyInjection: (config: LatencyInjectionConfig) => Policy;
+
+export { type LatencyInjectionConfig, latencyInjection };

package/dist/policies/resilience/latency-injection.js

@@ -0,0 +1,26 @@
+import { definePolicy, Priority } from "../sdk";
+const latencyInjection = /* @__PURE__ */ definePolicy({
+  name: "latency-injection",
+  priority: Priority.EARLY,
+  httpOnly: true,
+  defaults: { jitter: 0, probability: 1 },
+  handler: async (_c, next, { config, debug }) => {
+    if (Math.random() >= config.probability) {
+      debug("skipping injection (probability miss)");
+      await next();
+      return;
+    }
+    let delay = config.delayMs;
+    if (config.jitter > 0) {
+      delay += (Math.random() * 2 - 1) * config.jitter * config.delayMs;
+    }
+    delay = Math.max(0, delay);
+    debug(`injecting ${delay.toFixed(0)}ms latency`);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    await next();
+  }
+});
+export {
+  latencyInjection
+};
+//# sourceMappingURL=latency-injection.js.map

package/dist/policies/resilience/latency-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/resilience/latency-injection.ts"],"sourcesContent":["/**\n * Latency injection policy - simulate network delays for chaos testing.\n *\n * @module latency-injection\n */\n\nimport { definePolicy, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface LatencyInjectionConfig extends PolicyConfig {\n  /** Base delay in milliseconds. Required. */\n  delayMs: number;\n  /** Jitter proportion (0 to 1). Actual delay varies by +/- jitter * delayMs. Default: 0. */\n  jitter?: number;\n  /** Probability of injecting latency (0 to 1). Default: 1 (always). */\n  probability?: number;\n}\n\n/**\n * Inject artificial latency into the pipeline for chaos/resilience testing.\n *\n * When active, pauses execution for a configurable duration before calling\n * `next()`. Supports jitter to vary the delay and a probability setting to\n * inject latency only a fraction of the time.\n *\n * @param config - Delay duration, jitter, and injection probability.\n * @returns A {@link Policy} at priority 5 (early pipeline).\n *\n * @example\n * ```ts\n * // Fixed 100ms delay on every request\n * latencyInjection({ delayMs: 100 });\n *\n * // 200ms +/- 50% jitter, injected 30% of the time\n * latencyInjection({ delayMs: 200, jitter: 0.5, probability: 0.3 });\n * ```\n */\nexport const latencyInjection =\n  /*#__PURE__*/ definePolicy<LatencyInjectionConfig>({\n    name: \"latency-injection\",\n    priority: Priority.EARLY,\n    httpOnly: true,\n    defaults: { jitter: 0, probability: 1 },\n    handler: async (_c, next, { config, debug }) => {\n      // Roll against probability\n      if (Math.random() >= config.probability!) {\n        debug(\"skipping injection (probability miss)\");\n        await next();\n        return;\n      }\n\n      // Compute delay with optional jitter\n      let delay = config.delayMs;\n      if (config.jitter! > 0) {\n        delay += (Math.random() * 2 - 1) * config.jitter! * config.delayMs;\n      }\n      // Clamp to minimum 0\n      delay = Math.max(0, delay);\n\n      debug(`injecting ${delay.toFixed(0)}ms latency`);\n      await new Promise((resolve) => setTimeout(resolve, delay));\n\n      await next();\n    },\n  });\n"],"mappings":"AAMA,SAAS,cAAc,gBAAgB;AA+BhC,MAAM,mBACG,6BAAqC;AAAA,EACjD,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU,EAAE,QAAQ,GAAG,aAAa,EAAE;AAAA,EACtC,SAAS,OAAO,IAAI,MAAM,EAAE,QAAQ,MAAM,MAAM;AAE9C,QAAI,KAAK,OAAO,KAAK,OAAO,aAAc;AACxC,YAAM,uCAAuC;AAC7C,YAAM,KAAK;AACX;AAAA,IACF;AAGA,QAAI,QAAQ,OAAO;AACnB,QAAI,OAAO,SAAU,GAAG;AACtB,gBAAU,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,SAAU,OAAO;AAAA,IAC7D;AAEA,YAAQ,KAAK,IAAI,GAAG,KAAK;AAEzB,UAAM,aAAa,MAAM,QAAQ,CAAC,CAAC,YAAY;AAC/C,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,KAAK,CAAC;AAEzD,UAAM,KAAK;AAAA,EACb;AACF,CAAC;","names":[]}

package/dist/policies/resilience/retry.d.ts

@@ -0,0 +1,71 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+/**
+ * Retry policy - automatic retry with configurable backoff for failed upstream calls.
+ *
+ * Retries work by inspecting the response status after `next()` completes.
+ * When a retryable status code is detected and a `_proxyRequest` exists on
+ * the Hono context (set by the URL upstream handler in `gateway.ts`), the
+ * policy clones the stored request and re-issues it via `fetch()` directly -
+ * no `globalThis.fetch` patching, fully concurrency-safe.
+ *
+ * For handler-based or service-binding upstreams there is no `_proxyRequest`,
+ * so the retry policy is effectively a no-op - which is the correct behavior
+ * since those upstream types would require calling `next()` multiple times
+ * (disallowed by Hono's compose model).
+ *
+ * @module retry
+ */
+
+interface RetryConfig extends PolicyConfig {
+    /** Maximum number of retries. Default: 3. */
+    maxRetries?: number;
+    /** Status codes that trigger a retry. Default: [502, 503, 504]. */
+    retryOn?: number[];
+    /** Backoff strategy. Default: "exponential". */
+    backoff?: "fixed" | "exponential";
+    /** Base delay in ms for backoff. Default: 200. */
+    baseDelayMs?: number;
+    /** Maximum delay in ms. Default: 5000. */
+    maxDelayMs?: number;
+    /** HTTP methods eligible for retry. Default: idempotent methods. */
+    retryMethods?: string[];
+    /** Response header name for the retry count. Default: `"x-retry-count"`. */
+    retryCountHeader?: string;
+}
+/**
+ * Retry failed upstream calls with configurable backoff.
+ *
+ * After `next()` completes, checks the response status against `retryOn`
+ * codes. If a retry is warranted and a `_proxyRequest` is available on the
+ * context (set by `createUrlUpstream()` in `gateway.ts`), the policy clones
+ * the stored request and calls `fetch()` directly - fully concurrency-safe
+ * with no `globalThis.fetch` patching.
+ *
+ * For handler-based or service-binding upstreams (no `_proxyRequest`), the
+ * retry policy is a no-op since there is no stored request to re-issue.
+ * Sets `X-Retry-Count` on the response when retries occur.
+ *
+ * @param config - Retry limits, backoff strategy, and retryable status codes.
+ * @returns A {@link Policy} at priority 90 (runs late, wraps the upstream fetch).
+ *
+ * @example
+ * ```ts
+ * // Retry 502/503/504 up to 3 times with exponential backoff
+ * retry();
+ *
+ * // Fixed 500ms delay, retry on 500 too
+ * retry({
+ *   maxRetries: 2,
+ *   retryOn: [500, 502, 503, 504],
+ *   backoff: "fixed",
+ *   baseDelayMs: 500,
+ * });
+ * ```
+ */
+declare function retry(config?: RetryConfig): Policy;
+
+export { type RetryConfig, retry };

package/dist/policies/resilience/retry.js

@@ -0,0 +1,79 @@
+import { Priority, policyDebug, resolveConfig, withSkip } from "../sdk";
+const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"];
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeDelay(attempt, strategy, baseMs, maxMs) {
+  const jitter = Math.random() * baseMs;
+  return strategy === "fixed" ? baseMs + jitter : Math.min(baseMs * 2 ** attempt + jitter, maxMs);
+}
+function retry(config) {
+  const resolved = resolveConfig(
+    {
+      maxRetries: 3,
+      retryOn: [502, 503, 504],
+      backoff: "exponential",
+      baseDelayMs: 200,
+      maxDelayMs: 5e3,
+      retryMethods: DEFAULT_RETRY_METHODS,
+      retryCountHeader: "x-retry-count"
+    },
+    config
+  );
+  const handler = async (c, next) => {
+    const debug = policyDebug(c, "retry");
+    const method = c.req.method.toUpperCase();
+    if (!resolved.retryMethods.includes(method)) {
+      await next();
+      return;
+    }
+    await next();
+    const proxyRequest = c.get("_proxyRequest");
+    if (!proxyRequest) {
+      return;
+    }
+    let retryCount = 0;
+    for (let attempt = 0; attempt < resolved.maxRetries; attempt++) {
+      if (!resolved.retryOn.includes(c.res.status)) {
+        break;
+      }
+      const delay = computeDelay(
+        attempt,
+        resolved.backoff,
+        resolved.baseDelayMs,
+        resolved.maxDelayMs
+      );
+      debug(
+        `attempt ${attempt + 1}/${resolved.maxRetries} failed (status=${c.res.status}), retrying in ${Math.round(delay)}ms`
+      );
+      await c.res.body?.cancel();
+      await sleep(delay);
+      let retryResponse;
+      try {
+        retryResponse = await fetch(proxyRequest.clone());
+      } catch {
+        debug(`retry attempt ${attempt + 1} fetch error, synthesizing 502`);
+        retryResponse = new Response(null, { status: 502 });
+      }
+      retryCount = attempt + 1;
+      c.res = new Response(retryResponse.body, {
+        status: retryResponse.status,
+        statusText: retryResponse.statusText,
+        headers: new Headers(retryResponse.headers)
+      });
+    }
+    if (retryCount > 0) {
+      c.res.headers.set(resolved.retryCountHeader, String(retryCount));
+    }
+  };
+  return {
+    name: "retry",
+    priority: Priority.RETRY,
+    handler: withSkip(config?.skip, handler),
+    httpOnly: true
+  };
+}
+export {
+  retry
+};
+//# sourceMappingURL=retry.js.map

package/dist/policies/resilience/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/resilience/retry.ts"],"sourcesContent":["/**\n * Retry policy - automatic retry with configurable backoff for failed upstream calls.\n *\n * Retries work by inspecting the response status after `next()` completes.\n * When a retryable status code is detected and a `_proxyRequest` exists on\n * the Hono context (set by the URL upstream handler in `gateway.ts`), the\n * policy clones the stored request and re-issues it via `fetch()` directly -\n * no `globalThis.fetch` patching, fully concurrency-safe.\n *\n * For handler-based or service-binding upstreams there is no `_proxyRequest`,\n * so the retry policy is effectively a no-op - which is the correct behavior\n * since those upstream types would require calling `next()` multiple times\n * (disallowed by Hono's compose model).\n *\n * @module retry\n */\n\nimport { Priority, policyDebug, resolveConfig, withSkip } from \"../sdk\";\nimport type { Policy, PolicyConfig } from \"../types\";\n\nexport interface RetryConfig extends PolicyConfig {\n  /** Maximum number of retries. Default: 3. */\n  maxRetries?: number;\n  /** Status codes that trigger a retry. Default: [502, 503, 504]. */\n  retryOn?: number[];\n  /** Backoff strategy. Default: \"exponential\". */\n  backoff?: \"fixed\" | \"exponential\";\n  /** Base delay in ms for backoff. Default: 200. */\n  baseDelayMs?: number;\n  /** Maximum delay in ms. Default: 5000. */\n  maxDelayMs?: number;\n  /** HTTP methods eligible for retry. Default: idempotent methods. */\n  retryMethods?: string[];\n  /** Response header name for the retry count. Default: `\"x-retry-count\"`. */\n  retryCountHeader?: string;\n}\n\nconst DEFAULT_RETRY_METHODS = [\"GET\", \"HEAD\", \"OPTIONS\", \"PUT\", \"DELETE\"];\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction computeDelay(\n  attempt: number,\n  strategy: \"fixed\" | \"exponential\",\n  baseMs: number,\n  maxMs: number\n): number {\n  const jitter = Math.random() * baseMs;\n  return strategy === \"fixed\"\n    ? baseMs + jitter\n    : Math.min(baseMs * 2 ** attempt + jitter, maxMs);\n}\n\n/**\n * Retry failed upstream calls with configurable backoff.\n *\n * After `next()` completes, checks the response status against `retryOn`\n * codes. If a retry is warranted and a `_proxyRequest` is available on the\n * context (set by `createUrlUpstream()` in `gateway.ts`), the policy clones\n * the stored request and calls `fetch()` directly - fully concurrency-safe\n * with no `globalThis.fetch` patching.\n *\n * For handler-based or service-binding upstreams (no `_proxyRequest`), the\n * retry policy is a no-op since there is no stored request to re-issue.\n * Sets `X-Retry-Count` on the response when retries occur.\n *\n * @param config - Retry limits, backoff strategy, and retryable status codes.\n * @returns A {@link Policy} at priority 90 (runs late, wraps the upstream fetch).\n *\n * @example\n * ```ts\n * // Retry 502/503/504 up to 3 times with exponential backoff\n * retry();\n *\n * // Fixed 500ms delay, retry on 500 too\n * retry({\n *   maxRetries: 2,\n *   retryOn: [500, 502, 503, 504],\n *   backoff: \"fixed\",\n *   baseDelayMs: 500,\n * });\n * ```\n */\nexport function retry(config?: RetryConfig): Policy {\n  const resolved = resolveConfig<RetryConfig>(\n    {\n      maxRetries: 3,\n      retryOn: [502, 503, 504],\n      backoff: \"exponential\" as const,\n      baseDelayMs: 200,\n      maxDelayMs: 5_000,\n      retryMethods: DEFAULT_RETRY_METHODS,\n      retryCountHeader: \"x-retry-count\",\n    },\n    config\n  );\n\n  const handler: import(\"hono\").MiddlewareHandler = async (c, next) => {\n    const debug = policyDebug(c, \"retry\");\n    const method = c.req.method.toUpperCase();\n\n    // Non-retryable methods pass through without retry logic\n    if (!resolved.retryMethods!.includes(method)) {\n      await next();\n      return;\n    }\n\n    // Execute the downstream pipeline (policies + upstream)\n    await next();\n\n    // Retrieve the stored proxy request (set by createUrlUpstream in gateway.ts).\n    // For handler/service-binding upstreams this is undefined - retry is a no-op.\n    const proxyRequest = c.get(\"_proxyRequest\") as Request | undefined;\n    if (!proxyRequest) {\n      return;\n    }\n\n    // Retry loop: check response status and re-issue if retryable\n    let retryCount = 0;\n\n    for (let attempt = 0; attempt < resolved.maxRetries!; attempt++) {\n      if (!resolved.retryOn!.includes(c.res.status)) {\n        break;\n      }\n\n      const delay = computeDelay(\n        attempt,\n        resolved.backoff!,\n        resolved.baseDelayMs!,\n        resolved.maxDelayMs!\n      );\n      debug(\n        `attempt ${attempt + 1}/${resolved.maxRetries} failed (status=${c.res.status}), retrying in ${Math.round(delay)}ms`\n      );\n\n      // Cancel the body of the failed response to release resources\n      await c.res.body?.cancel();\n\n      await sleep(delay);\n\n      // Clone the stored proxy request and re-issue via fetch directly\n      let retryResponse: Response;\n      try {\n        retryResponse = await fetch(proxyRequest.clone());\n      } catch {\n        // Network error during retry - treat as a retryable 502 so\n        // the loop continues to the next attempt.\n        debug(`retry attempt ${attempt + 1} fetch error, synthesizing 502`);\n        retryResponse = new Response(null, { status: 502 });\n      }\n      retryCount = attempt + 1;\n\n      // Replace the response on the context\n      c.res = new Response(retryResponse.body, {\n        status: retryResponse.status,\n        statusText: retryResponse.statusText,\n        headers: new Headers(retryResponse.headers),\n      });\n    }\n\n    if (retryCount > 0) {\n      c.res.headers.set(resolved.retryCountHeader!, String(retryCount));\n    }\n  };\n\n  return {\n    name: \"retry\",\n    priority: Priority.RETRY,\n    handler: withSkip(config?.skip, handler),\n    httpOnly: true,\n  };\n}\n"],"mappings":"AAiBA,SAAS,UAAU,aAAa,eAAe,gBAAgB;AAoB/D,MAAM,wBAAwB,CAAC,OAAO,QAAQ,WAAW,OAAO,QAAQ;AAExE,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;AAEA,SAAS,aACP,SACA,UACA,QACA,OACQ;AACR,QAAM,SAAS,KAAK,OAAO,IAAI;AAC/B,SAAO,aAAa,UAChB,SAAS,SACT,KAAK,IAAI,SAAS,KAAK,UAAU,QAAQ,KAAK;AACpD;AAgCO,SAAS,MAAM,QAA8B;AAClD,QAAM,WAAW;AAAA,IACf;AAAA,MACE,YAAY;AAAA,MACZ,SAAS,CAAC,KAAK,KAAK,GAAG;AAAA,MACvB,SAAS;AAAA,MACT,aAAa;AAAA,MACb,YAAY;AAAA,MACZ,cAAc;AAAA,MACd,kBAAkB;AAAA,IACpB;AAAA,IACA;AAAA,EACF;AAEA,QAAM,UAA4C,OAAO,GAAG,SAAS;AACnE,UAAM,QAAQ,YAAY,GAAG,OAAO;AACpC,UAAM,SAAS,EAAE,IAAI,OAAO,YAAY;AAGxC,QAAI,CAAC,SAAS,aAAc,SAAS,MAAM,GAAG;AAC5C,YAAM,KAAK;AACX;AAAA,IACF;AAGA,UAAM,KAAK;AAIX,UAAM,eAAe,EAAE,IAAI,eAAe;AAC1C,QAAI,CAAC,cAAc;AACjB;AAAA,IACF;AAGA,QAAI,aAAa;AAEjB,aAAS,UAAU,GAAG,UAAU,SAAS,YAAa,WAAW;AAC/D,UAAI,CAAC,SAAS,QAAS,SAAS,EAAE,IAAI,MAAM,GAAG;AAC7C;AAAA,MACF;AAEA,YAAM,QAAQ;AAAA,QACZ;AAAA,QACA,SAAS;AAAA,QACT,SAAS;AAAA,QACT,SAAS;AAAA,MACX;AACA;AAAA,QACE,WAAW,UAAU,CAAC,IAAI,SAAS,UAAU,mBAAmB,EAAE,IAAI,MAAM,kBAAkB,KAAK,MAAM,KAAK,CAAC;AAAA,MACjH;AAGA,YAAM,EAAE,IAAI,MAAM,OAAO;AAEzB,YAAM,MAAM,KAAK;AAGjB,UAAI;AACJ,UAAI;AACF,wBAAgB,MAAM,MAAM,aAAa,MAAM,CAAC;AAAA,MAClD,QAAQ;AAGN,cAAM,iBAAiB,UAAU,CAAC,gCAAgC;AAClE,wBAAgB,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC;AAAA,MACpD;AACA,mBAAa,UAAU;AAGvB,QAAE,MAAM,IAAI,SAAS,cAAc,MAAM;AAAA,QACvC,QAAQ,cAAc;AAAA,QACtB,YAAY,cAAc;AAAA,QAC1B,SAAS,IAAI,QAAQ,cAAc,OAAO;AAAA,MAC5C,CAAC;AAAA,IACH;AAEA,QAAI,aAAa,GAAG;AAClB,QAAE,IAAI,QAAQ,IAAI,SAAS,kBAAmB,OAAO,UAAU,CAAC;AAAA,IAClE;AAAA,EACF;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU,SAAS;AAAA,IACnB,SAAS,SAAS,QAAQ,MAAM,OAAO;AAAA,IACvC,UAAU;AAAA,EACZ;AACF;","names":[]}

package/dist/policies/resilience/timeout.d.ts

@@ -0,0 +1,32 @@
+import { g as PolicyConfig, P as Policy } from '../../protocol-2fD3DJrL.js';
+import 'hono';
+import '../sdk/trace.js';
+import '@vivero/stoma-core';
+
+interface TimeoutConfig extends PolicyConfig {
+    /** Timeout in milliseconds. Default: 30000. */
+    timeoutMs?: number;
+    /** Error message when timeout fires. */
+    message?: string;
+    /** HTTP status code when timeout fires. Default: 504. */
+    statusCode?: number;
+}
+/**
+ * Enforce a time budget for downstream execution.
+ *
+ * Races `next()` against a timer. If the timer fires first, throws a
+ * GatewayError (default 504). The timer is always cleaned up, even on
+ * downstream errors.
+ *
+ * @param config - Timeout duration and custom error message. Defaults to 30 seconds.
+ * @returns A {@link Policy} at priority 85 (runs late, close to upstream).
+ *
+ * @example
+ * ```ts
+ * // 5-second timeout with custom message
+ * timeout({ timeoutMs: 5000, message: "Upstream did not respond in time" });
+ * ```
+ */
+declare const timeout: (config?: TimeoutConfig | undefined) => Policy;
+
+export { type TimeoutConfig, timeout };

package/dist/policies/resilience/timeout.js

@@ -0,0 +1,46 @@
+import { GatewayError } from "../../core/errors";
+import { definePolicy, Priority } from "../sdk";
+const timeout = /* @__PURE__ */ definePolicy({
+  name: "timeout",
+  priority: Priority.TIMEOUT,
+  httpOnly: true,
+  defaults: { timeoutMs: 3e4, message: "Gateway timeout", statusCode: 504 },
+  handler: async (c, next, { config, trace }) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    c.set("_timeoutSignal", controller.signal);
+    try {
+      const start = Date.now();
+      await Promise.race([
+        next(),
+        new Promise((_, reject) => {
+          controller.signal.addEventListener(
+            "abort",
+            () => reject(
+              new GatewayError(
+                config.statusCode,
+                "gateway_timeout",
+                config.message
+              )
+            )
+          );
+        })
+      ]);
+      trace("passed", {
+        budgetMs: config.timeoutMs,
+        elapsed: Date.now() - start
+      });
+    } catch (err) {
+      if (err instanceof GatewayError && err.code === "gateway_timeout") {
+        trace("fired", { budgetMs: config.timeoutMs });
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+});
+export {
+  timeout
+};
+//# sourceMappingURL=timeout.js.map

package/dist/policies/resilience/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/policies/resilience/timeout.ts"],"sourcesContent":["/**\n * Timeout policy - enforce a response time budget for downstream handlers.\n *\n * @module timeout\n */\nimport { GatewayError } from \"../../core/errors\";\nimport { definePolicy, Priority } from \"../sdk\";\nimport type { PolicyConfig } from \"../types\";\n\nexport interface TimeoutConfig extends PolicyConfig {\n  /** Timeout in milliseconds. Default: 30000. */\n  timeoutMs?: number;\n  /** Error message when timeout fires. */\n  message?: string;\n  /** HTTP status code when timeout fires. Default: 504. */\n  statusCode?: number;\n}\n\n/**\n * Enforce a time budget for downstream execution.\n *\n * Races `next()` against a timer. If the timer fires first, throws a\n * GatewayError (default 504). The timer is always cleaned up, even on\n * downstream errors.\n *\n * @param config - Timeout duration and custom error message. Defaults to 30 seconds.\n * @returns A {@link Policy} at priority 85 (runs late, close to upstream).\n *\n * @example\n * ```ts\n * // 5-second timeout with custom message\n * timeout({ timeoutMs: 5000, message: \"Upstream did not respond in time\" });\n * ```\n */\nexport const timeout = /*#__PURE__*/ definePolicy<TimeoutConfig>({\n  name: \"timeout\",\n  priority: Priority.TIMEOUT,\n  httpOnly: true,\n  defaults: { timeoutMs: 30_000, message: \"Gateway timeout\", statusCode: 504 },\n  handler: async (c, next, { config, trace }) => {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), config.timeoutMs!);\n\n    // Store the abort signal on context so the URL upstream handler can\n    // pass it to fetch(), enabling true cancellation of in-flight requests.\n    c.set(\"_timeoutSignal\", controller.signal);\n\n    try {\n      const start = Date.now();\n      await Promise.race([\n        next(),\n        new Promise<never>((_, reject) => {\n          controller.signal.addEventListener(\"abort\", () =>\n            reject(\n              new GatewayError(\n                config.statusCode!,\n                \"gateway_timeout\",\n                config.message!\n              )\n            )\n          );\n        }),\n      ]);\n      trace(\"passed\", {\n        budgetMs: config.timeoutMs!,\n        elapsed: Date.now() - start,\n      });\n    } catch (err) {\n      if (err instanceof GatewayError && err.code === \"gateway_timeout\") {\n        trace(\"fired\", { budgetMs: config.timeoutMs! });\n      }\n      throw err;\n    } finally {\n      clearTimeout(timer);\n    }\n  },\n});\n"],"mappings":"AAKA,SAAS,oBAAoB;AAC7B,SAAS,cAAc,gBAAgB;AA4BhC,MAAM,UAAwB,6BAA4B;AAAA,EAC/D,MAAM;AAAA,EACN,UAAU,SAAS;AAAA,EACnB,UAAU;AAAA,EACV,UAAU,EAAE,WAAW,KAAQ,SAAS,mBAAmB,YAAY,IAAI;AAAA,EAC3E,SAAS,OAAO,GAAG,MAAM,EAAE,QAAQ,MAAM,MAAM;AAC7C,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,QAAQ,WAAW,MAAM,WAAW,MAAM,GAAG,OAAO,SAAU;AAIpE,MAAE,IAAI,kBAAkB,WAAW,MAAM;AAEzC,QAAI;AACF,YAAM,QAAQ,KAAK,IAAI;AACvB,YAAM,QAAQ,KAAK;AAAA,QACjB,KAAK;AAAA,QACL,IAAI,QAAe,CAAC,GAAG,WAAW;AAChC,qBAAW,OAAO;AAAA,YAAiB;AAAA,YAAS,MAC1C;AAAA,cACE,IAAI;AAAA,gBACF,OAAO;AAAA,gBACP;AAAA,gBACA,OAAO;AAAA,cACT;AAAA,YACF;AAAA,UACF;AAAA,QACF,CAAC;AAAA,MACH,CAAC;AACD,YAAM,UAAU;AAAA,QACd,UAAU,OAAO;AAAA,QACjB,SAAS,KAAK,IAAI,IAAI;AAAA,MACxB,CAAC;AAAA,IACH,SAAS,KAAK;AACZ,UAAI,eAAe,gBAAgB,IAAI,SAAS,mBAAmB;AACjE,cAAM,SAAS,EAAE,UAAU,OAAO,UAAW,CAAC;AAAA,MAChD;AACA,YAAM;AAAA,IACR,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF;AACF,CAAC;","names":[]}