void 0.10.12 → 0.20.0

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

@@ -1,207 +0,0 @@
-//#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 };