@void/isr 0.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, Cloudflare, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @void/isr
+
+Shared Incremental Static Regeneration contracts for Void runtimes and deployment targets.
+
+The package is public so the Void SDK, the hosted platform, and deployment adapters can consume the same cache-key and edge-cache URL protocol directly. Applications normally use `void/isr`; this lower-level package is intended for runtime and adapter authors.
+
+## Purpose
+
+When a request is served via a dispatch-side rewrite (`routing.rewrites` or `routing.fallbacks`), the ISR slot splits per original-request URL via the `#rw=` variant suffix — so user code that branches on `c.isRewritten()` / `c.originalUrl()` doesn't share a cache entry with the direct-hit path to the same destination.
+
+ISR cache entries are written by `platform/packages/dispatch` and purged by `platform/packages/api`. The two workers must produce byte-identical keys and URLs — if the purger and the writer disagree on a single character, purges silently miss and stale HTML survives revalidation. This package centralizes every helper that constructs an ISR KV key or an edge-cache URL so the two sides cannot drift.
+
+Any new helper that touches the key or URL format belongs here, not in `api/` or `dispatch/`. Duplication is the failure mode this package exists to prevent.
+
+## Public API
+
+The package has three entry points:
+
+- `@void/isr` owns the immutable, versioned KV-key and edge-cache URL protocol.
+- `@void/isr/core` owns target-neutral codecs, validation, TTL selection, request bypass rules, response construction, header sanitization, Void Pages data extraction, and query-variant normalization.
+- `@void/isr/runtime` implements the fail-open, single-tenant Cloudflare KV and Cache API ladder used by direct Void deployments, including bounded variants from `routing.revalidateQueryAllowlist`.
+
+The direct runtime applies ISR only to public page requests. API paths, credentialed requests, Range requests, and EventSource requests render live. A rendered response is shared only when it is a complete `200` response without `Cache-Control: private`, `no-store`, or `no-cache`, and without `Set-Cookie`. When a background revalidation returns one of those opt-outs, the runtime removes the old HTML, Pages JSON, and KV variants so previously public content cannot remain reachable.
+
+| Symbol                        | Description                                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `isrCacheKey`                 | Build a full ISR KV key, optionally including a rewrite-variant suffix derived from the original request URL.            |
+| `isrCachePrefix`              | Prefix for listing/purging ISR keys by deployment (or all deployments when `deploymentId` is `undefined`).               |
+| `isrCacheVariantPrefix`       | Prefix that matches every rewrite variant of a given pathname under a deployment (for listing/purging).                  |
+| `isrLegacyCachePrefix`        | `v2` (hostless) counterpart of `isrCachePrefix`. Transition-only — purge path sweeps the pre-host-scoping namespace.     |
+| `isrLegacyCacheKey`           | `v2` (hostless) direct-hit key for a pathname. Transition-only — purge path reaps the orphaned pre-host-scoping key.     |
+| `isrLegacyCacheVariantPrefix` | `v2` (hostless) counterpart of `isrCacheVariantPrefix`. Transition-only — purge path recovers pre-host-scoping variants. |
+| `splitIsrCacheKey`            | Split a full key into `{ normalizedPath, variantToken }` — `variantToken` is `null` for direct-hit (non-rewrite) keys.   |
+| `denormalizeIsrPath`          | Turn a normalized path segment back into a pathname starting with `/`. Paired with `splitIsrCacheKey` on purge.          |
+| `isrEdgeCacheUrl`             | Build the internal edge-cache URL used as the `caches.default` key. Takes the original URL; hashes it internally.        |
+| `isrEdgeCacheUrlForToken`     | Same shape, but takes a pre-hashed variant token (the form returned by `splitIsrCacheKey`). Used by the purge path.      |
+| `hashOriginalUrl`             | Sync FNV-1a 64-bit hex hash of the original URL. Exposed for callers that need to compute the token outside the helpers. |
+
+The legacy (`v2`) sweep helpers `isrLegacyCachePrefix`, `isrLegacyCacheKey`, and `isrLegacyCacheVariantPrefix` are exported for the API purge path only — they target the pre-host-scoping `v2` namespace during the host-scoping rollout. Dispatch never uses them.
+
+Path normalization (`normalizeIsrPath` / `canonicalIsrPathname`), the version prefixes (`isrCacheVersionPrefix` / `isrLegacyCacheVersionPrefix`), and the version constants (`ISR_CACHE_KEY_VERSION` / `ISR_LEGACY_CACHE_KEY_VERSION`) are package-internal. Consumers work through the key-building helpers above so the format contract lives in one place; add a new exported helper rather than reaching for an internal if a call site needs one.
+
+## Key Format
+
+The current version is `v3` (host-scoped):
+
+```
+<projectId>/isr/v3/<deploymentId>/<host>/<normalizedPath>[#rw=<variantTokenHex>]
+```
+
+The legacy `v2` namespace is hostless (still swept by the purger during the rollout, never written or read by dispatch):
+
+```
+<projectId>/isr/v2/<deploymentId>/<normalizedPath>[#rw=<variantTokenHex>]
+```
+
+- `<projectId>/isr/v3/` — namespacing plus the current format version. The version prefix exists so a format change can coexist with stale entries from the previous version; bump `ISR_CACHE_KEY_VERSION` rather than reusing the current prefix.
+  - `v1`→`v2` added the rewrite-variant (`#rw=`) suffix.
+  - `v2`→`v3` added the `<host>` segment (host-scoping). This bump was **mandatory**, not cosmetic: under a single version a host-scoped key `<D>/<host>/<path>` and a legacy hostless key `<D>/<path>` are byte-identical whenever the hostless path's leading segment looks like a hostname. Dotted leading path segments are legal (a route param `[domain]` compiles to `:domain` = `[^/]+`, and `[...slug]` to `(.+)`), so the hostless page `/example.com/about` produces the key `<D>/example.com/about` — exactly the host-scoped key for `(host=example.com, /about)`. Encoding the shape in the version removes the ambiguity: `v3` keys are always host-scoped, `v2` keys always hostless, so the version segment alone classifies the key — no runtime heuristic needed. Do not remove the version prefix as "dead weight" — that silently breaks cache compatibility the next time the format evolves.
+- Every KV entry carries `{s,c,t,p}` metadata. `p` is the shared-response privacy-policy version. Readers reject entries without the current value because older writers stripped private headers before storage, leaving no reliable way to prove their bodies safe to share.
+- `<deploymentId>` — scopes each entry to the deployment that produced it. Cached HTML embeds hashed asset URLs from a specific deployment; reading it after a new deploy ships would serve stale HTML pointing at assets that no longer exist. Scoping by deployment makes that structurally impossible.
+- `<host>` — the request hostname dispatch saw (`new URL(request.url).hostname`). The same path served under a project slug and a custom domain (or two custom domains) never shares a cache slot. `v3` only; absent in `v2`.
+- `<normalizedPath>` — the pathname passed through `normalizeIsrPath`. Root `/` becomes `__index__`; other paths have leading and trailing slashes stripped.
+- `#rw=<token>` — optional rewrite-variant suffix. When a request was served via a dispatch-phase rewrite (`routing.rewrites`, `routing.fallbacks`, or a `_redirects` `200`/`200!` entry), the ISR slot splits per original request URL so direct hits and rewrite-served hits do not share cache entries (user code can branch on `c.isRewritten()` / `c.originalUrl()`). `#` is used as the separator because it cannot appear inside `url.pathname` — the browser strips fragments before the request reaches the edge — and it never survives `normalizeIsrPath`, so the suffix is unambiguous.
+
+## Variant Tokens
+
+Variant tokens are a fixed-length hex hash (FNV-1a 64-bit, 16 chars) of the UTF-8 bytes of the original request URL. The same hash is used as the KV-key suffix and as the `__void_orig=<token>` query value on the internal edge-cache URL, so the writer (dispatch) and the purger (api) compute byte-identical tokens for the same URL.
+
+Hashing — rather than reversibly encoding the URL — is deliberate:
+
+- **KV is operator-readable.** A reversible token (the prior `btoa` encoding) let any operator with KV list access read the original URLs, including sensitive query strings (`?token=…`, `?email=…`).
+- **Variant tokens are KV-key suffixes.** A fixed-length hash bounds the total key size regardless of how long the original URL was, so KV's name-length limit can't be approached by any single request.
+
+The hash is sync (BigInt FNV-1a; Workers' `crypto.subtle.digest` is async and we don't want to push async through every read/write). Collision resistance is ~2^32 (birthday) — fine for the per-deployment, per-pathname variant set we ever store; the per-pathname variant cap (see `isr` issue #6) keeps that population well under the threshold.
+
+Because the original URL is not recoverable from a variant token, `splitIsrCacheKey` returns the token directly (as `variantToken`), and the purger calls `isrEdgeCacheUrlForToken` rather than re-hashing.
+
+## Monorepo Consumers
+
+- `platform/packages/api/src/isr-cache.ts` — hosted purge path. Uses `splitIsrCacheKey` to decode variant KV entries and `isrEdgeCacheUrl` to reconstruct the matching edge-cache URL.
+- `platform/packages/dispatch/src/isr.ts` — hosted read/write path. Uses `isrCacheKey` and `isrEdgeCacheUrl` to resolve the slot for every ISR-backed page request.
+- `packages/void` — direct Cloudflare runtime and CLI integration.
+
+## Rules for Adding Helpers
+
+1. Any new helper that touches ISR key or URL format MUST live in this package. Do not inline a new format in `api/` or `dispatch/`.
+2. Any incompatible change to the format (different prefix, different separators, different encoding, or a new key segment like `<host>`) requires bumping `ISR_CACHE_KEY_VERSION`. Writers after the bump must produce keys under the new version; the old keys expire naturally as their deployments age out. Do not reuse a version number. The `v2`→`v3` (host-scoping) bump is the cautionary example: shipping host-scoping WITHOUT the bump let a `<host>/<path>` key alias a legacy hostless `<path>` key (see Key Format), so the purger's legacy sweep is written against the `v2` namespace explicitly rather than trusting a runtime heuristic to tell the shapes apart.
+3. Additive changes that extend an existing key suffix (new query parameters on the edge URL, new optional suffix segments on the KV key) are safe without a version bump as long as readers at both versions treat the absence of the new component as the previous default.

package/dist/core.d.mts

@@ -0,0 +1,81 @@
+//#region src/core.d.ts
+/**
+ * Bump when a cached response accepted by an older writer can no longer be
+ * proven safe to share. Readers reject entries from earlier policies instead
+ * of replaying opaque bodies whose private headers were stripped at write time.
+ */
+export declare const SHARED_CACHE_POLICY_VERSION: 1;
+export declare const SHARED_CACHE_POLICY_HEADER = "x-void-shared-cache-policy";
+/** Stamp an internal edge-cache representation with the policy that admitted it. */
+export declare function markSharedCachePolicy(headers: Headers): void;
+/** Reject opaque edge entries admitted before the current privacy policy. */
+export declare function hasCurrentSharedCachePolicy(response: Response): boolean;
+export type IsrCacheMetadata = Readonly<{
+  /** HTTP status code. */
+  s: number;
+  /** Creation time in milliseconds since the Unix epoch. */
+  c: number;
+  /** Freshness lifetime in seconds. */
+  t: number;
+  /** Shared-response privacy policy version. */
+  p: typeof SHARED_CACHE_POLICY_VERSION;
+}>;
+export type IsrCacheEntry = Readonly<{
+  body: ReadableStream;
+  status: number;
+  headers: Record<string, string>;
+  createdAt: number;
+  ttl: number;
+}>;
+/** Map of literal path pattern to the query names retained in an ISR cache variant. */
+export type QueryAllowlist = Record<string, ReadonlyArray<string>>;
+/**
+ * Normalize a request URL for cache-key use by retaining only query parameters
+ * explicitly allowlisted for its user-facing pathname.
+ */
+export declare function buildVariantOriginalUrl(requestUrl: string, pathname: string, queryAllowlist: QueryAllowlist | undefined): string;
+/** 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. */
+export declare function packIsrValue(headers: Record<string, string>, body: ArrayBuffer): ArrayBuffer;
+/** Unpack a canonical ISR binary value, returning null for malformed bytes. */
+export declare function unpackIsrValue(buffer: ArrayBuffer): {
+  headers: Record<string, string>;
+  body: ArrayBuffer;
+} | null;
+/** Decode and validate a KV value plus metadata into a safe cache entry. */
+export declare function decodeIsrCacheEntry(value: ArrayBuffer | null, metadata: IsrCacheMetadata | null): IsrCacheEntry | null;
+/** Check whether an ISR cache entry has passed its freshness lifetime. */
+export declare function isStale(entry: IsrCacheEntry, now?: number): boolean;
+/** Build an edge-cacheable response from a validated ISR cache entry. */
+export declare function isrCacheResponse(entry: IsrCacheEntry, stale: boolean, now?: number): Response;
+/** Resolve an x-revalidate override, falling back for absent or invalid values. */
+export declare function resolveRevalidateTtl(response: Response, defaultTtl: number): number;
+/** Return whether credentials or EventSource semantics require an ISR bypass. */
+export declare function shouldBypassIsr(request: Request): boolean;
+/** Return whether a response explicitly forbids storage in a shared cache. */
+export declare function hasSharedCacheOptOut(response: Response): boolean;
+/** Return whether a complete render may be persisted in the shared ISR cache. */
+export declare function isSharedCacheableResponse(response: Response): boolean;
+/** Resolve the first matching path TTL using Void route-pattern semantics. */
+export declare function resolvePathTtl(revalidate: number | Record<string, number> | undefined, pathname: string): number;
+/** One ordered page-route entry in the shared ISR TTL policy. */
+export type IsrPageTtl = Readonly<{
+  pattern: string;
+  revalidate?: number;
+}>;
+/**
+ * Resolve ISR TTL from the framework's ordered page table.
+ *
+ * The first matching page is authoritative. A baked positive TTL enables ISR,
+ * a baked `0` opts out, and an absent TTL inherits from the raw per-path config.
+ * Only requests that match no page fall back to the flattened revalidate config.
+ */
+export declare function resolvePageTtl(pages: ReadonlyArray<IsrPageTtl> | undefined, revalidate: number | Record<string, number> | undefined, pathRevalidate: Record<string, number> | undefined, pathname: string): number;
+/** Extract response headers while removing ISR-managed and private headers. */
+export declare function serializeHeaders(response: Response): Record<string, string>;
+/** Validate page data before storing it as the JSON ISR variant. */
+export declare function normalizePageDataForJsonCache(raw: string): string | null;
+/** Extract validated Void Pages data embedded in an HTML response. */
+export declare function extractPageDataFromHtml(html: string): string | null;
+//#endregion

package/dist/core.mjs

@@ -0,0 +1,200 @@
+import { matchLiteralPattern, matchSegmentPattern } from "@void/edge";
+//#region src/core.ts
+/**
+* Bump when a cached response accepted by an older writer can no longer be
+* proven safe to share. Readers reject entries from earlier policies instead
+* of replaying opaque bodies whose private headers were stripped at write time.
+*/
+const SHARED_CACHE_POLICY_VERSION = 1;
+const SHARED_CACHE_POLICY_HEADER = "x-void-shared-cache-policy";
+/** Stamp an internal edge-cache representation with the policy that admitted it. */
+function markSharedCachePolicy(headers) {
+	headers.set(SHARED_CACHE_POLICY_HEADER, String(1));
+}
+/** Reject opaque edge entries admitted before the current privacy policy. */
+function hasCurrentSharedCachePolicy(response) {
+	return response.headers.get(SHARED_CACHE_POLICY_HEADER) === String(1);
+}
+const PAGE_DATA_SCRIPT_RE = /<script\b[^>]*\bid=(["'])__VOID_PAGE_DATA__\1[^>]*>([\s\S]*?)<\/script>/i;
+const SKIP_HEADERS = /* @__PURE__ */ new Set([
+	"cache-control",
+	"x-isr-cache",
+	"x-void-page-data",
+	"set-cookie"
+]);
+/**
+* Normalize a request URL for cache-key use by retaining only query parameters
+* explicitly allowlisted for its user-facing pathname.
+*/
+function buildVariantOriginalUrl(requestUrl, pathname, queryAllowlist) {
+	const url = new URL(requestUrl);
+	if (!url.search) return url.toString();
+	const allowed = resolveQueryAllowlist(queryAllowlist, pathname);
+	if (allowed.size === 0) {
+		url.search = "";
+		return url.toString();
+	}
+	const keys = [...new Set(url.searchParams.keys())].filter((key) => allowed.has(key)).sort();
+	const filtered = new URLSearchParams();
+	for (const key of keys) for (const value of url.searchParams.getAll(key)) filtered.append(key, value);
+	const filteredString = filtered.toString();
+	url.search = filteredString ? `?${filteredString}` : "";
+	return url.toString();
+}
+/** Keep only exact allowlist patterns for uncapped static-cache consumers. */
+function exactQueryAllowlist(allowlist) {
+	if (!allowlist) return;
+	const exact = Object.fromEntries(Object.entries(allowlist).filter(([pattern]) => !pattern.includes("*")));
+	return Object.keys(exact).length > 0 ? exact : void 0;
+}
+function resolveQueryAllowlist(allowlist, pathname) {
+	if (!allowlist) return /* @__PURE__ */ new Set();
+	for (const [pattern, params] of Object.entries(allowlist)) if (matchLiteralPattern(pattern, pathname)) return new Set(params);
+	return /* @__PURE__ */ new Set();
+}
+/** Pack response headers and body into the canonical ISR binary value. */
+function packIsrValue(headers, body) {
+	const headerJson = new TextEncoder().encode(JSON.stringify(headers));
+	const buffer = new ArrayBuffer(4 + headerJson.byteLength + body.byteLength);
+	new DataView(buffer).setUint32(0, headerJson.byteLength, true);
+	new Uint8Array(buffer, 4, headerJson.byteLength).set(headerJson);
+	new Uint8Array(buffer, 4 + headerJson.byteLength).set(new Uint8Array(body));
+	return buffer;
+}
+/** Unpack a canonical ISR binary value, returning null for malformed bytes. */
+function unpackIsrValue(buffer) {
+	if (buffer.byteLength < 4) return null;
+	const headerLength = new DataView(buffer).getUint32(0, true);
+	if (buffer.byteLength < 4 + headerLength) return null;
+	try {
+		const headerBytes = new Uint8Array(buffer, 4, headerLength);
+		const parsed = JSON.parse(new TextDecoder().decode(headerBytes));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		const headers = {};
+		for (const [name, value] of Object.entries(parsed)) {
+			if (typeof value !== "string") return null;
+			headers[name] = value;
+		}
+		return {
+			headers,
+			body: buffer.slice(4 + headerLength)
+		};
+	} catch {
+		return null;
+	}
+}
+/** Decode and validate a KV value plus metadata into a safe cache entry. */
+function decodeIsrCacheEntry(value, metadata) {
+	if (!value || !metadata) return null;
+	const unpacked = unpackIsrValue(value);
+	if (!unpacked) return null;
+	if (!Number.isInteger(metadata.s) || metadata.s < 200 || metadata.s > 599) return null;
+	if (!Number.isFinite(metadata.c) || metadata.c <= 0 || !Number.isFinite(metadata.t) || metadata.t <= 0 || metadata.p !== 1) return null;
+	try {
+		new Headers(unpacked.headers);
+	} catch {
+		return null;
+	}
+	return {
+		body: new ReadableStream({ start(controller) {
+			controller.enqueue(new Uint8Array(unpacked.body));
+			controller.close();
+		} }),
+		status: metadata.s,
+		headers: unpacked.headers,
+		createdAt: metadata.c,
+		ttl: metadata.t
+	};
+}
+/** Check whether an ISR cache entry has passed its freshness lifetime. */
+function isStale(entry, now = Date.now()) {
+	return now - entry.createdAt > entry.ttl * 1e3;
+}
+/** Build an edge-cacheable response from a validated ISR cache entry. */
+function isrCacheResponse(entry, stale, now = Date.now()) {
+	const headers = new Headers(entry.headers);
+	headers.set("x-isr-cache", stale ? "STALE" : "HIT");
+	if (stale) headers.set("Cache-Control", `public, s-maxage=${Math.min(10, entry.ttl)}, max-age=0, must-revalidate`);
+	else {
+		const remainingSeconds = Math.max(0, Math.floor((entry.createdAt + entry.ttl * 1e3 - now) / 1e3));
+		headers.set("Cache-Control", `public, s-maxage=${remainingSeconds}, max-age=0, must-revalidate`);
+	}
+	markSharedCachePolicy(headers);
+	return new Response(entry.body, {
+		status: entry.status,
+		headers
+	});
+}
+/** Resolve an x-revalidate override, falling back for absent or invalid values. */
+function resolveRevalidateTtl(response, defaultTtl) {
+	const header = response.headers.get("x-revalidate");
+	if (header === null) return defaultTtl;
+	const value = Number.parseInt(header, 10);
+	return Number.isNaN(value) || value < 0 ? defaultTtl : value;
+}
+function acceptsEventStream(request) {
+	return request.headers.get("Accept")?.toLowerCase().split(",").some((part) => part.split(";", 1)[0]?.trim() === "text/event-stream") ?? false;
+}
+/** Return whether credentials or EventSource semantics require an ISR bypass. */
+function shouldBypassIsr(request) {
+	return request.headers.has("Cookie") || request.headers.has("Authorization") || acceptsEventStream(request);
+}
+/** Return whether a response explicitly forbids storage in a shared cache. */
+function hasSharedCacheOptOut(response) {
+	if (response.headers.has("Set-Cookie")) return true;
+	const cacheControl = response.headers.get("Cache-Control");
+	if (!cacheControl) return false;
+	return cacheControl.split(",").some((part) => {
+		const directive = part.split("=", 1)[0]?.trim().toLowerCase();
+		return directive === "private" || directive === "no-store" || directive === "no-cache";
+	});
+}
+/** Return whether a complete render may be persisted in the shared ISR cache. */
+function isSharedCacheableResponse(response) {
+	return response.status === 200 && !hasSharedCacheOptOut(response);
+}
+/** Resolve the first matching path TTL using Void route-pattern semantics. */
+function resolvePathTtl(revalidate, pathname) {
+	if (revalidate == null) return 0;
+	if (typeof revalidate === "number") return revalidate;
+	for (const [pattern, ttl] of Object.entries(revalidate)) if (matchSegmentPattern(pattern, pathname)) return ttl;
+	return 0;
+}
+/**
+* Resolve ISR TTL from the framework's ordered page table.
+*
+* The first matching page is authoritative. A baked positive TTL enables ISR,
+* a baked `0` opts out, and an absent TTL inherits from the raw per-path config.
+* Only requests that match no page fall back to the flattened revalidate config.
+*/
+function resolvePageTtl(pages, revalidate, pathRevalidate, pathname) {
+	if (pages) for (const page of pages) {
+		if (!matchSegmentPattern(page.pattern, pathname)) continue;
+		return page.revalidate === void 0 ? resolvePathTtl(pathRevalidate, pathname) : page.revalidate > 0 ? page.revalidate : 0;
+	}
+	return resolvePathTtl(revalidate, pathname);
+}
+/** Extract response headers while removing ISR-managed and private headers. */
+function serializeHeaders(response) {
+	const result = {};
+	response.headers.forEach((value, key) => {
+		if (!SKIP_HEADERS.has(key.toLowerCase())) result[key] = value;
+	});
+	return result;
+}
+/** Validate page data before storing it as the JSON ISR variant. */
+function normalizePageDataForJsonCache(raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		return parsed.deferred === void 0 && parsed.deferredKeys === void 0 ? raw : null;
+	} catch {
+		return null;
+	}
+}
+/** Extract validated Void Pages data embedded in an HTML response. */
+function extractPageDataFromHtml(html) {
+	const match = html.match(PAGE_DATA_SCRIPT_RE);
+	return match ? normalizePageDataForJsonCache(match[2]) : null;
+}
+//#endregion
+export { SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, buildVariantOriginalUrl, decodeIsrCacheEntry, exactQueryAllowlist, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePageTtl, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue };

package/dist/index.d.mts

@@ -0,0 +1,137 @@
+import { IsrCacheMetadata } from "./core.mjs";
+//#region src/index.d.ts
+/**
+ * Build the normalized path segment for an ISR-cached page.
+ * Root path `/` maps to `__index__` to avoid trailing-slash ambiguity.
+ */
+export declare function normalizeIsrPath(pathname: string): string;
+/**
+ * Inverse of `normalizeIsrPath`: turn a normalized segment back into a
+ * pathname starting with `/`.
+ */
+export declare function denormalizeIsrPath(normalized: string): string;
+/**
+ * Canonicalize an inbound pathname to the form used inside edge cache URLs.
+ * Equivalent to `denormalizeIsrPath(normalizeIsrPath(pathname))` — strips any
+ * trailing slash except for root.
+ */
+export declare function canonicalIsrPathname(pathname: string): string;
+/**
+ * Prefix for listing/purging ISR keys.
+ *
+ * `deploymentId === ''` must still produce the versioned prefix with an
+ * empty segment (`<projectId>/isr/v3//`) because dispatch uses
+ * `routing.version ?? 'legacy'`, which allows empty strings and writes
+ * keys at `<projectId>/isr/v3//<path>`. Only `undefined` selects the
+ * legacy scan-all prefix (`<projectId>/isr/`).
+ */
+export declare function isrCachePrefix(projectId: string, deploymentId?: string): string;
+/**
+ * Prefix for listing/purging LEGACY (pre-host-scoping) ISR keys — the `v2`
+ * namespace `<projectId>/isr/v2/<deploymentId>/`. Mirrors `isrCachePrefix`'s
+ * optional-`deploymentId` behavior exactly (empty string yields the versioned
+ * prefix with an empty segment; only `undefined` selects the scan-all
+ * `<projectId>/isr/` prefix).
+ *
+ * Exists SOLELY for the host-scoping rollout: the purger sweeps this namespace
+ * to reap orphaned `v2` KV keys and purge their edge URLs. Current dispatch
+ * neither reads nor writes `v2` keys. Transition-only — remove once `v2`
+ * entries have aged out.
+ */
+export declare function isrLegacyCachePrefix(projectId: string, deploymentId?: string): string;
+/**
+ * Build the cache key for an ISR-cached page.
+ * ISR is deployment-scoped so cached HTML cannot outlive the hashed assets
+ * referenced by the deployment that produced it, and host-scoped (`<host>`
+ * segment after the deployment id) so the same path served under different
+ * hostnames — e.g. a project slug and a custom domain, or two custom
+ * domains — never share a cache slot. `host` is the request hostname the
+ * dispatch worker saw (`new URL(request.url).hostname`).
+ *
+ * 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).
+ */
+export declare function isrCacheKey(projectId: string, deploymentId: string, host: string, pathname: string, originalUrl?: string | null): string;
+/**
+ * Prefix used to list/purge every variant of a given pathname under a
+ * deployment — both the direct-hit key and any rewrite-variant keys.
+ */
+export declare function isrCacheVariantPrefix(projectId: string, deploymentId: string, host: string, pathname: string): string;
+/**
+ * Build the exact LEGACY (pre-host-scoping) direct-hit key for a pathname under
+ * a deployment: `<projectId>/isr/v2/<deploymentId>/<normalizedPath>` — the
+ * hostless counterpart of `isrCacheKey` with no `<host>/` segment and no
+ * rewrite-variant suffix. Used by the purger to reap the orphaned `v2`
+ * direct-hit KV key for a requested path.
+ *
+ * Exists SOLELY for the host-scoping rollout — current dispatch neither writes
+ * nor reads hostless keys. Transition-only. Do not use it on the hot path.
+ */
+export declare function isrLegacyCacheKey(projectId: string, deploymentId: string, pathname: string): string;
+/**
+ * Prefix used to list/purge the pre-host-scoped ("legacy") rewrite variants of
+ * a given pathname under a deployment. Before ISR keys grew a `<host>` segment,
+ * variant keys were written as
+ * `<projectId>/isr/v2/<deploymentId>/<normalizedPath>#rw=<token>` — identical to
+ * `isrCacheVariantPrefix` but with NO `<host>/` segment. Those entries still
+ * persist during the host-scoping rollout (ISR puts set no `expirationTtl`),
+ * so the purger must scan this hostless `v2` prefix in addition to the
+ * host-scoped `v3` one to recover their variant tokens and purge the matching
+ * edge URLs.
+ *
+ * Built off `isrLegacyCachePrefix` (the `v2` namespace), NOT `isrCachePrefix`
+ * (now `v3`), so it targets the legacy hostless keys it is meant to sweep.
+ *
+ * Exists SOLELY for that rollout cleanup — current dispatch neither writes nor
+ * reads hostless keys. Transition-only. Do not use it on the hot path.
+ */
+export declare function isrLegacyCacheVariantPrefix(projectId: string, deploymentId: string, pathname: string): string;
+export declare function hashOriginalUrl(originalUrl: string): string;
+/**
+ * Split a fully-qualified ISR KV key into the normalized pathname segment
+ * and the optional rewrite-variant token. Returns `null` token when the
+ * key has no `#rw=` suffix (direct hit).
+ *
+ * The token is opaque (a hash); the original URL it was derived from is not
+ * recoverable. Callers that need to reproduce the matching edge-cache URL
+ * pass the token through `isrEdgeCacheUrlForToken`.
+ */
+export declare function splitIsrCacheKey(fullKey: string): {
+  normalizedPath: string;
+  variantToken: string | null;
+};
+/**
+ * Build the edge cache URL that dispatch uses as its `caches.default` key
+ * (wrapped in a GET `Request`). The public URL stays clean; the internal
+ * cache key carries the deployment id so a new deploy never reads HTML
+ * produced by an older deploy. The `json` variant separates pages-protocol
+ * JSON responses from HTML for the same path+deployment.
+ *
+ * This MUST match the URL dispatch writes. Dispatch builds the URL from
+ * `new URL(request.url).hostname`; for standard-port HTTPS traffic (all CF
+ * edge traffic) that yields the same origin as the one produced here.
+ */
+export declare function isrEdgeCacheUrl(hostname: string, pathname: string, deploymentId: string, variant: "html" | "json", originalUrl?: string | null): string;
+/**
+ * Like `isrEdgeCacheUrl`, but takes a pre-hashed variant token (from
+ * `splitIsrCacheKey`). Used by the purger, which only knows the hashed
+ * token: the original URL is not recoverable from a KV key.
+ */
+export declare function isrEdgeCacheUrlForToken(hostname: string, pathname: string, deploymentId: string, variant: "html" | "json", variantToken?: string | null): string;
+//#endregion
+export type { IsrCacheMetadata };