@decocms/nextjs 8.5.2 → 8.7.0

package/src/server/index.ts

@@ -2,76 +2,216 @@
  * `@decocms/nextjs/server`: draft previews in Server Components (pages,
  * layouts, route handlers). Server only: it reads `next/headers`.
  *
- * A page (and, through the `x-deco-draft` header the proxy forwards, the root
- * layout) binds the request's draft before it reads content, then reads
- * through `contentClient(cms)`:
+ * The proxy decides what a request reads (`@decocms/nextjs/proxy`): the
+ * version, the visitor, and each test and campaign on or off, forwarded on
+ * `x-deco-version`, `x-deco-visitor` and `x-deco-assignments`. A page (and,
+ * through those headers, the root layout) binds them before it reads
+ * content, then reads through `contentClient(cms)`, which builds
+ * `cms.client({ version, experiments, campaigns })` and decides nothing
+ * again:
  *
  * ```tsx
  * export default async function Page({ searchParams }) {
- *   await bindDraft(cms, { searchParams: await searchParams, site: "my-store" });
+ *   await bindDraft(cms, { searchParams: await searchParams });
  *   const client = contentClient(cms);
  *   …
  *   return <>{sections}<DraftPreviewIndicator /></>;
  * }
  * ```
  *
- * The host check is the proxy's (`decideDraft`), repeated here with the same
- * options, so a route the proxy doesn't match, or a forged `x-deco-draft`,
- * still gets the release on a host that may not preview.
+ * The host check is the proxy's (`decideDraft`), repeated here against the
+ * same CMS, so a route the proxy doesn't match, or a forged `x-deco-version`,
+ * still gets the release on a host that may not preview. On the release, a
+ * test at 0% stays off whatever `x-deco-assignments` says.
  */
 
-import type { Client, CMS } from "@decocms/blocks";
+import type { Client, ClientOptions, CMS } from "@decocms/blocks";
+import { parseVisitor } from "@decocms/blocks/experiments";
 import { headers } from "next/headers.js";
-import { DRAFT_HEADER, DRAFT_PARAM } from "../draft.ts";
-import { allowedDraft, isDraftPreviewEnabled, type PreviewPolicy, requestLike } from "../drafts.ts";
+import {
+  ASSIGNMENTS_HEADER,
+  type PathAssignments,
+  parseAssignmentsSegment,
+  withoutDarkTests,
+} from "../assignments.ts";
+import {
+  DRAFT_PARAM,
+  DRAFT_UNAVAILABLE_HEADER,
+  RELEASE_CHECK_HEADER,
+  VERSION_HEADER,
+} from "../draft.ts";
+import { allowedDraft, draftReleaseCheck, requestLike } from "../drafts.ts";
+import { VISITOR_HEADER } from "../visitor.ts";
 import { activeDraftPointer, draftSlot } from "./slot.ts";
 
-export { type PreviewPolicy, requestLike } from "../drafts.ts";
+export {
+  ASSIGNMENTS_ROUTE_PREFIX,
+  assignmentsSegment,
+  type PathAssignments,
+  parseAssignmentsSegment,
+} from "../assignments.ts";
+export { requestLike } from "../drafts.ts";
 export { activeDraftPointer };
 
 /** A page's `searchParams` prop, awaited. */
 export type SearchParams = Record<string, string | string[] | undefined>;
 
-export interface BindDraftOptions extends PreviewPolicy {
-  /** The page's own `searchParams` (a layout has none: it reads the proxy's `x-deco-draft`). */
+export interface BindDraftOptions {
+  /** The page's own `searchParams` (a layout has none: it reads the proxy's `x-deco-version`). */
   searchParams?: SearchParams;
 }
 
+type BindCMS = Pick<CMS, "readVersion" | "forRelease" | "checkRelease">;
+
 function firstParam(searchParams: SearchParams | undefined, key: string): string | null {
   const raw = searchParams?.[key];
   return (Array.isArray(raw) ? raw[0] : raw) ?? null;
 }
 
 /**
- * Binds the request's draft, if any: the page's own `?__draft=` first (`off`
- * leaves preview), then the pointer the proxy forwarded on `x-deco-draft`,
- * then the draft cookie, each on a host the options allow. Returns whether a
- * draft was bound. With previews off on every host it returns `false`
- * without reading the request, so a static page stays static.
+ * Binds what the request reads: the version, if any (the page's own
+ * `?__draft=` first, `off` leaving preview, then the version the proxy
+ * forwarded on `x-deco-version`, then the draft cookie, each on a host the
+ * CMS allows), and what the proxy decided (`x-deco-assignments`) and the
+ * visitor it read (`x-deco-visitor`). Returns whether a version was bound:
+ * a draft, or a published release's commit SHA (Studio's "Preview this
+ * version"). It reads the request's headers, so it belongs on the draft
+ * route; a cached (ISR) page reads what its path names (`assignedClient`).
  */
-export async function bindDraft(
-  cms: Pick<CMS, "draftPointer" | "settings" | "forRelease">,
-  options: BindDraftOptions = {},
-): Promise<boolean> {
-  const { searchParams, ...policy } = options;
-  if (!(await isDraftPreviewEnabled(cms, policy))) return false;
+export async function bindDraft(cms: BindCMS, options: BindDraftOptions = {}): Promise<boolean> {
+  if (await bindVersion(cms, options)) {
+    // A preview renders per request anyway, and may switch on a test at 0%.
+    await bindForwarded(cms, false);
+    return true;
+  }
+  if (await variesByVisitor(cms)) await bindForwarded(cms, true);
+  return false;
+}
+
+/** The visitor and the assignments the proxy forwarded, if any. */
+async function bindForwarded(cms: BindCMS, release: boolean): Promise<void> {
+  const requestHeaders = await headers();
+  const slot = draftSlot();
+  slot.visitor = parseVisitor(requestHeaders.get(VISITOR_HEADER));
+  const decided = parseAssignmentsSegment(requestHeaders.get(ASSIGNMENTS_HEADER) ?? "");
+  slot.assignments = decided && release ? await withoutDarkTests(cms, decided) : decided;
+}
+
+/**
+ * Whether the release saves an `experiments` block (the built-in
+ * `split-traffic`) or a `campaigns` block (the built-in `calendar`) with a
+ * name in it: only then does a page vary by what the proxy decided. Read from
+ * memory, unresolved; `false` when both are missing.
+ */
+async function variesByVisitor(cms: Pick<CMS, "forRelease">): Promise<boolean> {
+  const saves = async (name: string, type: string): Promise<boolean> => {
+    try {
+      const [block] = await cms.forRelease().resolve<unknown>(name, { run: false });
+      if (typeof block !== "object" || block === null) return false;
+      const record = block as Record<string, unknown>;
+      return (
+        record.__resolveType === type && Object.keys(record).some((key) => key !== "__resolveType")
+      );
+    } catch {
+      return false;
+    }
+  };
+  const [tests, campaigns] = await Promise.all([
+    saves("experiments", "split-traffic"),
+    saves("campaigns", "calendar"),
+  ]);
+  return tests || campaigns;
+}
+
+async function bindVersion(cms: BindCMS, options: BindDraftOptions): Promise<boolean> {
+  const { searchParams } = options;
   const param = firstParam(searchParams, DRAFT_PARAM);
   if (param === "off") return false;
   const requestHeaders = await headers();
-  const forwarded = param ?? requestHeaders.get(DRAFT_HEADER);
+  // The proxy read the link's draft and it's gone: the release, with the notice.
+  if (requestHeaders.get(DRAFT_UNAVAILABLE_HEADER) === "1") {
+    draftSlot().unavailable = true;
+    return false;
+  }
+  const forwarded = param ?? requestHeaders.get(VERSION_HEADER);
   const query = forwarded ? `?${DRAFT_PARAM}=${encodeURIComponent(forwarded)}` : "";
   const request = requestLike(requestHeaders as Headers, `/${query}`);
-  const pointer = request ? await allowedDraft(cms, request, policy) : null;
-  if (pointer === null) return false;
-  draftSlot().pointer = pointer;
+  if (request === null) return false;
+  // The proxy's release check for this request (`x-deco-release-check`), or one of its own:
+  // the host check here and the page's draft reads share it.
+  const releaseCheck = await draftReleaseCheck(
+    cms,
+    request,
+    requestHeaders.get(RELEASE_CHECK_HEADER),
+  );
+  const version = await allowedDraft(cms, request, releaseCheck);
+  if (version === null) return false;
+  const slot = draftSlot();
+  slot.version = version;
+  slot.releaseCheck = releaseCheck ?? null;
   return true;
 }
 
 /**
- * The content client for this request: the draft `bindDraft` bound, or the
- * release.
+ * The content client for this request, from what `bindDraft` bound:
+ * `cms.client({ version, experiments, campaigns })` with the tests and
+ * campaigns the proxy decided, deciding nothing again. On a route the proxy
+ * didn't decide for, the visitor and the preview's moment and switched tests
+ * and campaigns decide instead. Create one per request.
+ */
+export function contentClient(cms: Pick<CMS, "client">): Client {
+  const { version, visitor, assignments, releaseCheck } = draftSlot();
+  const options: ClientOptions = { visitor, version: version?.version ?? null };
+  if (version !== null && releaseCheck !== null) options.releaseCheck = releaseCheck;
+  if (version?.date !== undefined) options.date = version.date;
+  const experiments = over(version?.experiments, assignments?.experiments);
+  const campaigns = over(version?.campaigns, assignments?.campaigns);
+  if (experiments !== undefined) options.experiments = experiments;
+  if (campaigns !== undefined) options.campaigns = campaigns;
+  return cms.client(options);
+}
+
+/** `decided` over `preview`, name by name; `undefined` when neither has any. */
+function over(
+  preview: Readonly<Record<string, boolean>> | undefined,
+  decided: Readonly<Record<string, boolean>> | undefined,
+): Record<string, boolean> | undefined {
+  if (preview === undefined && decided === undefined) return undefined;
+  return { ...preview, ...decided };
+}
+
+/**
+ * The content client of a page on the assignments route
+ * (`app/%5Fassignments/[assignments]/[[...path]]`, which the proxy's
+ * `rewriteToAssignmentsRoute` rewrites the CMS's pages to): the current
+ * release, read as `cms.client({ experiments, campaigns })` with every test
+ * and campaign the path's segment names on or off as the proxy decided, and
+ * no visitor. The proxy decides, the page renders that, reading no request,
+ * so Next can cache it (ISR, `revalidate = 600`). A test at 0% stays off
+ * whatever the path names, and a test or a campaign the content doesn't have
+ * stays out, never an error: a 404 here would be cached under the path by
+ * Next. `null` only when the segment isn't one the proxy writes: the page
+ * answers with `notFound()`.
+ *
+ * ```tsx
+ * export const revalidate = 600;
+ * export async function generateStaticParams() {
+ *   return [];
+ * }
+ * export default async function Page({ params }) {
+ *   const { assignments, path } = await params;
+ *   const client = await assignedClient(cms, assignments);
+ *   if (!client) notFound();
+ *   …
+ * }
+ * ```
  */
-export function contentClient(cms: Pick<CMS, "forDraft" | "forRelease">): Client {
-  const pointer = activeDraftPointer();
-  return pointer ? cms.forDraft(pointer) : cms.forRelease();
+export async function assignedClient(
+  cms: Pick<CMS, "client" | "forRelease">,
+  segment: string,
+): Promise<Client | null> {
+  const parsed = parseAssignmentsSegment(segment);
+  if (parsed === null) return null;
+  const assignments: PathAssignments = await withoutDarkTests(cms, parsed);
+  return cms.client({ experiments: assignments.experiments, campaigns: assignments.campaigns });
 }

package/src/server/slot.ts

@@ -1,14 +1,42 @@
 /**
- * The draft a request renders, held for the request's Server Components.
- * React's `cache()` gives one slot per request in the React Server
+ * What a request renders, held for the request's Server Components: the
+ * version (a draft, or an old release, with its preview's moment and switched
+ * tests and campaigns), the visitor and the tests and campaigns the proxy
+ * decided. React's `cache()` gives one slot per request in the React Server
  * Components graph, the scope a draft needs; no `next/headers` here, so the
  * root components can read it without binding anything.
  */
+import type { RequestVersion } from "@decocms/blocks";
+import type { Visitor } from "@decocms/blocks/experiments";
 import { cache } from "react";
+import type { PathAssignments } from "../assignments.ts";
 
-export const draftSlot = cache((): { pointer: string | null } => ({ pointer: null }));
+interface DraftSlot {
+  version: RequestVersion | null;
+  visitor: Visitor | null;
+  assignments: PathAssignments | null;
+  /** The link named a draft that can't be read anymore: the page renders the release. */
+  unavailable: boolean;
+  /** The request's release check (`cms.checkRelease()`), which its draft reads wait for. */
+  releaseCheck: string | null;
+}
+
+export const draftSlot = cache(
+  (): DraftSlot => ({
+    version: null,
+    visitor: null,
+    assignments: null,
+    unavailable: false,
+    releaseCheck: null,
+  }),
+);
 
-/** The draft pointer bound to this request (`bindDraft`), or `null` when it renders the release. */
+/** The version bound to this request (`bindDraft`), or `null` when it renders the current release. */
 export function activeDraftPointer(): string | null {
-  return draftSlot().pointer;
+  return draftSlot().version?.version ?? null;
+}
+
+/** Whether the request's link named a draft that can't be read anymore (`bindDraft`). */
+export function draftUnavailable(): boolean {
+  return draftSlot().unavailable;
 }

package/src/visitor.ts

@@ -0,0 +1,16 @@
+/**
+ * How the proxy hands the pages the visitor: the request header it forwards
+ * once it read the visitor (`readVisitor` from `@decocms/blocks/experiments`,
+ * a new one on a first visit). The proxy writes it (`visitorRequestHeaders`
+ * from `@decocms/nextjs/proxy`); the pages read it (`bindDraft`, then
+ * `contentClient`, from `@decocms/nextjs/server`). The package's own copy: it
+ * never imports `@decocms/tanstack`. No imports, no state: safe in every
+ * bundle.
+ */
+
+/**
+ * The request header carrying the visitor, in its stored form (the
+ * `deco_segment` cookie's value, `serializeVisitor`). The proxy removes any
+ * copy that arrives from outside (`draftRequestHeaders`).
+ */
+export const VISITOR_HEADER = "x-deco-visitor";