@vinext/cloudflare 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/cache/kv-data-adapter.runtime.js

@@ -1,7 +1,7 @@
 import { ENTRY_PREFIX, createKvKeySpace } from "./kv-key.js";
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
-import { getRequestExecutionContext } from "vinext/shims/request-context";
 import { Buffer } from "node:buffer";
+import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/kv-data-adapter.runtime.ts
 /**
 * Cloudflare KV data cache — implementation + runtime factory.
@@ -28,6 +28,10 @@ const DEFAULT_BINDING = "VINEXT_KV_CACHE";
 const PATH_TAG_PREFIX = "_N_T_";
 /** Max tag length to prevent KV key abuse. */
 const MAX_TAG_LENGTH = 256;
+/** The runtime rejects a lower `cacheTtl` with "Cache TTL must be at least 30". */
+const MIN_KV_CACHE_TTL_SECONDS = 30;
+/** Cloudflare caps a bulk `get()` at 100 keys per call. */
+const KV_BULK_GET_LIMIT = 100;
 /** Matches a valid base64 string (standard alphabet with optional padding). */
 const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 /**
@@ -98,14 +102,20 @@ var KVCacheHandler = class {
 	ttlSeconds;
 	/** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
 	_tagCache = /* @__PURE__ */ new Map();
+	/** Monotonic ordering for concurrent tag-cache fills and local invalidations. */
+	_tagCacheOrder = 0;
 	/** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */
 	_tagCacheTtl;
+	/** Read options for entry keys only. `undefined` keeps the KV default cacheTtl. */
+	_entryReadOptions;
 	constructor(kvNamespace, options) {
 		this.kv = kvNamespace;
 		this.keySpace = createKvKeySpace(options?.appPrefix);
 		this.ctx = options?.ctx;
-		this.ttlSeconds = options?.ttlSeconds ?? 720 * 3600;
+		this.ttlSeconds = options?.ttlSeconds ?? 2592e3;
 		this._tagCacheTtl = options?.tagCacheTtlMs ?? 5e3;
+		const entryCacheTtl = options?.entryCacheTtlSeconds;
+		this._entryReadOptions = typeof entryCacheTtl === "number" && Number.isFinite(entryCacheTtl) ? { cacheTtl: Math.max(MIN_KV_CACHE_TTL_SECONDS, Math.floor(entryCacheTtl)) } : void 0;
 	}
 	_entryKey(key) {
 		return this.keySpace.entryKey(key);
@@ -115,37 +125,64 @@ var KVCacheHandler = class {
 	}
 	async get(key, _ctx) {
 		const kvKey = this._entryKey(key);
-		const raw = await this.kv.get(kvKey);
+		const softTags = validUniqueTags(readStringArrayField(_ctx, "softTags"));
+		const entryRead = this._entryReadOptions ? this.kv.get(kvKey, this._entryReadOptions) : this.kv.get(kvKey);
+		let softTagCache = this._tagCache;
+		const softTagPrime = this._primeTagCache(softTags);
+		if (softTags.length > 0) {
+			const backgroundPrime = softTagPrime.catch(() => {});
+			const ctx = getRequestExecutionContext() ?? this.ctx;
+			if (ctx) ctx.waitUntil(backgroundPrime);
+		}
+		const raw = await entryRead;
 		if (!raw) return null;
 		let parsed;
 		try {
 			parsed = JSON.parse(raw);
 		} catch {
-			this._deleteInBackground(kvKey);
+			this._deleteEntryReadInBackground(kvKey);
 			return null;
 		}
 		const entry = validateCacheEntry(parsed);
 		if (!entry) {
 			console.error("[vinext] Invalid cache entry shape for key:", key);
-			this._deleteInBackground(kvKey);
+			this._deleteEntryReadInBackground(kvKey);
 			return null;
 		}
 		let restoredValue = null;
 		if (entry.value) {
 			restoredValue = restoreArrayBuffers(entry.value);
 			if (!restoredValue) {
-				this._deleteInBackground(kvKey);
+				this._deleteEntryReadInBackground(kvKey);
 				return null;
 			}
 		}
-		if (await this._hasRevalidatedTag(validUniqueTags(entry.tags), entry.lastModified)) {
-			this._deleteInBackground(kvKey);
+		const entryTags = validUniqueTags(entry.tags);
+		if (this._hasRevalidatedTag(entryTags, entry.lastModified, true)) {
+			this._deleteEntryReadInBackground(kvKey);
 			return null;
 		}
-		const softTags = validUniqueTags(readStringArrayField(_ctx, "softTags"));
-		if (await this._hasRevalidatedTag(softTags, entry.lastModified)) return null;
+		await softTagPrime;
+		while (softTagCache !== this._tagCache) {
+			softTagCache = this._tagCache;
+			await this._primeTagCache(softTags);
+		}
+		let invalidated = this._hasRevalidatedTag(entryTags, entry.lastModified, true);
+		if (!invalidated) {
+			await this._primeTagCache(entryTags);
+			while (softTagCache !== this._tagCache) {
+				softTagCache = this._tagCache;
+				await this._primeTagCache([.../* @__PURE__ */ new Set([...softTags, ...entryTags])]);
+			}
+			invalidated = this._hasRevalidatedTag(entryTags, entry.lastModified);
+		}
+		if (invalidated) {
+			this._deleteEntryReadInBackground(kvKey);
+			return null;
+		}
+		if (this._hasRevalidatedTag(softTags, entry.lastModified)) return null;
 		if (entry.expireAt !== void 0 && entry.expireAt !== null && Date.now() > entry.expireAt) {
-			this._deleteInBackground(kvKey);
+			this._deleteEntryReadInBackground(kvKey);
 			return null;
 		}
 		const now = Date.now();
@@ -164,37 +201,63 @@ var KVCacheHandler = class {
 		};
 	}
 	/**
-	* Check tag invalidation markers for stored tags or read-time soft tags.
-	* Uses a local in-memory cache to avoid redundant KV reads for recently-seen tags.
+	* Load the invalidation markers these tags still need into the local cache.
+	* Tags a recent read already cached cost nothing, so the entry-tag batch only
+	* pays for what the soft-tag batch did not already fetch.
 	*/
-	async _hasRevalidatedTag(tags, lastModified) {
-		if (tags.length === 0) return false;
+	async _primeTagCache(tags) {
+		if (tags.length === 0) return;
+		const tagCache = this._tagCache;
 		const now = Date.now();
-		const uncachedTags = [];
+		const missing = tags.filter((tag) => {
+			const cached = tagCache.get(tag);
+			if (cached && now - cached.fetchedAt < this._tagCacheTtl) return false;
+			if (cached) tagCache.delete(tag);
+			return true;
+		});
+		if (missing.length === 0) return;
+		const order = ++this._tagCacheOrder;
+		const markers = await this._readTagMarkers(missing.map((tag) => this._tagKey(tag)));
+		for (const tag of missing) {
+			const current = tagCache.get(tag);
+			if (current && current.order >= order) continue;
+			const marker = markers.get(this._tagKey(tag));
+			tagCache.set(tag, {
+				timestamp: marker ? Number(marker) : 0,
+				fetchedAt: now,
+				order
+			});
+		}
+	}
+	/**
+	* Read every marker key, one round trip per 100-key chunk.
+	*
+	* Markers never take the entry `cacheTtl`: `revalidateTag()` writes them, so
+	* a longer colo cache would hide a publish from that colo for its span. They
+	* keep KV's own default cacheTtl of 60 s.
+	*/
+	async _readTagMarkers(keys) {
+		if (keys.length === 1) return /* @__PURE__ */ new Map([[keys[0], await this.kv.get(keys[0])]]);
+		const chunks = [];
+		for (let i = 0; i < keys.length; i += KV_BULK_GET_LIMIT) chunks.push(keys.slice(i, i + KV_BULK_GET_LIMIT));
+		const results = await Promise.all(chunks.map((chunk) => this.kv.get(chunk)));
+		const markers = /* @__PURE__ */ new Map();
+		for (const result of results) for (const [key, value] of result) markers.set(key, value);
+		return markers;
+	}
+	/**
+	* Report whether any tag has an invalidation marker at or after `lastModified`.
+	* Call `_primeTagCache` for the same tags first — a tag with no cache entry
+	* counts as never invalidated. Pass `requireFresh` to call it before a prime,
+	* so an entry past `tagCacheTtlMs` does not answer for a tag it never re-read.
+	*/
+	_hasRevalidatedTag(tags, lastModified, requireFresh = false) {
+		const now = requireFresh ? Date.now() : 0;
 		for (const tag of tags) {
 			const cached = this._tagCache.get(tag);
-			if (cached && now - cached.fetchedAt < this._tagCacheTtl) {
-				if (Number.isNaN(cached.timestamp) || cached.timestamp >= lastModified) return true;
-			} else {
-				if (cached) this._tagCache.delete(tag);
-				uncachedTags.push(tag);
-			}
-		}
-		if (uncachedTags.length > 0) {
-			const tagResults = await Promise.all(uncachedTags.map((tag) => this.kv.get(this._tagKey(tag))));
-			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
-				});
-			}
-			for (const tag of uncachedTags) {
-				const cached = this._tagCache.get(tag);
-				if (!cached || cached.timestamp === 0) continue;
-				if (Number.isNaN(cached.timestamp) || cached.timestamp >= lastModified) return true;
-			}
+			if (!cached || cached.timestamp === 0) continue;
+			if (requireFresh && now - cached.fetchedAt >= this._tagCacheTtl) continue;
+			if (Number.isNaN(cached.timestamp) || cached.timestamp >= lastModified) return true;
 		}
 		return false;
 	}
@@ -243,10 +306,12 @@ var KVCacheHandler = class {
 		const tagList = Array.isArray(tags) ? tags : [tags];
 		const now = Date.now();
 		const validTags = tagList.filter((t) => validateTag(t) !== null);
-		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now), { expirationTtl: 720 * 3600 })));
+		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now), { expirationTtl: 2592e3 })));
+		const order = ++this._tagCacheOrder;
 		for (const tag of validTags) this._tagCache.set(tag, {
 			timestamp: now,
-			fetchedAt: now
+			fetchedAt: now,
+			order
 		});
 	}
 	/**
@@ -302,7 +367,15 @@ var KVCacheHandler = class {
 	* fresh KVCacheHandler per request or invoke this method explicitly.
 	*/
 	resetRequestCache() {
-		this._tagCache.clear();
+		this._tagCache = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Clean up a bad entry only when this read cannot be an explicitly cached
+	* older version of the shared KV value. KV has no conditional delete, so a
+	* cached read must remain a non-destructive miss.
+	*/
+	_deleteEntryReadInBackground(kvKey) {
+		if (!this._entryReadOptions) this._deleteInBackground(kvKey);
 	}
 	/**
 	* Fire a KV delete in the background.
@@ -453,7 +526,8 @@ const createKvDataCacheAdapter = ({ env, options }) => {
 	return new KVCacheHandler(namespace, {
 		appPrefix: options?.appPrefix,
 		ttlSeconds: options?.ttlSeconds,
-		tagCacheTtlMs: options?.tagCacheTtlMs
+		tagCacheTtlMs: options?.tagCacheTtlMs,
+		entryCacheTtlSeconds: options?.entryCacheTtlSeconds
 	});
 };
 //#endregion

package/dist/cache/kv-key.d.ts

@@ -1,7 +1,7 @@
 //#region src/cache/kv-key.d.ts
 /** Key prefix for cache entries. */
-declare const ENTRY_PREFIX = "cache:";
-type KvKeySpace = {
+export declare const ENTRY_PREFIX = "cache:";
+export type KvKeySpace = {
   /** Prefix shared by every cache entry, including entries with hashed logical keys. */
   entryPrefix: string;
   entryKey(logicalKey: string): string;
@@ -11,6 +11,5 @@ type KvKeySpace = {
  * Create the deterministic key namespace shared by runtime cache operations
  * and deploy-time prerender population.
  */
-declare function createKvKeySpace(appPrefix: string | undefined): KvKeySpace;
-//#endregion
-export { ENTRY_PREFIX, KvKeySpace, createKvKeySpace };
+export declare function createKvKeySpace(appPrefix: string | undefined): KvKeySpace;
+//#endregion

package/dist/cache/response-store-adapter.d.ts

@@ -0,0 +1,37 @@
+//#region src/cache/response-store-adapter.d.ts
+export type ResponseStoreAdapterOptions = {
+  mode?: "self-contained" | "service-binding";
+};
+/**
+ * Use Workers Response Store for both vinext response-stage and data caching.
+ * Service-binding mode keeps storage in a separate cache Worker. Self-contained
+ * mode keeps the same API and loopback in the application Worker.
+ */
+export declare function responseStoreAdapter(options?: ResponseStoreAdapterOptions): {
+  cdn: {
+    adapter: string;
+    output: {
+      entry: string;
+      matchesBuild({ plugins }: {
+        plugins: readonly {
+          name?: string;
+        }[];
+      }): boolean;
+      transformHostEntry({ code, id }: {
+        code: string;
+        id: string;
+      }): string | null;
+      type: "multi-stage";
+    };
+    capabilities: {
+      buildIdentity: "response-header";
+      isResponsePolicyHeader: (name: string) => boolean;
+      requestRouting: "uncached-stage";
+      warmup: "response-store";
+    };
+  };
+  data: {
+    adapter: string;
+  };
+};
+//#endregion

package/dist/cache/response-store-adapter.js

@@ -0,0 +1,39 @@
+import { fileURLToPath } from "node:url";
+//#region src/cache/response-store-adapter.ts
+const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
+/**
+* Use Workers Response Store for both vinext response-stage and data caching.
+* Service-binding mode keeps storage in a separate cache Worker. Self-contained
+* mode keeps the same API and loopback in the application Worker.
+*/
+function responseStoreAdapter(options = {}) {
+	const mode = options.mode ?? "service-binding";
+	if (mode !== "service-binding" && mode !== "self-contained") throw new Error(`Unknown Workers Response Store mode: ${String(mode)}`);
+	const workerEntry = fileURLToPath(import.meta.resolve(mode === "self-contained" ? "./response-store-adapter.self-contained.worker.js" : "./response-store-adapter.service-binding.worker.js"));
+	const entrypoints = mode === "self-contained" ? "CacheMetadata, ResponseStoreBinding, ResponseStoreRevalidator" : "ResponseStoreClient, ResponseStoreRevalidator";
+	return {
+		cdn: {
+			adapter: fileURLToPath(import.meta.resolve("./response-store-cdn.runtime.js")),
+			output: {
+				entry: workerEntry,
+				matchesBuild({ plugins }) {
+					return plugins.some(({ name }) => name === "vite-plugin-cloudflare" || name?.startsWith("vite-plugin-cloudflare:"));
+				},
+				transformHostEntry({ code, id }) {
+					if ((id.charCodeAt(0) === 0 ? id.slice(1) : id) !== CLOUDFLARE_WORKER_ENTRY_ID) return null;
+					return `${code}\nexport { ${entrypoints} } from ${JSON.stringify(workerEntry)};\n`;
+				},
+				type: "multi-stage"
+			},
+			capabilities: {
+				buildIdentity: "response-header",
+				isResponsePolicyHeader: (name) => name.toLowerCase() === "cdn-cache-control" || name.toLowerCase() === "cloudflare-cdn-cache-control",
+				requestRouting: "uncached-stage",
+				warmup: "response-store"
+			}
+		},
+		data: { adapter: fileURLToPath(import.meta.resolve("./response-store-data.runtime.js")) }
+	};
+}
+//#endregion
+export { responseStoreAdapter };

package/dist/cache/response-store-adapter.self-contained.worker.d.ts

@@ -0,0 +1,17 @@
+import { VinextResponseStoreEnv } from "./response-store-adapter.worker.js";
+import { ResponseStoreRevalidatorEntrypoint, WorkersResponseStoreEnv } from "@cloudflare/workers-response-store";
+import { CacheMetadata as CacheMetadata$1, ResponseStoreBinding as ResponseStoreBinding$1 } from "@cloudflare/workers-response-store/service";
+//#region src/cache/response-store-adapter.self-contained.worker.d.ts
+export declare const CacheMetadata: typeof CacheMetadata$1;
+export declare const ResponseStoreBinding: typeof ResponseStoreBinding$1;
+export declare const ResponseStoreRevalidator: ResponseStoreRevalidatorEntrypoint<WorkersResponseStoreEnv>;
+declare const _default: {
+  fetch(request: Request, env: VinextResponseStoreEnv, ctx: {
+    exports?: Record<string, unknown>;
+    passThroughOnException(): void;
+    props?: unknown;
+    waitUntil(promise: Promise<unknown>): void;
+  }): Promise<Response>;
+};
+//#endregion
+export { _default as default };

package/dist/cache/response-store-adapter.self-contained.worker.js

@@ -0,0 +1,10 @@
+import { createVinextResponseStoreHandler, createVinextResponseStoreOptions } from "./response-store-adapter.worker.js";
+import { createWorkersResponseStore } from "@cloudflare/workers-response-store";
+//#region src/cache/response-store-adapter.self-contained.worker.ts
+const responseStore = createWorkersResponseStore(createVinextResponseStoreOptions());
+const CacheMetadata = responseStore.entrypoints.CacheMetadata;
+const ResponseStoreBinding = responseStore.entrypoints.ResponseStoreBinding;
+const ResponseStoreRevalidator = responseStore.entrypoints.ResponseStoreRevalidator;
+var response_store_adapter_self_contained_worker_default = createVinextResponseStoreHandler(responseStore);
+//#endregion
+export { CacheMetadata, ResponseStoreBinding, ResponseStoreRevalidator, response_store_adapter_self_contained_worker_default as default };

package/dist/cache/response-store-adapter.service-binding.worker.d.ts

@@ -0,0 +1,15 @@
+import { VinextResponseStoreEnv } from "./response-store-adapter.worker.js";
+import { ResponseStoreClientEntrypoint, ResponseStoreRevalidatorEntrypoint, WorkersResponseStoreClientEnv } from "@cloudflare/workers-response-store";
+//#region src/cache/response-store-adapter.service-binding.worker.d.ts
+export declare const ResponseStoreClient: ResponseStoreClientEntrypoint;
+export declare const ResponseStoreRevalidator: ResponseStoreRevalidatorEntrypoint<WorkersResponseStoreClientEnv>;
+declare const _default: {
+  fetch(request: Request, env: VinextResponseStoreEnv, ctx: {
+    exports?: Record<string, unknown>;
+    passThroughOnException(): void;
+    props?: unknown;
+    waitUntil(promise: Promise<unknown>): void;
+  }): Promise<Response>;
+};
+//#endregion
+export { _default as default };

package/dist/cache/response-store-adapter.service-binding.worker.js

@@ -0,0 +1,9 @@
+import { createVinextResponseStoreHandler, createVinextResponseStoreOptions } from "./response-store-adapter.worker.js";
+import { createWorkersResponseStoreClient } from "@cloudflare/workers-response-store";
+//#region src/cache/response-store-adapter.service-binding.worker.ts
+const responseStore = createWorkersResponseStoreClient(createVinextResponseStoreOptions());
+const ResponseStoreClient = responseStore.entrypoints.ResponseStoreClient;
+const ResponseStoreRevalidator = responseStore.entrypoints.ResponseStoreRevalidator;
+var response_store_adapter_service_binding_worker_default = createVinextResponseStoreHandler(responseStore);
+//#endregion
+export { ResponseStoreClient, ResponseStoreRevalidator, response_store_adapter_service_binding_worker_default as default };

package/dist/cache/response-store-adapter.worker.d.ts

@@ -0,0 +1,14 @@
+import { WorkersResponseStore, WorkersResponseStoreClientEnv, WorkersResponseStoreEnv, WorkersResponseStoreOptions } from "@cloudflare/workers-response-store";
+//#region src/cache/response-store-adapter.worker.d.ts
+type WorkerExecutionContext = {
+  exports?: Record<string, unknown>;
+  passThroughOnException(): void;
+  props?: unknown;
+  waitUntil(promise: Promise<unknown>): void;
+};
+export type VinextResponseStoreEnv = WorkersResponseStoreClientEnv | WorkersResponseStoreEnv;
+export declare function createVinextResponseStoreOptions<Env extends VinextResponseStoreEnv>(): WorkersResponseStoreOptions<Env>;
+export declare function createVinextResponseStoreHandler(store: WorkersResponseStore): {
+  fetch(request: Request, env: VinextResponseStoreEnv, ctx: WorkerExecutionContext): Promise<Response>;
+};
+//#endregion