@webjsdev/server 0.8.10 → 0.8.11

package/src/dev.js

@@ -1,7 +1,6 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { digestHex } from './crypto-utils.js';
 import { createGzip, createBrotliCompress, constants as zlibConstants } from 'node:zlib';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
@@ -68,7 +67,8 @@ import {
 import { defaultLogger } from './logger.js';
 import { assertNodeVersion } from './node-version.js';
 import { applyEnvValidation } from './env-schema.js';
-import { withRequest, setCspNonce, setBodyLimits } from './context.js';
+import { withRequest, setCspNonce, setBodyLimits, setRequestId, requestId as getRequestId } from './context.js';
+import { buildInfoResponse } from './build-info.js';
 import { readCspConfig, mintNonce, buildCspHeader, cspHeaderName } from './csp.js';
 import { attachWebSocket } from './websocket.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
@@ -80,10 +80,44 @@ import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
+
+/**
+ * Per-request correlation id (issue #239). Honor an inbound `X-Request-Id`
+ * from a trusted upstream proxy so a trace id propagates across services; mint
+ * a fresh `crypto.randomUUID()` otherwise. The inbound value is length-capped
+ * and validated against a conservative token charset so a hostile client
+ * cannot inject control chars / a header-splitting payload (the value is
+ * echoed back in the `X-Request-Id` response header). On any mismatch we fall
+ * back to a minted id rather than trust the junk.
+ *
+ * @param {Request} req
+ * @returns {string}
+ */
+function resolveRequestId(req) {
+  const inbound = req.headers.get('x-request-id');
+  if (inbound && inbound.length <= 200 && /^[A-Za-z0-9._-]+$/.test(inbound)) return inbound;
+  return crypto.randomUUID();
+}
+
+/**
+ * Whether a path should be access-logged (issue #239). The framework's own
+ * `/__webjs/*` probes, static runtime assets, and the dev SSE reload stream
+ * are high-frequency infrastructure traffic, not app requests, so logging them
+ * would just spam the access log. App routes (including app-authored
+ * `/api/*`) are logged.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function shouldAccessLog(pathname) {
+  return !pathname.startsWith('/__webjs/');
+}
 import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import { readBodyLimits, computeServerTimeouts } from './body-limit.js';
+import { applyConditionalGet, BUFFERED_MARKER } from './conditional-get.js';
+import { commitHtmlCache } from './html-cache.js';
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -294,6 +328,7 @@ export async function readServerTimeoutsFromApp(appDir) {
  *   appDir: string,
  *   dev?: boolean,
  *   logger?: import('./logger.js').Logger,
+ *   onError?: (error: unknown, ctx: { request: Request, requestId: string|null, phase: string }) => void,
  *   onReload?: () => void,
  * }} opts
  */
@@ -321,6 +356,30 @@ export async function createRequestHandler(opts) {
   await applyEnvValidation(appDir, { dev: !!opts.dev });
   const dev = !!opts.dev;
   const logger = opts.logger || defaultLogger({ dev });
+  // APM / Sentry integration point (issue #239). Called whenever the request
+  // pipeline catches an unhandled error: the top-level handle() catch (the
+  // last-resort 500), an unexpected throw inside the produce() funnel, or a
+  // middleware that threw. BEST-EFFORT by contract: a throwing onError is
+  // caught here so it can never crash the response, and the framework's own
+  // sanitized 500 / existing error behavior is unchanged (the hook is purely
+  // additive). The sink receives the error plus the correlation id so it can
+  // tie the report to the same id the access log and X-Request-Id carry.
+  const onError = typeof opts.onError === 'function' ? opts.onError : null;
+  /**
+   * Invoke the app's onError sink defensively. The phase is a coarse label of
+   * where the pipeline caught the error, for the sink's own grouping.
+   * @param {unknown} error
+   * @param {Request} request
+   * @param {string} phase
+   */
+  function reportError(error, request, phase) {
+    if (!onError) return;
+    try {
+      onError(error, { request, requestId: getRequestId(), phase });
+    } catch (e) {
+      logger.error?.('[webjs] onError hook threw (ignored)', { err: String(e) });
+    }
+  }
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -679,6 +738,14 @@ export async function createRequestHandler(opts) {
   /** @param {Request} req */
   function handle(req) {
     return withRequest(req, async () => {
+      // Correlation id (issue #239): honor an inbound X-Request-Id from a
+      // trusted upstream proxy, else mint a fresh UUID. Stored on the request
+      // scope FIRST so everything downstream (the SSR, server actions, the
+      // access / error log, the onError sink, the response header) reads the
+      // same id, threading one trace id across services.
+      const reqId = resolveRequestId(req);
+      setRequestId(reqId);
+
       // CSP (issue #233): when enabled, mint a fresh CSPRNG nonce and store
       // it on the request scope BEFORE producing the response, so the SSR
       // pipeline's `cspNonce()` reads this exact value and stamps it on the
@@ -693,20 +760,45 @@ export async function createRequestHandler(opts) {
       // cap the framework's own RPC / page-action body reads do.
       setBodyLimits(state.bodyLimits);
 
-      const res = await produce(req);
+      let pathname = '/';
+      try { pathname = new URL(req.url).pathname; } catch { /* keep default */ }
+      const startedAt = performance.now();
+
+      let res;
+      try {
+        res = await produce(req);
+      } catch (e) {
+        // A throw escaping produce() is the last-resort 500 (every interior
+        // path catches its own errors, but a surprise still must not crash the
+        // host). Fire the onError sink (best-effort) and emit a sanitized 500,
+        // preserving the prior behavior plus the new APM hook.
+        reportError(e, req, 'handle');
+        logger.error?.('[webjs] request pipeline threw', {
+          requestId: reqId,
+          method: req.method,
+          path: pathname,
+          err: e instanceof Error ? e.stack : String(e),
+        });
+        res = new Response('Server error', { status: 500 });
+      }
+
       // Merge in the secure-by-default headers plus the per-path config
       // (issue #232) as the final step, so app middleware, route
       // handlers, and `expose` headers (already on `res`) always win.
       // Applied to every served response (documents, assets, the core
       // runtime, probes), since the defaults are universally safe.
-      let pathname = '/';
-      try { pathname = new URL(req.url).pathname; } catch { /* keep default */ }
-      const merged = applySecurityHeaders(res, {
+      let merged = applySecurityHeaders(res, {
         pathname,
         https: webRequestIsHttps(req),
         prod: !dev,
         rules: headerRules,
       });
+
+      // Expose the correlation id on the response (issue #239) so a client /
+      // proxy can read it from the X-Request-Id header. Never clobber an id an
+      // upstream / the app already set on the response.
+      if (!merged.headers.has('x-request-id')) merged.headers.set('x-request-id', reqId);
+
       // Emit the Content-Security-Policy header carrying the SAME minted
       // nonce the SSR'd scripts got (no drift). Set only when CSP is
       // enabled; never clobber a CSP header the app already set (in
@@ -725,7 +817,49 @@ export async function createRequestHandler(opts) {
           /* a malformed policy must not take the request down: serve without CSP */
         }
       }
-      return merged;
+
+      // Server HTML cache write (#241): if the SSR marked this response as a
+      // cache candidate (an opted-in `revalidate` page), store the FINAL body
+      // now, after segment middleware has added any per-user Set-Cookie (which
+      // the funnel's guard re-checks, so a per-user response is not cached) and
+      // before conditional-GET can swap it for a bodiless 304. The marker is
+      // stripped here regardless. Best-effort: a store failure is swallowed.
+      try {
+        const reqUrl = new URL(req.url);
+        merged = await commitHtmlCache(req, merged, reqUrl);
+      } catch { /* never let the cache write crash the response */ }
+
+      // Conditional GET (RFC 7232, issue #240): attach a content-hash ETag to
+      // a cacheable response missing one, and turn a matching If-None-Match
+      // into a 304 Not Modified with no body. Applied LAST, after every header
+      // (X-Webjs-Build, X-Request-Id, Set-Cookie, CSP) is on the response, so a
+      // 304 carries the validators a shared cache and the client router need.
+      // A no-store / per-user response, a non-GET/HEAD, and a streaming Suspense
+      // body are all skipped (see conditional-get.js). Logged with the final
+      // (possibly 304) status. Best-effort: a failure leaves the 200 untouched.
+      let conditioned = merged;
+      try {
+        conditioned = await applyConditionalGet(req, merged);
+      } catch { /* never let validator computation crash the response */ }
+
+      // Structured access log (issue #239): ONE info line per handled request
+      // at the single response funnel, carrying only method / path / status /
+      // duration / requestId (no bodies, no secrets). Suppressed for the
+      // framework's own /__webjs/* probe + static traffic so it does not spam.
+      // Best-effort: a logger that throws must not take the response down.
+      if (shouldAccessLog(pathname)) {
+        try {
+          logger.info?.('request', {
+            requestId: reqId,
+            method: req.method,
+            path: pathname,
+            status: conditioned.status,
+            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+          });
+        } catch { /* never let logging crash the response */ }
+      }
+
+      return conditioned;
     });
   }
 
@@ -751,6 +885,13 @@ export async function createRequestHandler(opts) {
       if (probePath === '/__webjs/health') {
         return Response.json({ status: 'ok' }, { headers: { 'cache-control': 'no-store' } });
       }
+      // Build-info probe (issue #239): which build is live? Answered before
+      // ensureReady like the other probes (it depends only on the package
+      // version + already-published build id + process info, never the app
+      // analysis). No secrets.
+      if (probePath === '/__webjs/version') {
+        return buildInfoResponse();
+      }
       if (probePath === '/__webjs/ready') {
         const noStore = { 'cache-control': 'no-store' };
         if (!readyDone) {
@@ -790,12 +931,13 @@ export async function createRequestHandler(opts) {
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
       await ensureReady();
-      const next = () => handleCore(req, { state, appDir, coreDir, dev });
+      const next = () => handleCore(req, { state, appDir, coreDir, dev, reportError, cspEnabled: cspConfig.enabled });
       if (state.middleware) {
         try {
           return await state.middleware(req, next);
         } catch (e) {
-          logger.error('middleware threw', { err: String(e) });
+          reportError(e, req, 'middleware');
+          logger.error('middleware threw', { err: String(e), requestId: getRequestId() });
           return new Response('Server error', { status: 500 });
         }
       }
@@ -861,6 +1003,7 @@ export async function createRequestHandler(opts) {
  *   dev?: boolean,
  *   compress?: boolean,
  *   logger?: import('./logger.js').Logger,
+ *   onError?: (error: unknown, ctx: { request: Request, requestId: string|null, phase: string }) => void,
  * }} opts
  */
 export async function startServer(opts) {
@@ -1111,7 +1254,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
 }
 
 async function handleCore(req, ctx) {
-  const { state, appDir, coreDir, dev } = ctx;
+  const { state, appDir, coreDir, dev, reportError, cspEnabled } = ctx;
   const url = new URL(req.url);
   // Decode percent-encoded characters so filesystem lookups match real
   // filenames. Dynamic route segments like `[slug]` and route groups like
@@ -1136,7 +1279,10 @@ async function handleCore(req, ctx) {
   const actMatch = /^\/__webjs\/action\/([a-f0-9]+)\/([A-Za-z0-9_$]+)$/.exec(path);
   if (actMatch) {
     if (method !== 'POST') return new Response('POST only', { status: 405 });
-    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req);
+    // Pass the onError sink (issue #239): a server action that throws
+    // unexpectedly is reported to the APM hook before the sanitized 500.
+    const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;
+    return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError);
   }
 
   // expose()d server actions (first-class REST), with optional CORS support.
@@ -1157,7 +1303,12 @@ async function handleCore(req, ctx) {
   } else {
     const exposed = matchExposedAction(state.actionIndex, method, path);
     if (exposed) {
-      const resp = await invokeExposedAction(state.actionIndex, exposed.route, exposed.params, req);
+      // Pass the onError sink (issue #239): an exposed REST handler that throws
+      // unexpectedly is reported to the APM hook before the sanitized 500, the
+      // same as the RPC action path (phase 'action' covers both server-action
+      // invocation shapes).
+      const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;
+      const resp = await invokeExposedAction(state.actionIndex, exposed.route, exposed.params, req, onActionError);
       return withCors(resp, exposed.route, req);
     }
   }
@@ -1281,6 +1432,7 @@ async function handleCore(req, ctx) {
           });
         }
       } catch (e) {
+        if (reportError) reportError(e, req, 'metadata');
         if (dev) console.error(`[webjs] metadata route error (${meta.stem}):`, e);
         return new Response('Internal error', { status: 500 });
       }
@@ -1309,6 +1461,14 @@ async function handleCore(req, ctx) {
         elidableComponents: state.elidableComponents,
         inertRouteModules: state.inertRouteModules,
         notFoundFile: state.routeTable.notFound,
+        // Server HTML cache (#241): a CSP-enabled page emits a fresh
+        // per-request nonce into its body, so its bytes vary per request and
+        // it must never be HTML-cached. Pass the flag so the cache guard skips
+        // it. CSP is off by default, so the common case stays cacheable.
+        cspEnabled,
+        // onError sink (issue #239): a page render error that becomes a 500 is
+        // reported to the APM hook with the active request's correlation id.
+        onError: reportError ? (e) => reportError(e, req, 'ssr') : undefined,
       };
       if (method === 'GET' || method === 'HEAD') {
         const handler = () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
@@ -1577,16 +1737,15 @@ async function fileResponse(abs, opts) {
   try {
     const data = await readFile(abs);
     const type = MIME[extname(abs).toLowerCase()] || 'application/octet-stream';
-    const headers = { 'content-type': type };
-    if (opts.dev) {
-      headers['cache-control'] = 'no-cache';
-    } else {
-      const etag = `"${(await digestHex('SHA-1', data)).slice(0, 16)}"`;
-      headers['etag'] = etag;
-      headers['cache-control'] = opts.immutable
+    // The body is fully buffered (read into `data`), so opt it into the
+    // conditional-GET funnel, which is the single place that hashes the bytes
+    // into a weak ETag and honors If-None-Match -> 304 (dev + prod alike).
+    const headers = { 'content-type': type, [BUFFERED_MARKER]: '1' };
+    headers['cache-control'] = opts.dev
+      ? 'no-cache'
+      : opts.immutable
         ? 'public, max-age=31536000, immutable'
         : 'public, max-age=3600';
-    }
     return new Response(data, { status: 200, headers });
   } catch {
     return new Response('Not found', { status: 404 });
@@ -1611,13 +1770,13 @@ async function jsModuleResponse(abs, dev, elideOpts) {
   const code = elideImportsFromSource(
     source, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
   );
-  const headers = { 'content-type': 'application/javascript; charset=utf-8' };
-  if (dev) {
-    headers['cache-control'] = 'no-cache';
-  } else {
-    headers['etag'] = `"${(await digestHex('SHA-1', code)).slice(0, 16)}"`;
-    headers['cache-control'] = 'public, max-age=3600';
-  }
+  // Buffered (string) body, so opt into the conditional-GET funnel for the
+  // weak ETag + 304 (see fileResponse).
+  const headers = {
+    'content-type': 'application/javascript; charset=utf-8',
+    'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+    [BUFFERED_MARKER]: '1',
+  };
   return new Response(code, { status: 200, headers });
 }
 
@@ -1670,6 +1829,7 @@ async function tsResponse(abs, dev, elideOpts, cache) {
       headers: {
         'content-type': 'application/javascript; charset=utf-8',
         'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+        [BUFFERED_MARKER]: '1',
       },
     });
   }
@@ -1726,6 +1886,7 @@ async function tsResponse(abs, dev, elideOpts, cache) {
     headers: {
       'content-type': 'application/javascript; charset=utf-8',
       'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+      [BUFFERED_MARKER]: '1',
     },
   });
 }

package/src/html-cache.js

@@ -0,0 +1,305 @@
+/**
+ * Server HTML response cache with TTL and on-demand revalidation: the
+ * no-build equivalent of Next.js's Full Route Cache + ISR.
+ *
+ * A fully-static / inert route re-runs the entire SSR pipeline (layout
+ * chain, renderToString, metadata merge, importmap splice) on every
+ * request even though it proves identical HTML each time. This module
+ * caches the rendered HTML in the existing pluggable store
+ * (`getStore()` / `memoryStore` in dev, `redisStore` when configured)
+ * under a namespaced key, and serves it WITHOUT re-running the page
+ * function on a hit within the revalidation window.
+ *
+ * SAFETY: caching is OPT-IN and conservative. A wrongly-cached per-user
+ * page served to the wrong visitor is a data leak, so the page author
+ * MUST opt in by declaring a revalidation window, and the framework
+ * applies several defense-in-depth guards before it stores anything.
+ *
+ * The opt-in trigger is `export const revalidate = N` (seconds) on the
+ * page module (the Next idiom, read once cheaply before the cache lookup).
+ * The contract: declaring `revalidate` is the author asserting "this page
+ * is the same for everyone for N seconds". A page that reads `cookies()` /
+ * a session (per-user output) MUST NOT set `revalidate`.
+ *
+ * @module html-cache
+ */
+
+import { getStore } from './cache.js';
+import { STREAM_MARKER } from './conditional-get.js';
+import { publishedBuildId } from './importmap.js';
+import { dynamicAccessed } from './context.js';
+
+/** Namespace prefix for every cached-HTML key, so a flush can target it. */
+const KEY_PREFIX = 'webjs:html:';
+
+/**
+ * Internal response header `ssrPage` stamps on a render that opted into the
+ * HTML cache (its value is the revalidate TTL in seconds). The response
+ * funnel reads it, re-checks the guards against the FINAL response (after
+ * segment middleware, which may have appended a per-user Set-Cookie the SSR
+ * side could not see), writes the cache, and strips the marker so it never
+ * reaches the client. Mirrors the BUFFERED / STREAM marker pattern.
+ */
+export const HTML_CACHE_MARKER = 'x-webjs-html-cache';
+
+/**
+ * Generation counter folded into every key namespace. `revalidateAll()`
+ * bumps it so every previously-cached HTML entry becomes unreachable in one
+ * step (the CacheStore interface has no key-scan primitive, so a global
+ * clear cannot enumerate keys), and the store TTL eventually reclaims the
+ * orphaned entries. A single process clears its own memory store this way
+ * synchronously; a Redis-backed multi-process deploy bumps per process and
+ * leans on the TTL for the rest (a best-effort global flush).
+ */
+let _generation = 0;
+
+/**
+ * Read the revalidation window (seconds) a page module opted into via
+ * `export const revalidate = N` (the Next idiom). Returns a positive finite
+ * number of seconds, or `null` when the page did not opt in (the default:
+ * no server HTML caching, current behavior).
+ *
+ * `revalidate = 0`, a negative, NaN, Infinity, or a non-number is treated
+ * as "no caching" (opt-out), matching the Next semantics where 0 means
+ * always-dynamic. The trigger is the page-module export ONLY (read once,
+ * cheaply, before the cache lookup), so a per-user page that never declares
+ * it is never cached.
+ *
+ * @param {Record<string, any> | null | undefined} pageModule
+ * @returns {number | null}
+ */
+export function readRevalidate(pageModule) {
+  const raw = pageModule ? pageModule.revalidate : undefined;
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) return null;
+  return raw;
+}
+
+/**
+ * The cache key for a request: the FULL URL (path + search string), since
+ * `searchParams` change page output. Normalized to path + sorted query so
+ * `?a=1&b=2` and `?b=2&a=1` share an entry. Two more discriminators are
+ * folded into the namespace:
+ *
+ *  - the in-process generation, so `revalidateAll()` (a generation bump)
+ *    makes every prior key unreachable in one step;
+ *  - the published build id (the importmap fingerprint), so a NEW DEPLOY
+ *    naturally writes and reads under fresh keys. The cached HTML bakes the
+ *    deploy's `data-webjs-build` importmap into its boot script, so a Redis
+ *    store that survives a deploy must NOT let a v2 process serve a v1-body
+ *    (resolving modules against stale vendor URLs). Folding the build id in
+ *    means a deploy effectively invalidates all cached HTML for free.
+ *
+ * @param {URL} url
+ * @returns {string}
+ */
+export function htmlCacheKey(url) {
+  const params = [...url.searchParams.entries()].sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0
+  );
+  const search = params.length
+    ? '?' + params.map(([k, v]) => `${k}=${v}`).join('&')
+    : '';
+  const build = publishedBuildId() || 'nobuild';
+  return `${KEY_PREFIX}${build}:${_generation}:${url.pathname}${search}`;
+}
+
+/**
+ * Read a cached HTML entry for a URL. Returns the parsed record (body +
+ * the headers needed to faithfully rebuild the response) or null on a
+ * miss / expiry / parse error (fail open to a fresh render).
+ *
+ * @param {URL} url
+ * @returns {Promise<{ body: string, contentType: string, cacheControl: string, status: number } | null>}
+ */
+export async function readHtmlCache(url) {
+  try {
+    const raw = await getStore().get(htmlCacheKey(url));
+    if (!raw) return null;
+    const rec = JSON.parse(raw);
+    if (!rec || typeof rec.body !== 'string') return null;
+    return rec;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a rendered HTML response for a URL with TTL = revalidate seconds.
+ * Best-effort: a store error never affects the live response.
+ *
+ * @param {URL} url
+ * @param {{ body: string, contentType: string, cacheControl: string, status: number }} rec
+ * @param {number} revalidateSeconds
+ */
+export async function writeHtmlCache(url, rec, revalidateSeconds) {
+  try {
+    await getStore().set(htmlCacheKey(url), JSON.stringify(rec), revalidateSeconds * 1000);
+  } catch {
+    /* a store write failure must never crash the response */
+  }
+}
+
+/**
+ * Decide whether a freshly-rendered Response is SAFE to cache. This is the
+ * defense-in-depth gate that runs AFTER the page opted in via `revalidate`.
+ * Returns true only when every guard passes:
+ *
+ *  - status 200 (an error / redirect / 404 is request-specific)
+ *  - NOT a streamed Suspense body (it cannot be buffered cheaply, and an
+ *    unflushed stream has no stable bytes to cache)
+ *  - NO non-framework Set-Cookie. A page that sets a session / per-user
+ *    cookie is per-user output and must not be shared. The framework's own
+ *    CSRF cookie (`webjs_csrf`) is allowed and re-minted per response on a
+ *    cache hit, so its presence does not block caching.
+ *  - CSP is OFF. With CSP enabled the inline boot script carries a fresh
+ *    per-request nonce, so the body varies per request and a cached body
+ *    would replay a stale nonce that the response's CSP header rejects.
+ *
+ * @param {Response} res
+ * @param {{ cspEnabled?: boolean }} [guards]
+ * @returns {boolean}
+ */
+export function isCacheableResponse(res, guards = {}) {
+  if (res.status !== 200) return false;
+  if (res.headers.has(STREAM_MARKER)) return false;
+  if (guards.cspEnabled) return false;
+  if (hasNonFrameworkSetCookie(res)) return false;
+  return true;
+}
+
+/**
+ * True when the response carries a Set-Cookie OTHER than the framework's
+ * own CSRF cookie. Reads each cookie individually via `getSetCookie()`, the
+ * only correct way to enumerate multiple Set-Cookie values (a combined
+ * `get('set-cookie')` cannot be split safely, since a cookie value or an
+ * Expires date can contain a comma). When `getSetCookie` is unavailable
+ * (a runtime older than Node 24) this FAILS SAFE: it reports a
+ * non-framework cookie (do not cache) rather than parsing only the first of
+ * a combined header and wrongly judging it framework-only.
+ *
+ * @param {Response} res
+ * @returns {boolean}
+ */
+function hasNonFrameworkSetCookie(res) {
+  const h = res.headers;
+  if (typeof h.getSetCookie !== 'function') {
+    // No reliable per-cookie enumeration: fail safe (treat as per-user).
+    return h.has('set-cookie');
+  }
+  for (const c of h.getSetCookie()) {
+    const name = c.split('=', 1)[0].trim().toLowerCase();
+    if (name !== 'webjs_csrf') return true;
+  }
+  return false;
+}
+
+/**
+ * Evict the cached HTML for one path (server-side, on-demand
+ * revalidation: the no-build ISR revalidation hook). A server action that
+ * mutates the data a cached page renders calls this so the next request
+ * re-renders. Distinct from the client-side `revalidate()` (which evicts
+ * the browser snapshot cache).
+ *
+ * The path may include a search string. A bare path with no query evicts
+ * ONLY the no-query entry; pass the exact `path?query` to target a
+ * specific query variant, or call `revalidateAll()` to clear everything.
+ *
+ * @param {string} path  e.g. '/blog' or '/blog?page=2'
+ * @returns {Promise<void>}
+ */
+export async function revalidatePath(path) {
+  if (typeof path !== 'string' || !path) return;
+  // Build the same normalized key readHtmlCache / writeHtmlCache produce.
+  let url;
+  try {
+    url = new URL(path, 'http://internal.invalid');
+  } catch {
+    return;
+  }
+  try {
+    await getStore().delete(htmlCacheKey(url));
+  } catch {
+    /* a store delete failure is non-fatal: the TTL still expires the entry */
+  }
+}
+
+/**
+ * Response-funnel step (#241): if the response carries the HTML_CACHE_MARKER
+ * (the SSR opted it into caching), re-check every guard against the FINAL
+ * response and, when it passes, buffer the body and store it under the URL
+ * key with TTL = the marked revalidate seconds. Always strips the marker so
+ * it never reaches the client. Returns the same response (the marker removal
+ * mutates its headers in place). Best-effort: any failure leaves the live
+ * response untouched. The CSP guard was already applied on the SSR side (the
+ * marker is only stamped when CSP is off), so it is not re-checked here.
+ *
+ * @param {Request} req
+ * @param {Response} res
+ * @param {URL} url
+ * @returns {Promise<Response>}
+ */
+export async function commitHtmlCache(req, res, url) {
+  const marker = res.headers.get(HTML_CACHE_MARKER);
+  if (!marker) return res;
+  res.headers.delete(HTML_CACHE_MARKER);
+  const revalidateSeconds = Number(marker);
+  if (!Number.isFinite(revalidateSeconds) || revalidateSeconds <= 0) return res;
+  // Per-user leak defense (#241). The page set `revalidate` (asserting "same
+  // for everyone"), but if the render actually read per-user request state
+  // (cookies() / headers() / getSession()), its body varies by visitor and
+  // must NOT be cached, even though it set no new Set-Cookie. Fail safe (skip
+  // caching) and warn the author ONCE per path so the wrong `revalidate` is
+  // visible without spamming the log.
+  if (dynamicAccessed()) {
+    warnDynamicRevalidateOnce(url.pathname);
+    return res;
+  }
+  // Re-check status / streaming / cookie guards against the final response.
+  if (!isCacheableResponse(res)) return res;
+  try {
+    const body = await res.clone().text();
+    await writeHtmlCache(
+      url,
+      {
+        body,
+        contentType: res.headers.get('content-type') || 'text/html; charset=utf-8',
+        cacheControl: res.headers.get('cache-control') || 'no-store',
+        status: res.status,
+      },
+      revalidateSeconds,
+    );
+  } catch {
+    /* a buffer / store failure must never affect the live response */
+  }
+  return res;
+}
+
+/**
+ * Paths already warned about a `revalidate` on a per-user page, so the
+ * console.warn fires once per offending route rather than once per request.
+ * @type {Set<string>}
+ */
+const _warnedDynamicPaths = new Set();
+
+/** @param {string} pathname */
+function warnDynamicRevalidateOnce(pathname) {
+  if (_warnedDynamicPaths.has(pathname)) return;
+  _warnedDynamicPaths.add(pathname);
+  console.warn(
+    `[webjs] not caching ${pathname}: it exported \`revalidate\` but read ` +
+    `per-user request state (cookies() / headers() / getSession()) during ` +
+    `render, so its output varies by visitor. Remove \`revalidate\` from a ` +
+    `per-user page, or stop reading request state if it is the same for ` +
+    `everyone. The page is being served fresh (uncached) to avoid a leak.`
+  );
+}
+
+/** Evict ALL cached HTML for this process. @returns {void} */
+export function revalidateAll() {
+  _generation++;
+}
+
+/** Internal: current generation, folded into keys by `htmlCacheKey`. */
+export function htmlCacheGeneration() {
+  return _generation;
+}