@webjsdev/server 0.8.10 → 0.8.12

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';
@@ -48,6 +47,7 @@ process.emitWarning = function (warning, type, code, ctor) {
 };
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
+import { generateRouteTypes } from './route-types.js';
 import { ssrPage, ssrNotFound } from './ssr.js';
 import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
@@ -68,7 +68,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 +81,51 @@ import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
-import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
+
+/**
+ * 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, setBasePath, basePath } from './importmap.js';
+import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
+import {
+  compileRedirectRules,
+  applyRedirects,
+  readTrailingSlashPolicy,
+  applyTrailingSlash,
+} from './redirects.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',
@@ -227,6 +269,61 @@ export async function readHeaderRules(appDir) {
   }
 }
 
+/**
+ * Read the declarative redirect config (`webjs.redirects`) from the app's
+ * package.json and compile it to URLPattern rules (issue #254). A missing,
+ * malformed, or unreadable config yields an empty rule set (no redirects),
+ * never a throw. Patterns are compiled ONCE here at boot, not per request.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileRedirectRules>>}
+ */
+export async function readRedirectRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileRedirectRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the trailing-slash policy (`webjs.trailingSlash`) from the app's
+ * package.json (issue #255). A missing, malformed, or unreadable config
+ * yields `'ignore'` (no canonicalization), never a throw, so an
+ * unconfigured app is unchanged.
+ *
+ * @param {string} appDir
+ * @returns {Promise<'never' | 'always' | 'ignore'>}
+ */
+export async function readTrailingSlashFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readTrailingSlashPolicy(pkg);
+  } catch {
+    return 'ignore';
+  }
+}
+
+/**
+ * Read the sub-path base path (`webjs.basePath`) from the app's
+ * package.json (issue #256). A missing, malformed, or unreadable config
+ * yields `''` (root mount), never a throw, so an unconfigured app is
+ * byte-identical to before this feature. Normalized to `''` or
+ * `/segment[/segment...]` by `readBasePath`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+export async function readBasePathFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readBasePath(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
@@ -294,6 +391,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 +419,39 @@ 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) });
+    }
+  }
+  // Sub-path deployment base path (issue #256), read once from the app's
+  // package.json `webjs.basePath` and bound into the importmap builder BEFORE
+  // setCoreInstall / setVendorEntries so every importmap target (and the
+  // recomputed hash) reflects the prefix. Empty (the default) makes both the
+  // ingress strip and the emit-side prefix pure no-ops, so an unconfigured app
+  // is byte-identical to before this feature.
+  const basePathValue = await readBasePathFromApp(appDir);
+  await setBasePath(basePathValue);
+
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -387,11 +518,53 @@ export async function createRequestHandler(opts) {
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
 
+  // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
+  // dev so an editor's tsserver always has up-to-date route types without the
+  // developer remembering to run `webjs types`. Best-effort and fire-and-
+  // forget: a failure logs and never blocks boot. Re-emitted after each route
+  // rebuild (see doRebuild) so adding/removing a route refreshes the types.
+  /** @returns {Promise<void>} */
+  async function emitRouteTypes() {
+    try {
+      const { mkdir, writeFile, rename } = await import('node:fs/promises');
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      // Write to a temp sibling then rename, so tsserver (which reads this
+      // file) never observes a half-written body if two rebuilds race. rename
+      // is atomic within the same dir. Both paths sit under the watcher-ignored
+      // .webjs/, so neither the temp write nor the rename re-triggers a rebuild.
+      const dest = join(outDir, 'routes.d.ts');
+      const tmp = join(outDir, `routes.d.ts.${process.pid}.tmp`);
+      await writeFile(tmp, text);
+      await rename(tmp, dest);
+    } catch (e) {
+      logger.warn?.(`[webjs] could not write .webjs/routes.d.ts (route types): ${e?.message || e}`);
+    }
+  }
+  if (dev) void emitRouteTypes();
+
   // 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);
 
+  // Declarative redirect rules (issue #254), read once from the app's
+  // package.json `webjs.redirects` and compiled to URLPattern rules at
+  // boot (never per request). Empty when unconfigured, so an app with no
+  // redirects is unchanged. Applied at the very start of request handling,
+  // before routing / SSR / asset serving, so a moved URL returns a 308/307
+  // immediately.
+  const redirectRules = await readRedirectRules(appDir);
+
+  // Trailing-slash policy (issue #255), read once from the app's package.json
+  // `webjs.trailingSlash`. Default `'ignore'` (no canonicalization), so an
+  // unconfigured app is unchanged; `'never'` (recommended) strips a trailing
+  // slash and `'always'` adds one, each via a 308 to the canonical form.
+  // Applied in produce() AFTER the declarative redirects, so an explicit
+  // redirect rule wins first and the two never loop.
+  const trailingSlashPolicy = await readTrailingSlashFromApp(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
@@ -656,6 +829,10 @@ export async function createRequestHandler(opts) {
     // The route table is the only eager artifact (cheap directory scan); rebuild
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
+    // Refresh the generated route types (#258) so adding/removing a route file
+    // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
+    // best-effort (see emitRouteTypes).
+    if (dev) void emitRouteTypes();
     clearVendorCache();
     state.tsCache.clear();
     // Invalidate the lazy analysis; the next request rebuilds the graph,
@@ -679,6 +856,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 +878,58 @@ 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 */ }
+      // Sub-path deployment (issue #256): the per-path response-header rules
+      // (`webjs.headers`) author their `source` patterns app-root-relative,
+      // exactly like `webjs.redirects` / `webjs.trailingSlash` (which the
+      // ingress strip in produce() already sees root-relative). So match the
+      // header rules against the STRIPPED path too, keeping the whole config
+      // surface consistent under a base path. `pathname` itself (used for the
+      // access log) stays the RAW path the client hit. No-op when basePath is
+      // empty or the request is not under it.
+      let headerPathname = pathname;
+      if (basePathValue) {
+        const s = stripBasePath(pathname, basePathValue);
+        if (s !== null) headerPathname = s;
+      }
+      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, {
-        pathname,
+      let merged = applySecurityHeaders(res, {
+        pathname: headerPathname,
         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,13 +948,129 @@ 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);
+        // Sub-path deployment (issue #256): the HTML cache READ (in ssrPage)
+        // and `revalidatePath` both key on the app-root-relative path, so key
+        // the WRITE on the stripped path too, or a cached page would never
+        // hit. No-op when basePath is empty / the path is not under it.
+        if (basePathValue) {
+          const s = stripBasePath(reqUrl.pathname, basePathValue);
+          if (s !== null) reqUrl.pathname = s;
+        }
+        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.
+      // Use the STRIPPED path for the suppression check (issue #256) so a
+      // framework probe at `<basePath>/__webjs/*` is suppressed just like the
+      // root-mounted `/__webjs/*`. The logged `path` stays the RAW client URL.
+      if (shouldAccessLog(headerPathname)) {
+        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 () => {
+      // Sub-path deployment ingress strip (issue #256). When `webjs.basePath`
+      // is set and the request path is under it, STRIP the prefix and rewrite
+      // the Request so EVERYTHING downstream (redirects, trailing-slash, the
+      // probes, the `/__webjs/*` checks, the source-file gate, route matching,
+      // SSR) sees a ROOT-relative path and works UNCHANGED. This single strip
+      // is why the rest of the framework needs no per-site changes. A request
+      // whose path is NOT under the base path is not for this mounted app, so
+      // return a 404 (the safe default for a mounted app). Empty basePath (the
+      // default) is a pure pass-through, so an unconfigured app is unchanged.
+      if (basePathValue) {
+        let reqUrl;
+        try { reqUrl = new URL(req.url); } catch { reqUrl = null; }
+        if (reqUrl) {
+          const stripped = stripBasePath(reqUrl.pathname, basePathValue);
+          if (stripped === null) {
+            // Not under the base path: this request is not for this app.
+            return new Response('Not found', {
+              status: 404,
+              headers: { 'content-type': 'text/plain; charset=utf-8' },
+            });
+          }
+          if (stripped !== reqUrl.pathname) {
+            reqUrl.pathname = stripped;
+            // Rewrite the Request with the stripped URL, preserving method,
+            // headers, and body. `duplex: 'half'` is required by the spec when
+            // a body stream is present on a non-GET/HEAD request.
+            const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+            req = new Request(
+              reqUrl.toString(),
+              /** @type {any} */ ({
+                method: req.method,
+                headers: req.headers,
+                body: hasBody ? req.body : undefined,
+                duplex: hasBody ? 'half' : undefined,
+                redirect: req.redirect,
+                signal: req.signal,
+              }),
+            );
+          }
+        }
+      }
+
+      // Declarative redirects (issue #254): apply the configured old-path ->
+      // new-path rules at the VERY START of request handling, before the
+      // probes, routing, SSR, or asset serving. A matched source returns a
+      // 308 (permanent, the SEO default) / 307 (temporary) / configured
+      // status immediately, so a moved URL never reaches the router.
+      // `applyRedirects` skips /__webjs/* itself, so the framework probes /
+      // runtime below are never redirected. The secure-header + conditional-GET
+      // funnel in handle() still wraps this Response, like any other.
+      const redirectResp = applyRedirects(req, redirectRules);
+      if (redirectResp) return redirectResp;
+
+      // Trailing-slash canonicalization (issue #255): after the explicit
+      // redirects above (so an explicit rule wins first and the two never
+      // form a loop), 308-redirect a non-canonical path to the policy's
+      // canonical form (`never` strips a trailing slash, `always` adds one).
+      // Default `'ignore'` is a no-op. The root `/` and file paths are
+      // exempt; `/__webjs/*` is exempt too (defense in depth, the redirects
+      // above already skip it). The funnel in handle() still wraps this.
+      const slashResp = applyTrailingSlash(req, trailingSlashPolicy);
+      if (slashResp) return slashResp;
+
       // 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
@@ -751,6 +1090,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 +1136,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 });
         }
       }
@@ -808,14 +1155,25 @@ export async function createRequestHandler(opts) {
    * BEFORE running SSR: resolves a pathname to its page-route module URLs
    * without loading them. Returns null for non-page paths.
    *
+   * Sub-path deployment (issue #256): the HTTP layer passes the RAW request
+   * pathname (still carrying the base path, since the ingress strip happens
+   * inside `produce`, not here), so strip it for route matching and prefix
+   * the emitted module URLs so the early-hint preloads resolve under the
+   * prefix. A path not under the base path yields null (no hints).
+   *
    * @param {string} pathname
    */
   function routeFor(pathname) {
-    const page = matchPage(state.routeTable, pathname);
+    const matchPathname = basePathValue
+      ? stripBasePath(pathname, basePathValue)
+      : pathname;
+    if (matchPathname === null) return null;
+    const page = matchPage(state.routeTable, matchPathname);
     if (!page) return null;
     const moduleUrls = [page.route.file, ...page.route.layouts].map((f) => {
       let rel = f.startsWith(appDir) ? f.slice(appDir.length) : f;
-      return rel.split('\\').join('/').replace(/^\/?/, '/');
+      const url = rel.split('\\').join('/').replace(/^\/?/, '/');
+      return withBasePath(url, basePathValue);
     });
     return { moduleUrls };
   }
@@ -855,12 +1213,32 @@ export async function createRequestHandler(opts) {
  * etc.) sitting in front of this process. See the deployment docs for
  * the recommended topology.
  *
+/**
+ * Paths under the app root whose changes must NOT trigger a dev rebuild.
+ * `node_modules` / `.git` are noise. `.webjs/` is the framework's generated
+ * artefact dir (the #258 routes.d.ts and the vendor pin) that the dev server
+ * itself writes on startup and on every rebuild, so without this skip the
+ * write fires a watch event, triggers a rebuild, re-writes the file, and loops
+ * forever. `prisma/dev*` / `prisma/migrations` churn during db:migrate. The
+ * prisma branch is prefix-only (no trailing separator) so the SQLite sidecars
+ * `prisma/dev.db` / `prisma/dev.db-journal` match too; the others stay
+ * separator-anchored so an unrelated name like `node_modules.bak/foo` does not.
+ *
+ * @param {string} filename relative path from an fs.watch `event.filename`
+ * @returns {boolean} true when the change should be ignored
+ */
+export function shouldIgnoreWatchPath(filename) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/.test(filename || '');
+}
+
+/**
  * @param {{
  *   appDir: string,
  *   port?: number,
  *   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) {
@@ -889,18 +1267,9 @@ export async function startServer(opts) {
     // `fs.promises.watch`. Stable on macOS, Windows, and Linux as of
     // Node 24. No external dep needed.
     //
-    // fs.watch returns relative paths in event.filename. We apply
-    // the same ignore filter chokidar used before: skip
-    // node_modules, .git, and prisma's dev artefacts (dev.db,
-    // dev.db-journal, migrations/) which the dev server writes
-    // during db:migrate and would otherwise loop.
-    //
-    // The prisma branch uses prefix-only matching (no required
-    // trailing separator) so the SQLite sidecar files like
-    // `prisma/dev.db` and `prisma/dev.db-journal` are ignored too.
-    // node_modules / .git stay separator-anchored so unrelated
-    // names like `node_modules.bak/foo` don't get caught.
-    const IGNORE = /(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/;
+    // fs.watch returns relative paths in event.filename. `shouldIgnoreWatchPath`
+    // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
+    // prisma's dev artefacts so a file the dev server itself writes never loops.
     const rebuild = debounce(() => app.rebuild(), 80);
     watcherAbort = new AbortController();
     (async () => {
@@ -908,7 +1277,7 @@ export async function startServer(opts) {
         const events = fsWatch(app.appDir, { recursive: true, signal: watcherAbort.signal });
         for await (const event of events) {
           const filename = event.filename || '';
-          if (IGNORE.test(filename)) continue;
+          if (shouldIgnoreWatchPath(filename)) continue;
           rebuild();
         }
       } catch (err) {
@@ -932,8 +1301,11 @@ export async function startServer(opts) {
     try {
       const url = urlFromRequest(req);
 
-      // SSE: handled specially; doesn't fit the req→Response model.
-      if (url.pathname === '/__webjs/events') {
+      // SSE: handled specially; doesn't fit the req→Response model. Match the
+      // base-path-stripped pathname so the reload stream answers at
+      // `<basePath>/__webjs/events` under a sub-path deploy (#256). With no
+      // basePath this is a pure pass-through (the bare path still matches).
+      if (stripBasePath(url.pathname, basePath()) === '/__webjs/events') {
         if (!dev) { res.writeHead(404); res.end(); return; }
         res.writeHead(200, {
           'content-type': 'text/event-stream',
@@ -1052,7 +1424,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
   // Dev live-reload client.
   if (path === '/__webjs/reload.js') {
     if (!dev) return new Response('Not found', { status: 404 });
-    return new Response(RELOAD_CLIENT_JS, {
+    return new Response(reloadClientJs(basePath()), {
       headers: { 'content-type': 'application/javascript; charset=utf-8' },
     });
   }
@@ -1111,7 +1483,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 +1508,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 +1532,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 +1661,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 +1690,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 +1966,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 +1999,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 +2058,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 +2115,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',
     },
   });
 }
@@ -1851,7 +2241,17 @@ function locatePackageDir(appDir, pkgName) {
   return null;
 }
 
-const RELOAD_CLIENT_JS = `// webjs dev reload client
-const es = new EventSource('/__webjs/events');
+/**
+ * The dev live-reload client. The `EventSource` URL is a framework-emitted
+ * same-origin path, so it must carry the base path under a sub-path deploy
+ * (#256), like the importmap targets and the RPC stub. No-op when basePath
+ * is empty.
+ * @param {string} bp the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+function reloadClientJs(bp) {
+  return `// webjs dev reload client
+const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
 es.addEventListener('reload', () => location.reload());
 `;
+}