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

package/src/server/pipeline-outcome.ts

@@ -0,0 +1,167 @@
+/**
+ * Pipeline outcome translator — converts a `PhaseOutcome` (the value
+ * each phase function returns) into a final `Response`.
+ *
+ * Lifted out of `pipeline-phases.ts` (TIM-853) so the per-phase try /
+ * catch logic and the terminal Response-building logic each live in
+ * their own file. The phases produce values; this module is the single
+ * source of truth for how those values become wire responses.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import {
+  applyCookieJar,
+  buildRedirectResponse,
+  cloneWithMutableHeaders,
+  fireOnRequestError,
+  mergeMissingHeaders,
+} from './pipeline-helpers.js';
+import {
+  logProxyError,
+  logMiddlewareError,
+  logMiddlewareShortCircuit,
+  logRenderError,
+} from './logger.js';
+import { markResponseFlushed } from './request-context.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
+import type { PipelineConfig, RouteMatch } from './pipeline.js';
+
+// ─── Phase Outcome ─────────────────────────────────────────────────────────
+
+export type PhaseName = 'proxy' | 'middleware' | 'render';
+
+export type PhaseOutcome =
+  | { kind: 'response'; phase: PhaseName; response: Response }
+  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
+  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
+  | { kind: 'error'; phase: PhaseName; error: unknown };
+
+export interface OutcomeContext {
+  req: Request;
+  method: string;
+  path: string;
+  responseHeaders?: Headers;
+  match?: RouteMatch;
+}
+
+// ─── Translator ────────────────────────────────────────────────────────────
+
+/**
+ * Terminal outcome handler — converts a `PhaseOutcome` into a final
+ * `Response`, applying cookies, building redirects, rendering deny pages
+ * and fallback error pages, and firing instrumentation hooks.
+ *
+ * This is the single source of truth for how phase outputs become wire
+ * responses; the per-phase try/catch blocks now produce values, not
+ * Responses, so the conversion logic lives in exactly one place.
+ */
+export async function outcomeToResponse(
+  config: PipelineConfig,
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext
+): Promise<Response> {
+  switch (outcome.kind) {
+    case 'response': {
+      // Clone unconditionally so downstream code (cookie/header merge,
+      // Server-Timing in createPipeline) can write headers without paying
+      // for a try/catch immutability probe per request. User middleware,
+      // proxy, and route code may all return `Response.redirect()` or
+      // platform-level responses with frozen header bags. See TIM-866.
+      const finalResponse = cloneWithMutableHeaders(outcome.response);
+
+      if (outcome.phase === 'proxy') return finalResponse;
+
+      if (outcome.phase === 'middleware' && ctx.responseHeaders) {
+        applyCookieJar(finalResponse.headers);
+        mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
+        logMiddlewareShortCircuit({
+          method: ctx.method,
+          path: ctx.path,
+          status: finalResponse.status,
+        });
+      }
+
+      if (outcome.phase === 'render') {
+        markResponseFlushed();
+      }
+
+      return finalResponse;
+    }
+
+    case 'redirect': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      return buildRedirectResponse(outcome.signal, ctx.req, headers);
+    }
+
+    case 'deny': {
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      if (config.renderDenyFallback) {
+        try {
+          // Clone user-supplied deny-page responses so downstream
+          // Server-Timing writes are safe against frozen header bags
+          // (e.g. user returned Response.redirect from the hook).
+          return cloneWithMutableHeaders(
+            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
+          );
+        } catch (denyRenderError) {
+          // Deny page rendering failed — log before falling through to bare response.
+          // Without this, a crashing deny page produces a blank response with zero
+          // server-side signal. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: denyRenderError });
+          await fireOnRequestError(denyRenderError, ctx.req, 'render');
+          if (config.onPipelineError && denyRenderError instanceof Error)
+            config.onPipelineError(denyRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: outcome.signal.status, headers });
+    }
+
+    case 'error': {
+      if (outcome.phase === 'proxy') {
+        logProxyError({ error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'proxy');
+        if (config.onPipelineError && outcome.error instanceof Error)
+          config.onPipelineError(outcome.error, 'proxy');
+        return new Response(null, { status: 500 });
+      }
+
+      if (outcome.phase === 'middleware') {
+        logMiddlewareError({ method: ctx.method, path: ctx.path, error: outcome.error });
+        await fireOnRequestError(outcome.error, ctx.req, 'handler');
+        if (config.onPipelineError && outcome.error instanceof Error) {
+          config.onPipelineError(outcome.error, 'middleware');
+        }
+        return new Response(null, { status: 500 });
+      }
+
+      const headers = ctx.responseHeaders ?? new Headers();
+      applyCookieJar(headers);
+      logRenderError({ method: ctx.method, path: ctx.path, error: outcome.error });
+      await fireOnRequestError(outcome.error, ctx.req, 'render');
+      if (config.onPipelineError && outcome.error instanceof Error)
+        config.onPipelineError(outcome.error, 'render');
+      if (config.renderFallbackError) {
+        try {
+          // Clone user-supplied fallback error responses so downstream
+          // Server-Timing writes are safe against frozen header bags.
+          return cloneWithMutableHeaders(
+            await config.renderFallbackError(outcome.error, ctx.req, headers)
+          );
+        } catch (fallbackRenderError) {
+          // Fallback rendering itself failed — log the secondary error before
+          // falling through to bare 500. The original render error was already
+          // logged above; this captures the fallback renderer's own crash so it
+          // doesn't vanish silently. See TIM-876.
+          logRenderError({ method: ctx.method, path: ctx.path, error: fallbackRenderError });
+          await fireOnRequestError(fallbackRenderError, ctx.req, 'render');
+          if (config.onPipelineError && fallbackRenderError instanceof Error)
+            config.onPipelineError(fallbackRenderError, 'render');
+        }
+      }
+      return new Response(null, { status: 500 });
+    }
+  }
+}

package/src/server/pipeline-phases.ts

@@ -1,8 +1,9 @@
 /**
  * Pipeline phase functions — module-level free functions that take their
  * dependencies as explicit parameters. Each phase returns a `PhaseOutcome`
- * (a discriminated union over response / redirect / deny / error). The
- * terminal `outcomeToResponse` translates outcomes into Responses.
+ * (a discriminated union over response / redirect / deny / error) defined
+ * in `pipeline-outcome.ts`. The terminal `outcomeToResponse` (also in
+ * `pipeline-outcome.ts`) translates outcomes into Responses.
  *
  * Lifted out of `createPipeline` so each phase can be unit-tested in
  * isolation. The lift is mechanical — these functions used to be closures
@@ -13,118 +14,33 @@
 
 import { canonicalize } from './canonicalize.js';
 import { runProxy } from './proxy.js';
-import { runMiddlewareChain } from './middleware-runner.js';
+import { runMiddlewareChain, shouldBypassMiddleware } from './middleware-runner.js';
 import { withTiming } from './server-timing.js';
 import {
   applyRequestHeaderOverlay,
   setMutableCookieContext,
-  markResponseFlushed,
   setSegmentParams,
 } from './request-context.js';
 import { withSpan } from './tracing.js';
-import {
-  logProxyError,
-  logMiddlewareError,
-  logMiddlewareShortCircuit,
-  logRenderError,
-} from './logger.js';
+import { logRenderError } from './logger.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
 import { loadModule } from './safe-load.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
-import {
-  applyCookieJar,
-  buildRedirectResponse,
-  cloneWithMutableHeaders,
-  fireOnRequestError,
-  mergeMissingHeaders,
-  safeMerge,
-  type ProxyResolver,
-} from './pipeline-helpers.js';
+import { applyCookieJar, cloneWithMutableHeaders, type ProxyResolver } from './pipeline-helpers.js';
+import { coerceSegmentParams } from './param-coercion.js';
+import { outcomeToResponse, type PhaseOutcome } from './pipeline-outcome.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline.js';
-import type { MiddlewareContext } from './types.js';
-
-// ─── Phase Outcome ─────────────────────────────────────────────────────────
-
-export type PhaseName = 'proxy' | 'middleware' | 'render';
-
-export type PhaseOutcome =
-  | { kind: 'response'; phase: PhaseName; response: Response }
-  | { kind: 'redirect'; phase: PhaseName; signal: RedirectSignal }
-  | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
-  | { kind: 'error'; phase: PhaseName; error: unknown };
-
-export interface OutcomeContext {
-  req: Request;
-  method: string;
-  path: string;
-  responseHeaders?: Headers;
-  match?: RouteMatch;
-}
+import type { MetadataHandler, MetadataRoute, MiddlewareContext } from './types.js';
+import { swallow } from './logger.js';
 
 interface RenderContext {
   canonicalPathname: string;
   interception?: InterceptionContext;
 }
 
-// ─── Param Coercion ────────────────────────────────────────────────────────
-
-/**
- * Run segment param coercion on the matched route's segments.
- *
- * Loads params.ts modules from segments that have them, extracts the
- * segmentParams definition, and coerces raw string params through codecs.
- * Throws ParamCoercionError if any codec fails (→ 404).
- *
- * This runs BEFORE middleware, so ctx.segmentParams is already typed.
- * See design/07-routing.md §"Where Coercion Runs"
- */
-export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
-  const segments = match.segments;
-  let mergeTarget = match.segmentParams as Record<string, unknown>;
-  let usesNullPrototypeTarget = Object.getPrototypeOf(mergeTarget) === null;
-
-  for (const segment of segments) {
-    // Only process segments that have a params.ts convention file
-    if (!segment.params) continue;
-
-    let mod: Record<string, unknown>;
-    try {
-      mod = await loadModule(segment.params);
-    } catch (err) {
-      throw new ParamCoercionError(
-        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-
-    const segmentParamsDef = mod.segmentParams as
-      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
-      | undefined;
-
-    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
-
-    try {
-      const coerced = segmentParamsDef.parse(match.segmentParams);
-
-      if (!usesNullPrototypeTarget) {
-        mergeTarget = Object.create(null) as Record<string, unknown>;
-        safeMerge(mergeTarget, match.segmentParams as Record<string, unknown>);
-        match.segmentParams = mergeTarget as RouteMatch['segmentParams'];
-        usesNullPrototypeTarget = true;
-      }
-
-      // safeMerge blocks shallow prototype-polluting keys from codec output.
-      // The null-prototype target above provides the deeper guarantee for
-      // nested values without paying the cost of a deep sanitizer.
-      safeMerge(mergeTarget, coerced as Record<string, unknown>);
-    } catch (err) {
-      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
-    }
-  }
-}
-
 // ─── Phase: Proxy ──────────────────────────────────────────────────────────
 
 /**
@@ -307,7 +223,7 @@ export async function handleRequest(
           return await serveStaticMetadataFile(metaMatch);
         }
 
-        const mod = await loadModule<{ default?: Function }>(metaMatch.file);
+        const mod = await loadModule<{ default?: MetadataHandler }>(metaMatch.file);
         if (typeof mod.default !== 'function') {
           return new Response('Metadata route must export a default function', { status: 500 });
         }
@@ -318,17 +234,21 @@ export async function handleRequest(
         if (handlerResult instanceof Response) {
           return cloneWithMutableHeaders(handlerResult);
         }
-        // Otherwise, serialize based on content type
+        // Otherwise, serialize based on content type. The type discriminator
+        // here is the metadata route's declared content type (from the file
+        // convention), not the shape of `handlerResult` — TS can't narrow the
+        // `MetadataResult` union on that, so we assert against the expected
+        // shape at each branch.
         const contentType = metaMatch.contentType;
         let body: string;
         if (typeof handlerResult === 'string') {
           body = handlerResult;
         } else if (contentType === 'application/xml') {
-          body = serializeSitemap(handlerResult);
+          body = serializeSitemap(handlerResult as MetadataRoute.Sitemap);
         } else if (contentType === 'application/manifest+json') {
           body = JSON.stringify(handlerResult, null, 2);
         } else {
-          body = typeof handlerResult === 'string' ? handlerResult : String(handlerResult);
+          body = String(handlerResult);
         }
         return new Response(body, {
           status: 200,
@@ -427,8 +347,8 @@ export async function handleRequest(
   if (config.earlyHints) {
     try {
       await config.earlyHints(match, req, responseHeaders);
-    } catch {
-      // Early hints failure is non-fatal
+    } catch (err) {
+      swallow(err, 'early hints hook threw');
     }
   }
 
@@ -462,8 +382,14 @@ export async function handleRequest(
   // See design/07-routing.md §"params.ts — Convention File for Typed Params"
   setSegmentParams(match.segmentParams);
 
+  // Bypass middleware for synthetic re-render requests built by the
+  // action-dispatch wrapper after a no-JS form validation failure.
+  // The wrapper has already executed middleware once on the inbound POST;
+  // running it again on the rerender GET would double-execute auth, rate
+  // limiting, and request-header injection. See TIM-871.
+  const skipMiddleware = shouldBypassMiddleware(req);
   const outcome =
-    match.middlewareChain.length > 0
+    !skipMiddleware && match.middlewareChain.length > 0
       ? await runMiddlewarePhase(config, req, match, responseHeaders, requestHeaderOverlay, {
           canonicalPathname,
           interception,
@@ -481,111 +407,3 @@ export async function handleRequest(
     match,
   });
 }
-
-// ─── Outcome Translation ───────────────────────────────────────────────────
-
-/**
- * Terminal outcome handler — converts a `PhaseOutcome` into a final
- * `Response`, applying cookies, building redirects, rendering deny pages
- * and fallback error pages, and firing instrumentation hooks.
- *
- * This is the single source of truth for how phase outputs become wire
- * responses; the per-phase try/catch blocks now produce values, not
- * Responses, so the conversion logic lives in exactly one place.
- */
-export async function outcomeToResponse(
-  config: PipelineConfig,
-  outcome: PhaseOutcome,
-  ctx: OutcomeContext
-): Promise<Response> {
-  switch (outcome.kind) {
-    case 'response': {
-      // Clone unconditionally so downstream code (cookie/header merge,
-      // Server-Timing in createPipeline) can write headers without paying
-      // for a try/catch immutability probe per request. User middleware,
-      // proxy, and route code may all return `Response.redirect()` or
-      // platform-level responses with frozen header bags. See TIM-866.
-      const finalResponse = cloneWithMutableHeaders(outcome.response);
-
-      if (outcome.phase === 'proxy') return finalResponse;
-
-      if (outcome.phase === 'middleware' && ctx.responseHeaders) {
-        applyCookieJar(finalResponse.headers);
-        mergeMissingHeaders(finalResponse.headers, ctx.responseHeaders);
-        logMiddlewareShortCircuit({
-          method: ctx.method,
-          path: ctx.path,
-          status: finalResponse.status,
-        });
-      }
-
-      if (outcome.phase === 'render') {
-        markResponseFlushed();
-      }
-
-      return finalResponse;
-    }
-
-    case 'redirect': {
-      const headers = ctx.responseHeaders ?? new Headers();
-      applyCookieJar(headers);
-      return buildRedirectResponse(outcome.signal, ctx.req, headers);
-    }
-
-    case 'deny': {
-      const headers = ctx.responseHeaders ?? new Headers();
-      applyCookieJar(headers);
-      if (config.renderDenyFallback) {
-        try {
-          // Clone user-supplied deny-page responses so downstream
-          // Server-Timing writes are safe against frozen header bags
-          // (e.g. user returned Response.redirect from the hook).
-          return cloneWithMutableHeaders(
-            await config.renderDenyFallback(outcome.signal, ctx.req, headers, ctx.match)
-          );
-        } catch {
-          // Deny page rendering failed — fall through to bare response
-        }
-      }
-      return new Response(null, { status: outcome.signal.status, headers });
-    }
-
-    case 'error': {
-      if (outcome.phase === 'proxy') {
-        logProxyError({ error: outcome.error });
-        await fireOnRequestError(outcome.error, ctx.req, 'proxy');
-        if (config.onPipelineError && outcome.error instanceof Error)
-          config.onPipelineError(outcome.error, 'proxy');
-        return new Response(null, { status: 500 });
-      }
-
-      if (outcome.phase === 'middleware') {
-        logMiddlewareError({ method: ctx.method, path: ctx.path, error: outcome.error });
-        await fireOnRequestError(outcome.error, ctx.req, 'handler');
-        if (config.onPipelineError && outcome.error instanceof Error) {
-          config.onPipelineError(outcome.error, 'middleware');
-        }
-        return new Response(null, { status: 500 });
-      }
-
-      const headers = ctx.responseHeaders ?? new Headers();
-      applyCookieJar(headers);
-      logRenderError({ method: ctx.method, path: ctx.path, error: outcome.error });
-      await fireOnRequestError(outcome.error, ctx.req, 'render');
-      if (config.onPipelineError && outcome.error instanceof Error)
-        config.onPipelineError(outcome.error, 'render');
-      if (config.renderFallbackError) {
-        try {
-          // Clone user-supplied fallback error responses so downstream
-          // Server-Timing writes are safe against frozen header bags.
-          return cloneWithMutableHeaders(
-            await config.renderFallbackError(outcome.error, ctx.req, headers)
-          );
-        } catch {
-          // Fallback rendering itself failed — fall through to bare 500
-        }
-      }
-      return new Response(null, { status: 500 });
-    }
-  }
-}

package/src/server/pipeline.ts

@@ -31,15 +31,8 @@ import { logRequestReceived, logRequestCompleted, logSlowRequest } from './logge
 import { DenySignal } from './primitives.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { makeProxyResolver } from './pipeline-helpers.js';
-import { handleRequest, outcomeToResponse, runProxyPhase } from './pipeline-phases.js';
-
-// ─── Re-exports for backwards compatibility ────────────────────────────────
-
-// `safeMerge` and `coerceSegmentParams` were originally exported from this
-// module. They now live in pipeline-helpers.ts and pipeline-phases.ts; the
-// re-exports preserve `import { safeMerge } from './pipeline.js'` callers.
-export { safeMerge } from './pipeline-helpers.js';
-export { coerceSegmentParams } from './pipeline-phases.js';
+import { handleRequest, runProxyPhase } from './pipeline-phases.js';
+import { outcomeToResponse } from './pipeline-outcome.js';
 
 // ─── Route Match Result ────────────────────────────────────────────────────