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

package/src/server/pipeline-outcome.ts

@@ -14,6 +14,7 @@ import {
   applyCookieJar,
   buildRedirectResponse,
   cloneWithMutableHeaders,
+  dynamicResponseHeaders,
   fireOnRequestError,
   mergeMissingHeaders,
 } from './pipeline-helpers.ts';
@@ -22,9 +23,13 @@ import {
   logMiddlewareError,
   logMiddlewareShortCircuit,
   logRenderError,
+  logRouteError,
+  logRouteSetupError,
 } from './logger.ts';
 import { markResponseFlushed } from './request-context.ts';
 import { RedirectSignal, DenySignal } from './primitives.ts';
+import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
+import { isApiRouteChain } from './route-matcher.ts';
 import { isDebug } from './debug.ts';
 import { errorResponseHeaders } from './error-response-headers.ts';
 import { rscErrorEnvelope } from './rsc-error-envelope.ts';
@@ -54,17 +59,72 @@ function rscErrorResponse(isRsc: boolean, status: number, headers: Headers): Res
  * `proxy.ts` that awaits `next()` and then throws, this is the only place
  * the cookies downstream middleware set can reach the wire
  * (design/29-cookies.md §"proxy.ts Cookie Access"). Middleware-phase
- * signals throw before that phase's own application, so they need it too.
+ * signals throw before that phase's own application, so they need it too,
+ * and so do setup-phase outcomes, which come before any phase applied it.
+ *
+ * `fresh` creates the bag for an outcome that arrives without one.
  */
-function outcomeHeaders(outcome: PhaseOutcome, ctx: OutcomeContext): Headers {
-  const headers = ctx.responseHeaders ?? new Headers();
+function outcomeHeaders(
+  outcome: PhaseOutcome,
+  ctx: OutcomeContext,
+  fresh: () => Headers = () => new Headers()
+): Headers {
+  const headers = ctx.responseHeaders ?? fresh();
   if (outcome.phase !== 'render') applyCookieJar(headers);
   return headers;
 }
 
+/** Whether the outcome is for a route.ts match, which answers in its own format. */
+function isApiRouteMatch(ctx: OutcomeContext): boolean {
+  return ctx.match !== undefined && isApiRouteChain(ctx.match.segments);
+}
+
+/**
+ * Report an error outcome once: log it under its phase, fire
+ * `onRequestError`, and hand it to the dev overlay. An error from a
+ * route.ts handler — or anything else in its render phase — logs as a route
+ * error and reports as phase `'route'`.
+ */
+async function reportError(
+  config: PipelineConfig,
+  error: unknown,
+  phase: PhaseName,
+  ctx: OutcomeContext
+): Promise<void> {
+  const { method, path } = ctx;
+  switch (phase) {
+    case 'proxy':
+      logProxyError({ error });
+      break;
+    case 'setup':
+      logRouteSetupError({ method, path, error });
+      break;
+    case 'middleware':
+      logMiddlewareError({ method, path, error });
+      break;
+    case 'render':
+      if (isApiRouteMatch(ctx)) {
+        logRouteError({ method, path, error });
+      } else {
+        logRenderError({ method, path, error });
+      }
+      break;
+  }
+  await fireOnRequestError(error, ctx.req, phase, ctx.match?.segments);
+  if (config.onPipelineError && error instanceof Error) config.onPipelineError(error, phase);
+}
+
 // ─── Phase Outcome ─────────────────────────────────────────────────────────
 
-export type PhaseName = 'proxy' | 'middleware' | 'render';
+/**
+ * The pipeline phase an outcome came from.
+ *
+ * `'setup'` is route setup between `proxy.ts` and `middleware.ts`: route
+ * matching, interception, and segment-param coercion. It has its own name
+ * rather than borrowing `'middleware'` because both the cookie-jar guard
+ * and `onRequestError` key on the phase (TIM-1537).
+ */
+export type PhaseName = 'proxy' | 'setup' | 'middleware' | 'render';
 
 export type PhaseOutcome =
   | { kind: 'response'; phase: PhaseName; response: Response }
@@ -72,6 +132,13 @@ export type PhaseOutcome =
   | { kind: 'deny'; phase: PhaseName; signal: DenySignal }
   | { kind: 'error'; phase: PhaseName; error: unknown };
 
+/** The outcome for a value a phase threw: a signal, or an error. */
+export function thrownOutcome(phase: PhaseName, thrown: unknown): PhaseOutcome {
+  if (isRedirectSignal(thrown)) return { kind: 'redirect', phase, signal: thrown };
+  if (isDenySignal(thrown)) return { kind: 'deny', phase, signal: thrown };
+  return { kind: 'error', phase, error: thrown };
+}
+
 export interface OutcomeContext {
   req: Request;
   method: string;
@@ -126,11 +193,18 @@ export async function outcomeToResponse(
 
     case 'redirect': {
       const headers = outcomeHeaders(outcome, ctx);
-      return buildRedirectResponse(outcome.signal, ctx.req, headers);
+      // A route.ts match redirects with a real 3xx whatever it accepts; only
+      // a page navigation gets the client router's soft redirect.
+      const navigation = isRscRequest(ctx.req) && !isApiRouteMatch(ctx);
+      return buildRedirectResponse(outcome.signal, headers, navigation);
     }
 
     case 'deny': {
-      const headers = outcomeHeaders(outcome, ctx);
+      // A deny with no bag of its own (a proxy-phase deny) gets the
+      // dynamic-page cache policy every other rendered page starts with.
+      // Only the deny: a redirect proxy.ts chose keeps HTTP's own caching
+      // semantics (a 308 is heuristically cacheable).
+      const headers = outcomeHeaders(outcome, ctx, dynamicResponseHeaders);
       if (config.renderDenyFallback) {
         try {
           // Clone user-supplied deny-page responses so downstream
@@ -144,9 +218,12 @@ export async function outcomeToResponse(
           // 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');
+          await fireOnRequestError(denyRenderError, ctx.req, 'render', ctx.match?.segments);
           if (config.onPipelineError && denyRenderError instanceof Error)
             config.onPipelineError(denyRenderError, 'render');
+          // A client navigation cannot decode an empty body: send the
+          // hard-navigate envelope so the document request renders the deny.
+          if (isRscRequest(ctx.req)) return rscErrorEnvelope(outcome.signal.status, headers);
         }
       }
       if (isDebug()) {
@@ -166,31 +243,18 @@ export async function outcomeToResponse(
       // to the server-rendered error page instead of feeding HTML to the
       // Flight decoder (which crashes with "enqueueModel is not a function").
       const isRsc = isRscRequest(ctx.req);
+      const headers = outcomeHeaders(outcome, ctx);
+      await reportError(config, outcome.error, outcome.phase, ctx);
 
-      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 rscErrorResponse(isRsc, 500, outcomeHeaders(outcome, ctx));
-      }
-
-      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 rscErrorResponse(isRsc, 500, outcomeHeaders(outcome, ctx));
+      // proxy.ts and middleware.ts errors answer with a bare 500 — no page.
+      if (outcome.phase === 'proxy' || outcome.phase === 'middleware') {
+        return rscErrorResponse(isRsc, 500, headers);
       }
 
-      const headers = outcomeHeaders(outcome, ctx);
-      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 (isRsc) {
+      // A route.ts match answers in its JSON format whatever the Accept
+      // header says, so it skips the navigation envelope and goes to the
+      // fallback renderer with the match.
+      if (isRsc && !isApiRouteMatch(ctx)) {
         return rscErrorResponse(true, 500, headers);
       }
 
@@ -199,7 +263,15 @@ export async function outcomeToResponse(
           // 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)
+            // Sanitized: the replacement body must not inherit the success
+            // response's encoding, length, validators, or cache lifetime
+            // that middleware may already have set on the bag.
+            await config.renderFallbackError(
+              outcome.error,
+              ctx.req,
+              errorResponseHeaders(headers),
+              ctx.match
+            )
           );
         } catch (fallbackRenderError) {
           // Fallback rendering itself failed — log the secondary error before
@@ -207,7 +279,7 @@ export async function outcomeToResponse(
           // 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');
+          await fireOnRequestError(fallbackRenderError, ctx.req, 'render', ctx.match?.segments);
           if (config.onPipelineError && fallbackRenderError instanceof Error)
             config.onPipelineError(fallbackRenderError, 'render');
         }