@rangojs/router 0.18.0 → 0.19.1

package/src/cache/document-cache.ts

@@ -13,6 +13,7 @@
  * 4. If miss → run handler, cache if response has cache headers
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
@@ -24,6 +25,7 @@ import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
+import { executionStart, predatesInvalidation } from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -109,7 +111,10 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
 /**
  * Check if response should be cached based on Cache-Control headers
  */
-function shouldCacheResponse(response: Response): CacheDirectives | null {
+function shouldCacheResponse(
+  response: Response,
+  requestCtx?: Pick<RequestContext, "_payloadVisitorTheme">,
+): CacheDirectives | null {
   // Only cache successful responses
   if (response.status !== 200) {
     return null;
@@ -125,10 +130,34 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     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
@@ -279,7 +308,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     // are not visible on ctx.url in production.
     const rawUrl = new URL(ctx.request.url);
     const isFragmentRecovery =
-      ctx.request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
+      requestHeaders(ctx.request).get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
 
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
@@ -318,6 +347,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // The write gate's start (#977): the request's, not this middleware's. A
+    // middleware ahead of this one can read tagged data the document bakes,
+    // and a stale refresh re-runs the handler over what they set.
+    const start = requestCtx._requestStart ?? executionStart();
+
     // Determine request type for cache key differentiation.
     // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
     // detection. Full-document RSC fetches must not share the HTML cache slot.
@@ -343,7 +377,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // match-time capability gate.
       const fragmentSuffix =
         isPartial &&
-        (ctx.request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1" ||
+        (requestHeaders(ctx.request).get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) ===
+          "1" ||
           isFragmentRecovery)
           ? ":fragments"
           : "";
@@ -374,6 +409,9 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       const cached = isFragmentRecovery
         ? null
         : await store.getResponse(cacheKey);
+      // Every path past the lookup either returns a fresh HIT, which renders
+      // nothing, or renders a response this cache may store.
+      requestCtx._documentCacheRender = true;
 
       if (cached && cached.response.status === 200) {
         if (!cached.shouldRevalidate) {
@@ -409,7 +447,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                 PHASES.background("document-revalidation"),
                 async () => {
                   const fresh = await next();
-                  const directives = shouldCacheResponse(fresh);
+                  const directives = shouldCacheResponse(fresh, requestCtx);
 
                   if (!directives || !fresh.body) return;
 
@@ -418,12 +456,16 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   // (same render-complete barrier as the miss path).
                   const body = await new Response(fresh.body).arrayBuffer();
                   throwIfRenderErrored(requestCtx);
+                  // Not written when one of its tags was invalidated since
+                  // the render started (#977).
+                  const tags = collectRequestTags(requestCtx);
+                  if (await predatesInvalidation(store, tags, start)) return;
                   await store.putResponse!(
                     cacheKey,
                     new Response(body, fresh),
                     directives.sMaxAge!,
                     directives.staleWhileRevalidate,
-                    collectRequestTags(requestCtx),
+                    tags,
                   );
                   log(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
@@ -456,7 +498,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       const originalResponse = await next();
 
       // 3. Cache if response has appropriate headers
-      const directives = shouldCacheResponse(originalResponse);
+      const directives = shouldCacheResponse(originalResponse, requestCtx);
 
       if (directives) {
         log(
@@ -483,12 +525,16 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             // body and its tag set consistent.
             const body = await new Response(cacheStream).arrayBuffer();
             throwIfRenderErrored(requestCtx);
+            // Not written when one of its tags was invalidated since the
+            // render started (#977).
+            const tags = collectRequestTags(requestCtx);
+            if (await predatesInvalidation(store, tags, start)) return;
             await store.putResponse!(
               cacheKey,
               new Response(body, originalResponse),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
-              collectRequestTags(requestCtx),
+              tags,
             );
           } catch (error) {
             // Detached waitUntil task — pass the captured requestCtx so onError

package/src/cache/handle-snapshot.ts

@@ -134,6 +134,29 @@ export function captureHandleOwners(
   return owners;
 }
 
+/** How restoreHandles delivers a record's loader-owned values. */
+export interface OwnedPushDelivery {
+  /**
+   * Asked once per owner delivered through pushReplayed
+   * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
+   */
+  claim?: (loaderId: string) => boolean;
+  /**
+   * A PPR shell's record (capture, document HIT tail, navigation replay): the
+   * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
+   * the store (HandleStore.markLiveLane). A hole's values are replayed
+   * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
+   * place (HandleStore.redeliverReplays), and its run ending without a push
+   * drops them (HandleStore.settleLoaderRun).
+   */
+  liveLane?: ReadonlySet<string>;
+  /**
+   * A document HIT tail: every owner outside `liveLane` goes through
+   * pushRestored and stands, unclaimed.
+   */
+  restore?: boolean;
+}
+
 /**
  * Restore handle data from a cached snapshot into the handle store.
  * Used when serving cached segments to replay their handle data: a route
@@ -141,21 +164,32 @@ export function captureHandleOwners(
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
  * recorded order, an owned value through pushReplayed: if the owning loader
- * runs on the HIT (a live loader, or a promise-carrying `ssr: false` one;
- * a promise-free one is served from the shell and does not), its live pushes
- * replace the recorded ones in place instead of appending a second copy. `claim`
- * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
- * loader's own cache() HIT does not replay its pushes a second time
- * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A
- * record without owners restores as a plain replay.
+ * runs (a client navigation replaying a ppr route's cache() record runs its
+ * `ssr: false` loaders), its live pushes replace the recorded ones in place
+ * instead of appending a second copy. `owned.claim` is asked once per
+ * owner, so the loader's own cache() HIT does not replay its pushes a second
+ * time (loader-cache.ts replayLoaderHandles). A record without owners
+ * restores as a plain replay.
+ *
+ * `owned.restore`: a document HIT tail restoring the shell's doc record
+ * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
+ * through pushRestored and stand: a run of that loader on the HIT (a
+ * promise-carrying `ssr: false` loader, one whose record asks for a run)
+ * reads the store, and its settled pushes are dropped, not swapped in.
+ * Nothing is claimed, so the loader's own cache() HIT still replays the
+ * pushes the record could not keep (the thenable ones pushRestored lets
+ * through). A loader the route also runs on the live lane is a hole: its
+ * values keep pushReplayed, unclaimed, and its live run replaces them
+ * (#936), even inside a restored loader's body (`owned.liveLane`).
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
   owners?: HandleOwners,
-  claim?: (loaderId: string) => boolean,
+  owned?: OwnedPushDelivery,
 ): void {
   let delivers: Map<string, boolean> | undefined;
+  if (owned?.liveLane) handleStore.markLiveLane(owned.liveLane);
   for (const [segId, segHandles] of Object.entries(handles)) {
     if (Object.keys(segHandles).length === 0) continue;
     const segOwners = owners?.[segId];
@@ -174,10 +208,19 @@ export function restoreHandles(
           handleStore.push(handleName, segId, values[i]);
           continue;
         }
+        const hole = owned?.liveLane?.has(owner) === true;
+        if (owned?.restore && !hole) {
+          handleStore.pushRestored(handleName, segId, values[i], owner);
+          continue;
+        }
+        if (hole) {
+          handleStore.pushReplayed(handleName, segId, values[i], owner);
+          continue;
+        }
         delivers ??= new Map();
         let deliver = delivers.get(owner);
         if (deliver === undefined) {
-          deliver = claim ? claim(owner) : true;
+          deliver = owned?.claim ? owned.claim(owner) : true;
           delivers.set(owner, deliver);
         }
         if (deliver) {

package/src/cache/invalidation-order.ts

@@ -0,0 +1,84 @@
+/**
+ * The isolate's order of tag invalidations and cache execution starts
+ * (#973, #977): what the write gate in tag-invalidation.ts
+ * (predatesInvalidation) and the "use cache" join check read to tell whether
+ * an execution's value may predate an invalidation of one of its tags.
+ * Imports nothing, so request-context.ts can take each request's start here
+ * without a cycle through tag-invalidation.ts.
+ *
+ * - `seq` (#973): a counter, not Date.now(). Workers advance the clock only
+ *   on I/O, so an execution started right after an invalidation would share
+ *   its millisecond and read as older.
+ * - `tags` (#977): tag -> the `seq` of its latest invalidation, from every
+ *   request, oldest first. Bounded: dropping the oldest raises `forgotten`,
+ *   and an execution that started before a forgotten invalidation counts as
+ *   invalidated, whatever its tags (a miss, never a stale read).
+ *
+ * Keyed by tag name alone, not by router or store: two routers in one
+ * isolate that share a tag name skip each other's writes started before an
+ * invalidation. That costs a miss, never a stale read.
+ *
+ * On globalThis: a second evaluated copy of this module (a duplicated
+ * package, a dev re-evaluation) must read the invalidations the first one
+ * recorded, or its writers pass the gate.
+ */
+interface IsolateOrder {
+  seq: number;
+  tags: Map<string, number>;
+  forgotten: number;
+}
+const order: IsolateOrder = ((globalThis as any)[
+  Symbol.for("rangojs-router:tag-invalidation-order")
+] ??= { seq: 0, tags: new Map(), forgotten: 0 });
+const ISOLATE_INVALIDATION_HISTORY = 1024;
+
+/**
+ * Where a cache execution ("use cache", a loader's own cache(), a route
+ * cache() render, a request's document) started: its position in this
+ * isolate's order, and the store clock for invalidations this isolate did
+ * not see.
+ */
+export interface ExecutionStart {
+  readonly seq: number;
+  readonly at: number;
+}
+
+/** Record an execution's start, before it reads its data. */
+export function executionStart(): ExecutionStart {
+  return { seq: order.seq, at: Date.now() };
+}
+
+/**
+ * Whether this isolate invalidated any of `tags` after `since` (the `seq` of
+ * an ExecutionStart), in any request: the execution's value may predate the
+ * invalidation, so it is neither joined nor written (#973, #977).
+ */
+export function invalidatedSince(
+  tags: readonly string[] | undefined,
+  since: number,
+): boolean {
+  if (!tags || tags.length === 0) return false;
+  if (since < order.forgotten) return true;
+  for (const tag of tags) {
+    const at = order.tags.get(tag);
+    if (at !== undefined && at > since) return true;
+  }
+  return false;
+}
+
+/**
+ * Record an invalidation of `tags` in this isolate's order
+ * (updateTag()/revalidateTag(), before any store sees it).
+ */
+export function markInvalidated(tags: readonly string[]): void {
+  const at = ++order.seq;
+  for (const tag of tags) {
+    order.tags.delete(tag);
+    order.tags.set(tag, at);
+  }
+  for (const [tag, seq] of order.tags) {
+    if (order.tags.size <= ISOLATE_INVALIDATION_HISTORY) break;
+    order.tags.delete(tag);
+    order.forgotten = seq;
+  }
+}

package/src/cache/request-tag-mask.ts

@@ -0,0 +1,147 @@
+/**
+ * The per-request tag mask behind read-your-own-writes (#973).
+ *
+ * updateTag() and revalidateTag() call a store's invalidateTags() inside the
+ * request, and a built-in store masks the tags here before its first await:
+ * every later read in that request, through any context derived from it,
+ * treats an entry carrying one of the tags, written at or before the mask, as
+ * invalidated, without waiting for the durable write (the KV marker put, the
+ * tag purge, expireTag()) that revalidateTag() leaves to waitUntil. The mask
+ * only ever turns this request's hits into misses: if the durable write then
+ * fails, the request paid extra misses, never a stale read, and other
+ * requests read the durable state. CFCacheStore and VercelCacheStore share it.
+ */
+
+/** Request context -> store instance -> T, both levels weakly held. */
+export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
+
+/** The value for (ctx, store), created on first use. */
+export function perRequestStoreValue<T>(
+  map: PerRequestStoreMap<T>,
+  ctx: object,
+  store: object,
+  create: () => T,
+): T {
+  let byStore = map.get(ctx);
+  if (!byStore) {
+    byStore = new WeakMap();
+    map.set(ctx, byStore);
+  }
+  let value = byStore.get(store);
+  if (value === undefined) {
+    value = create();
+    byStore.set(store, value);
+  }
+  return value;
+}
+
+/**
+ * The request a context belongs to: RequestContext._requestRoot, which
+ * createRequestContext defines and a derived context (Object.create: a shell
+ * capture, a PPR HIT tail) inherits. A bare test context is its own root.
+ */
+export function requestRoot<T extends object>(
+  ctx: T & { _requestRoot?: T },
+): T {
+  return ctx._requestRoot ?? ctx;
+}
+
+/** Request root -> store -> tag -> the invalidatedAt its mask carries. */
+const requestMasks: PerRequestStoreMap<Map<string, number>> = new WeakMap();
+
+/** Mask `tags` at `at` through `store` for the rest of `ctx`'s request. */
+export function maskRequestTags(
+  ctx: object,
+  store: object,
+  tags: readonly string[],
+  at: number,
+): void {
+  const mask = perRequestStoreValue(
+    requestMasks,
+    requestRoot(ctx),
+    store,
+    () => new Map<string, number>(),
+  );
+  for (const tag of tags) mask.set(tag, at);
+}
+
+/**
+ * Whether `ctx`'s request masked one of `tags` through `store` at or after
+ * `taggedAt`. `>=`, as the stores' marker checks: an entry written in the
+ * invalidation's millisecond may hold a value computed before it, so it
+ * misses (a false miss, never a stale read).
+ */
+export function maskedForRequest(
+  ctx: object | undefined,
+  store: object,
+  tags: readonly string[] | undefined,
+  taggedAt: number,
+): boolean {
+  if (!ctx || !tags?.length) return false;
+  const mask = requestMasks.get(requestRoot(ctx))?.get(store);
+  if (!mask) return false;
+  for (const tag of tags) {
+    const at = mask.get(tag);
+    if (at !== undefined && at >= taggedAt) return true;
+  }
+  return false;
+}
+
+/**
+ * A marker read the write gate issued (#977) and has not settled: the
+ * store's answer for one tag and the millisecond it was issued in.
+ */
+interface GateRead {
+  issuedAt: number;
+  answer: Promise<unknown>;
+}
+
+/** Request root -> store -> tag -> the gate read in flight for it. */
+const gateReads: PerRequestStoreMap<Map<string, GateRead>> = new WeakMap();
+
+/**
+ * A marker read for a write gate (isTagsInvalidatedSince, from
+ * tag-invalidation.ts predatesInvalidation), shared by the gates of a
+ * request that ask while it is in flight. A page's writes (its "use cache"
+ * misses, its route record, its document) finish together and often carry
+ * the same tags, and each read its own marker before: one KV or
+ * runtime-cache read per tag per write.
+ *
+ * A read answers only for invalidations before it was issued. So a gate
+ * shares one still in flight, issued at or after its execution started
+ * (`sinceMs` is the millisecond after that start), and the read is dropped
+ * once it settles: a gate asking later reads again, and a shared read
+ * leaves open at most one marker round-trip. Reusing a settled read let a
+ * gate asking long after it miss another isolate's invalidation in
+ * between (a capture's putShell answered by a "use cache" write's read
+ * from the start of the capture), and kept a timed-out read's fail-open
+ * answer for the rest of the request. Without a request context `read()`
+ * runs unshared.
+ */
+export function gateMarkerRead<T>(
+  ctx: object | undefined,
+  store: object,
+  tag: string,
+  sinceMs: number,
+  read: () => Promise<T>,
+): Promise<T> {
+  if (!ctx) return read();
+  const reads = perRequestStoreValue(
+    gateReads,
+    requestRoot(ctx),
+    store,
+    () => new Map<string, GateRead>(),
+  );
+  const inFlight = reads.get(tag);
+  if (inFlight && inFlight.issuedAt >= sinceMs - 1) {
+    return inFlight.answer as Promise<T>;
+  }
+  const answer = read();
+  const entry: GateRead = { issuedAt: Date.now(), answer };
+  reads.set(tag, entry);
+  const settled = (): void => {
+    if (reads.get(tag) === entry) reads.delete(tag);
+  };
+  answer.then(settled, settled);
+  return answer;
+}