@decocms/blocks 7.23.0 → 7.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.23.0",
+  "version": "7.25.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/index.ts

@@ -1,3 +1,5 @@
+export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
+export { applySectionConventions } from "./applySectionConventions";
 export type { BlockSnapshot, BlockSource, KVNamespace } from "./blockSource";
 export {
   BUILD_HASH_ENV,
@@ -50,10 +52,11 @@ export type {
 } from "./resolve";
 export {
   addSkipResolveType,
+  cacheDeferredRawProps,
+  clearCommerceLoaders,
   evaluateMatcher,
   extractSeoFromProps,
   extractSeoFromSections,
-  cacheDeferredRawProps,
   getAsyncRenderingConfig,
   getDeferredRawProps,
   isBot,
@@ -63,45 +66,24 @@ export {
   registerBotPattern,
   registerCommerceLoader,
   registerCommerceLoaders,
-  unregisterCommerceLoader,
-  clearCommerceLoaders,
-  registerMatcher,
   registerEagerSections,
+  registerMatcher,
   registerNeverDeferSections,
   registerSeoSections,
   resolveDecoPage,
-  resolvePageSections,
-  resolvePageSeoBlock,
   resolveDeferredSection,
   resolveDeferredSectionFull,
+  resolvePageSections,
+  resolvePageSeoBlock,
   resolveValue,
   setAsyncRenderingConfig,
   setDanglingReferenceHandler,
   setResolveErrorHandler,
+  unregisterCommerceLoader,
   WELL_KNOWN_TYPES,
 } from "./resolve";
-export type { SectionLoaderFn } from "./sectionLoaders";
 export type { SectionLoaderContext } from "./sectionLoaderContext";
 export { buildSectionLoaderContext } from "./sectionLoaderContext";
-export {
-  isLayoutSection,
-  registerCacheableSections,
-  registerLayoutSections,
-  registerSectionLoader,
-  registerSectionLoaders,
-  runSectionLoaders,
-  runSingleSectionLoader,
-  unregisterLayoutSections,
-} from "./sectionLoaders";
-export {
-  compose,
-  withDevice,
-  withMobile,
-  withSearchParam,
-  withSectionLoader,
-} from "./sectionMixins";
-export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
-export { applySectionConventions } from "./applySectionConventions";
 export type {
   ActionConfig,
   AppSchemas,
@@ -123,3 +105,25 @@ export {
   registerMatcherSchema,
   registerMatcherSchemas,
 } from "./schema";
+export type { SectionLoaderFn } from "./sectionLoaders";
+export {
+  getDegradedSections,
+  isCriticalSection,
+  isLayoutSection,
+  markSectionDegraded,
+  registerCacheableSections,
+  registerLayoutSections,
+  registerNonCriticalSections,
+  registerSectionLoader,
+  registerSectionLoaders,
+  runSectionLoaders,
+  runSingleSectionLoader,
+  unregisterLayoutSections,
+} from "./sectionLoaders";
+export {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";

package/src/cms/resolve.ts

@@ -13,7 +13,7 @@ import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
-import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
+import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
 const G = globalThis as any;
@@ -911,6 +911,11 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
       return await commerceLoader(resolvedProps);
     } catch (error) {
       onResolveError(error, resolveType, "Commerce loader");
+      // Commerce loaders (VTEX product/PLP/PDP data) are the primary source of
+      // page-body data — this is exactly the layer that fails during a VTEX
+      // outage. Flag the page degraded so the edge won't cache the empty
+      // result as a healthy 200 (see X-Deco-Degraded in cmsRoute/workerEntry).
+      markSectionDegraded(resolveType);
       return null;
     }
   }

package/src/cms/sectionLoaders.test.ts

@@ -1,10 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { configureTracer, type Span } from "../sdk/observability";
+import { RequestContext } from "../sdk/requestContext";
 import type { ResolvedSection } from "./resolve";
 import {
+  getDegradedSections,
   isLayoutSection,
   registerCacheableSections,
   registerLayoutSections,
+  registerNonCriticalSections,
   registerSectionLoader,
   registerSectionLoaders,
   runSectionLoaders,
@@ -19,6 +22,7 @@ beforeEach(() => {
   G.__deco.sectionLoaderRegistry.clear();
   G.__deco.layoutSections.clear();
   G.__deco.cacheableSections.clear();
+  G.__deco.nonCriticalSections.clear();
 });
 
 const makeSection = (component: string, props: Record<string, unknown> = {}): ResolvedSection => ({
@@ -28,6 +32,78 @@ const makeSection = (component: string, props: Record<string, unknown> = {}): Re
   index: 0,
 });
 
+describe("section degradation tracking (anti-cache-poisoning)", () => {
+  const failing = async () => {
+    throw new Error("VTEX down");
+  };
+
+  it("marks a critical section as degraded when its loader throws", async () => {
+    registerSectionLoader("site/sections/ProductShelf.tsx", failing);
+    const section = makeSection("site/sections/ProductShelf.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      // Loader throws → section degrades to raw props (does not reject).
+      const result = await runSingleSectionLoader(section, request);
+      expect(result.component).toBe("site/sections/ProductShelf.tsx");
+      return getDegradedSections();
+    });
+
+    expect(degraded).toContain("site/sections/ProductShelf.tsx");
+  });
+
+  it("does NOT mark a non-critical section as degraded", async () => {
+    registerSectionLoader("site/sections/Decorative.tsx", failing);
+    registerNonCriticalSections(["site/sections/Decorative.tsx"]);
+    const section = makeSection("site/sections/Decorative.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    expect(degraded).toEqual([]);
+  });
+
+  it("does NOT mark a failing LAYOUT section as degraded (avoids site-wide poisoning)", async () => {
+    registerSectionLoader("site/sections/Header.tsx", failing);
+    registerLayoutSections(["site/sections/Header.tsx"]);
+    const section = makeSection("site/sections/Header.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    // A flaky Header/Footer must not flip every page to X-Deco-Degraded.
+    expect(degraded).toEqual([]);
+  });
+
+  it("does not flag a page whose loaders all succeed", async () => {
+    registerSectionLoader("site/sections/Ok.tsx", async (p: Record<string, unknown>) => p);
+    const section = makeSection("site/sections/Ok.tsx");
+    const request = new Request("https://store.com/p");
+
+    const degraded = await RequestContext.run(request, async () => {
+      await runSingleSectionLoader(section, request);
+      return getDegradedSections();
+    });
+
+    expect(degraded).toEqual([]);
+  });
+
+  it("is a no-op outside a request scope (does not throw)", async () => {
+    registerSectionLoader("site/sections/NoScope.tsx", failing);
+    const section = makeSection("site/sections/NoScope.tsx");
+    const request = new Request("https://store.com/p");
+    // No RequestContext.run wrapper — must not throw.
+    await expect(runSingleSectionLoader(section, request)).resolves.toBeTruthy();
+    expect(getDegradedSections()).toEqual([]);
+  });
+});
+
 describe("runSingleSectionLoader — page context injection", () => {
   it("injects __pageUrl and __pagePath into loader props", async () => {
     // Two-arg signature so loader.mock.calls[0] types as [props, req].

package/src/cms/sectionLoaders.ts

@@ -9,6 +9,7 @@
  * inside the TanStack Start server function.
  */
 
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { getCacheProfile } from "../sdk/cacheHeaders";
 import { djb2 } from "../sdk/djb2";
 import { withInflightTimeout } from "../sdk/inflightTimeout";
@@ -33,9 +34,56 @@ if (!G.__deco) G.__deco = {};
 if (!G.__deco.sectionLoaderRegistry) G.__deco.sectionLoaderRegistry = new Map();
 if (!G.__deco.layoutSections) G.__deco.layoutSections = new Set();
 if (!G.__deco.cacheableSections) G.__deco.cacheableSections = new Map();
+if (!G.__deco.nonCriticalSections) G.__deco.nonCriticalSections = new Set();
 
 const loaderRegistry: Map<string, SectionLoaderFn> = G.__deco.sectionLoaderRegistry;
 
+// ---------------------------------------------------------------------------
+// Degradation tracking (anti-cache-poisoning)
+//
+// When a section loader throws, the section renders with raw (un-enriched)
+// props — e.g. a product shelf with no products during a VTEX outage. Today
+// that degraded page is emitted as a healthy 200 and the edge caches it for the
+// full retention window, so stale-if-error never fires and users see an empty
+// page for hours. We record each CRITICAL section degradation on a
+// request-scoped collector; the CMS route reads it and emits `X-Deco-Degraded`
+// so the worker refuses to cache the broken page and serves stale instead.
+//
+// Every section is critical by default (a registered loader failing means
+// intended data is missing). Decorative sections whose empty state is harmless
+// can opt out via `registerNonCriticalSections`.
+// ---------------------------------------------------------------------------
+
+const DEGRADED_BAG_KEY = "deco:degraded-sections";
+const nonCriticalSections: Set<string> = G.__deco.nonCriticalSections;
+
+/** Mark section keys whose loader failure should NOT make the page uncacheable. */
+export function registerNonCriticalSections(keys: string[]): void {
+  for (const k of keys) nonCriticalSections.add(k);
+}
+
+/** A section is critical (its failure degrades the page) unless opted out. */
+export function isCriticalSection(key: string): boolean {
+  return !nonCriticalSections.has(key);
+}
+
+/**
+ * Record that a critical section rendered with raw props because its loader
+ * threw. No-op outside a request scope or for non-critical sections.
+ */
+export function markSectionDegraded(component: string): void {
+  if (!isCriticalSection(component)) return;
+  const set = RequestContext.getBag<Set<string>>(DEGRADED_BAG_KEY) ?? new Set<string>();
+  set.add(component);
+  RequestContext.setBag(DEGRADED_BAG_KEY, set);
+}
+
+/** Component keys of critical sections that degraded during this request. */
+export function getDegradedSections(): string[] {
+  const set = RequestContext.getBag<Set<string>>(DEGRADED_BAG_KEY);
+  return set ? [...set] : [];
+}
+
 // ---------------------------------------------------------------------------
 // Cacheable section loaders — SWR cache for section loader results
 // ---------------------------------------------------------------------------
@@ -432,6 +480,11 @@ async function runSingleSectionLoaderImpl(
         result = await resolveLayoutSection(section, wrapped, request);
       } catch (error) {
         console.error(`[SectionLoader] Error in layout "${section.component}":`, error);
+        // Deliberately NOT marked degraded: layout sections (Header/Footer/Theme)
+        // render on every page, so a flaky layout loader would flip the whole
+        // site to X-Deco-Degraded and defeat edge caching everywhere. A failed
+        // layout renders raw chrome, which is acceptable — page-body data
+        // integrity (product shelves/PLP/PDP) is what the degraded signal guards.
         result = section;
       }
     } else {
@@ -441,6 +494,7 @@ async function runSingleSectionLoaderImpl(
           result = await runCacheableSectionLoader(section, wrapped, request, cacheConfig);
         } catch (error) {
           console.error(`[SectionLoader] Error in cacheable "${section.component}":`, error);
+          markSectionDegraded(section.component);
           result = section;
         }
       } else {
@@ -449,6 +503,7 @@ async function runSingleSectionLoaderImpl(
           result = { ...section, props: enrichedProps };
         } catch (error) {
           console.error(`[SectionLoader] Error in "${section.component}":`, error);
+          markSectionDegraded(section.component);
           result = section;
         }
       }