@webjsdev/server 0.8.10 → 0.8.11

package/index.js

@@ -34,12 +34,14 @@ export {
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
-export { headers, cookies, getRequest, withRequest, cspNonce } from './src/context.js';
+export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
 export { cors, resolveOrigin, applyCorsHeaders } from './src/cors.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
+export { revalidateTag, revalidateTags } from './src/cache-tags.js';
+export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';
 export { json, readBody } from './src/json.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/actions.js

@@ -301,8 +301,12 @@ export async function serveActionStub(idx, absFile) {
  * @param {string} hash
  * @param {string} fnName
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   invoked when the action throws unexpectedly, BEFORE the sanitized 500 is
+ *   returned, so an APM integration sees the original error. The caller wraps
+ *   it so a throwing sink can never affect the response.
  */
-export async function invokeAction(idx, hash, fnName, req) {
+export async function invokeAction(idx, hash, fnName, req, onError) {
   if (!verifyCsrf(req)) {
     return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
   }
@@ -327,6 +331,7 @@ export async function invokeAction(idx, hash, fnName, req) {
     const result = await fn(...args);
     return rpcResponse(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }
@@ -432,8 +437,12 @@ function matchOrigin(configured, origin) {
  * @param {ExposedRoute} route
  * @param {Record<string,string>} params
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   invoked when the exposed REST handler throws unexpectedly, BEFORE the
+ *   sanitized 500 is returned, so an APM integration sees the original error.
+ *   The caller wraps it so a throwing sink can never affect the response.
  */
-export async function invokeExposedAction(idx, route, params, req) {
+export async function invokeExposedAction(idx, route, params, req, onError) {
   const url = new URL(req.url);
   const query = Object.fromEntries(url.searchParams.entries());
   let body = {};
@@ -473,6 +482,7 @@ export async function invokeExposedAction(idx, route, params, req) {
     if (result instanceof Response) return result;
     return Response.json(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }

package/src/auth.js

@@ -8,7 +8,7 @@
  */
 
 import { getStore } from './cache.js';
-import { getRequest, getBodyLimits } from './context.js';
+import { getRequest, getBodyLimits, markDynamicAccess } from './context.js';
 import { readTextBounded, readFormDataBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 
 const enc = new TextEncoder();
@@ -220,6 +220,13 @@ export function createAuth(config) {
   // -- Session read/write ---------------------------------------------------
 
   async function readSession(req) {
+    // Reading the auth session is per-user (the body branches on the logged-in
+    // user), so mark the request dynamic so the server HTML cache excludes the
+    // page even when it wrongly set `revalidate`, mirroring getSession() /
+    // cookies() / headers(). This closes the auth-path leak (#241): `auth()`
+    // reaches here, reads the auth cookie raw, and would otherwise leave the
+    // page cacheable so a logged-in body could be served to the next visitor.
+    markDynamicAccess();
     const cookies = parseCookies(req.headers.get('cookie') || '');
     const raw = cookies[AUTH_COOKIE];
     if (!raw) return null;

package/src/build-info.js

@@ -0,0 +1,59 @@
+import { createRequire } from 'node:module';
+import { publishedBuildId } from './importmap.js';
+
+/**
+ * Build-info / version probe (issue #239).
+ *
+ * `GET /__webjs/version` returns a small JSON object a deploy can curl to
+ * verify which build is live, alongside the existing `/__webjs/health` and
+ * `/__webjs/ready` probes. It carries NO secrets: only the framework version,
+ * the published importmap build id (the same value the client router reads
+ * from `data-webjs-build` to detect a deploy), the running node version, and
+ * process uptime. Served before `ensureReady()` like the other probes, so it
+ * answers on a cold instance without blocking on the whole-app analysis.
+ *
+ * The framework version is read once from this package's own `package.json`,
+ * the same single-source pattern `requiredNodeMajor()` uses, so it never drifts
+ * from the published version.
+ */
+
+/** @type {string} */
+let _frameworkVersion = '';
+function frameworkVersion() {
+  if (_frameworkVersion) return _frameworkVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    _frameworkVersion = String(pkg?.version || '');
+  } catch {
+    _frameworkVersion = '';
+  }
+  return _frameworkVersion;
+}
+
+/**
+ * Compose the build-info payload. Pure (takes the moment as an argument) so a
+ * test can assert the shape without mocking the clock; the handler calls it
+ * with `process.uptime()`.
+ *
+ * @param {{ uptime?: number }} [opts]
+ * @returns {{ version: string, build: string, node: string, uptime: number }}
+ */
+export function buildInfo(opts = {}) {
+  return {
+    version: frameworkVersion(),
+    build: publishedBuildId(),
+    node: process.version,
+    uptime: typeof opts.uptime === 'number' ? opts.uptime : process.uptime(),
+  };
+}
+
+/**
+ * Build the `GET /__webjs/version` response. `no-store` so a proxy / browser
+ * never caches a stale build fingerprint.
+ *
+ * @returns {Response}
+ */
+export function buildInfoResponse() {
+  return Response.json(buildInfo(), { headers: { 'cache-control': 'no-store' } });
+}

package/src/cache-fn.js

@@ -24,6 +24,7 @@
  */
 
 import { getStore } from './cache.js';
+import { addKeyToTags } from './cache-tags.js';
 
 /**
  * Wrap an async function with server-side caching.
@@ -33,9 +34,18 @@ import { getStore } from './cache.js';
  * @param {{
  *   key: string,
  *   ttl?: number,
+ *   tags?: string[] | ((...args: Parameters<T>) => string[]),
  * }} opts
  *   - `key`: cache key prefix. Combined with serialized args to form the full key.
  *   - `ttl`: time-to-live in seconds. Default: 60.
+ *   - `tags`: optional tags this cached result belongs to, for cross-module
+ *     invalidation via `revalidateTag(tag)`. Either a static `string[]`
+ *     (every cached entry of this function shares them) or a function
+ *     `(...args) => string[]` so a per-arg read tags with the entity id
+ *     (e.g. `tags: (id) => ['post:' + id]`). The result is also recorded
+ *     under each tag's thin key index so `revalidateTag` can find and
+ *     evict it later, including arg-specific entries that the no-args
+ *     `invalidate()` cannot reach.
  * @returns {T & { invalidate: () => Promise<void> }}
  *   The cached function with the same signature, plus an `invalidate()`
  *   method to manually clear the cache.
@@ -43,6 +53,19 @@ import { getStore } from './cache.js';
 export function cache(fn, opts) {
   const prefix = opts.key;
   const ttlMs = (opts.ttl ?? 60) * 1000;
+  const tagsOpt = opts.tags;
+
+  /**
+   * Resolve the tag list for one call. A function form receives the call
+   * args (so a per-entity read can tag with the id); a static array is
+   * returned as-is. Anything else yields no tags.
+   * @param {any[]} args
+   * @returns {string[]}
+   */
+  function tagsFor(args) {
+    const raw = typeof tagsOpt === 'function' ? tagsOpt(...args) : tagsOpt;
+    return Array.isArray(raw) ? raw.filter((t) => typeof t === 'string' && t) : [];
+  }
 
   const wrapped = /** @type {T & { invalidate: () => Promise<void> }} */ (
     async function (...args) {
@@ -58,6 +81,23 @@ export function cache(fn, opts) {
 
       const result = await fn(...args);
       await store.set(cacheKey, JSON.stringify(result), ttlMs);
+      // Record tag -> cacheKey in the thin tag index so a later
+      // revalidateTag can find and evict this entry (including
+      // arg-specific keys the no-args invalidate() cannot reach).
+      // Best-effort: the value is already stored, so taggability must
+      // never break the cached call. A user tags() function that throws
+      // (e.g. reading post.id off a null arg), or an index write that
+      // fails, leaves the value cached (just untagged) and returns
+      // normally. tagsFor() is INSIDE the try because it runs the
+      // user-supplied function.
+      try {
+        await addKeyToTags(tagsFor(args), cacheKey, ttlMs);
+      } catch (err) {
+        console.warn(
+          `[webjs] cache(${prefix}): tag indexing failed, value is cached ` +
+          `but untagged (revalidateTag will not reach it): ${err && err.message ? err.message : err}`
+        );
+      }
       return result;
     }
   );

package/src/cache-tags.js

@@ -0,0 +1,147 @@
+/**
+ * Tag-based invalidation for server `cache()` (the Next.js revalidateTag
+ * model), built as a THIN key-index over the existing pluggable store
+ * (`get` / `set` / `delete` in `cache.js`), NOT a new subsystem.
+ *
+ * The problem it solves: `cache(fn, { key, ttl })` can only be invalidated
+ * by calling `wrapped.invalidate()` from the module that owns the wrapper,
+ * and even then only the no-args base key (arg-specific keys leak until
+ * their TTL). There was no way for an unrelated mutation (createComment)
+ * to invalidate a related read (postById) without importing every wrapper.
+ *
+ * The index: when a cached result is stored, `cache-fn.js` also records the
+ * mapping `tag -> cacheKey` here. Each tag holds a JSON array of the cache
+ * keys tagged with it, under the namespaced store key `cache:tag:<tag>`.
+ * `revalidateTag(tag)` reads that array, deletes every cache key in it, then
+ * clears the index entry. A mutation in ANY module can therefore evict every
+ * read tagged `'posts'` across modules with one explicit call.
+ *
+ * It stays a thin index over `store.get/set/delete`: no new store method, a
+ * plain JSON array (a Set is trivial in the memory store; the same get/set of
+ * a JSON array works for Redis). The cohesive companion for HTML paths is
+ * `revalidatePath` in `html-cache.js`; together they are the server cache
+ * invalidation surface (this one for `cache()` DATA, that one for cached HTML).
+ *
+ * MULTI-INSTANCE CAVEAT (mirrors #241): the index is a plain read-modify-write
+ * of a JSON array, NOT atomic across processes. With a shared Redis store,
+ * `revalidateTag` deletes the keys it can see and reaches every instance for
+ * those keys, but two instances appending to the same tag concurrently can
+ * lose an append (last write wins), so a freshly-stored key on a peer might
+ * miss eviction and live until its TTL. The tag index entry itself also
+ * carries the cache TTL, so the index self-prunes and never grows unbounded.
+ * For strict cross-instance invalidation, prefer a short `ttl` as the floor.
+ *
+ * @module cache-tags
+ */
+
+import { getStore } from './cache.js';
+
+/** Namespace prefix for every tag-index key, parallel to `cache:` entries. */
+const TAG_PREFIX = 'cache:tag:';
+
+/** @param {string} tag @returns {string} */
+function tagKey(tag) {
+  return `${TAG_PREFIX}${tag}`;
+}
+
+/**
+ * Read the cache-key set stored under one tag. Returns a plain array (empty
+ * on a miss / parse error, failing open). The store holds a JSON array.
+ *
+ * @param {string} tag
+ * @returns {Promise<string[]>}
+ */
+async function readTagKeys(tag) {
+  try {
+    const raw = await getStore().get(tagKey(tag));
+    if (!raw) return [];
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a cache key to every given tag's index (deduped). Called by
+ * `cache-fn.js` right after it stores a cached result. The index entry
+ * carries the same TTL as the cached value so it self-prunes and the tag
+ * index never outgrows the data it points at.
+ *
+ * Best-effort: a store failure here never affects the cached result that was
+ * already written (the value is still served; only its taggability is lost).
+ *
+ * @param {string[]} tags
+ * @param {string} cacheKey
+ * @param {number} [ttlMs]
+ * @returns {Promise<void>}
+ */
+export async function addKeyToTags(tags, cacheKey, ttlMs) {
+  if (!Array.isArray(tags) || tags.length === 0) return;
+  const store = getStore();
+  for (const tag of tags) {
+    if (typeof tag !== 'string' || !tag) continue;
+    try {
+      const keys = await readTagKeys(tag);
+      if (keys.includes(cacheKey)) continue;
+      keys.push(cacheKey);
+      await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+    } catch {
+      /* a tag-index write failure must never affect the cached value */
+    }
+  }
+}
+
+/**
+ * Evict every cached entry tagged with `tag`, then clear the tag index.
+ * A mutating server action calls this after a write so the next read of any
+ * tagged query recomputes. Works across modules: the read tagged `'posts'`
+ * in one module is invalidated by a `revalidateTag('posts')` issued from
+ * any other.
+ *
+ * ```js
+ * // modules/comments/actions/create-comment.server.ts
+ * 'use server';
+ * import { revalidateTag } from '@webjsdev/server';
+ * export async function createComment(input) {
+ *   await prisma.comment.create({ data: input });
+ *   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
+ *   return { success: true };
+ * }
+ * ```
+ *
+ * @param {string} tag
+ * @returns {Promise<void>}
+ */
+export async function revalidateTag(tag) {
+  if (typeof tag !== 'string' || !tag) return;
+  const store = getStore();
+  const keys = await readTagKeys(tag);
+  for (const k of keys) {
+    try {
+      await store.delete(k);
+    } catch {
+      /* a delete failure is non-fatal: the entry still expires via its TTL */
+    }
+  }
+  try {
+    await store.delete(tagKey(tag));
+  } catch {
+    /* non-fatal */
+  }
+}
+
+/**
+ * Convenience: `revalidateTag` for several tags in one call. A mutation that
+ * touches multiple cached surfaces (e.g. a post AND the post list) evicts
+ * them together.
+ *
+ * @param {string[]} tags
+ * @returns {Promise<void>}
+ */
+export async function revalidateTags(tags) {
+  if (!Array.isArray(tags)) return;
+  for (const tag of tags) {
+    await revalidateTag(tag);
+  }
+}

package/src/conditional-get.js

@@ -0,0 +1,183 @@
+/**
+ * RFC 7232 conditional GET (ETag + If-None-Match -> 304).
+ *
+ * One shared funnel that, given a Request and the buffered Response the
+ * pipeline produced, attaches a content-hash `ETag` when the response is
+ * cacheable and missing one, then turns a matching `If-None-Match` into a
+ * `304 Not Modified` with no body. Wired once at the response funnel in
+ * `dev.js`'s `handle()`, so it covers SSR HTML pages, static assets, app
+ * source modules, vendor / core runtime modules, and route-handler bodies
+ * uniformly.
+ *
+ * What is EXCLUDED, and why:
+ *   - `no-store` / `private` responses (the default for dynamic, per-user
+ *     pages). Never enable a cross-session 304 on private content: a shared
+ *     cache keyed on the URL could serve one user's validator to another.
+ *   - Any body the framework did not positively mark as fully buffered. The
+ *     funnel only hashes a response that ALREADY carries an `ETag` (a serve
+ *     branch hashed its own bytes) OR carries the internal `X-Webjs-Buffered`
+ *     marker the buffered serve branches stamp on a string / bytes body. It
+ *     never calls `arrayBuffer()` on an unmarked body. This is the guard that
+ *     keeps a user `route.{js,ts}` handler returning a `ReadableStream` (and
+ *     especially an SSE `text/event-stream`, whose stream NEVER ends) from
+ *     being buffered into memory or, worse, awaited forever so the response
+ *     hangs. A web `Response` exposes a `ReadableStream` body for a string and
+ *     for a live stream alike, with no public way to tell them apart, so a
+ *     positive opt-in marker is the only safe discriminator.
+ *   - Streaming Suspense bodies, flagged with `X-Webjs-Stream: 1` by the SSR
+ *     pipeline (a stricter form of the unmarked-body rule: the marker is
+ *     stripped and the response returned untouched). Streaming responses are
+ *     not conditional-GET cached, by design.
+ *   - Non-GET / non-HEAD methods, and any status other than 200. A validator
+ *     is only meaningful for a successful, replayable read.
+ *
+ * The ETag is WEAK (`W/"..."`). It is computed over the UNCOMPRESSED body
+ * bytes, then the prod compression step (`sendWebResponse` in `dev.js`) may
+ * stamp `Content-Encoding: gzip` / `br` on the SAME response. A STRONG
+ * validator must be unique per content-coding (RFC 7232 2.3.3), so reusing one
+ * strong ETag across identity / gzip / br would be non-conformant; a WEAK
+ * validator is the conformant choice for a hash shared across codings, and
+ * `If-None-Match` already uses weak comparison so a `304` still fires.
+ *
+ * The ETag is computed over the response's OWN body bytes, so an identical
+ * body yields an identical ETag across requests. Per-response varying bits
+ * that ride RESPONSE HEADERS (the `x-webjs-build` id, a `set-cookie` CSRF
+ * token, the CSP nonce on the header) are NOT part of the body hash, so they
+ * do not destabilise the ETag. The one body-level varying input is the CSP
+ * nonce stamped INTO the inline boot script: when CSP is enabled the HTML
+ * body changes every request, so its ETag changes every request and a 304 is
+ * simply never produced for that page (correct, not a bug). CSP is off by
+ * default, so the common case has a stable body and a stable ETag.
+ *
+ * @module conditional-get
+ */
+
+import { digestHex } from './crypto-utils.js';
+
+/**
+ * Internal header a buffered serve branch stamps to opt a response into
+ * conditional GET. Stripped at the funnel; it never reaches a client. A web
+ * `Response` exposes a `ReadableStream` body whether it was built from a
+ * string, bytes, or a live stream, so this explicit marker is how the funnel
+ * KNOWS a body is safe to hash without risking buffering a route handler's
+ * stream or hanging on an SSE response.
+ */
+export const BUFFERED_MARKER = 'x-webjs-buffered';
+
+/** Internal header the SSR pipeline stamps on a genuinely-streamed body. */
+export const STREAM_MARKER = 'x-webjs-stream';
+
+/**
+ * Headers that must not ride a 304 response (it has no body). Everything
+ * else (ETag, Cache-Control, Vary, the framework's X-Webjs-Build /
+ * X-Request-Id, Set-Cookie) is preserved so a shared cache and the client
+ * router behave identically to a 200.
+ */
+const STRIP_ON_304 = ['content-length', 'content-encoding', 'content-type'];
+
+/**
+ * Is this response cacheable enough to carry a validator?  Cacheable means a
+ * 200 whose `Cache-Control` is present and does not forbid storage. A
+ * `no-store` or `private` response is excluded (private / per-user content
+ * must never get a cross-session 304). `no-cache` is INCLUDED: it means
+ * "revalidate before reuse", and a 304 is exactly that revalidation answer,
+ * so dev's `no-cache` assets still benefit.
+ *
+ * @param {Response} res
+ * @returns {boolean}
+ */
+function isCacheable(res) {
+  if (res.status !== 200) return false;
+  const cc = res.headers.get('cache-control');
+  if (!cc) return false;
+  return !/(?:^|,)\s*(?:no-store|private)\s*(?:,|$)/i.test(cc);
+}
+
+/**
+ * Parse an `If-None-Match` request header and test it against an ETag.
+ * Honors the `*` wildcard and a comma-separated list, and compares
+ * weak-insensitively (a `W/` prefix on either side is ignored for the
+ * comparison, per RFC 7232 weak-comparison semantics, which is the correct
+ * function for `If-None-Match`).
+ *
+ * @param {string | null} header  the raw `If-None-Match` value
+ * @param {string} etag  the response ETag, e.g. `"abc123"`
+ * @returns {boolean}
+ */
+export function ifNoneMatchSatisfied(header, etag) {
+  if (!header || !etag) return false;
+  const want = stripWeak(etag);
+  for (const raw of header.split(',')) {
+    const tok = raw.trim();
+    if (tok === '*') return true;
+    if (stripWeak(tok) === want) return true;
+  }
+  return false;
+}
+
+/** @param {string} tag */
+function stripWeak(tag) {
+  return tag.startsWith('W/') ? tag.slice(2) : tag;
+}
+
+/**
+ * Apply conditional-GET semantics to a finished, buffered Response.
+ *
+ * Returns either the same response (now possibly carrying an `ETag`) or, when
+ * the request's `If-None-Match` matches, a fresh `304 Not Modified` with no
+ * body and the validators / caching headers preserved. A streaming,
+ * non-cacheable, or non-GET/HEAD response is returned unchanged.
+ *
+ * @param {Request} req
+ * @param {Response} res
+ * @returns {Promise<Response>}
+ */
+export async function applyConditionalGet(req, res) {
+  const method = req.method.toUpperCase();
+  // Always consume the internal buffered marker so it never reaches a client.
+  const buffered = res.headers.has(BUFFERED_MARKER);
+  if (buffered) res.headers.delete(BUFFERED_MARKER);
+  // A genuinely streamed Suspense response is flagged by the SSR pipeline.
+  // Strip that marker too and skip conditional-GET so the live stream is
+  // never consumed.
+  if (res.headers.has(STREAM_MARKER)) {
+    res.headers.delete(STREAM_MARKER);
+    return res;
+  }
+  if (method !== 'GET' && method !== 'HEAD') return res;
+  if (!isCacheable(res)) return res;
+
+  let etag = res.headers.get('etag');
+  if (!etag) {
+    // Only hash a body the framework positively marked as fully buffered.
+    // Without the marker we must NOT read the body, because a user route
+    // handler returning a ReadableStream would be buffered into memory, and
+    // an SSE (text/event-stream) stream never ends so the await would hang
+    // forever. A web Response exposes a ReadableStream body for a string and
+    // for a live stream alike, so the marker is the only safe discriminator.
+    if (!buffered) return res;
+    let bytes;
+    try {
+      // Clone so the caller's body is never consumed. Safe here because a
+      // marked body is built from a string / bytes, so the clone resolves
+      // at once.
+      bytes = new Uint8Array(await res.clone().arrayBuffer());
+    } catch {
+      // A body that refuses to buffer (should not happen for a marked branch)
+      // is left without a validator rather than crashing the funnel.
+      return res;
+    }
+    // WEAK validator. The hash is over the uncompressed body and is reused
+    // across identity / gzip / br codings (compression runs after this), which
+    // a STRONG ETag may not do (RFC 7232 2.3.3). If-None-Match weak-compares.
+    etag = `W/"${(await digestHex('SHA-1', bytes)).slice(0, 16)}"`;
+    res.headers.set('etag', etag);
+  }
+
+  if (ifNoneMatchSatisfied(req.headers.get('if-none-match'), etag)) {
+    const headers = new Headers(res.headers);
+    for (const h of STRIP_ON_304) headers.delete(h);
+    return new Response(null, { status: 304, headers });
+  }
+  return res;
+}

package/src/context.js

@@ -20,7 +20,22 @@ import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
  * server state) can enforce the same limit the RPC and page-action paths do. The
  * handler writes it per request via `setBodyLimits`.
  *
- * @typedef {{ req: Request, cspNonce?: string, bodyLimits?: { json: number, multipart: number } }} Store
+ * `requestId` holds the per-request correlation id (issue #239). The handler
+ * mints a `crypto.randomUUID()` at the start of every request (or honors an
+ * inbound `X-Request-Id` from a trusted upstream proxy) and stores it here via
+ * `setRequestId`, so server-side app code can read it with `requestId()` to
+ * stamp it on its own logs / outbound calls, and the framework includes it in
+ * the access log, the error log, and the `X-Request-Id` response header.
+ *
+ * `dynamicAccess` is set the moment the render reads per-user request state
+ * through a framework helper (`cookies()`, `headers()`, `getSession()`),
+ * mirroring Next.js auto-marking a route dynamic on a `cookies()` / `headers()`
+ * read (#241). The server HTML cache reads it at commit time and REFUSES to
+ * cache a page that opted into `revalidate` but actually varies per user, so a
+ * wrong `revalidate` on a cookie-reading page fails safe (uncached) instead of
+ * leaking one visitor's view to another.
+ *
+ * @typedef {{ req: Request, cspNonce?: string, bodyLimits?: { json: number, multipart: number }, requestId?: string, dynamicAccess?: boolean }} Store
  */
 
 /** @type {AsyncLocalStorage<Store>} */
@@ -81,6 +96,56 @@ export function getBodyLimits() {
   return als.getStore()?.bodyLimits ?? null;
 }
 
+/**
+ * Set the per-request correlation id on the current store (issue #239). The
+ * handler calls this at the start of every request with either an inbound
+ * `X-Request-Id` (a trusted upstream proxy's trace id) or a freshly minted
+ * `crypto.randomUUID()`. A no-op outside a request scope.
+ *
+ * @param {string} id
+ */
+export function setRequestId(id) {
+  const store = als.getStore();
+  if (store) store.requestId = id;
+}
+
+/**
+ * The correlation id for the in-flight request (issue #239), or `null`
+ * outside a request scope. Server-side app code (pages, layouts, server
+ * actions, route handlers, middleware) reads it to correlate its own logs and
+ * outbound calls with the framework's access / error logs and the
+ * `X-Request-Id` response header, all of which carry the same id.
+ *
+ * @returns {string | null}
+ */
+export function requestId() {
+  return als.getStore()?.requestId ?? null;
+}
+
+/**
+ * Mark the in-flight request as having read per-user state (issue #241). The
+ * framework's request-state readers (`cookies()`, `headers()`, `getSession()`)
+ * call this, so the server HTML cache can tell at commit time that the render
+ * actually depends on the visitor and refuse to cache it even when the page
+ * declared `revalidate`. A no-op outside a request scope.
+ */
+export function markDynamicAccess() {
+  const store = als.getStore();
+  if (store) store.dynamicAccess = true;
+}
+
+/**
+ * True when the in-flight render read per-user request state via a framework
+ * helper (issue #241). Read by the server HTML cache's commit step to fail
+ * safe (do not cache) on a per-user page that wrongly set `revalidate`.
+ * Returns false outside a request scope.
+ *
+ * @returns {boolean}
+ */
+export function dynamicAccessed() {
+  return als.getStore()?.dynamicAccess === true;
+}
+
 /**
  * Server-only implementation of the CSP nonce reader. Returns the
  * per-request nonce that the handler MINTED and stored (issue #233) when
@@ -125,6 +190,10 @@ export { cspNonce };
 export function headers() {
   const req = getRequest();
   if (!req) throw new Error('headers(): called outside a request scope');
+  // Reading request headers makes the render per-user (an Authorization /
+  // Accept-Language / Cookie read varies the output), so mark the request
+  // dynamic so the HTML cache excludes it even under `revalidate` (#241).
+  markDynamicAccess();
   return req.headers;
 }
 
@@ -139,6 +208,10 @@ export function headers() {
 export function cookies() {
   const req = getRequest();
   if (!req) throw new Error('cookies(): called outside a request scope');
+  // Reading cookies makes the render per-user (a logged-in vs logged-out body
+  // keys off an auth cookie), so mark the request dynamic so the HTML cache
+  // excludes it even under `revalidate`, the core leak defense (#241).
+  markDynamicAccess();
   const map = parseCookies(req);
   return {
     get: (name) => map[name],