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

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

@@ -1,4 +1,5 @@
 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";
 
@@ -28,8 +29,6 @@ type KVNamespace = {
     cursor?: string;
   }>;
 };
-/** Key prefix for cache entries. */
-declare const ENTRY_PREFIX = "cache:";
 /**
  * Cloudflare KV data cache handler.
  *
@@ -53,7 +52,7 @@ declare const ENTRY_PREFIX = "cache:";
  */
 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. */
@@ -66,6 +65,8 @@ declare class KVCacheHandler implements CacheHandler {
     ttlSeconds?: number; /** TTL in milliseconds for the local tag cache. Defaults to 5000ms. */
     tagCacheTtlMs?: 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.

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

@@ -1,6 +1,7 @@
+import { ENTRY_PREFIX, createKvKeySpace } from "./kv-key.js";
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
-import { Buffer } from "node:buffer";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
+import { Buffer } from "node:buffer";
 //#region src/cache/kv-data-adapter.runtime.ts
 /**
 * Cloudflare KV data cache — implementation + runtime factory.
@@ -23,10 +24,6 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 */
 /** Default KV namespace binding name read from the Worker `env`. */
 const DEFAULT_BINDING = "VINEXT_KV_CACHE";
-/** Key prefix for tag invalidation timestamps. */
-const TAG_PREFIX = "__tag:";
-/** Key prefix for cache entries. */
-const ENTRY_PREFIX = "cache:";
 /** Prefix used by revalidatePath for path-based tags. */
 const PATH_TAG_PREFIX = "_N_T_";
 /** Max tag length to prevent KV key abuse. */
@@ -96,7 +93,7 @@ function isPathChildOf(path, prefix) {
 */
 var KVCacheHandler = class {
 	kv;
-	prefix;
+	keySpace;
 	ctx;
 	ttlSeconds;
 	/** Local in-memory cache for tag invalidation timestamps. Avoids redundant KV reads. */
@@ -105,13 +102,19 @@ var KVCacheHandler = class {
 	_tagCacheTtl;
 	constructor(kvNamespace, options) {
 		this.kv = kvNamespace;
-		this.prefix = options?.appPrefix ? `${options.appPrefix}:` : "";
+		this.keySpace = createKvKeySpace(options?.appPrefix);
 		this.ctx = options?.ctx;
 		this.ttlSeconds = options?.ttlSeconds ?? 720 * 3600;
 		this._tagCacheTtl = options?.tagCacheTtlMs ?? 5e3;
 	}
+	_entryKey(key) {
+		return this.keySpace.entryKey(key);
+	}
+	_tagKey(tag) {
+		return this.keySpace.tagKey(tag);
+	}
 	async get(key, _ctx) {
-		const kvKey = this.prefix + ENTRY_PREFIX + key;
+		const kvKey = this._entryKey(key);
 		const raw = await this.kv.get(kvKey);
 		if (!raw) return null;
 		let parsed;
@@ -178,7 +181,7 @@ var KVCacheHandler = class {
 			}
 		}
 		if (uncachedTags.length > 0) {
-			const tagResults = await Promise.all(uncachedTags.map((tag) => this.kv.get(this.prefix + TAG_PREFIX + tag)));
+			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;
@@ -229,7 +232,7 @@ var KVCacheHandler = class {
 		};
 		const expirationTtl = revalidateAt !== null ? this.ttlSeconds : void 0;
 		const metadata = JSON.stringify({ tags }).length <= 1024 ? { tags } : void 0;
-		return this._put(this.prefix + ENTRY_PREFIX + key, JSON.stringify(entry), {
+		return this._put(this._entryKey(key), JSON.stringify(entry), {
 			expirationTtl,
 			metadata
 		});
@@ -238,7 +241,7 @@ 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.prefix + TAG_PREFIX + tag, String(now), { expirationTtl: 720 * 3600 })));
+		await Promise.all(validTags.map((tag) => this.kv.put(this._tagKey(tag), String(now), { expirationTtl: 720 * 3600 })));
 		for (const tag of validTags) this._tagCache.set(tag, {
 			timestamp: now,
 			fetchedAt: now
@@ -263,7 +266,7 @@ var KVCacheHandler = class {
 	async revalidateByPathPrefix(pathPrefix) {
 		const tagsToInvalidate = /* @__PURE__ */ new Set();
 		let cursor;
-		const listPrefix = this.prefix + ENTRY_PREFIX;
+		const listPrefix = this.keySpace.entryPrefix;
 		do {
 			const page = await this.kv.list({
 				prefix: listPrefix,

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

@@ -0,0 +1,15 @@
+//#region src/cache/kv-key.d.ts
+/** Key prefix for cache entries. */
+declare const ENTRY_PREFIX = "cache:";
+type KvKeySpace = {
+  /** Prefix shared by every cache entry, including entries with hashed logical keys. */entryPrefix: string;
+  entryKey(logicalKey: string): string;
+  tagKey(tag: string): string;
+};
+/**
+ * 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 };

package/dist/cache/kv-key.js

@@ -0,0 +1,43 @@
+import { fnv1a64 } from "vinext/internal/utils/hash";
+//#region src/cache/kv-key.ts
+/** Key prefix for tag invalidation timestamps. */
+const TAG_PREFIX = "__tag:";
+/** Key prefix for cache entries. */
+const ENTRY_PREFIX = "cache:";
+/** Cloudflare KV's maximum UTF-8 encoded key length. */
+const KV_KEY_MAX_BYTES = 512;
+/** Marker for logical keys that must be hashed to fit in KV. */
+const HASHED_KEY_PREFIX = "__hash:";
+const KV_KEY_ENCODER = new TextEncoder();
+function kvKeyByteLength(key) {
+	return KV_KEY_ENCODER.encode(key).length;
+}
+/**
+* Keep short app prefixes readable, but bound the namespace portion so a
+* hashed entry or tag key is always able to fit within Cloudflare KV's limit.
+*/
+function normalizeAppPrefix(appPrefix) {
+	if (!appPrefix) return "";
+	const prefix = `${appPrefix}:`;
+	if (kvKeyByteLength(`${prefix}cache:${HASHED_KEY_PREFIX}${fnv1a64("")}`) <= KV_KEY_MAX_BYTES) return prefix;
+	return `__app:${fnv1a64(appPrefix)}:`;
+}
+function buildStorageKey(prefix, categoryPrefix, logicalKey) {
+	const key = `${prefix}${categoryPrefix}${logicalKey}`;
+	if (kvKeyByteLength(key) <= KV_KEY_MAX_BYTES) return key;
+	return `${prefix}${categoryPrefix}${HASHED_KEY_PREFIX}${fnv1a64(logicalKey)}`;
+}
+/**
+* Create the deterministic key namespace shared by runtime cache operations
+* and deploy-time prerender population.
+*/
+function createKvKeySpace(appPrefix) {
+	const prefix = normalizeAppPrefix(appPrefix);
+	return {
+		entryPrefix: `${prefix}${ENTRY_PREFIX}`,
+		entryKey: (logicalKey) => buildStorageKey(prefix, ENTRY_PREFIX, logicalKey),
+		tagKey: (tag) => buildStorageKey(prefix, TAG_PREFIX, tag)
+	};
+}
+//#endregion
+export { ENTRY_PREFIX, createKvKeySpace };

package/dist/deploy.js

@@ -1,8 +1,8 @@
 import { readPrerenderWarmPaths, warmCdnCache } from "./cdn-warm.js";
 import { parseWranglerConfig, runTPR } from "./tpr.js";
 import { formatImageOptimizationHint, formatMissingCacheAdapterError, resolveKvDataAdapterConfig, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
-import { parseWorkersDevUrl } from "./workers-dev-url.js";
 import { runWranglerDeploymentStatus, runWranglerTriggersDeploy, runWranglerVersionDeploy, runWranglerVersionUpload } from "./version-deploy.js";
+import { parseWorkerDeploymentUrl } from "./worker-deployment-url.js";
 import { buildPrerenderKVPairs } from "./prerender-kv-populate.js";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -344,7 +344,7 @@ async function runWranglerDeploy(root, options, execute = spawn) {
 			reject(/* @__PURE__ */ new Error(`Wrangler deploy failed with ${exitReason}.`));
 		});
 	});
-	return parseWorkersDevUrl(output) ?? "(URL not detected in wrangler output)";
+	return parseWorkerDeploymentUrl(output) ?? "(URL not detected in wrangler output)";
 }
 async function deployWithCdnWarmup(root, paths, options) {
 	const upload = runWranglerVersionUpload(root, options);

package/dist/prerender-kv-populate.js

@@ -1,4 +1,4 @@
-import { ENTRY_PREFIX } from "./cache/kv-data-adapter.runtime.js";
+import { createKvKeySpace } from "./cache/kv-key.js";
 import path from "node:path";
 import fs from "node:fs";
 import { getRenderedAppRoutes, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
@@ -28,9 +28,6 @@ function formatUnknownError(error) {
 	if (error instanceof Error && error.message) return error.message;
 	return String(error);
 }
-function buildKVKey(appPrefix, cacheKey) {
-	return `${appPrefix ? `${appPrefix}:` : ""}${ENTRY_PREFIX}${cacheKey}`;
-}
 function buildCacheEntry(value, tags, now, revalidateSeconds, expireSeconds) {
 	const cacheControl = revalidateSeconds === void 0 ? void 0 : expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
 		revalidate: revalidateSeconds,
@@ -64,6 +61,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 	const now = options?.now ?? Date.now();
 	const ttlSeconds = options?.ttlSeconds ?? DEFAULT_KV_TTL_SECONDS;
 	const trailingSlash = manifest.trailingSlash ?? false;
+	const keySpace = createKvKeySpace(options?.appPrefix);
 	let routeCount = 0;
 	for (const route of getRenderedAppRoutes(manifest.routes)) {
 		const artifactPathname = route.path ?? route.route;
@@ -87,7 +85,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 		const htmlKey = appIsrCacheKey(cachePathname, "html", manifest.buildId);
 		const rscKey = appIsrCacheKey(cachePathname, "rsc", manifest.buildId);
 		pairs.push({
-			key: buildKVKey(options?.appPrefix, htmlKey),
+			key: keySpace.entryKey(htmlKey),
 			value: buildCacheEntry({
 				kind: "APP_PAGE",
 				html: fs.readFileSync(htmlPath, "utf-8"),
@@ -99,7 +97,7 @@ function buildPrerenderKVPairs(serverDir, options) {
 		if (fs.existsSync(rscPath)) {
 			const rscData = fs.readFileSync(rscPath).toString("base64");
 			pairs.push({
-				key: buildKVKey(options?.appPrefix, rscKey),
+				key: keySpace.entryKey(rscKey),
 				value: buildCacheEntry({
 					kind: "APP_PAGE",
 					html: "",

package/dist/tpr.d.ts

@@ -71,7 +71,7 @@ declare function resolveVinextProdServerPath(root: string): string;
  * Build KV bulk API pairs from pre-rendered entries.
  *
  * Key format matches the runtime KVCacheHandler exactly:
- *   ENTRY_PREFIX + isrCacheKey("app", pathname, buildId) + ":html"
+ *   createKvKeySpace().entryKey(isrCacheKey("app", pathname, buildId) + ":html")
  *   → "cache:app:<buildId>:<pathname>:html"
  */
 declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId: string | undefined, defaultRevalidateSeconds: number): Array<{

package/dist/tpr.js

@@ -1,4 +1,4 @@
-import { ENTRY_PREFIX } from "./cache/kv-data-adapter.runtime.js";
+import { createKvKeySpace } from "./cache/kv-key.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
@@ -578,12 +578,13 @@ const MAX_KV_TTL_SECONDS = 720 * 3600;
 * Build KV bulk API pairs from pre-rendered entries.
 *
 * Key format matches the runtime KVCacheHandler exactly:
-*   ENTRY_PREFIX + isrCacheKey("app", pathname, buildId) + ":html"
+*   createKvKeySpace().entryKey(isrCacheKey("app", pathname, buildId) + ":html")
 *   → "cache:app:<buildId>:<pathname>:html"
 */
 function buildTprKVPairs(entries, buildId, defaultRevalidateSeconds) {
 	const now = Date.now();
 	const pairs = [];
+	const keySpace = createKvKeySpace(void 0);
 	for (const [routePath, result] of entries) {
 		if (!isTprCacheable(result.headers)) continue;
 		const revalidateSeconds = readTprRevalidateHeader(result.headers) ?? defaultRevalidateSeconds;
@@ -602,7 +603,7 @@ function buildTprKVPairs(entries, buildId, defaultRevalidateSeconds) {
 			lastModified: now,
 			revalidateAt
 		};
-		const cacheKey = ENTRY_PREFIX + isrCacheKey("app", routePath, buildId) + ":html";
+		const cacheKey = keySpace.entryKey(isrCacheKey("app", routePath, buildId) + ":html");
 		pairs.push({
 			key: cacheKey,
 			value: JSON.stringify(entry),

package/dist/worker-deployment-url.d.ts

@@ -0,0 +1,4 @@
+//#region src/worker-deployment-url.d.ts
+declare function parseWorkerDeploymentUrl(output: string): string | null;
+//#endregion
+export { parseWorkerDeploymentUrl };

package/dist/worker-deployment-url.js

@@ -0,0 +1,23 @@
+import { parseWorkersDevUrl } from "./workers-dev-url.js";
+//#region src/worker-deployment-url.ts
+function parseWorkerDeploymentUrl(output) {
+	return parseWorkersDevUrl(output) ?? parseCustomDomainUrl(output);
+}
+function parseCustomDomainUrl(output) {
+	for (const line of output.split(/\r?\n/)) {
+		const match = /^\s*(\S+)\s+\(custom domain(?: - zone (?:id|name): [^)]+)?\)(?: \[([^\]\r\n]+)\])?\s*$/.exec(line);
+		const hostname = match?.[1];
+		if (!hostname) continue;
+		if (match[2]?.split(",").some((flag) => flag.trim() === "disabled")) continue;
+		try {
+			const url = new URL(`https://${hostname}`);
+			if (url.username !== "" || url.password !== "" || url.port !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "") continue;
+			return url.origin;
+		} catch {
+			continue;
+		}
+	}
+	return null;
+}
+//#endregion
+export { parseWorkerDeploymentUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinext/cloudflare",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "Cloudflare adapters for vinext (KV data cache and Images-backed image optimization).",
   "license": "MIT",
   "repository": {
@@ -54,10 +54,10 @@
     "@types/node": "^25.9.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
     "vite-plus": "0.2.2",
-    "vinext": "1.0.0-beta.1"
+    "vinext": "1.0.0-beta.3"
   },
   "peerDependencies": {
-    "vinext": ">=0.0.0"
+    "vinext": "^1.0.0-beta.3"
   },
   "engines": {
     "node": ">=22"