@rangojs/router 0.0.0-experimental.121 → 0.0.0-experimental.124

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

@@ -4,6 +4,8 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { enterActionFence, exitActionFence } from "./action-fence.js";
+import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -156,12 +158,40 @@ export function createServerActionBridge(
 
     // Start action in event controller - handles lifecycle tracking
     const handle = eventController.startAction(id, args);
+    // Whether the action's response carried the keepClientCache() directive.
+    // Set when the response arrives; gates the deferred invalidation below.
+    let keepCache = false;
+    // Single deferred invalidation + fence release, run exactly ONCE however the
+    // action terminates (normal, redirect, error, abort, intercept, concurrent).
+    // This replaces main's eager clear at action start: every directive-free
+    // action invalidates once; keepClientCache() suppresses only the automatic
+    // invalidation, so a concurrent directive-free action still invalidates via
+    // its own latch. Latched so the finally AND the early SPA-redirect returns
+    // (whose Flight stream never settles) can both call it safely.
+    let actionFinalized = false;
+    // skipInvalidation: the version-mismatch reload terminal released nothing
+    // server-side, so it releases the fence without invalidating.
+    const finalizeAction = (skipInvalidation = false): void => {
+      if (actionFinalized) return;
+      actionFinalized = true;
+      // finally so a throw in invalidation cannot leak the fence (latch is set).
+      try {
+        if (!keepCache && !skipInvalidation) {
+          store.markCacheAsStaleAndBroadcast();
+        }
+      } finally {
+        exitActionFence();
+      }
+    };
     try {
       const segmentState = store.getSegmentState();
 
-      // Mark cache as stale immediately when action starts
-      // This ensures SWR pattern kicks in if user navigates away during action
-      store.markCacheAsStaleAndBroadcast();
+      // Raise the action fence (replaces the old eager clear). Nothing is wiped,
+      // rotated, or broadcast yet: navigations during the flight fetch fresh
+      // (no-store) and popstate is treated as SWR, but the decision to
+      // invalidate is deferred to the response so a no-op action (keepClientCache)
+      // can leave the caches and the jar untouched.
+      enterActionFence();
 
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
@@ -237,11 +267,22 @@ export function createServerActionBridge(
         // abortAllActions() doesn't disrupt the in-progress Flight stream.
         handle.signal.removeEventListener("abort", onHandleAbort);
 
+        // Did the action call keepClientCache()? If so the deferred invalidation
+        // below is suppressed for THIS action (a concurrent directive-free
+        // action still invalidates via its own response).
+        keepCache = response.headers.get(KEEP_CACHE_HEADER) === "1";
+
         // Check for version mismatch - server wants us to reload
         const reloadResult = handleReloadHeader(response, {
           onBlocked: resolveStreamComplete,
-          onReload: (url) =>
-            log("version mismatch on action, reloading", { reloadUrl: url }),
+          onReload: (url) => {
+            log("version mismatch on action, reloading", { reloadUrl: url });
+            // Never-settling terminal (navigates away), so the finally never
+            // runs: release the fence here. skipInvalidation — the mismatch
+            // short-circuits the action server-side, so nothing mutated and a
+            // broadcast would only risk hard-reloading a sibling mid-task.
+            finalizeAction(true);
+          },
         });
         if (reloadResult) return reloadResult;
 
@@ -253,6 +294,10 @@ export function createServerActionBridge(
         if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
           log("action simple redirect", { url: redirect.url });
           handle.complete(undefined);
+          // This path returns a never-settling promise, so the finally never
+          // runs: invalidate + release the fence here (the mutation committed
+          // and we're navigating away). Latched, so the finally is a no-op.
+          finalizeAction();
           await dispatchRedirect(redirect.url);
           return new Promise<Response>(() => {});
         }
@@ -277,6 +322,9 @@ export function createServerActionBridge(
           log("action router id mismatch, reloading to re-sync");
           handle.complete(undefined);
           resolveStreamComplete();
+          // Never-settling return: release the fence before the reload (the
+          // reload resets module state anyway, but stay balanced). Latched.
+          finalizeAction();
           window.location.reload();
           return new Promise<Response>(() => {});
         }
@@ -542,8 +590,9 @@ export function createServerActionBridge(
           handle.clearConsolidation();
 
           if (scenario.historyKeyChanged) {
-            if (!scenario.onInterceptRoute) {
-              store.markCacheAsStaleAndBroadcast();
+            // Invalidation is deferred to finalizeAction(); here we only trigger
+            // the revalidation refetch of the new route (suppressed on keep).
+            if (!scenario.onInterceptRoute && !keepCache) {
               refetchRoute().catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
                 console.error(
@@ -555,11 +604,14 @@ export function createServerActionBridge(
             break;
           }
 
-          // Same history key but different pathname - safe to refetch current route
-          store.markCacheAsStaleAndBroadcast();
-          await refetchRoute({
-            interceptSourceUrl: store.getInterceptSourceUrl(),
-          });
+          // Same history key but different pathname - safe to refetch current
+          // route. Invalidation is deferred to finalizeAction(); here we only
+          // trigger the revalidation refetch (suppressed on keep).
+          if (!keepCache) {
+            await refetchRoute({
+              interceptSourceUrl: store.getInterceptSourceUrl(),
+            });
+          }
           break;
         }
 
@@ -567,8 +619,11 @@ export function createServerActionBridge(
           console.warn(
             `[Browser] Missing segments after action (HMR detected), refetching...`,
           );
+          // Repair (not revalidation), so ungated on keepCache: a keep action
+          // resolving last must discharge a directive-free sibling's repair.
+          // See the keep row in docs/design/rango-state-cookie.md (the all-keep
+          // edge, and the benign re-mark-stale-after-refetch end-state delta).
           await refetchRoute({ interceptSourceUrl });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -585,11 +640,11 @@ export function createServerActionBridge(
           // Clear consolidation tracking before fetch
           handle.clearConsolidation();
 
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
           await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
           });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -653,7 +708,9 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-          store.markCacheAsStaleAndBroadcast();
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
           break;
         }
       }
@@ -661,6 +718,11 @@ export function createServerActionBridge(
       handle.complete(returnData);
       return returnData;
     } finally {
+      // The single deferred invalidation + fence release for this action. Runs
+      // for every terminal that settles (normal, navigated-away, error, abort,
+      // intercept, concurrent); the SPA-redirect paths above already ran it.
+      // Latched, so it fires exactly once.
+      finalizeAction();
       handle[Symbol.dispose]();
     }
   }

package/src/browser/types.ts

@@ -71,6 +71,12 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: number;
+  /**
+   * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
+   * reads it verbatim and binds the rango state cookie to it; composition
+   * happens only server-side.
+   */
+  stateCookieName?: string;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -433,9 +439,9 @@ export interface NavigationStore {
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
+  markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
   setCrossTabRefreshCallback(callback: () => void): void;

package/src/cache/cache-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
+}
+
+export type CacheErrorCategory =
+  /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+  | "cache-read"
+  /** A write failed. Degrade to a no-op (entry simply not cached). */
+  | "cache-write"
+  /** A delete/eviction failed. Best-effort. */
+  | "cache-delete"
+  /**
+   * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+   * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+   * evicted so subsequent reads do not keep failing on it. Distinct from
+   * cache-read so consumers can tell corruption from a transient outage.
+   */
+  | "cache-corrupt"
+  /** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+  | "cache-invalidate"
+  /**
+   * A background stale-while-revalidate refresh failed (the `"use cache"`
+   * read-through path). The stale value was already served; the refresh that
+   * would have replaced it errored.
+   */
+  | "stale-revalidation";
+
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export function reportCacheError(
+  error: unknown,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): void {
+  console.error(`${label}:`, error);
+  try {
+    const target = ctx ?? _getRequestContext();
+    target?._reportBackgroundError?.(error, category);
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+}
+
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export async function reportingAsync(
+  task: () => Promise<unknown>,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): Promise<void> {
+  try {
+    await task();
+  } catch (error) {
+    reportCacheError(error, category, label, ctx);
+  }
+}

package/src/cache/cache-policy.ts

@@ -9,6 +9,7 @@
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
+import { normalizeTags } from "./cache-tag.js";
 
 /**
  * Default TTL for route-level cache() DSL and loader cache.
@@ -108,6 +109,64 @@ export async function resolveCacheKey(
   return defaultKey;
 }
 
+// ============================================================================
+// Cache Tag Resolution
+// ============================================================================
+
+/**
+ * Resolve cache tags from a tags option (static array or function of ctx).
+ *
+ * Fails open: a thrown tag callback falls back to no tags rather than
+ * aborting the request. Tags are additive metadata (not identity), so a
+ * missing tag does not cause cache collisions, only a missed invalidation.
+ *
+ * Shared by the cache() DSL (cache-scope) and loader caching (loader-cache)
+ * so tag resolution behaves identically across every cache axis.
+ */
+export function resolveTagsOption<TEnv>(
+  tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
+  ctx: RequestContext<TEnv> | undefined,
+  label: string,
+): string[] | undefined {
+  if (!tags) return undefined;
+  if (typeof tags === "function") {
+    if (!ctx) {
+      // A dynamic tags function needs the request context to run. Without it
+      // (e.g. resolved outside a request, at build/prerender time) the entry is
+      // cached UNTAGGED and can never be invalidated - surface that rather than
+      // silently dropping the tags, matching the thrown-callback branch below.
+      console.warn(
+        `[${label}] Dynamic tags function present but no request context; ` +
+          `caching without tags (this entry will not be tag-invalidatable).`,
+      );
+      return undefined;
+    }
+    try {
+      return normalizeTagList(tags(ctx));
+    } catch (error) {
+      console.error(
+        `[${label}] Tags function failed, caching without tags:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+  return normalizeTagList(tags);
+}
+
+/**
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
+ */
+function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = normalizeTags(tags);
+  return out.length > 0 ? out : undefined;
+}
+
 // ============================================================================
 // Cache Store Resolution
 // ============================================================================
@@ -120,6 +179,41 @@ export async function resolveCacheKey(
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
-  if (explicitStore) return explicitStore;
+  if (explicitStore) {
+    // Register explicit per-scope stores so updateTag()/revalidateTag() can
+    // reach them. This is the single chokepoint every cache axis (segment,
+    // response, loader) resolves through, so registering here covers them all
+    // eagerly - no dependence on whether a tagged write has happened yet. The
+    // app-level store is intentionally not registered (always reachable via
+    // ctx._cacheStore).
+    registerExplicitTaggedStore(explicitStore);
+    return explicitStore;
+  }
   return _getRequestContext()?._cacheStore ?? null;
 }
+
+/**
+ * Upper bound on the per-handler explicit-store registry. A module-singleton
+ * store (the recommended pattern) dedupes to a single entry and never approaches
+ * this. The cap bounds the niche case of an explicit store constructed PER
+ * request/boundary (e.g. a ctx-bound CFCacheStore, which must take a per-request
+ * ctx): without it the registry - which intentionally persists across requests so
+ * a server action's updateTag() can reach stores a prior render registered -
+ * would accumulate one dead instance per request and fan invalidation out to
+ * finished execution contexts. LRU-touch on re-resolution keeps a live, re-used
+ * store from being evicted by that churn.
+ */
+const EXPLICIT_STORE_REGISTRY_CAP = 64;
+
+function registerExplicitTaggedStore(store: SegmentCacheStore): void {
+  const set = _getRequestContext()?._explicitTaggedStores;
+  if (!set) return;
+  // LRU touch: move an already-present store to the most-recent position (Set
+  // preserves insertion order) so a store re-resolved every request stays live.
+  set.delete(store);
+  set.add(store);
+  if (set.size > EXPLICIT_STORE_REGISTRY_CAP) {
+    const oldest = set.values().next().value;
+    if (oldest !== undefined) set.delete(oldest);
+  }
+}

package/src/cache/cache-runtime.ts

@@ -40,6 +40,12 @@ import {
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import {
+  normalizeTags,
+  recordRequestTags,
+  runWithCacheTagScope,
+} from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -74,9 +80,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const store = requestCtx?._cacheStore;
     const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store or no getItem support
+    // Bypass: no store or no getItem support. Still run inside a tag scope so a
+    // 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.
     if (!store?.getItem) {
-      return fn.apply(this, args);
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      // Still record the runtime tags into the request set so a cacheTag() in an
+      // uncached function tags the document, even with no item-capable store.
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Resolve profile strictly from request-scoped config (set by the
@@ -159,8 +173,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         cacheKey = `use-cache:${id}`;
       }
     } catch {
-      // Non-serializable args: run uncached
-      return fn.apply(this, args);
+      // Non-serializable args: run uncached (within a tag scope so cacheTag()
+      // still does not throw). Record runtime tags so the document union still
+      // sees them even though this call is not itself cached.
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Cache lookup
@@ -178,9 +197,20 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             if (r) restoreHandles(r, handleStore);
           }
         }
+        // Surface the hit's tags to the request set so a document built from a
+        // cached item is still tagged (the function did not re-run, so its
+        // runtime cacheTag() tags are only available from the stored entry).
+        recordRequestTags(cached.tags, requestCtx);
         return result;
-      } catch {
-        // Deserialization failed, fall through to fresh execution
+      } catch (error) {
+        // The stored value is corrupt/partial (failed RSC deserialize). Report
+        // it, then fall through to fresh execution - the miss path below re-runs
+        // and setItem() overwrites the faulty entry under the same key (self-heal).
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" fresh-hit`,
+        );
       }
     }
 
@@ -195,6 +225,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             if (r) restoreHandles(r, handleStore);
           }
         }
+        // Tag the request with the stale entry's tags (see fresh-hit note).
+        recordRequestTags(cached.tags, requestCtx);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.
@@ -244,8 +276,18 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
 
           try {
-            const freshResult = await fn.apply(this, args);
+            const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+            const freshResult = await scoped.result;
             bgStopCapture?.();
+            // Merge profile/DSL tags with runtime cacheTag() tags, read after
+            // awaiting so post-await cacheTag() calls are included. Normalize
+            // (drops empty profile tags, matching the invalidate path) + dedupe.
+            const freshTags = [
+              ...new Set(
+                normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+              ),
+            ];
+            recordRequestTags(freshTags, requestCtx);
             const serialized = await serializeResult(freshResult);
             if (serialized !== null) {
               const encodedHandles = bgCapture?.data
@@ -255,12 +297,20 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                 handles: encodedHandles,
                 ttl: profile.ttl,
                 swr: profile.swr,
-                tags: profile.tags,
+                tags: freshTags.length > 0 ? freshTags : undefined,
               });
             }
           } catch (bgError) {
             bgStopCapture?.();
-            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
+            // Pass requestCtx explicitly: this runs in a detached background
+            // task where the ALS context is gone, so onError can only fire if
+            // we hand it the context captured up front.
+            reportCacheError(
+              bgError,
+              "stale-revalidation",
+              "[use cache] background revalidation failed",
+              requestCtx,
+            );
           } finally {
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
@@ -272,8 +322,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
         });
         return result;
-      } catch {
-        // Deserialization of stale value failed, fall through
+      } catch (error) {
+        // Stale value is corrupt/partial; report and fall through to a fresh
+        // execution, which overwrites the faulty entry under the same key.
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" stale-hit`,
+        );
       }
     }
 
@@ -306,8 +362,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     }
 
     let result: any;
+    let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      result = await fn.apply(this, args);
+      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      result = await scoped.result;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
@@ -320,6 +378,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       stopCapture?.();
     }
 
+    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
+    // after awaiting result so post-await cacheTag() calls are included.
+    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
+    const allTags = [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
+    ];
+    recordRequestTags(allTags, requestCtx);
+
     // Serialize and store — fully non-blocking when waitUntil is available.
     // The response does not need to wait for serialization or the store write.
     const cacheWrite = async () => {
@@ -333,7 +399,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             handles: encodedHandles,
             ttl: profile.ttl,
             swr: profile.swr,
-            tags: profile.tags,
+            tags: allTags.length > 0 ? allTags : undefined,
           });
         }
       } catch (writeError) {