@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/server/prebuilt/overlay.ts

@@ -0,0 +1,256 @@
+/**
+ * Component cache overlay — runtime CacheHandler layer for ISR.
+ *
+ * Sits in front of the immutable build artifact (`.flight` files) and
+ * stores replacement payloads and tombstones via the configured
+ * CacheHandler. Overlay entries are per-deploy namespaced:
+ *   `timber:c:{deploymentId}:{componentId}:{hash}`
+ *
+ * The CacheHandler contract is untouched — tombstones and the tag index
+ * live above the interface as value conventions. Redis, KV, and custom
+ * handlers work unmodified.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+
+import { getCacheHandler, isCacheHandlerConfigured } from '../../cache/handler-store.js';
+import { MemoryCacheHandler } from '../../cache/index.js';
+import { getDeploymentId } from '../version-skew.js';
+import { buildTagIndex, type SeedKeyInfo } from './manifest-tag-index.js';
+import type { PrebuiltManifest } from './payload-source.js';
+import { ensureManifestLoaded } from './payload-source.js';
+
+/** Default ceiling TTL for tag-only entries (24 hours), in seconds. */
+const CEILING_TTL_SECONDS = 24 * 60 * 60;
+
+/** Deploy-long physical TTL for seed-backed overlay records (90 days). */
+const DEPLOY_LONG_TTL_SECONDS = 90 * 24 * 60 * 60;
+
+// ─── Overlay record shapes (value conventions above CacheHandler) ────────
+
+/**
+ * A cached component flight payload stored in the overlay.
+ * The `_t` discriminant distinguishes this from a tombstone.
+ */
+export interface ComponentOverlayRecord {
+  _t: 'co';
+  /** Base64-encoded flight payload bytes. */
+  p: string;
+  /** Logical freshness deadline (Date.now() + ttl * 1000). */
+  fu: number;
+  /** Whether a build-artifact seed exists for this key. */
+  s: boolean;
+}
+
+/**
+ * A tombstone marking a build seed as invalidated.
+ * Written by revalidateTag for seeds carrying the invalidated tag.
+ */
+export interface ComponentTombstoneRecord {
+  _t: 'ct';
+}
+
+type OverlayValue = ComponentOverlayRecord | ComponentTombstoneRecord;
+
+export function isOverlayRecord(v: unknown): v is ComponentOverlayRecord {
+  return v !== null && typeof v === 'object' && (v as Record<string, unknown>)._t === 'co';
+}
+
+export function isTombstone(v: unknown): v is ComponentTombstoneRecord {
+  return v !== null && typeof v === 'object' && (v as Record<string, unknown>)._t === 'ct';
+}
+
+// ─── Overlay key generation ──────────────────────────────────────────────
+
+export function overlayKey(componentId: string, cacheKey: string): string {
+  const deploymentId = getDeploymentId() ?? 'dev';
+  return `timber:c:${deploymentId}:${componentId}:${cacheKey}`;
+}
+
+// ─── Overlay read ────────────────────────────────────────────────────────
+
+export interface OverlayLookupResult {
+  kind: 'fresh' | 'stale' | 'tombstone';
+  /** The overlay value (null for tombstones). */
+  record: ComponentOverlayRecord | null;
+  /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
+  payload: Uint8Array | null;
+}
+
+/**
+ * Look up an overlay entry in the cache handler.
+ * Returns null on a clean miss (no overlay entry at all).
+ */
+export async function lookupOverlay(
+  componentId: string,
+  cacheKey: string
+): Promise<OverlayLookupResult | null> {
+  const handler = getCacheHandler();
+  const key = overlayKey(componentId, cacheKey);
+  const result = await handler.get(key);
+  if (!result) return null;
+
+  const value = result.value as OverlayValue;
+  if (isTombstone(value)) {
+    return { kind: 'tombstone', record: null, payload: null };
+  }
+  if (isOverlayRecord(value)) {
+    const logicallyStale = Date.now() > value.fu;
+    return {
+      kind: logicallyStale ? 'stale' : 'fresh',
+      record: value,
+      payload: base64ToBytes(value.p),
+    };
+  }
+  // Unknown value shape — treat as miss (forward compatibility).
+  return null;
+}
+
+// ─── Overlay write ───────────────────────────────────────────────────────
+
+/**
+ * Resolve the effective TTL for a component's runtime lifetime.
+ * Tag-only entries (no explicit ttl) get the ceiling TTL (design/45
+ * §Tag-only entries carry a ceiling TTL).
+ */
+export function effectiveTtl(ttl: number | undefined): number {
+  return ttl ?? CEILING_TTL_SECONDS;
+}
+
+/**
+ * Store a component flight payload in the overlay.
+ */
+export async function storeOverlayEntry(
+  componentId: string,
+  cacheKey: string,
+  payloadBytes: Uint8Array,
+  opts: {
+    ttl?: number;
+    tags: string[];
+    hasSeed: boolean;
+  }
+): Promise<void> {
+  const handler = getCacheHandler();
+  const key = overlayKey(componentId, cacheKey);
+  const logicalTtl = effectiveTtl(opts.ttl);
+  const physicalTtl = opts.hasSeed ? DEPLOY_LONG_TTL_SECONDS : logicalTtl;
+
+  const record: ComponentOverlayRecord = {
+    _t: 'co',
+    p: bytesToBase64(payloadBytes),
+    fu: Date.now() + logicalTtl * 1000,
+    s: opts.hasSeed,
+  };
+
+  await handler.set(key, record, { ttl: physicalTtl, tags: opts.tags });
+}
+
+// ─── Tombstone writes ────────────────────────────────────────────────────
+
+let tagIndex: Map<string, SeedKeyInfo[]> | null = null;
+
+/**
+ * Initialize the tag index from the prebuilt manifest. Called once when the
+ * manifest is loaded. Without a manifest (no prebuilt components), this is
+ * never called and revalidateTag skips the tombstone path entirely.
+ */
+export function initTagIndex(manifest: PrebuiltManifest): void {
+  tagIndex = buildTagIndex(manifest);
+  emitIsrDiagnosticIfNeeded(manifest);
+}
+
+/**
+ * Get the tag index, if initialized.
+ * @internal — exported for testing.
+ */
+export function getTagIndex(): Map<string, SeedKeyInfo[]> | null {
+  return tagIndex;
+}
+
+/**
+ * Reset the tag index (for tests).
+ * @internal
+ */
+export function resetTagIndex(): void {
+  tagIndex = null;
+}
+
+/**
+ * Write tombstones for all seed entries carrying the given tag.
+ * Called from cache.invalidate (cache-api.ts) AFTER the handler's own
+ * invalidation clears overlay entries.
+ *
+ * The tombstone prevents the immutable seed from being served after
+ * invalidation — without it, a handler.invalidate that clears the overlay
+ * would expose the (now-stale) build artifact on the next request.
+ *
+ * Ensures the manifest is loaded first so cold-process actions that
+ * invalidate before any page render still write tombstones.
+ */
+export async function writeTombstonesForTag(tag: string): Promise<void> {
+  if (!tagIndex) {
+    await ensureManifestLoaded();
+  }
+  if (!tagIndex) return;
+  const seeds = tagIndex.get(tag);
+  if (!seeds || seeds.length === 0) return;
+
+  const handler = getCacheHandler();
+  const tombstone: ComponentTombstoneRecord = { _t: 'ct' };
+
+  await Promise.all(
+    seeds.map((seed) => {
+      const key = overlayKey(seed.componentId, seed.cacheKey);
+      return handler.set(key, tombstone, {
+        ttl: DEPLOY_LONG_TTL_SECONDS,
+        tags: [tag],
+      });
+    })
+  );
+}
+
+// ─── ISR build diagnostic ────────────────────────────────────────────────
+
+let isrDiagnosticEmitted = false;
+
+function emitIsrDiagnosticIfNeeded(manifest: PrebuiltManifest): void {
+  if (isrDiagnosticEmitted) return;
+
+  const handler = getCacheHandler();
+  const isMemoryBased = handler instanceof MemoryCacheHandler || !isCacheHandlerConfigured();
+  if (!isMemoryBased) return;
+
+  for (const [, component] of Object.entries(manifest)) {
+    if (!component || typeof component !== 'object' || !('entries' in component)) continue;
+    for (const [, entry] of Object.entries(component.entries)) {
+      if (entry.tags && entry.tags.length > 0) {
+        isrDiagnosticEmitted = true;
+        console.warn(
+          '[timber] tag revalidation of prerendered components requires a shared cache ' +
+            'handler in multi-instance deployments. The current MemoryCacheHandler is ' +
+            'per-process — revalidateTag on one instance will not purge the build seed ' +
+            'on others. Configure a shared handler (Redis, KV) for production ISR.'
+        );
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * Reset the diagnostic flag (for tests).
+ * @internal
+ */
+export function resetIsrDiagnostic(): void {
+  isrDiagnosticEmitted = false;
+}
+
+// ─── Encoding helpers ────────────────────────────────────────────────────
+
+function bytesToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}

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

@@ -0,0 +1,201 @@
+/**
+ * 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>;
+    /** When true, the component does not read segment params — the cache key uses `{}`. */
+    paramIndependent?: boolean;
+  };
+}
+
+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 isParamIndependent(componentId: string): Promise<boolean> {
+  if (source === null) return false;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  return manifest?.[componentId]?.paramIndependent === true;
+}
+
+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,121 @@
+/**
+ * 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[];
+  /** Whether the component read `segmentParams` during the render. */
+  segmentParamsRead: boolean;
+}
+
+/**
+ * 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 handle: BuildTimeStoreHandle = {
+    store: null!,
+    violations,
+    segmentParamsRead: false,
+  };
+  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') },
+    mutableContext: { get: () => violate('cookies()') },
+    segmentParams: {
+      get: () => {
+        handle.segmentParamsRead = true;
+        return segmentParams;
+      },
+      enumerable: true,
+    },
+  });
+  handle.store = store;
+  return handle;
+}