@qzsy/vinext 0.1.7

package/dist/server/isr-cache.d.ts

@@ -0,0 +1,127 @@
+import { RenderObservation } from "./cache-proof.js";
+import { CacheHandlerValue, CachedAppPageValue, CachedPagesValue, IncrementalCacheValue } from "../shims/cache-handler.js";
+import { OnRequestErrorContext } from "./instrumentation.js";
+import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
+import { AppRscRenderMode } from "./app-rsc-render-mode.js";
+
+//#region src/server/isr-cache.d.ts
+/**
+ * Header set on the internal request that `res.revalidate()` issues to
+ * trigger on-demand ISR regeneration of a Pages Router route. Mirrors Next.js's
+ * `PRERENDER_REVALIDATE_HEADER` (`x-prerender-revalidate`) — see
+ * `.nextjs-ref/packages/next/src/lib/constants.ts`.
+ *
+ * SECURITY: in Next.js this header is NOT a presence flag — it carries the
+ * secret `previewModeId`, and `checkIsOnDemandRevalidate`
+ * (`.nextjs-ref/packages/next/src/server/api-utils/index.ts`) only treats a
+ * request as on-demand revalidation when the value *equals* that secret. If we
+ * gated on presence alone, any external client could send
+ * `x-prerender-revalidate: <anything>` to force synchronous regeneration of any
+ * ISR page, bypassing the fresh/stale cache short-circuits — a
+ * cache-stampede/DoS vector. We therefore validate the value against
+ * {@link getRevalidateSecret} (a build-time secret shared across all Workers
+ * isolates) with a constant-time comparison, and only the matching value (sent
+ * by our own `res.revalidate()`) is honored.
+ */
+declare const PRERENDER_REVALIDATE_HEADER = "x-prerender-revalidate";
+/**
+ * Companion header to {@link PRERENDER_REVALIDATE_HEADER}. When set,
+ * `res.revalidate(path, { unstable_onlyGenerated: true })` only revalidates the
+ * path if it was already generated, and a 404 response counts as a successful
+ * no-op. Mirrors Next.js's `PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER`
+ * (`x-prerender-revalidate-if-generated`) — see
+ * `.nextjs-ref/packages/next/src/lib/constants.ts`.
+ */
+declare const PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER = "x-prerender-revalidate-if-generated";
+declare function getRevalidateSecret(): string;
+/**
+ * Authorize an incoming request as an on-demand revalidation trigger. Mirrors
+ * Next.js's `checkIsOnDemandRevalidate`: the {@link PRERENDER_REVALIDATE_HEADER}
+ * value must *equal* the process revalidate secret. Header presence alone is
+ * NOT sufficient — see the security note on {@link PRERENDER_REVALIDATE_HEADER}.
+ */
+declare function isOnDemandRevalidateRequest(headerValue: string | string[] | null | undefined): boolean;
+type ISRCacheEntry = {
+  value: CacheHandlerValue;
+  isStale: boolean;
+};
+/**
+ * Get a cache entry with staleness information.
+ *
+ * Returns { value, isStale: false } for fresh entries,
+ * { value, isStale: true } for expired-but-usable entries,
+ * or null for cache misses.
+ */
+declare function isrGet(key: string): Promise<ISRCacheEntry | null>;
+/**
+ * Store a value in the ISR cache with a revalidation period.
+ */
+declare function isrSet(key: string, data: IncrementalCacheValue, revalidateSeconds: number, tags?: string[], expireSeconds?: number): Promise<void>;
+declare function isrSetPrerenderedAppPage(key: string, data: CachedAppPageValue, metadata: {
+  expireSeconds?: number;
+  revalidateSeconds?: number;
+  /**
+   * Implicit/path tags to attach to the seeded entry. Required so that
+   * `revalidatePath()` (and `revalidateTag()`) can invalidate prerender-seeded
+   * cache entries — without tags the entry is unreachable by tag-based
+   * invalidation and remains stale until natural `revalidateAt` expiry.
+   * See cloudflare/vinext#1486.
+   */
+  tags?: string[];
+}): Promise<void>;
+/**
+ * Trigger a background regeneration for a cache key.
+ *
+ * If a regeneration for this key is already in progress, this is a no-op.
+ * The renderFn should produce the new cache value and call isrSet internally.
+ *
+ * On Cloudflare Workers the regeneration promise is registered with
+ * `ctx.waitUntil()` via the ALS-backed ExecutionContext, keeping the isolate
+ * alive until the regeneration completes even after the Response is returned.
+ *
+ * When `errorContext` is provided and the render function fails, the error
+ * is reported via `reportRequestError` (instrumentation hook) with
+ * `revalidateReason: "stale"`.
+ */
+declare function triggerBackgroundRegeneration(key: string, renderFn: () => Promise<void>, errorContext?: {
+  routerKind: OnRequestErrorContext["routerKind"];
+  routePath: string;
+  routeType: OnRequestErrorContext["routeType"];
+}): void;
+/**
+ * Build a CachedPagesValue for the Pages Router ISR cache.
+ */
+declare function buildPagesCacheValue(html: string, pageData: object, status?: number): CachedPagesValue;
+/**
+ * Build a CachedAppPageValue for the App Router ISR cache.
+ */
+declare function buildAppPageCacheValue(html: string, rscData?: ArrayBuffer, status?: number, renderObservation?: RenderObservation): CachedAppPageValue;
+/**
+ * Compute an ISR cache key for a given router type and pathname.
+ * Long pathnames are hashed to stay within KV key-length limits (512 bytes).
+ */
+declare function isrCacheKey(router: string, pathname: string, buildId?: string): string;
+declare function appIsrHtmlKey(pathname: string): string;
+/**
+ * Build the ISR cache key for an RSC payload.
+ *
+ * Variants are sequenced in order: `source:<hash>` (intercepted source context,
+ * only when an interception context is present), `slots:<hash>` (mounted parallel
+ * route slots), and optionally `<render-mode-variant>` (e.g. `preserve-ui` or
+ * `prefetch-loading-shell`). Existing cached entries under the old format will
+ * become unreachable after deployment. This is acceptable because ISR entries
+ * have TTLs and will be regenerated on the next request.
+ */
+declare function appIsrRscKey(pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null): string;
+declare function appIsrRouteKey(pathname: string): string;
+/**
+ * Store the revalidate duration for a cache key.
+ * Uses insertion-order LRU eviction to prevent unbounded growth.
+ */
+declare function setRevalidateDuration(key: string, seconds: number): void;
+/**
+ * Get the revalidate duration for a cache key.
+ */
+declare function getRevalidateDuration(key: string): number | undefined;
+//#endregion
+export { ISRCacheEntry, PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };

package/dist/server/isr-cache.js

@@ -0,0 +1,282 @@
+import { getRequestExecutionContext } from "../shims/request-context.js";
+import { reportRequestError } from "./instrumentation.js";
+import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
+import { fnv1a64 } from "../utils/hash.js";
+import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
+import { APP_RSC_RENDER_MODE_NAVIGATION, getRscRenderModeCacheVariant } from "./app-rsc-render-mode.js";
+import { normalizeAppPageInterceptionProofPathname } from "./app-page-render-identity.js";
+//#region src/server/isr-cache.ts
+/**
+* Header set on the internal request that `res.revalidate()` issues to
+* trigger on-demand ISR regeneration of a Pages Router route. Mirrors Next.js's
+* `PRERENDER_REVALIDATE_HEADER` (`x-prerender-revalidate`) — see
+* `.nextjs-ref/packages/next/src/lib/constants.ts`.
+*
+* SECURITY: in Next.js this header is NOT a presence flag — it carries the
+* secret `previewModeId`, and `checkIsOnDemandRevalidate`
+* (`.nextjs-ref/packages/next/src/server/api-utils/index.ts`) only treats a
+* request as on-demand revalidation when the value *equals* that secret. If we
+* gated on presence alone, any external client could send
+* `x-prerender-revalidate: <anything>` to force synchronous regeneration of any
+* ISR page, bypassing the fresh/stale cache short-circuits — a
+* cache-stampede/DoS vector. We therefore validate the value against
+* {@link getRevalidateSecret} (a build-time secret shared across all Workers
+* isolates) with a constant-time comparison, and only the matching value (sent
+* by our own `res.revalidate()`) is honored.
+*/
+const PRERENDER_REVALIDATE_HEADER = "x-prerender-revalidate";
+/**
+* Companion header to {@link PRERENDER_REVALIDATE_HEADER}. When set,
+* `res.revalidate(path, { unstable_onlyGenerated: true })` only revalidates the
+* path if it was already generated, and a 404 response counts as a successful
+* no-op. Mirrors Next.js's `PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER`
+* (`x-prerender-revalidate-if-generated`) — see
+* `.nextjs-ref/packages/next/src/lib/constants.ts`.
+*/
+const PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER = "x-prerender-revalidate-if-generated";
+/**
+* Build-time secret that authenticates on-demand revalidation requests, the
+* vinext analog of Next.js's prerender-manifest `previewModeId`.
+*
+* `res.revalidate()` loops back into the server via an internal `fetch()`. On
+* Cloudflare Workers that loopback can land on a *different* isolate than the
+* sender, so a per-process random secret would mismatch across isolates and
+* false-reject legitimate revalidations (and, symmetrically, two isolates with
+* independently-rolled secrets could never agree). The fix mirrors Next.js's
+* `previewModeId`: the secret is generated once at BUILD time and baked
+* (server-only — never into the client bundle) into every server bundle via the
+* `__VINEXT_REVALIDATE_SECRET` Vite `define`, so it is byte-for-byte identical in
+* every isolate. See `vinext build` CLI (`__VINEXT_SHARED_REVALIDATE_SECRET`) and
+* the `vinext:compiler-define-server` plugin. The sender attaches it as the
+* {@link PRERENDER_REVALIDATE_HEADER} value; the receiver authorizes a request
+* only when the incoming value equals this secret (see
+* {@link isOnDemandRevalidateRequest}).
+*
+* When the build-time define is absent — dev mode, and any path that doesn't
+* run through `vinext build` — we fall back to a lazily-generated random secret.
+* Those paths are single-process, so a module-scoped value is shared by sender
+* and receiver there — no regression.
+*/
+let devRevalidateSecret;
+function getRevalidateSecret() {
+	const baked = process.env.__VINEXT_REVALIDATE_SECRET;
+	if (baked) return baked;
+	if (devRevalidateSecret === void 0) {
+		const bytes = new Uint8Array(32);
+		crypto.getRandomValues(bytes);
+		devRevalidateSecret = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	}
+	return devRevalidateSecret;
+}
+/**
+* Constant-time string equality. Avoids leaking secret length / prefix via
+* early-exit timing on the on-demand revalidation auth check. Returns false
+* for length mismatch (the only safe option without revealing the secret
+* length, and equality is impossible anyway).
+*/
+function safeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let mismatch = 0;
+	for (let i = 0; i < a.length; i++) mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return mismatch === 0;
+}
+/**
+* Authorize an incoming request as an on-demand revalidation trigger. Mirrors
+* Next.js's `checkIsOnDemandRevalidate`: the {@link PRERENDER_REVALIDATE_HEADER}
+* value must *equal* the process revalidate secret. Header presence alone is
+* NOT sufficient — see the security note on {@link PRERENDER_REVALIDATE_HEADER}.
+*/
+function isOnDemandRevalidateRequest(headerValue) {
+	if (typeof headerValue !== "string" || headerValue.length === 0) return false;
+	return safeEqual(headerValue, getRevalidateSecret());
+}
+/**
+* Get a cache entry with staleness information.
+*
+* Returns { value, isStale: false } for fresh entries,
+* { value, isStale: true } for expired-but-usable entries,
+* or null for cache misses.
+*/
+async function isrGet(key) {
+	const result = await getCdnCacheAdapter().get(key);
+	if (!result || !result.value) return null;
+	if (result.cacheState === "expired") return null;
+	return {
+		value: result,
+		isStale: result.cacheState === "stale"
+	};
+}
+/**
+* Store a value in the ISR cache with a revalidation period.
+*/
+async function isrSet(key, data, revalidateSeconds, tags, expireSeconds) {
+	await getCdnCacheAdapter().set(key, data, {
+		cacheControl: expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
+			revalidate: revalidateSeconds,
+			expire: expireSeconds
+		},
+		revalidate: revalidateSeconds,
+		tags: tags ?? []
+	});
+}
+async function isrSetPrerenderedAppPage(key, data, metadata) {
+	const revalidateSeconds = metadata.revalidateSeconds;
+	const tags = metadata.tags;
+	if (process.env.NEXT_PRIVATE_DEBUG_CACHE) console.debug("[vinext] ISR: seed", key);
+	const ctx = {};
+	if (revalidateSeconds !== void 0) {
+		ctx.revalidate = revalidateSeconds;
+		ctx.cacheControl = metadata.expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
+			revalidate: revalidateSeconds,
+			expire: metadata.expireSeconds
+		};
+	}
+	if (tags && tags.length > 0) ctx.tags = tags;
+	await getCdnCacheAdapter().set(key, data, ctx);
+	if (revalidateSeconds !== void 0) setRevalidateDuration(key, revalidateSeconds);
+}
+const _PENDING_REGEN_KEY = Symbol.for("vinext.isrCache.pendingRegenerations");
+const _g = globalThis;
+const pendingRegenerations = _g[_PENDING_REGEN_KEY] ??= /* @__PURE__ */ new Map();
+/**
+* Trigger a background regeneration for a cache key.
+*
+* If a regeneration for this key is already in progress, this is a no-op.
+* The renderFn should produce the new cache value and call isrSet internally.
+*
+* On Cloudflare Workers the regeneration promise is registered with
+* `ctx.waitUntil()` via the ALS-backed ExecutionContext, keeping the isolate
+* alive until the regeneration completes even after the Response is returned.
+*
+* When `errorContext` is provided and the render function fails, the error
+* is reported via `reportRequestError` (instrumentation hook) with
+* `revalidateReason: "stale"`.
+*/
+function triggerBackgroundRegeneration(key, renderFn, errorContext) {
+	if (!getCdnCacheAdapter().ownsBackgroundRevalidation) return;
+	if (pendingRegenerations.has(key)) return;
+	const promise = renderFn().catch((err) => {
+		console.error(`[vinext] ISR background regeneration failed for ${key}:`, err);
+		if (errorContext) reportRequestError(err instanceof Error ? err : new Error(String(err)), {
+			path: key,
+			method: "GET",
+			headers: {}
+		}, {
+			routerKind: errorContext.routerKind,
+			routePath: errorContext.routePath,
+			routeType: errorContext.routeType,
+			revalidateReason: "stale"
+		});
+	}).finally(() => {
+		pendingRegenerations.delete(key);
+	});
+	pendingRegenerations.set(key, promise);
+	getRequestExecutionContext()?.waitUntil(promise);
+}
+/**
+* Build a CachedPagesValue for the Pages Router ISR cache.
+*/
+function buildPagesCacheValue(html, pageData, status) {
+	return {
+		kind: "PAGES",
+		html,
+		pageData,
+		headers: void 0,
+		status
+	};
+}
+/**
+* Build a CachedAppPageValue for the App Router ISR cache.
+*/
+function buildAppPageCacheValue(html, rscData, status, renderObservation) {
+	const value = {
+		kind: "APP_PAGE",
+		html,
+		rscData,
+		headers: void 0,
+		postponed: void 0,
+		status
+	};
+	if (renderObservation) value.renderObservation = renderObservation;
+	return value;
+}
+function normalizeCachePathname(pathname) {
+	return pathname === "/" ? "/" : pathname.replace(/\/$/, "");
+}
+function buildCacheKey(prefix, pathname, suffix) {
+	const normalized = normalizeCachePathname(pathname);
+	const suffixPart = suffix ? `:${suffix}` : "";
+	const key = `${prefix}:${normalized}${suffixPart}`;
+	if (key.length <= 200) return key;
+	return `${prefix}:__hash:${fnv1a64(normalized)}${suffixPart}`;
+}
+/**
+* Compute an ISR cache key for a given router type and pathname.
+* Long pathnames are hashed to stay within KV key-length limits (512 bytes).
+*/
+function isrCacheKey(router, pathname, buildId) {
+	return buildCacheKey(buildId ? `${router}:${buildId}` : router, pathname);
+}
+/**
+* Compute an App Router ISR key for one cache artifact.
+*
+* App pages store HTML, RSC payloads, and route-handler responses separately.
+* The suffix mirrors Next.js's separate on-disk app artifacts while keeping the
+* Cloudflare KV key under its 512-byte limit for long pathnames.
+*/
+function appIsrCacheKey(pathname, suffix, buildId = process.env.__VINEXT_BUILD_ID) {
+	return buildCacheKey(buildId ? `app:${buildId}` : "app", pathname, suffix);
+}
+function appIsrHtmlKey(pathname) {
+	return appIsrCacheKey(pathname, "html");
+}
+function normalizeInterceptionContextForCacheKey(interceptionContext) {
+	return normalizeAppPageInterceptionProofPathname(interceptionContext);
+}
+/**
+* Build the ISR cache key for an RSC payload.
+*
+* Variants are sequenced in order: `source:<hash>` (intercepted source context,
+* only when an interception context is present), `slots:<hash>` (mounted parallel
+* route slots), and optionally `<render-mode-variant>` (e.g. `preserve-ui` or
+* `prefetch-loading-shell`). Existing cached entries under the old format will
+* become unreachable after deployment. This is acceptable because ISR entries
+* have TTLs and will be regenerated on the next request.
+*/
+function appIsrRscKey(pathname, mountedSlotsHeader, renderMode = APP_RSC_RENDER_MODE_NAVIGATION, interceptionContext) {
+	const normalizedMountedSlotsHeader = normalizeMountedSlotsHeader(mountedSlotsHeader);
+	const sourceVariant = interceptionContext === void 0 || interceptionContext === null ? null : normalizeInterceptionContextForCacheKey(interceptionContext);
+	const variant = [
+		sourceVariant ? `source:${fnv1a64(sourceVariant)}` : null,
+		normalizedMountedSlotsHeader ? `slots:${fnv1a64(normalizedMountedSlotsHeader)}` : null,
+		getRscRenderModeCacheVariant(renderMode)
+	].filter((part) => part !== null).join(":");
+	return appIsrCacheKey(pathname, variant ? `rsc:${variant}` : "rsc");
+}
+function appIsrRouteKey(pathname) {
+	return appIsrCacheKey(pathname, "route");
+}
+const MAX_REVALIDATE_ENTRIES = 1e4;
+const _REVALIDATE_KEY = Symbol.for("vinext.isrCache.revalidateDurations");
+const revalidateDurations = _g[_REVALIDATE_KEY] ??= /* @__PURE__ */ new Map();
+/**
+* Store the revalidate duration for a cache key.
+* Uses insertion-order LRU eviction to prevent unbounded growth.
+*/
+function setRevalidateDuration(key, seconds) {
+	revalidateDurations.delete(key);
+	revalidateDurations.set(key, seconds);
+	while (revalidateDurations.size > MAX_REVALIDATE_ENTRIES) {
+		const first = revalidateDurations.keys().next().value;
+		if (first !== void 0) revalidateDurations.delete(first);
+		else break;
+	}
+}
+/**
+* Get the revalidate duration for a cache key.
+*/
+function getRevalidateDuration(key) {
+	return revalidateDurations.get(key);
+}
+//#endregion
+export { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };

package/dist/server/isr-decision.d.ts

@@ -0,0 +1,79 @@
+import { CacheControlMetadata } from "../shims/cache-handler.js";
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL } from "./cache-control.js";
+
+//#region src/server/isr-decision.d.ts
+type IsrDisposition = "HIT" | "STALE" | "MISS";
+type IsrDecision = {
+  disposition: IsrDisposition; /** True when the caller must schedule a background regeneration. */
+  scheduleRegeneration: boolean; /** The `Cache-Control` string to stamp on the response. */
+  cacheControl: string;
+};
+/**
+ * Per-router special-case policies for `Cache-Control`.
+ *
+ * - `"app-page"` / `"pages"`: `buildCachedRevalidateCacheControl` for HIT/STALE.
+ * - `"app-route"`: same, but `revalidateSeconds=0` forces `NEVER_CACHE_CONTROL`
+ *   and `revalidateSeconds=Infinity` forces `STATIC_CACHE_CONTROL`.
+ * - `"dev"`: like `"pages"`, but `revalidate=0`/`Infinity` guards are absent
+ *   (dev never caches when revalidate=0 and never has Infinity entries in practice).
+ */
+type IsrPolicyKind = "app-page" | "app-route" | "pages" | "dev";
+type DecideIsrOptions = {
+  /**
+   * The cache state. Content guards (kind-mismatch, empty body,
+   * query-variant-unproven) must have already passed before passing
+   * `"HIT"` or `"STALE"` here.
+   */
+  cacheState: "HIT" | "STALE" | "MISS"; /** Which router is making the decision. */
+  kind: IsrPolicyKind;
+  /**
+   * The route's configured revalidate window in seconds. Used as the fallback
+   * when `cacheControlMeta` is absent.
+   *
+   * For `"dev"` call sites this is the only source of the revalidate value —
+   * dev never has metadata attached to a cache entry.
+   */
+  revalidateSeconds: number;
+  /**
+   * The expire ceiling (seconds from epoch) read from the route config.
+   * Absent when the route pre-dates expire metadata support.
+   */
+  expireSeconds?: number;
+  /**
+   * Optional per-entry metadata written alongside the cache value.
+   * When present its `revalidate`/`expire` fields override the route defaults,
+   * exactly as the call sites do today with `cacheControl?.revalidate ?? revalidateSeconds`.
+   */
+  cacheControlMeta?: CacheControlMetadata;
+};
+/**
+ * Derive the `Cache-Control` string for an ISR response.
+ *
+ * Content guards (kind mismatch, query-variant-unproven, empty body) are the
+ * caller's responsibility and must happen *before* this call. `cacheState`
+ * must only be `"HIT"` or `"STALE"` when those guards have already passed.
+ */
+declare function decideIsr(options: DecideIsrOptions): IsrDecision;
+/**
+ * Build the `Cache-Control` string for a fresh MISS response whose ISR policy
+ * is known (i.e. revalidate is set and > 0). Uses the unbounded SWR form when
+ * no expire ceiling is available, exactly as `buildRevalidateCacheControl` does.
+ *
+ * Separate from `decideIsr` because a MISS doesn't read a cache entry and
+ * therefore never has `cacheControlMeta`. `expireSeconds` here is the route
+ * config ceiling passed directly from the caller (not a per-entry fallback).
+ */
+declare function buildMissIsrCacheControl(revalidateSeconds: number, expireSeconds?: number): string;
+/**
+ * Build the `Cache-Control` string for a fresh (MISS) app-route response.
+ *
+ * Applies the same `revalidateSeconds=0`→NEVER and `Infinity`→STATIC gates
+ * that `decideIsr` uses for app-route cached responses. `expireSeconds` is
+ * the route config ceiling passed directly (not per-entry metadata fallback).
+ *
+ * Used by `applyRouteHandlerRevalidateHeader` which operates on a fresh
+ * response that has no per-entry cache metadata.
+ */
+declare function buildAppRouteMissIsrCacheControl(revalidateSeconds: number, expireSeconds?: number): string;
+//#endregion
+export { NEVER_CACHE_CONTROL as ISR_NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL as ISR_NO_STORE_CACHE_CONTROL, buildAppRouteMissIsrCacheControl, buildMissIsrCacheControl, decideIsr };

package/dist/server/isr-decision.js

@@ -0,0 +1,70 @@
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, buildCachedRevalidateCacheControl, buildRevalidateCacheControl } from "./cache-control.js";
+//#region src/server/isr-decision.ts
+/** Resolve effective revalidate/expire, preferring per-entry metadata. */
+function resolveRevalidate(options) {
+	return {
+		effectiveRevalidate: options.cacheControlMeta?.revalidate ?? options.revalidateSeconds,
+		effectiveExpire: options.cacheControlMeta === void 0 ? void 0 : options.cacheControlMeta.expire ?? options.expireSeconds
+	};
+}
+function buildCacheControl(disposition, kind, revalidate, expire) {
+	if (kind === "app-route") {
+		if (revalidate === 0) return NEVER_CACHE_CONTROL;
+		if (revalidate === Infinity) return STATIC_CACHE_CONTROL;
+	}
+	return buildCachedRevalidateCacheControl(disposition, revalidate, expire);
+}
+/**
+* Derive the `Cache-Control` string for an ISR response.
+*
+* Content guards (kind mismatch, query-variant-unproven, empty body) are the
+* caller's responsibility and must happen *before* this call. `cacheState`
+* must only be `"HIT"` or `"STALE"` when those guards have already passed.
+*/
+function decideIsr(options) {
+	if (options.cacheState === "MISS") return {
+		disposition: "MISS",
+		scheduleRegeneration: false,
+		cacheControl: ""
+	};
+	const { effectiveRevalidate, effectiveExpire } = resolveRevalidate(options);
+	if (options.cacheState === "HIT") return {
+		disposition: "HIT",
+		scheduleRegeneration: false,
+		cacheControl: buildCacheControl("HIT", options.kind, effectiveRevalidate, effectiveExpire)
+	};
+	return {
+		disposition: "STALE",
+		scheduleRegeneration: true,
+		cacheControl: buildCacheControl("STALE", options.kind, effectiveRevalidate, effectiveExpire)
+	};
+}
+/**
+* Build the `Cache-Control` string for a fresh MISS response whose ISR policy
+* is known (i.e. revalidate is set and > 0). Uses the unbounded SWR form when
+* no expire ceiling is available, exactly as `buildRevalidateCacheControl` does.
+*
+* Separate from `decideIsr` because a MISS doesn't read a cache entry and
+* therefore never has `cacheControlMeta`. `expireSeconds` here is the route
+* config ceiling passed directly from the caller (not a per-entry fallback).
+*/
+function buildMissIsrCacheControl(revalidateSeconds, expireSeconds) {
+	return buildRevalidateCacheControl(revalidateSeconds, expireSeconds);
+}
+/**
+* Build the `Cache-Control` string for a fresh (MISS) app-route response.
+*
+* Applies the same `revalidateSeconds=0`→NEVER and `Infinity`→STATIC gates
+* that `decideIsr` uses for app-route cached responses. `expireSeconds` is
+* the route config ceiling passed directly (not per-entry metadata fallback).
+*
+* Used by `applyRouteHandlerRevalidateHeader` which operates on a fresh
+* response that has no per-entry cache metadata.
+*/
+function buildAppRouteMissIsrCacheControl(revalidateSeconds, expireSeconds) {
+	if (revalidateSeconds === 0) return NEVER_CACHE_CONTROL;
+	if (revalidateSeconds === Infinity) return STATIC_CACHE_CONTROL;
+	return buildRevalidateCacheControl(revalidateSeconds, expireSeconds);
+}
+//#endregion
+export { NEVER_CACHE_CONTROL as ISR_NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL as ISR_NO_STORE_CACHE_CONTROL, buildAppRouteMissIsrCacheControl, buildMissIsrCacheControl, decideIsr };

package/dist/server/metadata-route-build-data.d.ts

@@ -0,0 +1,24 @@
+import { MetadataFileRoute, MetadataRouteHeadData } from "./metadata-routes.js";
+
+//#region src/server/metadata-route-build-data.d.ts
+type MetadataRouteEntrySourceInput = {
+  entryData: MetadataRouteEntryData;
+  moduleName?: string;
+  patternParts?: readonly string[] | null;
+};
+type MetadataRouteEntryData = {
+  type: MetadataFileRoute["type"];
+  isDynamic: boolean;
+  routePrefix: string;
+  routeSegments: readonly string[];
+  servedUrl: string;
+  contentType: string;
+  contentHash: string;
+  headData?: MetadataRouteHeadData | null;
+  fileDataBase64?: string;
+};
+declare function createMetadataRouteEntryData(route: MetadataFileRoute): MetadataRouteEntryData;
+declare function createMetadataRouteEntrySource(input: MetadataRouteEntrySourceInput): string;
+declare function createMetadataRouteEntriesSource(routes: readonly MetadataFileRoute[], moduleNames: ReadonlyMap<string, string>): string[];
+//#endregion
+export { createMetadataRouteEntriesSource, createMetadataRouteEntryData, createMetadataRouteEntrySource };