void 0.10.8 → 0.10.10

package/dist/runtime/env-public.mjs

@@ -1,5 +1,5 @@
-import { i as getRawRuntimeEnv } from "../env-raw-CoS20LHP.mjs";
-import { getRuntimeEnv } from "./env.mjs";
+import { a as getRawRuntimeEnv } from "../env-raw-Cx8ElDdj.mjs";
+import { getRuntimeEnv, isInternalBinding } from "./env.mjs";
 import { boolean, email, getSecretOverride, json, number, oneOf, string, url } from "./env-helpers.mjs";
 //#region src/shared/env-mask.ts
 /**
@@ -177,7 +177,10 @@ async function _validateEnvOnce(envValues) {
 				validatedCache.set(cacheKey, cache);
 				cacheList.push(cache);
 			}
-			for (const [key, value] of report.values) if (!cache.has(key)) cache.set(key, value);
+			for (const [key, value] of report.values) {
+				if (isInternalBinding(key, cacheKey)) continue;
+				if (!cache.has(key)) cache.set(key, value);
+			}
 		} catch {}
 		bootValidationState = { ok: true };
 		return;
@@ -254,11 +257,13 @@ var EnvValidationError = class extends Error {
 	}
 };
 function readKey(key) {
+	const rawEnv = getRawRuntimeEnv();
+	if (isInternalBinding(key, rawEnv)) return;
 	const rawValue = getRuntimeEnv()[key];
 	if (!registeredSchema) return rawValue;
 	const validator = registeredSchema[key];
 	if (!validator) return rawValue;
-	const cacheKey = getRawRuntimeEnv();
+	const cacheKey = rawEnv;
 	let cache = validatedCache.get(cacheKey);
 	if (!cache) {
 		cache = /* @__PURE__ */ new Map();

package/dist/runtime/env.d.mts

@@ -5,9 +5,22 @@ type RuntimeEnv = Record<string, unknown>;
 //#endregion
 //#region src/runtime/env.d.ts
 declare function withRuntimeEnv<T>(env: unknown, fn: () => T): T;
+/**
+* Shared internal-binding predicate. A binding is framework-internal — and must
+* never be exposed to user code — when it carries an internal prefix
+* (`__VOID_`, `__PROJECT_`; always hidden) or is an exact-name internal (e.g.
+* `ISR_CACHE`; hidden ONLY while ISR is active for the isolate). `rawEnv` is the
+* unfiltered runtime env, consulted via {@link isIsrActive} to gate the
+* exact-name check so a non-ISR app's own `ISR_CACHE` binding stays visible —
+* matching the build-time `isr` gate on the generated `c.env` filter.
+*
+* Single source of truth for the runtime `env` filter here and the public
+* `void/env` proxy (`env-public.ts`).
+*/
+declare function isInternalBinding(name: string, rawEnv: RuntimeEnv): boolean;
 /** Returns the runtime env with internal platform bindings hidden. */
 declare function getRuntimeEnv(): RuntimeEnv;
 declare function getRuntimeBinding<T = unknown>(name: string): T | undefined;
 declare function requireRuntimeBinding<T = unknown>(name: string): T;
 //#endregion
-export { type RuntimeEnv, getRuntimeBinding, getRuntimeEnv, requireRuntimeBinding, withRuntimeEnv };
+export { type RuntimeEnv, getRuntimeBinding, getRuntimeEnv, isInternalBinding, requireRuntimeBinding, withRuntimeEnv };

package/dist/runtime/env.mjs

@@ -1,4 +1,4 @@
-import { i as getRawRuntimeEnv, n as asEnv, r as envContext, t as INTERNAL_BINDING_PREFIXES } from "../env-raw-CoS20LHP.mjs";
+import { a as getRawRuntimeEnv, i as envContext, n as INTERNAL_BINDING_PREFIXES, o as isIsrActive, r as asEnv, t as INTERNAL_BINDING_EXACT_NAMES } from "../env-raw-Cx8ElDdj.mjs";
 //#region src/runtime/env.ts
 /**
 * Public runtime env API — exposed via "void/_env".
@@ -12,24 +12,37 @@ function withRuntimeEnv(env, fn) {
 	if (!resolved) return fn();
 	return envContext.run(resolved, fn);
 }
-function isInternalBinding(name) {
-	return INTERNAL_BINDING_PREFIXES.some((p) => name.startsWith(p));
+/**
+* Shared internal-binding predicate. A binding is framework-internal — and must
+* never be exposed to user code — when it carries an internal prefix
+* (`__VOID_`, `__PROJECT_`; always hidden) or is an exact-name internal (e.g.
+* `ISR_CACHE`; hidden ONLY while ISR is active for the isolate). `rawEnv` is the
+* unfiltered runtime env, consulted via {@link isIsrActive} to gate the
+* exact-name check so a non-ISR app's own `ISR_CACHE` binding stays visible —
+* matching the build-time `isr` gate on the generated `c.env` filter.
+*
+* Single source of truth for the runtime `env` filter here and the public
+* `void/env` proxy (`env-public.ts`).
+*/
+function isInternalBinding(name, rawEnv) {
+	if (INTERNAL_BINDING_PREFIXES.some((p) => name.startsWith(p))) return true;
+	return isIsrActive(rawEnv) && INTERNAL_BINDING_EXACT_NAMES.includes(name);
 }
 function filterEnvProxy(env) {
 	return new Proxy(env, {
 		get(target, prop, receiver) {
-			if (typeof prop === "string" && isInternalBinding(prop)) return;
+			if (typeof prop === "string" && isInternalBinding(prop, target)) return;
 			return Reflect.get(target, prop, receiver);
 		},
 		has(target, prop) {
-			if (typeof prop === "string" && isInternalBinding(prop)) return false;
+			if (typeof prop === "string" && isInternalBinding(prop, target)) return false;
 			return Reflect.has(target, prop);
 		},
 		ownKeys(target) {
-			return Reflect.ownKeys(target).filter((key) => typeof key !== "string" || !isInternalBinding(key));
+			return Reflect.ownKeys(target).filter((key) => typeof key !== "string" || !isInternalBinding(key, target));
 		},
 		getOwnPropertyDescriptor(target, prop) {
-			if (typeof prop === "string" && isInternalBinding(prop)) return;
+			if (typeof prop === "string" && isInternalBinding(prop, target)) return;
 			return Reflect.getOwnPropertyDescriptor(target, prop);
 		}
 	});
@@ -39,8 +52,9 @@ function getRuntimeEnv() {
 	return filterEnvProxy(getRawRuntimeEnv());
 }
 function getRuntimeBinding(name) {
-	if (isInternalBinding(name)) return;
-	return getRawRuntimeEnv()[name];
+	const raw = getRawRuntimeEnv();
+	if (isInternalBinding(name, raw)) return;
+	return raw[name];
 }
 function requireRuntimeBinding(name) {
 	const value = getRuntimeBinding(name);
@@ -48,4 +62,4 @@ function requireRuntimeBinding(name) {
 	throw new Error(`env: Missing Cloudflare binding '${name}'.`);
 }
 //#endregion
-export { getRuntimeBinding, getRuntimeEnv, requireRuntimeBinding, withRuntimeEnv };
+export { getRuntimeBinding, getRuntimeEnv, isInternalBinding, requireRuntimeBinding, withRuntimeEnv };

package/dist/runtime/isr-cache.d.mts

@@ -0,0 +1,207 @@
+//#region src/runtime/isr-cache.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 `void-platform/packages/dispatch` (`isr.ts`, `index.ts`,
+* `pattern.ts`) and `void-platform/packages/isr-shared`.
+*/
+/**
+* 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.
+*/
+interface IsrCacheEnv {
+  ISR_CACHE?: KVNamespace;
+  __VOID_ISR_DEPLOYMENT_ID?: string;
+}
+type IsrCacheEntry = Readonly<{
+  body: ReadableStream;
+  status: number;
+  headers: Record<string, string>;
+  createdAt: number;
+  ttl: number;
+}>;
+type IsrCacheMetadata = Readonly<{
+  /** HTTP status code */s: number; /** createdAt (ms) */
+  c: number; /** TTL (seconds) */
+  t: number;
+}>;
+/** Renders a live response for a request (worker dispatch + asset serving). */
+type RenderFn = (request: Request) => Promise<Response>;
+type HandleIsrOptions = Readonly<{
+  revalidate: number | Record<string, number> | undefined;
+  deploymentId: string;
+}>;
+/**
+* Build the normalized path segment for an ISR-cached page.
+* Root path `/` maps to `__index__` to avoid trailing-slash ambiguity.
+*/
+declare function normalizeIsrPath(pathname: string): string;
+/**
+* Inverse of `normalizeIsrPath`: turn a normalized segment back into a
+* pathname starting with `/`.
+*/
+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.
+*/
+declare function canonicalIsrPathname(pathname: 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.).
+*/
+declare function isrKey(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.
+*/
+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.
+*/
+declare function htmlEdgeKey(host: string, pathname: string, id: string): string;
+/**
+* Edge-cache key for the JSON (pages-protocol) variant. Separated from HTML by
+* the `&__void=json` marker.
+*/
+declare function jsonEdgeKey(host: string, pathname: string, id: string): string;
+/**
+* Match a pattern against a pathname using LITERAL semantics — no named
+* captures. Two wildcards are special: `*` matches any characters INCLUDING `/`
+* (a splat), and a WHOLE-segment `:name` (preceded by `/` or start, followed by
+* `/` or end) matches exactly ONE path segment (`[^/]+`). A mid-segment literal
+* `:` (e.g. `/api/v1:health`) is left alone. This is a strict SUPERSET of the
+* old `*`-only matcher (old `*`-only manifests match identically). Malformed
+* patterns yield `false` rather than throwing.
+*/
+declare function matchLiteralPattern(pattern: string, pathname: string): boolean;
+/**
+* Pack response headers + body into a single ArrayBuffer.
+* Format: [4 bytes uint32 LE header length][UTF-8 header JSON][raw body]
+*/
+declare function packIsrValue(headers: Record<string, string>, body: ArrayBuffer): ArrayBuffer;
+/**
+* Unpack headers + body from a packed ArrayBuffer.
+* Returns null if the buffer is too small or malformed.
+*/
+declare function unpackIsrValue(buffer: ArrayBuffer): {
+  headers: Record<string, string>;
+  body: ArrayBuffer;
+} | null;
+/**
+* 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.
+*/
+declare function readIsrCache(env: IsrCacheEnv, host: string, pathname: string): 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).
+*/
+declare function writeIsrCache(env: IsrCacheEnv, host: string, pathname: string, response: Response, ttl: number): 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.
+*/
+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).
+*/
+declare function deleteIsrCache(env: IsrCacheEnv, host: string, pathname: string): Promise<void>;
+/** Check if a cached entry is stale. */
+declare function isStale(entry: IsrCacheEntry): boolean;
+/** Build a Response from an ISR cache entry. */
+declare function isrCacheResponse(entry: IsrCacheEntry, stale: boolean): Response;
+/**
+* Read the `x-revalidate` header from a worker response.
+* Returns the override TTL, or the default. A value of 0 means "do not cache".
+*/
+declare function resolveRevalidateTtl(response: Response, defaultTtl: number): number;
+/**
+* ISR should be bypassed for requests with credentials and EventSource
+* requests. Pages protocol navigation (X-VoidPages) uses a separate JSON edge
+* cache.
+*/
+declare function shouldBypassIsr(request: Request): boolean;
+/**
+* Resolve the ISR TTL for a given pathname.
+* Accepts the `revalidate` config (number, object, or undefined). For the
+* object form, the first matching pattern wins.
+*/
+declare function resolvePathTtl(revalidate: number | Record<string, number> | undefined, pathname: string): number;
+declare function serializeHeaders(response: Response): Record<string, string>;
+declare function normalizePageDataForJsonCache(raw: string): string | null;
+declare function extractPageDataFromHtml(html: string): string | null;
+declare function clientRevalidateResponse(response: Response): Response;
+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`.
+*/
+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.
+*/
+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, 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.
+*/
+declare function handleIsr(request: Request, env: IsrCacheEnv, ctx: ExecutionContext, options: HandleIsrOptions, render: RenderFn): Promise<Response | null>;
+//#endregion
+export { HandleIsrOptions, IsrCacheEntry, IsrCacheEnv, IsrCacheMetadata, RenderFn, canonicalIsrPathname, clientRevalidateResponse, cloneWithoutVoidPages, deleteIsrCache, denormalizeIsrPath, extractPageDataFromHtml, handleIsr, hostRegistryKey, htmlEdgeKey, isEventStreamResponse, isStale, isrCacheResponse, isrKey, jsonEdgeKey, listIsrHosts, matchLiteralPattern, normalizeIsrPath, normalizePageDataForJsonCache, packIsrValue, populateJsonEdgeCache, readIsrCache, resolvePathTtl, resolveRevalidateTtl, serializeHeaders, shouldBypassIsr, unpackIsrValue, writeIsrCache };