@rangojs/router 0.4.1 → 0.4.3

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

@@ -42,6 +42,7 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { VERSION } from "@rangojs/router:version";
 import {
   isPerClientSignalHeader,
@@ -262,10 +263,10 @@ interface KVItemEnvelope {
 }
 
 /**
- * KV envelope for PPR shell cache entries.
+ * Coupled Cache API/KV envelope for PPR shell cache entries.
  * @internal
  */
-interface KVShellEnvelope {
+interface CFShellEnvelope {
   /** base64-encoded prelude bytes */
   p: string;
   /** postponed state JSON, or null (DATA variant — no holes) */
@@ -309,6 +310,67 @@ interface KVShellEnvelope {
   no?: true;
 }
 
+type CFShellDebugOutcome =
+  | "l1-hit"
+  | "l1-miss"
+  | "kv-hit"
+  | "kv-miss"
+  | "kv-promoted"
+  | "marker-invalidated"
+  | "l1-stored"
+  | "kv-stored"
+  | "write-invalidated";
+
+interface CFShellDebugDetails {
+  tier?: "l1" | "kv";
+  reason?:
+    | "absent"
+    | "timeout"
+    | "error"
+    | "non-200"
+    | "corrupt"
+    | "malformed"
+    | "expired"
+    | "unavailable";
+  freshness?: "fresh" | "stale";
+  status?: number;
+  matchMs?: number;
+  bodyReadMs?: number;
+  markerMs?: number;
+  readMs?: number;
+  expiresAt?: number;
+  remainingTtl?: number;
+}
+
+/** Validate the coupled PPR shell envelope before any field reaches resume. */
+function isShellEnvelope(value: unknown): value is CFShellEnvelope {
+  if (value == null || typeof value !== "object") return false;
+  const envelope = value as Partial<CFShellEnvelope>;
+  return (
+    typeof envelope.p === "string" &&
+    (envelope.po === null || typeof envelope.po === "string") &&
+    typeof envelope.rv === "string" &&
+    (envelope.bv === undefined || typeof envelope.bv === "string") &&
+    typeof envelope.c === "number" &&
+    Number.isFinite(envelope.c) &&
+    typeof envelope.s === "number" &&
+    Number.isFinite(envelope.s) &&
+    typeof envelope.e === "number" &&
+    Number.isFinite(envelope.e) &&
+    (envelope.t === undefined ||
+      (Array.isArray(envelope.t) &&
+        envelope.t.every((tag) => typeof tag === "string"))) &&
+    (envelope.ta === undefined ||
+      (typeof envelope.ta === "number" && Number.isFinite(envelope.ta))) &&
+    (envelope.i === undefined || typeof envelope.i === "string") &&
+    (envelope.sn === undefined || Array.isArray(envelope.sn)) &&
+    (envelope.dk === undefined || typeof envelope.dk === "string") &&
+    (envelope.lh === undefined || typeof envelope.lh === "boolean") &&
+    (envelope.tw === undefined || envelope.tw === true) &&
+    (envelope.no === undefined || envelope.no === true)
+  );
+}
+
 /**
  * KV envelope for document cache entries.
  * @internal
@@ -515,6 +577,36 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+  private debugShell(
+    key: string,
+    outcome: CFShellDebugOutcome,
+    details: CFShellDebugDetails = {},
+  ): void {
+    if (!INTERNAL_RANGO_DEBUG) return;
+    const request = _getRequestContext()?.request as
+      | (Request & { cf?: { colo?: unknown } })
+      | undefined;
+    const ray = request?.headers.get("cf-ray") ?? undefined;
+    const cfColo = request?.cf?.colo;
+    const colo =
+      typeof cfColo === "string"
+        ? cfColo
+        : ray?.includes("-")
+          ? ray.slice(ray.lastIndexOf("-") + 1)
+          : undefined;
+    console.log(
+      `[CFCacheStore][shell] ${JSON.stringify({
+        key,
+        outcome,
+        at: Date.now(),
+        ray,
+        colo,
+        ...details,
+      })}`,
+    );
+  }
+
   /**
    * Resolve the cache-key base URL for the current cache operation.
    * Prefers an explicit `baseUrl` option; otherwise derives it from the live
@@ -1765,17 +1857,18 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   // ============================================================================
-  // Shell Cache Methods (PPR shell resume) — KV-only in v1
+  // Shell Cache Methods (PPR shell resume) — Cache API L1 + KV L2
   // ============================================================================
   //
-  // 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 integrated PPR serve path 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.
+  // KV remains the durable, cross-colo shell tier. Cache API is a per-colo
+  // read-through accelerator: writes populate both tiers, and a valid KV hit
+  // promotes the same coupled envelope into L1. The family still requires KV;
+  // without it, getShell/putShell no-op and PPR fails open to a full HTML render.
+  //
+  // Shell L1 hits deliberately keep the KV generation-marker check even in
+  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time: an
+  // invalidation can purge while an older capture is still running, then that
+  // capture can land after the purge. The marker check rejects that resurrection.
 
   /**
    * Warn once per isolate that the shell family is inert: getShell/putShell
@@ -1799,10 +1892,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * 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 capture scheduler's module-level
+   * Get a cached PPR shell entry from Cache API, falling through to KV and
+   * promoting a valid KV hit. Both tiers store one envelope so the prelude,
+   * postponed state, snapshot, versions, and generation metadata cannot mix.
+   * SWR remains a plain staleness flag; the capture scheduler's module-level
    * in-flight set is the recapture stampede guard.
    */
   async getShell(
@@ -1813,56 +1906,128 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       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",
+      const cache = await this.getCache();
+      const request = this.keyToRequest(`shell:${key}`);
+      const matchStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const {
+        response,
+        timedOut,
+        error: matchError,
+      } = await this.matchWithTimeout(cache, request);
+      const matchMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - matchStartedAt
+        : undefined;
+
+      if (!response) {
+        if (matchError) {
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] getShell L1 match",
+          );
+        }
+        this.debugShell(key, "l1-miss", {
+          reason: matchError ? "error" : timedOut ? "timeout" : "absent",
+          matchMs,
+        });
+        return this.kvGetShell(key);
+      }
+      if (response.status !== 200) {
+        this.debugShell(key, "l1-miss", {
+          reason: "non-200",
+          status: response.status,
+          matchMs,
+        });
+        return this.kvGetShell(key);
+      }
+
+      const bodyStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const { value, errored, error } =
+        await this.readJsonWithTimeout<unknown>(response);
+      const bodyReadMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - bodyStartedAt
+        : undefined;
+      if (value === undefined) {
+        this.debugShell(key, "l1-miss", {
+          reason: errored ? "corrupt" : "timeout",
+          matchMs,
+          bodyReadMs,
+        });
+        if (errored) {
+          return this.healCorruptL1(cache, request, error, "getShell", () =>
+            this.kvGetShell(key),
+          );
+        }
+        return this.kvGetShell(key);
+      }
+      if (!isShellEnvelope(value)) {
+        this.debugShell(key, "l1-miss", {
+          reason: "malformed",
+          matchMs,
+          bodyReadMs,
+        });
+        return this.healCorruptL1(
+          cache,
+          request,
+          new Error("malformed/partial L1 shell envelope"),
           "getShell",
+          () => this.kvGetShell(key),
         );
-      // 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 (now > value.e) {
+        this.debugShell(key, "l1-miss", {
+          reason: "expired",
+          matchMs,
+          bodyReadMs,
+          expiresAt: value.e,
+        });
+        return this.kvGetShell(key);
+      }
 
-      if (await this.isGloballyInvalidated(envelope.t, envelope.ta)) {
+      // Unlike other L1 families, shells always check the durable generation
+      // marker. See the capture-start/purge race documented above.
+      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(value.t, value.ta);
+      const markerMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - markerStartedAt
+        : undefined;
+      if (invalidated) {
+        this.debugShell(key, "marker-invalidated", {
+          tier: "l1",
+          matchMs,
+          bodyReadMs,
+          markerMs,
+        });
         return null;
       }
 
-      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
+      const shouldRevalidate = value.s > 0 && now > value.s;
+      this.debugShell(key, "l1-hit", {
+        freshness: shouldRevalidate ? "stale" : "fresh",
+        matchMs,
+        bodyReadMs,
+        markerMs,
+        expiresAt: value.e,
+      });
       return {
-        entry: {
-          prelude: envelope.p,
-          postponed: envelope.po,
-          reactVersion: envelope.rv,
-          buildVersion: envelope.bv,
-          initialTheme: envelope.i,
-          snapshot: envelope.sn,
-          docKey: envelope.dk,
-          handlerLiveHoles: envelope.lh,
-          transitionWhen: envelope.tw,
-          navigationOnly: envelope.no,
-          createdAt: envelope.c,
-        },
+        entry: this.shellEnvelopeToEntry(value),
         shouldRevalidate,
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getShell");
-      return null;
+      this.debugShell(key, "l1-miss", { reason: "error" });
+      return this.kvGetShell(key);
     }
   }
 
   /**
-   * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
-   * registered with waitUntil and awaited so invalidation rejection can be
-   * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
-   * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
+   * Store a PPR shell envelope in Cache API and, when its retention meets KV's
+   * 60-second floor, KV. The shared write is registered with waitUntil and
+   * awaited so invalidation rejection can be acknowledged to the capture
+   * scheduler. Short-lived shells remain useful in L1 even though KV rejects
+   * them.
    */
   async putShell(
     key: string,
@@ -1871,9 +2036,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     swrSeconds?: number,
     tags?: string[],
   ): Promise<"stored" | "invalidated" | void> {
-    // KV-only tier: needs a KV namespace and waitUntil. The same write promise is
-    // registered for isolate lifetime and awaited so invalidation rejection can
-    // be acknowledged to the capture scheduler.
+    // KV remains required for durable generation markers and cross-colo reads.
     if (!this.kv) {
       this.warnShellFamilyInertOnce();
       return;
@@ -1883,9 +2046,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       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 retentionTtl =
         tags && tags.length > 0 && this.tagInvalidationTtl
@@ -1898,55 +2058,93 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : 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).
+      let writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
       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.`,
+              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted to KV (L2).`,
           ),
           "cache-write",
           "[CFCacheStore] putShell",
         );
-        return;
+        writeKv = false;
       }
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
-        try {
-          if (
-            tags &&
-            tags.length > 0 &&
-            (await this.isGloballyInvalidated(tags, entry.createdAt))
-          ) {
-            return "invalidated";
-          }
-          const envelope: KVShellEnvelope = {
-            p: entry.prelude,
-            po: entry.postponed,
-            rv: entry.reactVersion,
-            bv: entry.buildVersion,
-            c: entry.createdAt,
-            s: staleAt,
-            e: expiresAt,
-            t: tags,
-            ta: taggedAt,
-            i: entry.initialTheme,
-            sn: entry.snapshot,
-            dk: entry.docKey,
-            lh: entry.handlerLiveHoles,
-            tw: entry.transitionWhen,
-            no: entry.navigationOnly,
-          };
-          await this.kv!.put(kvKey, JSON.stringify(envelope), {
-            expirationTtl: retentionTtl,
-          });
-          return "stored";
-        } catch (error) {
-          reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
-          return undefined;
+        if (
+          tags &&
+          tags.length > 0 &&
+          (await this.isGloballyInvalidated(tags, entry.createdAt))
+        ) {
+          this.debugShell(key, "write-invalidated");
+          return "invalidated";
+        }
+
+        const envelope: CFShellEnvelope = {
+          p: entry.prelude,
+          po: entry.postponed,
+          rv: entry.reactVersion,
+          bv: entry.buildVersion,
+          c: entry.createdAt,
+          s: staleAt,
+          e: expiresAt,
+          t: tags,
+          ta: taggedAt,
+          i: entry.initialTheme,
+          sn: entry.snapshot,
+          dk: entry.docKey,
+          lh: entry.handlerLiveHoles,
+          tw: entry.transitionWhen,
+          no: entry.navigationOnly,
+        };
+        const body = JSON.stringify(envelope);
+        const writes: Promise<boolean>[] = [
+          (async () => {
+            try {
+              const cache = await this.getCache();
+              await cache.put(
+                this.keyToRequest(`shell:${key}`),
+                this.shellEnvelopeResponse(body, envelope),
+              );
+              this.debugShell(key, "l1-stored", {
+                expiresAt: envelope.e,
+              });
+              return true;
+            } catch (error) {
+              reportCacheError(
+                error,
+                "cache-write",
+                "[CFCacheStore] putShell L1",
+              );
+              return false;
+            }
+          })(),
+        ];
+        if (writeKv) {
+          writes.push(
+            (async () => {
+              try {
+                await this.kv!.put(kvKey, body, {
+                  expirationTtl: retentionTtl,
+                });
+                this.debugShell(key, "kv-stored", {
+                  expiresAt: envelope.e,
+                });
+                return true;
+              } catch (error) {
+                reportCacheError(
+                  error,
+                  "cache-write",
+                  "[CFCacheStore] putShell L2",
+                );
+                return false;
+              }
+            })(),
+          );
         }
+        return (await Promise.all(writes)).some(Boolean) ? "stored" : undefined;
       })();
       this.waitUntil(async () => {
         await write;
@@ -1957,6 +2155,141 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /** Rebuild the public shell entry from its validated storage envelope. */
+  private shellEnvelopeToEntry(envelope: CFShellEnvelope): ShellCacheEntry {
+    return {
+      prelude: envelope.p,
+      postponed: envelope.po,
+      reactVersion: envelope.rv,
+      buildVersion: envelope.bv,
+      initialTheme: envelope.i,
+      snapshot: envelope.sn,
+      docKey: envelope.dk,
+      handlerLiveHoles: envelope.lh,
+      transitionWhen: envelope.tw,
+      navigationOnly: envelope.no,
+      createdAt: envelope.c,
+    };
+  }
+
+  /** Build the Cache API representation of the coupled shell envelope. */
+  private shellEnvelopeResponse(
+    body: string,
+    envelope: CFShellEnvelope,
+  ): Response {
+    const remainingTtl = Math.max(
+      1,
+      Math.floor((envelope.e - Date.now()) / 1000),
+    );
+    return new Response(body, {
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": `public, max-age=${remainingTtl}`,
+        [CACHE_STALE_AT_HEADER]: String(envelope.s),
+        [CACHE_EXPIRES_AT_HEADER]: String(envelope.e),
+        [CACHE_STATUS_HEADER]: "HIT",
+        ...this.tagHeaderEntries(envelope.t, envelope.ta),
+      },
+    });
+  }
+
+  /** KV shell fallback with corruption checks and background L1 promotion. */
+  private async kvGetShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    if (!this.kv) return null;
+    try {
+      const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const kvKey = this.toKVKey(`shell:${key}`);
+      const { value: envelope, timedOut } =
+        await this.kvGetOrEvict<CFShellEnvelope>(
+          kvKey,
+          isShellEnvelope,
+          "getShell",
+        );
+      const readMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - readStartedAt
+        : undefined;
+      if (timedOut || !envelope) {
+        this.debugShell(key, "kv-miss", {
+          reason: timedOut ? "timeout" : "unavailable",
+          readMs,
+        });
+        return null;
+      }
+
+      const now = Date.now();
+      if (now > envelope.e) {
+        this.debugShell(key, "kv-miss", {
+          reason: "expired",
+          readMs,
+          expiresAt: envelope.e,
+        });
+        return null;
+      }
+      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(
+        envelope.t,
+        envelope.ta,
+      );
+      const markerMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - markerStartedAt
+        : undefined;
+      if (invalidated) {
+        this.debugShell(key, "marker-invalidated", {
+          tier: "kv",
+          readMs,
+          markerMs,
+        });
+        return null;
+      }
+
+      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
+      this.debugShell(key, "kv-hit", {
+        freshness: shouldRevalidate ? "stale" : "fresh",
+        readMs,
+        markerMs,
+        expiresAt: envelope.e,
+      });
+      this.promoteShellToL1(key, envelope);
+      return {
+        entry: this.shellEnvelopeToEntry(envelope),
+        shouldRevalidate,
+      };
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[CFCacheStore] kvGetShell");
+      this.debugShell(key, "kv-miss", { reason: "error" });
+      return null;
+    }
+  }
+
+  /** Promote a valid KV shell into the per-colo Cache API tier. */
+  private promoteShellToL1(key: string, envelope: CFShellEnvelope): void {
+    if (!this.waitUntil) return;
+    this.waitUntil(() =>
+      reportingAsync(
+        async () => {
+          if (Date.now() > envelope.e) return;
+          const cache = await this.getCache();
+          const body = JSON.stringify(envelope);
+          await cache.put(
+            this.keyToRequest(`shell:${key}`),
+            this.shellEnvelopeResponse(body, envelope),
+          );
+          this.debugShell(key, "kv-promoted", {
+            remainingTtl: Math.max(
+              1,
+              Math.floor((envelope.e - Date.now()) / 1000),
+            ),
+            expiresAt: envelope.e,
+          });
+        },
+        "cache-write",
+        "[CFCacheStore] promoteShellToL1",
+      ),
+    );
+  }
+
   // ============================================================================
   // Key Helpers
   // ============================================================================

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

@@ -228,8 +228,10 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    *   per-request memo is consulted (synchronously, no KV read), so a request
    *   that ran `updateTag()` still masks its own not-yet-purged entries
    *   (read-your-own-writes).
-   * - The KV tier and PPR shells still use the KV markers — those are written
-   *   regardless, and purge cannot reach KV — so keep `kv` configured for L2.
+   * - The KV tier and PPR shell reads still use the KV markers. Runtime shell
+   *   L1 entries are purgeable, but their taggedAt is the capture-start time: a
+   *   capture can finish after an invalidation purge, so eviction alone cannot
+   *   reject that older generation. Keep `kv` configured for shell L2 + markers.
    *   Without `kv`, purge mode is the ONLY tag invalidation and the store is
    *   L1-only: a supported configuration (previously tag invalidation without
    *   KV had no read-side effect at all). One KV-less caveat: an entry whose