@void/isr 0.27.0 → 0.28.0

package/dist/core.d.mts

@@ -10,6 +10,10 @@ export declare const SHARED_CACHE_POLICY_HEADER = "x-void-shared-cache-policy";
 export declare function markSharedCachePolicy(headers: Headers): void;
 /** Reject opaque edge entries admitted before the current privacy policy. */
 export declare function hasCurrentSharedCachePolicy(response: Response): boolean;
+/**
+ * KV metadata stored with every ISR cache entry. Writers should annotate it with
+ * `satisfies IsrCacheMetadata` so a renamed field fails typecheck.
+ */
 export type IsrCacheMetadata = Readonly<{
   /** HTTP status code. */
   s: number;

package/dist/index.d.mts

@@ -17,113 +17,55 @@ export declare function denormalizeIsrPath(normalized: string): string;
  */
 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/`).
+ * Prefix for listing/purging ISR keys. An empty `deploymentId` still yields the
+ * versioned prefix (`<projectId>/isr/v3//`), because writers may use an empty
+ * id. Only `undefined` selects every key (`<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.
+ * Like `isrCachePrefix`, for hostless `v2` keys. The `isrLegacy*` helpers exist
+ * only to purge `v2` entries; remove them once those 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`).
+ * KV key for an ISR-cached page: `<proj>/isr/v3/<D>/<host>/<path>`. Deployment
+ * scoping keeps cached HTML from outliving its hashed assets; host scoping keeps
+ * different hostnames apart. `host` is the request 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`.
- *
- * 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 unsuffixed key.
+ * Pass `originalUrl` for a rewritten request (or a query variant). It adds a
+ * `#rw=<token>` suffix, so a rewrite from `/docs` to `/en/docs` does not share
+ * an entry with a direct hit on `/en/docs`.
  */
 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.
- */
+/** Prefix for listing/purging the `#rw=` variant keys of a pathname (not its direct-hit key). */
 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.
- */
+/** Hostless `v2` direct-hit key for a pathname (purge only; see `isrLegacyCachePrefix`). */
 export declare function isrLegacyCacheKey(projectId: string, deploymentId: string, pathname: string): string;
+/** Hostless `v2` rewrite-variant prefix for a pathname (purge only; see `isrLegacyCachePrefix`). */
+export declare function isrLegacyCacheVariantPrefix(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.
+ * Hash an original URL into a 16-hex-char variant token (FNV-1a 64-bit), used
+ * as both the KV-key suffix and the `__void_orig` edge-cache parameter. It is
+ * sync so it fits every read/write path, and opaque so KV never exposes
+ * original URLs or their query strings. Not cryptographic.
  */
-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`.
+ * Split an ISR KV key into its normalized path and its `#rw=` variant token
+ * (`null` for a direct hit). Pass the token to `isrEdgeCacheUrlForToken` to
+ * rebuild the matching edge-cache URL.
  */
 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.
+ * Edge-cache (`caches.default`) URL for an ISR page. It carries the deployment
+ * id so a new deploy never reads older HTML, and the `json` variant keeps
+ * Pages-protocol JSON apart from HTML for the same path.
  */
 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.
- */
+/** Like `isrEdgeCacheUrl`, but takes a variant token from `splitIsrCacheKey`. */
 export declare function isrEdgeCacheUrlForToken(hostname: string, pathname: string, deploymentId: string, variant: "html" | "json", variantToken?: string | null): string;
 //#endregion
 export type { IsrCacheMetadata };

package/dist/index.mjs

@@ -1,32 +1,16 @@
 //#region src/index.ts
 /**
-* Shared ISR key/URL helpers used by both the API (purge) and the dispatch
-* worker (read/write). These functions MUST produce byte-identical output:
-* the API purges KV keys and edge URLs that dispatch writes and reads.
+* ISR cache keys and edge-cache URLs. Writers, readers, and purgers must build
+* byte-identical keys, so all of them use these helpers.
 *
-* Dispatch derives the deployment id for its keys via
-* `routing.version ?? 'legacy'`, which allows any non-nullish value —
-* including the empty string — to pass through unchanged. The helpers below
-* preserve that shape so the API can compute the exact same key for purge.
+* Key shapes: `v3` = `<proj>/isr/v3/<D>/<host>/<path>[#rw=<token>]`;
+* `v2` = hostless `<proj>/isr/v2/<D>/<path>`, kept only to purge old entries.
 */
 const ISR_CACHE_KEY_VERSION = "v3";
 /**
-* Previous key version. `v3` keys are ALWAYS host-scoped
-* (`<proj>/isr/v3/<D>/<host>/<path>`); `v2` keys are ALWAYS hostless
-* (`<proj>/isr/v2/<D>/<path>`) — the `<host>` segment did not exist yet.
-*
-* The bump to `v3` was forced by a real aliasing hazard: under a single
-* version, a host-scoped key `<D>/<host>/<path>` and a legacy hostless key
-* `<D>/<host>/<path>` are byte-identical whenever the legacy path's leading
-* segment happens to look like a hostname. Dotted leading path segments are
-* legal (`[domain]` → `:domain`, `[...slug]` → `(.+)`), so a hostless key for
-* the page `/example.com/about` collides exactly with the host-scoped key for
-* `(host=example.com, /about)`. The stored metadata is only `{s,c,t}` (no
-* path/host), so a reader cannot tell them apart and could serve one page's
-* body for the other. Encoding the shape in the version removes the ambiguity:
-* the version alone determines whether a `<host>` segment is present, so no
-* runtime heuristic (e.g. "is the first segment an attached hostname?") is
-* needed to classify a key. Package-internal, like `ISR_CACHE_KEY_VERSION`.
+* Hostless key version. Host scoping needed a new version: otherwise a hostless
+* key for `/example.com/about` would equal the host-scoped key for
+* (`example.com`, `/about`).
 */
 const ISR_LEGACY_CACHE_KEY_VERSION = "v2";
 /**
@@ -62,125 +46,57 @@ function versionedIsrCachePrefix(projectId, version, deploymentId) {
 	return `${projectId}/isr/`;
 }
 /**
-* 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/`).
+* Prefix for listing/purging ISR keys. An empty `deploymentId` still yields the
+* versioned prefix (`<projectId>/isr/v3//`), because writers may use an empty
+* id. Only `undefined` selects every key (`<projectId>/isr/`).
 */
 function isrCachePrefix(projectId, deploymentId) {
 	return versionedIsrCachePrefix(projectId, ISR_CACHE_KEY_VERSION, deploymentId);
 }
 /**
-* 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.
+* Like `isrCachePrefix`, for hostless `v2` keys. The `isrLegacy*` helpers exist
+* only to purge `v2` entries; remove them once those entries have aged out.
 */
 function isrLegacyCachePrefix(projectId, deploymentId) {
 	return versionedIsrCachePrefix(projectId, ISR_LEGACY_CACHE_KEY_VERSION, deploymentId);
 }
-/**
-* Separator that marks the rewrite-variant suffix on an ISR cache key or
-* the corresponding edge-cache URL parameter. `#` cannot appear in
-* `url.pathname` (fragments are stripped before the request reaches the
-* server) and does not survive `normalizeIsrPath`, so it unambiguously
-* identifies the variant suffix.
-*/
+/** `#` never appears in a request pathname, so it unambiguously marks the variant suffix. */
 const ISR_VARIANT_SEPARATOR = "#rw=";
 /**
-* 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`.
+* KV key for an ISR-cached page: `<proj>/isr/v3/<D>/<host>/<path>`. Deployment
+* scoping keeps cached HTML from outliving its hashed assets; host scoping keeps
+* different hostnames apart. `host` is the request hostname.
 *
-* 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 unsuffixed key.
+* Pass `originalUrl` for a rewritten request (or a query variant). It adds a
+* `#rw=<token>` suffix, so a rewrite from `/docs` to `/en/docs` does not share
+* an entry with a direct hit on `/en/docs`.
 */
 function isrCacheKey(projectId, deploymentId, host, pathname, originalUrl) {
 	const base = `${isrCachePrefix(projectId, deploymentId)}${host}/${normalizeIsrPath(pathname)}`;
 	if (!originalUrl) return base;
 	return `${base}${ISR_VARIANT_SEPARATOR}${hashOriginalUrl(originalUrl)}`;
 }
-/**
-* Prefix used to list/purge every variant of a given pathname under a
-* deployment — both the direct-hit key and any rewrite-variant keys.
-*/
+/** Prefix for listing/purging the `#rw=` variant keys of a pathname (not its direct-hit key). */
 function isrCacheVariantPrefix(projectId, deploymentId, host, pathname) {
 	return `${isrCachePrefix(projectId, deploymentId)}${host}/${normalizeIsrPath(pathname)}${ISR_VARIANT_SEPARATOR}`;
 }
-/**
-* 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.
-*/
+/** Hostless `v2` direct-hit key for a pathname (purge only; see `isrLegacyCachePrefix`). */
 function isrLegacyCacheKey(projectId, deploymentId, pathname) {
 	return `${isrLegacyCachePrefix(projectId, deploymentId)}${normalizeIsrPath(pathname)}`;
 }
-/**
-* 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.
-*/
+/** Hostless `v2` rewrite-variant prefix for a pathname (purge only; see `isrLegacyCachePrefix`). */
 function isrLegacyCacheVariantPrefix(projectId, deploymentId, pathname) {
 	return `${isrLegacyCachePrefix(projectId, deploymentId)}${normalizeIsrPath(pathname)}${ISR_VARIANT_SEPARATOR}`;
 }
-/**
-* Hash an original-URL value into a fixed-length, opaque variant token.
-* Used as both the KV-key suffix and the `__void_orig` query value, so the
-* writer and purger paths see byte-identical tokens for the same URL.
-*
-* Properties:
-*   - 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, 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.
-*
-* Implementation: FNV-1a 64-bit over UTF-8 bytes. BigInt arithmetic for the
-* multiply (no native u64 in JS), but inputs are short (URLs, sub-1KB) and
-* this only runs once per ISR-touched request.
-*/
 const FNV_OFFSET_BASIS = 14695981039346656037n;
 const FNV_PRIME = 1099511628211n;
 const FNV_MASK = 18446744073709551615n;
+/**
+* Hash an original URL into a 16-hex-char variant token (FNV-1a 64-bit), used
+* as both the KV-key suffix and the `__void_orig` edge-cache parameter. It is
+* sync so it fits every read/write path, and opaque so KV never exposes
+* original URLs or their query strings. Not cryptographic.
+*/
 function hashOriginalUrl(originalUrl) {
 	const bytes = new TextEncoder().encode(originalUrl);
 	let h = FNV_OFFSET_BASIS;
@@ -191,13 +107,9 @@ function hashOriginalUrl(originalUrl) {
 	return h.toString(16).padStart(16, "0");
 }
 /**
-* 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`.
+* Split an ISR KV key into its normalized path and its `#rw=` variant token
+* (`null` for a direct hit). Pass the token to `isrEdgeCacheUrlForToken` to
+* rebuild the matching edge-cache URL.
 */
 function splitIsrCacheKey(fullKey) {
 	const sepIdx = fullKey.indexOf(ISR_VARIANT_SEPARATOR);
@@ -211,24 +123,14 @@ function splitIsrCacheKey(fullKey) {
 	};
 }
 /**
-* 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.
+* Edge-cache (`caches.default`) URL for an ISR page. It carries the deployment
+* id so a new deploy never reads older HTML, and the `json` variant keeps
+* Pages-protocol JSON apart from HTML for the same path.
 */
 function isrEdgeCacheUrl(hostname, pathname, deploymentId, variant, originalUrl) {
 	return buildIsrEdgeCacheUrl(hostname, pathname, deploymentId, variant, originalUrl ? hashOriginalUrl(originalUrl) : null);
 }
-/**
-* 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.
-*/
+/** Like `isrEdgeCacheUrl`, but takes a variant token from `splitIsrCacheKey`. */
 function isrEdgeCacheUrlForToken(hostname, pathname, deploymentId, variant, variantToken) {
 	return buildIsrEdgeCacheUrl(hostname, pathname, deploymentId, variant, variantToken ?? null);
 }

package/dist/runtime.d.mts

@@ -4,36 +4,13 @@ import { canonicalIsrPathname, denormalizeIsrPath, normalizeIsrPath } from "./in
 import { matchSegmentPattern } from "@void/edge";
 //#region src/runtime.d.ts
 /**
- * Single-tenant ISR (incremental static regeneration) cache ladder for the
- * direct Cloudflare Worker (Void apps and framework deploy wrappers).
- *
- * On managed Void, ISR lives in the dispatch worker that sits IN FRONT of the
- * user worker. Self-host has no dispatch worker, so this module ports that
- * caching ladder INTO the user worker, collapsed from multi-tenant to a single
- * deployment:
- *
- *   - 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`. 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.
- *
- * Fail-open contract: every `env.ISR_CACHE` (KV) and `caches.default` operation
- * is wrapped so a misconfigured or erroring cache degrades to a live render,
- * never a 500. Read/hit-path failures bail (caller renders live); write-path
- * failures are swallowed.
- *
- * Worker-only: no `lib.dom` types — globals come from `@cloudflare/workers-types`.
- *
- * Ported from the hosted dispatch runtime and the shared `@void/isr` contract.
- */
-/**
- * Minimal env surface this module needs. Both fields are optional so a worker
- * with no ISR binding (or a caller that only knows the deployment id) still
- * typechecks and fails open at runtime.
+ * Single-tenant ISR cache for a direct Cloudflare Worker (Void apps and
+ * framework deploy wrappers). Every `ISR_CACHE` (KV) and `caches.default`
+ * operation fails open: read errors render live, write errors are ignored.
+ * KV helpers read the deployment id from `env.__VOID_ISR_DEPLOYMENT_ID`;
+ * edge-cache keys use the `deploymentId` option. Both hold the same value.
  */
+/** Env fields ISR reads. Both are optional: without them ISR fails open. */
 export interface IsrCacheEnv {
   ISR_CACHE?: KVNamespace;
   __VOID_ISR_DEPLOYMENT_ID?: string;
@@ -54,19 +31,15 @@ export declare const MAX_ISR_VARIANTS_PER_PATH = 200;
 /** Prefix for the current direct deployment's host-scoped cache entries. */
 export declare function isrPrefix(deploymentId: string): string;
 /**
- * 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.).
+ * KV key for an ISR-cached page, scoped by deployment (a new deploy starts with
+ * a cold cache) and by host (custom domain, workers.dev, apex, and www stay apart).
  */
 export declare function isrKey(deploymentId: string, host: string, pathname: string, variantUrl?: string | null): string;
 export declare function isrVariantPrefix(deploymentId: string, host: string, pathname: string): string;
 /**
- * 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.
+ * Host-registry key. Every host that writes cached content registers here, so a
+ * purge without a request host (cron or queue `revalidate({ paths })`) can find
+ * the hosts to purge.
  */
 export declare function hostRegistryKey(deploymentId: string, host: string): string;
 /**
@@ -80,68 +53,43 @@ export declare function htmlEdgeKey(host: string, pathname: string, id: string,
  * the `&__void=json` marker.
  */
 export declare function jsonEdgeKey(host: string, pathname: string, id: string, variantUrl?: string | null): string;
-/**
- * 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.
- */
+/** Read an ISR entry from KV. Returns null on a miss, a malformed entry, or any KV error. */
 export declare function readIsrCache(env: IsrCacheEnv, host: string, pathname: string, variantUrl?: string | null): Promise<IsrCacheEntry | null>;
 /**
- * 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).
+ * Write an ISR entry to KV. The response is cloned before any `await`, so the
+ * caller can stream the original body to the client. KV errors are ignored.
  */
 export declare function writeIsrCache(env: IsrCacheEnv, host: string, pathname: string, response: Response, ttl: number, variantUrl?: string | null): Promise<void>;
 /**
- * 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.
+ * List every host registered for a deployment. A registry read error returns
+ * the hosts collected so far instead of throwing.
  */
 export declare function listIsrHosts(kv: KVNamespace, deploymentId: string): Promise<Array<string>>;
-/**
- * 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).
- */
+/** Delete an ISR entry from KV (for example after `x-revalidate: 0`). KV errors are ignored. */
 export declare function deleteIsrCache(env: IsrCacheEnv, host: string, pathname: string, variantUrl?: string | null): Promise<void>;
 export declare function clientRevalidateResponse(response: Response): Response;
 export declare function isEventStreamResponse(response: Response): boolean;
 /**
- * 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`.
+ * Fill the JSON edge cache from a response's page data (the `x-void-page-data`
+ * header or the `__VOID_PAGE_DATA__` script). Does nothing without page data;
+ * cache errors are ignored.
  */
 export declare function populateJsonEdgeCache(cache: Cache | undefined, cacheKey: string, response: Response, ttl: number, state: "HIT" | "MISS"): Promise<void>;
-/**
- * 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.
- */
+/** Copy a request without its `X-VoidPages` header. */
 export declare function cloneWithoutVoidPages(request: Request): Request;
 /** Cache only framework document HTML; leave client data requests and other response types live. */
 export declare function handleFrameworkIsr(request: Request, env: IsrCacheEnv, ctx: ExecutionContext, options: HandleIsrOptions, render: RenderFn): Promise<Response | null>;
 /**
- * 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, a read/hit
- * cache op failed open, or a cache miss for a URL carrying query params
- * outside the allowlist).
+ * Run the ISR cache ladder for a request. Returns the response to send, or
+ * `null` when the caller should render live: the request is not eligible
+ * (not GET, `/api`, Range, `shouldBypassIsr`, or no TTL), a cache read failed,
+ * or a miss carries query params outside the allowlist.
  *
- * 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.
+ * Pages-protocol (`X-VoidPages`) requests read only the JSON edge cache, and a
+ * miss renders live without caching; HTML renders fill the JSON variant. HTML
+ * requests read the edge cache, then KV. A stale hit is served while it
+ * revalidates in the background, and a cacheable miss fills KV and the edge
+ * cache in the background.
  */
 export declare function handleIsr(request: Request, env: IsrCacheEnv, ctx: ExecutionContext, options: HandleIsrOptions, render: RenderFn): Promise<Response | null>;
 //#endregion

package/dist/runtime.mjs

@@ -10,11 +10,8 @@ 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.).
+* KV key for an ISR-cached page, scoped by deployment (a new deploy starts with
+* a cold cache) and by host (custom domain, workers.dev, apex, and www stay apart).
 */
 function isrKey(deploymentId, host, pathname, variantUrl) {
 	return isrCacheKey(DIRECT_ISR_PROJECT_ID, deploymentId, host, pathname, variantUrl);
@@ -23,10 +20,9 @@ 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.
+* Host-registry key. Every host that writes cached content registers here, so a
+* purge without a request host (cron or queue `revalidate({ paths })`) can find
+* the hosts to purge.
 */
 function hostRegistryKey(deploymentId, host) {
 	return `void-isr-hosts/${deploymentId}/${host}`;
@@ -46,12 +42,7 @@ function htmlEdgeKey(host, pathname, id, variantUrl) {
 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.
-*/
+/** Read an ISR entry from KV. Returns null on a miss, a malformed entry, or any KV error. */
 async function readIsrCache(env, host, pathname, variantUrl) {
 	const kv = env.ISR_CACHE;
 	if (!kv) return null;
@@ -68,10 +59,8 @@ async function readIsrCache(env, host, pathname, variantUrl) {
 	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).
+* Write an ISR entry to KV. The response is cloned before any `await`, so the
+* caller can stream the original body to the client. KV errors are ignored.
 */
 async function writeIsrCache(env, host, pathname, response, ttl, variantUrl) {
 	const kv = env.ISR_CACHE;
@@ -104,11 +93,7 @@ async function isVariantWriteAllowed(kv, deploymentId, host, pathname, key) {
 	});
 	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.
-*/
+/** `${id}/${host}` pairs this isolate has registered: one registry write per pair, not per page. */
 const registeredHosts = /* @__PURE__ */ new Set();
 async function registerIsrHost(kv, deploymentId, host) {
 	const guardKey = `${deploymentId}/${host}`;
@@ -121,10 +106,8 @@ async function registerIsrHost(kv, deploymentId, host) {
 	}
 }
 /**
-* 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.
+* List every host registered for a deployment. A registry read error returns
+* the hosts collected so far instead of throwing.
 */
 async function listIsrHosts(kv, deploymentId) {
 	const prefix = `void-isr-hosts/${deploymentId}/`;
@@ -142,10 +125,7 @@ async function listIsrHosts(kv, deploymentId) {
 	} 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).
-*/
+/** Delete an ISR entry from KV (for example after `x-revalidate: 0`). KV errors are ignored. */
 async function deleteIsrCache(env, host, pathname, variantUrl) {
 	const kv = env.ISR_CACHE;
 	if (!kv) return;
@@ -199,10 +179,9 @@ function jsonCacheResponse(pageData, ttl, state) {
 	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`.
+* Fill the JSON edge cache from a response's page data (the `x-void-page-data`
+* header or the `__VOID_PAGE_DATA__` script). Does nothing without page data;
+* cache errors are ignored.
 */
 async function populateJsonEdgeCache(cache, cacheKey, response, ttl, state) {
 	if (!cache) return;
@@ -213,19 +192,7 @@ async function populateJsonEdgeCache(cache, cacheKey, response, ttl, state) {
 		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?.`).
-*/
+/** `caches.default`, or `undefined` when reading it throws (for example, with no Cache API). */
 function edgeCache() {
 	try {
 		return caches.default;
@@ -250,26 +217,20 @@ async function deleteSharedIsrVariants(env, cache, host, pathname, keys, variant
 	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.
-*/
+/** Copy a request without its `X-VoidPages` header. */
 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.
+* Re-render a stale page in the background and refresh KV and the edge cache.
+* Errors are logged and the stale entry keeps serving. 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, htmlOnly, staleSinceMs) {
 	try {
-		const response = await render(cloneWithoutVoidPages(request));
+		const response = await render(request);
 		const ttl = resolveRevalidateTtl(response, defaultTtl);
 		const cache = edgeCache();
 		if (response.status === 200 && isEventStreamResponse(response)) {
@@ -282,7 +243,7 @@ async function revalidateInBackground(env, request, host, pathname, defaultTtl,
 				status: response.status,
 				headers: sharedHtmlCacheHeaders(response, ttl, "HIT")
 			}));
-			await populateJsonEdgeCache(cache, keys.jsonKey, response, ttl, "HIT");
+			if (!htmlOnly) await populateJsonEdgeCache(cache, keys.jsonKey, response, ttl, "HIT");
 		} 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);
@@ -294,24 +255,16 @@ async function handleFrameworkIsr(request, env, ctx, options, render) {
 	return handleIsrInternal(request, env, ctx, options, render, true);
 }
 /**
-* 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, a read/hit
-* cache op failed open, or a cache miss for a URL carrying query params
-* outside the allowlist).
+* Run the ISR cache ladder for a request. Returns the response to send, or
+* `null` when the caller should render live: the request is not eligible
+* (not GET, `/api`, Range, `shouldBypassIsr`, or no TTL), a cache read failed,
+* or a miss carries query params outside the allowlist.
 *
-* 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.
+* Pages-protocol (`X-VoidPages`) requests read only the JSON edge cache, and a
+* miss renders live without caching; HTML renders fill the JSON variant. HTML
+* requests read the edge cache, then KV. A stale hit is served while it
+* revalidates in the background, and a cacheable miss fills KV and the edge
+* cache in the background.
 */
 async function handleIsr(request, env, ctx, options, render) {
 	return handleIsrInternal(request, env, ctx, options, render, false);
@@ -381,7 +334,7 @@ async function handleIsrInternal(request, env, ctx, options, render, htmlOnly) {
 	const ttl = resolveRevalidateTtl(response, isrTtl);
 	if (isStorableRender(response, ttl, htmlOnly)) {
 		ctx.waitUntil(writeIsrCache(env, host, pathname, response, ttl, variantUrl));
-		ctx.waitUntil(populateJsonEdgeCache(cache, jsonKey, response, ttl, "HIT"));
+		if (!htmlOnly) ctx.waitUntil(populateJsonEdgeCache(cache, jsonKey, response, ttl, "HIT"));
 		const cacheResponse = new Response(response.clone().body, {
 			status: response.status,
 			headers: sharedHtmlCacheHeaders(response, ttl, "HIT")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@void/isr",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Incremental revalidation and cache helpers for Void runtimes.",
   "homepage": "https://void.cloud",
   "bugs": {
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@cloudflare/workers-types": "^5.20261009.1",
-    "@void/edge": "0.27.0"
+    "@void/edge": "0.28.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",