@rangojs/router 0.16.0 → 0.18.0

package/src/cache/cache-exec-scope.ts

@@ -26,19 +26,52 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { _setCacheExecScopeProbe } from "./taint.js";
 
-const cacheExecStorage = new AsyncLocalStorage<true>();
+/**
+ * One "use cache" execution. Identity matters: the execution's handle capture
+ * (cache-runtime.ts) records only pushes from its own chain, including cached
+ * functions it calls (`parent` links them), not concurrent pushes into the
+ * same request store.
+ */
+export interface CacheExecScope {
+  readonly parent?: CacheExecScope;
+}
+
+const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();
 
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ * Pass `scope` (createCacheExecScope) to test membership with
+ * isInCacheExecChain.
  */
-export function runWithCacheExecScope<T>(fn: () => T): T {
-  return cacheExecStorage.run(true, fn);
+export function runWithCacheExecScope<T>(
+  fn: () => T,
+  scope: CacheExecScope = createCacheExecScope(),
+): T {
+  return cacheExecStorage.run(scope, fn);
+}
+
+/** A scope nested in the calling chain's current one, if any. */
+export function createCacheExecScope(): CacheExecScope {
+  return { parent: cacheExecStorage.getStore() };
 }
 
 /** True when the calling async chain is inside a "use cache" body. */
 export function isInsideCacheExecScope(): boolean {
-  return cacheExecStorage.getStore() === true;
+  return cacheExecStorage.getStore() !== undefined;
+}
+
+/** The calling chain's innermost "use cache" scope, if any. */
+export function getCacheExecScope(): CacheExecScope | undefined {
+  return cacheExecStorage.getStore();
+}
+
+/** True when the calling async chain runs inside `scope`, at any depth. */
+export function isInCacheExecChain(scope: CacheExecScope): boolean {
+  for (let s = cacheExecStorage.getStore(); s; s = s.parent) {
+    if (s === scope) return true;
+  }
+  return false;
 }
 
 // Wire the ambient ctx-method guards (assertNotInsideCacheExec in taint.ts)

package/src/cache/cache-key-utils.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 
 import { encodeKV } from "../encode-kv.js";
@@ -20,12 +20,7 @@ import type { SearchParamsFilter } from "./search-params-filter.js";
  * slot; an allowlist keeps the router's own params out of the key while leaving
  * consumer `__` params intact.
  */
-const RESERVED_SEARCH_PARAMS = new Set([
-  "__no_cache",
-  "__rsc",
-  "__html",
-  "__prerender_collect",
-]);
+const RESERVED_SEARCH_PARAMS = new Set(["__no_cache", "__rsc", "__html"]);
 
 function isReservedSearchParam(key: string): boolean {
   return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
@@ -100,3 +95,23 @@ export function cacheKeyBase(
   if (searchStr) key += `?${searchStr}`;
   return key;
 }
+
+/**
+ * The record key, or shell partition, of nested keyed cache() scopes (#970)
+ * from its parts, outermost first: the chain's `key()` results and, for an
+ * inner scope without its own `key()`, that scope's default key
+ * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
+ * scope keeps its key byte for byte. Two or more are joined by `|`, each
+ * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
+ * encoded part holds no `|`, so every tuple maps to its own key, of any
+ * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
+ * key holds no `:` either, so a single raw result with one (a prefixed
+ * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
+ * can. Shared with the testing helper `shellCacheKey`, which composes a
+ * nested partition the same way.
+ */
+export function composeCacheKeys(parts: readonly string[]): string {
+  return parts.length === 1
+    ? parts[0]
+    : parts.map((part) => encodeURIComponent(part)).join("|");
+}

package/src/cache/cache-policy.ts

@@ -83,6 +83,28 @@ export function resolveSwrWindow(
   return 0;
 }
 
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1_000;
+
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export function staleShellRecaptureDue(
+  entry: { readonly createdAt?: number },
+  now: number,
+): boolean {
+  return !(now - (entry.createdAt as number) < SHELL_MIN_RECAPTURE_INTERVAL_MS);
+}
+
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *