@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/src/server/route-matcher.ts

@@ -10,6 +10,7 @@
 
 import type { RouteMatch } from './pipeline.js';
 import type { MiddlewareFn } from './middleware-runner.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
@@ -18,71 +19,40 @@ import {
 } from './metadata-routes.js';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
-// The virtual module manifest has a slightly different shape than SegmentNode:
-// file references are { load, filePath } instead of RouteFile.
+//
+// TIM-848: the runtime route manifest re-uses the same `SegmentNode<TFile>`
+// / `RouteTree<TFile>` interfaces from `routing/types.ts`. The only
+// difference between build-time and runtime is the file reference payload
+// — build-time has `{ filePath, extension }`, runtime has `{ filePath, load }`.
+// Walkers parameterized over `TFile` work on either; there is no separate
+// "manifest" tree shape.
 
 /** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
+export interface ManifestFile {
   load: () => Promise<unknown>;
   filePath: string;
 }
 
-/** A segment node as it appears in the virtual:timber-route-manifest module. */
-export interface ManifestSegmentNode {
-  segmentName: string;
-  segmentType:
-    | 'static'
-    | 'dynamic'
-    | 'catch-all'
-    | 'optional-catch-all'
-    | 'group'
-    | 'slot'
-    | 'intercepting';
-  urlPath: string;
-  paramName?: string;
-  /** For intercepting segments: the marker used, e.g. "(.)". */
-  interceptionMarker?: '(.)' | '(..)' | '(...)' | '(..)(..)';
-  /** For intercepting segments: the segment name after stripping the marker. */
-  interceptedSegmentName?: string;
-
-  page?: ManifestFile;
-  layout?: ManifestFile;
-  middleware?: ManifestFile;
-  access?: ManifestFile;
-  route?: ManifestFile;
-  /** params.ts — isomorphic convention file for segmentParams + searchParams definitions. */
-  params?: ManifestFile;
-  error?: ManifestFile;
-  default?: ManifestFile;
-  denied?: ManifestFile;
-  statusFiles?: Record<string, ManifestFile>;
-  jsonStatusFiles?: Record<string, ManifestFile>;
-  legacyStatusFiles?: Record<string, ManifestFile>;
-  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-  metadataRoutes?: Record<string, ManifestFile>;
-
-  children: ManifestSegmentNode[];
-  slots: Record<string, ManifestSegmentNode>;
-}
+/**
+ * A segment node as it appears in the virtual:timber-route-manifest module.
+ *
+ * Type alias for `SegmentNode<ManifestFile>` — the same shape used by the
+ * scanner, only with lazy `load` functions instead of build-time extension
+ * metadata.
+ */
+export type ManifestSegmentNode = SegmentNode<ManifestFile>;
 
-/** The manifest shape from virtual:timber-route-manifest. */
-export interface ManifestRoot {
-  root: ManifestSegmentNode;
-  /**
-   * Absolute path to the Vite project root, captured at build/load time.
-   * Used by dev-only features (e.g., dev error page frame classification)
-   * that need a correct project root even when CWD differs (e.g., monorepo
-   * custom root). See TIM-807 / TIM-808.
-   */
+/**
+ * The manifest shape from virtual:timber-route-manifest.
+ *
+ * Extends `RouteTree<ManifestFile>` with `viteRoot`, the absolute path
+ * to the Vite project root captured at build/load time. Used by dev-only
+ * features (e.g., dev error page frame classification) that need a
+ * correct project root even when CWD differs (e.g., monorepo custom root).
+ * See TIM-807 / TIM-808.
+ */
+export interface ManifestRoot extends RouteTree<ManifestFile> {
   viteRoot: string;
-  proxy?: ManifestFile;
-  /**
-   * Global error page: app/global-error.{tsx,ts,jsx,js}
-   * Tier 2 — standalone full-page replacement (no layouts) when no
-   * segment-level error file is found. SSR-only render.
-   * See design/10-error-handling.md §"Tier 2"
-   */
-  globalError?: ManifestFile;
 }
 
 // ─── Matcher ──────────────────────────────────────────────────────────────
@@ -132,9 +102,7 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
   }
 
   return {
-    // The pipeline uses segments as opaque objects passed to the renderer.
-    // Cast is safe — the renderer receives what the manifest provides.
-    segments: segments as unknown as RouteMatch['segments'],
+    segments,
     segmentParams: params,
     middlewareChain,
   };

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

@@ -0,0 +1,167 @@
+/**
+ * Middleware-on-actions runner — runs the matched route's `middleware.ts`
+ * chain for an action POST inside its own `runWithRequestContext` scope
+ * and returns a `MiddlewareOutcome` value the dispatcher can translate.
+ *
+ * Lifted out of `wrap-action-dispatch.ts` (TIM-853) so the dispatcher
+ * can be read top-to-bottom without scrolling past the chain runner. The
+ * function is intentionally a free function (not a closure over deps)
+ * so it can be unit-tested in isolation. It does not import virtual
+ * modules and does not call into the action handler — it owns exactly
+ * the "run middleware once" step and nothing else.
+ *
+ * Failure modes are encoded as outcome variants rather than thrown so the
+ * caller never has to wrap this in try/catch. The only thrown errors are
+ * truly unexpected (programmer bugs) and propagate naturally.
+ *
+ * See TIM-871 for the full design rationale (closing the
+ * CVE-2025-29927-class bug where actions silently bypass middleware).
+ */
+
+import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.js';
+import {
+  applyRequestHeaderOverlay,
+  runWithRequestContext,
+  setMutableCookieContext,
+  setSegmentParams,
+} from '../request-context.js';
+import { runMiddlewareChain } from '../middleware-runner.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { ParamCoercionError } from '../route-element-builder.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { MiddlewareContext } from '../types.js';
+
+/** Coerce a matched route's segment params via its `params.ts` codecs. */
+export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;
+
+/**
+ * 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.
+ *
+ * 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).
+ */
+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;
+    };
+
+/**
+ * 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.
+ */
+export async function runMiddlewareForAction(
+  req: Request,
+  match: RouteMatch,
+  coerceSegmentParams: CoerceSegmentParamsFn
+): 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);
+
+    // ─── 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: () => {},
+    };
+
+    // ─── Run the chain ──────────────────────────────────────────────
+    setMutableCookieContext(true);
+    try {
+      let middlewareResponse: Response | undefined;
+      try {
+        middlewareResponse = await runMiddlewareChain(match.middlewareChain, ctx);
+      } catch (err) {
+        if (err instanceof RedirectSignal) {
+          return {
+            kind: 'redirect',
+            signal: err,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        if (err instanceof DenySignal) {
+          return {
+            kind: 'deny',
+            signal: err,
+            match,
+            setCookieHeaders: getSetCookieHeaders(),
+          };
+        }
+        return { kind: 'error', error: err };
+      }
+
+      if (middlewareResponse) {
+        return {
+          kind: 'short-circuit',
+          response: middlewareResponse,
+          setCookieHeaders: getSetCookieHeaders(),
+        };
+      }
+
+      // 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);
+    }
+  });
+}

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

@@ -89,9 +89,9 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveManifestStatusFile } = await import('../manifest-status-resolver.js');
+  const { resolveStatusFile } = await import('../status-code-resolver.js');
 
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
   if (resolution) {
     const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;

package/src/server/rsc-entry/error-renderer.ts

@@ -25,7 +25,7 @@ import { renderDenyPage } from '../deny-renderer.js';
 import type { LayoutEntry } from '../deny-renderer.js';
 import type { NavContext } from '../ssr-entry.js';
 import { createDebugChannelSink } from './helpers.js';
-import { getCookiesForSsr } from '../request-context.js';
+import { getCookiesForSsr } from '../cookie-context.js';
 import { callSsr } from './ssr-bridge.js';
 import { teeWithErrorPropagation } from '../stream-utils.js';
 import { isDevMode } from '../debug.js';
@@ -377,7 +377,7 @@ export async function renderNoMatchPage(
   }
 
   const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
 
   return renderDenyPage(
     deny,

package/src/server/rsc-entry/helpers.ts

@@ -250,13 +250,8 @@ export function isAbortError(error: unknown): boolean {
   return false;
 }
 
-export function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// escapeHtml is now imported from server/utils/escape-html.ts
+export { escapeHtml } from '../utils/escape-html.js';
 
 /**
  * Parse a Cookie header string into a name→value Map.