@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/src/client/rsc-fetch.ts

@@ -11,14 +11,40 @@
  * 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 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,8 +55,6 @@ 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;
 }
@@ -42,31 +66,39 @@ 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 +120,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,13 +163,14 @@ export function isStaticMode(): boolean {
 }
 
 /**
- * RSC manifest mapping unhashed → hashed URLs. Populated from
- * `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during
- * static generation). See TIM-1254.
+ * 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: Record<string, string> | null = null;
+let rscManifest: RscManifest | null = null;
 
-function getRscManifest(): Record<string, string> | null {
+function getRscManifest(): RscManifest | null {
   if (rscManifest) return rscManifest;
   if (typeof window !== 'undefined' && (window as any).__TIMBER_RSC_MANIFEST__) {
     rscManifest = (window as any).__TIMBER_RSC_MANIFEST__;
@@ -122,28 +179,49 @@ function getRscManifest(): Record<string, string> | null {
 }
 
 /** @internal Exported for testing. */
-export function setRscManifest(manifest: Record<string, string> | null): void {
+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 {
@@ -152,27 +230,19 @@ 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);
 }
 
-/**
- * Convert a route URL to the corresponding _rsc/*.params.json sidecar path.
- * Used in static mode to fetch route params that are normally carried
- * in the X-Timber-Params response header. See TIM-1246.
- *
- * Consults the RSC manifest for hashed filenames (TIM-1254).
- */
 /**
  * Look up a key in the RSC manifest, falling back to percent-decoded
- * lookup for encoded browser URLs. Returns null if not found.
+ * lookup for encoded browser URLs. Returns the entry or null.
  */
-function manifestLookup(key: string): string | null {
+function manifestEntry(key: string): RscManifestEntry | null {
   const manifest = getRscManifest();
   if (!manifest) return null;
   if (manifest[key]) return manifest[key];
@@ -185,11 +255,19 @@ function manifestLookup(key: string): string | null {
   return null;
 }
 
-function toStaticParamsUrl(url: string): string {
-  const unhashed = toUnhashedRscUrl(url).replace(/\.rsc$/, '.params.json');
-  return manifestLookup(unhashed) ?? unhashed;
+/**
+ * Look up the hashed URL for an unhashed RSC path.
+ */
+function manifestLookup(key: string): string | null {
+  return manifestEntry(key)?.url ?? 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 ───────────────────────────────────────────────
 
 /** Header name used by the server to signal a version skew reload. */
@@ -208,8 +286,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> = {
@@ -287,23 +376,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 ──────────────────────────────────────────────
 
 /**
@@ -374,9 +446,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>;
@@ -431,13 +504,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
@@ -446,23 +529,7 @@ export async function fetchRscPayload(
     // Intercept the response to read segment metadata before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-    // In static mode, fetch the params sidecar in parallel. The .rsc
-    // file has no HTTP headers, so params come from a .params.json
-    // sidecar written at build time. See TIM-1246.
-    const staticParamsFetch = staticMode
-      ? deps
-          .fetch(toStaticParamsUrl(url), { signal })
-          .then((r) => (r.ok ? (r.json() as Promise<Record<string, string | string[]>>) : null))
-          .catch((e) => {
-            if (e instanceof DOMException && e.name === 'AbortError') throw e;
-            return null;
-          })
-      : null;
-    // Observe the sidecar promise so its rejection doesn't become
-    // unhandled if wrappedPromise rejects first (TIM-1248).
-    staticParamsFetch?.catch(() => {});
     let segmentInfo: SegmentInfo[] | null = null;
-    let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
     // Track when the full RSC body stream is consumed (not just shell).
     // Initialized to resolved for bodyless responses; overwritten when
@@ -490,7 +557,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
@@ -518,13 +585,12 @@ 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);
 
       // 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;
@@ -536,33 +602,37 @@ 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 sidecar (header extraction
-    // returns null because .rsc files have no HTTP headers). TIM-1246.
-    if (staticParamsFetch && !params) {
-      params = await staticParamsFetch;
-    }
     // 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,
     };
   }
@@ -576,7 +646,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.
@@ -600,24 +670,12 @@ export async function fetchRscPayload(
       throw new NonRscResponse(url);
     }
   }
-  let fallbackParams = extractParams(response);
-  // In static mode, params come from the sidecar. TIM-1246.
-  if (staticMode && !fallbackParams) {
-    try {
-      const paramsResponse = await deps.fetch(toStaticParamsUrl(url), { signal });
-      if (paramsResponse.ok) {
-        fallbackParams = (await paramsResponse.json()) as Record<string, string | string[]>;
-      }
-    } catch (e) {
-      if (e instanceof DOMException && e.name === 'AbortError') throw e;
-      // No params sidecar — non-dynamic route, params stay null
-    }
-  }
+  // 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),
   };
 }