@rangojs/router 0.0.0-experimental.139 → 0.0.0-experimental.140

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

@@ -34,6 +34,7 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
+  ShellCacheEntry,
 } from "../types.js";
 import {
   _getRequestContext,
@@ -189,6 +190,29 @@ interface KVItemEnvelope {
   ta?: number;
 }
 
+/**
+ * KV envelope for PPR shell cache entries.
+ * @internal
+ */
+interface KVShellEnvelope {
+  /** base64-encoded prelude bytes */
+  p: string;
+  /** postponed state JSON, or null (DATA variant — no holes) */
+  po: string | null;
+  /** React.version captured at prerender time */
+  rv: string;
+  /** createdAt (ms epoch) */
+  c: number;
+  /** When entry becomes stale (ms epoch) */
+  s: number;
+  /** When entry hard-expires (ms epoch) */
+  e: number;
+  /** Cache tags (for distributed tag invalidation) */
+  t?: string[];
+  /** Timestamp when tags were attached (ms epoch) */
+  ta?: number;
+}
+
 /**
  * KV envelope for document cache entries.
  * @internal
@@ -1574,6 +1598,137 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  // ============================================================================
+  // Shell Cache Methods (PPR shell resume) — KV-only in v1
+  // ============================================================================
+  //
+  // Unlike the segment/item/document tiers, the shell family has NO Cache-API L1
+  // tier: the prelude bytes + postponed blob are large and version-coupled, and a
+  // per-colo L1 for them is a deliberate follow-up (see the PPR shell-resume
+  // design doc). Shell entries live only in KV (the global tier), so the family
+  // requires a configured KV namespace; without one, getShell/putShell no-op and
+  // the shell-cache middleware fails open to a full HTML render. Tag invalidation
+  // still applies: shell entries carry tags/taggedAt and are checked against the
+  // same KV markers isGloballyInvalidated() reads for every other tier.
+
+  /**
+   * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
+   * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
+   * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
+   * no REVALIDATING herd guard, so the shell-cache middleware's module-level
+   * in-flight set is the recapture stampede guard.
+   */
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    if (!this.kv) return null;
+    try {
+      const kvKey = this.toKVKey(`shell:${key}`);
+      const { value: envelope, timedOut } =
+        await this.kvGetOrEvict<KVShellEnvelope>(
+          kvKey,
+          (e) =>
+            typeof e.p === "string" &&
+            (e.po === null || typeof e.po === "string") &&
+            typeof e.rv === "string" &&
+            typeof e.e === "number" &&
+            typeof e.s === "number",
+          "getShell",
+        );
+      // A timeout, a missing key, or an already-evicted corrupt entry is a miss.
+      if (timedOut || !envelope) return null;
+
+      const now = Date.now();
+      if (now > envelope.e) return null;
+
+      if (await this.isGloballyInvalidated(envelope.t, envelope.ta)) {
+        return null;
+      }
+
+      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
+      return {
+        entry: {
+          prelude: envelope.p,
+          postponed: envelope.po,
+          reactVersion: envelope.rv,
+          createdAt: envelope.c,
+        },
+        shouldRevalidate,
+      };
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[CFCacheStore] getShell");
+      return null;
+    }
+  }
+
+  /**
+   * Store a PPR shell entry in KV with TTL and optional SWR window. Non-blocking
+   * (waitUntil) like the other KV writes. The tags/taggedAt ride in the envelope
+   * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
+   */
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    // KV-only tier: needs a KV namespace and waitUntil (writes are non-blocking).
+    if (!this.kv || !this.waitUntil) return;
+    try {
+      const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
+      const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+      const totalTtl = ttl + swrWindow;
+      // KV requires expirationTtl >= 60s; skip a shorter-lived shell rather than
+      // letting kv.put reject inside waitUntil (mirrors setItem/kvSetSegment).
+      if (totalTtl < 60) return;
+
+      const staleAt = Date.now() + ttl * 1000;
+      const taggedAt =
+        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+
+      const kvKey = this.toKVKey(`shell:${key}`);
+      // A key over the KV limit makes kv.put reject deep inside waitUntil; report
+      // and skip the doomed write (mirrors kvSetSegment).
+      const kvKeyBytes = kvKeyByteLength(kvKey);
+      if (kvKeyBytes > KV_MAX_KEY_BYTES) {
+        reportCacheError(
+          new Error(
+            `shell cache key produces a ${kvKeyBytes}-byte KV key, over the ` +
+              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted.`,
+          ),
+          "cache-write",
+          "[CFCacheStore] putShell",
+        );
+        return;
+      }
+
+      this.waitUntil(() =>
+        reportingAsync(
+          () => {
+            const envelope: KVShellEnvelope = {
+              p: entry.prelude,
+              po: entry.postponed,
+              rv: entry.reactVersion,
+              c: entry.createdAt,
+              s: staleAt,
+              e: staleAt + swrWindow * 1000,
+              t: tags,
+              ta: taggedAt,
+            };
+            return this.kv!.put(kvKey, JSON.stringify(envelope), {
+              expirationTtl: totalTtl,
+            });
+          },
+          "cache-write",
+          "[CFCacheStore] putShell",
+        ),
+      );
+    } catch (error) {
+      reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
+    }
+  }
+
   // ============================================================================
   // Key Helpers
   // ============================================================================

package/src/cache/index.ts

@@ -4,6 +4,7 @@ export type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
+  ShellCacheEntry,
   SerializedSegmentData,
   SegmentHandleData,
 } from "./types.js";
@@ -43,4 +44,9 @@ export {
   type DocumentCacheOptions,
 } from "./document-cache.js";
 
+export {
+  createShellCacheMiddleware,
+  type ShellCacheOptions,
+} from "./shell-cache.js";
+
 export type { CacheErrorCategory } from "./cache-error.js";

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

@@ -12,6 +12,7 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
+  ShellCacheEntry,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 import { isPerClientSignalHeader } from "../browser/cookie-name.js";
@@ -26,6 +27,7 @@ import { reportCacheError } from "./cache-error.js";
 const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
 const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
+const SHELL_CACHE_REGISTRY_KEY = "__rsc_router_shell_cache_registry__";
 const TAG_INDEX_REGISTRY_KEY = "__rsc_router_tag_index_registry__";
 const KEY_TAGS_REGISTRY_KEY = "__rsc_router_key_tags_registry__";
 
@@ -65,6 +67,13 @@ interface CachedItemEntry {
   tags?: string[];
 }
 
+interface CachedShellEntry {
+  entry: ShellCacheEntry;
+  expiresAt: number;
+  staleAt: number;
+  tags?: string[];
+}
+
 /**
  * Options for MemorySegmentCacheStore
  */
@@ -157,7 +166,8 @@ export class MemorySegmentCacheStore<
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
-  /** tag -> set of prefixed cache keys (seg:key, res:key, item:key) */
+  private shellCache: Map<string, CachedShellEntry>;
+  /** tag -> set of prefixed cache keys (seg:key, res:key, item:key, shell:key) */
   private tagIndex: Map<string, Set<string>>;
   /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
   private keyTags: Map<string, Set<string>>;
@@ -181,6 +191,10 @@ export class MemorySegmentCacheStore<
         ITEM_CACHE_REGISTRY_KEY,
         options.name,
       );
+      this.shellCache = getNamedMap<CachedShellEntry>(
+        SHELL_CACHE_REGISTRY_KEY,
+        options.name,
+      );
       this.tagIndex = getNamedMap<Set<string>>(
         TAG_INDEX_REGISTRY_KEY,
         options.name,
@@ -193,6 +207,7 @@ export class MemorySegmentCacheStore<
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
       this.itemCache = new Map<string, CachedItemEntry>();
+      this.shellCache = new Map<string, CachedShellEntry>();
       this.tagIndex = new Map<string, Set<string>>();
       this.keyTags = new Map<string, Set<string>>();
     }
@@ -245,6 +260,7 @@ export class MemorySegmentCacheStore<
     this.cache.clear();
     this.responseCache.clear();
     this.itemCache.clear();
+    this.shellCache.clear();
     this.tagIndex.clear();
     this.keyTags.clear();
   }
@@ -353,6 +369,43 @@ export class MemorySegmentCacheStore<
     }
   }
 
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    const cached = this.shellCache.get(key);
+    if (!cached) return null;
+
+    const now = Date.now();
+    if (now > cached.expiresAt) {
+      this.unregisterTags(`shell:${key}`);
+      this.shellCache.delete(key);
+      return null;
+    }
+
+    // SWR mirrors the item family: stale within the swr window still serves, and
+    // signals shouldRevalidate so the middleware schedules a background recapture.
+    const shouldRevalidate = cached.staleAt > 0 && now > cached.staleAt;
+    return { entry: cached.entry, shouldRevalidate };
+  }
+
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
+    const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+    const prefixedKey = `shell:${key}`;
+    this.unregisterTags(prefixedKey);
+    this.shellCache.set(key, { entry, expiresAt, staleAt, tags });
+    if (tags && tags.length > 0) {
+      this.registerTags(tags, prefixedKey);
+    }
+  }
+
   async invalidateTags(tags: string[]): Promise<void> {
     for (const tag of tags) {
       const keys = this.tagIndex.get(tag);
@@ -371,6 +424,8 @@ export class MemorySegmentCacheStore<
           this.responseCache.delete(rawKey);
         } else if (prefix === "item") {
           this.itemCache.delete(rawKey);
+        } else if (prefix === "shell") {
+          this.shellCache.delete(rawKey);
         }
 
         this.unregisterTags(prefixedKey);
@@ -421,6 +476,7 @@ export class MemorySegmentCacheStore<
     delete (globalThis as any)[CACHE_REGISTRY_KEY];
     delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];
     delete (globalThis as any)[ITEM_CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[SHELL_CACHE_REGISTRY_KEY];
     delete (globalThis as any)[TAG_INDEX_REGISTRY_KEY];
     delete (globalThis as any)[KEY_TAGS_REGISTRY_KEY];
   }