@decocms/blocks 7.26.3 → 7.28.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.26.3",
+  "version": "7.28.0-beta.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/draftSource.test.ts

@@ -0,0 +1,201 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import {
+  buildDraftOrigin,
+  clearDraftCache,
+  isDraftPreviewEnabled,
+  parseDraftPointer,
+  resolveDraftDecofile,
+} from "./draftSource";
+
+const ENV_ON = {
+  DECO_DRAFT_PREVIEW: "1",
+  DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
+};
+
+function jsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    ...init,
+  });
+}
+
+beforeEach(() => {
+  clearDraftCache();
+});
+
+describe("parseDraftPointer", () => {
+  it("parses handle@version", () => {
+    expect(parseDraftPointer("gimenes-abc123@ff00")).toEqual({
+      handle: "gimenes-abc123",
+      version: "ff00",
+    });
+  });
+
+  it("rejects more than one @", () => {
+    // A naive split("@") accepts this and silently uses the first two
+    // segments — the exact hole found while spiking the fetch path.
+    expect(parseDraftPointer("a@b@c")).toBeNull();
+  });
+
+  it("rejects a handle that could escape the authority", () => {
+    expect(parseDraftPointer("evil.com/x@v1")).toBeNull();
+    expect(parseDraftPointer("user:pw@v1")).toBeNull();
+    expect(parseDraftPointer("a/../b@v1")).toBeNull();
+    expect(parseDraftPointer(".leading-dot@v1")).toBeNull();
+  });
+
+  it("rejects empty halves and missing input", () => {
+    expect(parseDraftPointer("@v1")).toBeNull();
+    expect(parseDraftPointer("handle@")).toBeNull();
+    expect(parseDraftPointer("handle")).toBeNull();
+    expect(parseDraftPointer(null)).toBeNull();
+    expect(parseDraftPointer("")).toBeNull();
+  });
+});
+
+describe("buildDraftOrigin", () => {
+  it("builds https from the configured suffix", () => {
+    expect(buildDraftOrigin("abc", [".preview-studio.decocms.com"])).toBe(
+      "https://abc.preview-studio.decocms.com",
+    );
+  });
+
+  it("uses http for a localhost suffix (local e2e)", () => {
+    expect(buildDraftOrigin("abc", [".localhost:3200"])).toBe("http://abc.localhost:3200");
+  });
+
+  it("returns null with no configured suffix — never guesses an origin", () => {
+    expect(buildDraftOrigin("abc", [])).toBeNull();
+  });
+});
+
+describe("isDraftPreviewEnabled", () => {
+  it("needs both the flag and a suffix", () => {
+    expect(isDraftPreviewEnabled(ENV_ON)).toBe(true);
+    expect(isDraftPreviewEnabled({ DECO_DRAFT_PREVIEW: "1" })).toBe(false);
+    expect(
+      isDraftPreviewEnabled({
+        DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com",
+      }),
+    ).toBe(false);
+    expect(isDraftPreviewEnabled({})).toBe(false);
+  });
+});
+
+describe("resolveDraftDecofile", () => {
+  it("fetches the sandbox decofile and returns it", async () => {
+    const calls: string[] = [];
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc@v1",
+      env: ENV_ON,
+      fetchImpl: (async (url: string) => {
+        calls.push(String(url));
+        return jsonResponse({ "pages-home": { title: "draft" } });
+      }) as unknown as typeof fetch,
+    });
+
+    expect(blocks).toEqual({ "pages-home": { title: "draft" } });
+    expect(calls).toEqual(["https://abc.preview-studio.decocms.com/_sandbox/decofile"]);
+  });
+
+  it("is inert unless explicitly enabled — no fetch at all", async () => {
+    let called = false;
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc@v1",
+      env: { DECO_SANDBOX_ORIGIN_SUFFIXES: ".preview-studio.decocms.com" },
+      fetchImpl: (async () => {
+        called = true;
+        return jsonResponse({});
+      }) as unknown as typeof fetch,
+    });
+
+    expect(blocks).toBeNull();
+    expect(called).toBe(false);
+  });
+
+  it("caches by version — one fetch per version, not per request", async () => {
+    let fetches = 0;
+    const fetchImpl = (async () => {
+      fetches++;
+      return jsonResponse({ n: fetches });
+    }) as unknown as typeof fetch;
+
+    const a = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
+    const b = await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(1);
+    expect(b).toBe(a);
+
+    await resolveDraftDecofile({ pointer: "abc@v2", env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(2);
+  });
+
+  it("bounds the cache so multi-MB decofiles can't accumulate", async () => {
+    let fetches = 0;
+    const fetchImpl = (async () => {
+      fetches++;
+      return jsonResponse({ n: fetches });
+    }) as unknown as typeof fetch;
+
+    for (const v of ["v1", "v2", "v3", "v4"]) {
+      await resolveDraftDecofile({ pointer: `abc@${v}`, env: ENV_ON, fetchImpl });
+    }
+    expect(fetches).toBe(4);
+
+    // v1 was evicted (cap is 3), so it must re-fetch rather than serve stale.
+    await resolveDraftDecofile({ pointer: "abc@v1", env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(5);
+
+    // v4 is still resident.
+    await resolveDraftDecofile({ pointer: "abc@v4", env: ENV_ON, fetchImpl });
+    expect(fetches).toBe(5);
+  });
+
+  it("degrades to published on a malformed pointer, without fetching", async () => {
+    let called = false;
+    const blocks = await resolveDraftDecofile({
+      pointer: "a@b@c",
+      env: ENV_ON,
+      fetchImpl: (async () => {
+        called = true;
+        return jsonResponse({});
+      }) as unknown as typeof fetch,
+    });
+    expect(blocks).toBeNull();
+    expect(called).toBe(false);
+  });
+
+  it("degrades to published on a non-2xx sandbox", async () => {
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc@v1",
+      env: ENV_ON,
+      fetchImpl: (async () => new Response("nope", { status: 404 })) as unknown as typeof fetch,
+    });
+    expect(blocks).toBeNull();
+  });
+
+  it("degrades to published when the sandbox is unreachable", async () => {
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc@v1",
+      env: ENV_ON,
+      fetchImpl: (async () => {
+        throw new Error("ECONNREFUSED");
+      }) as unknown as typeof fetch,
+    });
+    expect(blocks).toBeNull();
+  });
+
+  it("degrades to published on an unparseable body", async () => {
+    const blocks = await resolveDraftDecofile({
+      pointer: "abc@v1",
+      env: ENV_ON,
+      fetchImpl: (async () =>
+        new Response("<html>not json</html>", {
+          status: 200,
+          headers: { "content-type": "text/html" },
+        })) as unknown as typeof fetch,
+    });
+    expect(blocks).toBeNull();
+  });
+});

package/src/cms/draftSource.ts

@@ -0,0 +1,197 @@
+/**
+ * Draft preview — pull-based decofile override.
+ *
+ * A Studio sandbox serves the working-tree draft at
+ * `GET <origin>/_sandbox/decofile`; a production site pulls it and renders its
+ * own real pages against it. This replaces pushing the decofile into a POST
+ * body, which only deco's own runtime honours — Next.js and most frameworks
+ * render on GET only.
+ *
+ * This module is the framework-agnostic half: pointer parsing, origin
+ * construction, fetching, and version caching. Binding a resolved draft to a
+ * request is framework-specific (see `@decocms/nextjs`'s draft wiring) and
+ * reaches this module through {@link setDraftOverrideGetter} — the same
+ * dependency-injection shape as `setFastDeployKVGetter`, so `blocks` keeps its
+ * zero-dependency direction.
+ *
+ * Inert unless BOTH `DECO_DRAFT_PREVIEW=1` and `DECO_SANDBOX_ORIGIN_SUFFIXES`
+ * are set, mirroring Fast Deploy's opt-in: upgrading the package must never be
+ * enough to start fetching from the network and rendering unpublished content.
+ */
+
+/** A parsed `<handle>@<version>` draft pointer. */
+export interface DraftPointer {
+  /** Sandbox handle — the subdomain under a configured origin suffix. */
+  handle: string;
+  /** Content version (the daemon's ETag). Immutable, so safe to cache on. */
+  version: string;
+}
+
+/**
+ * Sandbox handles are `[a-z0-9-]`, always leading with an alphanumeric.
+ *
+ * Validated BEFORE the handle is interpolated into an authority, so it cannot
+ * smuggle `/`, `@`, `:` or userinfo into the URL and redirect the fetch at some
+ * other host.
+ */
+const HANDLE_RE = /^[a-zA-Z0-9][a-zA-Z0-9-]*$/;
+
+/**
+ * Parse `<handle>@<version>`.
+ *
+ * Requires EXACTLY one `@`: a naive `split("@")` accepts `a@b@c` and silently
+ * uses the first two segments, which is how a malformed pointer sneaks past
+ * validation. Returns null on anything unexpected — callers fall back to
+ * published content.
+ */
+export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
+  if (!raw) return null;
+  const parts = raw.split("@");
+  if (parts.length !== 2) return null;
+  const [handle, version] = parts;
+  if (!handle || !version) return null;
+  if (!HANDLE_RE.test(handle)) return null;
+  return { handle, version };
+}
+
+/** Configured suffixes, e.g. `.preview-studio.decocms.com,.localhost:3200`. */
+function readSuffixes(env: Record<string, string | undefined>): string[] {
+  return (env.DECO_SANDBOX_ORIGIN_SUFFIXES ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Build the sandbox origin for a handle.
+ *
+ * The origin comes from CONFIGURED suffixes, never from caller input, so there
+ * is no SSRF surface to defend and no allowlist to keep correct. A `localhost`
+ * suffix (local e2e) speaks http; everything else is https.
+ */
+export function buildDraftOrigin(handle: string, suffixes: string[]): string | null {
+  const suffix = suffixes[0];
+  if (!suffix) return null;
+  if (!HANDLE_RE.test(handle)) return null;
+  const scheme = suffix.includes("localhost") ? "http" : "https";
+  return `${scheme}://${handle}${suffix}`;
+}
+
+/**
+ * Version cache.
+ *
+ * Bounded on purpose: a decofile is routinely multi-megabyte, so an unbounded
+ * map keyed by version would grow with every save until the process died.
+ * Keyed by version (content-addressed), so a hit is always correct.
+ */
+const MAX_CACHED_VERSIONS = 3;
+const byVersion = new Map<string, Record<string, unknown>>();
+
+function cacheDraft(version: string, blocks: Record<string, unknown>): void {
+  // Re-insert to make this the most recently used key.
+  byVersion.delete(version);
+  byVersion.set(version, blocks);
+  while (byVersion.size > MAX_CACHED_VERSIONS) {
+    const oldest = byVersion.keys().next().value;
+    if (oldest === undefined) break;
+    byVersion.delete(oldest);
+  }
+}
+
+/** Test seam — drops every cached version. */
+export function clearDraftCache(): void {
+  byVersion.clear();
+}
+
+export interface ResolveDraftOptions {
+  /** Raw `<handle>@<version>` pointer from the request. */
+  pointer: string | null | undefined;
+  /** Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Defaults to global `fetch`. Injected in tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Resolve a draft pointer to a decofile, or null to render published content.
+ *
+ * Null on every failure path — disabled, malformed pointer, unreachable
+ * sandbox, non-2xx — because a draft that cannot be resolved must degrade to
+ * published rather than break the page. Callers that need to *tell the user*
+ * the draft failed should check {@link isDraftPreviewEnabled} and surface it
+ * themselves; silently showing published content while the user believes they
+ * are looking at a draft is the failure mode worth avoiding.
+ */
+export async function resolveDraftDecofile(
+  options: ResolveDraftOptions,
+): Promise<Record<string, unknown> | null> {
+  const env =
+    options.env ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
+    {};
+  if (env.DECO_DRAFT_PREVIEW !== "1") return null;
+
+  const parsed = parseDraftPointer(options.pointer);
+  if (!parsed) return null;
+
+  const cached = byVersion.get(parsed.version);
+  if (cached) return cached;
+
+  const origin = buildDraftOrigin(parsed.handle, readSuffixes(env));
+  if (!origin) return null;
+
+  const doFetch = options.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(`${origin}/_sandbox/decofile`, { cache: "no-store" });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+
+  let blocks: Record<string, unknown>;
+  try {
+    blocks = (await res.json()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  cacheDraft(parsed.version, blocks);
+  return blocks;
+}
+
+/** True when the feature is switched on and configured. Inert otherwise. */
+export function isDraftPreviewEnabled(env?: Record<string, string | undefined>): boolean {
+  const e =
+    env ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
+    {};
+  return e.DECO_DRAFT_PREVIEW === "1" && readSuffixes(e).length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Request binding (dependency-injected by the framework binding)
+// ---------------------------------------------------------------------------
+
+type DraftOverrideGetter = () => Record<string, unknown> | null | undefined;
+
+let getDraftOverride: DraftOverrideGetter = () => undefined;
+
+/**
+ * Inject the request-scoped draft getter.
+ *
+ * Binding a value to "the current request" is framework-specific and `blocks`
+ * must not know about any framework: `@decocms/nextjs` backs this with React
+ * `cache()` (App Router has no AsyncLocalStorage request scope of its own —
+ * `RequestContext.run` is never entered there). Bindings that do have an ALS
+ * request scope can back it with that instead. Never called → returns
+ * undefined → `loadBlocks()` behaves exactly as before.
+ */
+export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
+  getDraftOverride = getter;
+}
+
+/** The current request's draft blocks, if a binding registered one. */
+export function getRequestDraftOverride(): Record<string, unknown> | null | undefined {
+  return getDraftOverride();
+}

package/src/cms/index.ts

@@ -12,6 +12,16 @@ export {
   revisionKey,
   snapshotKey,
 } from "./blockSource";
+export type { DraftPointer, ResolveDraftOptions } from "./draftSource";
+export {
+  buildDraftOrigin,
+  clearDraftCache,
+  getRequestDraftOverride,
+  isDraftPreviewEnabled,
+  parseDraftPointer,
+  resolveDraftDecofile,
+  setDraftOverrideGetter,
+} from "./draftSource";
 export type { DecoPage, Resolvable } from "./loader";
 export {
   findPageByPath,
@@ -82,8 +92,6 @@ export {
   unregisterCommerceLoader,
   WELL_KNOWN_TYPES,
 } from "./resolve";
-export type { SectionLoaderContext } from "./sectionLoaderContext";
-export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export type {
   ActionConfig,
   AppSchemas,
@@ -105,6 +113,8 @@ export {
   registerMatcherSchema,
   registerMatcherSchemas,
 } from "./schema";
+export type { SectionLoaderContext } from "./sectionLoaderContext";
+export { buildSectionLoaderContext } from "./sectionLoaderContext";
 export type { SectionLoaderFn } from "./sectionLoaders";
 export {
   getDegradedSections,

package/src/cms/loader.ts

@@ -1,5 +1,6 @@
 import * as asyncHooks from "node:async_hooks";
 import { djb2Hex } from "../sdk/djb2";
+import { getRequestDraftOverride } from "./draftSource";
 
 export type Resolvable = {
   __resolveType?: string;
@@ -86,7 +87,8 @@ export function setBlocks(blocks: Record<string, unknown>) {
 
 /**
  * Load the current blocks. If running inside a `withBlocksOverride` scope
- * (admin preview), the override is merged on top of the base blocks.
+ * (admin preview) or a request carrying a draft-preview override, that
+ * override is merged on top of the base blocks.
  */
 export function loadBlocks(): Record<string, unknown> {
   // Re-sync from globalThis in case setBlocks was called in another module instance
@@ -95,7 +97,10 @@ export function loadBlocks(): Record<string, unknown> {
     revision = G.__deco.revision ?? null;
   }
 
-  const override = blocksOverrideStorage.getStore();
+  // `withBlocksOverride` (an explicit admin render of a specific payload) wins
+  // over an ambient draft: the caller named the exact blocks to render, so a
+  // draft pointer on the same request must not silently replace them.
+  const override = blocksOverrideStorage.getStore() ?? getRequestDraftOverride();
   if (override) {
     const merged = { ...blockData };
     for (const [key, value] of Object.entries(override)) {
@@ -203,12 +208,14 @@ export function getAllPages(): Array<{ key: string; page: DecoPage }> {
 // same regardless of whether @types/node has its own `URLPattern` global or
 // not — there's nothing for a local declaration to collide with.
 type MatchPatternResult = {
-	pathname: { groups: Record<string, string | undefined> };
+  pathname: { groups: Record<string, string | undefined> };
 };
 declare const URLPattern: {
-	new (init: { pathname: string }): {
-		exec(input: { pathname: string }): MatchPatternResult | null;
-	};
+  new (init: {
+    pathname: string;
+  }): {
+    exec(input: { pathname: string }): MatchPatternResult | null;
+  };
 };
 
 /**
@@ -231,10 +238,7 @@ declare const URLPattern: {
  * `URLPattern` is native in browsers, workerd, Deno, and Node >= 24 (this
  * package's `engines` floor). Node 22 and older lack it.
  */
-export function matchPath(
-  pattern: string,
-  urlPath: string,
-): Record<string, string> | null {
+export function matchPath(pattern: string, urlPath: string): Record<string, string> | null {
   if (typeof URLPattern === "undefined") {
     throw new Error(
       "@decocms/blocks: this runtime has no URLPattern Web API, so CMS page " +