@rangojs/router 0.27.0 → 0.28.0

package/src/browser/server-action-bridge.ts

@@ -52,6 +52,7 @@ import { stampLocationState } from "./react/location-state-shared.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { revalidationErrorOf } from "../decode-loader-results.js";
 import { getAppVersion } from "./app-version.js";
+import { writePartialParams } from "./wire-protocol.js";
 import {
   decideCommitGatedOff,
   findActionFormData,
@@ -487,28 +488,16 @@ export function createServerActionBridge(
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
 
-      // Build action request URL with current segments
-      const url = new URL(window.location.href);
-      url.searchParams.set("_rsc_action", id);
-      url.searchParams.set(
-        "_rsc_segments",
-        segmentState.currentSegmentIds.join(","),
-      );
-      // Add version param for version mismatch detection
-      const version = getAppVersion();
-      if (version) {
-        url.searchParams.set("_rsc_v", version);
-      }
-      // Add router ID for app switch detection
-      const rid = store.getRouterId?.();
-      if (rid) {
-        url.searchParams.set("_rsc_rid", rid);
-      }
-      // The page's rewrite target: the server diffs the re-render against it.
-      const rewriteTarget = store.getHistoryEntryMemory()?.rewriteTarget;
-      if (rewriteTarget) {
-        url.searchParams.set("_rsc_rt", rewriteTarget);
-      }
+      // Build action request URL with current segments; the server diffs the
+      // re-render against the page's rewrite target.
+      const url = writePartialParams(new URL(window.location.href), {
+        action: id,
+        segmentIds: segmentState.currentSegmentIds,
+        emptySegments: "send",
+        version: getAppVersion(),
+        routerId: store.getRouterId?.(),
+        rewriteTarget: store.getHistoryEntryMemory()?.rewriteTarget,
+      });
 
       // Encode arguments
       const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -740,36 +729,50 @@ export function createServerActionBridge(
       }
 
       // Handle error responses with error boundary UI
-      if (isError && isPartial && segments && diff) {
+      if (isError && isPartial && segments) {
         log("processing error boundary response");
 
-        // Fail current handle BEFORE aborting all actions so the event controller
-        // records the error state (abortAllActions clears inflight entries)
+        // transition({ when }) sees action.error on the boundary commit and on
+        // a dropped one's follow-up.
+        whenAction = {
+          ...whenAction,
+          error: returnValue && !returnValue.ok ? returnValue.data : undefined,
+        };
+
+        // No consolidation: the boundary replaces the page, or the page left.
+        handle.clearConsolidation();
+
+        const currentKey = store.getHistoryKey();
+        const pageLeft = () =>
+          navigatedSince() || store.getHistoryKey() !== currentKey;
+        // The action's page left the screen (during the flight or the error
+        // render): drop the boundary; the call rejects and the exit owes the
+        // follow-up.
+        const dropBoundary = () => {
+          log("user navigated during error render, skipping");
+          if (returnValue && !returnValue.ok) throw returnValue.data;
+          handle.complete(undefined);
+          return undefined;
+        };
+        if (pageLeft()) return dropBoundary();
+
+        // fail() settles once the response's stream ends; the abort below
+        // spares this action, so its entry keeps the error for useAction().
         if (returnValue && !returnValue.ok) {
           handle.fail(returnValue.data);
         }
 
-        // Abort all other pending action requests - error takes precedence
-        // This prevents other actions from completing and overwriting the error UI
-        eventController.abortAllActions();
-
-        // Clear concurrent action tracking - no consolidation needed when showing error
-        handle.clearConsolidation();
+        // Abort the other actions in flight: the error takes precedence, so
+        // none completes over the boundary.
+        eventController.abortAllActions(handle.id);
 
         // Get current page's cached segments
-        const currentKey = store.getHistoryKey();
         const cached = store.getCachedSegments(currentKey);
         const cachedSegments = cached?.segments || [];
 
         // Reconcile error segments with cached tree
         const errorResult = reconcileErrorSegments(cachedSegments, segments);
 
-        // transition({ when }) decides the error-boundary commit too, with
-        // `action.error` set.
-        whenAction = {
-          ...whenAction,
-          error: returnValue && !returnValue.ok ? returnValue.data : undefined,
-        };
         const errorGatedOff = decideActionGatedOff(
           errorResult.segments,
           metadata,
@@ -786,28 +789,18 @@ export function createServerActionBridge(
               : undefined,
         });
 
-        // The page the action was sent from left the screen, during the
-        // flight or while the error tree rendered: the boundary is not shown,
-        // and the action's exit owes the page on screen the follow-up.
-        if (navigatedSince() || store.getHistoryKey() !== currentKey) {
-          log("user navigated during error render, skipping");
-          if (returnValue && !returnValue.ok) {
-            throw returnValue.data;
-          }
-          handle.complete(undefined);
-          return undefined;
-        }
-
-        // Update segment tracking to exclude error segment IDs
-        const errorSegmentIds = new Set(diff);
-        const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
-          (id) => !errorSegmentIds.has(id),
-        );
+        if (pageLeft()) return dropBoundary();
 
         // Cache (and bump the nav instance) BEFORE the UI update so a deferred
         // handle pushed by the error-boundary render still applies — see the
-        // "normal" case below for why caching after onUpdate dropped it.
-        store.setSegmentIds(segmentIdsAfterError);
+        // "normal" case below for why caching after onUpdate dropped it. The
+        // page stops claiming the error segments only: the loaders the
+        // response re-ran above the boundary stay held.
+        store.setSegmentIds(
+          segmentState.currentSegmentIds.filter(
+            (id) => !segments.some((s) => s.id === id && s.type === "error"),
+          ),
+        );
         const currentHandleData = liveHandleDataForCache(
           eventController,
           store,

package/src/browser/types.ts

@@ -649,7 +649,8 @@ export interface NavigationStore {
         handlesPending?: boolean;
       }
     | undefined;
-  hasHistoryCache(historyKey: string): boolean;
+  /** Whether an intercept entry is cached for the plain `historyKey`, from any source page. */
+  hasInterceptCache(historyKey: string): boolean;
   /**
    * Update only the handleData (and optionally the stale / handlesPending flags)
    * of an existing cache entry. When a flag is omitted the entry's current value

package/src/browser/wire-protocol.ts

@@ -0,0 +1,41 @@
+import { WIRE } from "../wire-params.js";
+
+/** The parameters of a partial request: a navigation, a prefetch or a JS server action. */
+export interface PartialRequestInit {
+  /** A JS server action's id: written as `_rsc_action` in place of `_rsc_partial`. */
+  action?: string;
+  /** The mounted segment ids the server diffs against. */
+  segmentIds: readonly string[];
+  /**
+   * An empty `segmentIds`: "send" writes `_rsc_segments=` (navigation,
+   * action), "omit" leaves it out (prefetch). The prefetch cache keys carry
+   * the difference.
+   */
+  emptySegments: "send" | "omit";
+  stale?: boolean;
+  version?: string;
+  routerId?: string;
+  rewriteTarget?: string;
+  fill?: boolean;
+}
+
+/**
+ * Writes the partial-request parameters onto `url` in the one order every
+ * sender uses. Navigation and prefetch cache keys are built from the result
+ * (prefetch/cache.ts), so a navigation adopts a prefetch only while both
+ * write identically: browser/__tests__/wire-urls.test.ts pins the strings.
+ */
+export function writePartialParams(url: URL, init: PartialRequestInit): URL {
+  const params = url.searchParams;
+  if (init.action !== undefined) params.set(WIRE.action, init.action);
+  else params.set(WIRE.partial, "true");
+  if (init.segmentIds.length > 0 || init.emptySegments === "send") {
+    params.set(WIRE.segments, init.segmentIds.join(","));
+  }
+  if (init.stale) params.set(WIRE.stale, "true");
+  if (init.version) params.set(WIRE.version, init.version);
+  if (init.routerId) params.set(WIRE.routerId, init.routerId);
+  if (init.rewriteTarget) params.set(WIRE.rewriteTarget, init.rewriteTarget);
+  if (init.fill) params.set(WIRE.fill, "1");
+  return url;
+}

package/src/cache/cache-key-utils.ts

@@ -187,8 +187,10 @@ export const KEY_PART_PREFIX = "key:";
  * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
  * results of the scope's cache() chain, outermost first, then its default
  * parts: the keyGenerator results of enclosing scopes on another store
- * (#974) and, for a record key under a scope without its own `key()`, its
- * default key (or its store's keyGenerator result, #970).
+ * (#974) and, for a route record key, the scope's own part: without a
+ * `key()` of its own, its default key (or its store's keyGenerator result,
+ * #970); with one, the default key's request kind (`doc`, `partial` or
+ * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
  * and a record key has no route or scope discriminator (the store reads
@@ -214,9 +216,13 @@ export const KEY_PART_PREFIX = "key:";
  * A namespaced `key()` result starts with `key:` and holds no `|`. A
  * composed key holds a `|` and either starts with `key:` or holds no `:`.
  * Among composed keys, splitting on `|` recovers each part, a part's kind
- * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
- * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
- * result is the store's own namespace, as before.
+ * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
+ * a default key's prefix without the URL after it, so it never equals a
+ * default key part; a keyGenerator part can equal it (`doc`) only when the
+ * keyGenerator returns a constant, which already gives every URL one record.
+ * Pinned by the collision probe in
+ * src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator result is
+ * the store's own namespace, as before.
  *
  * Shared with the testing helper `shellCacheKey`, so a test builds the
  * production partition.

package/src/cache/cache-runtime.ts

@@ -22,7 +22,7 @@ import {
 } from "../deps/rsc-client.js";
 import {
   getRequestContext,
-  runWithRequestContext,
+  type RequestContext,
 } from "../server/request-context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import {
@@ -34,7 +34,12 @@ import {
 } from "./taint.js";
 
 export { isCachedFunction };
-import { serializeResult, deserializeResult } from "./segment-codec.js";
+import {
+  serializeResult,
+  deserializeResult,
+  isUnsupportedValueError,
+  teeResult,
+} from "./segment-codec.js";
 import {
   appendHandles,
   encodeHandles,
@@ -70,6 +75,7 @@ import {
   executionStart,
   invalidatedSince,
   predatesInvalidation,
+  runAsBackgroundRefresh,
   type ExecutionStart,
 } from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
@@ -384,6 +390,23 @@ function refreshView(arg: unknown): unknown {
   });
 }
 
+/**
+ * Run `fn` inside a "use cache" execution's scopes: its exec scope
+ * (cookies()/headers() reads and ctx writes refuse) and its tag scope
+ * (cacheTag() and nested calls tag the entry, #980), `recorded` when given.
+ * The body runs here, and so does the value's encode: it renders the server
+ * components in the value, which are part of the entry. Scar: the encode ran
+ * in the tag scope only, so a returned component's cookies() read went
+ * through and the entry served the first visitor's value to the next.
+ */
+function inExecution<T>(
+  scope: CacheExecScope,
+  fn: () => T,
+  recorded?: Set<string>,
+): { result: T; tags: Set<string> } {
+  return runWithCacheTagScope(() => runWithCacheExecScope(fn, scope), recorded);
+}
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -459,14 +482,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const entryTags = (recorded: Set<string>): string[] => [
       ...new Set(normalizeTags([...(profile.tags ?? []), ...recorded])),
     ];
-    // The value's Flight encode runs back inside its execution's tag scope:
-    // it renders the server components in the value, and a "use cache" call
-    // or cacheTag() among them belongs to this entry (#980).
-    const inTagScope = <T>(
-      recorded: Set<string>,
-      encode: () => Promise<T>,
-    ): Promise<T> => runWithCacheTagScope(encode, recorded).result;
-
     // Separate request-scoped args (ctx, a Request, the request's env) from
     // key-generating args. For those that carry route context (ctx params,
     // pathname, searchParams; a Request's URL), extract serializable values
@@ -717,25 +732,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               // reads the ambient getRequestContext() (e.g.
               // getRequestContext().env.ApiKey) resolves during the background
               // revalidation instead of throwing "called outside of a request
-              // context". runWithRequestContext sets the store for fn's
-              // synchronous kickoff; its async continuations inherit it.
+              // context". runAsBackgroundRefresh sets the store for fn's
+              // synchronous kickoff; its async continuations inherit it. No
+              // visitor made the invalidations it runs: they set no
+              // fresh-reads cookie.
               //
               // The span opens inside the request ALS and wraps the WHOLE task —
               // fn kickoff through the store write — so its platform spans nest
               // under rango.background and a slow or failing setItem is part of
               // the traced revalidation, not an untraced tail.
-              await runWithRequestContext(requestCtx, () =>
+              await runAsBackgroundRefresh(requestCtx, () =>
                 observePhase(
                   PHASES.background("use-cache-revalidation"),
                   async () => {
                     const refreshArgs = args.map(refreshView);
                     // The refresh reads its data from here on (#973, #977).
                     const start = executionStart();
-                    const scoped = runWithCacheTagScope(() =>
-                      runWithCacheExecScope(
-                        () => fn.apply(this, refreshArgs),
-                        bgScope,
-                      ),
+                    const scoped = inExecution(bgScope, () =>
+                      fn.apply(this, refreshArgs),
                     );
                     const freshResult = await scoped.result;
                     bgCapture?.stop();
@@ -744,17 +758,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                     const onFlightError = (error: unknown): void => {
                       flightErrors.push(error);
                     };
-                    const serialized = await inTagScope(scoped.tags, () =>
-                      serializeResult(freshResult, onFlightError),
-                    );
+                    const serialized = await inExecution(
+                      bgScope,
+                      () => serializeResult(freshResult, onFlightError),
+                      scoped.tags,
+                    ).result;
                     if (serialized !== null) {
                       const encodedHandles = bgCapture
-                        ? await inTagScope(scoped.tags, () =>
-                            encodeHandles(
-                              bgCapture.capture.data,
-                              onFlightError,
-                            ),
-                          )
+                        ? await inExecution(
+                            bgScope,
+                            () =>
+                              encodeHandles(
+                                bgCapture.capture.data,
+                                onFlightError,
+                              ),
+                            scoped.tags,
+                          ).result
                         : undefined;
                       // An error row would replace the stale entry; the catch
                       // below reports it and the stale entry keeps serving.
@@ -921,21 +940,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // deliberately NOT stamped: a property on that SHARED object made every
     // parallel read on the request throw for the cached body's whole
     // execution window (a 2s cached fetch poisoned a sibling loader's
-    // cookies() — same hazard class as issue #684, plan 010).
+    // cookies() — same hazard class as issue #684, plan 010). Not as an
+    // argument either (getRequestContext(), any pass: a derived pass inherits
+    // `_requestRoot`): a derived pass's writers that it does not route to a
+    // sink check the request's own context (server/render-pass.ts), so the
+    // stamp failed a shell capture's or a background re-render's writes while
+    // a foreground body held it.
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
-      if (isTainted(arg)) {
+      if (isTainted(arg) && !(arg as RequestContext)._requestRoot) {
         stampCacheExec(arg as object);
         taintedArgs.push(arg);
       }
     }
 
     let result: any;
-    let scoped: ReturnType<typeof runWithCacheTagScope>;
+    let scoped: ReturnType<typeof inExecution>;
     try {
-      scoped = runWithCacheTagScope(() =>
-        runWithCacheExecScope(() => fn.apply(this, args), execScope),
-      );
+      scoped = inExecution(execScope, () => fn.apply(this, args));
       result = await scoped.result;
     } catch (execError) {
       // The function threw: drop the in-flight entry and reject any waiters so
@@ -957,25 +979,39 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const recorded = scoped!.tags;
     recordRequestTags(entryTags(recorded), requestCtx);
 
-    // Serialize + encode handles ONCE, resolve the in-flight envelope so any
-    // concurrent followers can serve a synthetic hit, then persist to the store.
-    // Fully non-blocking when waitUntil is available — the leader's response
-    // waits on neither serialization nor the store write.
+    // Encode the value ONCE, inside the execution's scopes, and hand the
+    // caller a decoded copy of it, as a hit does. The caller rendering
+    // `result` itself would share its lazy state (a React.lazy, a memoizing
+    // thenable) with the encode: whichever render reached it first decided
+    // its value for both, so a read the caller's render made outside the
+    // scope was stored for the next visitor. Then resolve the in-flight
+    // envelope so concurrent followers serve a synthetic hit, and persist.
+    // When waitUntil is available the leader waits for the copy's root row
+    // only, not for the rest of the encode or the store write.
+    const flightErrors: unknown[] = [];
+    const onFlightError = (error: unknown): void => {
+      flightErrors.push(error);
+    };
+    const encoded = inExecution(
+      execScope,
+      () => teeResult(result, onFlightError),
+      recorded,
+    ).result;
     const finalizeAndWrite = async (): Promise<void> => {
       let serialized: string | null;
       let encodedHandles: string | undefined;
-      const flightErrors: unknown[] = [];
-      const onFlightError = (error: unknown): void => {
-        flightErrors.push(error);
-      };
       try {
-        serialized = await inTagScope(recorded, () =>
-          serializeResult(result, onFlightError),
-        );
+        serialized = encoded ? await encoded.serialized : null;
+        // The returned tree renders only in the encode, so its cacheTag()
+        // calls tag the entry alone: record the entry's tags onto the
+        // request, as a hit does.
+        recordRequestTags(entryTags(recorded), requestCtx);
         encodedHandles = capture
-          ? await inTagScope(recorded, () =>
-              encodeHandles(capture.capture.data, onFlightError),
-            )
+          ? await inExecution(
+              execScope,
+              () => encodeHandles(capture.capture.data, onFlightError),
+              recorded,
+            ).result
           : undefined;
         // Flight encodes an async component that throws, or a rejected
         // promise in the result or a handle value, as an error row and
@@ -986,10 +1022,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         assertLoaderReadsClean(execScope);
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
-        // fresh) and nothing to write.
+        // fresh) and nothing to write. Logged too: a read the guard refused
+        // in the value is otherwise silent with no onError. An error the call
+        // also throws reaches onError once (the request dedups by identity).
         clearSelf();
         rejectEnvelope(buildError);
-        requestCtx?._reportBackgroundError?.(buildError, "cache-write");
+        reportCacheError(
+          buildError,
+          "cache-write",
+          `[use cache] "${id}" write`,
+          requestCtx,
+        );
         return;
       }
       if (serialized === null) {
@@ -1039,7 +1082,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
 
     await runBackground(requestCtx, finalizeAndWrite, true);
 
-    return result;
+    // The encode could not start: nothing is stored, the value renders live.
+    if (!encoded) return result;
+    try {
+      return await encoded.decoded;
+    } catch (decodeError) {
+      // The root row failed. A value Flight cannot encode (a function, a
+      // class instance) is not cached and renders live, as it always has;
+      // anything else, a refused read above all, fails the call as the same
+      // read in the body does, with the encode's own error (production
+      // Flight redacts the decoded one).
+      if (
+        flightErrors.length > 0 &&
+        flightErrors.every(isUnsupportedValueError)
+      ) {
+        return result;
+      }
+      throw flightErrors[0] ?? decodeError;
+    }
   };
 
   // Brand the wrapper so it can be detected at runtime (e.g., to prevent