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

package/dist/cache/cdn-adapter.worker.js

@@ -0,0 +1,371 @@
+import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
+import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_RSC_VARY_HEADER } from "vinext/internal/server/headers";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { loadVinextRequestStage } from "vinext/server/request-stage";
+import { loadVinextResponseStage } from "vinext/server/response-stage";
+//#region src/cache/cdn-adapter.worker.ts
+const CACHED_RESPONSE_STAGE_EXPORT = "VinextCachedResponse";
+const UNCACHED_RESPONSE_STAGE_EXPORT = "VinextUncachedResponse";
+const AUTHORIZATION_TRANSPORT_HEADER = "x-vinext-internal-authorization";
+const REQUEST_CACHE_CONTROL_TRANSPORT_HEADER = "x-vinext-internal-request-cache-control";
+const REQUEST_CF_TRANSPORT_HEADER = "x-vinext-internal-request-cf";
+const REQUEST_PRAGMA_TRANSPORT_HEADER = "x-vinext-internal-request-pragma";
+const CLOUDFLARE_EDGE_POLICY_HEADER = "Cloudflare-CDN-Cache-Control";
+const SHARED_RESPONSE_STAGE_HEADER = "x-vinext-cloudflare-shared-response-stage";
+const RESPONSE_STAGE_WIRE_CACHE = {
+	bypass: "vinext-cloudflare-v1:bypass",
+	shared: "vinext-cloudflare-v1:shared"
+};
+const FRAMEWORK_RESPONSE_VARY_FIELDS = new Set(VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase()));
+function isResponseStageReadinessRequest(request) {
+	return request.url.includes(VINEXT_PRERENDER_READINESS_PATH) && new URL(request.url).pathname === VINEXT_PRERENDER_READINESS_PATH;
+}
+function responseStageUnavailable() {
+	return new Response(null, {
+		status: 503,
+		headers: { "Cache-Control": "no-store" }
+	});
+}
+/** Stamp the entrypoint that actually produced a response, before Workers Cache stores it. */
+function stampResponseStageBuildIdentity(response) {
+	const buildIdentity = getVinextCdnBuildIdentity();
+	if (!buildIdentity) return response;
+	try {
+		response.headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+		return response;
+	} catch {
+		const headers = new Headers(response.headers);
+		headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+		const webSocket = response.webSocket;
+		if (!webSocket && (response.status < 200 || response.status > 599)) {
+			const unavailable = responseStageUnavailable();
+			unavailable.headers.set(VINEXT_CDN_BUILD_ID_HEADER, buildIdentity);
+			return unavailable;
+		}
+		const init = {
+			headers,
+			status: response.status,
+			statusText: response.statusText
+		};
+		if (webSocket) init.webSocket = webSocket;
+		return new Response(response.body, init);
+	}
+}
+/** Reject a response routed to an entrypoint from another propagating build. */
+function validateResponseStageBuildIdentity(response) {
+	const expectedBuildIdentity = getVinextCdnBuildIdentity();
+	if (!expectedBuildIdentity || response.headers.get("X-Vinext-Build-Id") === expectedBuildIdentity) return response;
+	response.body?.cancel().catch(() => {});
+	return responseStageUnavailable();
+}
+function stripUntrustedTransportHeaders(request) {
+	if (!request.headers.has(AUTHORIZATION_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CF_TRANSPORT_HEADER) && !request.headers.has(REQUEST_PRAGMA_TRANSPORT_HEADER)) return request;
+	const headers = new Headers(request.headers);
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	const sanitized = new Request(request, { headers });
+	const requestCf = Reflect.get(request, "cf");
+	if (requestCf !== void 0) Object.defineProperty(sanitized, "cf", {
+		configurable: true,
+		enumerable: true,
+		value: requestCf
+	});
+	return sanitized;
+}
+function withWorkerHostRuntime(context, env) {
+	const candidateAssets = env && typeof env === "object" && Reflect.has(env, "ASSETS") ? Reflect.get(env, "ASSETS") : void 0;
+	const assets = candidateAssets && (typeof candidateAssets === "object" || typeof candidateAssets === "function") && Reflect.has(candidateAssets, "fetch") && typeof Reflect.get(candidateAssets, "fetch") === "function" ? candidateAssets : context?.assets;
+	return {
+		...assets === void 0 ? {} : { assets },
+		...context?.cache === void 0 ? {} : { cache: context.cache },
+		...context?.exports === void 0 ? {} : { exports: context.exports },
+		hostRuntime: "worker",
+		...typeof context?.passThroughOnException === "function" ? { passThroughOnException: () => context.passThroughOnException?.() } : {},
+		...context?.props === void 0 ? {} : { props: context.props },
+		...typeof context?.waitUntil === "function" ? { waitUntil: (promise) => context.waitUntil?.(promise) } : {}
+	};
+}
+function hasFetch(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && "fetch" in value && typeof value.fetch === "function";
+}
+function hasPurge(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && "purge" in value && typeof value.purge === "function";
+}
+function getResponseStageBinding(context, exportName, serializedInvocation) {
+	const binding = context.exports?.[exportName];
+	if (typeof binding !== "function") return null;
+	const target = binding({ props: JSON.parse(serializedInvocation) });
+	return hasFetch(target) ? target : null;
+}
+async function createCacheFacingRequest(request, serializedInvocation) {
+	const authorization = request.headers.get("Authorization");
+	let serializedRequestCf = null;
+	const requestCf = Reflect.get(request, "cf");
+	if (requestCf !== void 0) try {
+		const json = JSON.stringify(requestCf);
+		if (json !== void 0) serializedRequestCf = encodeURIComponent(json);
+	} catch {}
+	const authorizationIdentity = authorization === null ? "absent" : `present:${authorization.length}:${authorization}`;
+	const frameworkVaryIdentity = JSON.stringify([...FRAMEWORK_RESPONSE_VARY_FIELDS].map((name) => [name, request.headers.get(name)]));
+	const responseStageBuildIdentity = getVinextCdnBuildIdentity() ?? "";
+	const bytes = new TextEncoder().encode(`${request.url}\0${serializedInvocation}\0${authorizationIdentity}\0${frameworkVaryIdentity}\0${responseStageBuildIdentity}`);
+	const key = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	const url = new URL(request.url);
+	url.searchParams.set("__vinext_cache_key", key);
+	const headers = new Headers(request.headers);
+	const requestCacheControl = headers.get("Cache-Control");
+	const requestPragma = headers.get("Pragma");
+	headers.delete("Cache-Control");
+	headers.delete("Pragma");
+	headers.delete("Authorization");
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	if (authorization !== null) headers.set(AUTHORIZATION_TRANSPORT_HEADER, encodeURIComponent(authorization));
+	if (serializedRequestCf !== null) headers.set(REQUEST_CF_TRANSPORT_HEADER, serializedRequestCf);
+	if (requestCacheControl !== null) headers.set(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER, encodeURIComponent(requestCacheControl));
+	if (requestPragma !== null) headers.set(REQUEST_PRAGMA_TRANSPORT_HEADER, encodeURIComponent(requestPragma));
+	return new Request(url, {
+		cf: { vary: { default: { action: "passthrough" } } },
+		headers,
+		method: request.method
+	});
+}
+function restoreResponseStageRequest(request, requestUrl, requestMethod) {
+	const headers = new Headers(request.headers);
+	const serializedAuthorization = headers.get(AUTHORIZATION_TRANSPORT_HEADER);
+	const serializedRequestCacheControl = headers.get(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	const serializedRequestCf = headers.get(REQUEST_CF_TRANSPORT_HEADER);
+	const serializedRequestPragma = headers.get(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	headers.delete("Cache-Control");
+	headers.delete("Pragma");
+	headers.delete("Authorization");
+	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
+	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
+	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	if (serializedAuthorization !== null) try {
+		headers.set("Authorization", decodeURIComponent(serializedAuthorization));
+	} catch {}
+	let requestCf;
+	if (serializedRequestCf !== null) try {
+		requestCf = JSON.parse(decodeURIComponent(serializedRequestCf));
+	} catch {}
+	if (serializedRequestCacheControl !== null) try {
+		headers.set("Cache-Control", decodeURIComponent(serializedRequestCacheControl));
+	} catch {}
+	if (serializedRequestPragma !== null) try {
+		headers.set("Pragma", decodeURIComponent(serializedRequestPragma));
+	} catch {}
+	const restored = new Request(new Request(requestUrl, request), {
+		headers,
+		method: requestMethod
+	});
+	let didAccessRequestCf = false;
+	if (requestCf !== void 0) Object.defineProperty(restored, "cf", {
+		configurable: true,
+		enumerable: true,
+		get() {
+			didAccessRequestCf = true;
+			return requestCf;
+		}
+	});
+	return {
+		didAccessRequestCf: () => didAccessRequestCf,
+		request: restored
+	};
+}
+function preventResponseCaching(response) {
+	const headers = new Headers(response.headers);
+	headers.set("Cache-Control", "no-store");
+	headers.delete("CDN-Cache-Control");
+	headers.delete("Cloudflare-CDN-Cache-Control");
+	headers.delete("Cache-Tag");
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+/**
+* Cloudflare consumes its private cache policy before returning a cached
+* entrypoint response. Strip it here as well for uncached/local fallbacks so
+* the outer gateway never forwards an inner shared-cache policy after adding
+* request-specific middleware or routing headers.
+*/
+function markSharedResponseStage(response, provenanceToken, exposeEntrypointCacheStatus = false) {
+	const headers = new Headers(response.headers);
+	const cacheStatus = exposeEntrypointCacheStatus ? headers.get("CF-Cache-Status") : null;
+	headers.set(SHARED_RESPONSE_STAGE_HEADER, cacheStatus ? `${provenanceToken}:${encodeURIComponent(cacheStatus)}` : provenanceToken);
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function finalizeGatewayResponse(response, provenanceToken) {
+	const provenance = response.headers.get(SHARED_RESPONSE_STAGE_HEADER);
+	const usedSharedResponseStage = provenance === provenanceToken || provenance?.startsWith(`${provenanceToken}:`) === true;
+	const sharedResponseStageCollision = provenance !== null && !usedSharedResponseStage;
+	const cacheControl = response.headers.get("Cache-Control");
+	if (!response.headers.has(CLOUDFLARE_EDGE_POLICY_HEADER) && !usedSharedResponseStage && !sharedResponseStageCollision) return response;
+	const headers = new Headers(response.headers);
+	headers.delete(SHARED_RESPONSE_STAGE_HEADER);
+	headers.delete(CLOUDFLARE_EDGE_POLICY_HEADER);
+	if (usedSharedResponseStage || sharedResponseStageCollision) {
+		headers.delete("CDN-Cache-Control");
+		headers.delete("Cache-Tag");
+		headers.delete(VINEXT_CACHE_HEADER);
+		headers.delete(NEXTJS_CACHE_HEADER);
+		if (!cacheControl || !isNonCacheableCacheControl(cacheControl)) headers.set("Cache-Control", "private, max-age=0, must-revalidate");
+	}
+	if (usedSharedResponseStage && provenance?.startsWith(`${provenanceToken}:`)) {
+		const cacheStatus = decodeURIComponent(provenance.slice(provenanceToken.length + 1));
+		headers.set(VINEXT_CACHE_HEADER, cacheStatus);
+		headers.set(NEXTJS_CACHE_HEADER, cacheStatus);
+	}
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function hasTaggedCustomVary(response) {
+	if (!response.headers.get("Cache-Tag")) return false;
+	return (response.headers.get("Vary") ?? "").split(",").map((name) => name.trim().toLowerCase()).filter(Boolean).some((name) => !FRAMEWORK_RESPONSE_VARY_FIELDS.has(name));
+}
+function withResponseStagePurge(context) {
+	const factory = context.exports?.[CACHED_RESPONSE_STAGE_EXPORT];
+	if (typeof factory !== "function") return context;
+	const fallback = context.cache;
+	return {
+		...context,
+		cache: { purge(options) {
+			const target = factory({ props: {} });
+			if (hasPurge(target)) return target.purge(options);
+			return hasPurge(fallback) ? fallback.purge(options) : void 0;
+		} }
+	};
+}
+function getResponseStageInvocation(value, expectedCache) {
+	if (!value || typeof value !== "object") return null;
+	const expectedResponseStageBuildIdentity = Reflect.get(value, "expectedResponseStageBuildIdentity");
+	if (expectedResponseStageBuildIdentity !== void 0 && typeof expectedResponseStageBuildIdentity !== "string") return null;
+	const options = Reflect.get(value, "options");
+	if (!options || typeof options !== "object") return null;
+	const wireCache = Reflect.get(options, "cache");
+	let cache;
+	if (expectedResponseStageBuildIdentity !== void 0 && wireCache === RESPONSE_STAGE_WIRE_CACHE.shared) cache = "shared";
+	else if (expectedResponseStageBuildIdentity !== void 0 && wireCache === RESPONSE_STAGE_WIRE_CACHE.bypass) cache = "bypass";
+	else if (expectedResponseStageBuildIdentity === void 0 && getVinextCdnBuildIdentity() === null && (wireCache === "shared" || wireCache === "bypass")) cache = wireCache;
+	else return null;
+	if (expectedCache !== void 0 && cache !== expectedCache) return null;
+	const requestUrl = Reflect.get(value, "requestUrl");
+	if (typeof requestUrl !== "string") return null;
+	const requestMethod = Reflect.get(value, "requestMethod");
+	if (typeof requestMethod !== "string" || requestMethod.length === 0) return null;
+	try {
+		new URL(requestUrl);
+	} catch {
+		return null;
+	}
+	return {
+		...typeof expectedResponseStageBuildIdentity === "string" ? { expectedResponseStageBuildIdentity } : {},
+		options: {
+			...options,
+			cache
+		},
+		props: Reflect.get(value, "props"),
+		requestMethod,
+		requestUrl
+	};
+}
+async function invokeResponseStage(request, env, context, invocation) {
+	const dispatchResponseStage = (stageRequest, props, options) => invokeResponseStage(stageRequest, env, context, {
+		options,
+		props,
+		requestMethod: stageRequest.method,
+		requestUrl: stageRequest.url
+	});
+	const dispatchRequestStage = async (stageRequest) => {
+		const { handleRequestStage } = await loadVinextRequestStage();
+		return handleRequestStage(stageRequest, env, context, dispatchResponseStage);
+	};
+	const { handleResponseStage } = await loadVinextResponseStage();
+	return handleResponseStage(request, env, context, invocation.props, dispatchRequestStage, invocation.options);
+}
+/** Cache-bearing entrypoint. Workers Cache HITs bypass this class entirely. */
+var VinextCachedResponse = class extends WorkerEntrypoint {
+	async fetch(request) {
+		const context = withWorkerHostRuntime(this.ctx, this.env);
+		const invocation = getResponseStageInvocation(context.props, "shared");
+		if (!invocation) return stampResponseStageBuildIdentity(new Response("Invalid vinext response-stage invocation", {
+			status: 400,
+			headers: { "Cache-Control": "no-store" }
+		}));
+		if (invocation.expectedResponseStageBuildIdentity !== void 0 && invocation.expectedResponseStageBuildIdentity !== getVinextCdnBuildIdentity()) return stampResponseStageBuildIdentity(responseStageUnavailable());
+		const restored = restoreResponseStageRequest(request, invocation.requestUrl, invocation.requestMethod);
+		const response = await invokeResponseStage(restored.request, this.env, context, invocation);
+		return stampResponseStageBuildIdentity(restored.didAccessRequestCf() || hasTaggedCustomVary(response) ? preventResponseCaching(response) : response);
+	}
+	async purge(options) {
+		const cache = Reflect.get(this.ctx, "cache");
+		if (!hasPurge(cache)) return void 0;
+		return cache.purge(options);
+	}
+};
+/** Uncached response entrypoint. Bypass and probe renders execute only here. */
+var VinextUncachedResponse = class extends WorkerEntrypoint {
+	async fetch(request) {
+		const context = withResponseStagePurge(withWorkerHostRuntime(this.ctx, this.env));
+		const invocation = getResponseStageInvocation(context.props, "bypass");
+		if (!invocation) return stampResponseStageBuildIdentity(new Response("Invalid vinext response-stage invocation", {
+			status: 400,
+			headers: { "Cache-Control": "no-store" }
+		}));
+		if (invocation.expectedResponseStageBuildIdentity !== void 0 && invocation.expectedResponseStageBuildIdentity !== getVinextCdnBuildIdentity()) return stampResponseStageBuildIdentity(responseStageUnavailable());
+		return stampResponseStageBuildIdentity(await invokeResponseStage(request, this.env, context, invocation));
+	}
+};
+/** Uncached gateway: request routing and middleware always execute here. */
+var cdn_adapter_worker_default = { async fetch(request, env, context) {
+	request = stripUntrustedTransportHeaders(request);
+	const sharedResponseStageProvenance = crypto.randomUUID();
+	const stageContext = withResponseStagePurge(withWorkerHostRuntime(context, env));
+	const dispatchResponseStage = async (stageRequest, props, options) => {
+		const expectedResponseStageBuildIdentity = getVinextCdnBuildIdentity();
+		const invocation = {
+			...expectedResponseStageBuildIdentity === null ? {} : { expectedResponseStageBuildIdentity },
+			options,
+			props,
+			requestMethod: stageRequest.method,
+			requestUrl: stageRequest.url
+		};
+		const usesSharedCache = options.cache === "shared";
+		try {
+			const serializedInvocation = JSON.stringify({
+				...invocation,
+				options: expectedResponseStageBuildIdentity === null ? options : {
+					...options,
+					cache: RESPONSE_STAGE_WIRE_CACHE[options.cache]
+				}
+			});
+			const binding = getResponseStageBinding(stageContext, usesSharedCache ? CACHED_RESPONSE_STAGE_EXPORT : UNCACHED_RESPONSE_STAGE_EXPORT, serializedInvocation);
+			if (!binding) return responseStageUnavailable();
+			const entrypointRequest = usesSharedCache ? await createCacheFacingRequest(stageRequest, serializedInvocation) : stageRequest;
+			const response = validateResponseStageBuildIdentity(await binding.fetch(entrypointRequest));
+			return usesSharedCache ? markSharedResponseStage(response, sharedResponseStageProvenance, true) : response;
+		} catch (error) {
+			if (isResponseStageReadinessRequest(stageRequest)) return responseStageUnavailable();
+			throw error;
+		}
+	};
+	const { handleRequestStage } = await loadVinextRequestStage();
+	return finalizeGatewayResponse(await handleRequestStage(request, env, stageContext, dispatchResponseStage), sharedResponseStageProvenance);
+} };
+//#endregion
+export { VinextCachedResponse, VinextUncachedResponse, cdn_adapter_worker_default as default };

package/dist/cache/cdn-build-id.d.ts

@@ -0,0 +1,6 @@
+//#region src/cache/cdn-build-id.d.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+export declare const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+/** Opaque identity shared by every server entry emitted by one vinext build. */
+export declare function getVinextCdnBuildIdentity(): string | null;
+//#endregion

package/dist/cache/cdn-build-id.js

@@ -0,0 +1,9 @@
+//#region src/cache/cdn-build-id.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+/** Opaque identity shared by every server entry emitted by one vinext build. */
+function getVinextCdnBuildIdentity() {
+	return process.env.__VINEXT_RSC_BUILD_IDENTITY || process.env.__VINEXT_BUILD_ID || null;
+}
+//#endregion
+export { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity };

package/dist/cache/kv-data-adapter.d.ts

@@ -1,7 +1,7 @@
 //#region src/cache/kv-data-adapter.d.ts
-declare const DEFAULT_KV_DATA_CACHE_BINDING = "VINEXT_KV_CACHE";
+export declare const DEFAULT_KV_DATA_CACHE_BINDING = "VINEXT_KV_CACHE";
 /** Options accepted by {@link kvDataAdapter}, forwarded to the runtime factory. */
-type KvDataAdapterOptions = {
+export type KvDataAdapterOptions = {
   /** KV namespace binding name on the Worker `env`. @default "VINEXT_KV_CACHE" */
   binding?: string;
   /** Namespace prefix for cache keys (isolates multiple apps in one namespace). */
@@ -10,6 +10,23 @@ type KvDataAdapterOptions = {
   ttlSeconds?: number;
   /** TTL in milliseconds for the in-memory tag-invalidation cache. @default 5000 */
   tagCacheTtlMs?: number;
+  /**
+   * KV `cacheTtl` in seconds for entry reads, letting a colo answer a repeat
+   * read from its own cache instead of the central store. The runtime rejects
+   * a value below 30, so lower values are raised to 30.
+   *
+   * Trade-off: after a `set()`, a colo that already cached the key can serve
+   * the superseded value for up to this long.
+   *
+   * It applies to entry reads only. Tag markers, which `revalidateTag()` and
+   * `revalidatePath()` write, keep KV's own default cacheTtl of 60 s rather
+   * than this longer one, so this option never widens the window in which a
+   * colo can miss a publish. That window stays `tagCacheTtlMs` plus whatever
+   * the KV default cache holds, with or without this option.
+   *
+   * @default undefined (entry reads keep KV's default cacheTtl of 60 s)
+   */
+  entryCacheTtlSeconds?: number;
 };
 /**
  * Cloudflare KV data cache.
@@ -24,9 +41,8 @@ type KvDataAdapterOptions = {
  * }
  * ```
  */
-declare function kvDataAdapter(options?: KvDataAdapterOptions): {
+export declare function kvDataAdapter(options?: KvDataAdapterOptions): {
   adapter: string;
   options: KvDataAdapterOptions | undefined;
 };
-//#endregion
-export { DEFAULT_KV_DATA_CACHE_BINDING, KvDataAdapterOptions, kvDataAdapter };
+//#endregion

package/dist/cache/kv-data-adapter.runtime.d.ts

@@ -6,10 +6,16 @@ import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "vinext/s
 type KVNamespace = {
   get(key: string, options?: {
     type?: string;
+    cacheTtl?: number;
   }): Promise<string | null>;
   get(key: string, options: {
     type: "arrayBuffer";
   }): Promise<ArrayBuffer | null>;
+  /** Bulk read, capped at 100 keys per call. */
+  get(keys: string[], options?: {
+    type?: string;
+    cacheTtl?: number;
+  }): Promise<Map<string, string | null>>;
   put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
     expirationTtl?: number;
     metadata?: Record<string, unknown>;
@@ -49,28 +55,50 @@ type KVNamespace = {
  * the first request. This class stays exported for the runtime factory and for
  * backwards compatibility, but is not the recommended consumer API.
  */
-declare class KVCacheHandler implements CacheHandler {
+export declare class KVCacheHandler implements CacheHandler {
   private kv;
   private keySpace;
   private ctx;
   private ttlSeconds;
   /** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
   private _tagCache;
+  /** Monotonic ordering for concurrent tag-cache fills and local invalidations. */
+  private _tagCacheOrder;
   /** TTL (ms) for local tag cache entries. After this, re-fetch from KV. */
   private _tagCacheTtl;
+  /** Read options for entry keys only. `undefined` keeps the KV default cacheTtl. */
+  private _entryReadOptions;
   constructor(kvNamespace: KVNamespace, options?: {
     appPrefix?: string;
     ctx?: ExecutionContextLike;
     ttlSeconds?: number;
     /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
     tagCacheTtlMs?: number;
+    /** KV `cacheTtl` in seconds for entry reads. Off by default, never used for tag markers. */
+    entryCacheTtlSeconds?: number;
   });
   private _entryKey;
   private _tagKey;
   get(key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   /**
-   * 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.
+   */
+  private _primeTagCache;
+  /**
+   * 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.
+   */
+  private _readTagMarkers;
+  /**
+   * 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.
    */
   private _hasRevalidatedTag;
   set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
@@ -109,6 +137,12 @@ declare class KVCacheHandler implements CacheHandler {
    * fresh KVCacheHandler per request or invoke this method explicitly.
    */
   resetRequestCache(): void;
+  /**
+   * 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.
+   */
+  private _deleteEntryReadInBackground;
   /**
    * Fire a KV delete in the background.
    * Prefers the per-request ExecutionContext from ALS (set by
@@ -130,4 +164,4 @@ declare const createKvDataCacheAdapter: ({ env, options }: {
   options?: KvDataAdapterOptions;
 }) => CacheHandler;
 //#endregion
-export { ENTRY_PREFIX, KVCacheHandler, createKvDataCacheAdapter as default };
+export { ENTRY_PREFIX, createKvDataCacheAdapter as default };