@rangojs/router 0.0.0-experimental.8a4d0430 → 0.0.0-experimental.8bcfea43

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

@@ -10,14 +10,21 @@ declare global {
 /**
  * Cloudflare Edge Cache Store
  *
- * Production cache store using Cloudflare's Cache API.
- * Handles SWR atomically - get() checks staleness and marks REVALIDATING in one operation.
+ * Production cache store using Cloudflare's Cache API (L1) with optional
+ * KV persistence (L2).
+ *
+ * L1 (Cache API): Per-colo, fast, ephemeral. Handles SWR atomically.
+ * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
+ *
+ * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
+ * Write flow: L1 write + L2 write (both via waitUntil)
  *
  * Features:
  * - Extended TTL for SWR window (max-age = ttl + swr)
  * - Staleness via x-edge-cache-stale-at header
- * - Atomic REVALIDATING status for thundering herd prevention
+ * - Atomic REVALIDATING status for thundering herd prevention (L1 only)
  * - Non-blocking writes via waitUntil
+ * - KV L2 for cross-colo cache persistence
  */
 
 import type {
@@ -60,12 +67,71 @@ export const MAX_REVALIDATION_INTERVAL = 30;
 // Types
 // ============================================================================
 
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
+
+/**
+ * Minimal Cloudflare KV Namespace interface.
+ * Avoids hard dependency on @cloudflare/workers-types.
+ */
+export interface KVNamespace {
+  get(key: string, options?: { type?: string }): Promise<any>;
+  put(
+    key: string,
+    value: string,
+    options?: { expirationTtl?: number },
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * KV envelope for segment cache entries.
+ * @internal
+ */
+interface KVSegmentEnvelope {
+  /** Cached segment data */
+  d: CachedEntryData;
+  /** When entry becomes stale (ms epoch) */
+  s: number;
+  /** When entry hard-expires (ms epoch) */
+  e: number;
+}
+
+/**
+ * KV envelope for function cache entries ("use cache").
+ * @internal
+ */
+interface KVItemEnvelope {
+  /** RSC-serialized return value */
+  v: string;
+  /** Handle data */
+  h?: Record<string, Record<string, unknown[]>>;
+  /** When entry becomes stale (ms epoch) */
+  s: number;
+  /** When entry hard-expires (ms epoch) */
+  e: number;
+}
+
 /**
- * Cloudflare Workers ExecutionContext (subset we need)
+ * KV envelope for document cache entries.
+ * @internal
  */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
+interface KVResponseEnvelope {
+  /** Response body as base64-encoded string (safe for binary payloads) */
+  b: string;
+  /** HTTP status code */
+  st: number;
+  /** HTTP status text */
+  stx: string;
+  /** Serialized headers as key-value pairs */
+  hd: [string, string][];
+  /** When entry becomes stale (ms epoch) */
+  s: number;
+  /** When entry hard-expires (ms epoch) */
+  e: number;
 }
 
 export interface CFCacheStoreOptions<TEnv = unknown> {
@@ -98,6 +164,20 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   ctx: ExecutionContext;
 
+  /**
+   * Optional KV namespace for L2 cache persistence.
+   *
+   * When provided, KV acts as a global fallback behind the per-colo Cache API.
+   * On L1 miss, KV is checked and hits are promoted back to L1.
+   * On writes, data is persisted to both L1 and KV.
+   *
+   * @example
+   * ```typescript
+   * new CFCacheStore({ ctx: env.ctx, kv: env.CACHE_KV })
+   * ```
+   */
+  kv?: KVNamespace;
+
   /**
    * Cache version string override. When this changes, all cached entries are
    * effectively invalidated (new keys won't match old entries).
@@ -163,6 +243,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly baseUrl: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
   private readonly version?: string;
+  private readonly kv?: KVNamespace;
 
   constructor(options: CFCacheStoreOptions<TEnv>) {
     if (!options.ctx) {
@@ -179,6 +260,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.version = options.version ?? VERSION;
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
+    this.kv = options.kv;
   }
 
   /**
@@ -232,6 +314,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return caches.default;
   }
 
+  // ============================================================================
+  // Segment Cache Methods
+  // ============================================================================
+
   /**
    * Get cached entry data by key.
    *
@@ -240,7 +326,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * - If already REVALIDATING (and recent), returns shouldRevalidate: false
    * - If fresh, returns shouldRevalidate: false
    *
-   * The atomic mark prevents thundering herd - only first request triggers revalidation.
+   * On L1 miss, falls back to KV (L2) if configured.
+   * KV hits are promoted to L1 in the background.
    */
   async get(key: string): Promise<CacheGetResult | null> {
     try {
@@ -249,7 +336,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const response = await cache.match(request);
 
       if (!response) {
-        return null;
+        return this.kvGetSegment(key);
       }
 
       // Read status headers
@@ -292,6 +379,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Store entry data with TTL and optional SWR window.
    * Uses waitUntil for non-blocking write when available.
+   * When KV is configured, also persists to L2.
    */
   async set(
     key: string,
@@ -308,7 +396,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
-      const response = new Response(JSON.stringify(data), {
+      const body = JSON.stringify(data);
+      const response = new Response(body, {
         headers: {
           "Content-Type": "application/json",
           "Cache-Control": `public, max-age=${totalTtl}`,
@@ -328,18 +417,35 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         // Blocking fallback
         await putPromise;
       }
+
+      // L2: persist to KV
+      this.kvSetSegment(key, data, staleAt, totalTtl);
     } catch (error) {
       console.error("[CFCacheStore] set failed:", error);
     }
   }
 
   /**
-   * Delete a cached entry
+   * Delete a cached entry from L1 and L2.
    */
   async delete(key: string): Promise<boolean> {
     try {
       const cache = await this.getCache();
-      return await cache.delete(this.keyToRequest(key));
+      const result = await cache.delete(this.keyToRequest(key));
+
+      // L2: delete from KV
+      if (this.kv && this.waitUntil) {
+        const kvKey = this.toKVKey(key);
+        this.waitUntil(async () => {
+          try {
+            await this.kv!.delete(kvKey);
+          } catch {
+            // KV delete failures are non-critical
+          }
+        });
+      }
+
+      return result;
     } catch (error) {
       console.error("[CFCacheStore] delete failed:", error);
       return false;
@@ -353,6 +459,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Get a cached Response by key (for document-level caching).
    * Returns the response and whether it should be revalidated (SWR).
+   * Falls back to KV (L2) on L1 miss.
    */
   async getResponse(
     key: string,
@@ -363,7 +470,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const response = await cache.match(request);
 
       if (!response || response.status !== 200) {
-        return null;
+        return this.kvGetResponse(key);
       }
 
       // Check staleness
@@ -382,6 +489,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
   /**
    * Store a Response with TTL and optional SWR window (for document-level caching).
+   * When KV is configured, also persists to L2.
    */
   async putResponse(
     key: string,
@@ -398,12 +506,19 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
+      // Clone body for potential KV write before consuming it for L1
+      const [l1Body, kvBody] = this.kv
+        ? response.body
+          ? response.body.tee()
+          : [null, null]
+        : [response.body, null];
+
       // Clone and add cache headers
       const headers = new Headers(response.headers);
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
 
-      const toCache = new Response(response.body, {
+      const toCache = new Response(l1Body, {
         status: response.status,
         statusText: response.statusText,
         headers,
@@ -420,6 +535,36 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         // Blocking fallback
         await putPromise;
       }
+
+      // L2: persist to KV (KV requires expirationTtl >= 60s)
+      if (this.kv && this.waitUntil && totalTtl >= 60) {
+        const kvKey = this.toKVKey(`doc:${key}`);
+        const headersArray: [string, string][] = [];
+        response.headers.forEach((v, k) => headersArray.push([k, v]));
+        // Read body as ArrayBuffer and encode to base64 to preserve binary payloads
+        const bodyBuf = kvBody
+          ? await new Response(kvBody).arrayBuffer()
+          : new ArrayBuffer(0);
+        const bodyBase64 = bufferToBase64(bodyBuf);
+
+        this.waitUntil(async () => {
+          try {
+            const envelope: KVResponseEnvelope = {
+              b: bodyBase64,
+              st: response.status,
+              stx: response.statusText,
+              hd: headersArray,
+              s: staleAt,
+              e: staleAt + swrWindow * 1000,
+            };
+            await this.kv!.put(kvKey, JSON.stringify(envelope), {
+              expirationTtl: totalTtl,
+            });
+          } catch (error) {
+            console.error("[CFCacheStore] KV putResponse failed:", error);
+          }
+        });
+      }
     } catch (error) {
       console.error("[CFCacheStore] putResponse failed:", error);
     }
@@ -432,6 +577,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Get a cached function result by key.
    * Follows the same SWR pattern as get() for segment caching.
+   * Falls back to KV (L2) on L1 miss.
    */
   async getItem(key: string): Promise<CacheItemResult | null> {
     try {
@@ -439,7 +585,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const request = this.keyToRequest(`fn:${key}`);
       const response = await cache.match(request);
 
-      if (!response) return null;
+      if (!response) return this.kvGetItem(key);
 
       const staleAt = Number(
         response.headers.get(CACHE_STALE_AT_HEADER) ?? "0",
@@ -485,6 +631,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
   /**
    * Store a function result with TTL and optional SWR window.
+   * When KV is configured, also persists to L2.
    */
   async setItem(
     key: string,
@@ -519,11 +666,35 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       } else {
         await putPromise;
       }
+
+      // L2: persist to KV (KV requires expirationTtl >= 60s)
+      if (this.kv && this.waitUntil && totalTtl >= 60) {
+        const kvKey = this.toKVKey(`fn:${key}`);
+        this.waitUntil(async () => {
+          try {
+            const envelope: KVItemEnvelope = {
+              v: value,
+              h: options?.handles,
+              s: staleAt,
+              e: staleAt + swrWindow * 1000,
+            };
+            await this.kv!.put(kvKey, JSON.stringify(envelope), {
+              expirationTtl: totalTtl,
+            });
+          } catch (error) {
+            console.error("[CFCacheStore] KV setItem failed:", error);
+          }
+        });
+      }
     } catch (error) {
       console.error("[CFCacheStore] setItem failed:", error);
     }
   }
 
+  // ============================================================================
+  // Key Helpers
+  // ============================================================================
+
   /**
    * Convert string key to Request object for CF Cache API.
    * Includes version in URL if specified (for cache invalidation on code changes).
@@ -537,4 +708,273 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       method: "GET",
     });
   }
+
+  /**
+   * Convert string key to KV key string.
+   * Uses same version prefix as Cache API for consistent invalidation.
+   * @internal
+   */
+  private toKVKey(key: string): string {
+    const versionPath = this.version ? `v/${this.version}/` : "";
+    return `${versionPath}${key}`;
+  }
+
+  // ============================================================================
+  // KV L2 Helpers
+  // ============================================================================
+
+  /**
+   * KV fallback for segment cache reads.
+   * Returns null if KV is not configured, entry is missing, or expired.
+   * Promotes hits to L1 via waitUntil.
+   * @internal
+   */
+  private async kvGetSegment(key: string): Promise<CacheGetResult | null> {
+    if (!this.kv) return null;
+
+    try {
+      const kvKey = this.toKVKey(key);
+      const raw = await this.kv.get(kvKey, { type: "json" });
+      if (!raw) return null;
+
+      const envelope = raw as KVSegmentEnvelope;
+      const now = Date.now();
+
+      // Hard-expired — treat as miss
+      if (now > envelope.e) return null;
+
+      const shouldRevalidate = now > envelope.s;
+
+      // Promote to L1 in background
+      this.promoteSegmentToL1(key, envelope);
+
+      return { data: envelope.d, shouldRevalidate };
+    } catch (error) {
+      console.error("[CFCacheStore] KV get failed:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Write segment data to KV.
+   * @internal
+   */
+  private kvSetSegment(
+    key: string,
+    data: CachedEntryData,
+    staleAt: number,
+    totalTtl: number,
+  ): void {
+    // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
+    if (!this.kv || !this.waitUntil || totalTtl < 60) return;
+
+    const kvKey = this.toKVKey(key);
+    const swrWindow = totalTtl * 1000 - (staleAt - Date.now());
+    const expiresAt = staleAt + swrWindow;
+
+    this.waitUntil(async () => {
+      try {
+        const envelope: KVSegmentEnvelope = {
+          d: data,
+          s: staleAt,
+          e: expiresAt,
+        };
+        await this.kv!.put(kvKey, JSON.stringify(envelope), {
+          expirationTtl: totalTtl,
+        });
+      } catch (error) {
+        console.error("[CFCacheStore] KV set failed:", error);
+      }
+    });
+  }
+
+  /**
+   * Promote segment data from KV to L1 Cache API.
+   * @internal
+   */
+  private promoteSegmentToL1(key: string, envelope: KVSegmentEnvelope): void {
+    if (!this.waitUntil) return;
+
+    this.waitUntil(async () => {
+      try {
+        const now = Date.now();
+        const remainingTtl = Math.max(1, Math.floor((envelope.e - now) / 1000));
+        const cache = await this.getCache();
+        const request = this.keyToRequest(key);
+
+        const response = new Response(JSON.stringify(envelope.d), {
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": `public, max-age=${remainingTtl}`,
+            [CACHE_STALE_AT_HEADER]: String(envelope.s),
+            [CACHE_STATUS_HEADER]: "HIT",
+          },
+        });
+
+        await cache.put(request, response);
+      } catch (error) {
+        console.error("[CFCacheStore] L1 promote failed:", error);
+      }
+    });
+  }
+
+  /**
+   * KV fallback for function cache reads.
+   * @internal
+   */
+  private async kvGetItem(key: string): Promise<CacheItemResult | null> {
+    if (!this.kv) return null;
+
+    try {
+      const kvKey = this.toKVKey(`fn:${key}`);
+      const raw = await this.kv.get(kvKey, { type: "json" });
+      if (!raw) return null;
+
+      const envelope = raw as KVItemEnvelope;
+      const now = Date.now();
+
+      if (now > envelope.e) return null;
+
+      const shouldRevalidate = now > envelope.s;
+
+      // Promote to L1
+      this.promoteItemToL1(key, envelope);
+
+      return {
+        value: envelope.v,
+        handles: envelope.h,
+        shouldRevalidate,
+      };
+    } catch (error) {
+      console.error("[CFCacheStore] KV getItem failed:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Promote function cache data from KV to L1.
+   * @internal
+   */
+  private promoteItemToL1(key: string, envelope: KVItemEnvelope): void {
+    if (!this.waitUntil) return;
+
+    this.waitUntil(async () => {
+      try {
+        const now = Date.now();
+        const remainingTtl = Math.max(1, Math.floor((envelope.e - now) / 1000));
+        const cache = await this.getCache();
+        const request = this.keyToRequest(`fn:${key}`);
+
+        const body = JSON.stringify({ value: envelope.v, handles: envelope.h });
+        const response = new Response(body, {
+          headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": `public, max-age=${remainingTtl}`,
+            [CACHE_STALE_AT_HEADER]: String(envelope.s),
+            [CACHE_STATUS_HEADER]: "HIT",
+          },
+        });
+
+        await cache.put(request, response);
+      } catch (error) {
+        console.error("[CFCacheStore] L1 item promote failed:", error);
+      }
+    });
+  }
+
+  /**
+   * KV fallback for document cache reads.
+   * @internal
+   */
+  private async kvGetResponse(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
+    if (!this.kv) return null;
+
+    try {
+      const kvKey = this.toKVKey(`doc:${key}`);
+      const raw = await this.kv.get(kvKey, { type: "json" });
+      if (!raw) return null;
+
+      const envelope = raw as KVResponseEnvelope;
+      const now = Date.now();
+
+      if (now > envelope.e) return null;
+
+      const shouldRevalidate = now > envelope.s;
+
+      // Reconstruct Response (decode base64 → binary)
+      const headers = new Headers(envelope.hd);
+      const bodyBuffer = base64ToBuffer(envelope.b);
+      const response = new Response(bodyBuffer, {
+        status: envelope.st,
+        statusText: envelope.stx,
+        headers,
+      });
+
+      // Promote to L1
+      this.promoteResponseToL1(key, envelope);
+
+      return { response, shouldRevalidate };
+    } catch (error) {
+      console.error("[CFCacheStore] KV getResponse failed:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Promote document cache data from KV to L1.
+   * @internal
+   */
+  private promoteResponseToL1(key: string, envelope: KVResponseEnvelope): void {
+    if (!this.waitUntil) return;
+
+    this.waitUntil(async () => {
+      try {
+        const now = Date.now();
+        const remainingTtl = Math.max(1, Math.floor((envelope.e - now) / 1000));
+        const cache = await this.getCache();
+        const request = this.keyToRequest(`doc:${key}`);
+
+        const headers = new Headers(envelope.hd);
+        headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
+        headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));
+
+        const bodyBuffer = base64ToBuffer(envelope.b);
+        const response = new Response(bodyBuffer, {
+          status: envelope.st,
+          statusText: envelope.stx,
+          headers,
+        });
+
+        await cache.put(request, response);
+      } catch (error) {
+        console.error("[CFCacheStore] L1 response promote failed:", error);
+      }
+    });
+  }
+}
+
+// ============================================================================
+// Base64 Helpers (binary-safe response body encoding for KV)
+// ============================================================================
+
+/** Encode ArrayBuffer to base64 string. */
+function bufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+/** Decode base64 string to ArrayBuffer. */
+function base64ToBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
 }

package/src/cache/cf/index.ts

@@ -10,7 +10,11 @@
  */
 
 // Public API
-export { CFCacheStore, type CFCacheStoreOptions } from "./cf-cache-store.js";
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  type KVNamespace,
+} from "./cf-cache-store.js";
 
 // Header constants for debugging and inspection
 export {