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

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -18,7 +18,6 @@
  * this in try/catch.
  */
 
-import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.ts';
 import {
   applyRequestHeaderOverlay,
   runWithRequestContext,
@@ -26,149 +25,106 @@ import {
   setSegmentParams,
 } from '../request-context.ts';
 import { runMiddlewareChain } from '../middleware-runner.ts';
-import { isDenySignal, isRedirectSignal, DenySignal, RedirectSignal } from '../primitives.ts';
-import { ParamCoercionError } from '../param-coercion.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
 import type { RouteMatch } from '../pipeline.ts';
 import type { MiddlewareContext } from '../types.ts';
 import { requestCspNonce } from '../csp-nonce.ts';
-
-/** Coerce a matched route's segment params via its `params.ts` codecs. */
-export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;
+import type { ReactCacheScope } from '../react-cache-scope.ts';
 
 /**
- * Outcome of running middleware on an action request, surfaced from the
- * inner `runWithRequestContext` scope so the outer dispatcher can convert
- * it to a Response (short-circuit) or continue to the action handler.
+ * Outcome of running a route's middleware chain, surfaced from the inner
+ * `runWithRequestContext` scope as a value. Its one consumer is the
+ * revalidation renderer, which turns every variant but `continue` into
+ * a thrown signal or a dropped revalidation.
  *
- * Each variant carries the post-middleware Set-Cookie snapshot so the
- * outer scope can apply cookies to whichever Response it ultimately
- * returns. The middleware ALS scope ends before the action ALS scope
- * begins, so cookie state must be threaded explicitly across the boundary
- * via `seedRequestCookies` (cookie reads) and `setCookieHeaders` (cookie
- * writes).
+ * Only `continue` carries state out of the scope: the request-header
+ * overlay, which the renderer applies to the action's scope so the
+ * revalidated tree sees middleware-injected headers. Cookies the chain sets
+ * stay in the inner scope and are discarded with it; see the renderer's
+ * docstring for why.
  */
 export type MiddlewareOutcome =
-  | {
-      kind: 'continue';
-      overlay: Headers;
-      cookies: Map<string, string>;
-      setCookieHeaders: string[];
-    }
-  | {
-      kind: 'short-circuit';
-      response: Response;
-      setCookieHeaders: string[];
-    }
-  | {
-      kind: 'redirect';
-      signal: RedirectSignal;
-      setCookieHeaders: string[];
-    }
-  | {
-      kind: 'deny';
-      signal: DenySignal;
-      match: RouteMatch;
-      setCookieHeaders: string[];
-    }
-  | {
-      kind: 'param-coercion-error';
-    }
-  | {
-      kind: 'error';
-      error: unknown;
-    };
+  | { kind: 'continue'; overlay: Headers }
+  | { kind: 'short-circuit'; response: Response }
+  | { kind: 'redirect'; signal: RedirectSignal }
+  | { kind: 'deny'; signal: DenySignal }
+  | { kind: 'error'; error: unknown };
+
+/** The inner request scope's inputs, besides the request itself. */
+export interface MiddlewareScope {
+  /** The `React.cache` scope the revalidated tree will render in. */
+  reactCacheScope: ReactCacheScope;
+  /** The action's post-mutation cookies, as the inner scope's cookies. */
+  cookies?: Map<string, string>;
+}
 
 /**
  * Run the matched route's middleware chain inside a fresh request-context
- * scope, captured as a `MiddlewareOutcome` value the outer dispatcher can
- * translate to a Response or use as the seed for the action handler.
+ * scope, captured as a `MiddlewareOutcome` value.
+ *
+ * `match` must already carry coerced segment params: coercion runs before
+ * middleware, in the caller, as it does in the page pipeline.
  */
 export async function runMiddlewareForAction(
   req: Request,
   match: RouteMatch,
-  coerceSegmentParams: CoerceSegmentParamsFn
+  { reactCacheScope, cookies }: MiddlewareScope
 ): Promise<MiddlewareOutcome> {
-  return runWithRequestContext(req, async (): Promise<MiddlewareOutcome> => {
-    // ─── Coerce segment params (mirrors page pipeline) ──────────────
-    try {
-      await coerceSegmentParams(match);
-    } catch (err) {
-      if (err instanceof ParamCoercionError) {
-        return { kind: 'param-coercion-error' };
-      }
-      return { kind: 'error', error: err };
-    }
-    setSegmentParams(match.segmentParams);
+  return runWithRequestContext(
+    req,
+    async (): Promise<MiddlewareOutcome> => {
+      setSegmentParams(match.segmentParams);
 
-    // ─── Build the middleware context ───────────────────────────────
-    const responseHeaders = new Headers();
-    const requestHeaderOverlay = new Headers();
-    const ctx: MiddlewareContext = {
-      req,
-      requestHeaders: requestHeaderOverlay,
-      headers: responseHeaders,
-      segmentParams: match.segmentParams,
-      // 103 Early Hints are a page-render concern — server actions are
-      // RPC and never produce HTML, so there is nothing to hint about.
-      // Provide a no-op so user middleware can call `ctx.earlyHints()`
-      // unconditionally without branching on request kind.
-      earlyHints: () => {},
-      // Same reasoning: an action response carries no inline scripts, so a
-      // nonce has nothing to stamp. Still a real value so middleware that
-      // builds its CSP header unconditionally keeps working.
-      get nonce() {
-        return requestCspNonce();
-      },
-    };
+      // ─── Build the middleware context ───────────────────────────────
+      const responseHeaders = new Headers();
+      const requestHeaderOverlay = new Headers();
+      const ctx: MiddlewareContext = {
+        req,
+        requestHeaders: requestHeaderOverlay,
+        headers: responseHeaders,
+        segmentParams: match.segmentParams,
+        // 103 Early Hints are a page-render concern — server actions are
+        // RPC and never produce HTML, so there is nothing to hint about.
+        // Provide a no-op so user middleware can call `ctx.earlyHints()`
+        // unconditionally without branching on request kind.
+        earlyHints: () => {},
+        // Same reasoning: an action response carries no inline scripts, so a
+        // nonce has nothing to stamp. Still a real value so middleware that
+        // builds its CSP header unconditionally keeps working.
+        get nonce() {
+          return requestCspNonce();
+        },
+      };
 
-    // ─── Run the chain ──────────────────────────────────────────────
-    setMutableCookieContext(true);
-    try {
-      let middlewareResponse: Response | undefined;
+      // ─── Run the chain ──────────────────────────────────────────────
+      setMutableCookieContext(true);
       try {
-        middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
-      } catch (err) {
-        if (isRedirectSignal(err)) {
-          return {
-            kind: 'redirect',
-            signal: err,
-            setCookieHeaders: getSetCookieHeaders(),
-          };
+        let middlewareResponse: Response | undefined;
+        try {
+          middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+        } catch (err) {
+          if (isRedirectSignal(err)) return { kind: 'redirect', signal: err };
+          if (isDenySignal(err)) return { kind: 'deny', signal: err };
+          return { kind: 'error', error: err };
         }
-        if (isDenySignal(err)) {
-          return {
-            kind: 'deny',
-            signal: err,
-            match,
-            setCookieHeaders: getSetCookieHeaders(),
-          };
-        }
-        return { kind: 'error', error: err };
-      }
 
-      if (middlewareResponse) {
-        return {
-          kind: 'short-circuit',
-          response: middlewareResponse,
-          setCookieHeaders: getSetCookieHeaders(),
-        };
-      }
+        if (middlewareResponse) {
+          return { kind: 'short-circuit', response: middlewareResponse };
+        }
 
-      // Middleware passed — apply the request-header overlay to the
-      // current scope so any code that might still read it within
-      // this scope sees the merged view. The overlay is also captured
-      // in the outcome so the caller can re-apply it inside the
-      // action's request-context scope (which is a separate ALS run).
-      applyRequestHeaderOverlay(requestHeaderOverlay);
+        // Middleware passed — apply the request-header overlay to the
+        // current scope so any code that might still read it within
+        // this scope sees the merged view. The overlay is also captured
+        // in the outcome so the caller can re-apply it inside the
+        // action's request-context scope (which is a separate ALS run).
+        applyRequestHeaderOverlay(requestHeaderOverlay);
 
-      return {
-        kind: 'continue',
-        overlay: requestHeaderOverlay,
-        cookies: getCookiesForSsr(),
-        setCookieHeaders: getSetCookieHeaders(),
-      };
-    } finally {
-      setMutableCookieContext(false);
-    }
-  });
+        return { kind: 'continue', overlay: requestHeaderOverlay };
+      } finally {
+        setMutableCookieContext(false);
+      }
+    },
+    { reactCacheScope, cookies }
+  );
 }

package/src/server/rsc-entry/api-handler.ts

@@ -4,15 +4,20 @@
  * Runs access.ts standalone for all segments in the chain (no React render
  * pass, no AccessGate component). Then dispatches to the route handler.
  * See design/04-authorization.md §"Auth in API Routes".
+ *
+ * Nothing thrown here is answered here. A `deny()` or `redirect()` from
+ * `access.ts` or a method handler, and every other error, propagates to the
+ * pipeline: its deny fallback answers a route.ts match in the JSON status
+ * format, its redirect builder sends the 3xx, and its error outcome answers
+ * errors in the same JSON format. There is one translator for each, not one
+ * per route type (TIM-1537, TIM-1533).
  */
 
 import { withSpan, setSpanAttribute } from '../tracing.ts';
 import type { ManifestSegmentNode } from '../route-matcher.ts';
 import { loadModule } from '../safe-load.ts';
-import { isDenySignal, isRedirectSignal, DenySignal, RedirectSignal } from '../primitives.ts';
+import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
 import { handleRouteRequest } from '../route-handler.ts';
-import { stripHeadBody } from '../head-response.ts';
-import { isDebug } from '../debug.ts';
 import type { RouteModule } from '../route-handler.ts';
 import type { RouteContext } from '../types.ts';
 
@@ -40,33 +45,27 @@ export async function handleApiRoute(
       const accessMod = await loadModule(segment.access);
       const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
-        try {
-          await withSpan(
-            'timber.access',
-            { 'timber.segment': segment.segmentName ?? 'unknown' },
-            async () => {
-              try {
-                await accessFn();
-                await setSpanAttribute('timber.result', 'pass');
-              } catch (error) {
-                if (isDenySignal(error)) {
-                  await setSpanAttribute('timber.result', 'deny');
-                  await setSpanAttribute('timber.deny_status', error.status);
-                  if (error.sourceFile) {
-                    await setSpanAttribute('timber.deny_file', error.sourceFile);
-                  }
-                } else if (isRedirectSignal(error)) {
-                  await setSpanAttribute('timber.result', 'redirect');
+        await withSpan(
+          'timber.access',
+          { 'timber.segment': segment.segmentName ?? 'unknown' },
+          async () => {
+            try {
+              await accessFn();
+              await setSpanAttribute('timber.result', 'pass');
+            } catch (error) {
+              if (isDenySignal(error)) {
+                await setSpanAttribute('timber.result', 'deny');
+                await setSpanAttribute('timber.deny_status', error.status);
+                if (error.sourceFile) {
+                  await setSpanAttribute('timber.deny_file', error.sourceFile);
                 }
-                throw error;
+              } else if (isRedirectSignal(error)) {
+                await setSpanAttribute('timber.result', 'redirect');
               }
+              throw error;
             }
-          );
-        } catch (error) {
-          const signalResponse = await translateApiSignal(error, req, segments, responseHeaders);
-          if (signalResponse) return signalResponse;
-          throw error;
-        }
+          }
+        );
       }
     }
   }
@@ -77,80 +76,5 @@ export async function handleApiRoute(
   // the request-context ALS that the pipeline already populated.
   const routeMod = await loadModule<RouteModule>(leaf.route!);
   const ctx: RouteContext = { req, headers: responseHeaders };
-  try {
-    return await handleRouteRequest(routeMod, ctx);
-  } catch (error) {
-    const signalResponse = await translateApiSignal(error, req, segments, responseHeaders);
-    if (signalResponse) return signalResponse;
-    throw error;
-  }
-}
-
-/**
- * Translate a control-flow signal thrown from access.ts or a route.ts
- * method handler into the proper API response: DenySignal → JSON status-file
- * chain via `renderApiDeny`, RedirectSignal → bare 3xx with Location header.
- *
- * For HEAD requests, strip the deny body to preserve HEAD semantics — signals
- * bypass the HEAD path in `handleRouteRequest`, so this exit needs its own
- * call. Shares `stripHeadBody` with that path and with the pipeline exit; the
- * pipeline applying it again downstream is a no-op (TIM-1324).
- *
- * Returns `null` for non-signal errors so the caller knows to rethrow.
- */
-async function translateApiSignal(
-  error: unknown,
-  req: Request,
-  segments: ManifestSegmentNode[],
-  responseHeaders: Headers
-): Promise<Response | null> {
-  if (isDenySignal(error)) {
-    return stripHeadBody(await renderApiDeny(error, segments, responseHeaders), req.method);
-  }
-  if (isRedirectSignal(error)) {
-    responseHeaders.set('Location', error.location);
-    return new Response(null, { status: error.status, headers: responseHeaders });
-  }
-  return null;
-}
-
-/**
- * Render a deny response for an API route (route.ts).
- *
- * Tries JSON status file chain first. Falls back to bare JSON response.
- * Never renders a component — API consumers get structured JSON, not HTML.
- * See design/10-error-handling.md §"Format Selection for deny()"
- */
-async function renderApiDeny(
-  deny: DenySignal,
-  segments: ManifestSegmentNode[],
-  responseHeaders: Headers
-): Promise<Response> {
-  const { resolveStatusFile } = await import('../status-code-resolver.ts');
-
-  const resolution = resolveStatusFile(deny.status, segments, 'json');
-  if (resolution) {
-    if (isDebug() && deny.data !== undefined) {
-      console.warn(
-        `[timber] deny(${deny.status}, data) resolved to ${resolution.file.filePath}, ` +
-          `which is a static JSON file. The data argument is dropped — JSON status files ` +
-          `are returned verbatim with no interpolation. If you need the data in the ` +
-          `response, use a route handler (route.ts) that returns Response.json() directly.`
-      );
-    }
-    const mod = await loadModule(resolution.file);
-    const jsonContent = mod.default ?? mod;
-    responseHeaders.set('content-type', 'application/json; charset=utf-8');
-    return new Response(JSON.stringify(jsonContent), {
-      status: deny.status,
-      headers: responseHeaders,
-    });
-  }
-
-  // No JSON status file — bare JSON fallback
-  responseHeaders.set('content-type', 'application/json; charset=utf-8');
-  return new Response(JSON.stringify({ error: true, status: deny.status }), {
-    status: deny.status,
-    headers: responseHeaders,
-  });
+  return handleRouteRequest(routeMod, ctx);
 }

package/src/server/rsc-entry/deny-fallback.ts

@@ -1,22 +1,29 @@
 /**
  * Deny fallback renderer — renders the deny page (403.tsx, 404.tsx, etc.)
- * for DenySignals that escape from middleware or the render phase.
+ * for DenySignals that escape from proxy, middleware, or the render phase,
+ * and the 404 page for a URL no route matches.
+ *
+ * This is the one module that assembles deny pages. Renderers report a
+ * captured deny by rethrowing it; the pipeline's outcome translator calls
+ * this. See design/49-explicit-subsystem-boundaries.md §"C".
  *
  * Extracted from index.ts (TIM-968) as a pure move. The factory captures
  * the root segment and client bootstrap config once at handler creation;
- * the returned function is wired into `PipelineConfig.renderDenyFallback`
- * and reused by the action-dispatch wrapper.
+ * the returned function is wired into `PipelineConfig.renderDenyFallback`.
  *
  * Design docs: 04-authorization.md, 10-error-handling.md
  */
 
-import type { LayoutEntry } from '../deny-renderer.ts';
+import { getFirstDeniedSegmentIndex } from '../deny-boundary.ts';
+import type { DefaultPageRenderer, LayoutEntry } from '../deny-renderer.ts';
 import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
 import type { ClientBootstrapConfig } from '../html-injectors.ts';
-import { logRenderError } from '../logger.ts';
-import type { PipelineConfig, RouteMatch } from '../pipeline.ts';
-import type { ManifestSegmentNode } from '../route-matcher.ts';
-import { loadModule } from '../safe-load.ts';
+import { renderJsonStatusResponse } from '../json-status-response.ts';
+import { loadFallbackModule } from '../pipeline-helpers.ts';
+import type { RouteMatch } from '../pipeline.ts';
+import type { DenySignal } from '../primitives.ts';
+import { isApiRouteChain, type ManifestSegmentNode } from '../route-matcher.ts';
+import { rscErrorEnvelope } from '../rsc-error-envelope.ts';
 import { isRscRequest } from '../../shared/rsc-media-type.ts';
 import { callSsr } from './ssr-bridge.ts';
 
@@ -29,30 +36,73 @@ import { callSsr } from './ssr-bridge.ts';
  * route's `401.json` are picked up. Fall back to the root chain when no
  * match is available (e.g. proxy-stage deny before route matching).
  * See TIM-822, design/04-authorization.md, design/10-error-handling.md.
+ *
+ * The page is clamped to the denied segment exactly as the renderer clamps a
+ * captured deny: the index an AccessGate or layout recorded in request ALS
+ * bounds the status-file walk and the layout shell, so a thrown deny never
+ * selects a status file below the denial or runs the denied segment's
+ * layout. It is read here, at call time, rather than passed by the pipeline:
+ * the store is RSC-owned and the pipeline does not know it exists.
+ *
+ * The index is a position in the matched chain, so it is applied only when
+ * there is one. A proxy-phase deny arrives with no match (root-only chain),
+ * and one thrown after `await next()` shares the request store with the
+ * render it replaced — that render's denied index describes a different
+ * deny and must not clamp this one. A middleware-phase deny runs before
+ * render, so no index has been recorded. See TIM-1525, design/49-explicit-subsystem-boundaries.md §P0.
  */
 export function createDenyFallbackRenderer(options: {
   rootSegment: ManifestSegmentNode;
   clientBootstrap: ClientBootstrapConfig;
-}): NonNullable<PipelineConfig['renderDenyFallback']> {
+}): DenyFallbackRenderer {
   const { rootSegment, clientBootstrap } = options;
-  return async (deny, req, responseHeaders, matchedRoute) => {
+  return async (deny, req, responseHeaders, matchedRoute, defaultPage) => {
     const chain: ManifestSegmentNode[] = matchedRoute ? matchedRoute.segments : [rootSegment];
+
+    // A route.ts match answers in JSON whatever the Accept header says —
+    // before the RSC dispatch below, and without loading layouts it would
+    // never render. No AccessGate runs on an API route, so there is no
+    // denied-segment index to clamp to. See design/10-error-handling.md
+    // §"Format Selection for deny()".
+    //
+    // Asked of the match, not of `chain`: with no match the chain is the
+    // root alone, and an `app/route.ts` puts `route` on the root node. An
+    // unmatched URL or a proxy-phase deny is not a request to that route.
+    if (matchedRoute && isApiRouteChain(matchedRoute.segments)) {
+      return renderJsonStatusResponse(
+        req,
+        deny.status,
+        chain,
+        responseHeaders,
+        undefined,
+        deny.data
+      );
+    }
+
+    // A skipped segment whose access just flipped to deny marks the signal
+    // for hard-navigate: rendering a deny page here would execute the denied
+    // segment's protected layout and place it inside cached client chrome
+    // (TIM-1074). The envelope makes the client hard-navigate for a clean
+    // full render with correct deny page placement. See TIM-1363.
+    if (deny._hardNavigate && isRscRequest(req)) {
+      return rscErrorEnvelope(deny.status, responseHeaders);
+    }
+
+    // A layout that fails to import or evaluate is reported, and the page is
+    // wrapped in the layouts above it: a partial chain is acceptable, a deny
+    // page taken down by its layout is not. Nothing below the failure is
+    // wrapped, so a deeper layout never renders without its parent.
     const layoutComponents: LayoutEntry[] = [];
-    try {
-      for (const segment of chain) {
-        if (!segment.layout) continue;
-        const mod = await loadModule(segment.layout);
-        if (mod.default) {
-          layoutComponents.push({
-            component: mod.default as (...args: unknown[]) => unknown,
-            segment,
-          });
-        }
+    for (const segment of chain) {
+      if (!segment.layout) continue;
+      const mod = await loadFallbackModule(segment.layout, req, chain);
+      if (!mod) break;
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment,
+        });
       }
-    } catch (layoutError) {
-      // Layout failed to load — proceed without it. Partial layout chains
-      // are acceptable; the deny renderer wraps in whatever loaded.
-      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
     }
     // Reuse the matched route's params/middleware metadata when present so
     // downstream rendering sees the real route shape. Otherwise synthesise
@@ -60,6 +110,7 @@ export function createDenyFallbackRenderer(options: {
     const match: RouteMatch = matchedRoute ?? {
       segments: chain,
       segmentParams: {},
+      rawSegmentParams: {},
       middlewareChain: [],
     };
     // For client navigation (Accept: text/x-component), the timber router
@@ -67,8 +118,9 @@ export function createDenyFallbackRenderer(options: {
     // decoder breaks navigation, so dispatch to the RSC renderer when the
     // request is an RSC payload request — mirroring the normal render path.
     // See design/19-client-navigation.md §"RSC Payload Handling" and TIM-823.
+    const deniedIndex = matchedRoute ? getFirstDeniedSegmentIndex() : Infinity;
     if (isRscRequest(req)) {
-      return renderDenyPageAsRsc(deny, chain, layoutComponents, req, responseHeaders);
+      return renderDenyPageAsRsc(deny, chain, layoutComponents, req, responseHeaders, deniedIndex);
     }
     return renderDenyPage(
       deny,
@@ -78,7 +130,22 @@ export function createDenyFallbackRenderer(options: {
       match,
       responseHeaders,
       clientBootstrap,
-      callSsr
+      callSsr,
+      defaultPage,
+      deniedIndex
     );
   };
 }
+
+/**
+ * The deny fallback. `defaultPage` replaces the framework default status
+ * page when no status file answers — the dev 404 route listing for an
+ * unmatched URL.
+ */
+export type DenyFallbackRenderer = (
+  deny: DenySignal,
+  req: Request,
+  responseHeaders: Headers,
+  matchedRoute?: RouteMatch,
+  defaultPage?: DefaultPageRenderer
+) => Promise<Response>;