@decocms/blocks 7.31.7 → 7.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.31.7",
+  "version": "7.32.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -53,6 +53,7 @@
     "./sdk/djb2": "./src/sdk/djb2.ts",
     "./sdk/encoding": "./src/sdk/encoding.ts",
     "./sdk/env": "./src/sdk/env.ts",
+    "./sdk/fetchCache": "./src/sdk/fetchCache.ts",
     "./sdk/flags": "./src/sdk/flags.ts",
     "./sdk/http": "./src/sdk/http.ts",
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",

package/src/middleware/observability.test.ts

@@ -156,9 +156,9 @@ describe("recordCacheMetric — cache_layer label", () => {
     expect(counters).toHaveLength(1);
     expect(counters[0]?.name).toBe(MetricNames.CACHE_REQUESTS);
     expect(counters[0]?.labels).toMatchObject({
-      "deco.cache.profile": "product",
-      "deco.cache.status": "HIT",
-      "deco.cache.layer": "edge",
+      "profile": "product",
+      "status": "HIT",
+      "layer": "edge",
     });
   });
 
@@ -169,7 +169,7 @@ describe("recordCacheMetric — cache_layer label", () => {
     recordCacheMetric(false, "search", "MISS", "edge");
 
     expect(counters[0]?.name).toBe(MetricNames.CACHE_REQUESTS);
-    expect(counters[0]?.labels?.["deco.cache.status"]).toBe("MISS");
+    expect(counters[0]?.labels?.["status"]).toBe("MISS");
   });
 
   it("supports the legacy 3-arg signature for backward compat", () => {
@@ -179,20 +179,36 @@ describe("recordCacheMetric — cache_layer label", () => {
     recordCacheMetric(true, "static");
 
     expect(counters[0]?.labels).toEqual({
-      "deco.cache.status": "HIT",
-      "deco.cache.profile": "static",
+      "status": "HIT",
+      "profile": "static",
     });
   });
 
-  it("distinguishes cachedLoader vs edge vs vtex-swr layers", () => {
+  it("distinguishes cachedLoader vs edge vs swr layers", () => {
     const { adapter, counters } = captureMeter();
     configureMeter(adapter);
 
     recordCacheMetric(true, "loader-x", "HIT", "cachedLoader");
-    recordCacheMetric(true, "vtex-product", "HIT", "vtex-swr");
+    recordCacheMetric(true, undefined, "HIT", "swr", "vtex");
+
+    expect(counters[0]?.labels?.["layer"]).toBe("cachedLoader");
+    expect(counters[1]?.labels?.["layer"]).toBe("swr");
+  });
 
-    expect(counters[0]?.labels?.["deco.cache.layer"]).toBe("cachedLoader");
-    expect(counters[1]?.labels?.["deco.cache.layer"]).toBe("vtex-swr");
+  it("keeps provider (swr backend) on a separate label from profile (edge page-type)", () => {
+    const { adapter, counters } = captureMeter();
+    configureMeter(adapter);
+
+    // edge: profile carries the page-type; no provider.
+    recordCacheMetric(true, "product", "HIT", "edge");
+    // swr: provider carries the backend; profile left unset so a
+    // `sum by (profile)` panel never blends page-types with backend names.
+    recordCacheMetric(true, undefined, "HIT", "swr", "magento");
+
+    expect(counters[0]?.labels?.["profile"]).toBe("product");
+    expect(counters[0]?.labels?.["provider"]).toBeUndefined();
+    expect(counters[1]?.labels?.["profile"]).toBeUndefined();
+    expect(counters[1]?.labels?.["provider"]).toBe("magento");
   });
 });
 

package/src/middleware/observability.ts

@@ -263,6 +263,8 @@ export const MetricNames = {
   // Single cache counter dimensioned by `deco.cache.status` — follows the OTel
   // semconv pattern (cf. nfs.server.repcache.requests + .status). deco-cx/deco
   // uses the same name so both frameworks aggregate together.
+  // Labels on this counter use short keys (status/profile/layer/provider) —
+  // the metric name already provides the deco.cache.* namespace.
   CACHE_REQUESTS: "deco.cache.requests",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
@@ -288,7 +290,7 @@ export const METRIC_METADATA: Record<string, { description: string; unit: string
     unit: "s",
   },
   [MetricNames.CACHE_REQUESTS]: {
-    description: "Cache lookups, dimensioned by deco.cache.status (hit/stale/miss/bypass).",
+    description: "Cache lookups, dimensioned by status (hit/stale/miss/bypass).",
     unit: "{request}",
   },
   [MetricNames.RESOLVE_DURATION]: {
@@ -398,7 +400,7 @@ export function recordRequestMetric(
   //   - `status_class`: 5-element enum (2xx / 3xx / 4xx / 5xx / unknown).
   //   - `outcome`: CF outcome enum (~7 values).
   //   - `cache_decision`: 5-element enum.
-  //   - `cache_layer`: 3-element enum (edge / cachedLoader / vtex-swr).
+  //   - `cache_layer`: 3-element enum (edge / cachedLoader / swr).
   //   - `region`: ~250 CF colo codes worldwide.
   // Total combinations are bounded — safe for unbounded series on
   // ClickHouse but operators should still avoid grouping by `region`
@@ -457,10 +459,15 @@ export type CacheDecision = "HIT" | "STALE-HIT" | "STALE-ERROR" | "MISS" | "BYPA
  *  - `edge`         — Cloudflare Cache API (HTML pages, server-fn responses)
  *  - `cachedLoader` — In-memory per-isolate via `sdk/cachedLoader.ts`
  *                     (loader-level SWR, dedup, in-flight)
- *  - `vtex-swr`     — Apps-side in-memory cache shared by VTEX clients
- *                     (intelligent-search, cross-selling, etc.)
+ *  - `swr`          — Apps-side in-memory SWR fetch cache shared by commerce
+ *                     clients (VTEX intelligent-search, Magento GraphQL,
+ *                     Shopify, etc.) via `sdk/fetchCache.ts`. Provider-agnostic;
+ *                     the specific backend rides on `deco.cache.provider`
+ *                     (e.g. `vtex` / `magento` / `shopify`), a separate label
+ *                     from `deco.cache.profile` (page-type, set by `edge`).
+ *                     Renamed from the old `vtex-swr` once the util was shared.
  */
-export type CacheLayer = "edge" | "cachedLoader" | "vtex-swr";
+export type CacheLayer = "edge" | "cachedLoader" | "swr";
 
 /**
  * Record a cache hit/miss metric. Also stamps the decision on the active
@@ -471,18 +478,28 @@ export type CacheLayer = "edge" | "cachedLoader" | "vtex-swr";
  * Backward-compatible signature:
  *   recordCacheMetric(hit, profile?, decision?)
  *   recordCacheMetric(hit, profile?, decision?, layer?)
+ *   recordCacheMetric(hit, profile?, decision?, layer?, provider?)
  *
  * `decision` is optional — when omitted, the metric still records HIT
  * vs MISS but dashboards can't distinguish SWR/SIE paths. Pass it
  * whenever known. `layer` defaults to `edge` when called from
- * workerEntry; cachedLoader / vtex-swr call sites should pass their
+ * workerEntry; cachedLoader / swr call sites should pass their
  * value explicitly.
+ *
+ * `profile` and `provider` are DISTINCT dimensions and must not be
+ * conflated: `profile` is the page/route type (`product` / `listing` /
+ * `search`, set by the `edge` layer) or loader name (`cachedLoader`);
+ * `provider` is the commerce backend (`vtex` / `magento` / `shopify`, set
+ * by the `swr` layer). Keeping them on separate labels means a
+ * `sum by (profile)` panel never blends page-types with backend
+ * names. The `swr` layer passes `provider` and leaves `profile` unset.
  */
 export function recordCacheMetric(
   hit: boolean,
   profile?: string,
   decision?: CacheDecision,
   layer?: CacheLayer,
+  provider?: string,
 ) {
   // Stamp on the active span FIRST so the attribute survives even if the
   // meter is a no-op (e.g. on tests, or in dev without DECO_METRICS).
@@ -491,19 +508,21 @@ export function recordCacheMetric(
     if (decision) active.setAttribute?.("deco.cache.status", decision);
     if (profile) active.setAttribute?.("deco.cache.profile", profile);
     if (layer) active.setAttribute?.("deco.cache.layer", layer);
+    if (provider) active.setAttribute?.("deco.cache.provider", provider);
   }
 
   const m = getState().meter;
   if (!m) return;
-  // Single counter dimensioned by deco.cache.status — unified with deco-cx/deco
-  // (follows the semconv nfs.server.repcache.requests + .status pattern). status
-  // is the decision when known (HIT/STALE-HIT/STALE-ERROR/MISS/BYPASS), else the
-  // hit boolean. Same key on span + metric.
+  // Single counter dimensioned by status — the metric name deco.cache.requests
+  // already scopes the label, so the deco.cache. prefix is redundant on labels.
+  // Span attribute keeps the full deco.cache.status key (spans mix attrs from
+  // many sources, so the namespace is needed there).
   const labels: Labels = {
-    "deco.cache.status": decision ?? (hit ? "HIT" : "MISS"),
+    status: decision ?? (hit ? "HIT" : "MISS"),
   };
-  if (profile) labels["deco.cache.profile"] = profile;
-  if (layer) labels["deco.cache.layer"] = layer;
+  if (profile) labels["profile"] = profile;
+  if (layer) labels["layer"] = layer;
+  if (provider) labels["provider"] = provider;
   m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
 }
 

package/src/sdk/fetchCache.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Coverage for the shared SWR fetch cache — both the caching semantics
+ * (fresh HIT / dedup / SWR stale-serve / cold MISS) AND the telemetry it now
+ * emits (`deco.cache.requests` with `layer: "swr"` + `profile: <provider>`).
+ * The whole point of this module is that instrumentation is automatic, so the
+ * metric assertions are as load-bearing as the behavioral ones.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMeter, type MeterAdapter } from "../middleware/observability";
+import { createFetchCache } from "./fetchCache";
+
+interface Counter {
+  name: string;
+  value: number;
+  labels?: Record<string, unknown>;
+}
+
+function captureMeter(): { adapter: MeterAdapter; counters: Counter[] } {
+  const counters: Counter[] = [];
+  const adapter: MeterAdapter = {
+    counterInc(name, value, labels) {
+      counters.push({ name, value: value ?? 1, labels });
+    },
+    histogramRecord() {},
+  };
+  return { adapter, counters };
+}
+
+const KNOBS = {
+  maxEntries: 100,
+  freshTtlMs: { success: 1000, notFound: 500, serverError: 0 },
+  staleIfErrorMs: 10_000,
+  inflightBackstopMs: 15_000,
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+let counters: Counter[];
+
+beforeEach(() => {
+  const cap = captureMeter();
+  counters = cap.counters;
+  configureMeter(cap.adapter);
+});
+
+afterEach(() => {
+  configureMeter({ counterInc: () => {} });
+  vi.useRealTimers();
+});
+
+const statuses = () =>
+  counters
+    .filter((c) => c.name === "deco.cache.requests")
+    .map((c) => c.labels?.["status"]);
+
+describe("createFetchCache — behavior", () => {
+  it("cold call is a MISS, second call is a HIT with the cached body", async () => {
+    const cache = createFetchCache({ provider: "vtex", ...KNOBS });
+    let calls = 0;
+    const doFetch = () => {
+      calls++;
+      return Promise.resolve(jsonResponse({ ok: true }));
+    };
+
+    const a = await cache.fetchWithCache("k", doFetch);
+    const b = await cache.fetchWithCache("k", doFetch);
+
+    expect(a).toEqual({ ok: true });
+    expect(b).toEqual({ ok: true });
+    expect(calls).toBe(1); // second served from cache
+    expect(statuses()).toEqual(["MISS", "HIT"]);
+  });
+
+  it("dedups concurrent calls for the same key (one upstream, join = HIT)", async () => {
+    const cache = createFetchCache({ provider: "vtex", ...KNOBS });
+    let resolve!: (r: Response) => void;
+    let calls = 0;
+    const doFetch = () => {
+      calls++;
+      return new Promise<Response>((r) => {
+        resolve = r;
+      });
+    };
+
+    const p1 = cache.fetchWithCache("k", doFetch);
+    const p2 = cache.fetchWithCache("k", doFetch);
+    resolve(jsonResponse({ n: 1 }));
+    const [a, b] = await Promise.all([p1, p2]);
+
+    expect(a).toEqual({ n: 1 });
+    expect(b).toEqual({ n: 1 });
+    expect(calls).toBe(1); // only one upstream call
+    expect(statuses()).toEqual(["MISS", "HIT"]);
+  });
+
+  it("serves stale within the SIE window (STALE-HIT) and revalidates in background", async () => {
+    vi.useFakeTimers();
+    const cache = createFetchCache({ provider: "vtex", ...KNOBS });
+    let calls = 0;
+    const doFetch = () => {
+      calls++;
+      return Promise.resolve(jsonResponse({ v: calls }));
+    };
+
+    await cache.fetchWithCache("k", doFetch); // MISS, caches { v: 1 }
+    vi.setSystemTime(Date.now() + 1500); // past 1000ms fresh TTL, within SIE
+
+    const stale = await cache.fetchWithCache("k", doFetch); // serves last-good
+    expect(stale).toEqual({ v: 1 }); // stale body returned synchronously
+    await vi.runAllTimersAsync(); // let background refresh settle
+
+    expect(statuses()).toEqual(["MISS", "STALE-HIT"]);
+    expect(calls).toBe(2); // background refresh ran
+  });
+
+  it("past the SIE window the entry is dropped and refetched (MISS again)", async () => {
+    vi.useFakeTimers();
+    const cache = createFetchCache({ provider: "vtex", ...KNOBS });
+    const doFetch = () => Promise.resolve(jsonResponse({ ok: 1 }));
+
+    await cache.fetchWithCache("k", doFetch); // MISS
+    vi.setSystemTime(Date.now() + 1000 + 10_000 + 1); // past fresh + SIE
+    await cache.fetchWithCache("k", doFetch); // too stale -> cold MISS
+
+    expect(statuses()).toEqual(["MISS", "MISS"]);
+  });
+
+  it("isolates providers — distinct instances never share entries", async () => {
+    const vtex = createFetchCache({ provider: "vtex", ...KNOBS });
+    const magento = createFetchCache({ provider: "magento", ...KNOBS });
+    await vtex.fetchWithCache("k", () => Promise.resolve(jsonResponse({ p: "vtex" })));
+    const fromMagento = await magento.fetchWithCache("k", () =>
+      Promise.resolve(jsonResponse({ p: "magento" })),
+    );
+    expect(fromMagento).toEqual({ p: "magento" }); // magento MISS, not vtex's entry
+  });
+});
+
+describe("createFetchCache — telemetry labels", () => {
+  it("stamps layer=swr and provider=<provider> on every emit (profile stays unset)", async () => {
+    const cache = createFetchCache({ provider: "magento", ...KNOBS });
+    await cache.fetchWithCache("k", () => Promise.resolve(jsonResponse({})));
+    const emitted = counters.filter((c) => c.name === "deco.cache.requests");
+    expect(emitted.length).toBe(1);
+    expect(emitted[0]?.labels?.["layer"]).toBe("swr");
+    expect(emitted[0]?.labels?.["provider"]).toBe("magento");
+    // profile is reserved for the edge layer's page-type — must NOT be set here.
+    expect(emitted[0]?.labels?.["profile"]).toBeUndefined();
+    expect(emitted[0]?.labels?.["status"]).toBe("MISS");
+  });
+
+  it("is a no-op with no meter configured (never throws)", async () => {
+    configureMeter({ counterInc: () => {} });
+    const cache = createFetchCache({ provider: "vtex", ...KNOBS });
+    await expect(
+      cache.fetchWithCache("k", () => Promise.resolve(jsonResponse({}))),
+    ).resolves.toEqual({});
+  });
+});

package/src/sdk/fetchCache.ts

@@ -0,0 +1,266 @@
+/**
+ * Shared SWR in-memory fetch cache for commerce API responses.
+ *
+ * Provides in-flight deduplication + stale-while-revalidate + stale-if-error
+ * for server-side GET requests, keyed by full URL string. Ported from the
+ * VTEX app's `fetchCache.ts` (itself inspired by deco-cx/deco
+ * `runtime/fetch/fetchCache.ts`) and generalized so every commerce app
+ * (VTEX, Magento, Shopify, ...) shares ONE implementation instead of each
+ * rolling its own uninstrumented copy.
+ *
+ * **Why this lives in `@decocms/blocks/sdk` (the chokepoint):** cache hit/miss
+ * telemetry only becomes automatic when a single shared util emits it. Each
+ * cache instance calls {@link recordCacheMetric} with `layer: "swr"` on every
+ * decision branch, so any app that routes upstream GETs through
+ * {@link createFetchCache} lands hit/miss/stale in ClickHouse for free — no
+ * per-app wiring. The metric is a no-op when no meter is configured (dev,
+ * tests), so there is zero cost off the instrumented path.
+ *
+ * **Provider isolation:** every {@link createFetchCache} call owns its own
+ * `store`/`inflight` Maps, so VTEX / Magento / Shopify caches never collide in
+ * a shared isolate. The `provider` string rides on the `provider` metric label so
+ * dashboards can slice hit ratio per backend.
+ *
+ * Note on why the SWR cache — not `createInstrumentedFetch` — must emit the
+ * hit/miss counter: on a HIT the cache returns BEFORE invoking `doFetch`, so
+ * the instrumented fetch (and its `http.client.request.duration` histogram)
+ * never runs. Hit ratio can only be measured here.
+ */
+
+import { type CacheDecision, recordCacheMetric } from "../middleware/observability";
+
+/** Fresh-TTL (ms) by HTTP status class. See {@link FetchCacheConfig}. */
+export interface FreshTtlByStatus {
+  /** 2xx — how long a success body stays fresh. */
+  success: number;
+  /** 404 — how long a not-found stays fresh (kept short on purpose). */
+  notFound: number;
+  /** 5xx — a server error is never treated as a good cache hit (use 0). */
+  serverError: number;
+}
+
+export interface FetchCacheConfig {
+  /**
+   * Backend name — `vtex` / `magento` / `shopify` / ... Emitted as
+   * `deco.cache.profile` on the `deco.cache.requests` metric so dashboards can
+   * break down SWR hit ratio per provider. Also namespaces the instance's
+   * in-memory Maps (each instance is already isolated, but this keeps the
+   * telemetry label meaningful).
+   */
+  provider: string;
+  /** Max distinct cache keys kept in memory; oldest `createdAt` evicted first. */
+  maxEntries: number;
+  /** Fresh-TTL (ms) by status class. */
+  freshTtlMs: FreshTtlByStatus;
+  /**
+   * Stale-if-error window (ms): how long PAST the freshness TTL a last-good 2xx
+   * entry may still be served while the origin is failing. Set to 0 to disable
+   * stale serving.
+   */
+  staleIfErrorMs: number;
+  /**
+   * Inflight-slot backstop timeout (ms). Bounds how long a single hung
+   * `fetch()` can hold a dedup entry alive. MUST stay ABOVE any per-call
+   * timeout the underlying fetch owns — this is a last-resort leak backstop,
+   * not the primary timeout.
+   */
+  inflightBackstopMs: number;
+}
+
+interface CacheEntry {
+  body: unknown;
+  status: number;
+  createdAt: number;
+  refreshing: boolean;
+}
+
+export interface FetchCacheOptions {
+  /** Custom fresh TTL in ms. If provided, overrides status-based TTL. */
+  ttl?: number;
+  /**
+   * Stale-if-error window in ms for this call. Defaults to the instance's
+   * {@link FetchCacheConfig.staleIfErrorMs}. Set to 0 to disable stale serving.
+   */
+  sieMs?: number;
+}
+
+export interface FetchCache {
+  /**
+   * Wrap a GET fetch call with SWR caching + in-flight dedup. Returns the
+   * parsed JSON body, or `null` for cacheable non-2xx responses (e.g. 404).
+   * 5xx responses throw so the caller can handle them explicitly.
+   */
+  fetchWithCache<T>(
+    cacheKey: string,
+    doFetch: () => Promise<Response>,
+    opts?: FetchCacheOptions,
+  ): Promise<T | null>;
+  /** Drop all entries + inflight slots (mainly for tests). */
+  clear(): void;
+  /** Diagnostics: current entry / inflight counts. */
+  getStats(): { entries: number; inflight: number };
+}
+
+/**
+ * Race a Promise against a timeout so callers' `.finally()` always runs.
+ * Critical for evicting the inflight Map entry when a `fetch()` hangs —
+ * without this, a never-settling Promise leaks the Map slot forever and 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);
+  });
+}
+
+/**
+ * Create an isolated SWR fetch cache instance for one provider.
+ *
+ * @example
+ * const cache = createFetchCache({ provider: "vtex", ...VTEX_KNOBS });
+ * const body = await cache.fetchWithCache(url, () => fetch(url));
+ */
+export function createFetchCache(config: FetchCacheConfig): FetchCache {
+  const { provider, maxEntries, freshTtlMs, staleIfErrorMs, inflightBackstopMs } = config;
+
+  const store = new Map<string, CacheEntry>();
+  const inflight = new Map<string, Promise<CacheEntry>>();
+
+  function freshTtlForStatus(status: number): number {
+    if (status >= 200 && status < 300) return freshTtlMs.success;
+    if (status === 404) return freshTtlMs.notFound;
+    if (status >= 500) return freshTtlMs.serverError;
+    return 0;
+  }
+
+  function evictIfNeeded() {
+    // ponytail: Map preserves insertion order ≈ createdAt order — holds as long
+    // as updates always re-insert via store.set(key, fresh), never mutate in-place.
+    while (store.size > maxEntries) store.delete(store.keys().next().value!);
+  }
+
+  // Single attempt on purpose — the underlying fetch (resilience layer) owns
+  // retries/backoff/breaker. Retrying here would multiply upstream calls and
+  // re-enter the breaker too fast.
+  async function executeFetch(url: string, doFetch: () => Promise<Response>): Promise<CacheEntry> {
+    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 };
+  }
+
+  function emit(decision: CacheDecision) {
+    // `hit` is true for every branch that avoids a foreground upstream fetch
+    // (fresh, dedup-join, stale-serve); MISS is the only non-hit. The backend
+    // rides on the dedicated `provider` label (NOT `profile`, which the edge
+    // layer reserves for page-type) so dashboards don't blend the two.
+    recordCacheMetric(decision !== "MISS", undefined, decision, "swr", provider);
+  }
+
+  function fetchWithCache<T>(
+    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 ?? freshTtlForStatus(entry.status);
+      const age = now - entry.createdAt;
+      const isStale = age > maxAge;
+
+      if (!isStale) {
+        emit("HIT");
+        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, counted as MISS there). On a healthy origin this is
+      // never reached because the background refresh keeps resetting createdAt.
+      const sieMs = opts?.sieMs ?? staleIfErrorMs;
+      const tooStale = age > maxAge + sieMs;
+
+      if (!tooStale) {
+        if (!entry.refreshing) {
+          entry.refreshing = true;
+          // Background refresh: no retry — stale data is already being served.
+          withTimeout(
+            executeFetch(cacheKey, doFetch),
+            inflightBackstopMs,
+            `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 within the SIE window: this is the stale-while-
+        // revalidate serve.
+        emit("STALE-HIT");
+        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) {
+      // Joined an in-flight upstream fetch — no upstream call of our own.
+      emit("HIT");
+      return existing.then((e) => e.body as T | null);
+    }
+
+    // Cold miss: run the loader. Wrap with a timeout so `.finally()` always
+    // evicts the inflight slot even if `executeFetch` never settles.
+    emit("MISS");
+    const promise = withTimeout(
+      executeFetch(cacheKey, doFetch),
+      inflightBackstopMs,
+      `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);
+  }
+
+  return {
+    fetchWithCache,
+    clear() {
+      store.clear();
+      inflight.clear();
+    },
+    getStats() {
+      return { entries: store.size, inflight: inflight.size };
+    },
+  };
+}

package/src/sdk/urlUtils.ts

@@ -118,6 +118,23 @@ export function canonicalUrl(request: Request, baseUrl?: string): string {
   return `${origin}${path}`;
 }
 
+/**
+ * Extract the pathname from an absolute or relative URL, stripping query
+ * string and hash. Falls back to manual slicing when `new URL()` would
+ * throw (relative URL without a base). Used by operation routers that
+ * need to match against URL structure without caring about the host.
+ */
+export function extractPathname(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    const qs = url.indexOf("?");
+    const hash = url.indexOf("#");
+    const end = [qs, hash].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+    return end === undefined ? url : url.slice(0, end);
+  }
+}
+
 /**
  * Check if a URL has any tracking/UTM parameters.
  */