@webjsdev/server 0.8.11 → 0.8.12

package/src/ssr.js

@@ -1,7 +1,8 @@
 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';
@@ -776,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+'"]');` +
@@ -803,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
@@ -1036,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
@@ -1056,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}>`,
     );
   }
@@ -1168,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>
@@ -1424,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/webjs-config.schema.json

@@ -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
+    }
+  }
+}