@rangojs/router 0.0.0-experimental.86 → 0.0.0-experimental.87

package/dist/cache/cf/__tests__/cf-cache-store.test.js

@@ -0,0 +1,330 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { CFCacheStore, CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, } from "../cf-cache-store";
+// ============================================================================
+// Mock Cloudflare Cache API
+// ============================================================================
+class MockCache {
+    constructor() {
+        this.store = new Map();
+    }
+    async match(request) {
+        return this.store.get(request.url)?.clone();
+    }
+    async put(request, response) {
+        this.store.set(request.url, response.clone());
+    }
+    async delete(request) {
+        return this.store.delete(request.url);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+class MockCaches {
+    constructor() {
+        this.caches = new Map();
+        this._default = new MockCache();
+    }
+    async open(name) {
+        if (!this.caches.has(name)) {
+            this.caches.set(name, new MockCache());
+        }
+        return this.caches.get(name);
+    }
+    get default() {
+        return this._default;
+    }
+    clear() {
+        this._default.clear();
+        this.caches.forEach((cache) => cache.clear());
+        this.caches.clear();
+    }
+}
+// Install mock globally
+const mockCaches = new MockCaches();
+globalThis.caches = mockCaches;
+// ============================================================================
+// Mock ExecutionContext
+// ============================================================================
+const createMockCtx = () => ({
+    waitUntil: vi.fn((p) => p),
+    passThroughOnException: vi.fn(),
+});
+// ============================================================================
+// Test Data
+// ============================================================================
+const createTestData = () => ({
+    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 require ctx", () => {
+            expect(() => new CFCacheStore({})).toThrow("[CFCacheStore] ExecutionContext (ctx) is required");
+        });
+        it("should accept ctx and custom options", () => {
+            const store = new CFCacheStore({
+                ctx: createMockCtx(),
+                namespace: "custom-cache",
+                baseUrl: "https://custom.internal/",
+                defaults: { ttl: 120, swr: 600 },
+            });
+            expect(store.defaults).toEqual({ ttl: 120, swr: 600 });
+        });
+    });
+    describe("get/set", () => {
+        it("should return null for missing key", async () => {
+            const store = new CFCacheStore({ ctx: createMockCtx() });
+            const result = await store.get("missing-key");
+            expect(result).toBeNull();
+        });
+        it("should store and retrieve data", async () => {
+            const mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            // Execute waitUntil callback
+            await mockCtx.waitUntil.mock.results[0].value;
+            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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60, 300);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx, defaults: { swr: 120 } });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx, namespace: "custom-cache" });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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", async () => {
+            const mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            expect(mockCtx.waitUntil).toHaveBeenCalledTimes(1);
+            expect(mockCtx.waitUntil).toHaveBeenCalledWith(expect.any(Promise));
+            // Wait for the write to complete
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60, 300);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60, 300);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60, 300);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // 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 mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("test-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            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({ ctx: createMockCtx() });
+            const deleted = await store.delete("missing-key");
+            expect(deleted).toBe(false);
+        });
+    });
+    describe("key encoding", () => {
+        it("should handle special characters in keys", async () => {
+            const mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            const key = "route:products/category=electronics&page=1";
+            await store.set(key, data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            const result = await store.get(key);
+            expect(result).not.toBeNull();
+            expect(result.data).toEqual(data);
+        });
+    });
+    describe("baseUrl configuration", () => {
+        it("should use explicit baseUrl when provided", async () => {
+            const mockCtx = createMockCtx();
+            const store = new CFCacheStore({
+                ctx: mockCtx,
+                baseUrl: "https://custom.example.com/",
+            });
+            const data = createTestData();
+            await store.set("custom-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // Verify round-trip works with custom baseUrl
+            const result = await store.get("custom-key");
+            expect(result).not.toBeNull();
+            expect(result.data).toEqual(data);
+        });
+        it("should use fallback when no requestContext available", async () => {
+            // Default behavior when getRequestContext returns null
+            const mockCtx = createMockCtx();
+            const store = new CFCacheStore({ ctx: mockCtx });
+            const data = createTestData();
+            await store.set("fallback-key", data, 60);
+            await mockCtx.waitUntil.mock.results[0].value;
+            // Verify round-trip works with fallback baseUrl
+            const result = await store.get("fallback-key");
+            expect(result).not.toBeNull();
+            expect(result.data).toEqual(data);
+        });
+    });
+});
+//# sourceMappingURL=cf-cache-store.test.js.map

package/dist/cache/cf/__tests__/cf-cache-store.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-cache-store.test.js","sourceRoot":"","sources":["../../../../src/cache/cf/__tests__/cf-cache-store.test.ts"],"names":[],"mappings":"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"}

package/dist/cache/cf/cf-cache-store.d.ts

@@ -0,0 +1,165 @@
+declare global {
+    interface CacheStorage {
+        readonly default: Cache;
+    }
+}
+/**
+ * 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";
+/** Header storing timestamp when entry becomes stale */
+export declare const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
+/** Header storing cache status: HIT | REVALIDATING */
+export declare 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 declare const MAX_REVALIDATION_INTERVAL = 30;
+/**
+ * Cloudflare Workers ExecutionContext (subset we need)
+ */
+export interface ExecutionContext {
+    waitUntil(promise: Promise<any>): void;
+    passThroughOnException(): void;
+}
+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.
+     *
+     * If not provided, derives from request hostname via requestContext:
+     * - Production domains → uses `https://{hostname}/`
+     * - Dev/preview (localhost, workers.dev, pages.dev) → uses internal fallback URL
+     */
+    baseUrl?: string;
+    /** Default cache options */
+    defaults?: CacheDefaults;
+    /**
+     * Cloudflare ExecutionContext for non-blocking cache writes.
+     * Pass the `ctx` from your worker's fetch handler.
+     *
+     * @example
+     * ```typescript
+     * new CFCacheStore({ ctx: env.ctx })
+     * ```
+     */
+    ctx: ExecutionContext;
+    /**
+     * 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";
+export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    private readonly namespace?;
+    private readonly baseUrl;
+    private readonly waitUntil?;
+    private readonly version?;
+    constructor(options: CFCacheStoreOptions<TEnv>);
+    /**
+     * Derive base URL from request hostname via requestContext.
+     * Uses internal fallback for dev/preview environments.
+     * @internal
+     */
+    private deriveBaseUrl;
+    /**
+     * Get the cache instance - uses caches.default unless namespace is specified.
+     * @internal
+     */
+    private getCache;
+    /**
+     * 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.
+     */
+    get(key: string): Promise<CacheGetResult | null>;
+    /**
+     * Store entry data with TTL and optional SWR window.
+     * Uses waitUntil for non-blocking write when available.
+     */
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    /**
+     * Delete a cached entry
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Get a cached Response by key (for document-level caching).
+     * Returns the response and whether it should be revalidated (SWR).
+     */
+    getResponse(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * Store a Response with TTL and optional SWR window (for document-level caching).
+     */
+    putResponse(key: string, response: Response, ttl: number, swr?: number): Promise<void>;
+    /**
+     * 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;
+}
+//# sourceMappingURL=cf-cache-store.d.ts.map

package/dist/cache/cf/cf-cache-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-cache-store.d.ts","sourceRoot":"","sources":["../../../src/cache/cf/cf-cache-store.ts"],"names":[],"mappings":"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"}