@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/pipeline-helpers.ts

@@ -0,0 +1,485 @@
+/**
+ * Pipeline helpers — small utility functions used by `pipeline.ts` and
+ * `pipeline-phases.ts`. Lifted out of `pipeline.ts` to keep that file
+ * focused on the request handler entry point.
+ *
+ * Each helper is intentionally a free function with no closure capture, so
+ * it can be unit-tested in isolation.
+ *
+ * See design/07-routing.md §"Request Lifecycle".
+ */
+
+import type { ProxyExport } from './proxy.ts';
+import { getSetCookieHeaders } from './cookie-context.ts';
+import {
+  callOnRequestError,
+  hasOnRequestError,
+  type InstrumentationErrorContext,
+} from './instrumentation.ts';
+import { getTraceId } from './tracing.ts';
+import { requestContextAls } from './als-registry.ts';
+import { RedirectSignal } from './primitives.ts';
+import { isControlFlowSignal } from './signal-identity.ts';
+import { logRenderError, logSkippedModule, swallow } from './logger.ts';
+import { isAbortError } from './render-utils.ts';
+import { loadModule, ModuleLoadError, type ManifestLoader } from './safe-load.ts';
+import { getWaitUntil } from './waituntil-bridge.ts';
+import { isApiRouteChain, isCsrfExemptRoute, type ManifestSegmentNode } from './route-matcher.ts';
+import type { ProxyConfig, RouteMatcher } from './pipeline.ts';
+import { csrfRejectionResponse, validateCsrf, type CsrfConfig } from './csrf.ts';
+import type { PhaseName } from './pipeline-outcome.ts';
+
+// ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
+
+// ─── CSRF Gate ─────────────────────────────────────────────────────────────
+
+/**
+ * The pipeline-boundary CSRF gate: the 403 to answer with, or null to go on.
+ *
+ * Runs on every request after canonicalization and before proxy.ts, so it
+ * covers route.ts handlers and server actions alike, and no user code has
+ * run when it decides. The per-route exemption is looked up only for a
+ * request the check would reject — the common accepted request never pays
+ * for a match. The lookup uses the pipeline's own matcher on the canonical
+ * path, the same match `handleRequest` dispatches on, and reads a flag the
+ * scanner took from route.ts source, so deciding it loads no module.
+ *
+ * A matcher that throws leaves the request unexempted: fail closed.
+ *
+ * See design/08-forms-and-actions.md §"CSRF Protection".
+ */
+export function csrfGate(
+  req: Request,
+  canonicalPath: string,
+  csrf: CsrfConfig,
+  matchRoute: RouteMatcher
+): Response | null {
+  const result = validateCsrf(req, csrf);
+  if (result.ok) return null;
+  let exempt = false;
+  try {
+    const match = matchRoute(canonicalPath);
+    exempt = match !== null && isCsrfExemptRoute(match.segments);
+  } catch (err) {
+    swallow(err, 'csrf gate: route match for exemption lookup threw');
+  }
+  return exempt ? null : csrfRejectionResponse(req, result);
+}
+
+// ─── Proxy Resolver ────────────────────────────────────────────────────────
+
+/**
+ * Resolver closure produced once at pipeline construction. The lazy variant
+ * still calls `loader()` per-request (HMR relies on re-importing), but the
+ * choice of which branch to take is made once, not on every request.
+ */
+export type ProxyResolver = () => ProxyExport | Promise<ProxyExport>;
+
+/**
+ * Build a proxy resolver closure from the declared source. Called exactly
+ * once at `createPipeline` setup time, so the hot path sees only the branch
+ * that corresponds to this pipeline's configured variant.
+ *
+ * Returns `null` when the app has no proxy.ts — the hot path short-circuits
+ * around `runProxyPhase` entirely in that case.
+ *
+ * Accepts the sugar form (a bare `ProxyExport` — function or function array)
+ * and normalises it to the static variant. Functions and arrays are
+ * structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
+ * so discrimination is unambiguous.
+ */
+export function makeProxyResolver(
+  proxy: ProxyConfig | ProxyExport | undefined
+): ProxyResolver | null {
+  if (proxy === undefined) return null;
+  // Sugar: a bare ProxyExport (function or function array) — treat as static.
+  if (typeof proxy === 'function' || Array.isArray(proxy)) {
+    const exp = proxy;
+    return () => exp;
+  }
+  if (proxy.kind === 'static') {
+    const exp = proxy.export;
+    return () => exp;
+  }
+  const loader = proxy.loader;
+  return async () => (await loader()).default;
+}
+
+// ─── Cookie / Header Helpers ───────────────────────────────────────────────
+
+/**
+ * Apply all Set-Cookie headers from the cookie jar to a Headers object.
+ * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
+ */
+export function applyCookieJar(headers: Headers): void {
+  for (const value of getSetCookieHeaders()) {
+    headers.append('Set-Cookie', value);
+  }
+}
+
+/**
+ * Bring a bag the jar was already applied to up to date with the jar.
+ *
+ * `applied` is what `getSetCookieHeaders()` returned when the jar was
+ * applied to `headers`. Values the jar no longer holds (a later write to the
+ * same name replaced them) are removed, and values it gained are appended.
+ * Every cookie then appears once, with its last write (design/29-cookies.md
+ * §"Last-Write-Wins for Same Name"). `Set-Cookie` values that did not come
+ * from the jar, such as a middleware appending to `ctx.headers` directly,
+ * are left alone.
+ */
+export function syncCookieJar(headers: Headers, applied: readonly string[]): void {
+  const current = getSetCookieHeaders();
+  const stale = applied.filter((value) => !current.includes(value));
+  const added = current.filter((value) => !applied.includes(value));
+  if (stale.length === 0 && added.length === 0) return;
+
+  const kept = headers.getSetCookie();
+  for (const value of stale) {
+    const index = kept.indexOf(value);
+    if (index !== -1) kept.splice(index, 1);
+  }
+  headers.delete('Set-Cookie');
+  for (const value of [...kept, ...added]) headers.append('Set-Cookie', value);
+}
+
+/**
+ * Merge framework-managed response headers onto a terminal response without
+ * overwriting headers the terminal response already set itself.
+ */
+export function mergeMissingHeaders(target: Headers, source: Headers): void {
+  const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));
+  for (const [key, value] of source.entries()) {
+    if (!existingKeys.has(key.toLowerCase())) {
+      target.append(key, value);
+    }
+  }
+}
+
+// ─── Mutable Response Cloning ──────────────────────────────────────────────
+
+/**
+ * Clone a Response into a fresh one whose header bag is guaranteed mutable.
+ *
+ * `Response.redirect()` and some platform-level passthrough responses (notably
+ * on Cloudflare Workers) return objects with frozen header bags. Calling
+ * `.set()` or `.append()` on them throws `TypeError: immutable`, which the
+ * pipeline can hit when it appends Set-Cookie or Server-Timing entries.
+ *
+ * The pipeline calls this at the producer sites where user-controlled
+ * responses enter the framework — `outcomeToResponse` for all phase outcomes,
+ * and `handleRequest` for metadata-route and auto-sitemap user handlers — so
+ * downstream code can write headers without runtime feature-detection.
+ *
+ * The clone is unconditional. This is a deliberate trade: we avoid a
+ * try/catch + thrown `TypeError` on every request (the previous probe-based
+ * approach paid that cost on the hot path) and accept one cheap Response
+ * rewrap at the framework boundary instead.
+ */
+export function cloneWithMutableHeaders(response: Response): Response {
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: new Headers(response.headers),
+  });
+}
+
+// ─── Response Headers ──────────────────────────────────────────────────────
+
+/**
+ * A fresh response header bag for a page the pipeline renders, seeded with
+ * the default dynamic-page cache policy.
+ *
+ * Without a Cache-Control header, CDNs (particularly Cloudflare) may attempt
+ * to buffer/process the response differently, causing intermittent
+ * multi-second delays. This matches Next.js's default behavior. Every bag a
+ * rendered page can be written onto starts here — a matched route, the
+ * no-match 404, and a deny page for a proxy-phase signal — so none of them
+ * leaves without a cache policy. Middleware and route handlers may replace it.
+ */
+export function dynamicResponseHeaders(): Headers {
+  return new Headers({
+    'Cache-Control': 'private, no-cache, no-store, max-age=0, must-revalidate',
+  });
+}
+
+// ─── Redirect Builder ──────────────────────────────────────────────────────
+
+/**
+ * Build a redirect Response from a RedirectSignal.
+ *
+ * For a client navigation (an RSC payload request for a page), returns 204 +
+ * X-Timber-Redirect so the client router can perform a soft SPA redirect. A
+ * raw 302 would be turned into an opaque redirect by
+ * fetch({redirect:'manual'}), crashing createFromFetch. See
+ * design/19-client-navigation.md. The caller decides what counts as a
+ * navigation: a route.ts match answers with a real 3xx whatever it accepts.
+ */
+export function buildRedirectResponse(
+  signal: RedirectSignal,
+  headers: Headers,
+  navigation: boolean
+): Response {
+  if (navigation) {
+    headers.set('X-Timber-Redirect', signal.location);
+    return new Response(null, { status: 204, headers });
+  }
+  headers.set('Location', signal.location);
+  return new Response(null, { status: signal.status, headers });
+}
+
+// ─── Instrumentation ───────────────────────────────────────────────────────
+
+/**
+ * Where an error was raised: a pipeline phase, a server action, or a
+ * handler that answers outside the page pipeline — a metadata route or the
+ * auto-generated sitemap — which reports like a route.ts handler.
+ */
+export type ErrorSource = PhaseName | 'action' | 'route';
+
+/**
+ * Fire the user's onRequestError hook with request context.
+ *
+ * The one place a pipeline phase becomes the `phase` / `routeType` the hook
+ * reports, so every caller agrees. A render-phase error on a route.ts match
+ * is phase `'route'`, because the handler is what ran. Middleware reports
+ * as `'handler'`, its public name.
+ */
+export async function fireOnRequestError(
+  error: unknown,
+  req: Request,
+  source: ErrorSource,
+  segments?: readonly ManifestSegmentNode[]
+): Promise<void> {
+  // One rule for every caller (design/17 §"Which errors reach it"): outcomes
+  // and aborts are not failures, and neither is anything a request raises
+  // after its client left — a driver throwing "connection closed" is not a bug.
+  if (!isReportableError(error) || req.signal?.aborted) return;
+  if (isRepeatedLoadFailure(error)) return;
+  await callHook(error, req, source, segments);
+}
+
+/**
+ * Module evaluations whose failure was already reported. A module that fails
+ * to evaluate rethrows the same error on every later import, and
+ * `loadModule()` wraps each one in a new `ModuleLoadError` with that error
+ * as its `cause`. One broken module is one bug until it changes, however many
+ * loads trip over it in a request or across requests: the page's boundaries,
+ * then the fallback page, then the next request. A WeakSet, so a module that
+ * is re-evaluated (an HMR edit) gets a new cause and is reported again.
+ */
+const reportedLoadFailures = new WeakSet<object>();
+
+/**
+ * The same for a module that threw a primitive (`throw 'broken'`), which a
+ * WeakSet cannot hold. Keyed on the file and the value instead, so a module
+ * re-broken after an edit with the very same value is not reported again.
+ * It grows with the number of broken modules, not with requests.
+ */
+const reportedPrimitiveLoadFailures = new Set<string>();
+
+function isRepeatedLoadFailure(error: unknown): boolean {
+  if (!(error instanceof ModuleLoadError)) return false;
+  const cause: unknown = error.cause;
+  if (typeof cause === 'object' && cause !== null) {
+    if (reportedLoadFailures.has(cause)) return true;
+    reportedLoadFailures.add(cause);
+    return false;
+  }
+  const key = `${error.filePath}\0${typeof cause}\0${String(cause)}`;
+  if (reportedPrimitiveLoadFailures.has(key)) return true;
+  reportedPrimitiveLoadFailures.add(key);
+  return false;
+}
+
+/**
+ * Call the hook with request context, with no filtering. Only
+ * `fireOnRequestError()` and background reporting call it: background work
+ * runs after the response, so its request having aborted says nothing about
+ * the failure.
+ */
+async function callHook(
+  error: unknown,
+  req: Request,
+  source: ErrorSource,
+  segments?: readonly ManifestSegmentNode[]
+): Promise<void> {
+  if (!hasOnRequestError()) return;
+  const url = new URL(req.url);
+  const headersObj: Record<string, string> = {};
+  req.headers.forEach((v, k) => {
+    headersObj[k] = v;
+  });
+  const apiRoute = source === 'route' || (segments !== undefined && isApiRouteChain(segments));
+
+  await callOnRequestError(
+    error,
+    { method: req.method, path: url.pathname, headers: headersObj },
+    {
+      phase: reportedPhase(source, apiRoute),
+      routePath: url.pathname,
+      routeType: source === 'action' ? 'action' : apiRoute ? 'route' : 'page',
+      traceId: getTraceId(),
+    }
+  );
+}
+
+/**
+ * Whether an error is a failure `onRequestError` should hear about.
+ *
+ * Control-flow signals are outcomes the code chose — a `deny()` picks the
+ * page's status and data — and an abort is the client leaving. Callers answering
+ * a live request also skip everything once `req.signal` has aborted: a
+ * driver that throws "connection closed" after a disconnect is not a bug.
+ */
+export function isReportableError(error: unknown): boolean {
+  return !isControlFlowSignal(error) && !isAbortError(error);
+}
+
+/**
+ * Fire the hook without making the caller wait, for callers that cannot:
+ * Flight's `onError` is synchronous, and background work has no caller.
+ * The promise is registered with the request's `waitUntil` so platforms
+ * that stop work when the response ends (Workers, Lambda) let the hook
+ * finish. The hook's own failures are caught in `callOnRequestError()`.
+ */
+function fireInBackground(report: Promise<void>): void {
+  getWaitUntil()?.(
+    report.catch((hookError: unknown) => swallow(hookError, 'onRequestError could not be called'))
+  );
+}
+
+/**
+ * Log and report a render error that was answered in place rather than
+ * handed to the pipeline: a slot that degraded to its fallback, a Flight
+ * error row, a fallback page that failed and fell back again. The pipeline
+ * never sees these, so this is their one report. Errors that are not
+ * reportable (`isReportableError()`), or that arrive after the request
+ * aborted, are only logged.
+ */
+export function reportRenderError(
+  error: unknown,
+  req: Request,
+  details: { errorId?: string; segments?: readonly ManifestSegmentNode[] } = {}
+): void {
+  const { errorId, segments } = details;
+  logRenderError({ method: req.method, path: new URL(req.url).pathname, error, errorId });
+  fireInBackground(fireOnRequestError(error, req, 'render', segments));
+}
+
+/**
+ * Load a module the render can do without — a status page, an error page,
+ * `global-error.tsx`, a fallback page's layout — or report why it could not
+ * load and return `null`, so the next tier answers instead of the failure
+ * taking the page down. Every such load goes through here, whether it builds
+ * a boundary for a normal render or a fallback page, so a broken module is
+ * never skipped silently.
+ *
+ * Logged and reported once per broken file, not once per request: every
+ * request that renders under a broken `error.tsx` loads it again (TIM-1458).
+ * See `skippedFiles` for how "the same failure" is recognised. The first
+ * request to hit a failure is the one that reports it; if that request has
+ * already aborted, `fireOnRequestError()` drops the report and the failure is
+ * only logged.
+ *
+ * Never rejects, including when a user logger throws: building an error
+ * boundary must not itself throw (TIM-584), and the boundary walk does not
+ * catch for it.
+ */
+export async function loadFallbackModule(
+  file: ManifestLoader,
+  req: Request,
+  segments?: readonly ManifestSegmentNode[]
+): Promise<Record<string, unknown> | null> {
+  let loadError: unknown;
+  try {
+    const mod = await loadModule(file);
+    skippedFiles.delete(file.filePath);
+    return mod;
+  } catch (error) {
+    loadError = error;
+  }
+  const failure = loadError instanceof Error ? loadError.message : String(loadError);
+  if (skippedFiles.get(file.filePath) === failure) return null;
+  skippedFiles.set(file.filePath, failure);
+  try {
+    logSkippedModule({
+      method: req.method,
+      path: new URL(req.url).pathname,
+      file: file.filePath,
+      error: loadError,
+    });
+  } catch (logError) {
+    swallow(logError, 'logger.error threw while logging a skipped route file');
+  }
+  fireInBackground(fireOnRequestError(loadError, req, 'render', segments));
+  return null;
+}
+
+/**
+ * The failure each broken fallback file was last logged with, keyed by the
+ * file and compared by message — not by error identity. In Vite dev a file
+ * that fails to transform (a syntax error) is fetched again on every import,
+ * and the module runner revives the server's error as a new `Error` each
+ * time (`reviveInvokeError`), so identity never repeats; the message does.
+ * Keyed by file so two files skipped over one broken import each log.
+ *
+ * A successful load clears the file's entry, so fixing a file and breaking
+ * it again — even with the same message — logs again. An edit that changes
+ * the error changes the message and logs too. It grows with the number of
+ * broken files, not with requests.
+ */
+const skippedFiles = new Map<string, string>();
+
+/**
+ * Run a `cache.component` stale-while-revalidate re-render as a singleflight
+ * body, and log and report its failure once for the flight. The stale
+ * payload already answered, so nothing else sees the failure.
+ *
+ * - **Once per flight.** A `.catch` on the flight's promise would run once
+ *   per request that joined it, so the report happens inside the body. A
+ *   body still running when the singleflight times out is reported then,
+ *   with the timeout error (the signal's reason), and its later rejection
+ *   is dropped.
+ * - **Against the request whose stale read started it**, read from the
+ *   request context the work runs in. With no request (the build-time
+ *   capture store) it is only logged.
+ * - **As phase `'render'`, route type `'page`.** A `cache.component` is a
+ *   server component, so the read that started this was a page render (a
+ *   revalidated page tree included). The request's own abort does not
+ *   suppress the report: the work runs after the response either way.
+ */
+export async function runBackgroundFlight(
+  signal: AbortSignal,
+  work: () => Promise<unknown>,
+  log: (error: unknown) => void
+): Promise<void> {
+  const failed = (error: unknown): void => {
+    log(error);
+    const request = requestContextAls.getStore()?.request;
+    if (request && isReportableError(error)) fireInBackground(callHook(error, request, 'render'));
+  };
+  const onTimeout = (): void => failed(signal.reason);
+  signal.addEventListener('abort', onTimeout, { once: true });
+  try {
+    await work();
+  } catch (error) {
+    if (!signal.aborted) failed(error);
+  } finally {
+    signal.removeEventListener('abort', onTimeout);
+  }
+}
+
+function reportedPhase(
+  source: ErrorSource,
+  apiRoute: boolean
+): InstrumentationErrorContext['phase'] {
+  switch (source) {
+    case 'middleware':
+      return 'handler';
+    case 'render':
+      return apiRoute ? 'route' : 'render';
+    default:
+      return source;
+  }
+}