@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.142

package/src/cache/cache-runtime.ts

@@ -127,6 +127,86 @@ export async function replyToCacheKey(
 // the test-ergonomics warning fires once per fn rather than once per call.
 const warnedUncachedUnderTest = new Set<string>();
 
+/**
+ * Fast-path cache-key builder for JSON-safe key args. Returns a deterministic
+ * string (object keys recursively sorted so insertion order can't change the
+ * key) when EVERY part is a primitive or a plain object/array of the same, and
+ * `undefined` otherwise so the caller falls back to the Flight reply encoder.
+ *
+ * Strings are always quoted via JSON.stringify, so they can never collide with
+ * the bareword encodings of null/true/false/undefined/numbers. Anything the
+ * reply encoder must handle instead — functions, symbols, bigint, non-finite
+ * numbers, Dates, Maps, class instances, promises, and React elements (whose
+ * `$$typeof` symbol value trips the symbol reject) — yields `undefined`.
+ */
+function jsonSafeKeyPart(value: unknown): string | undefined {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      return Number.isFinite(value) ? String(value) : undefined;
+    case "undefined":
+      return "undefined";
+    case "object": {
+      if (Array.isArray(value)) {
+        const parts: string[] = [];
+        for (const item of value) {
+          const encoded = jsonSafeKeyPart(item);
+          if (encoded === undefined) return undefined;
+          parts.push(encoded);
+        }
+        return `[${parts.join(",")}]`;
+      }
+      // Only plain objects (Object.prototype or null proto) are fast-path safe.
+      // Dates, Maps, class instances, promises, etc. carry a different prototype
+      // and fall back to the encoder.
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return undefined;
+      const obj = value as Record<string, unknown>;
+      const parts: string[] = [];
+      for (const key of Object.keys(obj).sort()) {
+        const encoded = jsonSafeKeyPart(obj[key]);
+        if (encoded === undefined) return undefined;
+        parts.push(`${JSON.stringify(key)}:${encoded}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      // bigint, symbol, function
+      return undefined;
+  }
+}
+
+/**
+ * The serialized product of one "use cache" execution: exactly what the store
+ * write persists. Followers that dedup onto an in-flight execution (see
+ * inFlightExecutions) await this and serve it as a synthetic cache hit — each
+ * deserializing its OWN copy of `serialized` and replaying `handles`/`tags`
+ * against its OWN request. A deserialized result object is never shared.
+ */
+interface CacheEnvelope {
+  /** RSC-serialized return value (never null — a null serialize rejects). */
+  serialized: string;
+  /** Merged profile/DSL + runtime cacheTag() tags. */
+  tags: string[];
+  /** RSC-encoded handle blob captured during execution, if any. */
+  handles?: string;
+}
+
+/**
+ * In-flight "use cache" executions keyed by cache key. When N concurrent calls
+ * miss on the same key, only the first (the leader) runs the function; the rest
+ * await its {@link CacheEnvelope} and serve it as a synthetic hit rather than
+ * re-running the function and re-writing the store. Isolate-scoped (module
+ * singleton), and cleared for a key as soon as the leader settles: a rejected
+ * leader (function threw, or the result was not serializable) propagates to
+ * current waiters, which then retry fresh.
+ */
+const inFlightExecutions = new Map<string, Promise<CacheEnvelope>>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -253,12 +333,23 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     let cacheKey: string;
     try {
       if (keyArgs.length > 0) {
-        const tempRefs = createClientTemporaryReferenceSet();
-        const encoded = await encodeReply(keyArgs as unknown[], {
-          temporaryReferences: tempRefs,
-        });
-        const argsKey = await replyToCacheKey(encoded);
-        cacheKey = `use-cache:${id}:${argsKey}`;
+        // Fast path: when every key arg is JSON-safe, build the key with a
+        // deterministic stable-stringify and skip encodeReply (the Flight reply
+        // encoder runs on EVERY call, including hits). The `:j:` namespace keeps
+        // these keys disjoint from the encoder path so the two can never collide
+        // for one fn id. Entries cached under the old encoder key for JSON-safe
+        // args cold-start once after this upgrade.
+        const fastKey = jsonSafeKeyPart(keyArgs);
+        if (fastKey !== undefined) {
+          cacheKey = `use-cache:${id}:j:${fastKey}`;
+        } else {
+          const tempRefs = createClientTemporaryReferenceSet();
+          const encoded = await encodeReply(keyArgs as unknown[], {
+            temporaryReferences: tempRefs,
+          });
+          const argsKey = await replyToCacheKey(encoded);
+          cacheKey = `use-cache:${id}:${argsKey}`;
+        }
       } else {
         cacheKey = `use-cache:${id}`;
       }
@@ -438,7 +529,65 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       }
     }
 
-    // Cache miss: execute, serialize, store
+    // Cache miss.
+    //
+    // In-flight dedup: if a concurrent call for this key is already executing,
+    // await its envelope and serve it as a synthetic hit rather than re-running
+    // the function. Each follower deserializes its OWN copy, replays handles
+    // against its OWN handle store (gated on ITS hasTaintedArgs), and records
+    // tags into its OWN request — no deserialized result is shared across
+    // requests. The store write stays exactly once (the leader's).
+    const existing = inFlightExecutions.get(cacheKey);
+    if (existing) {
+      let envelope: CacheEnvelope | undefined;
+      try {
+        envelope = await existing;
+      } catch {
+        // Leader rejected (function threw or its result was not serializable);
+        // its map entry is already cleared, so fall through to a fresh run.
+        envelope = undefined;
+      }
+      if (envelope) {
+        try {
+          return await serveCached({
+            value: envelope.serialized,
+            handles: envelope.handles,
+            tags: envelope.tags,
+            shouldRevalidate: false,
+          });
+        } catch (error) {
+          reportCacheError(
+            error,
+            "cache-corrupt",
+            `[use cache] "${id}" inflight-hit`,
+          );
+          // Fall through to a fresh execution below.
+        }
+      }
+    }
+
+    // This call becomes the leader. Register a deferred envelope so concurrent
+    // callers dedup onto it; it is resolved/rejected exactly once below (or on a
+    // function throw). clearSelf only deletes the map slot if it still holds
+    // THIS promise, so a fall-through retry (rare rejected-leader path) can't
+    // evict a newer leader's entry.
+    let resolveEnvelope!: (env: CacheEnvelope) => void;
+    let rejectEnvelope!: (err: unknown) => void;
+    const envelopePromise = new Promise<CacheEnvelope>((res, rej) => {
+      resolveEnvelope = res;
+      rejectEnvelope = rej;
+    });
+    // Followers attach their own catch; guard the map's own reference so a
+    // rejected envelope with no waiter is not an unhandled rejection.
+    envelopePromise.catch(() => {});
+    inFlightExecutions.set(cacheKey, envelopePromise);
+    const clearSelf = (): void => {
+      if (inFlightExecutions.get(cacheKey) === envelopePromise) {
+        inFlightExecutions.delete(cacheKey);
+      }
+    };
+
+    // execute, serialize, store
     const handleStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
     let capture: HandleCapture | undefined;
     let stopCapture: (() => void) | undefined;
@@ -471,6 +620,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     try {
       scoped = runWithCacheTagScope(() => fn.apply(this, args));
       result = await scoped.result;
+    } catch (execError) {
+      // The function threw: drop the in-flight entry and reject any waiters so
+      // they retry fresh, then propagate to this caller.
+      clearSelf();
+      rejectEnvelope(execError);
+      throw execError;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
@@ -491,28 +646,53 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     ];
     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 () => {
+    // Serialize + encode handles ONCE, resolve the in-flight envelope so any
+    // concurrent followers can serve a synthetic hit, then persist to the store.
+    // Fully non-blocking when waitUntil is available — the leader's response
+    // waits on neither serialization nor the store write.
+    const finalizeAndWrite = async (): Promise<void> => {
+      let serialized: string | null;
+      let encodedHandles: string | undefined;
       try {
-        const serialized = await serializeResult(result);
-        if (serialized !== null) {
-          const encodedHandles = capture?.data
-            ? await encodeHandles(capture.data)
-            : undefined;
-          await store.setItem!(cacheKey, serialized, {
-            handles: encodedHandles,
-            ttl: profile.ttl,
-            swr: profile.swr,
-            tags: allTags.length > 0 ? allTags : undefined,
-          });
-        }
+        serialized = await serializeResult(result);
+        encodedHandles = capture?.data
+          ? await encodeHandles(capture.data)
+          : undefined;
+      } catch (buildError) {
+        // Serialize/handle-encode failed: no envelope for followers (they run
+        // fresh) and nothing to write.
+        clearSelf();
+        rejectEnvelope(buildError);
+        requestCtx?._reportBackgroundError?.(buildError, "cache-write");
+        return;
+      }
+      clearSelf();
+      if (serialized === null) {
+        // Non-serializable result: no store write (matches the prior silent
+        // skip); reject so any waiter falls through to a fresh execution.
+        rejectEnvelope(
+          new Error(
+            `[use cache] "${id}" result is not serializable; not cached`,
+          ),
+        );
+        return;
+      }
+      // Hand followers the envelope before the store write so a slow/failed
+      // write never stalls them.
+      resolveEnvelope({ serialized, tags: allTags, handles: encodedHandles });
+      try {
+        await store.setItem!(cacheKey, serialized, {
+          handles: encodedHandles,
+          ttl: profile.ttl,
+          swr: profile.swr,
+          tags: allTags.length > 0 ? allTags : undefined,
+        });
       } catch (writeError) {
         requestCtx?._reportBackgroundError?.(writeError, "cache-write");
       }
     };
 
-    await runBackground(requestCtx, cacheWrite, true);
+    await runBackground(requestCtx, finalizeAndWrite, true);
 
     return result;
   };

package/src/cache/document-cache.ts

@@ -127,20 +127,31 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
 // ============================================================================
 
 /**
- * Add cache status header to response for debugging
+ * Add the cache-status header (HIT/STALE/MISS) to a response.
+ *
+ * The response we get here is always a fresh instance — the store rebuilds a
+ * new Response per getResponse(), and the miss path wraps a fresh Response
+ * around the tee'd body — so mutating its headers in place is safe and avoids
+ * cloning every header + allocating a new Response on every cache hit. Only when
+ * the headers are immutable (a guarded Response rejects set() with a TypeError)
+ * do we fall back to rebuilding the Response with a mutable Headers.
  */
 function addCacheStatusHeader(
   response: Response,
   status: "HIT" | "STALE" | "MISS",
 ): Response {
-  const headers = new Headers(response.headers);
-  headers.set(CACHE_STATUS_HEADER, status);
-
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
+  try {
+    response.headers.set(CACHE_STATUS_HEADER, status);
+    return response;
+  } catch {
+    const headers = new Headers(response.headers);
+    headers.set(CACHE_STATUS_HEADER, status);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
 }
 
 /**

package/src/cache/memory-segment-store.ts

@@ -130,8 +130,25 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
     ctx: RequestContext<TEnv>,
     defaultKey: string,
   ) => string | Promise<string>;
+
+  /**
+   * Maximum number of entries kept per internal family (segment, response,
+   * item, shell). On insert, once a family reaches the cap its oldest entry is
+   * evicted FIFO (insertion order) and its tag-index entries are cleaned up, so
+   * a long-lived instance can't grow without bound. Lazy TTL expiry still runs
+   * independently. Defaults to DEFAULT_MAX_ENTRIES (1000).
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({ maxEntries: 500 });
+   * ```
+   */
+  maxEntries?: number;
 }
 
+/** Default per-family entry cap for MemorySegmentCacheStore (FIFO eviction). */
+const DEFAULT_MAX_ENTRIES = 1000;
+
 /**
  * In-memory segment cache store.
  *
@@ -139,10 +156,16 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * For production with multiple instances, use a distributed store
  * like Cloudflare KV or Redis.
  *
+ * Each family is size-capped at `maxEntries` (default 1000) with FIFO eviction
+ * on insert, so a long-lived instance can't grow unbounded; TTL expiry stays
+ * lazy on top of that.
+ *
  * Tag-index cleanup is lazy, mirroring the data maps: a tagged entry that
  * expires but is never re-read or invalidated leaves its forward+reverse index
- * entries resident until the key is reused or invalidated. This is bounded by
- * the distinct-tag count and acceptable for a dev/single-instance store.
+ * entries resident until the key is reused, invalidated, or FIFO-evicted. This
+ * is bounded by the distinct-tag count and acceptable for a dev/single-instance
+ * store. FIFO eviction unregisters the evicted key's tags, so the tag maps do
+ * not outlive the capped data maps.
  *
  * @example
  * ```typescript
@@ -176,6 +199,8 @@ export class MemorySegmentCacheStore<
     ctx: RequestContext<TEnv>,
     defaultKey: string,
   ) => string | Promise<string>;
+  /** Per-family FIFO entry cap. */
+  readonly maxEntries: number;
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
     if (options?.name != null) {
@@ -213,6 +238,28 @@ export class MemorySegmentCacheStore<
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
+    this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  }
+
+  /**
+   * FIFO cap enforcement, called before inserting `incomingKey` into `map`.
+   * When the key is new and the family is at capacity, the oldest entries are
+   * evicted in insertion order and their tag-index entries unregistered (so the
+   * tag maps don't outlive the capped data map). Overwriting an existing key
+   * grows nothing, so it is a no-op.
+   */
+  private evictIfNeeded<V>(
+    map: Map<string, V>,
+    incomingKey: string,
+    prefix: string,
+  ): void {
+    if (map.has(incomingKey)) return;
+    while (map.size >= this.maxEntries) {
+      const oldest = map.keys().next().value;
+      if (oldest === undefined) break;
+      map.delete(oldest);
+      this.unregisterTags(`${prefix}:${oldest}`);
+    }
   }
 
   async get(key: string): Promise<CacheGetResult | null> {
@@ -245,6 +292,7 @@ export class MemorySegmentCacheStore<
     };
     const prefixedKey = `seg:${key}`;
     this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.cache, key, "seg");
     this.cache.set(key, entry);
     if (data.tags && data.tags.length > 0) {
       this.registerTags(data.tags, prefixedKey);
@@ -308,6 +356,7 @@ export class MemorySegmentCacheStore<
 
       const prefixedKey = `res:${key}`;
       this.unregisterTags(prefixedKey);
+      this.evictIfNeeded(this.responseCache, key, "res");
       this.responseCache.set(key, {
         body,
         status: response.status,
@@ -357,6 +406,7 @@ export class MemorySegmentCacheStore<
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
     const prefixedKey = `item:${key}`;
     this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.itemCache, key, "item");
     this.itemCache.set(key, {
       value,
       handles: options?.handles,
@@ -400,6 +450,7 @@ export class MemorySegmentCacheStore<
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
     const prefixedKey = `shell:${key}`;
     this.unregisterTags(prefixedKey);
+    this.evictIfNeeded(this.shellCache, key, "shell");
     this.shellCache.set(key, { entry, expiresAt, staleAt, tags });
     if (tags && tags.length > 0) {
       this.registerTags(tags, prefixedKey);

package/src/cache/segment-codec.ts

@@ -25,16 +25,16 @@ export async function streamToString(
 ): Promise<string> {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
-  let result = "";
+  const chunks: string[] = [];
 
   while (true) {
     const { done, value } = await reader.read();
     if (done) break;
-    result += decoder.decode(value, { stream: true });
+    chunks.push(decoder.decode(value, { stream: true }));
   }
 
-  result += decoder.decode(); // flush
-  return result;
+  chunks.push(decoder.decode()); // flush
+  return chunks.join("");
 }
 
 /**

package/src/cache/shell-snapshot.ts

@@ -33,6 +33,7 @@ import type {
   ShellSnapshotRecord,
   ShellSnapshotItemValue,
   ShellSnapshotResponseValue,
+  ShellSnapshotLoaderValue,
 } from "./types.js";
 import { bufferToBase64, base64ToBuffer } from "./cf/cf-base64.js";
 import { isPerClientSignalHeader } from "../browser/cookie-name.js";
@@ -244,6 +245,51 @@ export function getRecordingStore<TEnv>(
   return store instanceof RecordingShellStore ? store : undefined;
 }
 
+/**
+ * Materialize the loader-family seed from a shell snapshot for a HIT's tail
+ * render: Flight-deserialize each recorded (promise-elided) bake-lane
+ * container into a segment-key -> container Map, which serveShellHit assigns
+ * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * Lives here so every snapshot family is decoded in this module (the
+ * item/segment/response families via {@link SeededShellStore}); the loader
+ * family is not a store read, so it seeds the context instead of a store.
+ *
+ * Deserializations run in parallel; a record that fails to decode is skipped
+ * (that loader drifts — the pre-snapshot behavior — instead of failing the
+ * HIT). Returns undefined when the snapshot carries no loader records, without
+ * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ */
+export async function buildShellLoaderSeed(
+  snapshot: ShellSnapshotRecord[],
+): Promise<Map<string, unknown> | undefined> {
+  const loaderRecords: ShellSnapshotRecord[] = [];
+  for (const rec of snapshot) {
+    if (rec.family === "loader") loaderRecords.push(rec);
+  }
+  if (loaderRecords.length === 0) return undefined;
+
+  const { deserializeResult } = await import("./segment-codec.js");
+  const entries = await Promise.all(
+    loaderRecords.map(async (rec): Promise<[string, unknown] | null> => {
+      try {
+        return [
+          rec.key,
+          await deserializeResult(
+            (rec.value as ShellSnapshotLoaderValue).value,
+          ),
+        ];
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const seed = new Map<string, unknown>();
+  for (const entry of entries) {
+    if (entry) seed.set(entry[0], entry[1]);
+  }
+  return seed.size > 0 ? seed : undefined;
+}
+
 /**
  * A read-through overlay the HIT tail render reads through. For a key present in
  * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
@@ -269,9 +315,12 @@ export class SeededShellStore<
         this.items.set(rec.key, rec.value as ShellSnapshotItemValue);
       } else if (rec.family === "segment") {
         this.segments.set(rec.key, rec.value as CachedEntryData);
-      } else {
+      } else if (rec.family === "response") {
         this.responses.set(rec.key, rec.value as ShellSnapshotResponseValue);
       }
+      // "loader" family records are not store reads — serveShellHit seeds them
+      // onto the tail context (_shellLoaderSeed) for the resolveLoaderData
+      // overlay instead.
     }
   }
 

package/src/cache/types.ts

@@ -271,11 +271,27 @@ export interface ShellCacheEntry {
 }
 
 /**
- * The cache-store families a shell snapshot pins. Excludes the shell family
- * itself (getShell/putShell) — the snapshot rides INSIDE a shell entry, so
- * recording it would be self-referential.
+ * The families a shell snapshot pins. The item/segment/response families are
+ * cache-store reads/writes (recorded by RecordingShellStore); the loader family
+ * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
+ * no renderable loading(), executed during capture — see
+ * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
+ * it would be self-referential.
  */
-export type ShellSnapshotFamily = "item" | "segment" | "response";
+export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
+
+/**
+ * The stored form of a loader-family snapshot value: the bake-lane loader's
+ * settled container, Flight-serialized AFTER eliding every still-pending nested
+ * promise to a hole marker (the marker paths are holes, not shell material; on
+ * a HIT the overlay re-slots the fresh run's promises there). Flight (not JSON)
+ * so typed values (Date/Map) survive the round trip.
+ */
+export interface ShellSnapshotLoaderValue {
+  /** RSC-serialized elided container (see loader-snapshot.ts). */
+  value: string;
+}
 
 /** A serialized cached Response for the response family of a shell snapshot. */
 export interface ShellSnapshotResponseValue {
@@ -307,7 +323,11 @@ export interface ShellSnapshotItemValue {
 export interface ShellSnapshotRecord {
   family: ShellSnapshotFamily;
   key: string;
-  value: ShellSnapshotItemValue | CachedEntryData | ShellSnapshotResponseValue;
+  value:
+    | ShellSnapshotItemValue
+    | CachedEntryData
+    | ShellSnapshotResponseValue
+    | ShellSnapshotLoaderValue;
 }
 
 /**