@webjsdev/server 0.8.11 → 0.8.13

package/src/sitemap.js

@@ -0,0 +1,161 @@
+/**
+ * Sitemap helpers (issue #276). Two pure functions that turn an array of
+ * entries into spec-valid XML, so an author of `app/sitemap.{js,ts}` does not
+ * hand-roll the `<urlset>` string (escaping URLs, formatting lastmod dates) and
+ * has a built-in path to shard a large site via a `<sitemapindex>`.
+ *
+ * Both are OPTIONAL and tiny. The dev server serves a STRING returned from a
+ * `sitemap.{js,ts}` default export as `application/xml`, so the author returns
+ * `sitemap([...])` from that function. They can still return a raw Response or a
+ * hand-built string, so this is thin XML serialization, not a sitemap framework.
+ *
+ * Reference: the sitemaps.org 0.9 protocol; Next.js `sitemap.ts` (a typed array
+ * serialized to XML) and `generateSitemaps()` (the index for sharding).
+ */
+
+/** Per-URL entry for {@link sitemap}.
+ * @typedef {object} SitemapEntry
+ * @property {string} url Absolute URL (REQUIRED). XML-escaped on emit.
+ * @property {string|Date} [lastModified] Last-modified time, formatted as W3C
+ *   datetime (ISO 8601). A Date is `toISOString()`'d; a string passes through.
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'} [changeFrequency]
+ *   How often the page changes. An invalid value is dropped (not emitted).
+ * @property {number} [priority] Priority 0.0..1.0. Out-of-range / non-numeric
+ *   is dropped.
+ */
+
+/** Child-sitemap entry for {@link sitemapIndex}.
+ * @typedef {object} SitemapIndexEntry
+ * @property {string} url Absolute URL of a child sitemap (REQUIRED).
+ * @property {string|Date} [lastModified] Last-modified time (W3C datetime).
+ */
+
+const VALID_CHANGEFREQ = new Set([
+  'always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never',
+]);
+
+const MAX_URLS = 50000;
+
+/**
+ * XML-escape text destined for an element body. This is the security-critical
+ * part: a url derived from author data or a DB can contain `&` or `<`, which
+ * would break the XML document or allow injection if emitted raw. The five
+ * predefined XML entities are replaced (`&` first, so the entities the other
+ * replacements introduce are not double-escaped).
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeXml(value) {
+  return String(value)
+    // Strip the C0 control characters XML 1.0 forbids (everything below 0x20
+    // except tab, newline, and carriage return). A stray one from a corrupt
+    // DB-derived URL would otherwise make the WHOLE sitemap document invalid
+    // and silently rejected by search engines, the exact failure this helper
+    // exists to prevent. Done before entity-escaping so it cannot interfere.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Format a `lastModified` value as a W3C datetime (ISO 8601) string. A Date
+ * becomes its `toISOString()`; a non-empty string passes through verbatim (the
+ * spec accepts both `YYYY-MM-DD` and a full timestamp). Anything else yields
+ * null so the `<lastmod>` element is omitted rather than emitted broken.
+ * @param {string|Date|undefined} value
+ * @returns {string|null}
+ */
+function formatLastmod(value) {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) return null;
+    return value.toISOString();
+  }
+  if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  return null;
+}
+
+/**
+ * Validate + format a `priority` to one decimal in the 0.0..1.0 range. Returns
+ * null (so the element is dropped) for a non-number or an out-of-range value.
+ * @param {number|undefined} value
+ * @returns {string|null}
+ */
+function formatPriority(value) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return null;
+  if (value < 0 || value > 1) return null;
+  return value.toFixed(1);
+}
+
+/**
+ * Serialize an array of {@link SitemapEntry} into a complete `<urlset>` XML
+ * document. Element order per the protocol is loc, lastmod, changefreq,
+ * priority. A malformed entry (missing / non-string / empty `url`) is skipped so
+ * it cannot produce broken XML. Output is deterministic.
+ * @param {SitemapEntry[]} entries
+ * @returns {string} a `<?xml ?>` + `<urlset>` document
+ */
+export function sitemap(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length > MAX_URLS) {
+    console.warn(
+      `[webjs] sitemap() received ${list.length} URLs, over the ${MAX_URLS} per-file limit. ` +
+      'Shard the site with sitemapIndex() instead. Emitting all URLs anyway.'
+    );
+  }
+  const urls = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemap(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    if (typeof entry.changeFrequency === 'string' && VALID_CHANGEFREQ.has(entry.changeFrequency)) {
+      parts.push(`    <changefreq>${entry.changeFrequency}</changefreq>`);
+    }
+    const priority = formatPriority(entry.priority);
+    if (priority !== null) parts.push(`    <priority>${priority}</priority>`);
+    urls.push(`  <url>\n${parts.join('\n')}\n  </url>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (urls.length ? urls.join('\n') + '\n' : '') +
+    '</urlset>\n'
+  );
+}
+
+/**
+ * Serialize an array of {@link SitemapIndexEntry} into a `<sitemapindex>` XML
+ * document, one `<sitemap>` per child sitemap URL. Same escaping + lastmod rules
+ * and same skip-malformed-entry behavior as {@link sitemap}. Use it from the
+ * root `app/sitemap.{js,ts}` to point at sharded child sitemaps served by
+ * `route.{js,ts}` handlers.
+ * @param {SitemapIndexEntry[]} sitemaps
+ * @returns {string} a `<?xml ?>` + `<sitemapindex>` document
+ */
+export function sitemapIndex(sitemaps) {
+  const list = Array.isArray(sitemaps) ? sitemaps : [];
+  const items = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemapIndex(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    items.push(`  <sitemap>\n${parts.join('\n')}\n  </sitemap>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (items.length ? items.join('\n') + '\n' : '') +
+    '</sitemapindex>\n'
+  );
+}

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