@decocms/apps-vtex 7.23.0 → 7.24.0

package/src/utils/fetchCache.ts

@@ -7,52 +7,35 @@
  * Only caches on the server side. Keyed by full URL string.
  */
 
-const DEFAULT_MAX_ENTRIES = 500;
-const MAX_RETRIES = 2;
-const RETRY_DELAYS = [200, 400];
-// Per-attempt timeout. Bounds how long a single hung `fetch()` can hold an
-// inflight entry alive. Without this, a VTEX subrequest that never settles
-// leaks the inflight Map slot forever and every subsequent request for the
-// same cache key joins the zombie Promise, pinning memory until
-// `exceededMemory` (observed in prod: 514 hard crashes / 24h on a PLP route).
-const FETCH_TIMEOUT_MS = 10_000;
+import {
+  FETCH_CACHE_FRESH_TTL_MS,
+  FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
+  FETCH_CACHE_MAX_ENTRIES,
+  FETCH_CACHE_STALE_IF_ERROR_MS,
+} from "./constants";
 
 interface CacheEntry {
-	body: unknown;
-	status: number;
-	createdAt: number;
-	refreshing: boolean;
+  body: unknown;
+  status: number;
+  createdAt: number;
+  refreshing: boolean;
 }
 
-const TTL_BY_STATUS: Record<string, number> = {
-	"2xx": 180_000, // 3 min for success
-	"404": 10_000, // 10s for not found
-	"5xx": 0, // never cache server errors
-};
-
-function ttlForStatus(status: number): number {
-	if (status >= 200 && status < 300) return TTL_BY_STATUS["2xx"];
-	if (status === 404) return TTL_BY_STATUS["404"];
-	if (status >= 500) return TTL_BY_STATUS["5xx"];
-	return 0;
+function freshTtlForStatus(status: number): number {
+  if (status >= 200 && status < 300) return FETCH_CACHE_FRESH_TTL_MS.success;
+  if (status === 404) return FETCH_CACHE_FRESH_TTL_MS.notFound;
+  if (status >= 500) return FETCH_CACHE_FRESH_TTL_MS.serverError;
+  return 0;
 }
 
 const store = new Map<string, CacheEntry>();
 const inflight = new Map<string, Promise<CacheEntry>>();
 
 function evictIfNeeded() {
-	if (store.size <= DEFAULT_MAX_ENTRIES) return;
-	const sorted = [...store.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
-	const toRemove = sorted.slice(0, store.size - DEFAULT_MAX_ENTRIES);
-	for (const [key] of toRemove) store.delete(key);
-}
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isRetryable(response: Response): boolean {
-	return response.status >= 500 || response.status === 429;
+  if (store.size <= FETCH_CACHE_MAX_ENTRIES) return;
+  const sorted = [...store.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+  const toRemove = sorted.slice(0, store.size - FETCH_CACHE_MAX_ENTRIES);
+  for (const [key] of toRemove) store.delete(key);
 }
 
 /**
@@ -62,70 +45,52 @@ function isRetryable(response: Response): boolean {
  * every subsequent request for the same key joins the zombie Promise.
  */
 function withTimeout<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const timeout = new Promise<never>((_, reject) => {
-		timer = setTimeout(() => {
-			reject(new Error(`${label} timed out after ${ms}ms`));
-		}, ms);
-	});
-	return Promise.race([work, timeout]).finally(() => {
-		clearTimeout(timer);
-	});
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+  });
+  return Promise.race([work, timeout]).finally(() => {
+    clearTimeout(timer);
+  });
 }
 
-async function executeFetch(
-	url: string,
-	doFetch: () => Promise<Response>,
-	retry = true,
-): Promise<CacheEntry> {
-	let lastError: Error | undefined;
-
-	const attempts = retry ? MAX_RETRIES + 1 : 1;
-	for (let attempt = 0; attempt < attempts; attempt++) {
-		try {
-			const response = await doFetch();
-
-			if (isRetryable(response) && attempt < attempts - 1) {
-				console.warn(
-					`[vtex-fetch] ${response.status} on attempt ${attempt + 1}/${attempts} — ${url}`,
-				);
-				await sleep(RETRY_DELAYS[attempt] ?? 400);
-				continue;
-			}
-
-			if (response.status >= 500) {
-				throw new Error(
-					`fetchWithCache: ${response.status} ${response.statusText} after ${attempt + 1} attempt(s) — ${url}`,
-				);
-			}
-
-			const body = response.ok ? await response.json() : null;
-			return {
-				body,
-				status: response.status,
-				createdAt: Date.now(),
-				refreshing: false,
-			};
-		} catch (error) {
-			lastError = error instanceof Error ? error : new Error(String(error));
-
-			if (attempt < attempts - 1) {
-				console.warn(
-					`[vtex-fetch] attempt ${attempt + 1}/${attempts} failed — ${url}: ${lastError.message}`,
-				);
-				await sleep(RETRY_DELAYS[attempt] ?? 400);
-			}
-		}
-	}
-
-	throw lastError ?? new Error(`fetchWithCache: all ${attempts} attempts failed — ${url}`);
+async function executeFetch(url: string, doFetch: () => Promise<Response>): Promise<CacheEntry> {
+  // Single attempt on purpose. The resilience layer (`createResilientFetch`,
+  // wired as the VTEX fetch's baseFetch) owns retries, backoff+jitter, the
+  // per-host retry budget, and the circuit breaker. Retrying here would:
+  //   - double-retry network errors (resilience 3× × fetchCache 3× = up to 9
+  //     upstream calls per logical request — the retry storm the budget
+  //     prevents), and
+  //   - re-enter the breaker on every 5xx retry, opening it ~3× too fast.
+  const response = await doFetch();
+
+  if (response.status >= 500) {
+    throw new Error(`fetchWithCache: ${response.status} ${response.statusText} — ${url}`);
+  }
+
+  const body = response.ok ? await response.json() : null;
+  return {
+    body,
+    status: response.status,
+    createdAt: Date.now(),
+    refreshing: false,
+  };
 }
 
 export interface FetchCacheOptions {
-	/**
-	 * Custom TTL in ms. If provided, overrides status-based TTL.
-	 */
-	ttl?: number;
+  /**
+   * Custom TTL in ms. If provided, overrides status-based TTL.
+   */
+  ttl?: number;
+  /**
+   * Stale-if-error window in ms. How long past the freshness TTL a last-good
+   * entry may still be served while the origin is failing. Defaults to
+   * {@link FETCH_CACHE_STALE_IF_ERROR_MS} (24h). Set to 0 to disable stale
+   * serving.
+   */
+  sieMs?: number;
 }
 
 /**
@@ -140,83 +105,95 @@ export interface FetchCacheOptions {
  * @returns Parsed JSON body, or null for cacheable error responses (e.g. 404)
  */
 export function fetchWithCache<T>(
-	cacheKey: string,
-	doFetch: () => Promise<Response>,
-	opts?: FetchCacheOptions,
+  cacheKey: string,
+  doFetch: () => Promise<Response>,
+  opts?: FetchCacheOptions,
 ): Promise<T | null> {
-	const now = Date.now();
-	const entry = store.get(cacheKey);
-
-	if (entry) {
-		const maxAge = opts?.ttl ?? ttlForStatus(entry.status);
-		const isStale = now - entry.createdAt > maxAge;
-
-		if (!isStale) return Promise.resolve(entry.body as T | null);
-
-		if (isStale && !entry.refreshing) {
-			entry.refreshing = true;
-			// Background refresh: no retry — stale data is already being served.
-			// Timeout guards against a hung VTEX response leaving `refreshing`
-			// stuck true forever (which would silently disable revalidation).
-			withTimeout(
-				executeFetch(cacheKey, doFetch, false),
-				FETCH_TIMEOUT_MS,
-				`fetchCache stale-refresh ${cacheKey}`,
-			)
-				.then((fresh) => {
-					const ttl = opts?.ttl ?? ttlForStatus(fresh.status);
-					const existingWasSuccess = entry.status >= 200 && entry.status < 300;
-					const freshIsError = fresh.status >= 400;
-					const wouldDowngrade = existingWasSuccess && freshIsError;
-					if (ttl > 0 && !wouldDowngrade) {
-						store.set(cacheKey, fresh);
-					} else {
-						entry.refreshing = false;
-					}
-				})
-				.catch(() => {
-					entry.refreshing = false;
-				});
-			return Promise.resolve(entry.body as T | null);
-		}
-
-		return Promise.resolve(entry.body as T | null);
-	}
-
-	const existing = inflight.get(cacheKey);
-	if (existing) return existing.then((e) => e.body as T | null);
-
-	// Wrap with a timeout so the `.finally()` below always runs and evicts
-	// the inflight slot — even if `executeFetch` never settles. See the
-	// FETCH_TIMEOUT_MS comment at the top of this file for the leak this
-	// guards against.
-	const promise = withTimeout(
-		executeFetch(cacheKey, doFetch),
-		FETCH_TIMEOUT_MS,
-		`fetchCache ${cacheKey}`,
-	)
-		.then((fresh) => {
-			const ttl = opts?.ttl ?? ttlForStatus(fresh.status);
-			if (ttl > 0) {
-				store.set(cacheKey, fresh);
-				evictIfNeeded();
-			}
-			return fresh;
-		})
-		.finally(() => inflight.delete(cacheKey));
-
-	inflight.set(cacheKey, promise);
-	return promise.then((e) => e.body as T | null);
+  const now = Date.now();
+  const entry = store.get(cacheKey);
+
+  if (entry) {
+    const maxAge = opts?.ttl ?? freshTtlForStatus(entry.status);
+    const age = now - entry.createdAt;
+    const isStale = age > maxAge;
+
+    if (!isStale) return Promise.resolve(entry.body as T | null);
+
+    // Beyond the stale-if-error window the last-good entry is too old to keep
+    // serving during an outage: drop it and fall through to a foreground
+    // refetch (cold path). On a healthy origin this is never reached because
+    // the background refresh below keeps resetting `createdAt`.
+    const sieMs = opts?.sieMs ?? FETCH_CACHE_STALE_IF_ERROR_MS;
+    const tooStale = age > maxAge + sieMs;
+
+    if (!tooStale) {
+      if (!entry.refreshing) {
+        entry.refreshing = true;
+        // Background refresh: no retry — stale data is already being served.
+        // Timeout guards against a hung VTEX response leaving `refreshing`
+        // stuck true forever (which would silently disable revalidation).
+        withTimeout(
+          executeFetch(cacheKey, doFetch),
+          FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
+          `fetchCache stale-refresh ${cacheKey}`,
+        )
+          .then((fresh) => {
+            const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
+            const existingWasSuccess = entry.status >= 200 && entry.status < 300;
+            const freshIsError = fresh.status >= 400;
+            const wouldDowngrade = existingWasSuccess && freshIsError;
+            if (ttl > 0 && !wouldDowngrade) {
+              store.set(cacheKey, fresh);
+            } else {
+              entry.refreshing = false;
+            }
+          })
+          .catch(() => {
+            entry.refreshing = false;
+          });
+      }
+      // Serve last-good while it is within the SIE window (stale-if-error).
+      return Promise.resolve(entry.body as T | null);
+    }
+
+    store.delete(cacheKey);
+    // fall through to the cold path below with the dead entry removed
+  }
+
+  const existing = inflight.get(cacheKey);
+  if (existing) return existing.then((e) => e.body as T | null);
+
+  // Wrap with a timeout so the `.finally()` below always runs and evicts
+  // the inflight slot — even if `executeFetch` never settles. See the
+  // FETCH_CACHE_INFLIGHT_BACKSTOP_MS doc comment (constants.ts) for the leak
+  // this guards against.
+  const promise = withTimeout(
+    executeFetch(cacheKey, doFetch),
+    FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
+    `fetchCache ${cacheKey}`,
+  )
+    .then((fresh) => {
+      const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
+      if (ttl > 0) {
+        store.set(cacheKey, fresh);
+        evictIfNeeded();
+      }
+      return fresh;
+    })
+    .finally(() => inflight.delete(cacheKey));
+
+  inflight.set(cacheKey, promise);
+  return promise.then((e) => e.body as T | null);
 }
 
 export function clearFetchCache() {
-	store.clear();
-	inflight.clear();
+  store.clear();
+  inflight.clear();
 }
 
 export function getFetchCacheStats() {
-	return {
-		entries: store.size,
-		inflight: inflight.size,
-	};
+  return {
+    entries: store.size,
+    inflight: inflight.size,
+  };
 }

package/src/utils/instrumentedFetch.ts

@@ -31,27 +31,37 @@
  */
 
 import {
-	createInstrumentedFetch,
-	type InstrumentedFetch,
+  createInstrumentedFetch,
+  type InstrumentedFetch,
 } from "@decocms/blocks/sdk/instrumentedFetch";
-import { recordCommerceMetric } from "@decocms/blocks/sdk/observability";
+import { recordCommerceMetric, statusClassFor } from "@decocms/blocks/sdk/observability";
 import { vtexOperationRouter } from "./operationRouter";
+import { createResilientFetch, type ResilienceConfig } from "./resilience";
 
 export interface CreateVtexFetchOptions {
-	/**
-	 * Underlying fetch to wrap. Defaults to `globalThis.fetch`.
-	 * Pass an existing custom fetch (e.g. one that injects auth cookies
-	 * or routes through a proxy) to preserve its behavior while adding
-	 * the VTEX instrumentation layer on top.
-	 */
-	baseFetch?: typeof fetch;
-	/**
-	 * Disable the `http.client.request.duration` histogram emission for
-	 * VTEX calls. The framework's span and structured logs still emit.
-	 * Useful when the consumer wants to record its own histogram with a
-	 * custom shape. Default: false.
-	 */
-	disableHistogram?: boolean;
+  /**
+   * Underlying fetch to wrap. Defaults to `globalThis.fetch`.
+   * Pass an existing custom fetch (e.g. one that injects auth cookies
+   * or routes through a proxy) to preserve its behavior while adding
+   * the VTEX instrumentation layer on top.
+   */
+  baseFetch?: typeof fetch;
+  /**
+   * Disable the `http.client.request.duration` histogram emission for
+   * VTEX calls. The framework's span and structured logs still emit.
+   * Useful when the consumer wants to record its own histogram with a
+   * custom shape. Default: false.
+   */
+  disableHistogram?: boolean;
+  /**
+   * Resilience layer (real abort/timeout + per-host circuit breaker +
+   * idempotent-only retry with a budget). ON by default so every VTEX
+   * consumer is protected against upstream slowness/outages without
+   * per-site wiring. Pass a partial config to tune, `false` to opt out,
+   * or flip the `VTEX_RESILIENCE_DISABLED=true` env var as a runtime
+   * kill-switch. See {@link createResilientFetch}.
+   */
+  resilience?: Partial<ResilienceConfig> | false;
 }
 
 /**
@@ -59,20 +69,29 @@ export interface CreateVtexFetchOptions {
  * `setVtexFetch(...)`. See module docstring for details.
  */
 export function createVtexFetch(options: CreateVtexFetchOptions = {}): InstrumentedFetch {
-	const { baseFetch, disableHistogram = false } = options;
-	return createInstrumentedFetch({
-		name: "vtex",
-		baseFetch,
-		resolveOperation: vtexOperationRouter,
-		onComplete: disableHistogram
-			? undefined
-			: ({ operation, status, durationMs, cached }) => {
-					recordCommerceMetric(durationMs, {
-						provider: "vtex",
-						operation,
-						status_class: `${Math.floor(status / 100)}xx`,
-						cached,
-					});
-				},
-	});
+  const { baseFetch, disableHistogram = false, resilience } = options;
+  // Compose the resilience layer UNDER the instrumentation so spans/histograms
+  // see the real outcome (including breaker fast-fails and timeouts). A single
+  // instrumented call = one logical request, which may span several underlying
+  // attempts. Covers every VTEX egress path — cached GETs, IS, and checkout
+  // POSTs — because they all funnel through this one fetch.
+  const resilientBase =
+    resilience === false
+      ? baseFetch
+      : createResilientFetch(baseFetch ?? globalThis.fetch, resilience ?? {});
+  return createInstrumentedFetch({
+    name: "vtex",
+    baseFetch: resilientBase,
+    resolveOperation: vtexOperationRouter,
+    onComplete: disableHistogram
+      ? undefined
+      : ({ operation, status, durationMs, cached }) => {
+          recordCommerceMetric(durationMs, {
+            provider: "vtex",
+            operation,
+            status_class: statusClassFor(status),
+            cached,
+          });
+        },
+  });
 }