@void/isr 0.20.0

package/dist/index.mjs

@@ -0,0 +1,265 @@
+//#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.
+*
+* 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.
+*/
+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`.
+*/
+const ISR_LEGACY_CACHE_KEY_VERSION = "v2";
+/**
+* Build the normalized path segment for an ISR-cached page.
+* Root path `/` maps to `__index__` to avoid trailing-slash ambiguity.
+*/
+function normalizeIsrPath(pathname) {
+	let normalized = pathname;
+	if (normalized === "/") normalized = "__index__";
+	else {
+		normalized = normalized.startsWith("/") ? normalized.slice(1) : normalized;
+		if (normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+	}
+	return normalized;
+}
+/**
+* Inverse of `normalizeIsrPath`: turn a normalized segment back into a
+* pathname starting with `/`.
+*/
+function denormalizeIsrPath(normalized) {
+	return normalized === "__index__" ? "/" : `/${normalized}`;
+}
+/**
+* Canonicalize an inbound pathname to the form used inside edge cache URLs.
+* Equivalent to `denormalizeIsrPath(normalizeIsrPath(pathname))` — strips any
+* trailing slash except for root.
+*/
+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}/`;
+}
+/**
+* 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/`).
+*/
+function isrCachePrefix(projectId, deploymentId) {
+	if (deploymentId !== void 0) return `${isrCacheVersionPrefix(projectId)}${deploymentId}/`;
+	return `${projectId}/isr/`;
+}
+/**
+* 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.
+*/
+function isrLegacyCachePrefix(projectId, deploymentId) {
+	if (deploymentId !== void 0) return `${isrLegacyCacheVersionPrefix(projectId)}${deploymentId}/`;
+	return `${projectId}/isr/`;
+}
+/**
+* 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.
+*/
+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`.
+* 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).
+*/
+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.
+*/
+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.
+*/
+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.
+*/
+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, and the previous base64url
+*     encoding let any operator with list access read the original URLs
+*     (including sensitive query strings like `?token=…`, `?email=…`).
+*   - 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;
+function hashOriginalUrl(originalUrl) {
+	const bytes = new TextEncoder().encode(originalUrl);
+	let h = FNV_OFFSET_BASIS;
+	for (let i = 0; i < bytes.length; i++) {
+		h = (h ^ BigInt(bytes[i])) & FNV_MASK;
+		h = h * FNV_PRIME & FNV_MASK;
+	}
+	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`.
+*/
+function splitIsrCacheKey(fullKey) {
+	const sepIdx = fullKey.indexOf(ISR_VARIANT_SEPARATOR);
+	if (sepIdx === -1) return {
+		normalizedPath: fullKey,
+		variantToken: null
+	};
+	return {
+		normalizedPath: fullKey.slice(0, sepIdx),
+		variantToken: fullKey.slice(sepIdx + 4)
+	};
+}
+/**
+* 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.
+*/
+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.
+*/
+function isrEdgeCacheUrlForToken(hostname, pathname, deploymentId, variant, variantToken) {
+	return buildIsrEdgeCacheUrl(hostname, pathname, deploymentId, variant, variantToken ?? null);
+}
+function buildIsrEdgeCacheUrl(hostname, pathname, deploymentId, variant, variantToken) {
+	const normalizedPathname = canonicalIsrPathname(pathname);
+	const url = new URL(`https://${hostname}${normalizedPathname}`);
+	if (variant === "json") url.searchParams.set("__void", "json");
+	url.searchParams.set("__void_isr", deploymentId);
+	if (variantToken) url.searchParams.set("__void_orig", variantToken);
+	return url.toString();
+}
+//#endregion
+export { canonicalIsrPathname, denormalizeIsrPath, hashOriginalUrl, isrCacheKey, isrCachePrefix, isrCacheVariantPrefix, isrEdgeCacheUrl, isrEdgeCacheUrlForToken, isrLegacyCacheKey, isrLegacyCachePrefix, isrLegacyCacheVariantPrefix, normalizeIsrPath, splitIsrCacheKey };

package/dist/runtime.d.mts

@@ -0,0 +1,145 @@
+/// <reference types="@cloudflare/workers-types" />
+import { IsrCacheEntry, IsrCacheMetadata, QueryAllowlist, SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, normalizePageDataForJsonCache, packIsrValue, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue } from "./core.mjs";
+import { canonicalIsrPathname, denormalizeIsrPath, normalizeIsrPath } from "./index.mjs";
+import { matchSegmentPattern } from "@void/edge";
+//#region src/runtime.d.ts
+/**
+ * Single-tenant ISR (incremental static regeneration) cache ladder for the
+ * self-hosted Void worker (`vite build && wrangler deploy`).
+ *
+ * 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` (Task 7). 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.
+ */
+export interface IsrCacheEnv {
+  ISR_CACHE?: KVNamespace;
+  __VOID_ISR_DEPLOYMENT_ID?: string;
+}
+/** Renders a live response for a request (worker dispatch + asset serving). */
+export type RenderFn = (request: Request) => Promise<Response>;
+export type HandleIsrOptions = Readonly<{
+  revalidate: number | Record<string, number> | undefined;
+  pages?: ReadonlyArray<{
+    pattern: string;
+    revalidate?: number;
+  }>;
+  pathRevalidate?: Record<string, number>;
+  deploymentId: string;
+  queryAllowlist?: QueryAllowlist;
+}>;
+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.).
+ */
+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.
+ */
+export declare function hostRegistryKey(deploymentId: string, host: string): string;
+/**
+ * Edge-cache (`caches.default`) key for the HTML variant. The public URL stays
+ * clean; this internal key carries the deployment id so a new deploy never
+ * reads HTML produced by an older deploy.
+ */
+export declare function htmlEdgeKey(host: string, pathname: string, id: string, variantUrl?: string | null): string;
+/**
+ * Edge-cache key for the JSON (pages-protocol) variant. Separated from HTML by
+ * 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.
+ */
+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).
+ */
+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.
+ */
+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).
+ */
+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`.
+ */
+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.
+ */
+export declare function cloneWithoutVoidPages(request: Request): Request;
+/**
+ * Run the ISR caching ladder for a request.
+ *
+ * Returns a cached/rendered `Response` when ISR applies, or `null` when the
+ * caller should render live itself (request not ISR-eligible, or a read/hit
+ * cache op failed open).
+ *
+ * Ladder:
+ *   - Bail (`null`) if not GET, an API path, a Range request, `shouldBypassIsr`,
+ *     or the path has no ISR TTL. Range requests bail BEFORE any cache read/write so they
+ *     render live (correct 206) and never touch the shared full-response entry.
+ *   - JSON (X-VoidPages) path: edge match → hit serves `clientRevalidateResponse`;
+ *     miss renders live JSON and returns it — the JSON path never writes the edge
+ *     cache. The JSON edge variant is warmed only as a side-effect of the HTML
+ *     render path (cold colo re-renders JSON).
+ *   - HTML path: L1 edge match → L2 KV. Hit serves `isrCacheResponse`
+ *     (stale hits also queue a background revalidation). Miss renders live and,
+ *     when cacheable, writes KV + JSON edge + HTML edge in the background.
+ */
+export declare function handleIsr(request: Request, env: IsrCacheEnv, ctx: ExecutionContext, options: HandleIsrOptions, render: RenderFn): Promise<Response | null>;
+//#endregion
+export { type IsrCacheEntry, type IsrCacheMetadata, SHARED_CACHE_POLICY_HEADER, SHARED_CACHE_POLICY_VERSION, canonicalIsrPathname, denormalizeIsrPath, extractPageDataFromHtml, hasCurrentSharedCachePolicy, hasSharedCacheOptOut, isSharedCacheableResponse, isStale, isrCacheResponse, markSharedCachePolicy, matchSegmentPattern as matchLiteralPattern, normalizeIsrPath, normalizePageDataForJsonCache, packIsrValue, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue };