@timber-js/app 0.2.0-alpha.158 → 0.2.0-alpha.159

package/src/server/prebuilt-builder.ts

@@ -0,0 +1,640 @@
+/**
+ * Prebuilt payload capture — the post-build half of cache.component
+ * (TIM-1119, design/44-render-at-build-time.md §Build Phase).
+ *
+ * Runs AFTER Vite's 5-step build sequence, INSIDE the built RSC bundle:
+ * the component registry, the ALS instances, and the flight renderer are
+ * module instances in the bundle's graph, so the capture pass must share
+ * that graph — `server/rsc-entry/index.ts` re-exports this module's
+ * entry point as `__timber_capturePrebuilt`, and the timber-prebuilt
+ * plugin imports the built `rsc/index.js` and calls it.
+ *
+ * Per candidate route (a page with prebuilt components attributed by the
+ * build-time module-graph walk):
+ *
+ *   1. Load the page module (+ layout-chain modules that declare prebuilt
+ *      components) — module evaluation registers `__prebuilt` components.
+ *   2. Enumerate param combos: `generateStaticSegmentParams()` for dynamic
+ *      routes, the single empty combo for static routes.
+ *   3. Per combo, reconstruct the URL and run the REAL request-time pair —
+ *      `matchRoute` + `coerceSegmentParams` — so codec-coerced params hash
+ *      byte-identically to a live request. `computeComponentCacheKey` is
+ *      the single shared implementation (design/44 §Cache Key).
+ *   4. Render each registered component in isolation under a synthetic ALS
+ *      store (segment params only; cookies/headers/searchParams are hard
+ *      errors — synthetic-store.ts), fully drain the flight stream, and
+ *      smoke-revive the captured bytes once before accepting them.
+ *   5. Hand each payload to the caller's sink. Persistence (atomic file
+ *      writes, manifest.json) is the PLUGIN's job on the Node side —
+ *      keeping node:fs out of the server bundle, which must also run on
+ *      Cloudflare Workers.
+ *
+ * No payload source is registered while this runs, so wrappers rendered
+ * inside a captured subtree always miss and render live — inner output is
+ * baked flat into the outer entry, which is exactly the nesting clamp of
+ * design/45 §Nesting Semantics. The capture pass detects and reports the
+ * clamp (and fails cyclic entries) via capture-state.ts.
+ *
+ * Error policy (design/44 §Build-Phase Error Handling):
+ *   - `BuildTimeContextError` (cookies/headers/searchParams at build time)
+ *     → HARD error; the caller must fail the build.
+ *   - Anything else (bad data, deny(), cycles, timeouts, revival failures)
+ *     → skip that entry, warn, keep building.
+ */
+
+import { createElement } from 'react';
+
+import { requestContextAls } from './als-registry.js';
+import { ParamCoercionError } from './route-element-builder.js';
+import { coerceSegmentParams } from './param-coercion.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
+import {
+  beginCapture,
+  endCapture,
+  PrebuiltCaptureCycleError,
+  type NestedWrapperRender,
+} from './prebuilt/capture-state.js';
+import { computeComponentCacheKey } from './prebuilt/cache-key.js';
+import { BuildTimeContextError, createBuildTimeStore } from './prebuilt/synthetic-store.js';
+import {
+  getPrebuiltRegistration,
+  type PrebuiltComponentOptions,
+  type PrebuiltRegistration,
+} from './prebuilt-runtime.js';
+import { createRouteMatcher } from './route-matcher.js';
+import type { ManifestFile, ManifestRoot, ManifestSegmentNode } from './route-matcher.js';
+import { createFromReadableStream, renderToReadableStream } from '../rsc-runtime/rsc.js';
+import { loadModule } from './safe-load.js';
+import { hasDynamicSegments, resolvePathWithParams } from './sitemap-generator.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** One captured flight payload, ready for the caller's persistence sink. */
+export interface CapturedEntry {
+  componentId: string;
+  /** `computeComponentCacheKey(callSiteProps, coercedParams)` — names the .flight file. */
+  cacheKey: string;
+  /** The raw param combo (JSON-safe) — manifest metadata, not the hash input. */
+  params: Record<string, string | string[]>;
+  /** Call-site props used for this entry (empty object for zero-prop usages). */
+  props?: Record<string, unknown>;
+  bytes: Uint8Array;
+  /** Resolved tags from callsite options — static or function-form, evaluated at capture time. */
+  tags?: string[];
+}
+
+/** A per-entry problem — either a skip (build continues) or a hard error. */
+export interface CaptureIssue {
+  componentId: string;
+  routeUrlPath: string;
+  params: Record<string, string | string[]>;
+  message: string;
+}
+
+export interface CaptureSummary {
+  /** Entries captured, smoke-revived, and accepted by the sink. */
+  captured: number;
+  /** Skipped entries — reported, build continues (design/44 policy). */
+  skipped: CaptureIssue[];
+  /** Dynamic-context violations — the caller MUST fail the build. */
+  hardErrors: CaptureIssue[];
+  /** Nesting-clamp warnings emitted (design/45 §Nesting Semantics). */
+  nestingWarnings: number;
+}
+
+export interface CaptureOptions {
+  /**
+   * Route file path (page or layout, absolute) → prebuilt component IDs
+   * transitively reachable from it. Computed by the timber-prebuilt
+   * plugin's RSC module-graph walk at generateBundle time.
+   */
+  fileComponentMap: Record<string, string[]>;
+  /**
+   * Component ID → array of distinct static call-site prop objects captured
+   * from JSX usage sites (design/44 §Props Derivation). Each entry renders
+   * one payload per (props, params) combination. Components with no captured
+   * props (zero-prop usages) render with `{}` — the pre-TIM-1142 behavior.
+   */
+  callSiteProps?: Record<string, Record<string, unknown>[]>;
+  /**
+   * Persistence sink, called once per accepted payload. Throws propagate
+   * and abort the capture — a failed artifact write is an infrastructure
+   * failure, not a per-entry data problem.
+   */
+  onEntry: (entry: CapturedEntry) => Promise<void>;
+  /**
+   * Per-entry ceiling on render + drain. A component that hangs (stalled
+   * fetch, unbounded recursion the cycle guard can't see) fails its entry
+   * instead of hanging the whole build — the A2 stream-read rule from
+   * design/13-security.md applied to the build process.
+   */
+  renderTimeoutMs?: number;
+  /** Progress/warning logger. Defaults to console.warn. */
+  log?: (message: string) => void;
+}
+
+const DEFAULT_RENDER_TIMEOUT_MS = 30_000;
+
+// ─── Route collection ─────────────────────────────────────────────────────
+
+interface CandidateRoute {
+  urlPath: string;
+  page: ManifestFile;
+  /** Layout files along the chain that declare prebuilt components. */
+  layoutsToLoad: ManifestFile[];
+  /** Component IDs attributed to this route's page + layout chain. */
+  componentIds: string[];
+}
+
+/**
+ * Walk the manifest tree and collect pages whose file chain (page +
+ * layouts above it) has prebuilt components attributed to it. Slots and
+ * intercepting/private segments are not walked — slot-scoped prebuilt is
+ * already unkeyable at request time when slot params diverge (see
+ * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
+ * slots either.
+ */
+function collectCandidateRoutes(
+  root: ManifestSegmentNode,
+  fileComponentMap: Record<string, string[]>
+): CandidateRoute[] {
+  const routes: CandidateRoute[] = [];
+
+  const walk = (node: ManifestSegmentNode, layoutChain: ManifestFile[]) => {
+    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
+    const chain = node.layout ? [...layoutChain, node.layout] : layoutChain;
+
+    if (node.page) {
+      const componentIds = new Set<string>();
+      for (const file of [...chain, node.page]) {
+        for (const id of fileComponentMap[file.filePath] ?? []) componentIds.add(id);
+      }
+      if (componentIds.size > 0) {
+        routes.push({
+          urlPath: node.urlPath,
+          page: node.page,
+          layoutsToLoad: chain.filter((l) => (fileComponentMap[l.filePath] ?? []).length > 0),
+          componentIds: Array.from(componentIds),
+        });
+      }
+    }
+
+    for (const child of node.children) walk(child, chain);
+  };
+
+  walk(root, []);
+  return routes;
+}
+
+// ─── Param enumeration ────────────────────────────────────────────────────
+
+type ParamCombo = Record<string, string | string[]>;
+
+/**
+ * Resolve the param combos to capture for a route. Static routes have
+ * exactly one combo (the empty record) — `export const prerender`-style
+ * components on static pages need no enumerator. Dynamic routes require
+ * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
+ * without it every request renders live and the wrapper is a no-op.
+ */
+async function enumerateCombos(
+  route: CandidateRoute,
+  pageModule: Record<string, unknown>,
+  log: (message: string) => void
+): Promise<ParamCombo[] | null> {
+  if (!hasDynamicSegments(route.urlPath)) return [{}];
+
+  let generateFn = pageModule.generateStaticSegmentParams;
+  if (typeof generateFn !== 'function' && typeof pageModule.generateStaticParams === 'function') {
+    generateFn = pageModule.generateStaticParams;
+    log(
+      `[timber] ${route.page.filePath}: generateStaticParams is deprecated — rename to generateStaticSegmentParams`
+    );
+  }
+  if (typeof generateFn !== 'function') {
+    log(
+      `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +
+        `generateStaticSegmentParams export — all its entries will render dynamically ` +
+        `until the page declares its param combos`
+    );
+    return null;
+  }
+  const combos: unknown = await (generateFn as () => unknown)();
+  if (!Array.isArray(combos)) {
+    throw new Error(
+      `generateStaticSegmentParams must return an array of param records, got ${typeof combos}`
+    );
+  }
+  return combos as ParamCombo[];
+}
+
+// ─── Rendering ────────────────────────────────────────────────────────────
+
+/** Concatenate drained chunks without Buffer (the bundle also runs on Workers). */
+function concatChunks(chunks: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const chunk of chunks) total += chunk.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+
+/**
+ * Drain a flight stream to completion under a deadline. On timeout the
+ * reader is cancelled (never abandoned mid-read — design/13 A2/A3) and
+ * the entry fails.
+ */
+async function drainWithTimeout(
+  stream: ReadableStream<Uint8Array>,
+  timeoutMs: number
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      reject(new Error(`render did not complete within ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    for (;;) {
+      const { done, value } = await Promise.race([reader.read(), deadline]);
+      if (done) break;
+      chunks.push(value as Uint8Array);
+    }
+  } finally {
+    clearTimeout(timer);
+    if (timedOut) await reader.cancel().catch(() => {});
+  }
+  return concatChunks(chunks);
+}
+
+/** Wrap payload bytes as a single-chunk stream for the smoke revival. */
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * View of a registered component that satisfies createElement — same
+ * narrowing rationale as prebuilt-runtime.ts.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RenderableComponent = (props: any) => React.ReactNode;
+
+interface EntryOutcome {
+  bytes: Uint8Array | null;
+  failure: unknown;
+  nested: NestedWrapperRender[];
+  resolvedTags: string[] | undefined;
+}
+
+/**
+ * Render one (component, props, coerced-params) entry in isolation and drain
+ * its flight payload. Any `onError` during serialization fails the entry —
+ * a payload with an embedded error row would replay that error on every
+ * future request, so only fully clean renders are captured.
+ */
+async function renderEntry(
+  registration: PrebuiltRegistration,
+  props: Record<string, unknown>,
+  coercedParams: Record<string, string | string[]>,
+  timeoutMs: number
+): Promise<EntryOutcome> {
+  const { store, violations } = createBuildTimeStore(registration.id, coercedParams);
+  let failure: unknown = null;
+
+  beginCapture(registration.id);
+  let bytes: Uint8Array | null = null;
+  let resolvedTags: string[] | undefined;
+  let nested: NestedWrapperRender[];
+  try {
+    // Render AND drain inside one ALS scope: flight executes components
+    // lazily as the stream is pulled, and each pull must still see the
+    // synthetic store (segmentParams.get() inside the component).
+    // Tag resolution also runs inside this scope so function-form tags
+    // that read segment params see the synthetic store (codex P2 on PR #858).
+    bytes = await requestContextAls.run(store, async () => {
+      const stream = renderToReadableStream(
+        createElement(registration.component as RenderableComponent, props),
+        {
+          onError(error: unknown) {
+            failure ??= error ?? new Error('unknown render error');
+            // Digest string keeps flight from warning about a missing
+            // digest; the payload is discarded because `failure` is set.
+            return 'timber-prebuilt-capture-error';
+          },
+        }
+      );
+      const drained = await drainWithTimeout(stream, timeoutMs);
+      resolvedTags = resolveCapturedTags(registration.options, props);
+      return drained;
+    });
+  } catch (error) {
+    // Sync component throw (renderToReadableStream creation), drain
+    // timeout, or stream error.
+    failure ??= error;
+  } finally {
+    nested = endCapture();
+  }
+
+  // Side-channel check FIRST: a component that touched per-request context
+  // is a hard error even when it caught the throw and rendered a fallback —
+  // accepting that payload would bake the request-dependent branch for
+  // every future request (codex P1 on PR #836).
+  if (violations.length > 0) return { bytes: null, failure: violations[0], nested, resolvedTags };
+  if (failure !== null) return { bytes: null, failure, nested, resolvedTags };
+  return { bytes, failure: null, nested, resolvedTags };
+}
+
+/** Human-readable classification for a failed entry. */
+function describeFailure(error: unknown): string {
+  if (error instanceof DenySignal) return `component called deny(${error.status})`;
+  if (error instanceof RedirectSignal) return `component called redirect("${error.location}")`;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+// ─── Nesting clamp warnings (design/45 §Nesting Semantics) ────────────────
+
+/** Render a lifetime declaration for the clamp warning. */
+function describeLifetime(options: PrebuiltComponentOptions): string {
+  const parts: string[] = [];
+  if (options.prerender) parts.push('prerender');
+  if (options.ttl !== undefined) parts.push(`ttl: ${options.ttl}`);
+  if (options.tags !== undefined) {
+    parts.push(
+      typeof options.tags === 'function' ? 'tags: fn' : `tags: ${JSON.stringify(options.tags)}`
+    );
+  }
+  return parts.join(', ') || 'no lifetime';
+}
+
+/**
+ * Warn when an inner wrapped component declares a refresh channel the
+ * enclosing prerendered entry cannot honor. The outer here is always
+ * prerender-tier (that's all the build captures), whose effective
+ * lifetime is deploy-long with no tags — so ANY inner ttl/tags warns.
+ * Once per (outer, inner) pair per build.
+ */
+function warnNestingClamps(
+  outerId: string,
+  nested: NestedWrapperRender[],
+  warnedPairs: Set<string>,
+  log: (message: string) => void
+): number {
+  let count = 0;
+  for (const { innerId, options } of nested) {
+    if (options.ttl === undefined && options.tags === undefined) continue;
+    const pairKey = `${outerId}${innerId}`;
+    if (warnedPairs.has(pairKey)) continue;
+    warnedPairs.add(pairKey);
+    count++;
+    log(
+      `[timber] ${innerId} (${describeLifetime(options)}) is embedded in prerendered ` +
+        `${outerId} — the embedded copy refreshes only when ${outerId} does (on redeploy). ` +
+        `Runtime revalidation will NOT update the embedded copy; tag ${outerId} itself if ` +
+        `you need that. Chain: ${outerId} (prerender) → ${innerId} (${describeLifetime(options)})`
+    );
+  }
+  return count;
+}
+
+// ─── Capture orchestration ────────────────────────────────────────────────
+
+/** Resolve tags from callsite options — static arrays pass through, function tags are evaluated with the capture-time props. */
+function resolveCapturedTags(
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): string[] | undefined {
+  if (!options.tags) return undefined;
+  const resolved = typeof options.tags === 'function' ? options.tags(props) : options.tags;
+  return resolved.length > 0 ? resolved : undefined;
+}
+
+/**
+ * Capture flight payloads for every attributed, registered, prerender-tier
+ * component across the route manifest. See module docblock for the flow.
+ */
+export async function capturePrebuiltPayloads(
+  manifest: ManifestRoot,
+  options: CaptureOptions
+): Promise<CaptureSummary> {
+  const log = options.log ?? ((message: string) => console.warn(message));
+  const timeoutMs = options.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
+  const matchRoute = createRouteMatcher(manifest);
+
+  const summary: CaptureSummary = { captured: 0, skipped: [], hardErrors: [], nestingWarnings: 0 };
+  const seenEntries = new Set<string>();
+  const warnedPairs = new Set<string>();
+  const reportedMissingRegistrations = new Set<string>();
+
+  const skip = (issue: CaptureIssue) => {
+    summary.skipped.push(issue);
+    log(
+      `[timber] cache.component skipped "${issue.componentId}" for ${issue.routeUrlPath} ` +
+        `${JSON.stringify(issue.params)} — ${issue.message}`
+    );
+  };
+
+  for (const route of collectCandidateRoutes(manifest.root, options.fileComponentMap)) {
+    // Load the page + prebuilt-declaring layout modules. Evaluation is what
+    // registers module-scope __prebuilt components (design/44 §Registration).
+    let pageModule: Record<string, unknown>;
+    try {
+      pageModule = await loadModule(route.page);
+      for (const layout of route.layoutsToLoad) await loadModule(layout);
+    } catch (error) {
+      for (const componentId of route.componentIds) {
+        skip({
+          componentId,
+          routeUrlPath: route.urlPath,
+          params: {},
+          message: describeFailure(error),
+        });
+      }
+      continue;
+    }
+
+    let combos: ParamCombo[] | null;
+    try {
+      combos = await enumerateCombos(route, pageModule, log);
+    } catch (error) {
+      for (const componentId of route.componentIds) {
+        skip({
+          componentId,
+          routeUrlPath: route.urlPath,
+          params: {},
+          message: describeFailure(error),
+        });
+      }
+      continue;
+    }
+    if (combos === null) continue;
+
+    for (const combo of combos) {
+      if (combo === null || typeof combo !== 'object' || Array.isArray(combo)) {
+        skip({
+          componentId: route.componentIds[0],
+          routeUrlPath: route.urlPath,
+          params: {},
+          message: `generateStaticSegmentParams returned a non-object combo: ${JSON.stringify(combo)}`,
+        });
+        continue;
+      }
+      // Reconstruct the URL and run the request-time matcher + coercion so
+      // the params record — and therefore the cache key — is byte-identical
+      // to what a live request for this combo produces.
+      const path = resolvePathWithParams(route.urlPath, combo);
+      if (path === null) {
+        skip({
+          componentId: route.componentIds[0],
+          routeUrlPath: route.urlPath,
+          params: combo,
+          message: 'param combo is missing a required dynamic segment value',
+        });
+        continue;
+      }
+      const match = matchRoute(path);
+      if (
+        !match ||
+        match.segments[match.segments.length - 1]?.page?.filePath !== route.page.filePath
+      ) {
+        skip({
+          componentId: route.componentIds[0],
+          routeUrlPath: route.urlPath,
+          params: combo,
+          message: `resolved URL "${path}" does not match this route (another route shadows it)`,
+        });
+        continue;
+      }
+      try {
+        await coerceSegmentParams(match);
+      } catch (error) {
+        skip({
+          componentId: route.componentIds[0],
+          routeUrlPath: route.urlPath,
+          params: combo,
+          message:
+            error instanceof ParamCoercionError
+              ? `param coercion rejected the combo: ${error.message}`
+              : describeFailure(error),
+        });
+        continue;
+      }
+      const coercedParams = match.segmentParams;
+
+      for (const componentId of route.componentIds) {
+        const registration = getPrebuiltRegistration(componentId);
+        if (!registration) {
+          if (!reportedMissingRegistrations.has(componentId)) {
+            reportedMissingRegistrations.add(componentId);
+            skip({
+              componentId,
+              routeUrlPath: route.urlPath,
+              params: combo,
+              message:
+                'attributed to this route but never registered at module load — the ' +
+                'declaring module is probably loaded via dynamic import; it will render live',
+            });
+          }
+          continue;
+        }
+        // Runtime tier (ttl/tags without prerender) does no build work.
+        if (registration.options.prerender !== true) continue;
+
+        // One entry per distinct call-site props object (design/44 §Props
+        // Derivation, TIM-1142). When no call-site props were captured,
+        // render with empty props (the pre-TIM-1142 behavior). When
+        // captured props exist, render ONLY those — a spurious {} render
+        // on a component that always receives props could hit a throw
+        // path (e.g., required prop access) and fail the build for a
+        // shape no JSX call site actually uses.
+        const capturedProps = options.callSiteProps?.[componentId];
+        const propsSets: Record<string, unknown>[] =
+          capturedProps && capturedProps.length > 0 ? [...capturedProps] : [{}];
+
+        for (const callSiteProps of propsSets) {
+          const cacheKey = computeComponentCacheKey(callSiteProps, coercedParams);
+          if (cacheKey === null) {
+            skip({
+              componentId,
+              routeUrlPath: route.urlPath,
+              params: combo,
+              message:
+                'coerced segment params are unkeyable (see design/44 §Cache Key) — ' +
+                'requests will always render live',
+            });
+            continue;
+          }
+          const entryKey = `${componentId}${cacheKey}`;
+          if (seenEntries.has(entryKey)) continue;
+          seenEntries.add(entryKey);
+
+          const outcome = await renderEntry(registration, callSiteProps, coercedParams, timeoutMs);
+          summary.nestingWarnings += warnNestingClamps(
+            componentId,
+            outcome.nested,
+            warnedPairs,
+            log
+          );
+
+          if (outcome.failure !== null) {
+            const issue: CaptureIssue = {
+              componentId,
+              routeUrlPath: route.urlPath,
+              params: combo,
+              message: describeFailure(outcome.failure),
+            };
+            if (outcome.failure instanceof BuildTimeContextError) {
+              summary.hardErrors.push(issue);
+              log(`[timber] BUILD ERROR: ${issue.message}`);
+            } else {
+              skip(issue);
+            }
+            continue;
+          }
+
+          // Write-time integrity: revive the captured bytes once, exactly the
+          // way the request path will, before accepting them. Corrupt or
+          // truncated captures fail HERE, at build time — the request path
+          // trusts artifacts the way it trusts JS chunks in the same deploy.
+          try {
+            await createFromReadableStream(bytesToStream(outcome.bytes!));
+          } catch (error) {
+            skip({
+              componentId,
+              routeUrlPath: route.urlPath,
+              params: combo,
+              message: `captured payload failed smoke revival: ${describeFailure(error)}`,
+            });
+            continue;
+          }
+
+          const hasProps = Object.keys(callSiteProps).length > 0;
+          await options.onEntry({
+            componentId,
+            cacheKey,
+            params: combo,
+            ...(hasProps ? { props: callSiteProps } : {}),
+            bytes: outcome.bytes!,
+            tags: outcome.resolvedTags,
+          });
+          summary.captured++;
+        }
+      }
+    }
+  }
+
+  return summary;
+}