@decocms/blocks 7.63.1 → 7.64.1

package/src/sdk/cacheStorage.ts

@@ -0,0 +1,287 @@
+import { RequestContext } from "./requestContext";
+
+/** Storage only. Values are serialized by the caller; expiration is absolute epoch ms. */
+export interface CacheStorage {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, expiresAt: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export interface CacheStorageContext {
+  storage: CacheStorage | null;
+  /** Include site, deployment and content revision. Never use a tenant-wide global binding. */
+  scope: string;
+  /** Bypass both memory and shared storage for previews or private requests. */
+  disabled?: boolean;
+  waitUntil?: (work: Promise<unknown>) => void;
+}
+
+const BAG_KEY = "deco:cache-storage";
+
+export function bindCacheStorage(context: CacheStorageContext): void {
+  RequestContext.setBag(BAG_KEY, context);
+}
+
+export function getCacheStorageContext(): CacheStorageContext | undefined {
+  return RequestContext.getBag<CacheStorageContext>(BAG_KEY);
+}
+
+/** Keep optional cache work alive on Workers, without letting storage errors fail a request. */
+export function cacheBackground(work: Promise<unknown>): void {
+  const safe = work.catch(() => {});
+  getCacheStorageContext()?.waitUntil?.(safe);
+}
+
+export async function hashCacheKey(key: string): Promise<string> {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+  return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+interface StoredValue {
+  value: string;
+  expiresAt: number;
+}
+
+function decode(raw: string | null): string | null {
+  if (raw === null) return null;
+  try {
+    const entry = JSON.parse(raw) as StoredValue;
+    return typeof entry.value === "string" &&
+      Number.isFinite(entry.expiresAt) &&
+      Date.now() < entry.expiresAt
+      ? entry.value
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Bounded LRU adapter, useful in Node, development and tests. */
+export function createMemoryCacheStorage(maxBytes = 32 * 1024 * 1024): CacheStorage {
+  const entries = new Map<string, string>();
+  let bytes = 0;
+  function remove(key: string) {
+    const old = entries.get(key);
+    if (old !== undefined) bytes -= (key.length + old.length) * 2;
+    entries.delete(key);
+  }
+  return {
+    async get(key) {
+      const raw = entries.get(key);
+      const value = decode(raw ?? null);
+      if (value === null) remove(key);
+      else {
+        entries.delete(key);
+        entries.set(key, raw!);
+      }
+      return value;
+    },
+    async set(key, value, expiresAt) {
+      remove(key);
+      if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return;
+      const raw = JSON.stringify({ value, expiresAt });
+      const size = (key.length + raw.length) * 2;
+      if (size > maxBytes) return;
+      entries.set(key, raw);
+      bytes += size;
+      while (bytes > maxBytes) remove(entries.keys().next().value!);
+    },
+    async delete(key) {
+      remove(key);
+    },
+  };
+}
+
+/** Structural binding type; the core has no Cloudflare package dependency. */
+export interface CacheKVNamespace {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options: { expirationTtl: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export function createKVCacheStorage(
+  kv: CacheKVNamespace,
+  prefix = "deco-cache:v1:",
+): CacheStorage {
+  const keyFor = async (key: string) => prefix + (await hashCacheKey(key));
+  return {
+    async get(key) {
+      return decode(await kv.get(await keyFor(key)));
+    },
+    async set(key, value, expiresAt) {
+      if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return;
+      const raw = JSON.stringify({ value, expiresAt });
+      // Leave space below KV's 25 MiB value limit. Oversized cache entries are optional.
+      if (new TextEncoder().encode(raw).byteLength > 25 * 1024 * 1024) return;
+      await kv.put(await keyFor(key), raw, {
+        expirationTtl: Math.max(60, Math.ceil((expiresAt - Date.now()) / 1000)),
+      });
+    },
+    async delete(key) {
+      await kv.delete(await keyFor(key));
+    },
+  };
+}
+
+/** The app supplies the native cache and its origin; no global API detection in consumers. */
+export function createWebCacheStorage(
+  cache: Pick<Cache, "match" | "put" | "delete">,
+  origin: string,
+): CacheStorage {
+  const requestFor = async (key: string) =>
+    new Request(new URL(`/__deco_cache/${await hashCacheKey(key)}`, origin));
+  return {
+    async get(key) {
+      const response = await cache.match(await requestFor(key));
+      return decode(response ? await response.text() : null);
+    },
+    async set(key, value, expiresAt) {
+      if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) return;
+      await cache.put(
+        await requestFor(key),
+        new Response(JSON.stringify({ value, expiresAt }), {
+          headers: {
+            "Cache-Control": `public, max-age=${Math.max(1, Math.ceil((expiresAt - Date.now()) / 1000))}`,
+          },
+        }),
+      );
+    },
+    async delete(key) {
+      await cache.delete(await requestFor(key));
+    },
+  };
+}
+
+/** Reject values JSON would silently change, including dates, functions and circular references. */
+function serialize(value: unknown): string | undefined {
+  const seen = new Set<object>();
+  function check(v: unknown): void {
+    if (v === null || typeof v === "string" || typeof v === "boolean") return;
+    if (typeof v === "number" && Number.isFinite(v)) return;
+    // Optional object fields are common in section props. JSON omits them safely.
+    if (v === undefined) return;
+    if (typeof v !== "object" || seen.has(v)) throw new Error("Unsupported cached value");
+    if (
+      !Array.isArray(v) &&
+      Object.getPrototypeOf(v) !== Object.prototype &&
+      Object.getPrototypeOf(v) !== null
+    ) {
+      throw new Error("Unsupported cached object");
+    }
+    seen.add(v);
+    for (const item of Object.values(v)) check(item);
+    seen.delete(v);
+  }
+  check(value);
+  return JSON.stringify(value);
+}
+
+/**
+ * Typed cache with a bounded, decoded memory tier. All remote access uses CacheStorage.
+ * Call key() once per operation so a content change cannot redirect an in-flight write.
+ * In-flight promises remain in the calling isolate; only completed results are persisted.
+ */
+export function createCacheStore<T>(
+  namespace: string,
+  maxEntries = 200,
+  maxBytes = 4 * 1024 * 1024,
+  sizeOf?: (value: T) => number,
+) {
+  const local = new Map<string, { value: T; expiresAt: number; bytes: number }>();
+  let bytes = 0;
+  let generation = 0;
+  function remove(key: string) {
+    const entry = local.get(key);
+    if (entry) bytes -= entry.bytes;
+    local.delete(key);
+  }
+  function remember(key: string, value: T, expiresAt: number) {
+    remove(key);
+    let size: number;
+    try {
+      size = sizeOf
+        ? sizeOf(value)
+        : Math.max(512, (key.length + (JSON.stringify(value)?.length ?? 0)) * 2);
+    } catch {
+      size = 1024;
+    }
+    if (size > maxBytes) return;
+    local.set(key, { value, expiresAt, bytes: size });
+    bytes += size;
+    while (local.size > 0 && (local.size > maxEntries || bytes > maxBytes))
+      remove(local.keys().next().value!);
+  }
+  function get(key: string): T | undefined {
+    if (getCacheStorageContext()?.disabled) return undefined;
+    const entry = local.get(key);
+    if (!entry) return undefined;
+    if (Date.now() >= entry.expiresAt) {
+      remove(key);
+      return undefined;
+    }
+    local.delete(key);
+    local.set(key, entry);
+    return entry.value;
+  }
+  return {
+    key(raw: string): string {
+      return JSON.stringify([getCacheStorageContext()?.scope ?? "local", namespace, raw]);
+    },
+    get,
+    async read(key: string): Promise<T | undefined> {
+      const hit = get(key);
+      if (hit !== undefined) return hit;
+      const context = getCacheStorageContext();
+      if (!context?.storage || context.disabled) return undefined;
+      const gen = generation;
+      try {
+        const raw = await context.storage.get(key);
+        if (gen !== generation) return undefined;
+        const concurrent = get(key);
+        if (concurrent !== undefined) return concurrent;
+        if (raw === null) return undefined;
+        const entry = JSON.parse(raw) as { value: T; expiresAt: number };
+        if (!Number.isFinite(entry.expiresAt) || Date.now() >= entry.expiresAt) return undefined;
+        remember(key, entry.value, entry.expiresAt);
+        return entry.value;
+      } catch {
+        return undefined;
+      }
+    },
+    set(key: string, value: T, expiresAt: number, persist = true): void {
+      if (
+        getCacheStorageContext()?.disabled ||
+        !Number.isFinite(expiresAt) ||
+        expiresAt <= Date.now()
+      )
+        return;
+      remember(key, value, expiresAt);
+      const storage = getCacheStorageContext()?.storage;
+      if (!persist || !storage || !Number.isFinite(expiresAt)) return;
+      try {
+        const raw = serialize({ value, expiresAt });
+        if (raw !== undefined) cacheBackground(storage.set(key, raw, expiresAt));
+      } catch {
+        /* Non-serializable results remain in the memory tier. */
+      }
+    },
+    delete(key: string): void {
+      remove(key);
+    },
+    /** Local eviction only. Shared invalidation uses a new scope/version or storage.delete(). */
+    clear(): void {
+      local.clear();
+      bytes = 0;
+      generation++;
+    },
+    get size(): number {
+      return local.size;
+    },
+    get estimatedBytes(): number {
+      return bytes;
+    },
+    *entries(): IterableIterator<[string, T]> {
+      for (const [key, entry] of local) yield [key, entry.value];
+    },
+  };
+}

package/src/sdk/cachedLoader.ts

@@ -1,7 +1,7 @@
 /**
  * Server-side loader caching with stale-while-revalidate + stale-if-error.
  *
- * Provides an in-memory cache layer for commerce loaders during SSR.
+ * Caches commerce loader results in memory and optional app-provided storage.
  * Supports:
  * - Single-flight dedup (identical concurrent requests share one fetch)
  * - SWR: serve stale immediately, refresh in background
@@ -19,6 +19,7 @@ import {
   withTracing,
 } from "../middleware/observability";
 import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
+import { cacheBackground, createCacheStore, getCacheStorageContext } from "./cacheStorage";
 import { withInflightTimeout } from "./inflightTimeout";
 import { RequestContext } from "./requestContext";
 
@@ -29,14 +30,8 @@ import { RequestContext } from "./requestContext";
 // pattern already used in `../cms/blockSource.ts`.
 declare const __DECO_BUILD_HASH__: string | undefined;
 
-// Prefixes every in-memory loader cache key with the build hash, mirroring the
-// edge cache's `__v`. This is defense-in-depth, NOT the primary invalidation
-// lever: the cache Map is per-isolate, so a fresh isolate spun for a new deploy
-// already starts empty, and a warm isolate keeps running its old bundle (hence
-// its old BUILD) until it is recycled — the prefix cannot flush that. It only
-// matters if this store ever becomes shared across builds. Gated on truthiness
-// (empty string ⇒ unversioned) to match getBuildHash()/getDeploymentId() in
-// workerEntry.ts / blockSource.ts.
+// Include the build version even when called outside the TanStack worker. The
+// request-scoped store additionally separates sites, content revisions and segments.
 const BUILD =
   typeof __DECO_BUILD_HASH__ !== "undefined" && __DECO_BUILD_HASH__ ? __DECO_BUILD_HASH__ : "";
 
@@ -56,6 +51,8 @@ export interface CachedLoaderOptions {
   maxAge?: number;
   /** How long to serve stale on origin error, in ms. Default: 0 (no error fallback). */
   staleIfError?: number;
+  /** Maximum stale-while-revalidate window in ms. Default: 5 minutes. */
+  staleWhileRevalidate?: number;
   /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
   keyFn?: (props: unknown) => string;
 }
@@ -138,8 +135,12 @@ export function getLoaderCacheMaxBytes(): number {
   return maxCacheBytes;
 }
 
-const cache = new Map<string, CacheEntry>();
-let cacheBytes = 0;
+const cache = createCacheStore<CacheEntry>(
+  "loaders",
+  Infinity,
+  Infinity,
+  (entry) => entry.estimatedBytes,
+);
 
 // Bumped by clearLoaderCache(). A loader invocation captures this at entry and
 // only writes its result back if the generation is unchanged when it settles —
@@ -177,26 +178,22 @@ function estimateBytes(value: unknown): number {
  * background-refresh callers route through here, which is why the size metric
  * is emitted at this chokepoint rather than at each call site.
  */
-function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string) {
+function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string, retention: number) {
   recordCacheSizeMetric(entry.estimatedBytes, name);
-  const prev = cache.get(key);
-  if (prev) cacheBytes -= prev.estimatedBytes;
-  cacheBytes += entry.estimatedBytes;
-  cache.set(key, entry);
+  cache.set(key, entry, entry.createdAt + retention);
 }
 
 function deleteCacheEntry(key: string) {
-  const prev = cache.get(key);
-  if (!prev) return;
-  cacheBytes -= prev.estimatedBytes;
   cache.delete(key);
 }
 
 function evictIfNeeded() {
+  let cacheBytes = cache.estimatedBytes;
   if (cacheBytes <= maxCacheBytes) return;
   const oldest = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
-  for (const [key] of oldest) {
+  for (const [key, entry] of oldest) {
     deleteCacheEntry(key);
+    cacheBytes -= entry.estimatedBytes;
     if (cacheBytes <= maxCacheBytes) break;
   }
 }
@@ -237,7 +234,13 @@ export function createCachedLoader<TProps, TResult>(
   optionsOrProfile: CachedLoaderOptions | CacheProfileName,
 ): (props: TProps) => Promise<TResult> {
   const resolved = resolveOptions(optionsOrProfile);
-  const { policy, maxAge = DEFAULT_MAX_AGE, staleIfError = 0, keyFn = JSON.stringify } = resolved;
+  const {
+    policy,
+    maxAge = DEFAULT_MAX_AGE,
+    staleIfError = 0,
+    staleWhileRevalidate = 300_000,
+    keyFn = JSON.stringify,
+  } = resolved;
 
   const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
   const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
@@ -247,14 +250,17 @@ export function createCachedLoader<TProps, TResult>(
     console.warn(
       `[cachedLoader] ${name}: maxAge=${Math.round(maxAge / 1000)}s is very long — ` +
         `upstream changes take that long to propagate. Prefer a short window and use ` +
-        `POST /_cache/purge-loaders (or a redeploy) for immediate invalidation.`,
+        `short TTLs for shared storage; the purge-loaders endpoint clears memory only.`,
     );
   }
 
   if (policy === "no-store") return loaderFn;
 
   return async (props: TProps): Promise<TResult> => {
-    const cacheKey = `${BUILD}::${name}::${keyFn(props)}`;
+    const cacheKey = cache.key(`${BUILD}::${name}::${keyFn(props)}`);
+    const retention =
+      maxAge +
+      Math.max(staleIfError, policy === "stale-while-revalidate" ? staleWhileRevalidate : 0);
     // Snapshot the cache generation; a purge during this invocation bumps it,
     // and the deferred writes below skip repopulating a just-cleared entry.
     const gen = cacheGeneration;
@@ -295,7 +301,14 @@ export function createCachedLoader<TProps, TResult>(
       return promise;
     }
 
-    const entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
+    let entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
+    if (!entry && getCacheStorageContext()?.storage) {
+      entry = (await cache.read(cacheKey)) as CacheEntry<TResult> | undefined;
+      evictIfNeeded();
+    }
+    // Another caller may have started the origin fetch while storage was being read.
+    const pending = inflightRequests.get(cacheKey);
+    if (pending) return pending as Promise<TResult>;
     const now = Date.now();
     const isStale = entry ? now - entry.createdAt > maxAge : true;
 
@@ -314,45 +327,52 @@ export function createCachedLoader<TProps, TResult>(
         return entry.value;
       }
 
-      if (entry && isStale && !entry.refreshing) {
+      if (
+        entry &&
+        isStale &&
+        now - entry.createdAt <= maxAge + staleWhileRevalidate &&
+        !entry.refreshing
+      ) {
         // Stale-while-revalidate hit: serve stale, refresh in background.
         recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
         recordLoaderMetric(name, 0, "STALE-HIT");
         entry.refreshing = true;
-        loaderFn(props)
-          .then((result) => {
-            // Skip the write if a purge cleared the cache mid-refresh — otherwise
-            // we'd re-insert pre-purge data the purge was meant to drop.
-            if (gen !== cacheGeneration) return;
-            setCacheEntry(
-              cacheKey,
-              {
-                value: result,
-                createdAt: Date.now(),
-                refreshing: false,
-                estimatedBytes: estimateBytes(result),
-              },
-              name,
-            );
-            evictIfNeeded();
-          })
-          .catch(() => {
-            // Background refresh failed — entry stays stale.
-            // If past the SIE window, evict so we don't serve indefinitely stale data.
-            entry.refreshing = false;
-            if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
-              deleteCacheEntry(cacheKey);
-            }
-          });
+        cacheBackground(
+          Promise.resolve()
+            .then(() => loaderFn(props))
+            .then((result) => {
+              // Skip the write if a purge cleared the cache mid-refresh — otherwise
+              // we'd re-insert pre-purge data the purge was meant to drop.
+              if (gen !== cacheGeneration) return;
+              setCacheEntry(
+                cacheKey,
+                {
+                  value: result,
+                  createdAt: Date.now(),
+                  refreshing: false,
+                  estimatedBytes: estimateBytes(result),
+                },
+                name,
+                retention,
+              );
+              evictIfNeeded();
+            })
+            .catch(() => {
+              // Background refresh failed — entry stays stale.
+              // If past the SIE window, evict so we don't serve indefinitely stale data.
+              entry.refreshing = false;
+              if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
+                deleteCacheEntry(cacheKey);
+              }
+            }),
+        );
         return entry.value;
       }
 
-      if (entry) {
-        // Past SIE window — still serve the stale value once but mark
-        // the decision as STALE-ERROR so dashboards can distinguish
-        // this from healthy SWR.
-        recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
-        recordLoaderMetric(name, 0, "STALE-ERROR");
+      if (entry && now - entry.createdAt <= maxAge + staleWhileRevalidate) {
+        // A background refresh is already running in this isolate.
+        recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-HIT");
         return entry.value;
       }
     }
@@ -382,6 +402,7 @@ export function createCachedLoader<TProps, TResult>(
               estimatedBytes: estimateBytes(result),
             },
             name,
+            retention,
           );
           evictIfNeeded();
         }
@@ -390,7 +411,7 @@ export function createCachedLoader<TProps, TResult>(
       .catch((err) => {
         // SIE fallback: if we have a stale entry within the error window, return it
         if (staleIfError > 0 && entry) {
-          const age = now - entry.createdAt;
+          const age = Date.now() - entry.createdAt;
           if (age < maxAge + staleIfError) {
             console.warn(
               `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
@@ -468,7 +489,7 @@ export function createCachedLoaderFromModule<TProps, TResult>(
     // Explicit null → the loader declared this call uncacheable: run fresh.
     if (keyPart === null) return mod.default(props, req);
 
-    const key = `${BUILD}::${name}::${keyPart}`;
+    const key = cache.key(`${BUILD}::${name}::${keyPart}`);
     const existing = moduleInflight.get(key) as Promise<TResult> | undefined;
     if (existing) return existing;
 
@@ -512,15 +533,13 @@ export function createLoaderEntry<TProps = any, TResult = any>(
 /**
  * Clear all cached entries in THIS isolate. Used both by decofile hot-reload
  * (`@decocms/blocks-admin`) and by the `POST /_cache/purge-loaders` route — an
- * escape hatch to invalidate immediately (e.g. after an out-of-band Magento/
- * catalog sync) without waiting out the TTL. Per-isolate: the route must be hit
- * for every isolate; a redeploy replaces isolates wholesale. Bumps the cache
+ * memory eviction hook. Shared storage entries expire by TTL and may hydrate
+ * memory again. Deployment/content scopes prevent reuse across versions. Bumps the cache
  * generation so any loader in flight at purge time won't repopulate a cleared
  * entry with pre-purge data.
  */
 export function clearLoaderCache() {
   cache.clear();
-  cacheBytes = 0;
   inflightRequests.clear();
   moduleInflight.clear();
   cacheGeneration++;
@@ -531,7 +550,7 @@ export function getLoaderCacheStats() {
   return {
     entries: cache.size,
     inflight: inflightRequests.size,
-    estimatedBytes: cacheBytes,
+    estimatedBytes: cache.estimatedBytes,
     maxBytes: maxCacheBytes,
   };
 }

package/src/sdk/encoding.ts

@@ -26,7 +26,7 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
   return btoa(bin);
 }
 
-export function decodeBase64(b64: string): Uint8Array {
+export function decodeBase64(b64: string): Uint8Array<ArrayBuffer> {
   const bin = atob(b64);
   const out = new Uint8Array(bin.length);
   for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
@@ -34,10 +34,7 @@ export function decodeBase64(b64: string): Uint8Array {
 }
 
 export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
-  return encodeBase64(data)
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_")
-    .replace(/=+$/, "");
+  return encodeBase64(data).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
 export function decodeBase64Url(b64url: string): Uint8Array {