@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/prebuilt/capture-state.ts

@@ -0,0 +1,196 @@
+/**
+ * Capture state — the channel between a payload capture and the
+ * `__prebuilt` wrappers that render inside it (server/prebuilt-runtime.ts).
+ *
+ * Two callers capture a wrapped component's flight payload:
+ *
+ * - **Build time**: the post-build capture pass (server/prebuilt-builder.ts)
+ *   renders each registry entry in turn.
+ * - **Request time**: `captureComponentPayload()` in prebuilt-runtime.ts
+ *   renders a component in isolation for an inline re-render (full miss,
+ *   stale entry, tombstone) or an SWR background re-render. These run
+ *   concurrently with other requests' renders — and with each other.
+ *
+ * During a capture, the component's subtree may render OTHER wrapped
+ * components. Those inner wrappers render live and their output is baked
+ * flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The wrapper
+ * reports every render that happens inside a capture:
+ *
+ * - **Cycle**: the inner render IS the entry being captured — same
+ *   component id AND same props key (TIM-1547). Left alone this recurses
+ *   until the render times out; instead the wrapper throws
+ *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
+ *   the cycle (build continues per doc 44 skip-and-report policy; at
+ *   request time the re-render fails and is not cached, and the wrapper
+ *   falls back as for any failed re-render). A component that renders
+ *   itself with different props (a comment thread, a tree) is legitimate
+ *   recursion with a base case and bakes flat like any other nesting.
+ * - **Nesting**: any other wrapper render is recorded per inner component
+ *   with the tags it resolved to. Both capture callers run the clamp rule
+ *   over those records when the entry completes (prebuilt/lifetime.ts).
+ *
+ * Identity is the capture ROOT only. A wrapper cannot see the wrappers
+ * between it and the root: Flight renders a component's children after
+ * the wrapper has returned, in Flight's own async context, not in a frame
+ * the wrapper could enter. So a same-key cycle that closes below the root
+ * (`A(p1) → A(p2) → A(p2) → …`) is not detected here; it is also an
+ * infinite recursion without caching, and the capture's render timeout
+ * fails it.
+ *
+ * The props key is the props half of the cache key (data props only,
+ * framework children outlet stripped — the same inputs the cache key
+ * hashes). The params half is left out: every render inside one capture
+ * reads the same segment params, so props decide identity. Unkeyable props
+ * (live React elements, …) cannot be proven identical and are never a
+ * cycle.
+ *
+ * Each capture's state lives in an AsyncLocalStorage store entered by
+ * `CaptureScope.run()`, so it is visible only to renders started inside
+ * that capture — including work Flight resumes after an await, which runs
+ * in the context the awaited promise was created in. A concurrent request
+ * rendering the same component is not a cycle, and a concurrent request
+ * rendering a different cached component still revives it from cache
+ * instead of baking it live (TIM-1536). Outside any capture
+ * `noteWrapperRender` is a single store lookup.
+ */
+
+import {
+  prebuiltCaptureAls,
+  requestContextAls,
+  type PrebuiltCaptureStore,
+} from '../als-registry.ts';
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+import { computeComponentCacheKey, splitSlotProps } from './cache-key.ts';
+import { resolveTags } from './lifetime.ts';
+import { withoutChildrenOutlet } from './slots.ts';
+
+/** A wrapped component that rendered inside an active capture. */
+export interface NestedWrapperRender {
+  innerId: string;
+  options: PrebuiltComponentOptions;
+  /**
+   * Every tag the inner resolved to across its renders in this capture;
+   * null when its tags function threw (the tags are unknown).
+   */
+  tags: string[] | null;
+}
+
+/** Per-inner record kept while the capture runs. */
+export interface NestedRecord {
+  options: PrebuiltComponentOptions;
+  tags: Set<string> | null;
+}
+
+/** Thrown by the wrapper when a capture renders its own entry. */
+export class PrebuiltCaptureCycleError extends Error {
+  constructor(componentId: string) {
+    super(
+      `[timber] cache.component "${componentId}" renders itself with the same props ` +
+        `(directly or through other components) — capturing its payload would recurse ` +
+        `forever. Remove the cycle or stop caching this component with cache.component.`
+    );
+    this.name = 'PrebuiltCaptureCycleError';
+  }
+}
+
+/** One capture's state, entered for the duration of its render. */
+export interface CaptureScope {
+  /**
+   * Run `fn` inside this capture. Flight renders in the async context it
+   * was started (and pinged) from, so the render must be CREATED inside
+   * `run`; every wrapper it renders then sees this capture.
+   */
+  run<T>(fn: () => T): T;
+  /** Wrapped components that rendered inside this capture so far. */
+  nestedRenders(): NestedWrapperRender[];
+}
+
+/**
+ * The props half of a render's cache key, or null when unkeyable. Same
+ * inputs `tryRevivePayload` hashes: data props only for slot components,
+ * the framework-injected children outlet stripped.
+ */
+function propsKey(
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): string | null {
+  let keyProps = props;
+  if (options.slots && options.slots.length > 0) {
+    const split = splitSlotProps(props, options.slots);
+    if (split === null) return null;
+    keyProps = split.dataProps;
+  }
+  return computeComponentCacheKey(withoutChildrenOutlet(keyProps), {});
+}
+
+/**
+ * Open a capture of component `outerId` rendered with `props`. Its state
+ * ends with the scope object.
+ */
+export function createCaptureScope(
+  outerId: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): CaptureScope {
+  const store: PrebuiltCaptureStore = {
+    outerId,
+    outerPropsKey: propsKey(options, props),
+    nested: new Map(),
+  };
+  return {
+    run: (fn) => prebuiltCaptureAls.run(store, fn),
+    nestedRenders: () =>
+      Array.from(store.nested, ([innerId, record]) => ({
+        innerId,
+        options: record.options,
+        tags: record.tags && Array.from(record.tags),
+      })),
+  };
+}
+
+/** Whether the current render is inside a capture. */
+export function isCaptureActive(): boolean {
+  return prebuiltCaptureAls.getStore() !== undefined;
+}
+
+/**
+ * Called by the `__prebuilt` wrapper on every render. No-op outside a
+ * capture. Throws `PrebuiltCaptureCycleError` when the render is the
+ * entry the enclosing capture is producing.
+ */
+export function noteWrapperRender(
+  innerId: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): void {
+  const capture = prebuiltCaptureAls.getStore();
+  if (capture === undefined) return;
+  if (innerId === capture.outerId && capture.outerPropsKey !== null) {
+    if (propsKey(options, props) === capture.outerPropsKey) {
+      throw new PrebuiltCaptureCycleError(innerId);
+    }
+  }
+  let record = capture.nested.get(innerId);
+  if (record === undefined) {
+    record = { options, tags: new Set() };
+    capture.nested.set(innerId, record);
+  }
+  if (record.tags !== null && options.tags) {
+    // A diagnostic must not change the capture. The tags function is user
+    // code, so it runs with the request context exited: a read of
+    // segment params, headers, or cookies inside it must not be charged
+    // to the OUTER entry (a build-time context violation, a lost
+    // param-independence proof, a key-discipline report). A tags function
+    // that throws — including because it needed that context — leaves the
+    // inner's tags unknown, which the clamp rule treats as not covered by
+    // the outer; the warning says so. The throw itself is not reported
+    // here: it belongs to the inner, which may never be cached on its own.
+    const tags = record.tags;
+    try {
+      for (const tag of requestContextAls.exit(() => resolveTags(options, props))) tags.add(tag);
+    } catch {
+      record.tags = null;
+    }
+  }
+}

package/src/server/prebuilt/key-discipline.ts

@@ -0,0 +1,122 @@
+/**
+ * Key-discipline diagnostic for cache.component (design/45 §Enforcement).
+ *
+ * Runtime-tier cached components MAY read request context, but the cache
+ * key is computed from props and segment params only — request-derived
+ * values in cached output are the data-leak danger zone (design/06
+ * security note). During a capture render the ALS store is wrapped in a
+ * transparent observing proxy; any request-context read produces a
+ * structured, rate-limited production diagnostic.
+ *
+ * The diagnostic fires per offending component, rate-limited to once per
+ * interval (default 60 s) — not once per process. This ensures the
+ * signal stays visible in log aggregators across restarts and deploys.
+ *
+ * When `strictKeyDiscipline` is enabled (via timber.config.ts
+ * `cache.strictKeyDiscipline: true`), the diagnostic is promoted to a
+ * thrown error that prevents the tainted payload from being cached.
+ */
+
+import type { RequestContextStore } from '../als-registry.ts';
+import { getLogger } from '../logger.ts';
+
+const REQUEST_CONTEXT_FIELDS: Record<string, string> = {
+  headers: 'headers()',
+  parsedCookies: 'cookies()',
+  searchParams: 'searchParams',
+};
+
+/** Rate-limit interval: one diagnostic per component per 60 seconds. */
+const RATE_LIMIT_MS = 60_000;
+
+/** Last emission timestamp per component ID. */
+const lastEmitted = new Map<string, number>();
+
+let strict = false;
+
+/**
+ * Configure strict key-discipline mode. When true, a violation throws
+ * instead of logging — the tainted payload is never cached.
+ * Called at boot from the RSC entry with the resolved config value.
+ */
+export function setKeyDisciplineStrict(enabled: boolean): void {
+  strict = enabled;
+}
+
+/**
+ * Whether the proxy should be created for this component on this render.
+ * Returns true when strict mode is on (always check) or enough time has
+ * elapsed since the last diagnostic for this component.
+ */
+export function shouldCheckKeyDiscipline(id: string): boolean {
+  if (strict) return true;
+  const last = lastEmitted.get(id);
+  if (last === undefined) return true;
+  return Date.now() - last >= RATE_LIMIT_MS;
+}
+
+/**
+ * Wrap a store with a proxy that records per-request field access.
+ * The proxy forwards all reads/writes transparently — it only observes.
+ */
+export function createKeyDisciplineProxy(store: RequestContextStore): {
+  proxy: RequestContextStore;
+  accessedApis: Set<string>;
+} {
+  const accessedApis = new Set<string>();
+  const proxy = new Proxy(store, {
+    get(target, prop, receiver) {
+      const api = REQUEST_CONTEXT_FIELDS[prop as string];
+      if (api) accessedApis.add(api);
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+  return { proxy, accessedApis };
+}
+
+/**
+ * Emit the key-discipline diagnostic or throw in strict mode.
+ *
+ * In strict mode: throws an error so the tainted payload is never cached.
+ * In default mode: emits a structured error-level diagnostic through the
+ * logger (same path as render errors), rate-limited per component.
+ */
+export function emitKeyDisciplineWarning(id: string, apis: Set<string>): void {
+  const apiList = Array.from(apis).join(', ');
+
+  if (strict) {
+    throw new Error(
+      `[timber] cache.component key-discipline violation: "${id}" reads ${apiList} ` +
+        `during a cache capture render. The cache key does not include ` +
+        `request-derived values — caching this output would serve one ` +
+        `user's data to another. Either pass request-derived values as ` +
+        `props (included in the cache key) or remove the ${apiList} call. ` +
+        `To downgrade this to a warning, set cache.strictKeyDiscipline: false ` +
+        `in timber.config.ts.`
+    );
+  }
+
+  const now = Date.now();
+  const last = lastEmitted.get(id);
+  if (last !== undefined && now - last < RATE_LIMIT_MS) return;
+  lastEmitted.set(id, now);
+
+  getLogger().error('cache.component cross-user data leak risk', {
+    component: id,
+    accessedApis: Array.from(apis),
+    message:
+      `cache.component "${id}" reads ${apiList} but the cache key is ` +
+      `computed from props and segment params only. If the output varies ` +
+      `by ${apiList}, different users may see each other's cached content. ` +
+      `Either pass request-derived values as props (included in the cache ` +
+      `key) or remove the ${apiList} call.`,
+  });
+}
+
+/**
+ * Reset all diagnostic state. Exported for tests only.
+ */
+export function resetKeyDisciplineState(): void {
+  lastEmitted.clear();
+  strict = false;
+}

package/src/server/prebuilt/lifetime.ts

@@ -0,0 +1,151 @@
+/**
+ * Lifetime declarations of a `cache.component` — `prerender`, `ttl`,
+ * `tags` (design/45-cache-lifetimes.md) — and the nesting clamp between
+ * two of them (§Nesting Semantics, TIM-1136).
+ *
+ * The clamp rule lives here once, for both places a capture can embed one
+ * wrapped component in another: the post-build capture pass
+ * (server/prebuilt-builder.ts) and request-time re-renders
+ * (`captureComponentPayload()` in server/prebuilt-runtime.ts, TIM-1545).
+ */
+
+import { splitSlotProps } from './cache-key.ts';
+import type { NestedWrapperRender } from './capture-state.ts';
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+
+/** Whether the component has a runtime lifetime (ttl or tags). */
+export function hasRuntimeLifetime(options: PrebuiltComponentOptions): boolean {
+  return options.ttl !== undefined || options.tags != null;
+}
+
+/**
+ * Resolve tags from options (may be static array or function of props).
+ * Function-form tags receive DATA props only — slot props are excluded so
+ * the tags fn never sees SlotOutlet placeholders (capture paths pass
+ * placeholder-substituted props) and tags stay deterministic per key.
+ */
+export function resolveTags(
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): string[] {
+  if (!options.tags) return [];
+  if (Array.isArray(options.tags)) return options.tags;
+  const slots = options.slots;
+  // The split cannot fail here — capture paths pass framework-built shell
+  // props — but stay total: fall back to the props as given.
+  const fnProps =
+    slots && slots.length > 0 ? (splitSlotProps(props, slots)?.dataProps ?? props) : props;
+  return options.tags(fnProps);
+}
+
+// ─── Nesting clamp (design/45 §Nesting Semantics) ────────────────────────
+
+/** The entry a capture is producing: its declaration and resolved tags. */
+export interface CapturedLifetime {
+  id: string;
+  options: PrebuiltComponentOptions;
+  tags: readonly string[];
+}
+
+/**
+ * Why an embedded copy of `inner` goes stale inside `outer`, or null when
+ * the outer's refreshes cover every refresh channel the inner declares:
+ *
+ * - `shorterTtl`: the inner's ttl is shorter than the outer's effective
+ *   lifetime (its ttl, or deploy-long without one).
+ * - `missingTags`: tags the inner resolved to that the outer lacks —
+ *   `revalidateTag` on them refreshes the inner's own entries, never the
+ *   copy. `null` inner tags (a tags function threw) cannot be proven a
+ *   subset, so they count as missing.
+ *
+ * Declaring the inner's tags on the outer is the documented fix, and it
+ * silences the tag half by construction.
+ */
+function clampReasons(
+  outer: CapturedLifetime,
+  inner: NestedWrapperRender
+): { shorterTtl: boolean; missingTags: string[] | null } | null {
+  const outerTtl = outer.options.ttl ?? Infinity;
+  const shorterTtl = inner.options.ttl !== undefined && inner.options.ttl < outerTtl;
+  const missingTags =
+    inner.tags === null ? null : inner.tags.filter((t) => !outer.tags.includes(t));
+  if (!shorterTtl && missingTags !== null && missingTags.length === 0) return null;
+  return { shorterTtl, missingTags };
+}
+
+/** Render a lifetime declaration for the clamp warning. */
+function describeLifetime(
+  options: PrebuiltComponentOptions,
+  tags: readonly string[] | null
+): string {
+  const parts: string[] = [];
+  if (options.prerender) parts.push('prerender');
+  if (options.ttl !== undefined) parts.push(`ttl: ${options.ttl}`);
+  if (tags === null) parts.push('tags: fn');
+  else if (tags.length > 0) parts.push(`tags: ${JSON.stringify(tags)}`);
+  return parts.join(', ') || 'no lifetime';
+}
+
+/** When the outer entry — and so every copy embedded in it — refreshes. */
+function describeRefresh(outer: CapturedLifetime): string {
+  const parts: string[] = [];
+  if (outer.options.ttl !== undefined) parts.push(`every ${outer.options.ttl}s`);
+  if (outer.tags.length > 0) parts.push(`on revalidateTag of its own tags`);
+  // Component keys are per-deploy, so every entry refreshes on redeploy.
+  parts.push('on redeploy');
+  return parts.join(', or ');
+}
+
+/**
+ * Warn for each wrapped component embedded in `outer`'s captured payload
+ * whose refresh channels the outer cannot honor. Once per (outer, inner)
+ * pair for the lifetime of `warnedPairs` — the builder passes one per
+ * build, the runtime one per process, since re-renders repeat. The key is
+ * the pair alone, not the reason: resolved tags vary with props, and a key
+ * that included them would grow with the data. So the first clamp found
+ * for a pair is the one reported. Returns the number of warnings emitted.
+ */
+export function warnNestingClamps(
+  outer: CapturedLifetime,
+  nested: readonly NestedWrapperRender[],
+  warnedPairs: Set<string>,
+  log: (message: string) => void
+): number {
+  let count = 0;
+  for (const inner of nested) {
+    const reasons = clampReasons(outer, inner);
+    if (reasons === null) continue;
+    const pairKey = `${outer.id}\0${inner.innerId}`;
+    if (warnedPairs.has(pairKey)) continue;
+    warnedPairs.add(pairKey);
+    count++;
+    const outerLifetime = describeLifetime(outer.options, outer.tags);
+    const innerLifetime = describeLifetime(inner.options, inner.tags);
+    const consequences: string[] = [];
+    if (reasons.missingTags === null) {
+      consequences.push(
+        `${inner.innerId}'s tags could not be resolved during the capture (its tags function ` +
+          `threw or needed request context), so revalidating them may NOT update the embedded copy.`
+      );
+    } else if (reasons.missingTags.length > 0) {
+      const calls = reasons.missingTags.map((t) => `revalidateTag(${JSON.stringify(t)})`);
+      consequences.push(
+        `${calls.join(', ')} will NOT update the embedded copy; tag ${outer.id} itself if you ` +
+          `need that.`
+      );
+    }
+    if (reasons.shorterTtl) {
+      consequences.push(
+        `${inner.innerId}'s ttl: ${inner.options.ttl} does not apply to the embedded copy.`
+      );
+    }
+    log(
+      `[timber] ${inner.innerId} (${innerLifetime}) is embedded in ` +
+        `${outer.options.prerender ? 'prerendered' : 'cached'} ${outer.id} — the embedded ` +
+        `copy refreshes only when ${outer.id} does (${describeRefresh(outer)}). ` +
+        `${consequences.join(' ')} Chain: ${outer.id} (${outerLifetime}) → ${inner.innerId} ` +
+        `(${innerLifetime})`
+    );
+  }
+  return count;
+}

package/src/server/prebuilt/manifest-tag-index.ts

@@ -0,0 +1,46 @@
+/**
+ * Manifest tag index — maps tags to seed cache keys for tombstone writes.
+ *
+ * When `revalidateTag(tag)` fires, the framework must write tombstones for
+ * every build-seed entry carrying that tag. The manifest records tags per
+ * entry; this module inverts the index at startup so the lookup is O(1) per
+ * tag instead of a full manifest scan per invalidation.
+ *
+ * The index is built lazily on first access and cached for the process
+ * lifetime — the manifest is immutable within a deploy.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+
+import type { PrebuiltManifest } from './payload-source.ts';
+
+export interface SeedKeyInfo {
+  componentId: string;
+  cacheKey: string;
+}
+
+/**
+ * Build the inverted tag → seed key index from the manifest.
+ *
+ * Returns a Map where each tag maps to the set of (componentId, cacheKey)
+ * pairs whose manifest entries carry that tag. Only entries with non-empty
+ * `tags` arrays participate.
+ */
+export function buildTagIndex(manifest: PrebuiltManifest): Map<string, SeedKeyInfo[]> {
+  const index = new Map<string, SeedKeyInfo[]>();
+  for (const [componentId, component] of Object.entries(manifest)) {
+    if (!component || typeof component !== 'object' || !('entries' in component)) continue;
+    for (const [cacheKey, entry] of Object.entries(component.entries)) {
+      if (!entry.tags || entry.tags.length === 0) continue;
+      for (const tag of entry.tags) {
+        let list = index.get(tag);
+        if (!list) {
+          list = [];
+          index.set(tag, list);
+        }
+        list.push({ componentId, cacheKey });
+      }
+    }
+  }
+  return index;
+}