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

package/src/server/node-stream-transforms.ts

@@ -1,13 +1,14 @@
 /**
  * Node.js native stream transforms for SSR HTML post-processing.
  *
- * These are Node.js Transform stream equivalents of the Web Stream
- * transforms in html-injectors.ts. Used on Node.js/Bun where native
- * streams (C++ backed) are faster than Web Streams (JS reimplementation).
- *
- * The transforms are pure string operations on HTML chunks — the same
- * logic as the Web Stream versions, just wrapped in Node.js Transform
- * instead of Web TransformStream.
+ * Node.js `Transform` wrappers around the pure helpers in
+ * `html-injector-core.ts`. Used on Node.js / Bun where C++-backed
+ * native streams are significantly faster than the JS-implemented
+ * Web Streams. The Web `TransformStream` equivalents live in
+ * `html-injectors.ts` and wrap the same core — keep the two files
+ * byte-for-byte equivalent in behavior. If you fix a streaming bug
+ * here, it almost certainly belongs in the core (`html-injector-core.ts`),
+ * not in this wrapper.
  *
  * Architecture:
  *   renderToPipeableStream → pipe(errorHandler) → pipe(headInjector)
@@ -20,11 +21,21 @@
 import { Transform } from 'node:stream';
 import { createGzip, constants } from 'node:zlib';
 
+import {
+  BufferAggregator,
+  FlightInjectorCore,
+  SUFFIX_BYTES,
+  createInjectorState,
+  createSuffixState,
+  injectorFlush,
+  processInjectorChunk,
+  processSuffixChunk,
+  suffixFlush,
+} from './html-injector-core.js';
+import { logStreamingError } from './logger.js';
+
 // ─── Buffered Transform ──────────────────────────────────────────────────────
 
-/**
- * Options for the Node.js buffered transform.
- */
 export interface NodeBufferedTransformOptions {
   /**
    * Flush synchronously once the buffer reaches this many bytes.
@@ -35,51 +46,44 @@ export interface NodeBufferedTransformOptions {
 }
 
 /**
- * Node.js Transform that buffers incoming chunks and coalesces them
+ * Node.js `Transform` that buffers incoming chunks and coalesces them
  * within a single event loop tick.
  *
- * Equivalent to createBufferedTransformStream() in html-injectors.ts.
- * React Fizz may emit multiple micro-chunks within a single flush.
- * Without buffering, downstream transforms (especially flight injection)
- * could see chunk boundaries in the middle of HTML tags or attributes.
- *
- * This transform collects all chunks that arrive in the same tick and
- * emits them as a single concatenated Buffer on the next `setImmediate`.
+ * Equivalent to `createBufferedTransformStream` in `html-injectors.ts` —
+ * the actual buffer math lives in `BufferAggregator`. This wrapper only
+ * owns the `setImmediate` scheduling and the push to the Node `Transform`.
  *
- * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
- * cycle — no recursive scheduling, no busy-wait. See design/02 §"No Polling".
- *
- * Inspired by Next.js `createBufferedTransformStream`.
+ * **Not a polling loop.** Single-shot `setImmediate` per flush cycle —
+ * no recursive scheduling. See design/02 §"No Polling".
  */
 export function createNodeBufferedTransform(options: NodeBufferedTransformOptions = {}): Transform {
-  const { maxBufferByteLength = Infinity } = options;
-
-  let bufferedChunks: Buffer[] = [];
-  let bufferByteLength = 0;
+  const buffer = new BufferAggregator(options.maxBufferByteLength ?? Infinity);
   let pendingImmediate: ReturnType<typeof setImmediate> | null = null;
 
+  const flushBuffer = () => {
+    const merged = buffer.drain();
+    if (merged) transform.push(merged);
+  };
+
   const transform = new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      bufferedChunks.push(chunk);
-      bufferByteLength += chunk.byteLength;
-
-      if (bufferByteLength >= maxBufferByteLength) {
-        // Synchronous flush — buffer is too large to hold
+      const overCap = buffer.append(chunk);
+      if (overCap) {
+        // Buffer too large to hold — flush synchronously now.
         flushBuffer();
       } else if (!pendingImmediate) {
         // Schedule a deferred flush for end of this tick.
-        // Single-shot setImmediate — NOT a recursive loop.
-        // See design/02 §"No Polling".
+        // Single-shot setImmediate — NOT a recursive loop. See design/02
+        // §"No Polling".
         pendingImmediate = setImmediate(() => {
           pendingImmediate = null;
           flushBuffer();
         });
       }
-
       callback();
     },
     flush(callback) {
-      // Cancel any pending deferred flush and flush synchronously
+      // Cancel any pending deferred flush and flush synchronously.
       if (pendingImmediate) {
         clearImmediate(pendingImmediate);
         pendingImmediate = null;
@@ -89,94 +93,52 @@ export function createNodeBufferedTransform(options: NodeBufferedTransformOption
     },
   });
 
-  function flushBuffer() {
-    if (bufferedChunks.length === 0) return;
-
-    const merged = Buffer.concat(bufferedChunks, bufferByteLength);
-    bufferedChunks = [];
-    bufferByteLength = 0;
-    transform.push(merged);
-  }
-
   return transform;
 }
 
-// ─── Injection Transforms ────────────────────────────────────────────────────
-
-import { createMachine } from '../utils/state-machine.js';
-import { flightChunkScript } from './flight-scripts.js';
-import {
-  flightInjectionTransitions,
-  isHtmlDone,
-  isPullDone,
-  type FlightInjectionState,
-  type FlightInjectionEvent,
-} from './flight-injection-state.js';
-import { withTimeout, RenderTimeoutError } from './render-timeout.js';
-import { logStreamingError } from './logger.js';
-
 // ─── Move Suffix Transform ───────────────────────────────────────────────────
 
-const SUFFIX = '</body></html>';
-const SUFFIX_BUF = Buffer.from(SUFFIX, 'utf-8');
-
 /**
- * Node.js Transform that moves `</body></html>` to the end of the stream.
+ * Node.js `Transform` that moves `</body></html>` to the end of the stream.
  *
- * Equivalent to createMoveSuffixStream() in html-injectors.ts.
- * Strips the suffix when first encountered and re-emits it in flush().
- * If no suffix is found, it's appended anyway for well-formed HTML.
+ * Equivalent to `createMoveSuffixStream` in `html-injectors.ts`. Strips
+ * the suffix on first sight and re-emits it from `flush()`. If the
+ * suffix never appeared in the input, it is appended anyway so output
+ * is well-formed.
  */
 export function createNodeMoveSuffixTransform(): Transform {
-  let foundSuffix = false;
+  const state = createSuffixState();
 
   return new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      if (foundSuffix) {
+      const result = processSuffixChunk(state, chunk);
+      if (result.kind === 'passthrough' || result.kind === 'noSuffix') {
         this.push(chunk);
         callback();
         return;
       }
-
-      const text = chunk.toString('utf-8');
-      const idx = text.indexOf(SUFFIX);
-      if (idx === -1) {
-        this.push(chunk);
-        callback();
-        return;
-      }
-
-      foundSuffix = true;
-
-      // If the entire chunk is exactly the suffix, skip it
-      if (chunk.byteLength === SUFFIX_BUF.byteLength) {
-        callback();
-        return;
-      }
-
-      // Emit content before the suffix
-      const before = text.slice(0, idx);
-      const after = text.slice(idx + SUFFIX.length);
-      if (before) this.push(Buffer.from(before, 'utf-8'));
-      if (after) this.push(Buffer.from(after, 'utf-8'));
+      if (result.before) this.push(Buffer.from(result.before));
+      if (result.after) this.push(Buffer.from(result.after));
       callback();
     },
     flush(callback) {
-      // Always emit the suffix at the very end
-      this.push(SUFFIX_BUF);
+      this.push(Buffer.from(suffixFlush(state)));
       callback();
     },
   });
 }
 
+// Re-export for tests / consumers that need the suffix bytes constant.
+export { SUFFIX_BYTES };
+
 // ─── Head Injection ──────────────────────────────────────────────────────────
 
 /**
- * Node.js Transform that injects HTML content before </head>.
+ * Node.js `Transform` that injects HTML content before `</head>`.
  *
- * Equivalent to injectHead() in html-injectors.ts. Streams chunks
+ * Equivalent to `injectHead` in `html-injectors.ts`. Streams chunks
  * through immediately, keeping only a small trailing buffer to handle
- * </head> split across chunk boundaries.
+ * `</head>` split across chunk boundaries.
  */
 export function createNodeHeadInjector(headHtml: string): Transform {
   if (!headHtml) {
@@ -187,41 +149,21 @@ export function createNodeHeadInjector(headHtml: string): Transform {
     });
   }
 
-  const target = '</head>';
-  const tailLen = target.length - 1;
-  let injected = false;
-  let tail = '';
+  const state = createInjectorState({ content: headHtml, targetTag: '</head>' });
 
   return new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      if (injected) {
+      const result = processInjectorChunk(state, chunk);
+      if (result.kind === 'passthrough') {
         callback(null, chunk);
         return;
       }
-
-      const text = tail + chunk.toString('utf-8');
-      const tagIndex = text.indexOf(target);
-
-      if (tagIndex !== -1) {
-        const before = text.slice(0, tagIndex);
-        const after = text.slice(tagIndex);
-        this.push(Buffer.from(before + headHtml + after, 'utf-8'));
-        injected = true;
-        tail = '';
-        callback();
-      } else {
-        const safeEnd = Math.max(0, text.length - tailLen);
-        if (safeEnd > 0) {
-          this.push(Buffer.from(text.slice(0, safeEnd), 'utf-8'));
-        }
-        tail = text.slice(safeEnd);
-        callback();
-      }
+      if (result.bytes) this.push(Buffer.from(result.bytes));
+      callback();
     },
     flush(callback) {
-      if (!injected && tail) {
-        this.push(Buffer.from(tail, 'utf-8'));
-      }
+      const leftover = injectorFlush(state);
+      if (leftover) this.push(Buffer.from(leftover));
       callback();
     },
   });
@@ -229,35 +171,37 @@ export function createNodeHeadInjector(headHtml: string): Transform {
 
 // ─── RSC Flight Injection ────────────────────────────────────────────────────
 
-/**
- * Node.js Transform that merges RSC script tags into the HTML stream.
- *
- * Reads RSC chunks from the provided ReadableStream and injects them
- * as `<script>` tags between HTML chunks. Scripts are buffered in
- * pending[] and only drained from transform() (after a complete HTML
- * chunk) or flush() — never pushed directly from the pull loop.
- *
- * Suffix stripping (</body></html>) is handled upstream by
- * createNodeMoveSuffixTransform. This transform only interleaves
- * RSC scripts at safe chunk boundaries.
- *
- * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
- * stream). We read from it using the Web API — this is the one bridge
- * point between Web Streams and Node.js streams in the pipeline.
- */
 /**
  * Options for the Node.js flight injector.
  */
 export interface NodeFlightInjectorOptions {
   /**
-   * Timeout in milliseconds for individual RSC stream reads.
-   * If a single `rscReader.read()` call does not resolve within
-   * this duration, the read is aborted and the stream errors with
-   * a RenderTimeoutError. Default: 30000 (30s).
+   * Timeout in milliseconds for individual RSC stream reads. If a single
+   * `rscReader.read()` call does not resolve within this duration, the
+   * read is aborted and the stream errors with a `RenderTimeoutError`.
+   * Default: 30000 (30s).
    */
   renderTimeoutMs?: number;
 }
 
+/**
+ * Node.js `Transform` that merges RSC script tags into the HTML stream.
+ *
+ * Equivalent to `createFlightInjectionTransform` in `html-injectors.ts`.
+ * The state machine, pending queue, and pull loop all live in
+ * `FlightInjectorCore` — this wrapper only shuffles bytes between the
+ * core and the Node `Transform.push()` API.
+ *
+ * Suffix stripping (`</body></html>`) is handled upstream by
+ * `createNodeMoveSuffixTransform`. RSC scripts are buffered in
+ * `core.pending[]` and only drained from `transform()` (after a complete
+ * HTML chunk) or `flush()` — never mid-tag. See design/02
+ * §"Scripts at Chunk Boundaries Only".
+ *
+ * The RSC stream is a Web `ReadableStream` (from the tee'd RSC Flight
+ * stream). The core reads from it using the Web API — this is the one
+ * bridge point between Web Streams and Node.js streams in the pipeline.
+ */
 export function createNodeFlightInjector(
   rscStream: ReadableStream<Uint8Array> | undefined,
   options?: NodeFlightInjectorOptions
@@ -270,136 +214,53 @@ export function createNodeFlightInjector(
     });
   }
 
-  const timeoutMs = options?.renderTimeoutMs ?? 30_000;
-  const rscReader = rscStream.getReader();
-  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const core = new FlightInjectorCore(rscStream, options?.renderTimeoutMs);
 
-  const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
-    initial: { phase: 'init' },
-    transitions: flightInjectionTransitions,
-  });
-
-  // Stored promise from pullLoop — awaited in flush() via .then()
-  // instead of polling. See design/02 §"No Polling".
-  let pullPromise: Promise<void> | null = null;
-
-  // RSC script chunks waiting to be drained at a safe boundary.
-  // pullLoop buffers here; transform() and flush() drain.
-  // RSC script chunks waiting to be drained at a safe boundary.
-  // pullLoop buffers here; transform(), flush(), and pullLoop's
-  // post-yield drain all consume from this buffer.
-  const pending: Buffer[] = [];
-  async function pullLoop(): Promise<void> {
-    // Yield once so the first transform() call can process the shell
-    // HTML chunk before we start reading RSC data.
-    await new Promise<void>((r) => setImmediate(r));
-    try {
-      for (;;) {
-        // Guard each RSC read with a timeout so a permanently hung
-        // RSC stream eventually aborts instead of blocking forever.
-        // See design/02-rendering-pipeline.md §"Streaming Constraints".
-        const readPromise = rscReader.read();
-        const { done, value } =
-          timeoutMs > 0
-            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
-            : await readPromise;
-        if (done) {
-          machine.send({ type: 'PULL_DONE' });
-          return;
-        }
-        const decoded = decoder.decode(value, { stream: true });
-        const scriptBuf = Buffer.from(flightChunkScript(decoded), 'utf-8');
-        // Buffer the script — drained by the next transform() call,
-        // flush(), or by the scheduled drain below.
-        pending.push(scriptBuf);
-        // Yield between reads so HTML chunks get priority in the event
-        // loop — but only while HTML is still streaming. Once flush()
-        // fires, read without yielding to drain remaining RSC data.
-        if (!isHtmlDone(machine.state)) {
-          await new Promise<void>((r) => setImmediate(r));
-          // After yielding, if no transform() call drained the buffer
-          // (i.e., no new HTML chunk arrived), drain now. This ensures
-          // RSC flight data reaches the client at shell-flush time —
-          // without this, hydration blocks on createFromReadableStream
-          // waiting for data that's stuck in pending[].
-          // This is safe: we're between event loop ticks, so no
-          // transform() call is mid-execution (no mid-tag risk).
-          if (pending.length > 0) {
-            drainPending();
-          }
-        }
-      }
-    } catch (err) {
-      // On timeout, cancel the RSC reader to release resources.
-      if (err instanceof RenderTimeoutError) {
-        rscReader.cancel(err).catch(() => {});
-      }
-      machine.send({ type: 'PULL_ERROR', error: err });
-    }
-  }
-
-  /** Drain all buffered RSC script chunks to the transform output. */
-  function drainPending(): void {
-    while (pending.length > 0) {
-      transform.push(pending.shift()!);
-    }
-  }
-
-  // No bootstrap script here — the init script is in <head> via
-  // flightInitScript() (see flight-scripts.ts). This ensures __timber_f
-  // exists before any chunk scripts execute.
+  const drain = (): void => {
+    while (core.pending.length > 0) transform.push(Buffer.from(core.pending.shift()!));
+  };
 
   const transform = new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      const isFirst = machine.state.phase === 'init';
-      if (isFirst) {
-        machine.send({ type: 'FIRST_CHUNK' });
-      }
+      const wasInit = core.isInit;
+      if (wasInit) core.notifyFirstChunk();
 
       // Emit the HTML chunk, then drain any buffered RSC scripts.
       // Scripts always come AFTER a complete HTML chunk — never mid-tag.
-      // The buffered transform upstream (TIM-528) ensures each chunk is
-      // a coherent HTML fragment. Suffix stripping is handled upstream
-      // by createNodeMoveSuffixTransform (TIM-530).
+      // The buffered transform upstream (TIM-528) ensures coherent chunks.
+      // Suffix stripping is upstream via createNodeMoveSuffixTransform (TIM-530).
       transform.push(chunk);
-      drainPending();
+      drain();
 
       // Start the pull loop on the first HTML chunk.
-      if (isFirst) {
-        pullPromise = pullLoop();
-      }
+      if (wasInit) core.ensurePullLoop(drain);
       callback();
     },
     flush(callback) {
-      // All HTML chunks have been emitted. Transition to flushing —
-      // the pull loop will stop yielding between RSC reads since
-      // isHtmlDone() now returns true.
-      machine.send({ type: 'HTML_DONE' });
+      // All HTML chunks have been emitted. Pull loop stops yielding.
+      core.notifyHtmlDone();
 
       const finish = () => {
-        // Drain any remaining buffered RSC scripts
-        drainPending();
-        if (machine.state.phase === 'error') {
-          const err = machine.state.error;
+        drain();
+        const err = core.terminalError;
+        if (err !== null) {
           transform.destroy(err instanceof Error ? err : new Error(String(err)));
           return;
         }
         callback();
       };
 
-      if (isPullDone(machine.state)) {
+      if (core.isPullDone) {
         finish();
         return;
       }
-      // Wait for the RSC pull loop promise to resolve instead of
-      // polling with setImmediate. No CPU spin, no busy-poll —
-      // just a Promise chain. See design/02 §"No Polling".
-      if (!pullPromise) {
-        pullPromise = pullLoop();
-      }
-      pullPromise.then(finish, (err) => {
-        machine.send({ type: 'PULL_ERROR', error: err });
-        finish();
+      // Wait on the pull-loop promise instead of polling. Zero CPU cost
+      // while waiting. See design/02 §"No Polling".
+      core.ensurePullLoop(drain).then(finish, (err) => {
+        // ensurePullLoop's underlying loop catches its own errors and
+        // sends PULL_ERROR — this catch is defence-in-depth for any
+        // synchronous throws inside the .then() chain itself.
+        transform.destroy(err instanceof Error ? err : new Error(String(err)));
       });
     },
   });
@@ -459,7 +320,6 @@ const COMPRESSIBLE_TYPES = new Set([
   'application/xml',
   'application/xhtml+xml',
   'application/rss+xml',
-  'application/atom+xml',
   'image/svg+xml',
 ]);
 

package/src/server/pipeline-helpers.ts

@@ -0,0 +1,180 @@
+/**
+ * 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.js';
+import { getSetCookieHeaders } from './request-context.js';
+import { callOnRequestError } from './instrumentation.js';
+import { getTraceId } from './tracing.js';
+import { RedirectSignal } from './primitives.js';
+import type { ProxyConfig } from './pipeline.js';
+
+// ─── Prototype-Pollution-Safe Merge ────────────────────────────────────────
+
+/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Shallow merge that skips top-level prototype-polluting keys.
+ *
+ * This is intentionally NOT a deep sanitizer. It only blocks shallow
+ * pollution via top-level `__proto__` / `constructor` / `prototype`
+ * keys. The deeper guarantee for segment params comes from merging
+ * codec output into a null-prototype target inside coerceSegmentParams().
+ *
+ * See TIM-655, TIM-855, design/13-security.md
+ */
+export function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      target[key] = source[key];
+    }
+  }
+}
+
+// ─── 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);
+  }
+}
+
+/**
+ * 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),
+  });
+}
+
+// ─── Redirect Builder ──────────────────────────────────────────────────────
+
+/**
+ * Build a redirect Response from a RedirectSignal.
+ *
+ * For RSC payload requests (client navigation), 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.
+ */
+export function buildRedirectResponse(
+  signal: RedirectSignal,
+  req: Request,
+  headers: Headers
+): Response {
+  const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+  if (isRsc) {
+    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 ───────────────────────────────────────────────────────
+
+/**
+ * Fire the user's onRequestError hook with request context.
+ * Extracts request info from the Request object and calls the instrumentation hook.
+ */
+export async function fireOnRequestError(
+  error: unknown,
+  req: Request,
+  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
+): Promise<void> {
+  const url = new URL(req.url);
+  const headersObj: Record<string, string> = {};
+  req.headers.forEach((v, k) => {
+    headersObj[k] = v;
+  });
+
+  await callOnRequestError(
+    error,
+    { method: req.method, path: url.pathname, headers: headersObj },
+    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
+  );
+}