@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

package/src/cache/cf/index.ts

@@ -1,25 +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";
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
+  type KVNamespace,
+} from "./cf-cache-store.js";
 
-// Header constants for debugging and inspection
 export {
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
 } from "./cf-cache-store.js";
 
-// Internal exports (re-exported for backwards compatibility, marked @internal in source)
 export {
-  type CacheStatus,
-  MAX_REVALIDATION_INTERVAL,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
 } from "./cf-cache-store.js";

package/src/cache/document-cache.ts

@@ -12,22 +12,25 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { getRequestContext } from "../server/request-context.js";
+import { hasPerClientSignal } from "../browser/cookie-name.js";
+import {
+  getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
 
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Header indicating cache status for debugging */
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
-/**
- * Simple hash function for segment IDs.
- * Creates a short, deterministic hash to differentiate cache keys
- * based on which segments the client already has.
- */
+function collectRequestTags(
+  requestCtx: RequestContext | undefined,
+): string[] | undefined {
+  const tags = requestCtx?._requestTags;
+  return tags && tags.size > 0 ? [...tags] : undefined;
+}
+
 function hashSegmentIds(segmentIds: string): string {
   if (!segmentIds) return "";
 
@@ -36,12 +39,9 @@ function hashSegmentIds(segmentIds: string): string {
     const char = segmentIds.charCodeAt(i);
     hash = ((hash << 5) - hash + char) | 0;
   }
-  // Convert to base36 for shorter string, take absolute value
   return Math.abs(hash).toString(36);
 }
 
-// ============================================================================
-// Cache Control Parsing
 // ============================================================================
 
 interface CacheDirectives {
@@ -55,6 +55,16 @@ interface CacheDirectives {
 function parseCacheControl(header: string | null): CacheDirectives | null {
   if (!header) return null;
 
+  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
+  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
+  // The document cache is a shared edge store, so refuse both regardless of any
+  // s-maxage / stale-while-revalidate also present. Match standalone directive
+  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
+  // substring, so a value containing "private" cannot false-veto.
+  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage
@@ -86,6 +96,16 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     return null;
   }
 
+  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
+  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
+  // loader set) would be replayed to every client on a hit — pinning them to
+  // one value and even rolling a rotated client back to a prior one. The
+  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
+  // would suppress invalidation for every replayed client. Refuse both.
+  if (hasPerClientSignal(response.headers)) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
@@ -204,18 +224,24 @@ export function createDocumentCacheMiddleware<TEnv = any>(
   ): Promise<Response> {
     const url = ctx.url;
 
+    // Use the original request URL for _rsc* param detection and cache key
+    // differentiation. ctx.url is stripped of _rsc* params by the middleware
+    // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
+    // are not visible on ctx.url in production.
+    const rawUrl = new URL(ctx.request.url);
+
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
       return next();
     }
 
     // Skip RSC action requests (mutations shouldn't be cached)
-    if (url.searchParams.has("_rsc_action")) {
+    if (rawUrl.searchParams.has("_rsc_action")) {
       return next();
     }
 
     // Skip loader requests (have their own caching)
-    if (url.searchParams.has("_rsc_loader")) {
+    if (rawUrl.searchParams.has("_rsc_loader")) {
       return next();
     }
 
@@ -241,9 +267,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // Determine request type for cache key differentiation
-    const isPartial = url.searchParams.has("_rsc_partial");
-    const typeLabel = isPartial ? "RSC" : "HTML";
+    // Determine request type for cache key differentiation.
+    // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
+    // detection. Full-document RSC fetches must not share the HTML cache slot.
+    const isPartial = rawUrl.searchParams.has("_rsc_partial");
+    const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
+    const typeLabel = isRscRequest ? "RSC" : "HTML";
 
     // Track whether next() has been called so the catch block knows
     // whether it is safe to fall through to the handler.
@@ -254,10 +283,10 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // gracefully to the origin handler instead of rejecting the request.
       // This is a deliberate fail-open-to-origin policy: the fallback is
       // "serve uncached from origin", not "use a different cache key".
-      const clientSegments = url.searchParams.get("_rsc_segments") || "";
+      const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
       const segmentHash =
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
-      const typeSuffix = isPartial ? ":rsc" : ":html";
+      const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
       let searchSuffix = "";
       if (!keyGenerator) {
@@ -293,17 +322,26 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             const fresh = await next();
             const directives = shouldCacheResponse(fresh);
 
-            if (directives) {
+            if (directives && fresh.body) {
+              // Background revalidation: nothing streams to a client, so drain
+              // the fresh render fully before snapshotting tags (same
+              // render-complete barrier as the miss path).
+              const body = await new Response(fresh.body).arrayBuffer();
               await store.putResponse!(
                 cacheKey,
-                fresh,
+                new Response(body, fresh),
                 directives.sMaxAge!,
                 directives.staleWhileRevalidate,
+                collectRequestTags(requestCtx),
               );
               log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
             }
           } catch (error) {
-            console.error(`[DocumentCache] Revalidation failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] revalidation",
+            );
           }
         });
 
@@ -336,14 +374,27 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         // Clone response for caching (non-blocking)
         runBackground(requestCtx, async () => {
           try {
+            // Drain the cache copy fully BEFORE snapshotting tags. Tags from
+            // Suspense-streamed "use cache"/cacheTag and loaders are recorded as
+            // each value resolves during the RSC/HTML render, which completes
+            // only when the stream ends - the handler-settlement barrier is too
+            // early. Buffering the body (the client streams the other tee branch,
+            // unaffected) is the render-complete barrier that keeps the cached
+            // body and its tag set consistent.
+            const body = await new Response(cacheStream).arrayBuffer();
             await store.putResponse!(
               cacheKey,
-              new Response(cacheStream, originalResponse),
+              new Response(body, originalResponse),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
+              collectRequestTags(requestCtx),
             );
           } catch (error) {
-            console.error(`[DocumentCache] Cache write failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] cache write",
+            );
           }
         });
 
@@ -356,7 +407,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // No cache headers - pass through
       return originalResponse;
     } catch (error) {
-      console.error(`[DocumentCache] Error:`, error);
+      reportCacheError(error, "cache-read", "[DocumentCache] middleware");
       if (handlerCalled) {
         // Post-handler failure (e.g. body.tee()): do not call next() again
         // as that would re-run handler side effects.

package/src/cache/handle-snapshot.ts

@@ -9,6 +9,69 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
+import { serializeResult, deserializeResult } from "./segment-codec.js";
+
+const HANDLE_ENCODE_TIMEOUT_MS = 5000;
+
+type HandleRecord = Record<string, SegmentHandleData>;
+
+function hasHandleData(handles: HandleRecord): boolean {
+  for (const segId in handles) {
+    for (const _ in handles[segId]) return true;
+  }
+  return false;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout), ms);
+  });
+  return Promise.race([
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        return v;
+      },
+      (e) => {
+        clearTimeout(timer);
+        throw e;
+      },
+    ),
+    timeout,
+  ]);
+}
+
+export async function encodeHandles(handles: HandleRecord): Promise<string> {
+  if (!hasHandleData(handles)) return "";
+  return encodeHandleValue(handles);
+}
+
+export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
+  return decodeHandleValue<HandleRecord>(encoded);
+}
+
+export async function encodeHandleValue(value: unknown): Promise<string> {
+  const encoded = await withTimeout(
+    serializeResult(value),
+    HANDLE_ENCODE_TIMEOUT_MS,
+    null,
+  );
+  return encoded ?? "";
+}
+
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
+  try {
+    return await deserializeResult<T>(encoded);
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Capture handle data for a set of segments from the handle store.

package/src/cache/index.ts

@@ -1,43 +1,46 @@
-/**
- * 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
- */
-
-// Segment cache store types and implementations
 export type {
   SegmentCacheStore,
-  SegmentCacheProvider,
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
   SerializedSegmentData,
   SegmentHandleData,
-  CacheConfig,
-  CacheConfigOrFactory,
 } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
-// Cloudflare cache store
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
+  type KVNamespace,
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
 } from "./cf/index.js";
 
-// Cache scope
+export {
+  VercelCacheStore,
+  type VercelCacheStoreOptions,
+  type VercelRuntimeCache,
+  type VercelCacheDebug,
+  type VercelCacheReadDebugEvent,
+  type VercelCacheReadOutcome,
+  VERCEL_MAX_ITEM_BYTES,
+  VERCEL_MAX_TAGS_PER_ITEM,
+  VERCEL_MAX_TAG_BYTES,
+} from "./vercel/index.js";
+
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
-// Document-level cache middleware
 export {
   createDocumentCacheMiddleware,
   type DocumentCacheOptions,
 } from "./document-cache.js";
+
+export type { CacheErrorCategory } from "./cache-error.js";