vinext 0.0.27 → 0.0.29

package/dist/cloudflare/kv-cache-handler.d.ts

@@ -28,6 +28,7 @@
  *   }
  */
 import type { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "../shims/cache.js";
+import { type ExecutionContextLike } from "../shims/request-context.js";
 interface KVNamespace {
     get(key: string, options?: {
         type?: string;
@@ -53,31 +54,41 @@ interface KVNamespace {
         cursor?: string;
     }>;
 }
-/**
- * Minimal ExecutionContext interface for Cloudflare Workers.
- * Background KV operations (cleanup deletes, cache writes) are registered
- * with ctx.waitUntil() so they are not killed when the Response is returned.
- *
- * The preferred way to supply ctx is via runWithExecutionContext() in the
- * worker entry (see vinext/shims/request-context). The constructor option
- * is kept as a fallback for callers that set it explicitly.
- */
-interface ExecutionContext {
-    waitUntil(promise: Promise<unknown>): void;
-}
 export declare class KVCacheHandler implements CacheHandler {
     private kv;
     private prefix;
     private ctx;
+    private ttlSeconds;
+    /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
+    private _tagCache;
+    /** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */
+    private _tagCacheTtl;
     constructor(kvNamespace: KVNamespace, options?: {
         appPrefix?: string;
-        ctx?: ExecutionContext;
+        ctx?: ExecutionContextLike;
+        ttlSeconds?: number;
+        /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
+        tagCacheTtlMs?: number;
     });
     get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
     set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
     revalidateTag(tags: string | string[], _durations?: {
         expire?: number;
     }): Promise<void>;
+    /**
+     * Clear the in-memory tag cache for this KVCacheHandler instance.
+     *
+     * Note: KVCacheHandler instances are typically reused across multiple
+     * requests in a Cloudflare Worker. The `_tagCache` is intentionally
+     * cross-request — it reduces redundant KV reads for recently-seen tags
+     * across all requests hitting the same isolate, bounded by `tagCacheTtlMs`
+     * (default 5s). vinext does NOT call this method per request.
+     *
+     * This is an opt-in escape hatch for callers that need stricter isolation
+     * (e.g., tests, or environments with custom lifecycle management).
+     * Callers that require per-request isolation should either construct a
+     * fresh KVCacheHandler per request or invoke this method explicitly.
+     */
     resetRequestCache(): void;
     /**
      * Fire a KV delete in the background.
@@ -89,11 +100,11 @@ export declare class KVCacheHandler implements CacheHandler {
      */
     private _deleteInBackground;
     /**
-     * Fire a KV put in the background.
-     * Same ALS ctx → constructor ctx → fire-and-forget precedence as
-     * `_deleteInBackground`.
+     * Execute a KV put and return the promise so callers can await completion.
+     * Also registers with ctx.waitUntil() so the Workers runtime keeps the
+     * isolate alive even if the caller does not await the returned promise.
      */
-    private _putInBackground;
+    private _put;
 }
 export {};
 //# sourceMappingURL=kv-cache-handler.d.ts.map

package/dist/cloudflare/kv-cache-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kv-cache-handler.d.ts","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAIhG,UAAU,WAAW;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAChF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,cAAc,EAC5C,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAC5E,IAAI,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAC;QAClE,aAAa,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;;;;;;;GAQG;AACH,UAAU,gBAAgB;IACxB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5C;AAiCD,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAA+B;gBAE9B,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,gBAAgB,CAAA;KAAE;IAMxF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAmEzF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,GAAG,IAAI,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IA8DV,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7F,iBAAiB,IAAI,IAAI;IAIzB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAYzB"}
+{"version":3,"file":"kv-cache-handler.d.ts","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAA8B,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGpG,UAAU,WAAW;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAChF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,cAAc,EAC5C,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GACvE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAC5E,IAAI,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAC;QAClE,aAAa,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAsCD,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAmC;IAC9C,OAAO,CAAC,UAAU,CAAS;IAE3B,wFAAwF;IACxF,OAAO,CAAC,SAAS,CAA+D;IAChF,0EAA0E;IAC1E,OAAO,CAAC,YAAY,CAAS;gBAG3B,WAAW,EAAE,WAAW,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,oBAAoB,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,uEAAuE;QACvE,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuGzF,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,GAAG,IAAI,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IAiEV,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB7F;;;;;;;;;;;;;OAaG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;OAIG;IACH,OAAO,CAAC,IAAI;CAQb"}

package/dist/cloudflare/kv-cache-handler.js

@@ -27,6 +27,7 @@
  *     ]
  *   }
  */
+import { Buffer } from "node:buffer";
 import { getRequestExecutionContext } from "../shims/request-context.js";
 /** Key prefix for tag invalidation timestamps. */
 const TAG_PREFIX = "__tag:";
@@ -34,6 +35,8 @@ const TAG_PREFIX = "__tag:";
 const ENTRY_PREFIX = "cache:";
 /** Max tag length to prevent KV key abuse. */
 const MAX_TAG_LENGTH = 256;
+/** Matches a valid base64 string (standard alphabet with optional padding). */
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 /**
  * Validate a cache tag. Returns null if invalid.
  * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a
@@ -42,9 +45,11 @@ const MAX_TAG_LENGTH = 256;
 function validateTag(tag) {
     if (typeof tag !== "string" || tag.length === 0 || tag.length > MAX_TAG_LENGTH)
         return null;
-    // Block control characters, path separators, and KV-special characters.
+    // Block control characters and reserved separators used in our own key format.
+    // Slash is allowed because revalidatePath() relies on pathname tags like
+    // "/posts/hello" and "_N_T_/posts/hello".
     // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags
-    if (/[\x00-\x1f/\\:]/.test(tag))
+    if (/[\x00-\x1f\\:]/.test(tag))
         return null;
     return tag;
 }
@@ -52,10 +57,17 @@ export class KVCacheHandler {
     kv;
     prefix;
     ctx;
+    ttlSeconds;
+    /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
+    _tagCache = new Map();
+    /** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */
+    _tagCacheTtl;
     constructor(kvNamespace, options) {
         this.kv = kvNamespace;
         this.prefix = options?.appPrefix ? `${options.appPrefix}:` : "";
         this.ctx = options?.ctx;
+        this.ttlSeconds = options?.ttlSeconds ?? 30 * 24 * 3600;
+        this._tagCacheTtl = options?.tagCacheTtlMs ?? 5_000;
     }
     async get(key, _ctx) {
         const kvKey = this.prefix + ENTRY_PREFIX + key;
@@ -88,20 +100,54 @@ export class KVCacheHandler {
                 return null;
             }
         }
-        // Check tag-based invalidation (parallel for lower latency)
+        // Check tag-based invalidation.
+        // Uses a local in-memory cache to avoid redundant KV reads for recently-seen tags.
         if (entry.tags.length > 0) {
-            const tagResults = await Promise.all(entry.tags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)));
-            for (let i = 0; i < entry.tags.length; i++) {
-                const tagTime = tagResults[i];
-                if (tagTime) {
-                    const tagTimestamp = Number(tagTime);
-                    if (Number.isNaN(tagTimestamp) || tagTimestamp >= entry.lastModified) {
-                        // Tag was invalidated after this entry, or timestamp is corrupted
-                        // — treat as miss to force re-render
+            const now = Date.now();
+            const uncachedTags = [];
+            // First pass: check local cache for each tag.
+            // Delete expired entries to prevent unbounded Map growth in long-lived isolates.
+            for (const tag of entry.tags) {
+                const cached = this._tagCache.get(tag);
+                if (cached && now - cached.fetchedAt < this._tagCacheTtl) {
+                    // Local cache hit — check invalidation inline
+                    if (Number.isNaN(cached.timestamp) || cached.timestamp >= entry.lastModified) {
                         this._deleteInBackground(kvKey);
                         return null;
                     }
                 }
+                else {
+                    // Expired or absent — evict stale entry and re-fetch from KV
+                    if (cached)
+                        this._tagCache.delete(tag);
+                    uncachedTags.push(tag);
+                }
+            }
+            // Second pass: fetch uncached tags from KV in parallel.
+            // Populate the local cache for ALL fetched tags before checking invalidation,
+            // so that KV round-trips are not wasted when an earlier tag triggers an
+            // early return — subsequent get() calls benefit from the already-fetched results.
+            if (uncachedTags.length > 0) {
+                const tagResults = await Promise.all(uncachedTags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)));
+                // Populate cache for all results first, then check for invalidation.
+                // Two-loop structure ensures all tag results are cached even when an
+                // earlier tag would cause an early return — so subsequent get() calls
+                // for entries sharing those tags don't redundantly re-fetch from KV.
+                for (let i = 0; i < uncachedTags.length; i++) {
+                    const tagTime = tagResults[i];
+                    const tagTimestamp = tagTime ? Number(tagTime) : 0;
+                    this._tagCache.set(uncachedTags[i], { timestamp: tagTimestamp, fetchedAt: now });
+                }
+                // Then check for invalidation using the now-cached timestamps
+                for (const tag of uncachedTags) {
+                    const cached = this._tagCache.get(tag);
+                    if (cached.timestamp !== 0) {
+                        if (Number.isNaN(cached.timestamp) || cached.timestamp >= entry.lastModified) {
+                            this._deleteInBackground(kvKey);
+                            return null;
+                        }
+                    }
+                }
             }
         }
         // Check time-based expiry — return stale with cacheState
@@ -157,21 +203,24 @@ export class KVCacheHandler {
             lastModified: Date.now(),
             revalidateAt,
         };
-        // Calculate KV TTL — keep entries well beyond their revalidate window
-        // (10x revalidate period, clamped to 60s–30d) so stale-while-revalidate
-        // can serve stale content while background regeneration happens.
-        let expirationTtl;
-        if (revalidateAt !== null) {
-            const revalidateSeconds = Math.ceil((revalidateAt - Date.now()) / 1000);
-            // Keep in KV for 10x the revalidation period, up to 30 days
-            expirationTtl = Math.min(revalidateSeconds * 10, 30 * 24 * 3600);
-            // KV minimum TTL is 60 seconds
-            expirationTtl = Math.max(expirationTtl, 60);
-        }
-        this._putInBackground(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {
+        // KV TTL is decoupled from the revalidation period.
+        //
+        // Staleness (when to trigger background regen) is tracked by `revalidateAt`
+        // in the stored JSON — not by KV eviction. KV eviction is purely a storage
+        // hygiene mechanism and must never be the reason a stale entry disappears.
+        //
+        // If KV TTL were tied to the revalidate window (e.g. 10x), a page with
+        // revalidate=5 would be evicted after ~50 seconds of no traffic, causing the
+        // next request to block on a fresh render instead of serving stale content.
+        //
+        // Fix: always keep entries for 30 days regardless of revalidate frequency.
+        // Background regen overwrites the key with a fresh entry + new revalidateAt,
+        // so active pages always have something to serve. Entries only disappear after
+        // 30 days of zero traffic, or when explicitly deleted via tag invalidation.
+        const expirationTtl = revalidateAt !== null ? this.ttlSeconds : undefined;
+        return this._put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {
             expirationTtl,
         });
-        return Promise.resolve();
     }
     async revalidateTag(tags, _durations) {
         const tagList = Array.isArray(tags) ? tags : [tags];
@@ -182,9 +231,28 @@ export class KVCacheHandler {
         await Promise.all(validTags.map((tag) => this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {
             expirationTtl: 30 * 24 * 3600,
         })));
+        // Update local tag cache immediately so invalidations are reflected
+        // without waiting for the TTL to expire
+        for (const tag of validTags) {
+            this._tagCache.set(tag, { timestamp: now, fetchedAt: now });
+        }
     }
+    /**
+     * Clear the in-memory tag cache for this KVCacheHandler instance.
+     *
+     * Note: KVCacheHandler instances are typically reused across multiple
+     * requests in a Cloudflare Worker. The `_tagCache` is intentionally
+     * cross-request — it reduces redundant KV reads for recently-seen tags
+     * across all requests hitting the same isolate, bounded by `tagCacheTtlMs`
+     * (default 5s). vinext does NOT call this method per request.
+     *
+     * This is an opt-in escape hatch for callers that need stricter isolation
+     * (e.g., tests, or environments with custom lifecycle management).
+     * Callers that require per-request isolation should either construct a
+     * fresh KVCacheHandler per request or invoke this method explicitly.
+     */
     resetRequestCache() {
-        // No-op — KV is stateless per request
+        this._tagCache.clear();
     }
     /**
      * Fire a KV delete in the background.
@@ -203,17 +271,17 @@ export class KVCacheHandler {
         // else: fire-and-forget on Node.js
     }
     /**
-     * Fire a KV put in the background.
-     * Same ALS ctx → constructor ctx → fire-and-forget precedence as
-     * `_deleteInBackground`.
+     * Execute a KV put and return the promise so callers can await completion.
+     * Also registers with ctx.waitUntil() so the Workers runtime keeps the
+     * isolate alive even if the caller does not await the returned promise.
      */
-    _putInBackground(kvKey, value, options) {
+    _put(kvKey, value, options) {
         const promise = this.kv.put(kvKey, value, options);
         const ctx = getRequestExecutionContext() ?? this.ctx;
         if (ctx) {
             ctx.waitUntil(promise);
         }
-        // else: fire-and-forget on Node.js
+        return promise;
     }
 }
 // ---------------------------------------------------------------------------
@@ -299,24 +367,23 @@ function restoreArrayBuffers(value) {
     return true;
 }
 function arrayBufferToBase64(buffer) {
-    const bytes = new Uint8Array(buffer);
-    let binary = "";
-    for (let i = 0; i < bytes.length; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
-    return btoa(binary);
+    return Buffer.from(buffer).toString("base64");
 }
+/**
+ * Decode a base64 string to an ArrayBuffer.
+ * Validates the input against the base64 alphabet before decoding,
+ * since Buffer.from(str, "base64") silently ignores invalid characters.
+ */
 function base64ToArrayBuffer(base64) {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-        bytes[i] = binary.charCodeAt(i);
+    if (!BASE64_RE.test(base64) || base64.length % 4 !== 0) {
+        throw new Error("Invalid base64 string");
     }
-    return bytes.buffer;
+    const buf = Buffer.from(base64, "base64");
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
 /**
  * Safely decode base64 to ArrayBuffer. Returns null on invalid input
- * instead of throwing a DOMException.
+ * instead of throwing.
  */
 function safeBase64ToArrayBuffer(base64) {
     try {

package/dist/cloudflare/kv-cache-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"kv-cache-handler.js","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAyCzE,kDAAkD;AAClD,MAAM,UAAU,GAAG,QAAQ,CAAC;AAE5B,oCAAoC;AACpC,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,8CAA8C;AAC9C,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;;;GAIG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc;QAAE,OAAO,IAAI,CAAC;IAC5F,wEAAwE;IACxE,yFAAyF;IACzF,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,cAAc;IACjB,EAAE,CAAc;IAChB,MAAM,CAAS;IACf,GAAG,CAA+B;IAE1C,YAAY,WAAwB,EAAE,OAAwD;QAC5F,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,GAAG,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAA8B;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,YAAY,GAAG,GAAG,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;YAC5E,iFAAiF;YACjF,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,2CAA2C;QAC3C,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;YAClE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,uEAAuE;QACvE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,wDAAwD;gBACxD,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,GAAG,CAClC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC,CAAC,CACrE,CAAC;YACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;gBAC9B,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;oBACrC,IAAI,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;wBACrE,kEAAkE;wBAClE,qCAAqC;wBACrC,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;wBAChC,OAAO,IAAI,CAAC;oBACd,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;YACnE,OAAO;gBACL,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU,EAAE,OAAO;aACpB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;IACJ,CAAC;IAED,GAAG,CACD,GAAW,EACX,IAAkC,EAClC,GAA6B;QAE7B,2DAA2D;QAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QACjC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC1B,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,SAAS;oBAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAgB,EAAE,CAAC;gBACrC,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,SAAS;oBAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAEzB,8BAA8B;QAC9B,IAAI,YAAY,GAAkB,IAAI,CAAC;QACvC,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,UAAU,GAAI,GAAW,CAAC,YAAY,EAAE,UAAU,IAAK,GAAW,CAAC,UAAU,CAAC;YACpF,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBACrD,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC;YAChD,CAAC;QACH,CAAC;QACD,IACE,IAAI;YACJ,YAAY,IAAI,IAAI;YACpB,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;YACnC,IAAI,CAAC,UAAU,GAAG,CAAC,EACnB,CAAC;YACD,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACrD,CAAC;QAED,kEAAkE;QAClE,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE1D,MAAM,KAAK,GAAiB;YAC1B,KAAK,EAAE,YAAY;YACnB,IAAI;YACJ,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;YACxB,YAAY;SACb,CAAC;QAEF,sEAAsE;QACtE,wEAAwE;QACxE,iEAAiE;QACjE,IAAI,aAAiC,CAAC;QACtC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACxE,4DAA4D;YAC5D,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YACjE,+BAA+B;YAC/B,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,GAAG,YAAY,GAAG,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;YAC7E,aAAa;SACd,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAuB,EAAE,UAAgC;QAC3E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QACjE,4CAA4C;QAC5C,oEAAoE;QACpE,MAAM,OAAO,CAAC,GAAG,CACf,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACpB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE;YACvD,aAAa,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;SAC9B,CAAC,CACH,CACF,CAAC;IACJ,CAAC;IAED,iBAAiB;QACf,sCAAsC;IACxC,CAAC;IAED;;;;;;;OAOG;IACK,mBAAmB,CAAC,KAAa;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,0BAA0B,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC;QACrD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,mCAAmC;IACrC,CAAC;IAED;;;;OAIG;IACK,gBAAgB,CACtB,KAAa,EACb,KAAa,EACb,OAAoC;QAEpC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,0BAA0B,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC;QACrD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,mCAAmC;IACrC,CAAC;CACF;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9F;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAE3C,kBAAkB;IAClB,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,GAAG,CAAC,YAAY,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnF,qEAAqE;IACrE,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;QACnD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IAClF,CAAC;IAED,OAAO,GAAmB,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAA4B;IACpD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO;YACL,GAAG,KAAK;YACR,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAS,CAAC,CAAC,CAAC,SAAS;SACjF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,OAAO;YACL,GAAG,KAAK;YACR,IAAI,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAQ;SAC7C,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO;YACL,GAAG,KAAK;YACR,MAAM,EAAE,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAQ;SACjD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,KAA4B;IACvD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACnE,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAc,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,OAAO,GAAG,OAAO,CAAC;IACnC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjE,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,IAAI,GAAG,OAAO,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,MAAa,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,MAAM,GAAG,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAmB;IAC9C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAc;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAAC,MAAc;IAC7C,IAAI,CAAC;QACH,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * Cloudflare KV-backed CacheHandler for vinext.\n *\n * Provides persistent ISR caching on Cloudflare Workers using KV as the\n * storage backend. Supports time-based expiry (stale-while-revalidate)\n * and tag-based invalidation.\n *\n * Usage in worker/index.ts:\n *\n *   import { KVCacheHandler } from \"vinext/cloudflare\";\n *   import { setCacheHandler } from \"vinext/shims/cache\";\n *\n *   export default {\n *     async fetch(request: Request, env: Env, ctx: ExecutionContext) {\n *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));\n *       // ctx is propagated automatically via runWithExecutionContext in\n *       // the vinext handler — no need to pass it to KVCacheHandler.\n *       // ... rest of worker handler\n *     }\n *   };\n *\n * Wrangler config (wrangler.jsonc):\n *\n *   {\n *     \"kv_namespaces\": [\n *       { \"binding\": \"VINEXT_CACHE\", \"id\": \"<your-kv-namespace-id>\" }\n *     ]\n *   }\n */\n\nimport type { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from \"../shims/cache.js\";\nimport { getRequestExecutionContext } from \"../shims/request-context.js\";\n\n// Cloudflare KV namespace interface (matches Workers types)\ninterface KVNamespace {\n  get(key: string, options?: { type?: string }): Promise<string | null>;\n  get(key: string, options: { type: \"arrayBuffer\" }): Promise<ArrayBuffer | null>;\n  put(\n    key: string,\n    value: string | ArrayBuffer | ReadableStream,\n    options?: { expirationTtl?: number; metadata?: Record<string, unknown> },\n  ): Promise<void>;\n  delete(key: string): Promise<void>;\n  list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{\n    keys: Array<{ name: string; metadata?: Record<string, unknown> }>;\n    list_complete: boolean;\n    cursor?: string;\n  }>;\n}\n\n/**\n * Minimal ExecutionContext interface for Cloudflare Workers.\n * Background KV operations (cleanup deletes, cache writes) are registered\n * with ctx.waitUntil() so they are not killed when the Response is returned.\n *\n * The preferred way to supply ctx is via runWithExecutionContext() in the\n * worker entry (see vinext/shims/request-context). The constructor option\n * is kept as a fallback for callers that set it explicitly.\n */\ninterface ExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\n/** Shape stored in KV for each cache entry. */\ninterface KVCacheEntry {\n  value: IncrementalCacheValue | null;\n  tags: string[];\n  lastModified: number;\n  /** Absolute timestamp (ms) after which the entry is \"stale\" (but still served). */\n  revalidateAt: number | null;\n}\n\n/** Key prefix for tag invalidation timestamps. */\nconst TAG_PREFIX = \"__tag:\";\n\n/** Key prefix for cache entries. */\nconst ENTRY_PREFIX = \"cache:\";\n\n/** Max tag length to prevent KV key abuse. */\nconst MAX_TAG_LENGTH = 256;\n\n/**\n * Validate a cache tag. Returns null if invalid.\n * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a\n * separator — allowing `:` in user tags could cause ambiguous key lookups.\n */\nfunction validateTag(tag: string): string | null {\n  if (typeof tag !== \"string\" || tag.length === 0 || tag.length > MAX_TAG_LENGTH) return null;\n  // Block control characters, path separators, and KV-special characters.\n  // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags\n  if (/[\\x00-\\x1f/\\\\:]/.test(tag)) return null;\n  return tag;\n}\n\nexport class KVCacheHandler implements CacheHandler {\n  private kv: KVNamespace;\n  private prefix: string;\n  private ctx: ExecutionContext | undefined;\n\n  constructor(kvNamespace: KVNamespace, options?: { appPrefix?: string; ctx?: ExecutionContext }) {\n    this.kv = kvNamespace;\n    this.prefix = options?.appPrefix ? `${options.appPrefix}:` : \"\";\n    this.ctx = options?.ctx;\n  }\n\n  async get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null> {\n    const kvKey = this.prefix + ENTRY_PREFIX + key;\n    const raw = await this.kv.get(kvKey);\n    if (!raw) return null;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Corrupted JSON — fire cleanup delete in the background and treat as miss.\n      // Using waitUntil ensures the delete isn't killed when the Response is returned.\n      this._deleteInBackground(kvKey);\n      return null;\n    }\n\n    // Validate deserialized shape before using\n    const entry = validateCacheEntry(parsed);\n    if (!entry) {\n      console.error(\"[vinext] Invalid cache entry shape for key:\", key);\n      this._deleteInBackground(kvKey);\n      return null;\n    }\n\n    // Restore ArrayBuffer fields that were base64-encoded for JSON storage\n    if (entry.value) {\n      const ok = restoreArrayBuffers(entry.value);\n      if (!ok) {\n        // base64 decode failed — corrupted entry, treat as miss\n        this._deleteInBackground(kvKey);\n        return null;\n      }\n    }\n\n    // Check tag-based invalidation (parallel for lower latency)\n    if (entry.tags.length > 0) {\n      const tagResults = await Promise.all(\n        entry.tags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)),\n      );\n      for (let i = 0; i < entry.tags.length; i++) {\n        const tagTime = tagResults[i];\n        if (tagTime) {\n          const tagTimestamp = Number(tagTime);\n          if (Number.isNaN(tagTimestamp) || tagTimestamp >= entry.lastModified) {\n            // Tag was invalidated after this entry, or timestamp is corrupted\n            // — treat as miss to force re-render\n            this._deleteInBackground(kvKey);\n            return null;\n          }\n        }\n      }\n    }\n\n    // Check time-based expiry — return stale with cacheState\n    if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) {\n      return {\n        lastModified: entry.lastModified,\n        value: entry.value,\n        cacheState: \"stale\",\n      };\n    }\n\n    return {\n      lastModified: entry.lastModified,\n      value: entry.value,\n    };\n  }\n\n  set(\n    key: string,\n    data: IncrementalCacheValue | null,\n    ctx?: Record<string, unknown>,\n  ): Promise<void> {\n    // Collect, validate, and dedupe tags from data and context\n    const tagSet = new Set<string>();\n    if (data && \"tags\" in data && Array.isArray(data.tags)) {\n      for (const t of data.tags) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    if (ctx && \"tags\" in ctx && Array.isArray(ctx.tags)) {\n      for (const t of ctx.tags as string[]) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    const tags = [...tagSet];\n\n    // Determine revalidation time\n    let revalidateAt: number | null = null;\n    if (ctx) {\n      const revalidate = (ctx as any).cacheControl?.revalidate ?? (ctx as any).revalidate;\n      if (typeof revalidate === \"number\" && revalidate > 0) {\n        revalidateAt = Date.now() + revalidate * 1000;\n      }\n    }\n    if (\n      data &&\n      \"revalidate\" in data &&\n      typeof data.revalidate === \"number\" &&\n      data.revalidate > 0\n    ) {\n      revalidateAt = Date.now() + data.revalidate * 1000;\n    }\n\n    // Prepare entry — convert ArrayBuffers to base64 for JSON storage\n    const serializable = data ? serializeForJSON(data) : null;\n\n    const entry: KVCacheEntry = {\n      value: serializable,\n      tags,\n      lastModified: Date.now(),\n      revalidateAt,\n    };\n\n    // Calculate KV TTL — keep entries well beyond their revalidate window\n    // (10x revalidate period, clamped to 60s–30d) so stale-while-revalidate\n    // can serve stale content while background regeneration happens.\n    let expirationTtl: number | undefined;\n    if (revalidateAt !== null) {\n      const revalidateSeconds = Math.ceil((revalidateAt - Date.now()) / 1000);\n      // Keep in KV for 10x the revalidation period, up to 30 days\n      expirationTtl = Math.min(revalidateSeconds * 10, 30 * 24 * 3600);\n      // KV minimum TTL is 60 seconds\n      expirationTtl = Math.max(expirationTtl, 60);\n    }\n\n    this._putInBackground(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {\n      expirationTtl,\n    });\n    return Promise.resolve();\n  }\n\n  async revalidateTag(tags: string | string[], _durations?: { expire?: number }): Promise<void> {\n    const tagList = Array.isArray(tags) ? tags : [tags];\n    const now = Date.now();\n    const validTags = tagList.filter((t) => validateTag(t) !== null);\n    // Store invalidation timestamp for each tag\n    // Use a long TTL (30 days) so recent invalidations are always found\n    await Promise.all(\n      validTags.map((tag) =>\n        this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {\n          expirationTtl: 30 * 24 * 3600,\n        }),\n      ),\n    );\n  }\n\n  resetRequestCache(): void {\n    // No-op — KV is stateless per request\n  }\n\n  /**\n   * Fire a KV delete in the background.\n   * Prefers the per-request ExecutionContext from ALS (set by\n   * runWithExecutionContext in the worker entry) so that background KV\n   * operations are registered with the correct request's waitUntil().\n   * Falls back to the constructor-provided ctx for callers that set it\n   * explicitly, and to fire-and-forget when neither is available (Node.js dev).\n   */\n  private _deleteInBackground(kvKey: string): void {\n    const promise = this.kv.delete(kvKey);\n    const ctx = getRequestExecutionContext() ?? this.ctx;\n    if (ctx) {\n      ctx.waitUntil(promise);\n    }\n    // else: fire-and-forget on Node.js\n  }\n\n  /**\n   * Fire a KV put in the background.\n   * Same ALS ctx → constructor ctx → fire-and-forget precedence as\n   * `_deleteInBackground`.\n   */\n  private _putInBackground(\n    kvKey: string,\n    value: string,\n    options?: { expirationTtl?: number },\n  ): void {\n    const promise = this.kv.put(kvKey, value, options);\n    const ctx = getRequestExecutionContext() ?? this.ctx;\n    if (ctx) {\n      ctx.waitUntil(promise);\n    }\n    // else: fire-and-forget on Node.js\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation helpers\n// ---------------------------------------------------------------------------\n\nconst VALID_KINDS = new Set([\"FETCH\", \"APP_PAGE\", \"PAGES\", \"APP_ROUTE\", \"REDIRECT\", \"IMAGE\"]);\n\n/**\n * Validate that a parsed JSON value has the expected KVCacheEntry shape.\n * Returns the validated entry or null if the shape is invalid.\n */\nfunction validateCacheEntry(raw: unknown): KVCacheEntry | null {\n  if (!raw || typeof raw !== \"object\") return null;\n\n  const obj = raw as Record<string, unknown>;\n\n  // Required fields\n  if (typeof obj.lastModified !== \"number\") return null;\n  if (!Array.isArray(obj.tags)) return null;\n  if (obj.revalidateAt !== null && typeof obj.revalidateAt !== \"number\") return null;\n\n  // value must be null or a valid cache value object with a known kind\n  if (obj.value !== null) {\n    if (!obj.value || typeof obj.value !== \"object\") return null;\n    const value = obj.value as Record<string, unknown>;\n    if (typeof value.kind !== \"string\" || !VALID_KINDS.has(value.kind)) return null;\n  }\n\n  return raw as KVCacheEntry;\n}\n\n// ---------------------------------------------------------------------------\n// ArrayBuffer serialization helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Deep-clone a cache value, converting ArrayBuffer fields to base64 strings\n * so the entire structure can be JSON.stringify'd for KV storage.\n */\nfunction serializeForJSON(value: IncrementalCacheValue): IncrementalCacheValue {\n  if (value.kind === \"APP_PAGE\") {\n    return {\n      ...value,\n      rscData: value.rscData ? (arrayBufferToBase64(value.rscData) as any) : undefined,\n    };\n  }\n  if (value.kind === \"APP_ROUTE\") {\n    return {\n      ...value,\n      body: arrayBufferToBase64(value.body) as any,\n    };\n  }\n  if (value.kind === \"IMAGE\") {\n    return {\n      ...value,\n      buffer: arrayBufferToBase64(value.buffer) as any,\n    };\n  }\n  return value;\n}\n\n/**\n * Restore base64 strings back to ArrayBuffers after JSON.parse.\n * Returns false if any base64 decode fails (corrupted entry).\n */\nfunction restoreArrayBuffers(value: IncrementalCacheValue): boolean {\n  if (value.kind === \"APP_PAGE\" && typeof value.rscData === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.rscData as any);\n    if (!decoded) return false;\n    (value as any).rscData = decoded;\n  }\n  if (value.kind === \"APP_ROUTE\" && typeof value.body === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.body as any);\n    if (!decoded) return false;\n    (value as any).body = decoded;\n  }\n  if (value.kind === \"IMAGE\" && typeof value.buffer === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.buffer as any);\n    if (!decoded) return false;\n    (value as any).buffer = decoded;\n  }\n  return true;\n}\n\nfunction arrayBufferToBase64(buffer: ArrayBuffer): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\nfunction base64ToArrayBuffer(base64: string): ArrayBuffer {\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes.buffer;\n}\n\n/**\n * Safely decode base64 to ArrayBuffer. Returns null on invalid input\n * instead of throwing a DOMException.\n */\nfunction safeBase64ToArrayBuffer(base64: string): ArrayBuffer | null {\n  try {\n    return base64ToArrayBuffer(base64);\n  } catch {\n    console.error(\"[vinext] Invalid base64 in cache entry\");\n    return null;\n  }\n}\n"]}
+{"version":3,"file":"kv-cache-handler.js","sourceRoot":"","sources":["../../src/cloudflare/kv-cache-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,0BAA0B,EAA6B,MAAM,6BAA6B,CAAC;AA4BpG,kDAAkD;AAClD,MAAM,UAAU,GAAG,QAAQ,CAAC;AAE5B,oCAAoC;AACpC,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,8CAA8C;AAC9C,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,+EAA+E;AAC/E,MAAM,SAAS,GAAG,wBAAwB,CAAC;AAE3C;;;;GAIG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc;QAAE,OAAO,IAAI,CAAC;IAC5F,+EAA+E;IAC/E,yEAAyE;IACzE,0CAA0C;IAC1C,yFAAyF;IACzF,IAAI,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,cAAc;IACjB,EAAE,CAAc;IAChB,MAAM,CAAS;IACf,GAAG,CAAmC;IACtC,UAAU,CAAS;IAE3B,wFAAwF;IAChF,SAAS,GAAG,IAAI,GAAG,EAAoD,CAAC;IAChF,0EAA0E;IAClE,YAAY,CAAS;IAE7B,YACE,WAAwB,EACxB,OAMC;QAED,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,GAAG,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACxD,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,aAAa,IAAI,KAAK,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAA8B;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,YAAY,GAAG,GAAG,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QAEtB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;YAC5E,iFAAiF;YACjF,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,2CAA2C;QAC3C,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;YAClE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,uEAAuE;QACvE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,wDAAwD;gBACxD,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,mFAAmF;QACnF,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,YAAY,GAAa,EAAE,CAAC;YAElC,8CAA8C;YAC9C,iFAAiF;YACjF,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACvC,IAAI,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;oBACzD,8CAA8C;oBAC9C,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;wBAC7E,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;wBAChC,OAAO,IAAI,CAAC;oBACd,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,6DAA6D;oBAC7D,IAAI,MAAM;wBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACvC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAED,wDAAwD;YACxD,8EAA8E;YAC9E,wEAAwE;YACxE,kFAAkF;YAClF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,GAAG,CAClC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC,CAAC,CACvE,CAAC;gBAEF,qEAAqE;gBACrE,qEAAqE;gBACrE,sEAAsE;gBACtE,qEAAqE;gBACrE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;oBAC9B,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBACnD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;gBACnF,CAAC;gBAED,8DAA8D;gBAC9D,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;oBAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;oBACxC,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;wBAC3B,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;4BAC7E,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;4BAChC,OAAO,IAAI,CAAC;wBACd,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;YACnE,OAAO;gBACL,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU,EAAE,OAAO;aACpB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;IACJ,CAAC;IAED,GAAG,CACD,GAAW,EACX,IAAkC,EAClC,GAA6B;QAE7B,2DAA2D;QAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QACjC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC1B,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,SAAS;oBAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAgB,EAAE,CAAC;gBACrC,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,SAAS;oBAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAEzB,8BAA8B;QAC9B,IAAI,YAAY,GAAkB,IAAI,CAAC;QACvC,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,UAAU,GAAI,GAAW,CAAC,YAAY,EAAE,UAAU,IAAK,GAAW,CAAC,UAAU,CAAC;YACpF,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBACrD,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC;YAChD,CAAC;QACH,CAAC;QACD,IACE,IAAI;YACJ,YAAY,IAAI,IAAI;YACpB,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ;YACnC,IAAI,CAAC,UAAU,GAAG,CAAC,EACnB,CAAC;YACD,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACrD,CAAC;QAED,kEAAkE;QAClE,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE1D,MAAM,KAAK,GAAiB;YAC1B,KAAK,EAAE,YAAY;YACnB,IAAI;YACJ,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;YACxB,YAAY;SACb,CAAC;QAEF,oDAAoD;QACpD,EAAE;QACF,4EAA4E;QAC5E,2EAA2E;QAC3E,2EAA2E;QAC3E,EAAE;QACF,uEAAuE;QACvE,6EAA6E;QAC7E,4EAA4E;QAC5E,EAAE;QACF,2EAA2E;QAC3E,6EAA6E;QAC7E,+EAA+E;QAC/E,4EAA4E;QAC5E,MAAM,aAAa,GAAuB,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAE9F,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,YAAY,GAAG,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;YACxE,aAAa;SACd,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAuB,EAAE,UAAgC;QAC3E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QACjE,4CAA4C;QAC5C,oEAAoE;QACpE,MAAM,OAAO,CAAC,GAAG,CACf,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACpB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,GAAG,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE;YACvD,aAAa,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;SAC9B,CAAC,CACH,CACF,CAAC;QACF,oEAAoE;QACpE,wCAAwC;QACxC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,iBAAiB;QACf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACK,mBAAmB,CAAC,KAAa;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,0BAA0B,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC;QACrD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,mCAAmC;IACrC,CAAC;IAED;;;;OAIG;IACK,IAAI,CAAC,KAAa,EAAE,KAAa,EAAE,OAAoC;QAC7E,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,0BAA0B,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC;QACrD,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9F;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAE3C,kBAAkB;IAClB,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,GAAG,CAAC,YAAY,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnF,qEAAqE;IACrE,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;QACnD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IAClF,CAAC;IAED,OAAO,GAAmB,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAA4B;IACpD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO;YACL,GAAG,KAAK;YACR,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAS,CAAC,CAAC,CAAC,SAAS;SACjF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,OAAO;YACL,GAAG,KAAK;YACR,IAAI,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAQ;SAC7C,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO;YACL,GAAG,KAAK;YACR,MAAM,EAAE,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAQ;SACjD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,KAA4B;IACvD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACnE,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAc,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,OAAO,GAAG,OAAO,CAAC;IACnC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjE,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,IAAI,GAAG,OAAO,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,MAAa,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC1B,KAAa,CAAC,MAAM,GAAG,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAmB;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,MAAc;IACzC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1C,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;AAC3E,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAAC,MAAc;IAC7C,IAAI,CAAC;QACH,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * Cloudflare KV-backed CacheHandler for vinext.\n *\n * Provides persistent ISR caching on Cloudflare Workers using KV as the\n * storage backend. Supports time-based expiry (stale-while-revalidate)\n * and tag-based invalidation.\n *\n * Usage in worker/index.ts:\n *\n *   import { KVCacheHandler } from \"vinext/cloudflare\";\n *   import { setCacheHandler } from \"vinext/shims/cache\";\n *\n *   export default {\n *     async fetch(request: Request, env: Env, ctx: ExecutionContext) {\n *       setCacheHandler(new KVCacheHandler(env.VINEXT_CACHE));\n *       // ctx is propagated automatically via runWithExecutionContext in\n *       // the vinext handler — no need to pass it to KVCacheHandler.\n *       // ... rest of worker handler\n *     }\n *   };\n *\n * Wrangler config (wrangler.jsonc):\n *\n *   {\n *     \"kv_namespaces\": [\n *       { \"binding\": \"VINEXT_CACHE\", \"id\": \"<your-kv-namespace-id>\" }\n *     ]\n *   }\n */\n\nimport { Buffer } from \"node:buffer\";\n\nimport type { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from \"../shims/cache.js\";\nimport { getRequestExecutionContext, type ExecutionContextLike } from \"../shims/request-context.js\";\n\n// Cloudflare KV namespace interface (matches Workers types)\ninterface KVNamespace {\n  get(key: string, options?: { type?: string }): Promise<string | null>;\n  get(key: string, options: { type: \"arrayBuffer\" }): Promise<ArrayBuffer | null>;\n  put(\n    key: string,\n    value: string | ArrayBuffer | ReadableStream,\n    options?: { expirationTtl?: number; metadata?: Record<string, unknown> },\n  ): Promise<void>;\n  delete(key: string): Promise<void>;\n  list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{\n    keys: Array<{ name: string; metadata?: Record<string, unknown> }>;\n    list_complete: boolean;\n    cursor?: string;\n  }>;\n}\n\n/** Shape stored in KV for each cache entry. */\ninterface KVCacheEntry {\n  value: IncrementalCacheValue | null;\n  tags: string[];\n  lastModified: number;\n  /** Absolute timestamp (ms) after which the entry is \"stale\" (but still served). */\n  revalidateAt: number | null;\n}\n\n/** Key prefix for tag invalidation timestamps. */\nconst TAG_PREFIX = \"__tag:\";\n\n/** Key prefix for cache entries. */\nconst ENTRY_PREFIX = \"cache:\";\n\n/** Max tag length to prevent KV key abuse. */\nconst MAX_TAG_LENGTH = 256;\n\n/** Matches a valid base64 string (standard alphabet with optional padding). */\nconst BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;\n\n/**\n * Validate a cache tag. Returns null if invalid.\n * Note: `:` is rejected because TAG_PREFIX and ENTRY_PREFIX use `:` as a\n * separator — allowing `:` in user tags could cause ambiguous key lookups.\n */\nfunction validateTag(tag: string): string | null {\n  if (typeof tag !== \"string\" || tag.length === 0 || tag.length > MAX_TAG_LENGTH) return null;\n  // Block control characters and reserved separators used in our own key format.\n  // Slash is allowed because revalidatePath() relies on pathname tags like\n  // \"/posts/hello\" and \"_N_T_/posts/hello\".\n  // eslint-disable-next-line no-control-regex -- intentional: reject control chars in tags\n  if (/[\\x00-\\x1f\\\\:]/.test(tag)) return null;\n  return tag;\n}\n\nexport class KVCacheHandler implements CacheHandler {\n  private kv: KVNamespace;\n  private prefix: string;\n  private ctx: ExecutionContextLike | undefined;\n  private ttlSeconds: number;\n\n  /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */\n  private _tagCache = new Map<string, { timestamp: number; fetchedAt: number }>();\n  /** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */\n  private _tagCacheTtl: number;\n\n  constructor(\n    kvNamespace: KVNamespace,\n    options?: {\n      appPrefix?: string;\n      ctx?: ExecutionContextLike;\n      ttlSeconds?: number;\n      /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */\n      tagCacheTtlMs?: number;\n    },\n  ) {\n    this.kv = kvNamespace;\n    this.prefix = options?.appPrefix ? `${options.appPrefix}:` : \"\";\n    this.ctx = options?.ctx;\n    this.ttlSeconds = options?.ttlSeconds ?? 30 * 24 * 3600;\n    this._tagCacheTtl = options?.tagCacheTtlMs ?? 5_000;\n  }\n\n  async get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null> {\n    const kvKey = this.prefix + ENTRY_PREFIX + key;\n    const raw = await this.kv.get(kvKey);\n    if (!raw) return null;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Corrupted JSON — fire cleanup delete in the background and treat as miss.\n      // Using waitUntil ensures the delete isn't killed when the Response is returned.\n      this._deleteInBackground(kvKey);\n      return null;\n    }\n\n    // Validate deserialized shape before using\n    const entry = validateCacheEntry(parsed);\n    if (!entry) {\n      console.error(\"[vinext] Invalid cache entry shape for key:\", key);\n      this._deleteInBackground(kvKey);\n      return null;\n    }\n\n    // Restore ArrayBuffer fields that were base64-encoded for JSON storage\n    if (entry.value) {\n      const ok = restoreArrayBuffers(entry.value);\n      if (!ok) {\n        // base64 decode failed — corrupted entry, treat as miss\n        this._deleteInBackground(kvKey);\n        return null;\n      }\n    }\n\n    // Check tag-based invalidation.\n    // Uses a local in-memory cache to avoid redundant KV reads for recently-seen tags.\n    if (entry.tags.length > 0) {\n      const now = Date.now();\n      const uncachedTags: string[] = [];\n\n      // First pass: check local cache for each tag.\n      // Delete expired entries to prevent unbounded Map growth in long-lived isolates.\n      for (const tag of entry.tags) {\n        const cached = this._tagCache.get(tag);\n        if (cached && now - cached.fetchedAt < this._tagCacheTtl) {\n          // Local cache hit — check invalidation inline\n          if (Number.isNaN(cached.timestamp) || cached.timestamp >= entry.lastModified) {\n            this._deleteInBackground(kvKey);\n            return null;\n          }\n        } else {\n          // Expired or absent — evict stale entry and re-fetch from KV\n          if (cached) this._tagCache.delete(tag);\n          uncachedTags.push(tag);\n        }\n      }\n\n      // Second pass: fetch uncached tags from KV in parallel.\n      // Populate the local cache for ALL fetched tags before checking invalidation,\n      // so that KV round-trips are not wasted when an earlier tag triggers an\n      // early return — subsequent get() calls benefit from the already-fetched results.\n      if (uncachedTags.length > 0) {\n        const tagResults = await Promise.all(\n          uncachedTags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)),\n        );\n\n        // Populate cache for all results first, then check for invalidation.\n        // Two-loop structure ensures all tag results are cached even when an\n        // earlier tag would cause an early return — so subsequent get() calls\n        // for entries sharing those tags don't redundantly re-fetch from KV.\n        for (let i = 0; i < uncachedTags.length; i++) {\n          const tagTime = tagResults[i];\n          const tagTimestamp = tagTime ? Number(tagTime) : 0;\n          this._tagCache.set(uncachedTags[i], { timestamp: tagTimestamp, fetchedAt: now });\n        }\n\n        // Then check for invalidation using the now-cached timestamps\n        for (const tag of uncachedTags) {\n          const cached = this._tagCache.get(tag)!;\n          if (cached.timestamp !== 0) {\n            if (Number.isNaN(cached.timestamp) || cached.timestamp >= entry.lastModified) {\n              this._deleteInBackground(kvKey);\n              return null;\n            }\n          }\n        }\n      }\n    }\n\n    // Check time-based expiry — return stale with cacheState\n    if (entry.revalidateAt !== null && Date.now() > entry.revalidateAt) {\n      return {\n        lastModified: entry.lastModified,\n        value: entry.value,\n        cacheState: \"stale\",\n      };\n    }\n\n    return {\n      lastModified: entry.lastModified,\n      value: entry.value,\n    };\n  }\n\n  set(\n    key: string,\n    data: IncrementalCacheValue | null,\n    ctx?: Record<string, unknown>,\n  ): Promise<void> {\n    // Collect, validate, and dedupe tags from data and context\n    const tagSet = new Set<string>();\n    if (data && \"tags\" in data && Array.isArray(data.tags)) {\n      for (const t of data.tags) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    if (ctx && \"tags\" in ctx && Array.isArray(ctx.tags)) {\n      for (const t of ctx.tags as string[]) {\n        const validated = validateTag(t);\n        if (validated) tagSet.add(validated);\n      }\n    }\n    const tags = [...tagSet];\n\n    // Determine revalidation time\n    let revalidateAt: number | null = null;\n    if (ctx) {\n      const revalidate = (ctx as any).cacheControl?.revalidate ?? (ctx as any).revalidate;\n      if (typeof revalidate === \"number\" && revalidate > 0) {\n        revalidateAt = Date.now() + revalidate * 1000;\n      }\n    }\n    if (\n      data &&\n      \"revalidate\" in data &&\n      typeof data.revalidate === \"number\" &&\n      data.revalidate > 0\n    ) {\n      revalidateAt = Date.now() + data.revalidate * 1000;\n    }\n\n    // Prepare entry — convert ArrayBuffers to base64 for JSON storage\n    const serializable = data ? serializeForJSON(data) : null;\n\n    const entry: KVCacheEntry = {\n      value: serializable,\n      tags,\n      lastModified: Date.now(),\n      revalidateAt,\n    };\n\n    // KV TTL is decoupled from the revalidation period.\n    //\n    // Staleness (when to trigger background regen) is tracked by `revalidateAt`\n    // in the stored JSON — not by KV eviction. KV eviction is purely a storage\n    // hygiene mechanism and must never be the reason a stale entry disappears.\n    //\n    // If KV TTL were tied to the revalidate window (e.g. 10x), a page with\n    // revalidate=5 would be evicted after ~50 seconds of no traffic, causing the\n    // next request to block on a fresh render instead of serving stale content.\n    //\n    // Fix: always keep entries for 30 days regardless of revalidate frequency.\n    // Background regen overwrites the key with a fresh entry + new revalidateAt,\n    // so active pages always have something to serve. Entries only disappear after\n    // 30 days of zero traffic, or when explicitly deleted via tag invalidation.\n    const expirationTtl: number | undefined = revalidateAt !== null ? this.ttlSeconds : undefined;\n\n    return this._put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {\n      expirationTtl,\n    });\n  }\n\n  async revalidateTag(tags: string | string[], _durations?: { expire?: number }): Promise<void> {\n    const tagList = Array.isArray(tags) ? tags : [tags];\n    const now = Date.now();\n    const validTags = tagList.filter((t) => validateTag(t) !== null);\n    // Store invalidation timestamp for each tag\n    // Use a long TTL (30 days) so recent invalidations are always found\n    await Promise.all(\n      validTags.map((tag) =>\n        this.kv.put(this.prefix + TAG_PREFIX + tag, String(now), {\n          expirationTtl: 30 * 24 * 3600,\n        }),\n      ),\n    );\n    // Update local tag cache immediately so invalidations are reflected\n    // without waiting for the TTL to expire\n    for (const tag of validTags) {\n      this._tagCache.set(tag, { timestamp: now, fetchedAt: now });\n    }\n  }\n\n  /**\n   * Clear the in-memory tag cache for this KVCacheHandler instance.\n   *\n   * Note: KVCacheHandler instances are typically reused across multiple\n   * requests in a Cloudflare Worker. The `_tagCache` is intentionally\n   * cross-request — it reduces redundant KV reads for recently-seen tags\n   * across all requests hitting the same isolate, bounded by `tagCacheTtlMs`\n   * (default 5s). vinext does NOT call this method per request.\n   *\n   * This is an opt-in escape hatch for callers that need stricter isolation\n   * (e.g., tests, or environments with custom lifecycle management).\n   * Callers that require per-request isolation should either construct a\n   * fresh KVCacheHandler per request or invoke this method explicitly.\n   */\n  resetRequestCache(): void {\n    this._tagCache.clear();\n  }\n\n  /**\n   * Fire a KV delete in the background.\n   * Prefers the per-request ExecutionContext from ALS (set by\n   * runWithExecutionContext in the worker entry) so that background KV\n   * operations are registered with the correct request's waitUntil().\n   * Falls back to the constructor-provided ctx for callers that set it\n   * explicitly, and to fire-and-forget when neither is available (Node.js dev).\n   */\n  private _deleteInBackground(kvKey: string): void {\n    const promise = this.kv.delete(kvKey);\n    const ctx = getRequestExecutionContext() ?? this.ctx;\n    if (ctx) {\n      ctx.waitUntil(promise);\n    }\n    // else: fire-and-forget on Node.js\n  }\n\n  /**\n   * Execute a KV put and return the promise so callers can await completion.\n   * Also registers with ctx.waitUntil() so the Workers runtime keeps the\n   * isolate alive even if the caller does not await the returned promise.\n   */\n  private _put(kvKey: string, value: string, options?: { expirationTtl?: number }): Promise<void> {\n    const promise = this.kv.put(kvKey, value, options);\n    const ctx = getRequestExecutionContext() ?? this.ctx;\n    if (ctx) {\n      ctx.waitUntil(promise);\n    }\n    return promise;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation helpers\n// ---------------------------------------------------------------------------\n\nconst VALID_KINDS = new Set([\"FETCH\", \"APP_PAGE\", \"PAGES\", \"APP_ROUTE\", \"REDIRECT\", \"IMAGE\"]);\n\n/**\n * Validate that a parsed JSON value has the expected KVCacheEntry shape.\n * Returns the validated entry or null if the shape is invalid.\n */\nfunction validateCacheEntry(raw: unknown): KVCacheEntry | null {\n  if (!raw || typeof raw !== \"object\") return null;\n\n  const obj = raw as Record<string, unknown>;\n\n  // Required fields\n  if (typeof obj.lastModified !== \"number\") return null;\n  if (!Array.isArray(obj.tags)) return null;\n  if (obj.revalidateAt !== null && typeof obj.revalidateAt !== \"number\") return null;\n\n  // value must be null or a valid cache value object with a known kind\n  if (obj.value !== null) {\n    if (!obj.value || typeof obj.value !== \"object\") return null;\n    const value = obj.value as Record<string, unknown>;\n    if (typeof value.kind !== \"string\" || !VALID_KINDS.has(value.kind)) return null;\n  }\n\n  return raw as KVCacheEntry;\n}\n\n// ---------------------------------------------------------------------------\n// ArrayBuffer serialization helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Deep-clone a cache value, converting ArrayBuffer fields to base64 strings\n * so the entire structure can be JSON.stringify'd for KV storage.\n */\nfunction serializeForJSON(value: IncrementalCacheValue): IncrementalCacheValue {\n  if (value.kind === \"APP_PAGE\") {\n    return {\n      ...value,\n      rscData: value.rscData ? (arrayBufferToBase64(value.rscData) as any) : undefined,\n    };\n  }\n  if (value.kind === \"APP_ROUTE\") {\n    return {\n      ...value,\n      body: arrayBufferToBase64(value.body) as any,\n    };\n  }\n  if (value.kind === \"IMAGE\") {\n    return {\n      ...value,\n      buffer: arrayBufferToBase64(value.buffer) as any,\n    };\n  }\n  return value;\n}\n\n/**\n * Restore base64 strings back to ArrayBuffers after JSON.parse.\n * Returns false if any base64 decode fails (corrupted entry).\n */\nfunction restoreArrayBuffers(value: IncrementalCacheValue): boolean {\n  if (value.kind === \"APP_PAGE\" && typeof value.rscData === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.rscData as any);\n    if (!decoded) return false;\n    (value as any).rscData = decoded;\n  }\n  if (value.kind === \"APP_ROUTE\" && typeof value.body === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.body as any);\n    if (!decoded) return false;\n    (value as any).body = decoded;\n  }\n  if (value.kind === \"IMAGE\" && typeof value.buffer === \"string\") {\n    const decoded = safeBase64ToArrayBuffer(value.buffer as any);\n    if (!decoded) return false;\n    (value as any).buffer = decoded;\n  }\n  return true;\n}\n\nfunction arrayBufferToBase64(buffer: ArrayBuffer): string {\n  return Buffer.from(buffer).toString(\"base64\");\n}\n\n/**\n * Decode a base64 string to an ArrayBuffer.\n * Validates the input against the base64 alphabet before decoding,\n * since Buffer.from(str, \"base64\") silently ignores invalid characters.\n */\nfunction base64ToArrayBuffer(base64: string): ArrayBuffer {\n  if (!BASE64_RE.test(base64) || base64.length % 4 !== 0) {\n    throw new Error(\"Invalid base64 string\");\n  }\n  const buf = Buffer.from(base64, \"base64\");\n  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);\n}\n\n/**\n * Safely decode base64 to ArrayBuffer. Returns null on invalid input\n * instead of throwing.\n */\nfunction safeBase64ToArrayBuffer(base64: string): ArrayBuffer | null {\n  try {\n    return base64ToArrayBuffer(base64);\n  } catch {\n    console.error(\"[vinext] Invalid base64 in cache entry\");\n    return null;\n  }\n}\n"]}

package/dist/cloudflare/tpr.d.ts

@@ -61,6 +61,16 @@ interface WranglerConfig {
  * account_id, VINEXT_CACHE KV namespace ID, and custom domain.
  */
 export declare function parseWranglerConfig(root: string): WranglerConfig | null;
+/**
+ * Generate zone lookup candidates from shortest (2-part) to longest.
+ * Tries the most common case first (e.g., "example.com") and progressively
+ * adds labels for multi-part TLDs (e.g., "co.uk" → "example.co.uk").
+ *
+ * "shop.example.com"    → ["example.com", "shop.example.com"]
+ * "shop.example.co.uk"  → ["co.uk", "example.co.uk", "shop.example.co.uk"]
+ * "example.com"         → ["example.com"]
+ */
+export declare function domainCandidates(domain: string): string[];
 /**
  * Walk the ranked traffic list, accumulating request counts until the
  * coverage target is met or the hard cap is reached.

package/dist/cloudflare/tpr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tpr.d.ts","sourceRoot":"","sources":["../../src/cloudflare/tpr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBvE;AAmXD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,CAuBhB;AAsPD;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA2HpE"}
+{"version":3,"file":"tpr.d.ts","sourceRoot":"","sources":["../../src/cloudflare/tpr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAQD,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBvE;AA6MD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzD;AAmJD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,cAAc,CAuBhB;AAsPD;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA2HpE"}

package/dist/cloudflare/tpr.js

@@ -227,49 +227,44 @@ function extractFromTOML(content) {
     return result;
 }
 // ─── Cloudflare API ──────────────────────────────────────────────────────────
+/**
+ * Generate zone lookup candidates from shortest (2-part) to longest.
+ * Tries the most common case first (e.g., "example.com") and progressively
+ * adds labels for multi-part TLDs (e.g., "co.uk" → "example.co.uk").
+ *
+ * "shop.example.com"    → ["example.com", "shop.example.com"]
+ * "shop.example.co.uk"  → ["co.uk", "example.co.uk", "shop.example.co.uk"]
+ * "example.com"         → ["example.com"]
+ */
+export function domainCandidates(domain) {
+    const parts = domain.split(".");
+    const candidates = [];
+    for (let i = parts.length - 2; i >= 0; i--) {
+        candidates.push(parts.slice(i).join("."));
+    }
+    return candidates;
+}
 /** Resolve zone ID from a domain name via the Cloudflare API. */
 async function resolveZoneId(domain, apiToken) {
-    // Extract the registrable domain (e.g., "shop.example.com" → "example.com").
-    // TODO: This doesn't handle multi-part TLDs like .co.uk, .com.br, .com.au.
-    // For those, we'd need a public suffix list. For now, we try the simple
-    // two-part extraction first, then fall back to the full domain if the zone
-    // lookup fails. Cloudflare's zone API will match on the correct registrable
-    // domain regardless.
-    const parts = domain.split(".");
-    const MULTI_PART_TLDS = [
-        "co.uk",
-        "com.br",
-        "com.au",
-        "co.jp",
-        "co.kr",
-        "co.nz",
-        "co.za",
-        "com.mx",
-        "com.ar",
-        "com.cn",
-        "org.uk",
-        "net.au",
-    ];
-    const lastTwo = parts.slice(-2).join(".");
-    let rootDomain;
-    if (MULTI_PART_TLDS.includes(lastTwo) && parts.length > 2) {
-        rootDomain = parts.slice(-3).join(".");
-    }
-    else {
-        rootDomain = parts.length > 2 ? parts.slice(-2).join(".") : domain;
-    }
-    const response = await fetch(`https://api.cloudflare.com/client/v4/zones?name=${encodeURIComponent(rootDomain)}`, {
-        headers: {
-            Authorization: `Bearer ${apiToken}`,
-            "Content-Type": "application/json",
-        },
-    });
-    if (!response.ok)
-        return null;
-    const data = (await response.json());
-    if (!data.success || !data.result?.length)
-        return null;
-    return data.result[0].id;
+    // Try progressively longer domain candidates until one matches a zone.
+    // This handles all public suffixes without a hardcoded TLD list —
+    // for simple TLDs (.com, .io) the 2-part candidate hits on the first try;
+    // for multi-part TLDs (.co.uk, .com.au) it takes one extra call.
+    for (const candidate of domainCandidates(domain)) {
+        const response = await fetch(`https://api.cloudflare.com/client/v4/zones?name=${encodeURIComponent(candidate)}`, {
+            headers: {
+                Authorization: `Bearer ${apiToken}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok)
+            continue;
+        const data = (await response.json());
+        if (data.success && data.result?.length) {
+            return data.result[0].id;
+        }
+    }
+    return null;
 }
 /** Resolve the account ID associated with the API token. */
 async function resolveAccountId(apiToken) {