@webjsdev/server 0.8.9 → 0.8.11

package/src/dev.js

@@ -1,10 +1,18 @@
 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, stripTypeScriptTypes } from 'node:module';
+import { createRequire } from 'node:module';
+// Namespace import, NOT `import { stripTypeScriptTypes }`. On Node < 22.13 the
+// `stripTypeScriptTypes` named export does not exist, and a NAMED import of a
+// missing builtin export is a LINK-TIME SyntaxError that fires before any
+// module body runs, which would defeat the Node-version preflight (issue #238)
+// by crashing the import of @webjsdev/server itself. A namespace import links
+// on every Node (the property is just `undefined` at runtime on old Node), so
+// importing @webjsdev/server succeeds and `assertNodeVersion()` at the top of
+// createRequestHandler throws the clean "you need Node 24+" message instead.
+import * as nodeModule from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Server-side `.ts` imports are handled natively by Node 24+'s default
@@ -40,6 +48,7 @@ process.emitWarning = function (warning, type, code, ctor) {
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { ssrPage, ssrNotFound } from './ssr.js';
+import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
 import {
   buildActionIndex,
@@ -56,7 +65,11 @@ import {
   hashFile,
 } from './actions.js';
 import { defaultLogger } from './logger.js';
-import { withRequest } from './context.js';
+import { assertNodeVersion } from './node-version.js';
+import { applyEnvValidation } from './env-schema.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';
 import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
@@ -67,8 +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',
@@ -194,6 +243,81 @@ export async function readElideEnabled(appDir) {
   return true;
 }
 
+/**
+ * Read the per-path response-header config (`webjs.headers`) from the
+ * app's package.json and compile it to URLPattern rules. A missing,
+ * malformed, or unreadable config yields an empty rule set (the secure
+ * defaults still apply), never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileHeaderRules>>}
+ */
+export async function readHeaderRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileHeaderRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the CSP config (`webjs.csp`) from the app's package.json and
+ * normalize it (issue #233). A missing, malformed, or unreadable config
+ * yields a disabled config (no nonce minted, no CSP header), never a
+ * throw: a broken security knob must fail closed, not take the app down.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof readCspConfig>>}
+ */
+export async function readCspConfigFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readCspConfig(pkg);
+  } catch {
+    return readCspConfig(undefined);
+  }
+}
+
+/**
+ * Resolve the request body-size limits (issue #237) from the app's package.json
+ * `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env overrides
+ * (`WEBJS_MAX_BODY_BYTES` / `WEBJS_MAX_MULTIPART_BYTES`). A missing or
+ * unreadable package.json falls through to the secure defaults (env still wins),
+ * never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ json: number, multipart: number }>}
+ */
+export async function readBodyLimitsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return readBodyLimits(pkg);
+}
+
+/**
+ * Resolve the node:http server timeouts (issue #237) from the app's
+ * package.json `webjs.requestTimeoutMs` / `webjs.headersTimeoutMs` /
+ * `webjs.keepAliveTimeoutMs` plus the env overrides. A missing or unreadable
+ * package.json falls through to the secure defaults (env still wins).
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }>}
+ */
+export async function readServerTimeoutsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return computeServerTimeouts(pkg);
+}
+
 /**
  * Create a reusable, framework-agnostic request handler for a webjs app.
  * The returned `handle(req)` takes a standard `Request` and resolves to a
@@ -204,10 +328,15 @@ export async function readElideEnabled(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
  */
 export async function createRequestHandler(opts) {
+  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Throw a clear Error here so an embedded host (Express/Fastify/Bun/Deno)
+  // gets the actionable message at boot, not a cryptic API failure mid-request.
+  assertNodeVersion({ onFail: 'throw' });
   const appDir = resolve(opts.appDir);
   // Load <appDir>/.env into process.env BEFORE anything else.
   // buildActionIndex below imports server-only files (lib/*.server.ts,
@@ -217,8 +346,40 @@ export async function createRequestHandler(opts) {
   // to boot until the user discovered the missing env-load. See
   // tracker #37.
   loadAppEnv(appDir);
+  // Optional boot-time env validation (#236). If <appDir>/env.{js,ts} exists it
+  // default-exports a typed schema or a custom validator function; we run it
+  // against process.env (now populated by loadAppEnv) BEFORE buildActionIndex
+  // imports any server-only module. A failure throws a clear aggregated Error
+  // here, so an embedded host rejects at boot and the CLI exits non-zero,
+  // failing fast instead of crashing cryptically mid-request. Absent file is a
+  // no-op (opt-in). Coerced + defaulted values are written back to process.env.
+  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
@@ -285,10 +446,32 @@ export async function createRequestHandler(opts) {
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
 
+  // Per-path response-header rules (issue #232), read once from the
+  // app's package.json `webjs.headers`. Static config, so no rebuild
+  // re-read; the secure defaults need no config and apply regardless.
+  const headerRules = await readHeaderRules(appDir);
+
+  // CSP config (issue #233), read once from the app's package.json
+  // `webjs.csp`. OFF by default: when disabled no nonce is minted and no
+  // Content-Security-Policy header is set, so an unconfigured app is
+  // unchanged. When enabled, `handle()` mints a fresh per-request nonce,
+  // makes it the value `cspNonce()` returns (so the SSR'd inline scripts
+  // carry it), and sets the matching header carrying the same nonce.
+  const cspConfig = await readCspConfigFromApp(appDir);
+
+  // Request body-size limits (issue #237), read once from the app's
+  // package.json `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env
+  // overrides. The secure defaults (1 MiB JSON/RPC, 10 MiB form) apply when
+  // unconfigured. Stamped on every request via `setBodyLimits` so `readBody`
+  // (used inside route handlers) enforces the same cap the RPC and page-action
+  // paths do.
+  const bodyLimits = await readBodyLimitsFromApp(appDir);
+
   const state = {
     routeTable,
     actionIndex: null,
     middleware: null,
+    bodyLimits,
     logger,
     moduleGraph: null,
     elidableComponents: new Set(),
@@ -555,6 +738,134 @@ 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
+      // inline boot script, the importmap, and the modulepreload hints.
+      // Disabled by default, so no nonce is minted and the response is
+      // unchanged. One minted value flows mint -> store -> SSR -> header.
+      const nonce = cspConfig.enabled ? mintNonce() : '';
+      if (nonce) setCspNonce(nonce);
+
+      // Make the resolved body-size limits (issue #237) readable from the
+      // request scope, so `readBody` inside a route handler enforces the same
+      // cap the framework's own RPC / page-action body reads do.
+      setBodyLimits(state.bodyLimits);
+
+      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 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
+      // middleware, a route handler, or via the webjs.headers config), so
+      // an explicit app policy still wins.
+      if (nonce && !merged.headers.has('content-security-policy') &&
+          !merged.headers.has('content-security-policy-report-only')) {
+        // readCspConfig already drops a directive whose name/value carries a
+        // control char, so buildCspHeader produces a Headers-safe value. The
+        // try/catch is a belt-and-suspenders backstop: a surprise value must
+        // never throw the response pipeline (fail closed to no CSP header
+        // rather than a self-inflicted 500 on every request).
+        try {
+          merged.headers.set(cspHeaderName(cspConfig), buildCspHeader(cspConfig, nonce));
+        } catch {
+          /* a malformed policy must not take the request down: serve without CSP */
+        }
+      }
+
+      // 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;
+    });
+  }
+
+  /** @param {Request} req */
+  function produce(req) {
+    return (async () => {
       // Health and readiness probes are answered BEFORE ensureReady so a probe
       // never blocks on the analysis. `/__webjs/health` is liveness (the
       // process is up and accepting connections). `/__webjs/ready` is 503 until
@@ -574,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) {
@@ -613,17 +931,18 @@ 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 });
         }
       }
       return next();
-    });
+    })();
   }
 
   /**
@@ -684,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) {
@@ -800,6 +1120,20 @@ export async function startServer(opts) {
     }
   });
 
+  // Inbound server timeouts (issue #237), node:http built-ins. Defends against
+  // slowloris and hung connections: `requestTimeout` bounds the time to receive
+  // the WHOLE request, `headersTimeout` the time to receive just the headers
+  // (node measures both from the same request start, so it is kept strictly
+  // under requestTimeout to actually fire), and `keepAliveTimeout` the idle
+  // window before a kept-alive socket is closed. Secure production defaults,
+  // overridable via `webjs.requestTimeoutMs` / `headersTimeoutMs` /
+  // `keepAliveTimeoutMs` in package.json or the matching WEBJS_*_MS env vars.
+  // A value of 0 disables that timeout (node's own no-limit sentinel).
+  const timeouts = await readServerTimeoutsFromApp(app.appDir);
+  server.requestTimeout = timeouts.requestTimeout;
+  server.headersTimeout = timeouts.headersTimeout;
+  server.keepAliveTimeout = timeouts.keepAliveTimeout;
+
   // WebSocket upgrade handling: any route.js that exports `WS` becomes a
   // WebSocket endpoint at its URL.
   attachWebSocket(server, () => app.getRouteTable(), { dev, logger });
@@ -920,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
@@ -945,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.
@@ -966,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);
     }
   }
@@ -1090,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 });
       }
@@ -1103,17 +1446,39 @@ async function handleCore(req, ctx) {
     return runWithSegmentMiddleware(req, api.route.middlewares, handler, dev);
   }
 
-  // Page route (only for GET/HEAD)
-  if (method === 'GET' || method === 'HEAD') {
+  // Page route. GET/HEAD render the page. A NON-GET/HEAD method (POST/PUT/…)
+  // is only routed here when the page module exports an `action` (#244); the
+  // action runs inside the page's segment middleware, then either PRG-redirects
+  // (303) on success, re-renders the same page (422) with field errors on
+  // failure, or honors a thrown redirect()/notFound(). Without an `action`
+  // export, a non-GET/HEAD request falls through to the 404 below, unchanged.
+  {
     const page = matchPage(state.routeTable, path);
     if (page) {
-      const handler = () => ssrPage(page.route, page.params, url, {
-        dev, appDir, req, moduleGraph: state.moduleGraph,
+      const ssrOpts = {
+        dev, appDir, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
         elidableComponents: state.elidableComponents,
         inertRouteModules: state.inertRouteModules,
-      });
-      return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+        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 });
+        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+      }
+      const loaded = await loadPageAction(page.route.file, dev);
+      if (loaded) {
+        const handler = () => runPageAction(page.route, page.params, url, loaded, req, ssrOpts);
+        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
+      }
     }
   }
 
@@ -1372,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 });
@@ -1406,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 });
 }
 
@@ -1440,7 +1804,7 @@ async function exists(p) {
  * @returns {Promise<string>}
  */
 async function stripTs(source, _abs) {
-  return stripTypeScriptTypes(source);
+  return nodeModule.stripTypeScriptTypes(source);
 }
 
 /**
@@ -1465,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',
       },
     });
   }
@@ -1521,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',
     },
   });
 }