npm - @webjsdev/server - Versions diffs - 0.8.10 → 0.8.12 - Mend

@webjsdev/server 0.8.10 → 0.8.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/index.js +4 -1
package/package.json +4 -2
package/src/actions.js +21 -3
package/src/auth.js +8 -1
package/src/base-path.js +149 -0
package/src/build-info.js +59 -0
package/src/cache-fn.js +40 -0
package/src/cache-tags.js +147 -0
package/src/conditional-get.js +183 -0
package/src/context.js +74 -1
package/src/dev.js +449 -49
package/src/html-cache.js +305 -0
package/src/importmap.js +54 -3
package/src/redirects.js +389 -0
package/src/route-types.js +176 -0
package/src/session.js +4 -0
package/src/ssr.js +210 -9
package/src/vendor.js +9 -6
package/webjs-config.schema.json +147 -0

package/src/ssr.js CHANGED Viewed

@@ -1,10 +1,17 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, publishedBuildId } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
+import { BUFFERED_MARKER, STREAM_MARKER } from './conditional-get.js';
+import {
+  readRevalidate,
+  readHtmlCache,
+  HTML_CACHE_MARKER,
+} from './html-cache.js';
 /**
  * SSR a matched page route to a Response.
@@ -20,10 +27,43 @@ import { transitiveDeps } from './module-graph.js';
  * @param {import('./router.js').PageRoute} route
  * @param {Record<string,string>} params
  * @param {URL} url
- * @param {{ dev: boolean, appDir: string, req?: Request, moduleGraph?: import('./module-graph.js').ModuleGraph, serverFiles?: Map<string,string> | Set<string>, actionData?: unknown, status?: number, pageModule?: Record<string, unknown> }} opts
+ * @param {{ dev: boolean, appDir: string, req?: Request, moduleGraph?: import('./module-graph.js').ModuleGraph, serverFiles?: Map<string,string> | Set<string>, actionData?: unknown, status?: number, pageModule?: Record<string, unknown>, cspEnabled?: boolean }} opts
  * @returns {Promise<Response>}
  */
 export async function ssrPage(route, params, url, opts) {
+  // Server HTML response cache (ISR for no-build, #241). OPT-IN: only a page
+  // that declares `export const revalidate = N` is ever cached (the page
+  // module export is the single trigger). The page module is loaded ONCE up
+  // front to read that window
+  // and is threaded back through `opts.pageModule` so renderChain reuses the
+  // same evaluation (no double-load). A cache HIT serves the stored HTML
+  // without re-running the page function. Skipped entirely (no opt-in read,
+  // no double behaviour) for the page-action re-render (actionData / a non-200
+  // status) and for a partial-nav request (X-Webjs-Have), whose bytes depend
+  // on the request and must not be shared under the full-URL key.
+  const cacheEligible =
+    !opts.actionData &&
+    !opts.status &&
+    !opts.pageModule &&
+    !(opts.req && opts.req.headers.get('x-webjs-have'));
+  let revalidateSeconds = null;
+  if (cacheEligible) {
+    try {
+      const pageMod = await loadModule(route.file, opts.dev);
+      opts = { ...opts, pageModule: pageMod };
+      revalidateSeconds = readRevalidate(pageMod);
+      if (revalidateSeconds !== null) {
+        const hit = await readHtmlCache(url);
+        if (hit) return cachedHtmlResponse(hit, opts.req, url);
+      }
+    } catch {
+      // A load / store failure falls through to a normal fresh render: the
+      // cache is an optimization, never a correctness dependency. Leave
+      // revalidateSeconds as read so the write path still applies when the
+      // page loaded but only the store lookup failed.
+    }
+  }
   const ctx = {
     params,
     searchParams: Object.fromEntries(url.searchParams.entries()),
@@ -103,7 +143,7 @@ export async function ssrPage(route, params, url, opts) {
     // shell. Either way the returned `prefix` ends just past the open <body>
     // and `closer` is the matching `</body></html>`.
     const { prefix, streamBody, closer } = buildDocumentParts(body, wrapOpts);
-    return streamingHtmlResponse(
+    const res = streamingHtmlResponse(
       prefix,
       streamBody,
       closer,
@@ -117,6 +157,17 @@ export async function ssrPage(route, params, url, opts) {
       metadata,
       nonce,
     );
+    // Server HTML cache write (#241). The page opted in via `revalidate`, so
+    // FLAG this candidate for the response funnel rather than writing here: the
+    // store decision must see the FINAL response (after segment middleware,
+    // which may append a per-user Set-Cookie this code can't see yet). The
+    // funnel re-checks every guard via isCacheableResponse, writes the cache,
+    // and strips this internal marker. The CSP guard is decided here (the SSR
+    // side knows whether a nonce was stamped into the body).
+    if (revalidateSeconds !== null && !opts.cspEnabled) {
+      res.headers.set(HTML_CACHE_MARKER, String(revalidateSeconds));
+    }
+    return res;
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
@@ -126,6 +177,15 @@ export async function ssrPage(route, params, url, opts) {
       const html = await ssrNotFoundHtml(null, opts);
       return htmlResponse(html, 404, opts.req, url);
     }
+    // APM / Sentry sink (issue #239): a page render error that becomes a 500
+    // (an error.js boundary OR the default 500 page) is an unhandled error the
+    // app should see in its error tracker. Report it best-effort BEFORE
+    // rendering the boundary, so the sink gets the ORIGINAL error even if the
+    // boundary itself swallows or transforms it. notFound / redirect are
+    // sentinels (control flow), not errors, so they are excluded above.
+    if (typeof opts.onError === 'function') {
+      try { opts.onError(err); } catch { /* a throwing sink must not affect the response */ }
+    }
     // Error paths still need to honor the request's CSP nonce so the
     // error page's boot scripts (when moduleUrls is non-empty) and
     // the meta csp-nonce tag both pass strict-CSP enforcement.
@@ -194,9 +254,41 @@ function htmlResponse(html, status, req, url, metadata) {
     const secure = url ? url.protocol === 'https:' : false;
     headers.append('set-cookie', cookieHeader(newToken(), { secure }));
   }
+  // Buffered (string) body: opt into the conditional-GET funnel so a
+  // PUBLIC-cacheable page (metadata.cacheControl) gets a weak ETag + 304.
+  // The funnel still excludes the no-store default, so a private page is
+  // never ETagged. See conditional-get.js.
+  headers.set(BUFFERED_MARKER, '1');
   return new Response(html, { status, headers });
 }
+/**
+ * Rebuild a Response from a cached HTML record (#241). The stored body is
+ * the stable per-page HTML; the per-response varying bits are re-minted
+ * here so a new visitor still gets them: the CSRF cookie is freshly issued
+ * when the request lacks one (it is a Set-Cookie header, never part of the
+ * cached body), and the published build id is re-read so a post-deploy
+ * client sees the current id. The BUFFERED marker opts the cached body into
+ * the conditional-GET funnel exactly as a fresh render does, so a cached
+ * PUBLIC-cacheable page still 304s. Output is observably identical to the
+ * fresh render of the same route within the window.
+ *
+ * @param {{ body: string, contentType: string, cacheControl: string, status: number }} rec
+ * @param {Request | undefined} req
+ * @param {URL | undefined} url
+ */
+function cachedHtmlResponse(rec, req, url) {
+  const headers = new Headers({ 'content-type': rec.contentType });
+  headers.set('cache-control', rec.cacheControl);
+  headers.set('x-webjs-build', publishedBuildId());
+  if (req && !readToken(req)) {
+    const secure = url ? url.protocol === 'https:' : false;
+    headers.append('set-cookie', cookieHeader(newToken(), { secure }));
+  }
+  headers.set(BUFFERED_MARKER, '1');
+  return new Response(rec.body, { status: rec.status, headers });
+}
 /* ------------ internals ------------ */
 async function ssrNotFoundHtml(notFoundFile, opts) {
@@ -685,15 +777,36 @@ function wrapHead(opts) {
   // the request's CSP header by the caller.
   const n = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
-  const imports = opts.moduleUrls.map((u) => `import ${jsonForScriptTag(u)};`).join('\n');
-  const lazyEntries = opts.lazyComponents && Object.keys(opts.lazyComponents).length
+  // Sub-path deployment (issue #256): the boot script's per-route module
+  // specifiers and the dev reload `src` are framework-emitted same-origin
+  // absolute URLs, so prefix them with the base path (a no-op when empty).
+  // The lazy-loader import is a BARE specifier resolved through the importmap
+  // (whose target is already base-path-prefixed in importmap.js), so it is
+  // NOT prefixed here. The base path is the one set at boot via setBasePath
+  // (read from importmap.js's module state), the same value the importmap
+  // targets were prefixed with, so the boot specifiers and the map agree.
+  const bp = basePath();
+  const imports = opts.moduleUrls
+    .map((u) => `import ${jsonForScriptTag(withBasePath(u, bp))};`)
+    .join('\n');
+  const rawLazyEntries = opts.lazyComponents && Object.keys(opts.lazyComponents).length
     ? opts.lazyComponents
     : null;
+  // The lazy map's values are same-origin module URLs `observeLazy` will
+  // dynamically import, so prefix them with the base path too (no-op when
+  // empty).
+  const lazyEntries = rawLazyEntries && bp
+    ? Object.fromEntries(
+        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, withBasePath(u, bp)]),
+      )
+    : rawLazyEntries;
   const lazyBoot = lazyEntries
     ? `\nimport { observeLazy } from '@webjsdev/core/lazy-loader';\nobserveLazy(${jsonForScriptTag(lazyEntries)});`
     : '';
   const boot = (imports || lazyBoot) ? `<script type="module"${n}>\n${imports}${lazyBoot}\n</script>` : '';
-  const reload = opts.dev ? `<script type="module"${n} src="/__webjs/reload.js"></script>` : '';
+  const reload = opts.dev
+    ? `<script type="module"${n} src="${escapeAttr(withBasePath('/__webjs/reload.js', bp))}"></script>`
+    : '';
   const suspenseBoot = opts.streaming
     ? `<script${n}>(function(){` +
       `function r(id){var t=document.querySelector('template[data-webjs-resolve="'+id+'"]');` +
@@ -712,6 +825,8 @@ function wrapHead(opts) {
   // alternates, archives, etc.) AND by the preload block further down.
   // Hoist the declaration so the metadata block can push into it.
   const linkTags = [];
+  // scriptTags collects JSON-LD structured-data blocks (see m.jsonLd below).
+  const scriptTags = [];
   // Tiny URL resolver against metadataBase. If metadataBase is set and a
   // value looks like a relative URL (no scheme, no `//` prefix), resolve
@@ -945,6 +1060,23 @@ function wrapHead(opts) {
     }
   }
+  // JSON-LD structured data (schema.org). `m.jsonLd` is a single object
+  // OR an array of objects. The author owns the schema.org shape; the
+  // framework only serializes and HTML-safe-escapes each object into a
+  // `<script type="application/ld+json">` block. A single object emits
+  // ONE script; an array emits one script PER element.
+  //
+  // The block is a NON-EXECUTABLE data island (type application/ld+json),
+  // so CSP script-src does not gate it and it carries NO nonce. Adding one
+  // would wrongly imply it is executable script.
+  if (m.jsonLd != null) {
+    const list = Array.isArray(m.jsonLd) ? m.jsonLd : [m.jsonLd];
+    for (const obj of list) {
+      const tag = jsonLdScript(obj);
+      if (tag) scriptTags.push(tag);
+    }
+  }
   // Preload hints: page modules themselves + every discovered component
   // module, then any custom `metadata.preload` entries (fonts, images, etc.)
   // (linkTags array was declared earlier so the metadata block above can
@@ -965,15 +1097,21 @@ function wrapHead(opts) {
   // importmap-rails) applies nonce on every modulepreload tag for
   // the same reason.
   const noncePreload = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  // Sub-path deployment (issue #256): the modulepreload href is prefixed with
+  // the base path (a no-op when empty), but `crossorigin` / `integrity` are
+  // decided on the ORIGINAL url, so the integrity lookup still keys on the
+  // unprefixed map url and a cross-origin CDN url (never prefixed) keeps its
+  // crossorigin attribute.
+  const bpPreload = basePath();
   for (const url of opts.moduleUrls) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(url)}"` +
+      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
   for (const url of opts.preloads || []) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(url)}"` +
+      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
@@ -1077,7 +1215,7 @@ ${metaTags.join('\n')}
 ${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}
 ${importMapTag({ nonce: opts.nonce })}
 ${linkTags.join('\n')}
-${boot}
+${scriptTags.length ? scriptTags.join('\n') + '\n' : ''}${boot}
 ${reload}
 ${suspenseBoot}
 </head>
@@ -1213,9 +1351,18 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   }
   if (!ctx.pending.length) {
+    // No pending boundaries: this degrades to a single buffered (string)
+    // flush, so opt it into the conditional-GET funnel like htmlResponse.
+    headers.set(BUFFERED_MARKER, '1');
     return new Response(prefix + bodyHtml + closer, { status, headers });
   }
+  // Flag a genuinely streamed body so the conditional-GET funnel skips it
+  // (an unflushed stream cannot be hashed without buffering, which would
+  // defeat streaming). The marker is internal and stripped at the funnel
+  // before the response reaches the client. See conditional-get.js.
+  headers.set(STREAM_MARKER, '1');
   const stream = new ReadableStream({
     async start(controller) {
       controller.enqueue(encoder.encode(prefix + bodyHtml));
@@ -1324,6 +1471,60 @@ function escapeAttr(s) {
   return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
 }
+/**
+ * HTML-safe-escape a JSON string for embedding inside a
+ * `<script type="application/ld+json">` element.
+ *
+ * This is NOT the HTML-entity escaper (escapeHtml / escapeAttr). A
+ * JSON parser reads the raw character, so turning `<` into `&lt;`
+ * would CORRUPT the JSON. Instead we emit the Unicode escape form
+ * (`<`), which a JSON parser decodes back to the original
+ * character while making the literal byte sequence `</script>`
+ * impossible to form in the served HTML. So the embedded data parses
+ * back to the author's exact object, AND a value containing
+ * `</script><img onerror=...>` can never break out of the script tag.
+ *
+ * U+2028 / U+2029 are escaped too: they are valid inside a JSON
+ * string but are line terminators in HTML/JS contexts, and some
+ * consumers choke on them. Escaping keeps the block robust.
+ *
+ * @param {string} json  the `JSON.stringify` output
+ * @returns {string}
+ */
+function escapeJsonLd(json) {
+  return json
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+/**
+ * Serialize one schema.org object into a `<script type="application/ld+json">`
+ * block, HTML-safe-escaped via escapeJsonLd. Fails SAFE: a non-object
+ * input, or a circular reference that makes JSON.stringify throw, is
+ * skipped (returns the empty string) with a one-line warn, never breaking
+ * the whole render.
+ *
+ * @param {unknown} obj
+ * @returns {string}  the script tag, or '' to skip this element
+ */
+function jsonLdScript(obj) {
+  if (!obj || typeof obj !== 'object') return '';
+  try {
+    const json = JSON.stringify(obj);
+    if (typeof json !== 'string') return '';
+    return `<script type="application/ld+json">${escapeJsonLd(json)}</script>`;
+  } catch (err) {
+    console.warn('[webjs] metadata.jsonLd: skipped an entry that could not be serialized:', err && err.message);
+    return '';
+  }
+}
+// Internal helpers re-exported for unit testing.
+export { escapeJsonLd as _escapeJsonLd, jsonLdScript as _jsonLdScript };
 /**
  * Decide whether a `<link rel="modulepreload">` href needs a
  * `crossorigin="anonymous"` attribute. True for absolute URLs with

package/src/vendor.js CHANGED Viewed

@@ -44,7 +44,8 @@ import { readFile, readdir, writeFile, mkdir, unlink, stat, rename } from 'node:
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { join, dirname, basename, sep } from 'node:path';
 import { createRequire } from 'node:module';
-import { digestBase64, digestHex } from './crypto-utils.js';
+import { digestBase64 } from './crypto-utils.js';
+import { BUFFERED_MARKER } from './conditional-get.js';
 /**
  * Set of package names whose importmap entries are populated by the
@@ -1410,15 +1411,17 @@ export async function serveDownloadedBundle(filename, appDir, dev) {
     // match if any byte didn't round-trip exactly (e.g. invalid
     // surrogate replacement). Keep the I/O binary end-to-end.
     const body = await readFile(join(pinDir(appDir), filename));
-    // ETag for downstream caches that strip the `immutable` directive.
-    // Bundle filenames already carry the version, so content + ETag
-    // round-trip is deterministic per filename.
-    const etag = `"${(await digestHex('SHA-1', body)).slice(0, 16)}"`;
+    // Buffered (bytes) body, so opt into the conditional-GET funnel, which
+    // hashes the bytes into a weak ETag (for downstream caches that strip the
+    // `immutable` directive) and honors If-None-Match -> 304. A WEAK validator
+    // is correct here because compression may re-encode the bytes per request
+    // (RFC 7232 2.3.3); the funnel is the single source for that. See
+    // conditional-get.js.
     return new Response(body, {
       headers: {
         'content-type': 'application/javascript; charset=utf-8',
         'cache-control': dev ? 'no-cache' : 'public, max-age=31536000, immutable',
-        'etag': etag,
+        [BUFFERED_MARKER]: '1',
       },
     });
   } catch {

package/webjs-config.schema.json ADDED Viewed

@@ -0,0 +1,147 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://webjs.dev/schemas/webjs-config.schema.json",
+  "title": "webjs config block",
+  "description": "Schema for the `webjs` object in a webjs app's package.json. Each key maps to a documented server reader. An unknown key is flagged (additionalProperties is false) so a typo no longer silently falls back to the default.",
+  "$comment": "Single source of truth lives in THREE co-located places that must stay in lockstep: this schema, the TS type at packages/core/src/webjs-config.d.ts, and the server reader functions (readElideEnabled in dev.js, compileHeaderRules in headers.js, compileRedirectRules / readTrailingSlashPolicy in redirects.js, readBasePath in base-path.js, readCspConfig in csp.js, readBodyLimits / computeServerTimeouts in body-limit.js). Adding a webjs.* key means updating all three. See packages/server/AGENTS.md for the one documented procedure.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "elide": {
+      "description": "Display-only and inert-route dead-JS elision switch. Default true. Set to false to ship every module's JS app-wide, as before the feature existed. Read by readElideEnabled in dev.js; the WEBJS_ELIDE env override wins over this.",
+      "type": "boolean",
+      "default": true
+    },
+    "headers": {
+      "description": "Per-path response-header rules, shaped like Next's. Each rule pairs a URLPattern source against header directives. Read by compileHeaderRules in headers.js.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "headers"],
+        "properties": {
+          "source": {
+            "description": "Path pattern matched with the native URLPattern API (so :param and :rest* syntax works).",
+            "type": "string"
+          },
+          "headers": {
+            "description": "Header directives applied on a match.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["key"],
+              "properties": {
+                "key": {
+                  "description": "Header name, e.g. X-Frame-Options.",
+                  "type": "string"
+                },
+                "value": {
+                  "description": "Header value. A null or false value REMOVES the header on a match, the escape hatch that drops a secure default on a path. true is intentionally not allowed (it would stringify to the literal 'true').",
+                  "oneOf": [{ "type": ["string", "null"] }, { "const": false }]
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "redirects": {
+      "description": "Declarative permanent / temporary redirects for moved URLs. Compiled once at boot by compileRedirectRules in redirects.js. A malformed entry is dropped with a warning.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "destination"],
+        "properties": {
+          "source": {
+            "description": "Path pattern matched with the native URLPattern API (so :param and :rest* syntax works).",
+            "type": "string"
+          },
+          "destination": {
+            "description": "Target path, a path referencing named groups captured by source, or an absolute URL. The incoming query string is preserved and merged onto the destination.",
+            "type": "string"
+          },
+          "permanent": {
+            "description": "true (the default) is a 308 Permanent Redirect, false is a 307 Temporary Redirect. Both preserve the request method and body. statusCode wins over this when set.",
+            "type": "boolean",
+            "default": true
+          },
+          "statusCode": {
+            "description": "Explicit redirect status, for a tool needing a legacy code. Wins over permanent. One of 301, 302, 303, 307, 308.",
+            "type": "integer",
+            "enum": [301, 302, 303, 307, 308]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "trailingSlash": {
+      "description": "Trailing-slash canonicalization policy. 'never' strips a trailing slash, 'always' adds one (both via a 308 redirect), 'ignore' (the default) does nothing. An unrecognized value is treated as 'ignore'. Read by readTrailingSlashPolicy in redirects.js.",
+      "type": "string",
+      "enum": ["never", "always", "ignore"],
+      "default": "ignore"
+    },
+    "basePath": {
+      "description": "Sub-path deployment prefix for an app mounted under example.com/app/ behind a proxy that does NOT strip the prefix. 'app', '/app', and '/app/' all normalize to '/app'; an empty value (the default) is a root mount and a pure no-op. The prefix is stripped from the incoming path at ingress and prepended to every framework-emitted URL (importmap targets, modulepreload hints, boot module specifiers, the dev reload src). Read by readBasePath in base-path.js. Author-written <a href> links and client-router navigation are NOT auto-prefixed (a documented follow-up).",
+      "type": "string",
+      "default": ""
+    },
+    "csp": {
+      "description": "Content-Security-Policy config. Off by default. true enables a strict nonce-based default policy. An object customizes directives and report-only mode. Read by readCspConfig in csp.js.",
+      "oneOf": [
+        {
+          "description": "true enables the strict default policy, false (or absence) disables CSP.",
+          "type": "boolean"
+        },
+        {
+          "description": "Custom config. directives merges over the strict defaults (a null / false / '' value drops a default directive); reportOnly emits the Content-Security-Policy-Report-Only header. A bare directive map (without a directives key) is also accepted.",
+          "type": "object",
+          "properties": {
+            "directives": {
+              "description": "Directive map merged over the strict defaults, e.g. { \"connect-src\": \"'self' https://api.example.com\" }. A __NONCE__ token in a value is replaced with the per-request nonce.",
+              "type": "object",
+              "additionalProperties": {
+                "type": ["string", "null", "boolean"]
+              }
+            },
+            "reportOnly": {
+              "description": "true emits Content-Security-Policy-Report-Only instead of the enforcing header (the staged-rollout path).",
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      ]
+    },
+    "maxBodyBytes": {
+      "description": "JSON / RPC request body cap in bytes. Default 1048576 (1 MiB). A value of 0 disables the cap. The WEBJS_MAX_BODY_BYTES env override wins. Read by readBodyLimits in body-limit.js.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 1048576
+    },
+    "maxMultipartBytes": {
+      "description": "Form / multipart request body cap in bytes. Default 10485760 (10 MiB). A value of 0 disables the cap. The WEBJS_MAX_MULTIPART_BYTES env override wins. Read by readBodyLimits in body-limit.js.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 10485760
+    },
+    "requestTimeoutMs": {
+      "description": "Max time in ms to receive the ENTIRE request (headers plus body). Default 30000. A value of 0 disables the timeout. The WEBJS_REQUEST_TIMEOUT_MS env override wins. Read by computeServerTimeouts in body-limit.js.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 30000
+    },
+    "headersTimeoutMs": {
+      "description": "Max time in ms to receive just the request headers. Default 20000. Clamped strictly under requestTimeoutMs per node semantics. A value of 0 disables the timeout. The WEBJS_HEADERS_TIMEOUT_MS env override wins. Read by computeServerTimeouts in body-limit.js.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 20000
+    },
+    "keepAliveTimeoutMs": {
+      "description": "Idle time in ms before a kept-alive socket is closed. Default 5000. A value of 0 disables the timeout. The WEBJS_KEEP_ALIVE_TIMEOUT_MS env override wins. Read by computeServerTimeouts in body-limit.js.",
+      "type": "integer",
+      "minimum": 0,
+      "default": 5000
+    }
+  }
+}