@void/isr 0.20.0

package/dist/runtime.mjs

@@ -0,0 +1,378 @@
+import { canonicalIsrPathname, denormalizeIsrPath, isrCacheKey, isrCachePrefix, isrCacheVariantPrefix, isrEdgeCacheUrl, normalizeIsrPath } from "./index.mjs";
+import { SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, buildVariantOriginalUrl, decodeIsrCacheEntry, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePageTtl, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue } from "./core.mjs";
+import { matchSegmentPattern } from "@void/edge";
+//#region src/runtime.ts
+const MAX_ISR_VARIANTS_PER_PATH = 200;
+const DIRECT_ISR_PROJECT_ID = "__void_direct__";
+/** Prefix for the current direct deployment's host-scoped cache entries. */
+function isrPrefix(deploymentId) {
+	return isrCachePrefix(DIRECT_ISR_PROJECT_ID, deploymentId);
+}
+/**
+* KV cache key for an ISR-cached page. Deployment- AND host-scoped: cached HTML
+* cannot outlive the hashed assets of the deployment that produced it (a fresh
+* `wrangler deploy` mints a new deployment id → cold cache), and one host's
+* cached content never bleeds into another host served by the same worker
+* (custom domain + workers.dev, apex + www, etc.).
+*/
+function isrKey(deploymentId, host, pathname, variantUrl) {
+	return isrCacheKey(DIRECT_ISR_PROJECT_ID, deploymentId, host, pathname, variantUrl);
+}
+function isrVariantPrefix(deploymentId, host, pathname) {
+	return isrCacheVariantPrefix(DIRECT_ISR_PROJECT_ID, deploymentId, host, pathname);
+}
+/**
+* Host-registry key. Every host that has written cached content registers itself
+* under `void-isr-hosts/<id>/<host>` (value `''`) so a purge with no request host
+* (cron / queue `revalidate({ paths })`) can enumerate the hosts to purge.
+* Scoped by deployment id so registrations from an old deploy do not leak.
+*/
+function hostRegistryKey(deploymentId, host) {
+	return `void-isr-hosts/${deploymentId}/${host}`;
+}
+/**
+* Edge-cache (`caches.default`) key for the HTML variant. The public URL stays
+* clean; this internal key carries the deployment id so a new deploy never
+* reads HTML produced by an older deploy.
+*/
+function htmlEdgeKey(host, pathname, id, variantUrl) {
+	return isrEdgeCacheUrl(host, pathname, id, "html", variantUrl);
+}
+/**
+* Edge-cache key for the JSON (pages-protocol) variant. Separated from HTML by
+* the `&__void=json` marker.
+*/
+function jsonEdgeKey(host, pathname, id, variantUrl) {
+	return isrEdgeCacheUrl(host, pathname, id, "json", variantUrl);
+}
+/**
+* Read an ISR cache entry from KV. Returns null on cache miss, malformed
+* metadata, or ANY KV error (fail-open → caller renders live). The KV key is
+* deployment-scoped via `env.__VOID_ISR_DEPLOYMENT_ID` (see module header) and
+* host-scoped via `host` so one host never reads another host's cached bytes.
+*/
+async function readIsrCache(env, host, pathname, variantUrl) {
+	const kv = env.ISR_CACHE;
+	if (!kv) return null;
+	const key = isrKey(env.__VOID_ISR_DEPLOYMENT_ID ?? "", host, pathname, variantUrl);
+	let value;
+	let metadata;
+	try {
+		const result = await kv.getWithMetadata(key, "arrayBuffer");
+		value = result.value;
+		metadata = result.metadata;
+	} catch {
+		return null;
+	}
+	return decodeIsrCacheEntry(value, metadata);
+}
+/**
+* Write an ISR cache entry to KV. The `response.clone()` is taken SYNCHRONOUSLY
+* before any `await` so a caller that consumes `response.body` for the client
+* response (after kicking us off via `ctx.waitUntil`) cannot race the body
+* away. Any KV error is swallowed (fail-open on the write path).
+*/
+async function writeIsrCache(env, host, pathname, response, ttl, variantUrl) {
+	const kv = env.ISR_CACHE;
+	if (!kv) return;
+	const responseClone = response.clone();
+	const headers = serializeHeaders(responseClone);
+	const status = responseClone.status;
+	const id = env.__VOID_ISR_DEPLOYMENT_ID ?? "";
+	try {
+		const key = isrKey(id, host, pathname, variantUrl);
+		if (variantUrl && !await isVariantWriteAllowed(kv, id, host, pathname, key)) {
+			await registerIsrHost(kv, id, host);
+			return;
+		}
+		const body = await responseClone.arrayBuffer();
+		const packed = packIsrValue(headers, body);
+		await kv.put(key, packed, { metadata: {
+			s: status,
+			c: Date.now(),
+			t: ttl,
+			p: 1
+		} });
+	} catch {}
+	await registerIsrHost(kv, id, host);
+}
+async function isVariantWriteAllowed(kv, deploymentId, host, pathname, key) {
+	const listed = await kv.list({
+		prefix: isrVariantPrefix(deploymentId, host, pathname),
+		limit: 1e3
+	});
+	return listed.keys.length < 200 || listed.keys.some((entry) => entry.name === key);
+}
+/**
+* In-isolate guard: `${id}/${host}` values whose host-registry key this isolate
+* has already written (or attempted). Bounds host registration to ~one KV write
+* per (isolate, deployment, host) instead of one per page write.
+*/
+const registeredHosts = /* @__PURE__ */ new Set();
+async function registerIsrHost(kv, deploymentId, host) {
+	const guardKey = `${deploymentId}/${host}`;
+	if (registeredHosts.has(guardKey)) return;
+	registeredHosts.add(guardKey);
+	try {
+		await kv.put(hostRegistryKey(deploymentId, host), "");
+	} catch {
+		registeredHosts.delete(guardKey);
+	}
+}
+/**
+* List every host that has registered cached content for a deployment. Used by
+* the on-demand `revalidate({ paths })` purge when there is no request host
+* (cron / queue). Fail-open: a registry read error yields the hosts collected so
+* far (or none) rather than throwing — degraded purge coverage, never a 500.
+*/
+async function listIsrHosts(kv, deploymentId) {
+	const prefix = `void-isr-hosts/${deploymentId}/`;
+	const hosts = [];
+	try {
+		let cursor;
+		do {
+			const list = await kv.list({
+				prefix,
+				cursor
+			});
+			for (const key of list.keys) hosts.push(key.name.slice(prefix.length));
+			cursor = list.list_complete ? void 0 : list.cursor;
+		} while (cursor);
+	} catch {}
+	return hosts;
+}
+/**
+* Delete an ISR cache entry from KV. Used when a worker permanently opts out
+* via `x-revalidate: 0`. Any KV error is swallowed (fail-open).
+*/
+async function deleteIsrCache(env, host, pathname, variantUrl) {
+	const kv = env.ISR_CACHE;
+	if (!kv) return;
+	try {
+		await kv.delete(isrKey(env.__VOID_ISR_DEPLOYMENT_ID ?? "", host, pathname, variantUrl));
+	} catch {}
+}
+const CLIENT_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+function clientRevalidateResponse(response) {
+	const res = new Response(response.body, response);
+	res.headers.set("Cache-Control", CLIENT_REVALIDATE_CACHE_CONTROL);
+	res.headers.delete(SHARED_CACHE_POLICY_HEADER);
+	return res;
+}
+function isEventStreamResponse(response) {
+	return response.headers.get("content-type")?.toLowerCase().split(";", 1)[0]?.trim() === "text/event-stream";
+}
+function jsonCacheResponse(pageData, ttl, state) {
+	const response = new Response(pageData, { headers: {
+		"content-type": "application/json",
+		"X-VoidPages": "true",
+		Vary: "X-VoidPages",
+		"Cache-Control": `public, s-maxage=${ttl}, max-age=0, must-revalidate`,
+		"x-isr-cache": state
+	} });
+	markSharedCachePolicy(response.headers);
+	return response;
+}
+/**
+* Populate the JSON edge cache from a response's embedded page data (the
+* `x-void-page-data` header or the `__VOID_PAGE_DATA__` inline script). No-ops
+* when there is no extractable page data. Any cache error is swallowed
+* (fail-open) so this is always safe to fire inside `ctx.waitUntil`.
+*/
+async function populateJsonEdgeCache(cache, cacheKey, response, ttl, state) {
+	if (!cache) return;
+	try {
+		const fromHeader = response.headers.get("x-void-page-data");
+		const pageData = fromHeader ? normalizePageDataForJsonCache(fromHeader) : extractPageDataFromHtml(await response.clone().text());
+		if (!pageData) return;
+		await cache.put(cacheKey, jsonCacheResponse(pageData, ttl, state));
+	} catch {}
+}
+/**
+* The per-colo edge cache (`caches.default`), or `undefined` when the Cache API
+* is absent/degraded. Accessed through a cast because this package has both
+* `@types/node` and `@cloudflare/workers-types` in scope, and Node's ambient
+* `CacheStorage` (which lacks `.default`) otherwise shadows the Workers one on
+* the `caches` global.
+*
+* Non-throwing by contract: dereferencing `caches.default` can throw if the
+* Cache API is missing (e.g. a non-worker runtime) or degraded. We swallow that
+* here and return `undefined` so `handleIsr` never rejects before its fail-open
+* guards run — the serving invariant is a degraded cache must render live, never
+* 500. Every call site guards `undefined` (via `if (!cache)` or `cache?.`).
+*/
+function edgeCache() {
+	try {
+		return caches.default;
+	} catch {
+		return;
+	}
+}
+async function safeCachePut(cache, key, response) {
+	if (!cache) return;
+	try {
+		await cache.put(key, response);
+	} catch {}
+}
+async function safeCacheDelete(cache, key) {
+	if (!cache) return;
+	try {
+		await cache.delete(key);
+	} catch {}
+}
+async function deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl) {
+	await deleteIsrCache(env, host, pathname, variantUrl);
+	await safeCacheDelete(cache, keys.htmlKey);
+	await safeCacheDelete(cache, keys.jsonKey);
+}
+/**
+* Build a new Request with the `X-VoidPages` header removed. Headers on an
+* existing Request are immutable, so we must clone into a fresh Request. ISR
+* only runs for GET, so there is no body to preserve.
+*/
+function cloneWithoutVoidPages(request) {
+	const headers = new Headers(request.headers);
+	headers.delete("X-VoidPages");
+	return new Request(request, { headers });
+}
+/**
+* Revalidate an ISR page in the background. Re-renders as HTML (X-VoidPages
+* stripped), writes fresh HTML to KV + HTML edge cache, and populates the JSON
+* edge cache from embedded page data. Errors are caught and logged — serve
+* stale, don't retry. An explicit cache opt-out (including `ttl === 0`)
+* deletes the KV entry and both edge variants.
+*/
+async function revalidateInBackground(env, request, host, pathname, defaultTtl, keys, render, variantUrl) {
+	try {
+		const response = await render(cloneWithoutVoidPages(request));
+		const ttl = resolveRevalidateTtl(response, defaultTtl);
+		const cache = edgeCache();
+		if (isEventStreamResponse(response)) {
+			if (ttl === 0 || hasSharedCacheOptOut(response)) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
+			return;
+		}
+		if (ttl > 0 && isSharedCacheableResponse(response)) {
+			await writeIsrCache(env, host, pathname, response, ttl, variantUrl);
+			const headers = new Headers(response.headers);
+			headers.set("x-isr-cache", "HIT");
+			headers.set("Cache-Control", `public, s-maxage=${ttl}, max-age=0, must-revalidate`);
+			markSharedCachePolicy(headers);
+			headers.delete("set-cookie");
+			headers.delete("x-void-page-data");
+			await safeCachePut(cache, keys.htmlKey, new Response(response.clone().body, {
+				status: response.status,
+				headers
+			}));
+			await populateJsonEdgeCache(cache, keys.jsonKey, response, ttl, "HIT");
+		} else if (ttl === 0 || hasSharedCacheOptOut(response)) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
+	} catch (err) {
+		console.error("ISR revalidation failed:", err);
+	}
+}
+/**
+* Run the ISR caching ladder for a request.
+*
+* Returns a cached/rendered `Response` when ISR applies, or `null` when the
+* caller should render live itself (request not ISR-eligible, or a read/hit
+* cache op failed open).
+*
+* Ladder:
+*   - Bail (`null`) if not GET, an API path, a Range request, `shouldBypassIsr`,
+*     or the path has no ISR TTL. Range requests bail BEFORE any cache read/write so they
+*     render live (correct 206) and never touch the shared full-response entry.
+*   - JSON (X-VoidPages) path: edge match → hit serves `clientRevalidateResponse`;
+*     miss renders live JSON and returns it — the JSON path never writes the edge
+*     cache. The JSON edge variant is warmed only as a side-effect of the HTML
+*     render path (cold colo re-renders JSON).
+*   - HTML path: L1 edge match → L2 KV. Hit serves `isrCacheResponse`
+*     (stale hits also queue a background revalidation). Miss renders live and,
+*     when cacheable, writes KV + JSON edge + HTML edge in the background.
+*/
+async function handleIsr(request, env, ctx, options, render) {
+	const { revalidate, pages, pathRevalidate, deploymentId, queryAllowlist } = options;
+	if (request.method !== "GET") return null;
+	if (request.headers.has("range")) return null;
+	if (shouldBypassIsr(request)) return null;
+	const url = new URL(request.url);
+	const pathname = url.pathname;
+	if (pathname === "/api" || pathname.startsWith("/api/")) return null;
+	const isrTtl = resolvePageTtl(pages, revalidate, pathRevalidate, pathname);
+	if (isrTtl <= 0) return null;
+	env.__VOID_ISR_DEPLOYMENT_ID ??= deploymentId;
+	const host = url.hostname;
+	const normalizedVariantUrl = buildVariantOriginalUrl(request.url, pathname, queryAllowlist);
+	const variantUrl = new URL(normalizedVariantUrl).search ? normalizedVariantUrl : null;
+	const cache = edgeCache();
+	const htmlKey = htmlEdgeKey(host, pathname, deploymentId, variantUrl);
+	const jsonKey = jsonEdgeKey(host, pathname, deploymentId, variantUrl);
+	if (request.headers.has("X-VoidPages")) {
+		let jsonCached;
+		try {
+			jsonCached = await cache?.match(jsonKey);
+		} catch {
+			return null;
+		}
+		if (jsonCached && hasCurrentSharedCachePolicy(jsonCached)) return clientRevalidateResponse(jsonCached);
+		if (jsonCached) await safeCacheDelete(cache, jsonKey);
+		const response = await render(request);
+		const ttl = resolveRevalidateTtl(response, isrTtl);
+		if (response.status === 200 && (ttl === 0 || hasSharedCacheOptOut(response))) ctx.waitUntil(deleteSharedIsrVariants(env, cache, host, pathname, {
+			htmlKey,
+			jsonKey
+		}, variantUrl));
+		return response;
+	}
+	let edgeCached;
+	try {
+		edgeCached = await cache?.match(htmlKey);
+	} catch {
+		return null;
+	}
+	if (edgeCached && hasCurrentSharedCachePolicy(edgeCached)) return clientRevalidateResponse(edgeCached);
+	if (edgeCached) await safeCacheDelete(cache, htmlKey);
+	const cached = await readIsrCache(env, host, pathname, variantUrl);
+	if (cached) try {
+		const stale = isStale(cached);
+		if (stale) ctx.waitUntil(revalidateInBackground(env, request, host, pathname, isrTtl, {
+			htmlKey,
+			jsonKey
+		}, render, variantUrl));
+		const cacheResponse = isrCacheResponse(cached, stale);
+		if (!stale) ctx.waitUntil(safeCachePut(cache, htmlKey, cacheResponse.clone()));
+		return clientRevalidateResponse(cacheResponse);
+	} catch {
+		return null;
+	}
+	const response = await render(request);
+	if (isEventStreamResponse(response)) return response;
+	const ttl = resolveRevalidateTtl(response, isrTtl);
+	if (ttl > 0 && isSharedCacheableResponse(response)) {
+		ctx.waitUntil(writeIsrCache(env, host, pathname, response, ttl, variantUrl));
+		ctx.waitUntil(populateJsonEdgeCache(cache, jsonKey, response, ttl, "MISS"));
+		const cacheHeaders = new Headers(response.headers);
+		cacheHeaders.set("Cache-Control", `public, s-maxage=${ttl}, max-age=0, must-revalidate`);
+		cacheHeaders.set("x-isr-cache", "MISS");
+		markSharedCachePolicy(cacheHeaders);
+		cacheHeaders.delete("x-void-page-data");
+		cacheHeaders.delete("set-cookie");
+		const cacheResponse = new Response(response.clone().body, {
+			status: response.status,
+			headers: cacheHeaders
+		});
+		ctx.waitUntil(safeCachePut(cache, htmlKey, cacheResponse));
+		const clientHeaders = new Headers(cacheHeaders);
+		clientHeaders.set("Cache-Control", CLIENT_REVALIDATE_CACHE_CONTROL);
+		clientHeaders.delete(SHARED_CACHE_POLICY_HEADER);
+		return new Response(response.body, {
+			status: response.status,
+			headers: clientHeaders
+		});
+	}
+	if (response.status === 200 && (ttl === 0 || hasSharedCacheOptOut(response))) ctx.waitUntil(deleteSharedIsrVariants(env, cache, host, pathname, {
+		htmlKey,
+		jsonKey
+	}, variantUrl));
+	return response;
+}
+//#endregion
+export { MAX_ISR_VARIANTS_PER_PATH, SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, canonicalIsrPathname, clientRevalidateResponse, cloneWithoutVoidPages, deleteIsrCache, denormalizeIsrPath, extractPageDataFromHtml, handleIsr, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, hostRegistryKey, htmlEdgeKey, isEventStreamResponse, isSharedCacheableResponse, isStale, isrCacheResponse, isrKey, isrPrefix, isrVariantPrefix, jsonEdgeKey, listIsrHosts, markSharedCachePolicy, matchSegmentPattern as matchLiteralPattern, normalizeIsrPath, normalizePageDataForJsonCache, packIsrValue, populateJsonEdgeCache, readIsrCache, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue, writeIsrCache };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@void/isr",
+  "version": "0.20.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voidzero-dev/void.git",
+    "directory": "packages/isr"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.mts",
+      "import": "./dist/core.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "import": "./dist/runtime.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^4.20260702.1",
+    "@void/edge": "0.20.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vite-plus": "0.3.1"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}