@vinext/cloudflare 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/cache/config.d.ts

@@ -0,0 +1,137 @@
+import { CloudflareConfig, WorkerConfig } from "@cloudflare/vite-plugin/experimental-config";
+//#region src/cache/config.d.ts
+type ResponseStoreStorageOptions = {
+  worker: string;
+  bucket: string;
+};
+export declare function createWorkersResponseStoreSelfContainedConfig(options: ResponseStoreStorageOptions): Promise<{
+  cache: {
+    enabled: true;
+  };
+  exports: {
+    CacheMetadata: {
+      state?: "created";
+      type: "durable-object";
+      storage: "sqlite";
+      container: undefined;
+    } | {
+      state?: "created";
+      type: "durable-object";
+      storage: "sqlite";
+      container: undefined;
+    };
+    ResponseStoreBinding: import("@cloudflare/vite-plugin/experimental-config").WorkerEntrypointExport;
+  };
+  env: {
+    CACHE_BODIES: import("@cloudflare/vite-plugin/experimental-config").R2Binding;
+    CACHE_METADATA: {
+      type: "durable-object";
+      worker: string;
+      exportName: string;
+    };
+    CF_VERSION_METADATA: import("@cloudflare/vite-plugin/experimental-config").VersionMetadataBinding;
+  };
+}>;
+export declare function createWorkersResponseStoreServiceBindingConfig(options: {
+  accountId?: CloudflareConfig["accountId"];
+  worker: {
+    name: string;
+    compatibilityDate: string;
+    compatibilityFlags?: string[];
+    observability?: WorkerConfig["observability"];
+  };
+  bucket: string;
+}): Promise<{
+  accountId: string | undefined;
+  serviceBindingWorker: {
+    cache: {
+      enabled: true;
+    };
+    exports: {
+      CacheMetadata: {
+        state?: "created";
+        type: "durable-object";
+        storage: "sqlite";
+        container: undefined;
+      } | {
+        state?: "created";
+        type: "durable-object";
+        storage: "sqlite";
+        container: undefined;
+      };
+      ResponseStoreBinding: import("@cloudflare/vite-plugin/experimental-config").WorkerEntrypointExport;
+    };
+    env: {
+      CACHE_BODIES: import("@cloudflare/vite-plugin/experimental-config").R2Binding;
+      CACHE_METADATA: {
+        type: "durable-object";
+        worker: string;
+        exportName: string;
+      };
+    };
+    name: string;
+    compatibilityDate: string;
+    compatibilityFlags?: string[];
+    observability?: WorkerConfig["observability"];
+    entrypoint: string;
+    workersDev: false;
+    previewUrls: false;
+  };
+  applicationWorker: {
+    cache: {
+      enabled: false;
+    };
+    env: {
+      RESPONSE_STORE: import("@cloudflare/vite-plugin/experimental-config").WorkerBinding<{
+        cache: {
+          enabled: true;
+        };
+        exports: {
+          CacheMetadata: {
+            state?: "created";
+            type: "durable-object";
+            storage: "sqlite";
+            container: undefined;
+          } | {
+            state?: "created";
+            type: "durable-object";
+            storage: "sqlite";
+            container: undefined;
+          };
+          ResponseStoreBinding: import("@cloudflare/vite-plugin/experimental-config").WorkerEntrypointExport;
+        };
+        env: {
+          CACHE_BODIES: import("@cloudflare/vite-plugin/experimental-config").R2Binding;
+          CACHE_METADATA: {
+            type: "durable-object";
+            worker: string;
+            exportName: string;
+          };
+        };
+        name: string;
+        compatibilityDate: string;
+        compatibilityFlags?: string[];
+        observability?: WorkerConfig["observability"];
+        entrypoint: string;
+        workersDev: false;
+        previewUrls: false;
+      }, "ResponseStoreService">;
+      CF_VERSION_METADATA: import("@cloudflare/vite-plugin/experimental-config").VersionMetadataBinding;
+    };
+  };
+}>;
+export declare function createWorkersCacheConfig({ versionMetadataBinding }?: {
+  versionMetadataBinding?: string;
+}): Promise<{
+  cache: {
+    enabled: false;
+  };
+  env: {
+    [versionMetadataBinding]: import("@cloudflare/vite-plugin/experimental-config").VersionMetadataBinding;
+  };
+  exports: {
+    VinextCachedResponse: import("@cloudflare/vite-plugin/experimental-config").WorkerEntrypointExport;
+    VinextUncachedResponse: import("@cloudflare/vite-plugin/experimental-config").WorkerEntrypointExport;
+  };
+}>;
+//#endregion

package/dist/cache/config.js

@@ -0,0 +1,87 @@
+//#region src/cache/config.ts
+const RESPONSE_STORE_BINDING = "RESPONSE_STORE";
+const RESPONSE_STORE_ENTRYPOINT = "ResponseStoreService";
+const DEFAULT_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+const CACHE_BODIES_BINDING = "CACHE_BODIES";
+const CACHE_METADATA_BINDING = "CACHE_METADATA";
+const CACHE_METADATA_CLASS = "CacheMetadata";
+const RESPONSE_STORE_CACHE_ENTRYPOINT = "ResponseStoreBinding";
+const RESPONSE_STORE_SERVICE_ENTRYPOINT = "@cloudflare/workers-response-store/service";
+async function createResponseStoreWorkerConfig(options) {
+	const { bindings, exports } = await import("@cloudflare/vite-plugin/experimental-config");
+	return {
+		cache: { enabled: true },
+		exports: {
+			[CACHE_METADATA_CLASS]: {
+				...exports.durableObject({ storage: "sqlite" }),
+				storage: "sqlite",
+				container: void 0
+			},
+			[RESPONSE_STORE_CACHE_ENTRYPOINT]: exports.worker({ cache: { enabled: true } })
+		},
+		env: {
+			[CACHE_BODIES_BINDING]: bindings.r2({ name: options.bucket }),
+			[CACHE_METADATA_BINDING]: {
+				...bindings.durableObject({
+					worker: options.worker,
+					exportName: CACHE_METADATA_CLASS
+				}),
+				worker: options.worker,
+				exportName: CACHE_METADATA_CLASS
+			}
+		}
+	};
+}
+async function createWorkersResponseStoreSelfContainedConfig(options) {
+	const { bindings } = await import("@cloudflare/vite-plugin/experimental-config");
+	const storage = await createResponseStoreWorkerConfig(options);
+	return {
+		...storage,
+		env: {
+			...storage.env,
+			[DEFAULT_VERSION_METADATA_BINDING]: bindings.versionMetadata()
+		}
+	};
+}
+async function createWorkersResponseStoreServiceBindingConfig(options) {
+	const { bindings } = await import("@cloudflare/vite-plugin/experimental-config");
+	const storage = await createResponseStoreWorkerConfig({
+		worker: options.worker.name,
+		bucket: options.bucket
+	});
+	const serviceBindingWorker = {
+		...options.worker,
+		entrypoint: RESPONSE_STORE_SERVICE_ENTRYPOINT,
+		workersDev: false,
+		previewUrls: false,
+		...storage
+	};
+	return {
+		accountId: options.accountId,
+		serviceBindingWorker,
+		applicationWorker: {
+			cache: { enabled: false },
+			env: {
+				[RESPONSE_STORE_BINDING]: bindings.worker({
+					worker: serviceBindingWorker,
+					exportName: RESPONSE_STORE_ENTRYPOINT
+				}),
+				[DEFAULT_VERSION_METADATA_BINDING]: bindings.versionMetadata()
+			}
+		}
+	};
+}
+async function createWorkersCacheConfig({ versionMetadataBinding = DEFAULT_VERSION_METADATA_BINDING } = {}) {
+	if (versionMetadataBinding.length === 0) throw new TypeError("versionMetadataBinding must be a non-empty string");
+	const { bindings, exports } = await import("@cloudflare/vite-plugin/experimental-config");
+	return {
+		cache: { enabled: false },
+		env: { [versionMetadataBinding]: bindings.versionMetadata() },
+		exports: {
+			VinextCachedResponse: exports.worker({ cache: { enabled: true } }),
+			VinextUncachedResponse: exports.worker({ cache: { enabled: false } })
+		}
+	};
+}
+//#endregion
+export { createWorkersCacheConfig, createWorkersResponseStoreSelfContainedConfig, createWorkersResponseStoreServiceBindingConfig };

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

@@ -1,11 +1,32 @@
 //#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 = {
-  /** 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). */
-  appPrefix?: string; /** Default KV `expirationTtl` in seconds. @default 2592000 (30 days) */
-  ttlSeconds?: number; /** TTL in milliseconds for the in-memory tag-invalidation cache. @default 5000 */
+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). */
+  appPrefix?: string;
+  /** Default KV `expirationTtl` in seconds. @default 2592000 (30 days) */
+  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.
@@ -20,9 +41,12 @@ type KvDataAdapterOptions = {
  * }
  * ```
  */
-declare function kvDataAdapter(options?: KvDataAdapterOptions): {
+export declare function kvDataAdapter(options?: KvDataAdapterOptions): {
   adapter: string;
   options: KvDataAdapterOptions | undefined;
+  capabilities: {
+    buildIdentity: "response-header";
+    warmup: "data-cache";
+  };
 };
-//#endregion
-export { DEFAULT_KV_DATA_CACHE_BINDING, KvDataAdapterOptions, kvDataAdapter };
+//#endregion

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

@@ -18,7 +18,11 @@ function kvDataAdapter(options) {
 	if (options?.binding !== void 0 && typeof options.binding !== "string") throw new TypeError("[vinext] kvDataAdapter({ binding }) must be a string KV binding name.");
 	return {
 		adapter: fileURLToPath(import.meta.resolve("./kv-data-adapter.runtime.js")),
-		options
+		options,
+		capabilities: {
+			buildIdentity: "response-header",
+			warmup: "data-cache"
+		}
 	};
 }
 //#endregion

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

@@ -1,15 +1,21 @@
 import { KvDataAdapterOptions } from "./kv-data-adapter.js";
+import { ENTRY_PREFIX } from "./kv-key.js";
 import { ExecutionContextLike } from "vinext/shims/request-context";
 import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
-
 //#region src/cache/kv-data-adapter.runtime.d.ts
 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>;
@@ -28,8 +34,6 @@ type KVNamespace = {
     cursor?: string;
   }>;
 };
-/** Key prefix for cache entries. */
-declare const ENTRY_PREFIX = "cache:";
 /**
  * Cloudflare KV data cache handler.
  *
@@ -51,25 +55,50 @@ declare const ENTRY_PREFIX = "cache:";
  * 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 prefix;
+  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. */
+    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>;
@@ -108,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
@@ -124,12 +159,9 @@ declare class KVCacheHandler implements CacheHandler {
    */
   private _put;
 }
-declare const createKvDataCacheAdapter: ({
-  env,
-  options
-}: {
+declare const createKvDataCacheAdapter: ({ env, options }: {
   env?: Record<string, unknown>;
   options?: KvDataAdapterOptions;
 }) => CacheHandler;
 //#endregion
-export { ENTRY_PREFIX, KVCacheHandler, createKvDataCacheAdapter as default };
+export { ENTRY_PREFIX, createKvDataCacheAdapter as default };