@rangojs/router 0.22.1 → 0.24.0

package/src/cache/document-cache.ts

@@ -14,8 +14,12 @@
  */
 
 import { requestHeaders } from "../server/request-headers.js";
+import { FILL_PARAM } from "../prefetch-markers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { hasPerClientSignal } from "../browser/cookie-name.js";
+import {
+  documentCacheStoresRender,
+  shouldCacheResponse,
+} from "./document-cache-policy.js";
 import {
   getRequestContext,
   runWithRequestContext,
@@ -36,11 +40,14 @@ import {
   predatesInvalidation,
 } from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { isRewrite } from "../route-definition/rewrite.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
 
+export { documentCacheStoresRender };
+
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
 function collectRequestTags(
@@ -61,112 +68,6 @@ function hashSegmentIds(segmentIds: string): string {
   return Math.abs(hash).toString(36);
 }
 
-// ============================================================================
-
-interface CacheDirectives {
-  sMaxAge?: number;
-  staleWhileRevalidate?: number;
-}
-
-/**
- * Parse Cache-Control header for s-maxage and stale-while-revalidate directives
- */
-function parseCacheControl(header: string | null): CacheDirectives | null {
-  if (!header) return null;
-
-  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
-  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
-  // The document cache is a shared app store, so refuse both regardless of any
-  // s-maxage / stale-while-revalidate also present. Match standalone directive
-  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
-  // substring, so a value containing "private" cannot false-veto.
-  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
-    return null;
-  }
-
-  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
-  // response without successful origin validation. This store's hit path has no
-  // validation step, so serving a stored no-cache response within s-maxage
-  // would hand the client content the origin marked must-revalidate. Refuse to
-  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
-  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
-  // boundary is excluded from the lookahead (unlike private/no-store above).
-  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
-    return null;
-  }
-
-  const directives: CacheDirectives = {};
-
-  // Parse s-maxage
-  const sMaxAgeMatch = header.match(/s-maxage\s*=\s*(\d+)/i);
-  if (sMaxAgeMatch) {
-    directives.sMaxAge = parseInt(sMaxAgeMatch[1], 10);
-  }
-
-  // Parse stale-while-revalidate
-  const swrMatch = header.match(/stale-while-revalidate\s*=\s*(\d+)/i);
-  if (swrMatch) {
-    directives.staleWhileRevalidate = parseInt(swrMatch[1], 10);
-  }
-
-  // Only return if we have at least s-maxage (required for document caching)
-  if (directives.sMaxAge !== undefined) {
-    return directives;
-  }
-
-  return null;
-}
-
-/**
- * Check if response should be cached based on Cache-Control headers
- */
-function shouldCacheResponse(
-  response: Response,
-  requestCtx?: Pick<RequestContext, "_payloadVisitorTheme">,
-): CacheDirectives | null {
-  // Only cache successful responses
-  if (response.status !== 200) {
-    return null;
-  }
-
-  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
-  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
-  // loader set) would be replayed to every client on a hit — pinning them to
-  // one value and even rolling a rotated client back to a prior one. The
-  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
-  // would suppress invalidation for every replayed client. Refuse both.
-  if (hasPerClientSignal(response.headers)) {
-    return null;
-  }
-
-  // The payload carries the visitor's theme (#978): the render ran before the
-  // response opted in (a Cache-Control written after next()), so
-  // payloadInitialTheme could not render the default.
-  if (requestCtx?._payloadVisitorTheme) {
-    return null;
-  }
-
-  const cacheControl = response.headers.get("Cache-Control");
-  return parseCacheControl(cacheControl);
-}
-
-/**
- * Whether this cache will store the response the current render produces, as
- * far as the render can tell: the middleware runs it (a MISS or a stale
- * refresh) and the response stub already opts in. payloadInitialTheme
- * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
- * Cache-Control written after next() is not on the stub yet; for that render
- * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
- */
-export function documentCacheStoresRender(
-  reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">,
-): boolean {
-  return (
-    reqCtx._documentCacheRender === true &&
-    shouldCacheResponse(reqCtx.res) !== null
-  );
-}
-
 /**
  * Throw the first error the drained render reported through Flight or Fizz
  * onError. A component that throws after the 200 committed does not fail the
@@ -337,6 +238,14 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // Skip fill requests (prefetch: false): a fill is the second half of one
+    // adoption, rendered against what that client holds. Never served from a
+    // stored body and never stored. Asked of the raw URL like the two skips
+    // above: the request context is not read yet.
+    if (rawUrl.searchParams.has(FILL_PARAM)) {
+      return next();
+    }
+
     // Skip configured paths
     if (skipPaths.some((path) => url.pathname.startsWith(path))) {
       return next();
@@ -492,6 +401,9 @@ export function createDocumentCacheMiddleware<TEnv = any>(
               ),
             );
           } catch (error) {
+            // The route now rewrites (route middleware): nothing to refresh
+            // this entry with.
+            if (isRewrite(error)) return;
             // Pass requestCtx explicitly: this runs in a detached waitUntil task
             // where the ALS context is gone, so onError only fires if we hand it
             // the captured context (reportCacheError falls back to _getRequestContext
@@ -579,6 +491,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       noteWarmDocument(requestCtx, "not-cacheable");
       return originalResponse;
     } catch (error) {
+      // A rewrite() thrown downstream re-dispatches the request.
+      if (isRewrite(error)) throw error;
       reportCacheError(error, "cache-read", "[DocumentCache] middleware");
       if (handlerCalled) {
         // Post-handler failure (e.g. body.tee()): do not call next() again

package/src/client-urls/client-urls.ts

@@ -3,9 +3,9 @@ import { validateUserRouteName } from "../route-name.js";
 import { buildRouteTrie } from "../router/route-trie-builder.js";
 import { tryTrieMatch } from "../router/trie-matching.js";
 import type { LoaderDefinition } from "../types.js";
+import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
 import type {
   ClientPathOptions,
-  ClientRevalidateFn,
   ClientTransitionConfig,
   ClientUrlBuilder,
   ClientUrlHelpers,
@@ -137,13 +137,14 @@ interface TransitionItem extends ItemBase {
 interface LoaderItem extends ItemBase {
   readonly type: "loader";
   readonly definition: LoaderDefinition<any, any>;
-  readonly revalidate: readonly ClientRevalidateFn[];
+  readonly revalidate: ClientUrlLoaderRecord["revalidate"];
   readonly ssr?: false;
+  readonly prefetch?: false;
 }
 
 interface RevalidateItem extends ItemBase {
   readonly type: "revalidate";
-  readonly fn: ClientRevalidateFn;
+  readonly fn: ClientUrlLoaderRecord["revalidate"][number];
 }
 
 interface LoadingItem extends ItemBase {
@@ -386,11 +387,22 @@ function createHelpers(): ClientUrlHelpers {
         "clientUrls() loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
       );
     }
+    // Inline, not errors.ts assertBooleanOption: this module is in the
+    // client router chunk, where the helper costs 20 B gzip.
     if (options?.ssr !== undefined && typeof options.ssr !== "boolean") {
       throw new Error(
         `clientUrls() loader() ssr must be a boolean (got ${JSON.stringify(options.ssr)}). Omit it (or pass true) to stream on every render.`,
       );
     }
+    if (
+      process.env.NODE_ENV !== "production" &&
+      options?.prefetch !== undefined &&
+      typeof options.prefetch !== "boolean"
+    ) {
+      throw new Error(
+        `clientUrls() loader() prefetch must be a boolean (got ${JSON.stringify(options.prefetch)}). Omit it (or pass true) to run the loader in prefetches.`,
+      );
+    }
     const items = use ? runUse(use, "loader use") : [];
     rejectItems(items, new Set(["revalidate"]), "loader");
     return toPublicItem({
@@ -404,11 +416,14 @@ function createHelpers(): ClientUrlHelpers {
         )
         .map((item) => item.fn),
       ...(options?.ssr === false ? { ssr: false as const } : {}),
+      ...(options?.prefetch === false ? { prefetch: false as const } : {}),
     });
   };
 
   const revalidate: ClientUrlHelpers["revalidate"] = (fn) => {
-    if (typeof fn !== "function") {
+    // The build leaves a marker in place of the predicate it moved to the
+    // server (vite/plugins/client-urls-revalidate-hoist.ts).
+    if (typeof fn !== "function" && !isHoistedRevalidateRef(fn)) {
       throw new Error("clientUrls() revalidate() expects a predicate function");
     }
     return toPublicItem({
@@ -563,6 +578,7 @@ function applyConfig(
           loader: item.definition,
           revalidate: Object.freeze([...item.revalidate]),
           ...(item.ssr === false ? { ssr: false as const } : {}),
+          ...(item.prefetch === false ? { prefetch: false as const } : {}),
         }),
       );
     } else if (item.type === "loading") {
@@ -675,6 +691,8 @@ function collectIntercepts(
       let loading: ReactNode | undefined;
       for (const useItem of item.use) {
         if (useItem.type === "loader") {
+          // `prefetch` is not carried: an intercept prefetch defers nothing,
+          // so the flag is accepted and ignored, as on a urls() intercept().
           loaders.push(
             Object.freeze({
               loader: useItem.definition,
@@ -762,8 +780,6 @@ export function clientUrls<const TItems extends ClientUrlItems>(
 }
 
 export type {
-  ClientRevalidateArgs,
-  ClientRevalidateFn,
   ClientTransitionConfig,
   ClientUrlBuilder,
   ClientUrlHelpers,

package/src/client-urls/hoisted-revalidate.ts

@@ -0,0 +1,25 @@
+/**
+ * The value the build leaves in place of a clientUrls() `revalidate()`
+ * predicate in the browser and SSR copies of a "use client" module
+ * (vite/plugins/client-urls-revalidate-hoist.ts): the predicate itself moves
+ * to a server module, registered under the same content key
+ * (revalidate-registry.ts). The projection carries the key; the materialized
+ * loader stub calls the registered predicate.
+ */
+
+export const HOISTED_REVALIDATE_KEY = "$$rangoRevalidate";
+
+export interface HoistedRevalidateRef {
+  readonly $$rangoRevalidate: string;
+}
+
+export function isHoistedRevalidateRef(
+  value: unknown,
+): value is HoistedRevalidateRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Partial<HoistedRevalidateRef>)[HOISTED_REVALIDATE_KEY] ===
+      "string"
+  );
+}

package/src/client-urls/navigation.ts

@@ -1,12 +1,6 @@
 "use client";
 
 import { startTransition } from "react";
-import { makeIsAction } from "../router/is-action.js";
-import {
-  lockedClientDefault,
-  runClientRevalidateChain,
-} from "./revalidate-chain.js";
-import { encodeClientRevalidationDecisions } from "./revalidation-protocol.js";
 import type { ClientUrlPatterns } from "./types.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 
@@ -210,96 +204,6 @@ export function beginClientUrlNavigation(
   };
 }
 
-/**
- * Run the held clientUrls route's per-loader revalidate() predicates and
- * encode their decisions for the request header. Predicates are CLIENT code
- * (declared in the "use client" definition module); only decisions cross the
- * wire — the synthesized per-loader revalidate() on every materialized stub
- * (server-projection.ts) reads them back by loader $$id.
- *
- * Decisions exist only for the loaders the client currently HOLDS: the local
- * match of currentUrl. They matter when the server would re-evaluate those
- * held loader segments — same-route param/search navs, actions, and stale
- * restores. Cross-route targets render new segments unconditionally, so a
- * decision would be ignored; we still compute against the current route since
- * only its held segments are addressable.
- *
- * Returns null when no group is active, the current location is not a client
- * route, or no predicate produced a decision that differs from the locked
- * default — the server then applies defaults, which is also the behavior for
- * requests that cannot carry decisions (no-JS, PE, prefetch, document loads).
- */
-export function collectClientRevalidationDecisions(options: {
-  currentUrl: URL;
-  nextUrl: URL;
-  /**
-   * True only when the decisions ride the action POST itself — the one
-   * request the server evaluates with actionContext (locked default true).
-   * Action-triggered refetch GETs (partial-update terminals) pass false:
-   * the server gives those navigation defaults, and the delta gate below
-   * must diff against the default the SERVER will use, or a force decision
-   * on the refetch would be silently swallowed as "equals default".
-   */
-  actionRequest: boolean;
-  /** Action TRUTH for the predicates' isAction() matcher; may be true on
-   * refetch GETs where actionRequest is false. */
-  isAction: boolean;
-  actionId?: string;
-  stale: boolean;
-}): string | null {
-  const group = activeGroup;
-  if (!group) return null;
-
-  const { currentUrl, nextUrl, actionRequest, isAction, actionId, stale } =
-    options;
-  const currentLocal = stripMountPrefix(currentUrl.pathname, group.mount);
-  if (currentLocal === null) return null;
-  const currentMatch = group.definition.match(currentLocal);
-  if (!currentMatch || currentMatch.redirectTo) return null;
-  const record = group.definition.routes.find(
-    (candidate) => candidate.id === currentMatch.routeKey,
-  );
-  if (!record) return null;
-
-  const nextLocal = stripMountPrefix(nextUrl.pathname, group.mount);
-  const nextMatch =
-    nextLocal === null ? null : group.definition.match(nextLocal);
-  const nextParams = nextMatch?.params ?? {};
-
-  const defaultShouldRevalidate = lockedClientDefault({
-    actionRequest,
-    currentParams: currentMatch.params,
-    nextParams,
-    currentUrl,
-    nextUrl,
-  });
-
-  const baseArgs = {
-    currentUrl,
-    nextUrl,
-    currentParams: currentMatch.params,
-    nextParams,
-    stale,
-    isAction: makeIsAction(actionId, isAction),
-    ...(actionId !== undefined ? { actionId } : {}),
-  };
-  const skip: string[] = [];
-  const force: string[] = [];
-  for (const { loader, revalidate } of record.loaders) {
-    if (revalidate.length === 0) continue;
-    const decision = runClientRevalidateChain(
-      revalidate,
-      baseArgs,
-      defaultShouldRevalidate,
-      `loader "${loader.$$id}"`,
-    );
-    if (decision === defaultShouldRevalidate) continue;
-    (decision ? force : skip).push(loader.$$id);
-  }
-
-  return encodeClientRevalidationDecisions({ skip, force });
-}
-
 export function clearClientUrlNavigationRegistry(): void {
   activeGroup = null;
   activeInterceptTargets = new Set();

package/src/client-urls/revalidate-registry.ts

@@ -0,0 +1,30 @@
+import type { ShouldRevalidateFn } from "../types.js";
+
+/**
+ * Hoisted clientUrls() `revalidate()` predicates by content key. The
+ * generated `<file>?rango-revalidate` module of a group fills it when the
+ * group's module loads in the RSC realm
+ * (vite/plugins/client-urls-revalidate-hoist.ts); materialized loader stubs
+ * read it (server-projection.ts). A key hashes the file and the predicate's
+ * syntax, so a re-registration under one key is the same predicate.
+ *
+ * Server-only build output, not router state: no router hook reads it
+ * (AGENTS.md Hard rule 8).
+ */
+const revalidators = new Map<string, ShouldRevalidateFn<any, any>>();
+
+export function registerClientUrlRevalidators(
+  fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>,
+): void {
+  for (const [key, fn] of Object.entries(fns)) revalidators.set(key, fn);
+}
+
+export function getClientUrlRevalidator(
+  key: string,
+): ShouldRevalidateFn<any, any> | undefined {
+  return revalidators.get(key);
+}
+
+export function clearClientUrlRevalidators(): void {
+  revalidators.clear();
+}