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

package/src/server/prebuilt/payload-source.ts

@@ -0,0 +1,192 @@
+/**
+ * Prebuilt payload source — the adapter seam through which the runtime
+ * reads build-time flight artifacts (`.timber/dist/prebuilt/`).
+ *
+ * The runtime never touches the filesystem directly: adapters register a
+ * source at startup (Node: fs reads; Cloudflare: the assets binding —
+ * design/44-render-at-build-time.md §Adapter Integration). Artifacts are
+ * produced by the post-build capture pass (TIM-1119, prebuilt-builder.ts);
+ * adapter registration of the source is TIM-1122. Until a source is
+ * registered (adapter not wired yet, dev mode, no artifacts built), every
+ * lookup misses and cache.component wrappers render live — the designed
+ * dynamic-fallback behavior.
+ *
+ * Phase 3 (design/45 runtime tier) inserts the CacheHandler overlay lookup
+ * in front of `lookupPrebuiltPayload` — overlay first, then artifact. The
+ * single-lookup-function shape here is that seam.
+ */
+
+import { initTagIndex, resetTagIndex } from './overlay.js';
+
+export interface PrebuiltManifestEntry {
+  /** Segment params this entry was captured under. */
+  params: Record<string, string | string[]>;
+  /** Payload path relative to the prebuilt/ directory. */
+  file: string;
+  /** Payload size in bytes (build report / diagnostics). */
+  bytes?: number;
+  /** Runtime invalidation tags (design/45 ISR tier). */
+  tags?: string[];
+  /** Epoch ms when this entry was captured (seed freshness for ISR). */
+  buildTimestamp?: number;
+}
+
+export interface PrebuiltManifest {
+  [componentId: string]: {
+    entries: Record<string, PrebuiltManifestEntry>;
+  };
+}
+
+export interface PrebuiltPayloadSource {
+  /** Load prebuilt/manifest.json. Null when no artifacts exist. */
+  loadManifest(): Promise<PrebuiltManifest | null>;
+  /** Read a `.flight` payload by manifest file path. Null when missing. */
+  readPayload(file: string): Promise<Uint8Array | null>;
+}
+
+let source: PrebuiltPayloadSource | null = null;
+let manifestPromise: Promise<PrebuiltManifest | null> | null = null;
+
+/**
+ * Ceiling on the memoized manifest load. Without it, a stalled
+ * `loadManifest()` would leave `manifestPromise` pending forever and every
+ * subsequent cache.component render would await the same hung promise —
+ * the coalesced-promise deadlock class from design/13-security.md (A5).
+ * On expiry the load memoizes as null (permanent dynamic fallback, same
+ * policy as a failed load) and callers proceed immediately.
+ */
+const MANIFEST_LOAD_TIMEOUT_MS = 5_000;
+
+/**
+ * Per-read ceiling on payload reads. The read is awaited inside a server
+ * component render — a stalled adapter promise would otherwise hang the
+ * RSC stream until the render timeout kills the whole page, when the
+ * correct degradation is a miss → live render (codex review round 4 on
+ * PR #835).
+ */
+const PAYLOAD_READ_TIMEOUT_MS = 5_000;
+
+/** Race a source promise against a timeout that resolves to `fallback`. */
+async function withTimeout<T>(
+  work: Promise<T>,
+  timeoutMs: number,
+  fallback: T,
+  onTimeout: () => void
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<T>((resolve) => {
+        timer = setTimeout(() => {
+          onTimeout();
+          resolve(fallback);
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function loadManifestWithTimeout(
+  src: PrebuiltPayloadSource
+): Promise<PrebuiltManifest | null> {
+  let manifest: PrebuiltManifest | null;
+  try {
+    manifest = await withTimeout(src.loadManifest(), MANIFEST_LOAD_TIMEOUT_MS, null, () => {
+      console.error(
+        `[timber] prebuilt manifest load exceeded ${MANIFEST_LOAD_TIMEOUT_MS}ms — all cache.component lookups will render dynamically`
+      );
+    });
+  } catch (error) {
+    console.error(
+      '[timber] failed to load prebuilt manifest — all cache.component lookups will miss:',
+      error
+    );
+    return null;
+  }
+  if (manifest) {
+    initTagIndex(manifest);
+  }
+  return manifest;
+}
+
+/**
+ * Register the payload source. Called once at server startup by the
+ * adapter/entry wiring (TIM-1122); tests inject fakes. Passing null
+ * unregisters (and drops the memoized manifest).
+ */
+export function setPrebuiltPayloadSource(next: PrebuiltPayloadSource | null): void {
+  source = next;
+  manifestPromise = null;
+  if (!next) resetTagIndex();
+}
+
+/**
+ * Whether a source is registered — the gate for both marker emission and
+ * splice-transform installation. False means zero prebuilt overhead.
+ */
+export function hasPrebuiltPayloadSource(): boolean {
+  return source !== null;
+}
+
+/**
+ * Ensure the manifest is loaded (and the tag index initialized). No-op
+ * when no source is registered. Used by the tombstone path to avoid
+ * skipping tombstones on cold processes where the first request is an
+ * action rather than a page render.
+ */
+export async function ensureManifestLoaded(): Promise<void> {
+  if (source === null) return;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  await manifestPromise;
+}
+
+/**
+ * Look up a manifest entry (metadata only, no payload read).
+ * Used by the overlay to check seed existence and freshness.
+ */
+export async function getManifestEntry(
+  componentId: string,
+  cacheKey: string
+): Promise<PrebuiltManifestEntry | null> {
+  if (source === null) return null;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  return manifest?.[componentId]?.entries?.[cacheKey] ?? null;
+}
+
+/**
+ * Look up a cached payload: manifest entry → payload bytes.
+ * Null on any miss or read failure — callers fall back to live render.
+ *
+ * The manifest is loaded once and memoized (design/44 §manifest.json:
+ * loaded at startup, held in memory; payloads read on demand). A failed
+ * manifest load is memoized as null rather than retried per-request — a
+ * broken artifact should degrade to dynamic rendering, not add a failing
+ * read to every request.
+ */
+export async function lookupPrebuiltPayload(
+  componentId: string,
+  cacheKey: string
+): Promise<Uint8Array | null> {
+  if (source === null) return null;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  const entry = manifest?.[componentId]?.entries?.[cacheKey];
+  if (!entry) return null;
+  try {
+    return await withTimeout(source.readPayload(entry.file), PAYLOAD_READ_TIMEOUT_MS, null, () => {
+      console.error(
+        `[timber] prebuilt payload read for "${entry.file}" exceeded ${PAYLOAD_READ_TIMEOUT_MS}ms — rendering dynamically`
+      );
+    });
+  } catch (error) {
+    console.error(
+      `[timber] failed to read prebuilt payload "${entry.file}" for ${componentId} — rendering dynamically:`,
+      error
+    );
+    return null;
+  }
+}

package/src/server/prebuilt/synthetic-store.ts

@@ -0,0 +1,108 @@
+/**
+ * Synthetic ALS store for build-time capture (design/44 §Param Injection).
+ *
+ * Each param combo renders inside a `RequestContextStore` that provides
+ * segment params and NOTHING else. Every per-request API is a hard error,
+ * never a silent empty value — a component that branches on a header
+ * (locale, experiment, auth state) must fail the build, not bake the
+ * "header absent" branch into the cache for every future request:
+ *
+ * - `segmentParams.get()` works — reads from this store
+ * - `cookies()` / `headers()` / `searchParams` throw `BuildTimeContextError`
+ *
+ * The enforcement lives in the store's own fields (recording accessors)
+ * rather than in request-context.ts / cookie-context.ts, so the request
+ * path pays nothing and those modules stay untouched. The per-request
+ * fields — `headers`, `parsedCookies`, `searchParams` — are getters that
+ * record a violation and throw, so the CALL itself (`getHeaders()`,
+ * `getCookieJar()`, `getSearchParams()`) is the build error, not some
+ * later member read; merely obtaining and passing the object around is
+ * already outside the build-time contract (codex P2 round 5 on PR #836).
+ * `mutableContext` gets the same treatment because cookie MUTATORS reach
+ * it (via cookie-context's assertMutable, its only reader) before any
+ * other store field (codex P2 round 4).
+ *
+ * Every violation is recorded in a side channel BEFORE the throw — a
+ * component that catches the error (`try { headers() } catch { fallback }`)
+ * still fails its entry; accepting that render would silently bake the
+ * request-dependent fallback branch into the payload (codex P1 on PR #836).
+ * The capture pass checks the side channel after every render.
+ *
+ * This is safe precisely because capture renders the bare component
+ * element — no pipeline, no SSR bridge, no action machinery — so the only
+ * code that can reach these fields during a capture is the component
+ * itself (via the public accessors).
+ */
+
+import type { RequestContextStore } from '../als-registry.js';
+
+/**
+ * Thrown when a prerendered component touches per-request context at
+ * build time. The capture pass treats this as a HARD build error —
+ * it indicates a design mistake, not transient bad data (design/44
+ * §Build-Phase Error Handling).
+ */
+export class BuildTimeContextError extends Error {
+  /** The per-request API that was called (e.g. "cookies()"). */
+  readonly api: string;
+
+  constructor(componentId: string, api: string) {
+    super(
+      `[timber] cache.component "${componentId}": ${api} cannot be used in a ` +
+        `prerendered component — there is no request at build time. Prerendered ` +
+        `components may read segment params and timber.cache data only. Remove the ` +
+        `${api} call, or drop { prerender: true } and render this component ` +
+        `per-request. (design/44-render-at-build-time.md §Param Injection)`
+    );
+    this.name = 'BuildTimeContextError';
+    this.api = api;
+  }
+}
+
+/** A synthetic store plus the side channel its accessors report into. */
+export interface BuildTimeStoreHandle {
+  store: RequestContextStore;
+  /**
+   * Every per-request API access during the render, recorded even when
+   * the accompanying throw was caught by user code. Non-empty after the
+   * render ⇒ the entry must fail as a hard build error.
+   */
+  violations: BuildTimeContextError[];
+}
+
+/**
+ * Create the synthetic per-combo store. `segmentParams` must already be
+ * coerced through the route's codecs — cache-key parity with request time
+ * depends on hashing the exact record `coerceSegmentParams` produces.
+ */
+export function createBuildTimeStore(
+  componentId: string,
+  segmentParams: Record<string, string | string[]>
+): BuildTimeStoreHandle {
+  const violations: BuildTimeContextError[] = [];
+  const store: RequestContextStore = {
+    headers: new Headers(),
+    originalHeaders: new Headers(),
+    cookieHeader: '',
+    searchParams: new URLSearchParams(),
+    searchString: '',
+    segmentParams,
+    cookieJar: new Map(),
+    flushed: false,
+    mutableContext: false,
+  };
+  const violate = (api: string): never => {
+    const error = new BuildTimeContextError(componentId, api);
+    violations.push(error);
+    throw error;
+  };
+  Object.defineProperties(store, {
+    headers: { get: () => violate('headers()') },
+    parsedCookies: { get: () => violate('cookies()') },
+    searchParams: { get: () => violate('searchParams') },
+    // Reached by cookie mutators (set/delete/clear) via assertMutable —
+    // its only reader — before any other store field.
+    mutableContext: { get: () => violate('cookies()') },
+  });
+  return { store, violations };
+}