@void/isr 0.26.0 → 0.27.0

package/README.md

@@ -1,11 +1,17 @@
 # @void/isr
 
-Shared incremental revalidation helpers for Void runtimes and deployment adapters. Applications use `void/isr` to revalidate pages; see the [Revalidation guide](https://void.cloud/guide/edge/revalidation).
+Incremental revalidation helpers for [Void](https://void.cloud) runtimes and deployment adapters. Applications use `void/isr` to revalidate pages.
 
-For runtime authors, the package provides three entry points:
+For runtime authors, this package provides three entry points:
 
 - `@void/isr`: versioned cache keys and edge-cache URLs
 - `@void/isr/core`: codecs, cache policy, TTL selection, and response helpers
 - `@void/isr/runtime`: the direct Cloudflare KV and Cache API runtime
 
-The writer and purger must use the same key helpers. Keep incompatible format changes behind a new cache-key version. See the [source](./src/index.ts) for the format contract and [Platform Development](https://void.cloud/guide/platform-development) for runtime work.
+Cache writes and purges must use the same key helpers. Incompatible format changes require a new cache-key version.
+
+## Documentation
+
+See [Revalidation](https://void.cloud/guide/edge/revalidation) for application usage and [Platform Development](https://void.cloud/guide/platform-development) for building a runtime or adapter.
+
+Read the [Void documentation](https://void.cloud) online or use the Markdown guides and references in `node_modules/void/docs/`, included with the `void` package.

package/dist/core.d.mts

@@ -34,6 +34,12 @@ export type QueryAllowlist = Record<string, ReadonlyArray<string>>;
  * explicitly allowlisted for its user-facing pathname.
  */
 export declare function buildVariantOriginalUrl(requestUrl: string, pathname: string, queryAllowlist: QueryAllowlist | undefined): string;
+/**
+ * True when the request carries a query parameter that the cache key leaves
+ * out. A render made from such a URL may depend on that parameter, so it must
+ * not be stored under the shared key.
+ */
+export declare function hasUnlistedQueryParams(requestUrl: string, pathname: string, allowlist: QueryAllowlist | undefined): boolean;
 /** Keep only exact allowlist patterns for uncapped static-cache consumers. */
 export declare function exactQueryAllowlist(allowlist: QueryAllowlist | undefined): QueryAllowlist | undefined;
 /** Pack response headers and body into the canonical ISR binary value. */

package/dist/core.mjs

@@ -41,6 +41,18 @@ function buildVariantOriginalUrl(requestUrl, pathname, queryAllowlist) {
 	url.search = filteredString ? `?${filteredString}` : "";
 	return url.toString();
 }
+/**
+* True when the request carries a query parameter that the cache key leaves
+* out. A render made from such a URL may depend on that parameter, so it must
+* not be stored under the shared key.
+*/
+function hasUnlistedQueryParams(requestUrl, pathname, allowlist) {
+	const url = new URL(requestUrl);
+	if (!url.search) return false;
+	const allowed = resolveQueryAllowlist(allowlist, pathname);
+	for (const key of url.searchParams.keys()) if (!allowed.has(key)) return true;
+	return false;
+}
 /** Keep only exact allowlist patterns for uncapped static-cache consumers. */
 function exactQueryAllowlist(allowlist) {
 	if (!allowlist) return;
@@ -213,4 +225,4 @@ function extractPageDataFromHtml(html) {
 	return match ? normalizePageDataForJsonCache(match[2]) : null;
 }
 //#endregion
-export { SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, buildVariantOriginalUrl, decodeIsrCacheEntry, exactQueryAllowlist, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, isFrameworkDocumentRequest, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePageTtl, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue };
+export { SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, buildVariantOriginalUrl, decodeIsrCacheEntry, exactQueryAllowlist, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, hasUnlistedQueryParams, isFrameworkDocumentRequest, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePageTtl, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue };

package/dist/index.d.mts

@@ -50,21 +50,13 @@ export declare function isrLegacyCachePrefix(projectId: string, deploymentId?: s
  *
  * Host-scoping is a `v3` key format: `<proj>/isr/v3/<D>/<host>/<path>`. The
  * version bump is load-bearing, not cosmetic — see `ISR_LEGACY_CACHE_KEY_VERSION`.
- * Under a single version, this key would be byte-identical to a legacy hostless
- * key for a page whose leading path segment looks like a hostname (e.g.
- * `(host=example.com, /about)` vs the hostless page `/example.com/about`, both
- * `<D>/example.com/about`). Dotted leading segments are legal, so the collision
- * is reachable. `v3` keys are ALWAYS host-scoped and `v2` keys ALWAYS hostless,
- * so the version segment alone disambiguates the two shapes.
  *
  * When `originalUrl` is provided, the request was served via a dispatch-side
  * rewrite (`redirectRules`/`fallbackRules` with status 200). The original
  * request URL is mixed into the key so a direct hit to `/en/docs` and a
  * rewrite from `/docs` to `/en/docs` do not collide — user code can branch
  * on `c.isRewritten()` / `c.originalUrl()`, and the cache must honor that.
- * A missing `originalUrl` means "direct hit" and produces the legacy
- * rewriteless key (backward-compatible with entries written before this
- * feature landed).
+ * A missing `originalUrl` means "direct hit" and produces the unsuffixed key.
  */
 export declare function isrCacheKey(projectId: string, deploymentId: string, host: string, pathname: string, originalUrl?: string | null): string;
 /**

package/dist/index.mjs

@@ -57,19 +57,9 @@ function denormalizeIsrPath(normalized) {
 function canonicalIsrPathname(pathname) {
 	return denormalizeIsrPath(normalizeIsrPath(pathname));
 }
-/**
-* Prefix shared by every ISR key for a project at the current version —
-* `<projectId>/isr/v3/`. Used internally by `isrCachePrefix`.
-*/
-function isrCacheVersionPrefix(projectId) {
-	return `${projectId}/isr/${ISR_CACHE_KEY_VERSION}/`;
-}
-/**
-* Prefix shared by every LEGACY (hostless) ISR key for a project —
-* `<projectId>/isr/v2/`. Used internally by `isrLegacyCachePrefix`.
-*/
-function isrLegacyCacheVersionPrefix(projectId) {
-	return `${projectId}/isr/${ISR_LEGACY_CACHE_KEY_VERSION}/`;
+function versionedIsrCachePrefix(projectId, version, deploymentId) {
+	if (deploymentId !== void 0) return `${projectId}/isr/${version}/${deploymentId}/`;
+	return `${projectId}/isr/`;
 }
 /**
 * Prefix for listing/purging ISR keys.
@@ -81,8 +71,7 @@ function isrLegacyCacheVersionPrefix(projectId) {
 * legacy scan-all prefix (`<projectId>/isr/`).
 */
 function isrCachePrefix(projectId, deploymentId) {
-	if (deploymentId !== void 0) return `${isrCacheVersionPrefix(projectId)}${deploymentId}/`;
-	return `${projectId}/isr/`;
+	return versionedIsrCachePrefix(projectId, ISR_CACHE_KEY_VERSION, deploymentId);
 }
 /**
 * Prefix for listing/purging LEGACY (pre-host-scoping) ISR keys — the `v2`
@@ -97,8 +86,7 @@ function isrCachePrefix(projectId, deploymentId) {
 * entries have aged out.
 */
 function isrLegacyCachePrefix(projectId, deploymentId) {
-	if (deploymentId !== void 0) return `${isrLegacyCacheVersionPrefix(projectId)}${deploymentId}/`;
-	return `${projectId}/isr/`;
+	return versionedIsrCachePrefix(projectId, ISR_LEGACY_CACHE_KEY_VERSION, deploymentId);
 }
 /**
 * Separator that marks the rewrite-variant suffix on an ISR cache key or
@@ -119,21 +107,13 @@ const ISR_VARIANT_SEPARATOR = "#rw=";
 *
 * Host-scoping is a `v3` key format: `<proj>/isr/v3/<D>/<host>/<path>`. The
 * version bump is load-bearing, not cosmetic — see `ISR_LEGACY_CACHE_KEY_VERSION`.
-* Under a single version, this key would be byte-identical to a legacy hostless
-* key for a page whose leading path segment looks like a hostname (e.g.
-* `(host=example.com, /about)` vs the hostless page `/example.com/about`, both
-* `<D>/example.com/about`). Dotted leading segments are legal, so the collision
-* is reachable. `v3` keys are ALWAYS host-scoped and `v2` keys ALWAYS hostless,
-* so the version segment alone disambiguates the two shapes.
 *
 * When `originalUrl` is provided, the request was served via a dispatch-side
 * rewrite (`redirectRules`/`fallbackRules` with status 200). The original
 * request URL is mixed into the key so a direct hit to `/en/docs` and a
 * rewrite from `/docs` to `/en/docs` do not collide — user code can branch
 * on `c.isRewritten()` / `c.originalUrl()`, and the cache must honor that.
-* A missing `originalUrl` means "direct hit" and produces the legacy
-* rewriteless key (backward-compatible with entries written before this
-* feature landed).
+* A missing `originalUrl` means "direct hit" and produces the unsuffixed key.
 */
 function isrCacheKey(projectId, deploymentId, host, pathname, originalUrl) {
 	const base = `${isrCachePrefix(projectId, deploymentId)}${host}/${normalizeIsrPath(pathname)}`;
@@ -189,9 +169,8 @@ function isrLegacyCacheVariantPrefix(projectId, deploymentId, pathname) {
 *   - Sync (Workers `crypto.subtle.digest` is async; we don't want to push
 *     async through every read/write path for this).
 *   - 16 hex chars (64 bits) — bounds the KV key length regardless of input.
-*   - Non-recoverable: KV is operator-readable, and the previous base64url
-*     encoding let any operator with list access read the original URLs
-*     (including sensitive query strings like `?token=…`, `?email=…`).
+*   - Non-recoverable: KV is operator-readable, so the token must not reveal
+*     original URLs (including sensitive query strings like `?token=…`).
 *   - Not cryptographic: collision resistance is ~2^32 (birthday). Fine for
 *     the per-deployment, per-pathname variant set we ever store in one slot.
 *

package/dist/runtime.d.mts

@@ -15,7 +15,7 @@ import { matchSegmentPattern } from "@void/edge";
  *   - No `projectId`, no cross-tenant metering.
  *   - No `#rw=` rewrite variant, no query-string variant fanout, no variant cap.
  *   - The deployment id is baked at build time as a compile-time literal and
- *     surfaced on `env.__VOID_ISR_DEPLOYMENT_ID` (Task 7). The KV helpers read
+ *     surfaced on `env.__VOID_ISR_DEPLOYMENT_ID`. The KV helpers read
  *     it from `env` (matching the `revalidate()` purge path in `runtime/isr.ts`),
  *     while `handleIsr` uses the `deploymentId` option for the edge-cache keys —
  *     the two are the same value.
@@ -127,8 +127,9 @@ export declare function handleFrameworkIsr(request: Request, env: IsrCacheEnv, c
  * 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).
+ * caller should render live itself (request not ISR-eligible, a read/hit
+ * cache op failed open, or a cache miss for a URL carrying query params
+ * outside the allowlist).
  *
  * Ladder:
  *   - Bail (`null`) if not GET, an API path, a Range request, `shouldBypassIsr`,

package/dist/runtime.mjs

@@ -1,5 +1,5 @@
 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, isFrameworkDocumentRequest, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePageTtl, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue } from "./core.mjs";
+import { SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, buildVariantOriginalUrl, decodeIsrCacheEntry, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, hasUnlistedQueryParams, isFrameworkDocumentRequest, 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;
@@ -160,8 +160,32 @@ function clientRevalidateResponse(response) {
 	res.headers.delete(SHARED_CACHE_POLICY_HEADER);
 	return res;
 }
+function mediaType(response) {
+	return response.headers.get("content-type")?.toLowerCase().split(";", 1)[0]?.trim();
+}
 function isEventStreamResponse(response) {
-	return response.headers.get("content-type")?.toLowerCase().split(";", 1)[0]?.trim() === "text/event-stream";
+	return mediaType(response) === "text/event-stream";
+}
+function isHtmlResponse(response) {
+	return mediaType(response) === "text/html";
+}
+/** Whether a fresh render may be written to the shared KV and edge caches. */
+function isStorableRender(response, ttl, htmlOnly) {
+	return ttl > 0 && isSharedCacheableResponse(response) && (!htmlOnly || isHtmlResponse(response));
+}
+/** Whether a successful render opts out of sharing, so cached copies must go. */
+function isUncacheableRender(response, ttl, htmlOnly) {
+	return response.status === 200 && (ttl === 0 || hasSharedCacheOptOut(response) || htmlOnly && !isHtmlResponse(response));
+}
+/** Headers for a shared HTML cache copy, without ISR-managed or private headers. */
+function sharedHtmlCacheHeaders(response, ttl, state) {
+	const headers = new Headers(response.headers);
+	headers.set("x-isr-cache", state);
+	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");
+	return headers;
 }
 function jsonCacheResponse(pageData, ttl, state) {
 	const response = new Response(pageData, { headers: {
@@ -249,30 +273,21 @@ async function revalidateInBackground(env, request, host, pathname, defaultTtl,
 		const ttl = resolveRevalidateTtl(response, defaultTtl);
 		const cache = edgeCache();
 		if (response.status === 200 && isEventStreamResponse(response)) {
-			if (ttl === 0 || hasSharedCacheOptOut(response)) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
+			if (isUncacheableRender(response, ttl, false)) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
 			return;
 		}
-		if (ttl > 0 && isSharedCacheableResponse(response) && (!htmlOnly || isHtmlResponse(response))) {
+		if (isStorableRender(response, ttl, htmlOnly)) {
 			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
+				headers: sharedHtmlCacheHeaders(response, ttl, "HIT")
 			}));
 			await populateJsonEdgeCache(cache, keys.jsonKey, response, ttl, "HIT");
-		} else if (response.status === 200 && (ttl === 0 || hasSharedCacheOptOut(response) || htmlOnly && !isHtmlResponse(response)) || (response.status === 404 || response.status === 410) && Date.now() - staleSinceMs > ISR_STALE_EVICT_GRACE_MS) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
+		} else if (isUncacheableRender(response, ttl, htmlOnly) || (response.status === 404 || response.status === 410) && Date.now() - staleSinceMs > ISR_STALE_EVICT_GRACE_MS) await deleteSharedIsrVariants(env, cache, host, pathname, keys, variantUrl);
 	} catch (err) {
 		console.error("ISR revalidation failed:", err);
 	}
 }
-function isHtmlResponse(response) {
-	return response.headers.get("content-type")?.toLowerCase().split(";", 1)[0]?.trim() === "text/html";
-}
 /** Cache only framework document HTML; leave client data requests and other response types live. */
 async function handleFrameworkIsr(request, env, ctx, options, render) {
 	if (!isFrameworkDocumentRequest(request)) return null;
@@ -282,8 +297,9 @@ async function handleFrameworkIsr(request, env, ctx, options, render) {
 * 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).
+* caller should render live itself (request not ISR-eligible, a read/hit
+* cache op failed open, or a cache miss for a URL carrying query params
+* outside the allowlist).
 *
 * Ladder:
 *   - Bail (`null`) if not GET, an API path, a Range request, `shouldBypassIsr`,
@@ -314,6 +330,7 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 	const host = url.hostname;
 	const normalizedVariantUrl = buildVariantOriginalUrl(request.url, pathname, queryAllowlist);
 	const variantUrl = new URL(normalizedVariantUrl).search ? normalizedVariantUrl : null;
+	const unlisted = hasUnlistedQueryParams(request.url, pathname, queryAllowlist);
 	const cache = edgeCache();
 	const htmlKey = htmlEdgeKey(host, pathname, deploymentId, variantUrl);
 	const jsonKey = jsonEdgeKey(host, pathname, deploymentId, variantUrl);
@@ -327,8 +344,7 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 		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, {
+		if (isUncacheableRender(response, resolveRevalidateTtl(response, isrTtl), false)) ctx.waitUntil(deleteSharedIsrVariants(env, cache, host, pathname, {
 			htmlKey,
 			jsonKey
 		}, variantUrl));
@@ -345,7 +361,11 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 	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, {
+		if (stale) ctx.waitUntil(revalidateInBackground(env, unlisted ? new Request(normalizedVariantUrl, {
+			method: request.method,
+			headers: request.headers,
+			cf: request.cf
+		}) : request, host, pathname, isrTtl, {
 			htmlKey,
 			jsonKey
 		}, render, variantUrl, htmlOnly, cached.createdAt + cached.ttl * 1e3));
@@ -355,26 +375,19 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 	} catch {
 		return null;
 	}
+	if (unlisted) return null;
 	const response = await render(request);
 	if (isEventStreamResponse(response)) return response;
 	const ttl = resolveRevalidateTtl(response, isrTtl);
-	if (ttl > 0 && isSharedCacheableResponse(response) && (!htmlOnly || isHtmlResponse(response))) {
+	if (isStorableRender(response, ttl, htmlOnly)) {
 		ctx.waitUntil(writeIsrCache(env, host, pathname, response, ttl, variantUrl));
 		ctx.waitUntil(populateJsonEdgeCache(cache, jsonKey, response, ttl, "HIT"));
-		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 edgeHeaders = new Headers(cacheHeaders);
-		edgeHeaders.set("x-isr-cache", "HIT");
 		const cacheResponse = new Response(response.clone().body, {
 			status: response.status,
-			headers: edgeHeaders
+			headers: sharedHtmlCacheHeaders(response, ttl, "HIT")
 		});
 		ctx.waitUntil(safeCachePut(cache, htmlKey, cacheResponse));
-		const clientHeaders = new Headers(cacheHeaders);
+		const clientHeaders = sharedHtmlCacheHeaders(response, ttl, "MISS");
 		clientHeaders.set("Cache-Control", CLIENT_REVALIDATE_CACHE_CONTROL);
 		clientHeaders.delete(SHARED_CACHE_POLICY_HEADER);
 		return new Response(response.body, {
@@ -382,7 +395,7 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 			headers: clientHeaders
 		});
 	}
-	if (response.status === 200 && (ttl === 0 || hasSharedCacheOptOut(response) || htmlOnly && !isHtmlResponse(response))) ctx.waitUntil(deleteSharedIsrVariants(env, cache, host, pathname, {
+	if (isUncacheableRender(response, ttl, htmlOnly)) ctx.waitUntil(deleteSharedIsrVariants(env, cache, host, pathname, {
 		htmlKey,
 		jsonKey
 	}, variantUrl));

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@void/isr",
-  "version": "0.26.0",
+  "version": "0.27.0",
+  "description": "Incremental revalidation and cache helpers for Void runtimes.",
+  "homepage": "https://void.cloud",
+  "bugs": {
+    "url": "https://github.com/voidzero-dev/void/issues"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -28,12 +34,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@cloudflare/workers-types": "^4.20260702.1",
-    "@void/edge": "0.26.0"
+    "@cloudflare/workers-types": "^5.20261009.1",
+    "@void/edge": "0.27.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vite-plus": "1.0.0"
+    "vite-plus": "1.1.0"
   },
   "scripts": {
     "build": "vp pack",