@decocms/apps-vtex 7.23.0 → 7.25.0

package/src/utils/__tests__/resilience.test.ts

@@ -0,0 +1,205 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createResilientFetch,
+  isNonRetryableVtexError,
+  resetResilienceState,
+  VtexCircuitOpenError,
+  VtexTimeoutError,
+} from "../resilience";
+
+function res(status: number, body = "ok"): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: "",
+    json: async () => body,
+  } as Response;
+}
+
+beforeEach(() => {
+  resetResilienceState();
+});
+
+describe("createResilientFetch", () => {
+  it("passes a healthy GET through untouched, no retry", async () => {
+    const underlying = vi.fn(async () => res(200, "prod"));
+    const rf = createResilientFetch(underlying as unknown as typeof fetch);
+    const r = await rf("https://acct.vtexcommercestable.com.br/ok");
+    expect(r.status).toBe(200);
+    expect(underlying).toHaveBeenCalledOnce();
+  });
+
+  it("never retries a POST (mutation), even on 5xx", async () => {
+    const underlying = vi.fn(async () => res(500));
+    const rf = createResilientFetch(underlying as unknown as typeof fetch);
+    const r = await rf("https://acct.vtexcommercestable.com.br/checkout", {
+      method: "POST",
+      body: "{}",
+    });
+    expect(r.status).toBe(500);
+    expect(underlying).toHaveBeenCalledOnce();
+  });
+
+  it("retries an idempotent GET on a thrown network error, then succeeds", async () => {
+    let n = 0;
+    const underlying = vi.fn(async () => {
+      n++;
+      if (n < 3) throw new Error("ECONNRESET");
+      return res(200);
+    });
+    const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+      backoffBaseMs: 1,
+      backoffCapMs: 2,
+    });
+    const r = await rf("https://acct.vtexcommercestable.com.br/search");
+    expect(r.status).toBe(200);
+    expect(underlying).toHaveBeenCalledTimes(3);
+  });
+
+  it("opens the circuit after N consecutive failures and then fails fast", async () => {
+    const underlying = vi.fn(async () => res(503));
+    const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+      breakerConsecutiveFailures: 5,
+    });
+    const host = "https://acct.vtexcommercestable.com.br";
+    // 5 POSTs (1 attempt each) → 5 consecutive breaker failures → open.
+    for (let i = 0; i < 5; i++) {
+      await rf(`${host}/p`, { method: "POST", body: "x" });
+    }
+    const before = underlying.mock.calls.length;
+    await expect(rf(`${host}/p`, { method: "POST", body: "x" })).rejects.toBeInstanceOf(
+      VtexCircuitOpenError,
+    );
+    // Fail-fast must not touch the origin.
+    expect(underlying.mock.calls.length).toBe(before);
+  });
+
+  it("half-opens after cooldown and closes on a successful probe", async () => {
+    vi.useFakeTimers();
+    try {
+      let healthy = false;
+      const underlying = vi.fn(async () => (healthy ? res(200) : res(503)));
+      const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+        breakerConsecutiveFailures: 3,
+        breakerOpenCooldownMs: 5_000,
+      });
+      const host = "https://acct.vtexcommercestable.com.br";
+      for (let i = 0; i < 3; i++) await rf(`${host}/p`, { method: "POST", body: "x" });
+      // Open now → fail fast.
+      await expect(rf(`${host}/p`, { method: "POST", body: "x" })).rejects.toBeInstanceOf(
+        VtexCircuitOpenError,
+      );
+      // After cooldown, a probe is allowed; make it succeed.
+      healthy = true;
+      await vi.advanceTimersByTimeAsync(5_001);
+      const r = await rf(`${host}/p`, { method: "POST", body: "x" });
+      expect(r.status).toBe(200);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("aborts a hung request with the per-attempt timeout", async () => {
+    vi.useFakeTimers();
+    try {
+      const underlying = vi.fn(
+        (_input: RequestInfo | URL, init?: RequestInit) =>
+          new Promise<Response>((_resolve, reject) => {
+            init?.signal?.addEventListener("abort", () =>
+              reject(Object.assign(new Error("aborted"), { name: "AbortError" })),
+            );
+          }),
+      );
+      const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+        maxRetries: 0,
+        perAttemptTimeoutMs: 8_000,
+      });
+      const p = rf("https://acct.vtexcommercestable.com.br/hung");
+      p.catch(() => {});
+      await vi.advanceTimersByTimeAsync(8_001);
+      await expect(p).rejects.toBeInstanceOf(VtexTimeoutError);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("aborts an in-flight VTEX call when the ambient request signal aborts", async () => {
+    const ac = new AbortController();
+    const request = new Request("https://store.example/page", { signal: ac.signal });
+    const underlying = vi.fn(
+      (_input: RequestInfo | URL, init?: RequestInit) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () =>
+            reject(Object.assign(new Error("aborted"), { name: "AbortError" })),
+          );
+        }),
+    );
+    const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+      maxRetries: 0,
+      perAttemptTimeoutMs: 60_000,
+    });
+
+    await RequestContext.run(request, async () => {
+      const p = rf("https://acct.vtexcommercestable.com.br/slow");
+      p.catch(() => {});
+      ac.abort();
+      await expect(p).rejects.toThrow();
+    });
+    expect(underlying).toHaveBeenCalled();
+  });
+
+  it("does NOT count an external (caller/ambient) abort as a breaker failure", async () => {
+    const underlying = vi.fn(
+      (_input: RequestInfo | URL, init?: RequestInit) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () =>
+            reject(Object.assign(new Error("aborted"), { name: "AbortError" })),
+          );
+        }),
+    );
+    const host = "https://acct.vtexcommercestable.com.br";
+    const rf = createResilientFetch(underlying as unknown as typeof fetch, {
+      maxRetries: 0,
+      breakerConsecutiveFailures: 3,
+    });
+
+    // Abort 5 caller requests (> the 3-failure threshold). If these counted as
+    // breaker failures, the circuit would open against a healthy upstream.
+    for (let i = 0; i < 5; i++) {
+      const ac = new AbortController();
+      const p = rf(`${host}/x`, { signal: ac.signal });
+      p.catch(() => {});
+      ac.abort();
+      await expect(p).rejects.toThrow();
+    }
+
+    // Breaker must still be CLOSED: a healthy call succeeds (not VtexCircuitOpenError).
+    const healthy = createResilientFetch((async () => res(200)) as unknown as typeof fetch);
+    const r = await healthy(`${host}/x`);
+    expect(r.status).toBe(200);
+  });
+
+  it("honors the kill-switch env var", async () => {
+    const prev = process.env.VTEX_RESILIENCE_DISABLED;
+    process.env.VTEX_RESILIENCE_DISABLED = "true";
+    try {
+      const underlying = vi.fn(async () => res(200));
+      const rf = createResilientFetch(underlying as unknown as typeof fetch);
+      await rf("https://acct.vtexcommercestable.com.br/x", { method: "POST", body: "y" });
+      expect(underlying).toHaveBeenCalledOnce();
+    } finally {
+      if (prev === undefined) delete process.env.VTEX_RESILIENCE_DISABLED;
+      else process.env.VTEX_RESILIENCE_DISABLED = prev;
+    }
+  });
+});
+
+describe("isNonRetryableVtexError", () => {
+  it("flags circuit-open and timeout errors, not generic ones", () => {
+    expect(isNonRetryableVtexError(new VtexCircuitOpenError("h"))).toBe(true);
+    expect(isNonRetryableVtexError(new VtexTimeoutError("h", 1))).toBe(true);
+    expect(isNonRetryableVtexError(new Error("boom"))).toBe(false);
+    expect(isNonRetryableVtexError(null)).toBe(false);
+  });
+});

package/src/utils/cartProjection.ts

@@ -0,0 +1,96 @@
+/**
+ * Project a VTEX OrderForm down to a requested `CartProjection`.
+ *
+ * The VTEX checkout API always returns the whole OrderForm from mutation
+ * endpoints (bounded only by `expectedOrderFormSections`) — there is no
+ * delta/patch response. So "return the minimum" is enforced **server-side**:
+ * we take whatever VTEX gave us and shape it into `none` / `summary` /
+ * `summary+items` / `minicart` / `raw` before it reaches the browser.
+ *
+ * Pure function — no I/O, fully unit-testable. All monetary values in the
+ * projected output are in major units (VTEX is cents).
+ *
+ * @see `@decocms/apps-commerce/types/cart` for the agnostic contract.
+ */
+
+import type {
+  CartItemSlim,
+  CartOk,
+  CartProjection,
+  CartSummary,
+  CartSummaryWithItems,
+  Minicart,
+} from "@decocms/apps-commerce/types";
+import type { OrderForm, OrderFormItem } from "../types";
+import { type VtexOrderFormToMinicartOptions, vtexOrderFormToMinicart } from "./minicart";
+
+const CENTS_PER_MAJOR = 100;
+
+function fromCents(cents: number | undefined | null): number {
+  if (cents == null || !Number.isFinite(cents)) return 0;
+  return cents / CENTS_PER_MAJOR;
+}
+
+/** Sum of line quantities. */
+function countItems(orderForm: OrderForm): number {
+  return (orderForm.items ?? []).reduce((sum, i) => sum + (i.quantity ?? 0), 0);
+}
+
+function toSummary(orderForm: OrderForm): CartSummary {
+  return {
+    orderFormId: orderForm.orderFormId ?? null,
+    totalItems: countItems(orderForm),
+    total: fromCents(orderForm.value),
+  };
+}
+
+/** Map a VTEX line to the slim, analytics-compatible `CartItemSlim`. */
+function toSlimItem(item: OrderFormItem): CartItemSlim {
+  return {
+    item_id: item.id,
+    item_name: item.name ?? item.skuName ?? "",
+    item_variant: item.skuName,
+    image: item.imageUrl?.replace(/^http:/, "https:") ?? "",
+    price: fromCents(item.sellingPrice ?? item.price),
+    quantity: item.quantity,
+  };
+}
+
+export type ProjectOrderFormOptions = VtexOrderFormToMinicartOptions;
+
+/** The projected result type, with VTEX-concrete `minicart`/`raw` payloads. */
+export type VtexCartProjectionResult =
+  | CartOk
+  | CartSummary
+  | CartSummaryWithItems
+  | Minicart<OrderForm>
+  | OrderForm;
+
+/**
+ * Shape a VTEX OrderForm into the requested projection.
+ *
+ * @param orderForm - Raw OrderForm from a VTEX checkout call.
+ * @param projection - Desired client-facing shape.
+ * @param opts - Storefront overrides forwarded to the `minicart` projection.
+ */
+export function projectOrderForm(
+  orderForm: OrderForm,
+  projection: CartProjection,
+  opts: ProjectOrderFormOptions = {},
+): VtexCartProjectionResult {
+  switch (projection) {
+    case "none":
+      return { ok: true };
+    case "summary":
+      return toSummary(orderForm);
+    case "summary+items":
+      return {
+        ...toSummary(orderForm),
+        items: (orderForm.items ?? []).map(toSlimItem),
+      };
+    case "minicart":
+      return vtexOrderFormToMinicart(orderForm, opts);
+    case "raw":
+      return orderForm;
+  }
+}

package/src/utils/constants.ts

@@ -0,0 +1,98 @@
+/**
+ * Tuning knobs for the VTEX fetch resilience + cache layer.
+ *
+ * Every timeout, limit, and threshold that governs how `resilience.ts`
+ * (abort/timeout, circuit breaker, retry budget) and `fetchCache.ts` (SWR +
+ * stale-if-error) behave under VTEX slowness/outages lives HERE, in one file,
+ * with the reasoning for each number next to it. Auditing or tuning the
+ * resilience posture means reading one file, not hunting across two.
+ */
+
+// ---------------------------------------------------------------------------
+// fetchCache.ts — SWR + stale-if-error cache for VTEX GET responses
+// ---------------------------------------------------------------------------
+
+/** Max distinct cache keys kept in memory; oldest `createdAt` evicted first. */
+export const FETCH_CACHE_MAX_ENTRIES = 500;
+
+/**
+ * How long a cached response is considered FRESH, keyed by status class.
+ * Past this the entry is stale — served via SWR (2xx) while a background
+ * refresh runs, or treated as expired (404/5xx). See `ttlForStatus` in
+ * `fetchCache.ts`.
+ */
+export const FETCH_CACHE_FRESH_TTL_MS = {
+  /** 2xx — 3 min. Catalog/price data doesn't need to be second-fresh. */
+  success: 180_000,
+  /** 404 — 10s. Short on purpose: a just-published SKU shouldn't 404 long. */
+  notFound: 10_000,
+  /** 5xx — never "fresh". A server error is never treated as a good cache hit. */
+  serverError: 0,
+} as const;
+
+/**
+ * Stale-if-error window: how long PAST the freshness TTL a last-good 2xx entry
+ * may still be served when the origin is failing (5xx / timeout / circuit
+ * open). This is the "availability first" knob — a warm key survives a full
+ * VTEX outage for up to this long with zero upstream pressure; once an entry
+ * is older than `freshTtl + this`, it's considered too stale to serve and the
+ * error surfaces (→ the degraded / branded-error path takes over). Mirrors the
+ * edge `sie` window sites configure for the product/listing cache profiles.
+ */
+export const FETCH_CACHE_STALE_IF_ERROR_MS = 86_400_000; // 24h
+
+/**
+ * Inflight-slot backstop timeout. Bounds how long a single hung `fetch()` can
+ * hold a dedup 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).
+ *
+ * MUST stay ABOVE `RESILIENCE_CONFIG.totalTimeoutMs` (see below) — the
+ * resilient fetch already owns real per-call abort/timeout, so this is only a
+ * last-resort backstop. If it fired first it would kill a slow-but-recoverable
+ * response the resilience layer was about to deliver, discard the good body
+ * (it never reaches the cache), and free the dedup slot early so a concurrent
+ * request launches a duplicate upstream fetch.
+ */
+export const FETCH_CACHE_INFLIGHT_BACKSTOP_MS = 15_000;
+
+// ---------------------------------------------------------------------------
+// resilience.ts — abort/timeout, retry budget, circuit breaker
+// ---------------------------------------------------------------------------
+
+export interface ResilienceConfig {
+  /** Per-attempt timeout in ms. Aborts the socket. */
+  perAttemptTimeoutMs: number;
+  /** Total time budget across all attempts (incl. backoff) in ms. */
+  totalTimeoutMs: number;
+  /** Max retries for idempotent requests (attempts = maxRetries + 1). */
+  maxRetries: number;
+  /** Exponential backoff base in ms. */
+  backoffBaseMs: number;
+  /** Exponential backoff cap in ms. */
+  backoffCapMs: number;
+  /** Consecutive failures before the breaker opens. */
+  breakerConsecutiveFailures: number;
+  /** How long the breaker stays open before half-opening, in ms. */
+  breakerOpenCooldownMs: number;
+  /** Number of probe requests allowed while half-open. */
+  breakerHalfOpenProbes: number;
+  /** Max retry tokens per host (token bucket). */
+  retryBudgetMax: number;
+  /** Token refill rate per second. */
+  retryBudgetRefillPerSec: number;
+}
+
+export const DEFAULT_RESILIENCE_CONFIG: ResilienceConfig = {
+  perAttemptTimeoutMs: 8_000,
+  totalTimeoutMs: 12_000,
+  maxRetries: 2,
+  backoffBaseMs: 150,
+  backoffCapMs: 1_000,
+  breakerConsecutiveFailures: 5,
+  breakerOpenCooldownMs: 5_000,
+  breakerHalfOpenProbes: 3,
+  retryBudgetMax: 20,
+  retryBudgetRefillPerSec: 5,
+};