@rangojs/router 0.5.2 → 0.6.0

package/src/cache/cache-runtime.ts

@@ -51,6 +51,7 @@ import {
   recordRequestTags,
   runWithCacheTagScope,
 } from "./cache-tag.js";
+import { runWithCacheExecScope } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
 import type { CacheItemResult } from "./types.js";
 
@@ -289,11 +290,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // cacheTag() call inside the function degrades to a no-op rather than
     // throwing "must be called inside a use cache function" - adopting cacheTag()
     // must not hard-fail in apps/tests without an item-capable cache configured.
-    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
-    // is intentionally NOT stamped here. It is a cached-path-only check; in the
-    // bypass the body actually executes, so the guarded side effects take effect
-    // and nothing is lost on a (non-existent) hit. Same applies to the
-    // non-serializable-args bypass below.
+    // Note: the cache-exec guards (cookies()/headers()/ctx.set() rejection —
+    // runWithCacheExecScope + the INSIDE_CACHE_EXEC arg stamp) are intentionally
+    // NOT active here. They are cached-path-only checks; in the bypass the body
+    // actually executes, so the guarded side effects take effect and nothing is
+    // lost on a (non-existent) hit. Same applies to the non-serializable-args
+    // bypass below.
     if (!store?.getItem) {
       // Test-ergonomics guard: under a test runner, a "use cache" function that
       // executes with no item-capable store seeded is exercising the UNCACHED
@@ -507,9 +509,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           // property stamped onto that SHARED object — so for the whole
           // revalidation window a concurrent foreground ctx.set() /
           // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
-          // not stamped for the same reason. In-fn misuse is already caught
-          // by the miss path's stamps on the function's FIRST execution — the
-          // background re-runs the same function with the same request.
+          // never stamped anywhere for the same reason. In-body misuse IS
+          // still guarded here: runWithCacheExecScope below follows only this
+          // body's async chain, so a conditional cookies()/headers() read
+          // that fires only during revalidation throws instead of baking one
+          // user's value into the shared entry — with zero visibility to the
+          // concurrent foreground.
 
           try {
             // Re-establish the request-context ALS so a "use cache" body that
@@ -530,7 +535,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                 PHASES.background("use-cache-revalidation"),
                 async () => {
                   const scoped = runWithCacheTagScope(() =>
-                    fn.apply(this, args),
+                    runWithCacheExecScope(() => fn.apply(this, args)),
                   );
                   const freshResult = await scoped.result;
                   bgStopCapture?.();
@@ -678,12 +683,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Uses ref-counted stamp/unstamp so overlapping executions
     // sharing the same ctx don't clear each other's guards.
     //
-    // LOAD-BEARING for the stale-revalidation path above: the background
-    // re-execution deliberately does NOT re-stamp (the objects are live
-    // foreground state mid-render), relying on THIS stamp having caught in-fn
-    // misuse on the function's first execution — an entry only becomes
-    // stale-revalidatable because a stamped miss ran clean and stored it. Do
-    // not create a "use cache" entry via any path that skips this stamp.
+    // The ambient guards (cookies()/headers() and getRequestContext()-reached
+    // ctx methods) ride runWithCacheExecScope below instead — an ALS scoped to
+    // the cached body's own async chain. The RequestContext itself is
+    // 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).
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
       if (isTainted(arg)) {
@@ -691,17 +697,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         taintedArgs.push(arg);
       }
     }
-    // Always stamp the ALS RequestContext so cookies()/headers() guards fire
-    // even when the cached function receives no tainted args. The guard in
-    // cookie-store.ts checks RequestContext, not function args.
-    if (requestCtx) {
-      stampCacheExec(requestCtx as object);
-    }
 
     let result: any;
     let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      scoped = runWithCacheTagScope(() =>
+        runWithCacheExecScope(() => fn.apply(this, args)),
+      );
       result = await scoped.result;
     } catch (execError) {
       // The function threw: drop the in-flight entry and reject any waiters so
@@ -714,9 +716,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       for (const arg of taintedArgs) {
         unstampCacheExec(arg as object);
       }
-      if (requestCtx) {
-        unstampCacheExec(requestCtx as object);
-      }
       // Remove this capture token (order-independent, safe for concurrent use)
       stopCapture?.();
     }

package/src/cache/taint.ts

@@ -21,14 +21,19 @@ export function isTainted(value: unknown): boolean {
 }
 
 /**
- * Symbol stamped on tainted ctx during "use cache" function execution.
- * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
- * throw if present — reads would cache per-request data under a shared key,
- * and side effects would be lost on cache hit.
+ * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
+ * function during its execution. ctx.set(), ctx.header(), etc. check this
+ * flag and throw if present — those side effects are lost on cache hit.
+ *
+ * Argument objects only. Ambient access (cookies()/headers() and ctx methods
+ * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope
+ * in cache-exec-scope.ts instead: stamping the SHARED RequestContext 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()).
  *
  * The value is a numeric reference count, not a boolean. Multiple concurrent
- * cached functions sharing the same ctx/requestCtx each increment on entry
- * and decrement on exit. Guards fire when count > 0.
+ * cached functions sharing the same ctx each increment on entry and decrement
+ * on exit. Guards fire when count > 0.
  */
 export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
   "rango:inside-cache-exec",
@@ -56,6 +61,20 @@ export function unstampCacheExec(obj: object): void {
   }
 }
 
+/**
+ * Probe for the AsyncLocalStorage-based "use cache" execution scope.
+ * Registered by cache-exec-scope.ts at module init; the default ("never
+ * inside") keeps this module free of node:async_hooks — taint.ts is reachable
+ * from browser-bundled DSL helpers. Covers AMBIENT ctx access inside a cached
+ * body (getRequestContext().set(...)) chain-scoped, where the object stamp
+ * below only covers ctx objects explicitly passed as arguments.
+ */
+let cacheExecScopeProbe: () => boolean = () => false;
+
+export function _setCacheExecScopeProbe(probe: () => boolean): void {
+  cacheExecScopeProbe = probe;
+}
+
 /**
  * Throw if ctx is inside a "use cache" execution.
  * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
@@ -64,12 +83,12 @@ export function assertNotInsideCacheExec(
   ctx: unknown,
   methodName: string,
 ): void {
-  if (
+  const argStamped =
     ctx !== null &&
     ctx !== undefined &&
     typeof ctx === "object" &&
-    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
-  ) {
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>);
+  if (argStamped || cacheExecScopeProbe()) {
     throw new Error(
       `ctx.${methodName}() cannot be called inside a "use cache" function. ` +
         `Side effects on the request context are lost on cache hit because ` +

package/src/client-urls/client-root.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import {
+  createElement,
+  Fragment,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { Outlet } from "../client.js";
+import { OutletProvider } from "../outlet-provider.js";
+import { useMount } from "../browser/react/use-mount.js";
+import {
+  registerClientUrlGroup,
+  type ClientUrlNavigationIntent,
+} from "./navigation.js";
+import type {
+  ClientUrlInterceptRecord,
+  ClientUrlPatterns,
+  ClientUrlRouteRecord,
+} from "./types.js";
+
+function findRoute(
+  definition: ClientUrlPatterns,
+  routeId: string,
+): ClientUrlRouteRecord {
+  const route = definition.routes.find((candidate) => candidate.id === routeId);
+  if (!route) {
+    throw new Error(
+      `Client URL route mismatch: route id "${routeId}" was not found in the provided definition`,
+    );
+  }
+  return route;
+}
+
+function findIntercept(
+  definition: ClientUrlPatterns,
+  interceptIndex: number,
+): ClientUrlInterceptRecord {
+  const record = definition.intercepts[interceptIndex];
+  if (!record) {
+    throw new Error(
+      `Client URL intercept mismatch: intercept index ${interceptIndex} was not found in the provided definition`,
+    );
+  }
+  return record;
+}
+
+/**
+ * Server-materialized wrapper layout for a clientUrls() group that declares
+ * intercepts. Attachment scar: intercepts emitted at the TOP LEVEL of a lazily
+ * included module attach to the isolated parent clone
+ * (getIsolatedLazyParent in server/context.ts) and are silently discarded —
+ * only intercepts attached to a layout entry created WITHIN the expansion
+ * survive in origin chains. Materialization therefore wraps the group's routes
+ * and intercept entries in this layout; it renders the child outlet plus one
+ * named outlet per declared slot, so the modal presents inside the group's own
+ * subtree (module-local declaration, module-local presentation).
+ */
+export function ClientUrlsGroupLayout({
+  slotNames,
+}: {
+  slotNames: readonly `@${string}`[];
+}): ReactNode {
+  return (
+    <Fragment>
+      <Outlet />
+      {slotNames.map((name) => (
+        <Outlet key={name} name={name} />
+      ))}
+    </Fragment>
+  );
+}
+
+/** Slot content for a client-declared intercept: renders the definition's
+ *  modal component; its useLoader() calls read the slot segment's loader data
+ *  from the surrounding outlet context. */
+export function ClientUrlsInterceptSlot({
+  definition,
+  interceptIndex,
+}: {
+  definition: ClientUrlPatterns;
+  interceptIndex: number;
+}): ReactNode {
+  const record = findIntercept(definition, interceptIndex);
+  return createElement(record.component, {
+    key: `intercept-${interceptIndex}`,
+  });
+}
+
+export function ClientUrlsInterceptLoading({
+  definition,
+  interceptIndex,
+}: {
+  definition: ClientUrlPatterns;
+  interceptIndex: number;
+}): ReactNode {
+  return findIntercept(definition, interceptIndex).loading ?? null;
+}
+
+export function ClientUrlsRoot({
+  definition,
+  routeId,
+  namePrefix = "",
+}: {
+  definition: ClientUrlPatterns;
+  routeId: string;
+  /** include() route-name prefix, injected at materialization for canonical
+   *  name composition (intercept-target coordination). */
+  namePrefix?: string;
+}): ReactNode {
+  // The include() mount prefix this group renders under ("/" at root). The
+  // module trie is built from definition-LOCAL patterns; navigation strips
+  // this prefix before matching (see stripMountPrefix in navigation.ts), the
+  // same way client href()/useMount resolve include-relative URLs.
+  const mount = useMount();
+  const [intent, setIntent] = useState<ClientUrlNavigationIntent | null>(null);
+  useEffect(
+    () => registerClientUrlGroup(definition, mount, namePrefix, setIntent),
+    [definition, mount, namePrefix],
+  );
+
+  const pendingRoute =
+    intent && intent.routeId !== routeId
+      ? findRoute(definition, intent.routeId)
+      : null;
+  // Presence must mirror the projection's hasLoading (`loading !== undefined`
+  // in server-projection.ts): a falsy-but-valid node like loading("") is still
+  // a configured destination loading state, not an absent one.
+  const hasPendingLoading =
+    pendingRoute !== null && pendingRoute.loading !== undefined;
+  const route = hasPendingLoading
+    ? pendingRoute
+    : findRoute(definition, routeId);
+  // ANY in-flight group navigation is pending — including same-route navs
+  // (intent.routeId === routeId). For the search-only shape (filters, tabs)
+  // the canonical commit is HELD in a transition (isSameStructureNav in
+  // partial-update.ts) with no content swap to signal progress — this flag
+  // is the only affordance. The urgent setIntent at nav start flips it
+  // immediately; the transition-wrapped clear() entangles with the held
+  // commit, so pending drops exactly when the data lands.
+  const pending = intent !== null;
+  let content: ReactNode = hasPendingLoading
+    ? pendingRoute.loading
+    : createElement(route.component, { key: route.id });
+
+  for (let index = route.layouts.length - 1; index >= 0; index--) {
+    const layoutKey = `${route.id}-layout-${index}`;
+    content = createElement(OutletProvider, {
+      key: layoutKey,
+      content,
+      pending,
+      children: createElement(route.layouts[index], { key: layoutKey }),
+    });
+  }
+
+  return content;
+}
+
+export function ClientUrlsLoading({
+  definition,
+  routeId,
+}: {
+  definition: ClientUrlPatterns;
+  routeId: string;
+}): ReactNode {
+  return findRoute(definition, routeId).loading ?? null;
+}