@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/server/react-cache-bridge.ts

@@ -0,0 +1,124 @@
+/**
+ * React.cache bridge — one `React.cache` scope per request, shared by
+ * `proxy.ts`, `middleware.ts`, route handlers, and the render.
+ *
+ * `React.cache(fn)` stores its memo table in whatever Map
+ * `ReactSharedInternals.A.getCacheForType()` returns. `A` is Flight's
+ * `DefaultAsyncDispatcher`, whose `getCacheForType` returns the active Flight
+ * request's `cache` Map, or a throwaway `new Map()` outside a render. So
+ * without this bridge a `React.cache` call in middleware silently never
+ * dedupes with the same call in `access.ts` or a layout.
+ *
+ * The bridge wraps that one method on the existing dispatcher object:
+ *
+ * - When a timber scope is active (`reactCacheScopeAls`), it returns the
+ *   scope's Map — inside or outside a Flight render.
+ * - Otherwise it calls Flight's original method, so behaviour outside a
+ *   request (build-time capture, tests, isolated renders) is unchanged.
+ *
+ * Opening, resuming, and leaving scopes lives in `react-cache-scope.ts`,
+ * which does not import `react` so request-context and cookie code can use it.
+ *
+ * Constraints (TIM-1529, design/spike-TIM-1529-react-cache-bridge.md):
+ *
+ * - Never reassign `ReactSharedInternals.A`. Flight's `Request` constructor
+ *   throws "Currently React only supports one RSC renderer at a time" when
+ *   `A` is set to anything but its own dispatcher.
+ * - Never shim the `react` module's `cache` export and never patch the
+ *   vendored Flight bundle.
+ * - Flight installs `A` lazily, in the `Request` constructor, so it is
+ *   `null` until the first render. `installReactCacheBridge` takes a
+ *   `warmUp` callback that constructs one throwaway render to install it.
+ * - Idempotent: a program reload that re-evaluates this module but not
+ *   Flight finds the brand on the live method and does not wrap it twice.
+ *   A reload that re-evaluates Flight too hands back a fresh dispatcher,
+ *   which the re-evaluated RSC entry patches again. The wrapper closes over
+ *   nothing but the `globalThis`-anchored ALS, so an old wrapper that
+ *   survives a reload still reads the current scope.
+ */
+
+import * as React from 'react';
+import { reactCacheScopeAls } from './als-registry.ts';
+
+const INTERNALS_KEY = '__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';
+const BRIDGED = Symbol.for('timber:react-cache-bridge');
+
+type GetCacheForType = (resourceType: () => unknown) => unknown;
+
+interface AsyncDispatcher {
+  getCacheForType: GetCacheForType;
+}
+
+interface ServerInternals {
+  A: unknown;
+}
+
+function isServerInternals(value: unknown): value is ServerInternals {
+  return typeof value === 'object' && value !== null && 'A' in value;
+}
+
+function isAsyncDispatcher(value: unknown): value is AsyncDispatcher {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'getCacheForType' in value &&
+    typeof value.getCacheForType === 'function'
+  );
+}
+
+/** Result of `installReactCacheBridge`, for the boot log and the canary test. */
+export type ReactCacheBridgeStatus =
+  | { installed: true; alreadyBridged: boolean }
+  | { installed: false; reason: string };
+
+/**
+ * Patch Flight's dispatcher so `React.cache` resolves the active timber
+ * scope. Call once from the RSC entry, after the Flight server has loaded.
+ *
+ * `warmUp` must construct a Flight render (e.g. `renderToReadableStream(null)`
+ * and cancel it) — that is the only public way to make Flight install `A`.
+ *
+ * Never throws: if React's internals change shape the bridge is skipped,
+ * `React.cache` keeps its stock per-render behaviour, and the reason is
+ * returned. `tests/react-cache-bridge.test.ts` fails CI on that path.
+ */
+export function installReactCacheBridge(warmUp: () => void): ReactCacheBridgeStatus {
+  const internals: unknown = Reflect.get(React, INTERNALS_KEY);
+  if (!isServerInternals(internals)) {
+    return {
+      installed: false,
+      reason: `react does not export ${INTERNALS_KEY}`,
+    };
+  }
+  if (internals.A === null || internals.A === undefined) {
+    try {
+      warmUp();
+    } catch (error) {
+      return { installed: false, reason: `warm-up render threw: ${String(error)}` };
+    }
+  }
+  const dispatcher = internals.A;
+  if (!isAsyncDispatcher(dispatcher)) {
+    return {
+      installed: false,
+      reason: 'ReactSharedInternals.A has no getCacheForType()',
+    };
+  }
+
+  const original = dispatcher.getCacheForType;
+  if (BRIDGED in original) return { installed: true, alreadyBridged: true };
+
+  const bridged: GetCacheForType = function getCacheForType(resourceType) {
+    const scope = reactCacheScopeAls.getStore();
+    if (!scope) return original.call(dispatcher, resourceType);
+    let entry = scope.get(resourceType);
+    if (entry === undefined) {
+      entry = resourceType();
+      scope.set(resourceType, entry);
+    }
+    return entry;
+  };
+  Object.defineProperty(bridged, BRIDGED, { value: true });
+  dispatcher.getCacheForType = bridged;
+  return { installed: true, alreadyBridged: false };
+}

package/src/server/react-cache-scope.ts

@@ -0,0 +1,104 @@
+/**
+ * React.cache scopes — opening, resuming, and leaving the per-request
+ * `React.cache` scope that `react-cache-bridge.ts` makes Flight read.
+ *
+ * Kept apart from the bridge so request-context and cookie code can use
+ * it without importing `react`. See design/spike-TIM-1529-react-cache-bridge.md.
+ */
+
+import { reactCacheScopeAls, type ReactCacheScope } from './als-registry.ts';
+import { isDevMode } from './debug.ts';
+
+export type { ReactCacheScope };
+
+/** A new, empty `React.cache` scope. */
+export function createReactCacheScope(): ReactCacheScope {
+  return new Map();
+}
+
+/**
+ * Run `fn` in a `React.cache` scope — a fresh one unless `scope` is given.
+ * Every `React.cache` call made from `fn` — synchronously, in its async
+ * continuations, and in any Flight render it starts — shares one memo table.
+ *
+ * Opened by `runWithRequestContext`, so each request context gets its own
+ * scope. Pass `scope` to resume one across two ALS runs: the post-action
+ * revalidation opens a fresh scope for the target route's middleware and
+ * renders the revalidated tree in that same scope later.
+ */
+export function runWithReactCacheScope<T>(
+  fn: () => T,
+  scope: ReactCacheScope = createReactCacheScope()
+): T {
+  return reactCacheScopeAls.run(scope, fn);
+}
+
+/**
+ * Run `fn` with no timber scope, so `React.cache` behaves as stock React:
+ * no dedupe outside a render, Flight's own per-render cache inside one.
+ *
+ * Used for server action bodies — an action reads, writes cookies, and
+ * mutates, so memoized reads would go stale mid-action (the same choice
+ * Next.js makes) — and for renders whose output outlives the request
+ * (`cache.component` capture), which must not bake request-memoized values
+ * into a cross-request cache entry.
+ */
+export function runOutsideReactCacheScope<T>(fn: () => T): T {
+  return reactCacheScopeAls.exit(fn);
+}
+
+// ─── Dev diagnostic: cookie written after a cached read ──────────────────
+//
+// A value React.cache stored was computed from the request inputs it read,
+// and does not see a later write — a cached getUser() that read the session
+// cookie still returns the old user after middleware deletes the cookie.
+// The scope is deliberately NOT cleared on a write: that would silently
+// discard every value middleware warmed (spike doc §Decisions D3). Instead,
+// dev mode flags the one case that can go stale: a cookie read while the
+// scope held values, then written later in the same request. Tracking is
+// per scope, so it ends with the request; production does none of it.
+
+/** Stands for "every cookie" — a getAll()/size read, or a clear() write. */
+export const ANY_COOKIE = '*';
+
+const cookieReads = new WeakMap<ReactCacheScope, Set<string>>();
+const warnedScopes = new WeakSet<ReactCacheScope>();
+
+/**
+ * Dev-only: record that cookie `name` (or {@link ANY_COOKIE}) was read
+ * while `React.cache` held values in this request — the read may have
+ * happened inside a cached function.
+ */
+export function noteCookieReadForReactCache(name: string): void {
+  if (!isDevMode()) return;
+  const scope = reactCacheScopeAls.getStore();
+  if (!scope || scope.size === 0) return;
+  let reads = cookieReads.get(scope);
+  if (!reads) {
+    reads = new Set();
+    cookieReads.set(scope, reads);
+  }
+  reads.add(name);
+}
+
+/**
+ * Dev-only: warn (once per request) when a cookie recorded by
+ * {@link noteCookieReadForReactCache} is written. `name` is the written
+ * cookie, or {@link ANY_COOKIE} for `clear()`. Dev-only because reads are
+ * only recorded in dev.
+ */
+export function warnIfCachedCookieIsWritten(name: string): void {
+  const scope = reactCacheScopeAls.getStore();
+  if (!scope || warnedScopes.has(scope)) return;
+  const reads = cookieReads.get(scope);
+  if (!reads) return;
+  const stale = name === ANY_COOKIE ? reads.size > 0 : reads.has(name) || reads.has(ANY_COOKIE);
+  if (!stale) return;
+  warnedScopes.add(scope);
+  const which = name === ANY_COOKIE ? 'Cookies were cleared' : `Cookie "${name}" was written`;
+  console.warn(
+    `[timber] ${which} after being read while React.cache held values for this request. ` +
+      `A cached function that read it keeps returning the old result — pass the cookie ` +
+      `value in as an argument (e.g. getUser(sessionToken)) so a change is a new cache key.`
+  );
+}

package/src/server/render-timeout.ts

@@ -8,6 +8,26 @@
  * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
  */
 
+/** `renderTimeoutMs` when timber.config.ts leaves it unset. */
+export const DEFAULT_RENDER_TIMEOUT_MS = 30_000;
+
+/**
+ * What `renderTimeoutMs: 0` means: a safety ceiling, never "no timeout" —
+ * an unbounded render or singleflight wait can hang a connection or
+ * deadlock a cache key forever.
+ */
+export const RENDER_TIMEOUT_CEILING_MS = 120_000;
+
+/**
+ * The one mapping from configured `renderTimeoutMs` to the timeout every
+ * consumer enforces. Config enters the runtime already resolved (the
+ * runtime config module, static generation's options), so readers never
+ * see 0 or undefined.
+ */
+export function resolveRenderTimeoutMs(configured: number | undefined): number {
+  return (configured ?? DEFAULT_RENDER_TIMEOUT_MS) || RENDER_TIMEOUT_CEILING_MS;
+}
+
 /**
  * Error thrown when an SSR render or RSC stream read exceeds the
  * configured timeout. Callers can check `instanceof RenderTimeoutError`

package/src/server/render-utils.ts

@@ -6,7 +6,17 @@
  * ssr-render.ts, and rsc-entry/helpers.ts. See TIM-1071 item 1.
  */
 
-import { nonceAttr } from './csp-nonce.ts';
+/**
+ * The ` nonce="…"` attribute fragment for a timber-generated `<script>` tag,
+ * or `''` when the request has no nonce. Callers interpolate it directly
+ * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.
+ *
+ * The value comes from `generateNonce` in csp-nonce.ts and is base64, so no attribute
+ * escaping is required.
+ */
+export function nonceAttr(nonce: string | undefined): string {
+  return nonce ? ` nonce="${nonce}"` : '';
+}
 
 /**
  * Check if an error is an abort error (connection closed by client).

package/src/server/request-context.ts

@@ -17,7 +17,6 @@
 import type { CoercedParams } from '../shared/param-value.ts';
 import { requestContextAls, type RequestContextStore } from './als-registry.ts';
 import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.ts';
-import { consumeSeededCookies } from './cookie-context.ts';
 import { appVisibleSearch } from '../shared/rsc-cache-key.ts';
 import {
   mergeSlotParams,
@@ -25,6 +24,7 @@ import {
   type SlotParamsRecord,
 } from '../shared/slot-params.ts';
 import { isDebug } from './debug.ts';
+import { runWithReactCacheScope, type ReactCacheScope } from './react-cache-scope.ts';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -306,26 +306,53 @@ export type ReadonlyHeaders = Pick<
 
 // ─── Framework-Internal Helpers ───────────────────────────────────────────
 
+/** Options for `runWithRequestContext()`. */
+export interface RequestContextOptions {
+  /**
+   * Resume this `React.cache` scope instead of opening a fresh one. Only the
+   * post-action revalidation passes it.
+   */
+  reactCacheScope?: ReactCacheScope;
+  /**
+   * The request's cookies, already parsed. Re-entry callers (the no-JS form
+   * rerender and the revalidation middleware) pass the action's
+   * post-mutation cookie state here instead of round-tripping it through a
+   * `Cookie:` header — the same parse the H-3 smuggling primitive abused
+   * (TIM-868).
+   */
+  cookies?: Map<string, string>;
+}
+
 /**
  * Run a callback within a request context. Used by the pipeline to establish
  * per-request ALS scope so that `getHeaders()` and `getCookies()` work.
  *
- * If the request was previously registered via `seedRequestCookies`, the
- * resulting context's `parsedCookies` map is initialized from the seed and
- * the raw `cookieHeader` is left empty — `parseCookieHeader` is never called
- * for that request. This is the no-JS form-rerender path. See TIM-868.
+ * When `options.cookies` is given, the context's `parsedCookies` map is a
+ * copy of it and the raw `cookieHeader` is left empty, so
+ * `parseCookieHeader` never runs for that request. Re-entry callers pass the
+ * action's post-mutation cookie state this way (TIM-868).
+ *
+ * Each request context also opens its own `React.cache` scope, shared by
+ * everything that runs inside it — proxy.ts, middleware.ts, route handlers,
+ * and the render (design/02-rendering-pipeline.md §"Cache Scoping Model").
  *
  * @param req - The incoming Request object.
  * @param fn - The function to run within the request context.
  */
-export function runWithRequestContext<T>(req: Request, fn: () => T): T {
+export function runWithRequestContext<T>(
+  req: Request,
+  fn: () => T,
+  { reactCacheScope, cookies }: RequestContextOptions = {}
+): T {
   const originalCopy = new Headers(req.headers);
   const appVisible = appVisibleSearch(new URL(req.url));
-  const seed = consumeSeededCookies(req);
+  // A copy: the caller keeps its map, and this request's writes stay here.
+  const seed = cookies ? new Map(cookies) : undefined;
   const store: RequestContextStore = {
+    request: req,
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
-    // When seeded, leave the raw header empty — parseCookieHeader is the
+    // Given parsed cookies, leave the raw header empty — parseCookieHeader is the
     // exact code path the smuggling primitive abused, and lazy parsing is
     // gated on `parsedCookies` being undefined.
     cookieHeader: seed ? '' : (req.headers.get('cookie') ?? ''),
@@ -340,7 +367,7 @@ export function runWithRequestContext<T>(req: Request, fn: () => T): T {
     flushed: false,
     mutableContext: false,
   };
-  return requestContextAls.run(store, fn);
+  return requestContextAls.run(store, () => runWithReactCacheScope(fn, reactCacheScope));
 }
 
 /**

package/src/server/route-element-builder.ts

@@ -20,7 +20,8 @@ import { createElement, Fragment } from 'react';
 import { withSpan } from './tracing.ts';
 import type { RouteMatch } from './pipeline.ts';
 import type { ManifestSegmentNode } from './route-matcher.ts';
-import { isDenySignal, DenySignal } from './primitives.ts';
+import { DenySignal } from './primitives.ts';
+import { isDenySignal } from './signal-identity.ts';
 import { isClientReference } from './utils/element-type.ts';
 import { loadRouteModules, type MetadataSource, type AccessFn } from './route-module-loader.ts';
 import { MetadataCollector, MetadataHead } from './metadata-collector.ts';
@@ -46,7 +47,8 @@ import type { ClientStateTree } from './state-tree-diff.ts';
 import { computeSkippableSet } from './skippable-prefix.ts';
 import { computeSegmentKeys, computeSegmentTreePaths } from '../routing/segment-keys.ts';
 import { setFirstDeniedSegmentIndex } from './deny-boundary.ts';
-import { loadModule } from './safe-load.ts';
+import { loadModule, type ManifestLoader } from './safe-load.ts';
+import { loadFallbackModule } from './pipeline-helpers.ts';
 import { replaceOutermostSegmentOutlet } from './route-element-helpers.ts';
 
 /**
@@ -205,6 +207,9 @@ export async function buildRouteElement(
   metadataRouteHashes?: Record<string, string>
 ): Promise<RouteElementResult> {
   const segments = match.segments;
+  // Status and error pages the boundaries need: a load failure is reported,
+  // and the boundary is skipped rather than failing the render.
+  const loadBoundaryModule = (file: ManifestLoader) => loadFallbackModule(file, req, segments);
 
   // ── Module loading ──────────────────────────────────────────────────
   // Load layout/page modules and collect metadata sources. Metadata
@@ -239,7 +244,7 @@ export async function buildRouteElement(
   // can tell a file it owns from an ancestor's. See TIM-666, TIM-1356.
   const denyPageChains = new Map<number, DenyPageEntry[]>();
   for (let i = 0; i < segments.length; i++) {
-    const chain = await buildDenyPageChain(segments, i, segmentKeys);
+    const chain = await buildDenyPageChain(segments, i, segmentKeys, req);
     if (chain.length > 0) {
       denyPageChains.set(i, chain);
     }
@@ -424,7 +429,7 @@ export async function buildRouteElement(
     // rather than catching it first and rendering at the wrong depth
     // (TIM-1356).
     element = await wrapSegmentWithErrorBoundaries(segment, element, {
-      loadModule,
+      loadModule: loadBoundaryModule,
       createElement: h,
       errorBoundaryComponent: TimberErrorBoundary,
       segmentKey: segmentKeys[i],
@@ -449,7 +454,7 @@ export async function buildRouteElement(
         h,
         interception,
         parentTreePath,
-        destinationUrl,
+        req,
         clientStateTree: clientStateTree ?? null,
         slotSkipInfo,
       });
@@ -517,7 +522,7 @@ export async function buildRouteElement(
         // provider into the client's mounted outlet, carries it along.
         // See TIM-1450, design/04-authorization.md §"Where a Deny Page Renders".
         layoutElement = await wrapSegmentWithErrorBoundaries(segment, layoutElement, {
-          loadModule,
+          loadModule: loadBoundaryModule,
           createElement: h,
           errorBoundaryComponent: TimberErrorBoundary,
           segmentKey: segmentId,

package/src/server/route-handler.ts

@@ -9,9 +9,10 @@
  */
 
 import type { RouteContext } from './types.ts';
-import { logRouteError } from './logger.ts';
-import { isDenySignal, isRedirectSignal } from './primitives.ts';
 import { stripHeadBody } from './head-response.ts';
+import { setMutableCookieContext } from './request-context.ts';
+import { getSetCookieHeaders } from './cookie-context.ts';
+import { syncCookieJar } from './pipeline-helpers.ts';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -79,15 +80,16 @@ export async function handleRouteRequest(mod: RouteModule, ctx: RouteContext): P
   const allowed = resolveAllowedMethods(mod);
   const allowHeader = allowed.join(', ');
 
-  // Auto OPTIONS — 204 with Allow header
+  // Auto OPTIONS — 204 with Allow header. Merged like any handler response,
+  // so a CORS header middleware set reaches the preflight.
   if (method === 'OPTIONS') {
     if (mod.OPTIONS) {
       return runHandler(mod.OPTIONS, ctx);
     }
-    return new Response(null, {
-      status: 204,
-      headers: { Allow: allowHeader },
-    });
+    return mergeResponseHeaders(
+      new Response(null, { status: 204, headers: { Allow: allowHeader } }),
+      ctx.headers
+    );
   }
 
   // HEAD fallback — dispatch to GET when the module exports no HEAD, so the
@@ -107,32 +109,43 @@ export async function handleRouteRequest(mod: RouteModule, ctx: RouteContext): P
   // Dispatch to the named handler
   const handler = mod[method];
   if (!handler) {
-    return new Response(null, {
-      status: 405,
-      headers: { Allow: allowHeader },
-    });
+    return mergeResponseHeaders(
+      new Response(null, { status: 405, headers: { Allow: allowHeader } }),
+      ctx.headers
+    );
   }
 
   return runHandler(handler, ctx);
 }
 
 /**
- * Run a handler, merge ctx.headers into the response, and catch errors.
+ * Run a handler with cookie writes enabled and merge ctx.headers into its
+ * response.
+ *
+ * Cookies (design/29-cookies.md §"Where Cookies Can Be Set"): the render
+ * phase applied the jar to `ctx.headers` before the handler ran, so on the
+ * way out only what the handler changed is synced onto that bag. It happens
+ * whether the handler returns or throws, so a cookie set before `redirect()`
+ * rides the redirect, and the pipeline's 500 for a throw carries the same
+ * bag.
+ *
+ * Nothing is caught. A signal goes to the pipeline, whose deny fallback
+ * answers a route.ts match in JSON and whose redirect outcome sends the 3xx
+ * (TIM-1533). Any other error goes to the pipeline, which logs it,
+ * reports it to `onRequestError` as phase `'route'`, and answers it in the
+ * same format as every other route.ts error (TIM-1537).
  */
 async function runHandler(handler: RouteHandler, ctx: RouteContext): Promise<Response> {
+  const applied = getSetCookieHeaders();
+  setMutableCookieContext(true);
+  let res: Response;
   try {
-    const res = await handler(ctx);
-    return mergeResponseHeaders(res, ctx.headers);
-  } catch (error) {
-    // Control-flow signals — propagate to the API route dispatcher so deny()
-    // gets the JSON status-file chain and redirect() gets a proper 3xx with
-    // Location. Not errors; don't log them.
-    if (isDenySignal(error) || isRedirectSignal(error)) {
-      throw error;
-    }
-    logRouteError({ method: ctx.req.method, path: new URL(ctx.req.url).pathname, error });
-    return new Response(null, { status: 500 });
+    res = await handler(ctx);
+  } finally {
+    setMutableCookieContext(false);
+    syncCookieJar(ctx.headers, applied);
   }
+  return mergeResponseHeaders(res, ctx.headers);
 }
 
 /**

package/src/server/route-matcher.ts

@@ -85,7 +85,10 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
 
   return {
     segments: result.chain,
-    segmentParams: result.params,
+    rawSegmentParams: result.params,
+    // Uncoerced until the pipeline runs the codecs; a copy, so nothing that
+    // later replaces or edits it can reach the raw record.
+    segmentParams: { ...result.params },
     middlewareChain: collectMiddlewareChain(result.chain),
   };
 }
@@ -117,6 +120,17 @@ export function collectMiddlewareChain(chain: ManifestSegmentNode[]): Middleware
   return middlewareChain;
 }
 
+/**
+ * Whether a matched chain renders as an API route: its leaf has a
+ * `route.ts` and no `page.tsx`. The same test `renderRoute` dispatches on,
+ * so every answer about a route's format — early hints, deny format, error
+ * format, error reporting — agrees with what actually ran.
+ */
+export function isApiRouteChain(segments: readonly ManifestSegmentNode[]): boolean {
+  const leaf = segments[segments.length - 1];
+  return !!leaf?.route && !leaf.page;
+}
+
 // ─── Metadata Route Matcher ─────────────────────────────────────────────
 
 /** Result of matching a metadata route. */