@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/cache/cf/cf-zone-purge.ts

@@ -0,0 +1,101 @@
+// ============================================================================
+// Cloudflare zone purge-by-tag helper
+// ============================================================================
+//
+// Ready-made `tagPurge` implementation for CFCacheStoreOptions: POSTs the
+// Cache-Tags handed over by invalidateTags() to the zone purge endpoint.
+// Kept transport-only (no store coupling) so it is unit-testable with an
+// injected fetch and reusable for onRevalidateTag.
+
+/**
+ * Tags per purge_cache API call. Cloudflare's documented purge-by-tag batch
+ * limit has historically been 30 tags per call (the newer all-plans limits
+ * page quotes 100 operations per request); chunking at 30 stays under both.
+ * @internal
+ */
+export const PURGE_TAGS_PER_CALL = 30;
+
+export interface CloudflareZonePurgeOptions {
+  /** Zone to purge (Cloudflare dashboard -> zone overview -> Zone ID). */
+  zoneId: string;
+  /** API token with the `Zone.Cache Purge` permission for that zone. */
+  apiToken: string;
+  /**
+   * API origin override, mainly for tests/proxies.
+   * Defaults to `https://api.cloudflare.com`.
+   */
+  apiBase?: string;
+  /** fetch override, mainly for tests. Defaults to the global fetch. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Create a purge-by-tag function for {@link CFCacheStoreOptions.tagPurge} (or
+ * `onRevalidateTag`). Chunks the tag list under the per-call API limit and
+ * rejects on any non-success response, so a failed purge surfaces through
+ * `updateTag()` instead of silently leaving L1 stale.
+ *
+ * Purge-by-tag is available on ALL Cloudflare plans (since April 2025), but
+ * account-level purge rate limits apply (Free: 5 calls/min) — keep invalidation
+ * tag batches small and low-frequency on lower plans.
+ */
+export function createCloudflareZonePurge(
+  options: CloudflareZonePurgeOptions,
+): (cacheTags: string[]) => Promise<void> {
+  const { zoneId, apiToken } = options;
+  // Fail at construction, not at the first updateTag(): a store wired with an
+  // unset env var would otherwise report the misconfig only when the first
+  // invalidation rejects — long after deploy.
+  if (typeof zoneId !== "string" || zoneId.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] zoneId is required (Cloudflare dashboard " +
+        "-> zone overview -> Zone ID). Check the env var/secret it is read from.",
+    );
+  }
+  if (typeof apiToken !== "string" || apiToken.length === 0) {
+    throw new Error(
+      "[createCloudflareZonePurge] apiToken is required (an API token with " +
+        "the Zone.Cache Purge permission for the zone). Check the secret it " +
+        "is read from.",
+    );
+  }
+  const apiBase = options.apiBase ?? "https://api.cloudflare.com";
+  const fetchImpl = options.fetch ?? fetch;
+  const endpoint = `${apiBase}/client/v4/zones/${zoneId}/purge_cache`;
+
+  return async (cacheTags: string[]): Promise<void> => {
+    for (let i = 0; i < cacheTags.length; i += PURGE_TAGS_PER_CALL) {
+      const chunk = cacheTags.slice(i, i + PURGE_TAGS_PER_CALL);
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ tags: chunk }),
+      });
+      // The API reports failures both via HTTP status and a success flag.
+      // Require an EXPLICIT success: true — an empty body, an HTML error
+      // page, invalid JSON, or `{}` on a 2xx is NOT a confirmed purge, and
+      // purge mode trusts surviving L1 entries on the strength of this call,
+      // so an unconfirmed purge must reject rather than pass silently.
+      const body = (await response.json().catch(() => null)) as {
+        success?: boolean;
+        errors?: { code?: number; message?: string }[];
+      } | null;
+      if (!response.ok || body?.success !== true) {
+        const detail =
+          body?.errors
+            ?.map((e) => `${e.code ?? "?"}: ${e.message ?? "unknown"}`)
+            .join("; ") ??
+          (response.ok
+            ? `HTTP ${response.status} with a missing/invalid success body`
+            : `HTTP ${response.status}`);
+        throw new Error(
+          `[createCloudflareZonePurge] purge_cache failed for ${chunk.length} ` +
+            `tag(s): ${detail}`,
+        );
+      }
+    }
+  };
+}

package/src/cache/cf/index.ts

@@ -1,19 +1,24 @@
-/**
- * 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
- */
+export {
+  CFCacheStore,
+  type CFCacheStoreOptions,
+  type CFCacheDebug,
+  type CFCacheReadDebugEvent,
+  type KVNamespace,
+} from "./cf-cache-store.js";
 
-// Public API
-export { CFCacheStore, type CFCacheStoreOptions } from "./cf-cache-store.js";
+export {
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+  CACHE_REVALIDATING_AT_HEADER,
+} from "./cf-cache-store.js";
 
-// Header constants for debugging and inspection
-export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER } from "./cf-cache-store.js";
+export {
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
+} 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";
+export {
+  createCloudflareZonePurge,
+  type CloudflareZonePurgeOptions,
+} from "./cf-zone-purge.js";

package/src/cache/document-cache.ts

@@ -1,7 +1,9 @@
 /**
  * Document-Level Cache Middleware
  *
- * Caches full HTTP responses at the edge based on Cache-Control headers.
+ * Caches full HTTP responses in the configured app store based on Cache-Control
+ * headers. A deployment CDN may independently consume the same shared-cache
+ * directives; this middleware itself runs inside the worker/function.
  * Routes opt-in to caching by setting s-maxage or stale-while-revalidate headers.
  *
  * Flow:
@@ -12,20 +14,31 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { getRequestContext } from "../server/request-context.js";
+import { hasPerClientSignal } from "../browser/cookie-name.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
+import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import {
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+} from "../segment-fragments.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 "";
 
@@ -34,12 +47,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 {
@@ -53,6 +63,27 @@ 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 app 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;
+  }
+
+  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
+  // response without successful origin validation. This store's hit path has no
+  // validation step, so serving a stored no-cache response within s-maxage
+  // would hand the client content the origin marked must-revalidate. Refuse to
+  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
+  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
+  // boundary is excluded from the lookahead (unlike private/no-store above).
+  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage
@@ -84,6 +115,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);
 }
@@ -93,32 +134,52 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
 // ============================================================================
 
 /**
- * Add cache status header to response for debugging
+ * Add the cache-status header (HIT/STALE/MISS) to a response.
+ *
+ * The response we get here is always a fresh instance — the store rebuilds a
+ * new Response per getResponse(), and the miss path wraps a fresh Response
+ * around the tee'd body — so mutating its headers in place is safe and avoids
+ * cloning every header + allocating a new Response on every cache hit. Only when
+ * the headers are immutable (a guarded Response rejects set() with a TypeError)
+ * do we fall back to rebuilding the Response with a mutable Headers.
  */
 function addCacheStatusHeader(
   response: Response,
   status: "HIT" | "STALE" | "MISS",
 ): Response {
-  const headers = new Headers(response.headers);
-  headers.set(CACHE_STATUS_HEADER, status);
-
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
+  try {
+    response.headers.set(CACHE_STATUS_HEADER, status);
+    return response;
+  } catch {
+    const headers = new Headers(response.headers);
+    headers.set(CACHE_STATUS_HEADER, status);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
 }
 
 /**
- * Run onResponse callbacks registered on the request context
+ * Drain and run onResponse callbacks registered on the request context.
+ * Mirrors the drain semantics of finalizeResponse() in rsc/helpers.ts:
+ * callbacks are spliced out so they fire at most once per request.
  */
-function runOnResponseCallbacks(
+function drainOnResponseCallbacks(
   response: Response,
-  callbacks: Array<(response: Response) => Response>,
+  requestCtx:
+    | { _onResponseCallbacks: Array<(r: Response) => Response> }
+    | undefined,
 ): Response {
+  if (!requestCtx || requestCtx._onResponseCallbacks.length === 0) {
+    return response;
+  }
+  const callbacks = requestCtx._onResponseCallbacks;
+  requestCtx._onResponseCallbacks = [];
   let result = response;
   for (const callback of callbacks) {
-    result = callback(result);
+    result = callback(result) ?? result;
   }
   return result;
 }
@@ -134,7 +195,13 @@ export interface DocumentCacheOptions<TEnv = any> {
   skipPaths?: string[];
 
   /**
-   * Custom cache key generator
+   * Custom cache key generator.
+   *
+   * Replaces the default `host + pathname + search` key entirely. On a
+   * multi-domain deployment served by one function you MUST include `url.host`
+   * (or an equivalent tenant discriminator) yourself — the default key is
+   * host-namespaced, but a custom generator's output is used verbatim, so
+   * omitting host bleeds one hostname's cached response to another.
    */
   keyGenerator?: (url: URL) => string;
 
@@ -185,9 +252,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
 ): MiddlewareFn<TEnv> {
   const { skipPaths = [], keyGenerator, isEnabled, debug = false } = options;
 
-  const log = debug
-    ? (message: string) => console.log(message)
-    : () => {};
+  const log = debug ? (message: string) => console.log(message) : () => {};
 
   return async function documentCacheMiddleware(
     ctx: MiddlewareContext<TEnv>,
@@ -195,13 +260,26 @@ 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);
+    const isFragmentRecovery =
+      ctx.request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
+
+    // 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();
     }
 
@@ -227,101 +305,188 @@ 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";
 
-    // Generate cache key
-    // For partial requests, include hash of client segments to prevent serving
-    // wrong cached response when navigating from different pages with different layouts
-    const clientSegments = url.searchParams.get("_rsc_segments") || "";
-    const segmentHash = isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
-    const typeSuffix = isPartial ? ":rsc" : ":html";
-    const cacheKey = keyGenerator
-      ? keyGenerator(url) + segmentHash + typeSuffix
-      : `${url.pathname}${segmentHash}${typeSuffix}`;
+    // Track whether next() has been called so the catch block knows
+    // whether it is safe to fall through to the handler.
+    let handlerCalled = false;
 
     try {
+      // Generate cache key inside try so a throwing keyGenerator degrades
+      // 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 = rawUrl.searchParams.get("_rsc_segments") || "";
+      const segmentHash =
+        isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
+      // Fragment envelopes require a capable Rango decoder. Keep that wire
+      // variant out of the context-less/legacy partial slot; this middleware
+      // returns hits before request classification and cannot rely on the
+      // match-time capability gate.
+      const fragmentSuffix =
+        isPartial &&
+        (ctx.request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1" ||
+          isFragmentRecovery)
+          ? ":fragments"
+          : "";
+      const typeSuffix = isRscRequest ? ":rsc" : ":html";
+
+      // Default key rides the shared host-namespaced base (cacheKeyBase) so the
+      // segment tier (cache-scope.ts) and this document tier cannot drift on the
+      // host-namespacing rule -- see the contract on cacheKeyBase.
+      // The keyGenerator branch is left untouched: a consumer-supplied generator
+      // owns its own namespacing (auto-prefixing host would silently change their
+      // existing keys and double any host they already include).
+      const cacheKey = keyGenerator
+        ? keyGenerator(url) + segmentHash + fragmentSuffix + typeSuffix
+        : cacheKeyBase(
+            url.host,
+            url.pathname,
+            url.searchParams,
+            undefined,
+            requestCtx?._searchParamsFilter,
+          ) +
+          segmentHash +
+          fragmentSuffix +
+          typeSuffix;
       // 1. Check cache
-      const cached = await store.getResponse(cacheKey);
+      // Recovery must reach CacheScope's server decoder so it can evict the bad
+      // segment. Treat it as a miss, then let the ordinary write path replace
+      // the corrupt fragment-capable response with the valid fallback bytes.
+      const cached = isFragmentRecovery
+        ? null
+        : await store.getResponse(cacheKey);
 
       if (cached && cached.response.status === 200) {
         if (!cached.shouldRevalidate) {
           // Fresh hit - return immediately
           log(`[DocumentCache] HIT ${typeLabel}: ${url.pathname}`);
-          let response = addCacheStatusHeader(cached.response, "HIT");
-          // Run onResponse callbacks even for cache hits
-          if (requestCtx && requestCtx._onResponseCallbacks.length > 0) {
-            response = runOnResponseCallbacks(
-              response,
-              requestCtx._onResponseCallbacks,
-            );
-          }
-          return response;
+          return drainOnResponseCallbacks(
+            addCacheStatusHeader(cached.response, "HIT"),
+            requestCtx,
+          );
         }
 
         // Stale hit - return cached response, revalidate in background
-        log(`[DocumentCache] STALE ${typeLabel}: ${url.pathname} (revalidating)`);
-
-        if (requestCtx) {
-          requestCtx.waitUntil(async () => {
-            try {
-              const fresh = await next();
-              const directives = shouldCacheResponse(fresh);
-
-              if (directives) {
-                await store.putResponse!(
-                  cacheKey,
-                  fresh,
-                  directives.sMaxAge!,
-                  directives.staleWhileRevalidate,
-                );
-                log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
-              }
-            } catch (error) {
-              console.error(`[DocumentCache] Revalidation failed:`, error);
-            }
-          });
-        }
+        log(
+          `[DocumentCache] STALE ${typeLabel}: ${url.pathname} (revalidating)`,
+        );
 
-        let response = addCacheStatusHeader(cached.response, "STALE");
-        // Run onResponse callbacks even for stale cache hits
-        if (requestCtx && requestCtx._onResponseCallbacks.length > 0) {
-          response = runOnResponseCallbacks(
-            response,
-            requestCtx._onResponseCallbacks,
-          );
-        }
-        return response;
+        runBackground(requestCtx, async () => {
+          try {
+            // Re-establish the request-context ALS around the whole background
+            // task: next() re-runs the full handler pipeline, and on workerd a
+            // waitUntil task runs detached from the request's I/O context, so a
+            // handler/component reading getRequestContext() would otherwise
+            // throw. Same fix as the route-level/use-cache background
+            // revalidation paths. The rango.background span (kind=
+            // document-revalidation) wraps the re-render AND the store write so
+            // the task's spans — the re-run's own rango.* set and the drain/put
+            // platform spans — nest under one explanatory parent instead of
+            // dangling under the ended foreground phases. Running the put
+            // inside the ALS matches the MISS path, where putResponse already
+            // executes within the foreground request context.
+            await runWithRequestContext(requestCtx, () =>
+              observePhase(
+                PHASES.background("document-revalidation"),
+                async () => {
+                  const fresh = await next();
+                  const directives = shouldCacheResponse(fresh);
+
+                  if (!directives || !fresh.body) return;
+
+                  // 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,
+                    new Response(body, fresh),
+                    directives.sMaxAge!,
+                    directives.staleWhileRevalidate,
+                    collectRequestTags(requestCtx),
+                  );
+                  log(
+                    `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
+                  );
+                },
+              ),
+            );
+          } catch (error) {
+            // Pass requestCtx explicitly: this runs in a detached waitUntil task
+            // where the ALS context is gone, so onError only fires if we hand it
+            // the captured context (reportCacheError falls back to _getRequestContext
+            // otherwise, which is null here).
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] revalidation",
+              requestCtx,
+            );
+          }
+        });
+
+        return drainOnResponseCallbacks(
+          addCacheStatusHeader(cached.response, "STALE"),
+          requestCtx,
+        );
       }
 
       // 2. Cache miss - run handler
+      handlerCalled = true;
       const originalResponse = await next();
 
       // 3. Cache if response has appropriate headers
       const directives = shouldCacheResponse(originalResponse);
 
       if (directives) {
-        log(`[DocumentCache] MISS ${typeLabel}: ${url.pathname} (caching with s-maxage=${directives.sMaxAge})`);
+        log(
+          `[DocumentCache] MISS ${typeLabel}: ${url.pathname} (caching with s-maxage=${directives.sMaxAge})`,
+        );
+
+        // If the response has no body (e.g., 200 with empty body), skip caching
+        if (!originalResponse.body) {
+          return originalResponse;
+        }
 
         // Tee the body so we can return one stream and cache the other
-        const [returnStream, cacheStream] = originalResponse.body!.tee();
+        const [returnStream, cacheStream] = originalResponse.body.tee();
 
         // Clone response for caching (non-blocking)
-        if (requestCtx) {
-          requestCtx.waitUntil(async () => {
-            try {
-              await store.putResponse!(
-                cacheKey,
-                new Response(cacheStream, originalResponse),
-                directives.sMaxAge!,
-                directives.staleWhileRevalidate,
-              );
-            } catch (error) {
-              console.error(`[DocumentCache] Cache write failed:`, error);
-            }
-          });
-        }
+        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(body, originalResponse),
+              directives.sMaxAge!,
+              directives.staleWhileRevalidate,
+              collectRequestTags(requestCtx),
+            );
+          } catch (error) {
+            // Detached waitUntil task — pass the captured requestCtx so onError
+            // fires even though the ALS context is gone (see the revalidation
+            // catch above).
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] cache write",
+              requestCtx,
+            );
+          }
+        });
 
         return addCacheStatusHeader(
           new Response(returnStream, originalResponse),
@@ -332,8 +497,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // No cache headers - pass through
       return originalResponse;
     } catch (error) {
-      console.error(`[DocumentCache] Error:`, error);
-      // On any cache error, fall through to handler
+      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.
+        throw error;
+      }
+      // Pre-handler failure (cache lookup): degrade gracefully to origin
       return next();
     }
   };