@rangojs/router 0.22.1 → 0.24.0

package/src/browser/types.ts

@@ -85,7 +85,11 @@ export interface RscMetadata {
    * positions and must complete at the handler barrier.
    */
   handlesLate?: AsyncGenerator<HandleData, void, unknown>;
-  /** Cached handle data (for back/forward navigation from cache) */
+  /**
+   * Handle data of the history-cache entry the update renders from (a
+   * back/forward restore, or a link to a cached page). It replaces the handle
+   * state, and `handles`, when present, merge onto it.
+   */
   cachedHandleData?: HandleData;
   /**
    * RSC version string from the server.
@@ -308,7 +312,12 @@ export interface HistoryEntryMemory {
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
-  /** Scroll behavior to apply after React commits this update */
+  /**
+   * The scroll decision of the navigation transaction this update commits,
+   * applied after React commits it. Absent on every update that is not a
+   * navigation's (server action, error, `prefetch: false` fill): such an
+   * update says nothing about scroll, and leaves a pending decision alone.
+   */
   scroll?: {
     /** For back/forward: restore saved position */
     restore?: boolean;
@@ -637,6 +646,12 @@ export interface NavigationStore {
     stale?: boolean,
     handlesPending?: boolean,
   ): void;
+  /**
+   * The history keys whose entries show the page `historyKey`'s entry shows:
+   * that entry and the copies a shallow navigation made of it, which share its
+   * segments array. `[historyKey]` when it has no entry.
+   */
+  getPageHistoryKeys(historyKey: string): string[];
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
@@ -671,13 +686,6 @@ export interface FetchPartialOptions {
   signal?: AbortSignal;
   /** If true, this is a stale cache revalidation request - server should force revalidators */
   staleRevalidation?: boolean;
-  /**
-   * Encoded client-run per-loader revalidation decisions
-   * (clientUrls revalidate() predicates executed in the browser); sent as
-   * X-Rango-Client-Reval and honored only by materialized client-urls loader
-   * stubs. Null/absent = locked server defaults.
-   */
-  clientRevalidation?: string | null;
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
@@ -685,6 +693,12 @@ export interface FetchPartialOptions {
   routerId?: string;
   /** If true, this is an HMR refetch - server should invalidate manifest cache */
   hmr?: boolean;
+  /**
+   * The fill request of an adopted prefetch that carried deferred segments
+   * (`prefetch: false`): marked `_rsc_fill`, never answered from or written
+   * to a prefetch cache or the HTTP cache, and it cancels no prefetch.
+   */
+  fill?: boolean;
 }
 
 /**
@@ -785,7 +799,7 @@ export type { ResolvedSegment };
 
 /**
  * Token for tracking an active stream.
- * Call end() when the stream completes.
+ * Call end() when the stream completes. Only the first call counts.
  */
 export interface StreamingToken {
   end(): void;

package/src/browser/validate-redirect-origin.ts

@@ -54,3 +54,19 @@ export function validateExternalRedirect(
   }
   return resolved;
 }
+
+/**
+ * The target of a redirect a Flight payload carries (`metadata.redirect`), or
+ * null when the client refuses it. An explicit off-host one
+ * (`redirect(url, { external: true })`) is scheme-validated only:
+ * `external` waives the same-origin check the app opted out of, not scheme
+ * safety. Every other one must stay on this origin.
+ */
+export function validatePayloadRedirect(redirect: {
+  url: string;
+  external?: boolean;
+}): string | null {
+  return redirect.external
+    ? validateExternalRedirect(redirect.url, window.location.origin)
+    : validateRedirectOrigin(redirect.url, window.location.origin);
+}

package/src/build/generate-route-types.ts

@@ -13,6 +13,7 @@ export {
   type ScanFilter,
   createScanFilter,
   findTsFiles,
+  isInSkippedScanDir,
 } from "./route-types/scan-filter.js";
 export {
   writePerModuleRouteTypes,

package/src/build/route-types/router-processing.ts

@@ -14,7 +14,7 @@ import {
 } from "node:path";
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
-import type { ScanFilter } from "./scan-filter.js";
+import { isUniversallySkippedScanDir, type ScanFilter } from "./scan-filter.js";
 import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
@@ -58,12 +58,9 @@ function isRoutableSourceFile(name: string): boolean {
 
 function isExcludedScanDir(name: string): boolean {
   return (
-    name === "node_modules" ||
-    name === "dist" ||
-    name === "coverage" ||
+    isUniversallySkippedScanDir(name) ||
     name === "__tests__" ||
-    name === "__mocks__" ||
-    name.startsWith(".")
+    name === "__mocks__"
   );
 }
 

package/src/build/route-types/scan-filter.ts

@@ -1,4 +1,4 @@
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import { readdirSync } from "node:fs";
 // @ts-ignore -- picomatch ships no .d.ts; types are trivial
 import picomatch from "picomatch";
@@ -44,8 +44,49 @@ export function createScanFilter(
 }
 
 /**
- * Recursively find .ts/.tsx files under a directory, skipping node_modules
- * and .gen. files.
+ * Directory names no discovery scan enters: findTsFiles() and the router scans
+ * (findRouterFiles/findHostRouterFiles, router-processing.ts) all build their
+ * skip rule on this, so a file below one is never discovered. Dot-directories
+ * cover a nested git worktree, a tool cache, or a test's working copy of
+ * another app.
+ */
+export function isUniversallySkippedScanDir(name: string): boolean {
+  return (
+    name === "node_modules" ||
+    name === "dist" ||
+    name === "coverage" ||
+    name.startsWith(".")
+  );
+}
+
+/**
+ * Whether a file under `root` sits in a directory every discovery scan skips
+ * (isUniversallySkippedScanDir). The dev route-file watcher uses it to ignore
+ * files discovery would never find. A path outside `root` is false.
+ */
+export function isInSkippedScanDir(
+  root: string,
+  absolutePath: string,
+): boolean {
+  const rel = relative(root, absolutePath);
+  if (isAbsolute(rel)) return false;
+  const dirs = rel.split(/[\\/]/).slice(0, -1);
+  if (dirs[0] === "..") return false;
+  return dirs.some(isUniversallySkippedScanDir);
+}
+
+/**
+ * Directory names the source-file scans skip: findTsFiles() and the build
+ * loader pre-scan (expose-internal-ids.ts). The isUniversallySkippedScanDir()
+ * set plus `build`, which the router scans still enter.
+ */
+export function isSkippedSourceScanDir(name: string): boolean {
+  return isUniversallySkippedScanDir(name) || name === "build";
+}
+
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping the directories
+ * isSkippedSourceScanDir() names and .gen. files.
  */
 export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   const results: string[] = [];
@@ -61,14 +102,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (
-        entry.name === "node_modules" ||
-        entry.name.startsWith(".") ||
-        entry.name === "dist" ||
-        entry.name === "build" ||
-        entry.name === "coverage"
-      )
-        continue;
+      if (isSkippedSourceScanDir(entry.name)) continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||

package/src/cache/cf/cf-cache-store.ts

@@ -15,6 +15,9 @@ declare global {
  * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
  *
  * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
+ *             With `kvFallThrough`, an L1 copy a tag marker rejects reads as
+ *             an L1 miss: L2 is checked against the same markers (see get(),
+ *             "Tag invalidation"). Off by default: the rejected copy is a miss.
  * Write flow: L1 write + L2 write (both via waitUntil)
  *
  * Features:
@@ -388,7 +391,7 @@ type OpenedShellFrame =
   | { status: "corrupt"; error: Error; head?: undefined }
   | { status: "expired"; head: ShellFrameHead }
   | { status: "timeout"; head?: undefined }
-  | { status: "invalidated"; head?: undefined };
+  | { status: "invalidated"; head: ShellFrameHead };
 
 /** The `[CFCacheStore][shell]` trace's timings, from a read's stats. */
 function debugTimings(
@@ -531,6 +534,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
   private readonly tagCacheTtl: number;
+  private readonly kvFallThrough: boolean;
 
   constructor(options: CFCacheStoreOptions<TEnv>) {
     if (!options.ctx) {
@@ -605,6 +609,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
+    this.kvFallThrough = options.kvFallThrough === true && !!options.kv;
     // Without KV, isTagsInvalidatedSince has no durable history — it answers
     // from the per-request mask at best. Runtime shells tolerate that (purge
     // eviction + ttl/swr bound the staleness), but an immutable TAGGED
@@ -1210,16 +1215,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetSegment(key, { suppressRevalidate: true });
       }
 
-      // Tag invalidation: an entry whose tags were invalidated after it was
-      // cached is treated as a miss, so the next render re-populates it. We
-      // return null (re-render locally) rather than falling through to KV. In
-      // the common case the L1 entry and its KV twin were written together with
-      // the same taggedAt, so kvGetSegment's own tag check would miss too and a
-      // fall-through is pure cost. The tiers CAN diverge -- another colo may have
-      // already re-rendered and written a fresher KV envelope -- in which case a
-      // fall-through could serve that copy instead of re-rendering here.
-      // Capturing that cross-colo optimization is a deferred follow-up, not a
-      // correctness gap: this colo's next read after its own re-render self-heals.
+      // Tag invalidation: a copy whose tags were invalidated after it was
+      // cached is never served. Without `kvFallThrough` it is a miss and this
+      // colo re-renders. With it, it reads as an L1 miss, because the tiers can
+      // diverge: another colo may have written KV after the marker (its own
+      // re-render, or a router.prerender() warm after updateTag()), and this
+      // colo then serves that entry instead of rendering it again.
+      // kvGetSegment checks the KV entry against the same markers (this
+      // request's memo: no second marker read) and promotes a valid one over
+      // this copy. When KV still holds the twin written with this copy, the
+      // read costs one KV get and misses as before. The request that
+      // invalidated the tag itself keeps the plain miss (declinesKvFallThrough).
       const tagInfo = this.readTagInfo(response.headers);
       // Measure the marker-resolution tail (memo -> L1 marker cache -> KV) only
       // when debug is on, so the hot path pays nothing. It is the serial read
@@ -1241,7 +1247,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             matchMs,
             markerMs,
           });
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetSegment(key);
       }
 
       // Read status headers
@@ -1524,7 +1532,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetResponse(key);
       }
 
-      // Tag invalidation check (treat invalidated entry as a miss).
+      // Tag invalidation check: a rejected copy reads as an L1 miss (see get()).
       const tagInfo = this.readTagInfo(response.headers);
       if (
         await this.isL1Invalidated(
@@ -1533,7 +1541,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           response.headers,
         )
       ) {
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetResponse(key);
       }
 
       // Check staleness
@@ -1801,8 +1811,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         return this.kvGetItem(key, { suppressRevalidate: true });
       }
 
-      // Tag invalidation check (treat invalidated entry as a miss). Measure the
-      // marker-resolution tail only under debug (see get()).
+      // Tag invalidation check: a rejected copy reads as an L1 miss (see
+      // get()). Measure the marker-resolution tail only under debug.
       const tagInfo = this.readTagInfo(response.headers);
       const markerStart = this.debug ? Date.now() : 0;
       const invalidated = await this.isL1Invalidated(
@@ -1821,7 +1831,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             matchMs,
             markerMs,
           });
-        return null;
+        return this.declinesKvFallThrough(tagInfo.tags, tagInfo.taggedAt)
+          ? null
+          : this.kvGetItem(key);
       }
 
       const staleAt = Number(
@@ -2233,7 +2245,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           tier: "l1",
           stats,
         });
-        return null;
+        // As get(): KV may hold a capture from after the marker.
+        return this.declinesKvFallThrough(opened.head.t, opened.head.ta)
+          ? null
+          : kvFallback("invalidated");
       }
       const read = this.shellDocumentRead(
         key,
@@ -2325,7 +2340,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * dropped and read from the store (SWR recapture scheduling and each mode's
    * invalidation semantics stay with the store read). That read keeps the
    * caller's `tagHints`: cfTagHints may have evicted the key while the memo
-   * still holds it.
+   * still holds it. A shell a tag marker rejects is dropped and read from
+   * the store too, which may hold a capture from after the marker (see
+   * get(), "Tag invalidation"), unless the request's own mask rejected it
+   * (declinesKvFallThrough).
    */
   private async readMemoizedShell(
     key: string,
@@ -2360,7 +2378,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         tier: "memo",
         stats,
       });
-      return null;
+      return this.declinesKvFallThrough(head.t, head.ta)
+        ? null
+        : this.readShellDocumentWithin(key, options, snapshotBudget);
     }
     if (stats) stats.memo = { hit: true, bytes: cfShellMemo.size };
     this.recordShellHit(key, head.t, stats);
@@ -2472,7 +2492,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
     if (invalidated) {
       reader.cancel();
-      return { status: "invalidated" };
+      return { status: "invalidated", head: value.head };
     }
     return value;
   }
@@ -3341,6 +3361,24 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return false;
   }
 
+  /**
+   * Whether a rejected L1 copy skips the KV read: always unless the
+   * `kvFallThrough` option is on, and with it on when this request's own
+   * updateTag()/revalidateTag() (its mask, request-tag-mask.ts) rejects an
+   * entry tagged at `taggedAt`. KV holds a newer entry only if something
+   * rendered after this request's invalidation, while the request re-renders
+   * every entry it masked, so the read would add one KV get per masked entry
+   * to that re-render.
+   * @internal
+   */
+  private declinesKvFallThrough(
+    tags: string[] | undefined,
+    taggedAt: number | undefined,
+  ): boolean {
+    if (!this.kvFallThrough) return true;
+    return maskedForRequest(_getRequestContext(), this, tags, taggedAt ?? 0);
+  }
+
   /**
    * Synthetic Cache API request for a tag's L1-cached invalidation marker.
    * Unversioned for the same reason as tagMarkerKey; the cache namespace

package/src/cache/cf/cf-cache-types.ts

@@ -66,8 +66,11 @@ export interface CFCacheReadDebugEvent {
    * - kv-timeout: the L2/KV read budget fired (read abandoned, NOT a genuine
    *   absence -- distinct from kv-miss so a degradation signal is separable)
    * - tag-invalidated: a live L1/KV entry whose cache tags were invalidated
-   *   after it was written -- treated as a miss so the next render re-populates
-   *   it (the tag-invalidation read path, distinct from a plain miss)
+   *   after it was written -- never served (the tag-invalidation read path,
+   *   distinct from a plain miss). With `kvFallThrough` on, an L1 copy then
+   *   reads L2/KV, so a kv-* event follows unless the request invalidated the
+   *   tag itself; from L2/KV it is a miss and the next render re-populates
+   *   the entry
    * - error: the read threw
    */
   outcome:
@@ -383,6 +386,25 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   kvReadTimeoutMs?: number;
 
+  /**
+   * After `updateTag()`/`revalidateTag()`, a location whose own L1 copy a tag
+   * marker rejects reads KV next, and serves the entry another location (or a
+   * `router.prerender()` warm) wrote after the invalidation, instead of
+   * rendering again. Covers `cache()` records, `"use cache"` results, cached
+   * responses and `ppr` shells. The request that invalidated the tag still
+   * re-renders its own entries without the read.
+   *
+   * Cost: one KV get per rejected copy per location after each invalidation
+   * (150 ms added wait, measured in #1069 locally at 50 ms per KV read on a
+   * document with a shell, a record and one `"use cache"` result, every copy
+   * rejected; not measured on a deployed worker), paid even when KV holds only
+   * the old twin. Worth it where re-rendering costs more than a KV read
+   * (several locations, expensive renders). Needs `kv`; ignored without it.
+   *
+   * Defaults to false: a rejected L1 copy is a miss and the location renders.
+   */
+  kvFallThrough?: boolean;
+
   /**
    * Per-isolate memos ({@link StoreMemoOptions}), one set per isolate and
    * shared by every CFCacheStore in it. `shellMs` (default 2000) and

package/src/cache/document-cache-policy.ts

@@ -0,0 +1,131 @@
+/**
+ * Document cache storage policy: which responses the document cache stores.
+ * A leaf (types and the per-client signal only), so request-scoped code can
+ * ask whether a render will be stored (documentCacheStoresRender) without
+ * importing the cache middleware.
+ */
+
+import { hasPerClientSignal } from "../browser/cookie-name.js";
+import type { RequestContext } from "../server/request-context.js";
+
+export 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
+ */
+export function shouldCacheResponse(
+  response: Response,
+  requestCtx?: Pick<
+    RequestContext,
+    "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation"
+  >,
+): 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;
+  }
+
+  // A rewritten request's render shows the visitor's URL (renderedLocation,
+  // full-payload.ts); this entry is keyed by the rewrite target.
+  if (requestCtx?._payloadVisitorLocation) {
+    return null;
+  }
+
+  // prefetch: false. The payload carries deferred units: it answers one
+  // page's prefetch and nothing else. parseCacheControl refuses the
+  // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a
+  // middleware can replace that after next(), and a navigation answered
+  // with this body would show a fallback no fill ever replaces.
+  if (requestCtx?._payloadDeferred) {
+    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
+  );
+}