@ivogt/rsc-router 0.0.0-experimental.1

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

@@ -0,0 +1,361 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  CFCacheStore,
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+} from "../cf-cache-store";
+import type { CachedEntryData } from "../../types";
+
+// ============================================================================
+// Mock Cloudflare Cache API
+// ============================================================================
+
+class MockCache {
+  private store = new Map<string, Response>();
+
+  async match(request: Request): Promise<Response | undefined> {
+    return this.store.get(request.url)?.clone();
+  }
+
+  async put(request: Request, response: Response): Promise<void> {
+    this.store.set(request.url, response.clone());
+  }
+
+  async delete(request: Request): Promise<boolean> {
+    return this.store.delete(request.url);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+class MockCaches {
+  private caches = new Map<string, MockCache>();
+  private _default = new MockCache();
+
+  async open(name: string): Promise<MockCache> {
+    if (!this.caches.has(name)) {
+      this.caches.set(name, new MockCache());
+    }
+    return this.caches.get(name)!;
+  }
+
+  get default(): MockCache {
+    return this._default;
+  }
+
+  clear(): void {
+    this._default.clear();
+    this.caches.forEach((cache) => cache.clear());
+    this.caches.clear();
+  }
+}
+
+// Install mock globally
+const mockCaches = new MockCaches();
+(globalThis as any).caches = mockCaches;
+
+// ============================================================================
+// Test Data
+// ============================================================================
+
+const createTestData = (): CachedEntryData => ({
+  segments: [
+    {
+      encoded: "test-component",
+      metadata: {
+        id: "test-segment",
+        type: "route",
+        namespace: "test",
+        index: 0,
+        params: {},
+      },
+    },
+  ],
+  handles: {},
+  expiresAt: Date.now() + 60000,
+});
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("CFCacheStore", () => {
+  beforeEach(() => {
+    mockCaches.clear();
+    vi.useFakeTimers();
+  });
+
+  describe("constructor", () => {
+    it("should use default namespace and baseUrl", () => {
+      const store = new CFCacheStore();
+      expect(store).toBeDefined();
+    });
+
+    it("should accept custom options", () => {
+      const store = new CFCacheStore({
+        namespace: "custom-cache",
+        baseUrl: "https://custom.internal/",
+        defaults: { ttl: 120, swr: 600 },
+      });
+      expect(store.defaults).toEqual({ ttl: 120, swr: 600 });
+    });
+
+    it("should accept waitUntil function", () => {
+      const waitUntil = vi.fn();
+      const store = new CFCacheStore({ waitUntil });
+      expect(store).toBeDefined();
+    });
+  });
+
+  describe("get/set", () => {
+    it("should return null for missing key", async () => {
+      const store = new CFCacheStore();
+      const result = await store.get("missing-key");
+      expect(result).toBeNull();
+    });
+
+    it("should store and retrieve data", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+      const result = await store.get("test-key");
+
+      expect(result).not.toBeNull();
+      expect(result!.data).toEqual(data);
+      expect(result!.shouldRevalidate).toBe(false);
+    });
+
+    it("should set Cache-Control header with TTL", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      // Uses caches.default by default
+      const cache = mockCaches.default;
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=60");
+    });
+
+    it("should extend TTL with SWR window", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60, 300);
+
+      const cache = mockCaches.default;
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=360");
+    });
+
+    it("should use store defaults for SWR if not provided", async () => {
+      const store = new CFCacheStore({ defaults: { swr: 120 } });
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      const cache = mockCaches.default;
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=180");
+    });
+
+    it("should use named cache when namespace is provided", async () => {
+      const store = new CFCacheStore({ namespace: "custom-cache" });
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      const cache = await mockCaches.open("custom-cache");
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      expect(response?.headers.get("Cache-Control")).toBe("public, max-age=60");
+    });
+
+    it("should use waitUntil for non-blocking writes when provided", async () => {
+      const waitUntil = vi.fn();
+      const store = new CFCacheStore({ waitUntil });
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      expect(waitUntil).toHaveBeenCalledTimes(1);
+      expect(waitUntil).toHaveBeenCalledWith(expect.any(Function));
+
+      // Execute the waitUntil callback
+      const callback = waitUntil.mock.calls[0][0];
+      await callback();
+
+      // Now the entry should be in cache
+      const result = await store.get("test-key");
+      expect(result).not.toBeNull();
+    });
+  });
+
+  describe("staleness headers", () => {
+    it("should set stale-at header based on TTL", async () => {
+      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
+
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      const cache = mockCaches.default;
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      const staleAt = Number(response?.headers.get(CACHE_STALE_AT_HEADER));
+      const expectedStaleAt = Date.now() + 60 * 1000;
+
+      expect(staleAt).toBe(expectedStaleAt);
+    });
+
+    it("should set status header to HIT", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      const cache = mockCaches.default;
+      const request = new Request("https://rsc-cache.internal.com/test-key");
+      const response = await cache.match(request);
+
+      expect(response?.headers.get(CACHE_STATUS_HEADER)).toBe("HIT");
+    });
+  });
+
+  describe("staleness detection and atomic revalidation", () => {
+    it("should return shouldRevalidate=false for fresh entries", async () => {
+      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
+
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+
+      // Still fresh
+      vi.advanceTimersByTime(30 * 1000);
+
+      const result = await store.get("test-key");
+      expect(result?.shouldRevalidate).toBe(false);
+    });
+
+    it("should return shouldRevalidate=true and atomically mark REVALIDATING for stale entries", async () => {
+      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
+
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60, 300);
+
+      // Past TTL but within SWR window
+      vi.advanceTimersByTime(120 * 1000);
+
+      // First get should return shouldRevalidate=true and mark as REVALIDATING
+      const result = await store.get("test-key");
+      expect(result?.shouldRevalidate).toBe(true);
+
+      // Verify the entry is now marked as REVALIDATING
+      const cache = mockCaches.default;
+      const request = new Request(
+        "https://rsc-cache.internal.com/" + encodeURIComponent("test-key")
+      );
+      const response = await cache.match(request);
+      expect(response?.headers.get(CACHE_STATUS_HEADER)).toBe("REVALIDATING");
+    });
+
+    it("should return shouldRevalidate=false when already REVALIDATING", async () => {
+      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
+
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60, 300);
+
+      // Make it stale
+      vi.advanceTimersByTime(120 * 1000);
+
+      // First get - atomically marks as REVALIDATING
+      const result1 = await store.get("test-key");
+      expect(result1?.shouldRevalidate).toBe(true);
+
+      // Second get - already REVALIDATING, should not trigger again
+      const result2 = await store.get("test-key");
+      expect(result2?.shouldRevalidate).toBe(false);
+    });
+
+    it("should prevent thundering herd with sequential requests", async () => {
+      // Note: Real thundering herd prevention relies on CF Cache API's atomic semantics.
+      // This test verifies sequential requests work correctly - first triggers revalidation,
+      // subsequent ones see REVALIDATING status and don't trigger again.
+      vi.setSystemTime(new Date("2024-01-01T00:00:00Z"));
+
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60, 300);
+
+      // Make it stale
+      vi.advanceTimersByTime(120 * 1000);
+
+      // Sequential requests - first triggers revalidation
+      const result1 = await store.get("test-key");
+      expect(result1?.shouldRevalidate).toBe(true);
+      expect(result1?.data).toBeDefined();
+
+      // Subsequent requests see REVALIDATING status
+      const result2 = await store.get("test-key");
+      expect(result2?.shouldRevalidate).toBe(false);
+      expect(result2?.data).toBeDefined();
+
+      const result3 = await store.get("test-key");
+      expect(result3?.shouldRevalidate).toBe(false);
+      expect(result3?.data).toBeDefined();
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete existing entry", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      await store.set("test-key", data, 60);
+      const deleted = await store.delete("test-key");
+
+      expect(deleted).toBe(true);
+
+      const result = await store.get("test-key");
+      expect(result).toBeNull();
+    });
+
+    it("should return false for non-existent entry", async () => {
+      const store = new CFCacheStore();
+      const deleted = await store.delete("missing-key");
+      expect(deleted).toBe(false);
+    });
+  });
+
+  describe("key encoding", () => {
+    it("should handle special characters in keys", async () => {
+      const store = new CFCacheStore();
+      const data = createTestData();
+
+      const key = "route:products/category=electronics&page=1";
+      await store.set(key, data, 60);
+
+      const result = await store.get(key);
+      expect(result).not.toBeNull();
+      expect(result!.data).toEqual(data);
+    });
+  });
+});

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

@@ -0,0 +1,274 @@
+/// <reference path="../../vite/version.d.ts" />
+/**
+ * Cloudflare Edge Cache Store
+ *
+ * Production cache store using Cloudflare's Cache API.
+ * Handles SWR atomically - get() checks staleness and marks REVALIDATING in one operation.
+ *
+ * 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
+ * - Non-blocking writes via waitUntil
+ */
+
+import type {
+  SegmentCacheStore,
+  CachedEntryData,
+  CacheDefaults,
+  CacheGetResult,
+} from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+import { VERSION } from "rsc-router:version";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Header storing timestamp when entry becomes stale */
+export const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
+
+/** Header storing cache status: HIT | REVALIDATING */
+export const CACHE_STATUS_HEADER = "x-edge-cache-status";
+
+/**
+ * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
+ * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
+ * @internal
+ */
+export const MAX_REVALIDATION_INTERVAL = 30;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CFCacheStoreOptions<TEnv = unknown> {
+  /**
+   * Cache namespace. If not provided, uses caches.default (recommended).
+   * Only set this if you need isolated cache storage.
+   */
+  namespace?: string;
+
+  /** Base URL for cache keys (default: 'https://rsc-cache.internal.com/') */
+  baseUrl?: string;
+
+  /** Default cache options */
+  defaults?: CacheDefaults;
+
+  /**
+   * waitUntil function from request's ExecutionContext.
+   * Used for non-blocking cache writes.
+   */
+  waitUntil?: (fn: () => Promise<void>) => void;
+
+  /**
+   * Cache version string override. When this changes, all cached entries are
+   * effectively invalidated (new keys won't match old entries).
+   *
+   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+   * Only set this if you need a custom versioning strategy.
+   */
+  version?: string;
+
+  /**
+   * Custom key generator applied to all cache operations.
+   * Receives the full RequestContext (including env) and the default-generated key.
+   * Return value becomes the final cache key (unless route overrides with `key` option).
+   *
+   * @example Using headers for user segmentation
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
+   *   return `${segment}:${defaultKey}`;
+   * }
+   * ```
+   *
+   * @example Using env bindings for multi-region
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const region = ctx.env.REGION || 'us';
+   *   return `${region}:${defaultKey}`;
+   * }
+   * ```
+   *
+   * @example Using cookies for locale-aware caching
+   * ```typescript
+   * keyGenerator: (ctx, defaultKey) => {
+   *   const locale = ctx.cookie('locale') || 'en';
+   *   return `${locale}:${defaultKey}`;
+   * }
+   * ```
+   */
+  keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    defaultKey: string
+  ) => string | Promise<string>;
+}
+
+/**
+ * Cache status values for the x-edge-cache-status header.
+ * @internal
+ */
+export type CacheStatus = "HIT" | "REVALIDATING";
+
+// ============================================================================
+// CFCacheStore Implementation
+// ============================================================================
+
+export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+  readonly defaults?: CacheDefaults;
+  readonly keyGenerator?: (
+    ctx: RequestContext<TEnv>,
+    defaultKey: string
+  ) => string | Promise<string>;
+
+  private readonly namespace?: string;
+  private readonly baseUrl: string;
+  private readonly waitUntil?: (fn: () => Promise<void>) => void;
+  private readonly version?: string;
+
+  constructor(options: CFCacheStoreOptions<TEnv> = {}) {
+    this.namespace = options.namespace;
+    this.baseUrl = options.baseUrl ?? "https://rsc-cache.internal.com/";
+    this.defaults = options.defaults;
+    this.waitUntil = options.waitUntil;
+    this.version = options.version ?? VERSION;
+    this.keyGenerator = options.keyGenerator;
+  }
+
+  /**
+   * Get the cache instance - uses caches.default unless namespace is specified.
+   * @internal
+   */
+  private getCache(): Cache | Promise<Cache> {
+    if (this.namespace) {
+      return caches.open(this.namespace);
+    }
+    return caches.default;
+  }
+
+  /**
+   * Get cached entry data by key.
+   *
+   * Handles SWR atomically:
+   * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
+   * - If already REVALIDATING (and recent), returns shouldRevalidate: false
+   * - If fresh, returns shouldRevalidate: false
+   *
+   * The atomic mark prevents thundering herd - only first request triggers revalidation.
+   */
+  async get(key: string): Promise<CacheGetResult | null> {
+    try {
+      const cache = await this.getCache();
+      const request = this.keyToRequest(key);
+      const response = await cache.match(request);
+
+      if (!response) {
+        return null;
+      }
+
+      // Read status headers
+      const status = response.headers.get(CACHE_STATUS_HEADER);
+      const age = Number(response.headers.get("age") ?? "0");
+      const staleAt = Number(response.headers.get(CACHE_STALE_AT_HEADER) ?? "0");
+
+      const isStale = staleAt > 0 && Date.now() > staleAt;
+      const isRevalidating = status === "REVALIDATING" && age < MAX_REVALIDATION_INTERVAL;
+
+      // Case 1: Fresh or already being revalidated - just return data
+      if (!isStale || isRevalidating) {
+        const data = (await response.json()) as CachedEntryData;
+        return { data, shouldRevalidate: false };
+      }
+
+      // Case 2: Stale and needs revalidation - atomically mark REVALIDATING
+      const [b1, b2] = response.body!.tee();
+
+      const headers = new Headers(response.headers);
+      headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+
+      // Blocking write - must complete before returning to prevent race
+      await cache.put(
+        request,
+        new Response(b1, { status: response.status, headers })
+      );
+
+      const data = (await new Response(b2).json()) as CachedEntryData;
+      return { data, shouldRevalidate: true };
+    } catch (error) {
+      console.error("[CFCacheStore] get failed:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Store entry data with TTL and optional SWR window.
+   * Uses waitUntil for non-blocking write when available.
+   */
+  async set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    swr?: number
+  ): Promise<void> {
+    try {
+      const cache = await this.getCache();
+      const request = this.keyToRequest(key);
+
+      // Extended TTL covers SWR window
+      const swrWindow = swr ?? this.defaults?.swr ?? 0;
+      const totalTtl = ttl + swrWindow;
+      const staleAt = Date.now() + ttl * 1000;
+
+      const response = new Response(JSON.stringify(data), {
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": `public, max-age=${totalTtl}`,
+          [CACHE_STALE_AT_HEADER]: String(staleAt),
+          [CACHE_STATUS_HEADER]: "HIT",
+        },
+      });
+
+      const putPromise = cache.put(request, response);
+
+      if (this.waitUntil) {
+        // Non-blocking write
+        this.waitUntil(async () => {
+          await putPromise;
+        });
+      } else {
+        // Blocking fallback
+        await putPromise;
+      }
+    } catch (error) {
+      console.error("[CFCacheStore] set failed:", error);
+    }
+  }
+
+  /**
+   * Delete a cached entry
+   */
+  async delete(key: string): Promise<boolean> {
+    try {
+      const cache = await this.getCache();
+      return await cache.delete(this.keyToRequest(key));
+    } catch (error) {
+      console.error("[CFCacheStore] delete failed:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Convert string key to Request object for CF Cache API.
+   * Includes version in URL if specified (for cache invalidation on code changes).
+   * @internal
+   */
+  private keyToRequest(key: string): Request {
+    const encodedKey = encodeURIComponent(key);
+    // Include version in URL path to invalidate cache when version changes
+    const versionPath = this.version ? `v/${this.version}/` : "";
+    return new Request(`${this.baseUrl}${versionPath}${encodedKey}`, {
+      method: "GET",
+    });
+  }
+}

package/src/cache/cf/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Cloudflare Cache Store Exports
+ *
+ * Main export:
+ * - CFCacheStore - Production cache store using Cloudflare's Cache API
+ *
+ * Header constants (for inspection/debugging):
+ * - CACHE_STALE_AT_HEADER - Header containing staleness timestamp
+ * - CACHE_STATUS_HEADER - Header containing HIT/REVALIDATING status
+ */
+
+// Public API
+export { CFCacheStore, type CFCacheStoreOptions } from "./cf-cache-store.js";
+
+// Header constants for debugging and inspection
+export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER } from "./cf-cache-store.js";
+
+// Internal exports (re-exported for backwards compatibility, marked @internal in source)
+export { type CacheStatus, MAX_REVALIDATION_INTERVAL } from "./cf-cache-store.js";

package/src/cache/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Cache Store
+ *
+ * Server-side caching for RSC segments and loader data.
+ *
+ * Main exports for users:
+ * - SegmentCacheStore - Interface for implementing custom cache stores
+ * - MemorySegmentCacheStore - In-memory cache for development/testing
+ * - CFCacheStore - Cloudflare edge cache store for production
+ * - CacheScope / createCacheScope - Request-scoped cache provider
+ */
+
+// Generic cache store types (reserved for future extensibility)
+// These types support caching arbitrary values like Response, Stream, etc.
+// Currently unused - segment caching uses SegmentCacheStore directly.
+export type {
+  CacheStore,
+  CacheEntry,
+  CacheValue,
+  CacheValueType,
+  CachePutOptions,
+  CacheMetadata,
+} from "./types.js";
+
+// Generic memory cache (reserved for future extensibility)
+export { MemoryCacheStore } from "./memory-store.js";
+
+// Segment cache store types and implementations
+export type {
+  SegmentCacheStore,
+  SegmentCacheProvider,
+  CachedEntryData,
+  CachedEntryResult,
+  CacheGetResult,
+  SerializedSegmentData,
+  SegmentHandleData,
+  CacheConfig,
+  CacheConfigOrFactory,
+} from "./types.js";
+
+export { MemorySegmentCacheStore } from "./memory-segment-store.js";
+
+// Cloudflare cache store
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+} from "./cf/index.js";
+
+// Cache scope
+export { CacheScope, createCacheScope } from "./cache-scope.js";