@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/client/rsc-fetch.ts

@@ -11,14 +11,41 @@
  * See design/19-client-navigation.md §"RSC Payload Handling"
  */
 
-import type { SegmentInfo } from './segment-cache';
-import type { RouterDeps } from './router';
+import {
+  rscCacheKey,
+  recordLookup,
+  randomRscCacheKey,
+  RSC_KEY_PARAM,
+} from '../shared/rsc-cache-key.js';
+import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.js';
+import {
+  splitPayloadRoot,
+  readPublishedParams,
+  type PublishedParams,
+} from '../shared/payload-root.js';
+import { normalizeBasePath, stripBasePath, withBasePath } from '../shared/base-path.js';
+import { rscPayloadPath } from '../shared/rsc-payload-path.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+import { TIMBER_ERROR_HEADER } from '../shared/rsc-error-envelope.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+import type { RouterDeps } from './router-types.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
 /** Result of fetching an RSC payload — includes segment metadata. */
 export interface FetchResult {
+  /** The renderable tree, split off the payload root. */
   payload: unknown;
+  /**
+   * The params the same payload published beside that tree.
+   *
+   * Not a separate channel: both fields come out of one `splitPayloadRoot`
+   * call on one decoded root, so a response cannot deliver a tree and another
+   * route's params. They used to arrive on their own header, which is how a
+   * navigation could render one route and publish another's (TIM-1285,
+   * TIM-1294).
+   */
+  params: PublishedParams | Promise<PublishedParams>;
   /**
    * Promise that settles when the RSC decode completes or fails.
    * The payload thenable is NOT awaited before returning (for streaming),
@@ -29,44 +56,55 @@ export interface FetchResult {
   decodePromise: Promise<void> | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
-  params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
+  /**
+   * HTTP status of the navigation response.
+   *
+   * Read at the commit site to decide whether the tree this payload produced
+   * is one worth caching. A deny page replaced a subtree, so `segmentInfo`
+   * describes more than actually mounted — but it cannot simply be emptied,
+   * because the merge point is chosen out of it. See TIM-1356.
+   */
+  status: number;
 }
 
-// ─── Constants ───────────────────────────────────────────────────
-
-export const RSC_CONTENT_TYPE = 'text/x-component';
-
 // ─── URL Helpers ─────────────────────────────────────────────────
 
 /**
- * Generate a short random cache-busting ID (5 chars, a-z0-9).
- * Matches the format Next.js uses for _rsc params.
- */
-function generateCacheBustId(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 5; i++) {
-    id += chars[(Math.random() * 36) | 0];
-  }
-  return id;
-}
-
-/**
- * Append a `_rsc=<id>` query parameter to the URL.
- * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
- * for RSC navigation requests and signals that this is an RSC fetch.
+ * Append a `_rsc=<key>` query parameter to the URL (TIM-1268).
+ *
+ * The key is a deterministic hash of the RSC request headers, so identical
+ * requests share a URL and the payload becomes cacheable. It also keeps the
+ * document and the payload on different URLs, so a shared cache cannot
+ * return HTML for an RSC request (or vice versa) even where `Vary` is
+ * opt-in configuration rather than default behaviour — Cloudflare and
+ * CloudFront both. See GHSA-wfc6-r584-vfw7, design/13-security.md.
+ *
+ * The origin recomputes this key from the received headers and refuses to
+ * let a mismatched response be shared-cached, so a caller cannot claim
+ * another client's key while sending its own headers.
+ *
+ * Falls back to a random value when no key can be derived — `crypto.subtle`
+ * is absent in non-secure browsing contexts (plain `http://` on a LAN
+ * address). Dropping the parameter instead would put the payload back on
+ * the document URL, where a query-keyed cache that ignores `Vary` could
+ * store a Flight response under `/about` and serve it to an HTML
+ * navigation. The random parameter this feature replaced did separate those
+ * representations, and the fallback must not be worse than what it
+ * replaced. The origin cannot verify a random key, so it refuses to
+ * share-cache the response — which is exactly the old behaviour, where a
+ * unique URL was never a cache hit anyway.
  *
  * Strips any #fragment before appending — fragments are client-only and
  * fetch() discards them, so _rsc would land inside the hash and be lost.
  */
-function appendRscParam(url: string): string {
+async function appendRscParam(url: string, headers: Record<string, string>): Promise<string> {
   const hashIndex = url.indexOf('#');
   const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const key = (await rscCacheKey(recordLookup(headers))) ?? randomRscCacheKey();
   const separator = urlWithoutHash.includes('?') ? '&' : '?';
-  return `${urlWithoutHash}${separator}_rsc=${generateCacheBustId()}`;
+  return `${urlWithoutHash}${separator}${RSC_KEY_PARAM}=${key}`;
 }
 
 // ─── Deployment ID ───────────────────────────────────────────────
@@ -88,6 +126,30 @@ export function getClientDeploymentId(): string | null {
   return clientDeploymentId;
 }
 
+// ─── Base Path ───────────────────────────────────────────────────
+
+/**
+ * The deployment base path (Vite's resolved `base`), normalized.
+ * Set at bootstrap from `virtual:timber-config`; `'/'` unless the app is
+ * deployed under a sub-path. See design/11-platform.md, TIM-1261.
+ *
+ * **The base is applied in exactly one place: at fetch time**
+ * (`toStaticRscUrl`). The static build writes the RSC manifest with
+ * root-relative keys *and* root-relative URLs, so the generated site stays
+ * relocatable and there is no second copy of the base to drift from this one.
+ */
+let basePath = '/';
+
+/** Set the deployment base path. Called once at bootstrap. */
+export function setBasePath(base: string | undefined): void {
+  basePath = normalizeBasePath(base);
+}
+
+/** Get the normalized deployment base path. @internal Exported for testing. */
+export function getBasePath(): string {
+  return basePath;
+}
+
 // ─── Static Mode ────────────────────────────────────────────────
 
 /**
@@ -107,20 +169,10 @@ export function isStaticMode(): boolean {
 }
 
 /**
- * RSC manifest entry: hashed URL with optional inlined route params.
- * Params are embedded at build time (TIM-1255) so no sidecar fetch needed.
- */
-interface RscManifestEntry {
-  url: string;
-  params?: Record<string, string | string[]>;
-}
-
-type RscManifest = Record<string, RscManifestEntry>;
-
-/**
- * RSC manifest mapping unhashed → hashed URLs + params. Populated from
- * `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during
- * static generation). See TIM-1254, TIM-1255.
+ * RSC manifest mapping unhashed → content-hashed `.rsc` URLs. Populated from
+ * `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during static
+ * generation). Shape shared with the static build that writes it — see
+ * `shared/rsc-manifest.ts`. See TIM-1254.
  */
 let rscManifest: RscManifest | null = null;
 
@@ -137,24 +189,45 @@ export function setRscManifest(manifest: RscManifest | null): void {
   rscManifest = manifest;
 }
 
+/** A resolved static payload target: the URL to fetch, and how it was resolved. */
+interface StaticRscTarget {
+  /** Fetchable URL — base-prefixed. */
+  url: string;
+  /**
+   * True when the RSC manifest supplied a content-hashed filename. The hash
+   * guarantees freshness, so no `_rsc` cache key is appended (TIM-1254).
+   */
+  hashed: boolean;
+}
+
 /**
- * Convert a route URL to the corresponding _rsc/*.rsc file path.
- * Mirrors the naming in plugins/static-build.ts staticOutputPath.
+ * Resolve a route URL to the `_rsc/*.rsc` file to fetch. The naming rule is
+ * `shared/rsc-payload-path.ts`, shared with the build that writes the files.
  *
  * When an RSC manifest is available (hashed filenames from TIM-1254),
  * the manifest is consulted to resolve to the hashed path.
  *
  *   /           → /_rsc/index.rsc (or /_rsc/index-B7YxEKdN.rsc with manifest)
- *   /about      → /_rsc/about.rsc (or /_rsc/about-C8ZzFLfO.rsc with manifest)
- *   /blog/hello → /_rsc/blog/hello.rsc
+ *   /about      → /_rsc/about/index.rsc (or /_rsc/about/index-C8ZzFLfO.rsc)
+ *   /blog/hello → /_rsc/blog/hello/index.rsc
+ *
+ * The manifest is written and read in route space (no base prefix), so the
+ * base is applied here — once, on the way out. See client/base-path.ts.
  */
-function toStaticRscUrl(url: string): string {
+function toStaticRscUrl(url: string): StaticRscTarget {
   const unhashed = toUnhashedRscUrl(url);
-  return manifestLookup(unhashed) ?? unhashed;
+  const hashedUrl = manifestLookup(unhashed);
+  return { url: withBasePath(basePath, hashedUrl ?? unhashed), hashed: hashedUrl !== null };
 }
 
 /**
- * Compute the unhashed _rsc/*.rsc URL for a route path.
+ * Compute the unhashed `_rsc/*.rsc` path for a route URL.
+ *
+ * Returns a **route-space** path: the deployment base is stripped from the
+ * incoming URL and is NOT re-applied, because this value doubles as the RSC
+ * manifest key, and the manifest is base-less. `toStaticRscUrl` applies the
+ * base to whatever is actually fetched.
+ *
  * @internal Exported for testing.
  */
 export function toUnhashedRscUrl(url: string): string {
@@ -163,13 +236,12 @@ export function toUnhashedRscUrl(url: string): string {
   const hashEnd = hashIndex === -1 ? url.length : hashIndex;
   const queryEnd = queryIndex === -1 ? url.length : queryIndex;
   const end = Math.min(hashEnd, queryEnd);
-  let pathname = url.slice(0, end);
+  let pathname = stripBasePath(basePath, url.slice(0, end));
   // Strip trailing slash (unless root) to match static build output naming
   if (pathname.length > 1 && pathname.endsWith('/')) {
     pathname = pathname.slice(0, -1);
   }
-  const rscPath = pathname === '/' ? '/index' : pathname;
-  return `/_rsc${rscPath}.rsc`;
+  return rscPayloadPath(pathname);
 }
 
 /**
@@ -196,13 +268,11 @@ function manifestLookup(key: string): string | null {
   return manifestEntry(key)?.url ?? null;
 }
 
-/**
- * Look up inlined route params for a route from the manifest. TIM-1255.
- */
-function manifestParams(url: string): Record<string, string | string[]> | null {
-  const key = toUnhashedRscUrl(url);
-  return manifestEntry(key)?.params ?? null;
-}
+// The manifest used to inline each route's params, because a generated
+// `.rsc` file carries no response headers and the header channel therefore
+// did not exist on the static path (TIM-1255, TIM-1285). The `.rsc` file now
+// carries them itself — they are props inside the payload — so the static
+// path needs no special case at all.
 
 // ─── Reload Signal ───────────────────────────────────────────────
 
@@ -222,8 +292,19 @@ export function checkReloadSignal(response: Response): boolean {
 
 // ─── Header Builder ──────────────────────────────────────────────
 
+/**
+ * Build the headers for an RSC payload request.
+ *
+ * **Every header added here is hashed into the payload URL** as the `_rsc`
+ * cache key (see `rscCacheKey`), and URLs are logged by proxies, CDNs, and
+ * origin access logs. So: no credentials, no session identifiers, no
+ * user-supplied content. `fnv1aHash` is a cache-key hash, not a KDF — a
+ * low-entropy secret would be recoverable from the URL by brute force.
+ * Authentication already travels on cookies, which are not part of this
+ * object and never enter the key.
+ */
 export function buildRscHeaders(
-  stateTree: { segments: string[] } | undefined,
+  stateTree: StateTree | undefined,
   currentUrl?: string
 ): Record<string, string> {
   const headers: Record<string, string> = {
@@ -301,23 +382,6 @@ export function extractSkippedSegments(response: Response): string[] | null {
   }
 }
 
-/**
- * Extract route params from the X-Timber-Params response header.
- * Returns null if the header is missing or malformed.
- *
- * Used to populate useSegmentParams() after client-side navigation.
- */
-export function extractParams(response: Response): Record<string, string | string[]> | null {
-  const header = response.headers.get('X-Timber-Params');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    warnMalformedHeader('X-Timber-Params', header);
-    return null;
-  }
-}
-
 // ─── Redirect Error ──────────────────────────────────────────────
 
 /**
@@ -388,9 +452,10 @@ export class NonRscResponse extends Error {
  * a `done` promise that resolves when the last chunk is read (or
  * rejects if the stream errors).
  *
- * Used to keep React transitions open for the full RSC stream
- * duration — createFromFetch's thenable resolves on shell arrival,
- * but we need stream completion for useOptimistic pending state.
+ * createFromFetch's thenable resolves on shell arrival, but callers need to
+ * know when the stream is fully decoded: that is what `navigateTransition`'s
+ * returned promise means, and what the router's pending store, the Navigation
+ * API deferred and `<Link>`'s `isPending` are all timed against.
  */
 function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
   body: ReadableStream<Uint8Array>;
@@ -445,13 +510,23 @@ export async function fetchRscPayload(
   // In static mode, fetch the pre-generated _rsc/*.rsc file directly
   // instead of the route URL with Accept headers. Static hosts ignore
   // Accept headers, so the route URL would return HTML.
-  const fetchTarget = staticMode ? toStaticRscUrl(url) : url;
-  // Skip the cache-bust param when the manifest supplies a content-hashed
+  const staticTarget = staticMode ? toStaticRscUrl(url) : null;
+  const fetchTarget = staticTarget ? staticTarget.url : url;
+  // Static hosts resolve neither partial payloads nor intercepting routes,
+  // so neither the state tree nor the source URL is sent — and neither may
+  // fragment the cache key of a file that does not vary on them.
+  const headers = staticMode
+    ? buildRscHeaders(undefined, undefined)
+    : buildRscHeaders(stateTree, currentUrl);
+  // Skip the cache key when the manifest supplies a content-hashed
   // URL — the hash itself guarantees freshness, and the param would defeat
   // the immutable cache headers on /_rsc/* (TIM-1254).
-  const isHashedFromManifest = staticMode && fetchTarget !== toUnhashedRscUrl(url);
-  const rscUrl = isHashedFromManifest ? fetchTarget : appendRscParam(fetchTarget);
-  const headers = buildRscHeaders(staticMode ? undefined : stateTree, currentUrl);
+  const rscUrl = staticTarget?.hashed ? fetchTarget : await appendRscParam(fetchTarget, headers);
+  // Deriving the cache key is async (SubtleCrypto), so the fetch is no
+  // longer issued in the same tick as the call. A navigation superseded
+  // during that window would otherwise still hit the network with an
+  // already-aborted signal.
+  signal?.throwIfAborted();
   if (deps.decodeRsc) {
     // Production path: use createFromFetch for streaming RSC decoding.
     // createFromFetch takes a Promise<Response> and progressively parses
@@ -461,8 +536,8 @@ export async function fetchRscPayload(
     // consumes the body. Reading headers does NOT consume the body stream.
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let segmentInfo: SegmentInfo[] | null = null;
-    let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
+    let status = 200;
     // Track when the full RSC body stream is consumed (not just shell).
     // Initialized to resolved for bodyless responses; overwritten when
     // the response has a body.
@@ -489,7 +564,7 @@ export async function fetchRscPayload(
       // with a JSON body instead of a broken RSC stream for any RenderError
       // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
       // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
-      if (response.headers.get('X-Timber-Error') === '1') {
+      if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
         throw new ServerErrorResponse(response.status, url);
       }
       // Content-Type guard: reject non-RSC responses before createFromFetch
@@ -517,13 +592,13 @@ export async function fetchRscPayload(
       // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
       // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
-      params = extractParams(response);
       skippedSegments = extractSkippedSegments(response);
+      status = response.status;
 
       // Wrap the body to track full stream consumption. createFromFetch's
       // thenable resolves when the root model (shell) arrives, but we need
-      // to know when ALL chunks are read so the React transition stays
-      // open for the full streaming duration (keeps useOptimistic alive).
+      // to know when ALL chunks are read — that is what the navigation
+      // promise resolving means, and what keeps the pending store set.
       if (response.body) {
         const tracked = trackStreamCompletion(response.body);
         streamDone = tracked.done;
@@ -535,34 +610,39 @@ export async function fetchRscPayload(
       }
       return response;
     });
-    // Await headers so segmentInfo/params are populated.
+    // Await headers so segmentInfo is populated.
     await wrappedPromise;
-    // In static mode, params come from the manifest (inlined at build
-    // time) since .rsc files have no HTTP headers. TIM-1255.
-    if (staticMode && !params) {
-      params = manifestParams(url);
-    }
     // Start decoding but do NOT await — return the in-progress thenable.
     // React can render a Flight thenable directly: it suspends on unresolved
     // parts and progressively renders as chunks arrive, spreading work across
     // frames instead of blocking the main thread in one burst.
-    const payload = deps.decodeRsc(wrappedPromise);
+    const root = deps.decodeRsc(wrappedPromise);
+    // One split, one root: the tree and the params it was rendered with come
+    // apart here and nowhere else, so nothing downstream has to keep them
+    // paired by hand.
+    const { tree: payload, params } = splitPayloadRoot(root);
     // Combine stream completion with payload error propagation.
-    // streamDone keeps the transition open for the full RSC stream
-    // duration (useOptimistic pending state). payloadError propagates
+    // streamDone marks the end of the RSC stream, which is what the
+    // navigation promise resolves on. payloadError propagates
     // decode failures (stale client references, Flight parse errors)
     // so the router's catch block can trigger recovery (stale reload).
     const payloadError = new Promise<void>((_, reject) => {
-      Promise.resolve(payload).then(() => {}, reject);
+      Promise.resolve(root).then(() => {}, reject);
     });
     payloadError.catch(() => {});
     const decodePromise = Promise.race([streamDone, payloadError]);
+    // Mark handled, like payloadError above. The same rejection reaches the
+    // router through `payload`, and a navigation that recovers by hard
+    // navigating (version skew, non-RSC response) hangs deliberately and never
+    // awaits this one — leaving it to surface as an unhandled rejection.
+    decodePromise.catch(() => {});
     return {
       payload,
+      params,
       decodePromise,
       segmentInfo,
-      params,
       skippedSegments,
+      status,
     };
   }
   // Test/fallback path: return raw text
@@ -575,7 +655,7 @@ export async function fetchRscPayload(
     }
   }
   // Server error guard (same as production path above).
-  if (response.headers.get('X-Timber-Error') === '1') {
+  if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
     throw new ServerErrorResponse(response.status, url);
   }
   // Content-Type guard (same as production path above). See TIM-1231, TIM-1243, TIM-1247.
@@ -599,16 +679,13 @@ export async function fetchRscPayload(
       throw new NonRscResponse(url);
     }
   }
-  let fallbackParams = extractParams(response);
-  // In static mode, params come from the manifest. TIM-1255.
-  if (staticMode && !fallbackParams) {
-    fallbackParams = manifestParams(url);
-  }
+  // Test/fallback path: raw text carries no payload root, so no params.
   return {
     payload: await response.text(),
+    params: readPublishedParams(undefined),
     decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
-    params: fallbackParams,
     skippedSegments: extractSkippedSegments(response),
+    status: response.status,
   };
 }