@webjsdev/server 0.8.39 → 0.8.40

package/src/rate-limit.js

@@ -89,13 +89,68 @@ export function rateLimit(opts = {}) {
  */
 const REMOTE_IP_HEADER = 'x-webjs-remote-ip';
 
+/**
+ * Out-of-band trusted remote IP (#756). A listener shell that already holds the
+ * socket IP can stamp it here instead of reallocating a whole `Request` just to
+ * set the `x-webjs-remote-ip` header (the Bun hot path). When an entry exists
+ * for a request it is AUTHORITATIVE: `trustedRemoteIp` returns it and ignores
+ * the inbound header entirely, so a client-spoofed `x-webjs-remote-ip` is never
+ * trusted even though the original (unmodified) request still carries it.
+ * @type {WeakMap<Request, string>}
+ */
+const trustedIpMap = new WeakMap();
+
+/**
+ * Stamp the trusted remote IP for a request out-of-band (no Request clone).
+ * Pass `''` (or a falsy value) to mark the request as listener-stamped with no
+ * known IP, which still makes the inbound header untrusted (resolves to the
+ * anon fallback rather than a spoofable header value).
+ * @param {Request} req
+ * @param {string | null | undefined} ip
+ */
+export function setTrustedRemoteIp(req, ip) {
+  trustedIpMap.set(req, ip || '');
+}
+
+/**
+ * The framework-trusted remote IP for a request: the out-of-band WeakMap value
+ * when a listener stamped it (authoritative, header ignored), else the
+ * framework-stamped `x-webjs-remote-ip` header (the node / embedded path).
+ * @param {Request} req
+ * @returns {string}
+ */
+function trustedRemoteIp(req) {
+  if (trustedIpMap.has(req)) return trustedIpMap.get(req) || '';
+  return req.headers.get(REMOTE_IP_HEADER) || '';
+}
+
+/**
+ * Carry the trusted remote IP from `src` to a freshly-rebuilt `dst` Request
+ * (#756). When the framework re-wraps a request (the page-action body rebuild in
+ * `page-action.js`), the out-of-band WeakMap key is a new object, so the trusted
+ * IP would be lost and `clientIp(dst)` would fall back to the (spoofable) header
+ * the rebuild copied over. Propagating the trusted value via the WeakMap keeps
+ * `dst` authoritative on BOTH runtimes (it reads `trustedRemoteIp(src)`, which is
+ * the WeakMap value on Bun and the framework-stamped header on Node). The caller
+ * must ALSO strip the inbound `x-webjs-remote-ip` header from `dst` so a client
+ * copy can never win. Idempotent and safe to call on any rebuild.
+ * @param {Request} src
+ * @param {Request} dst
+ */
+export function propagateTrustedRemoteIp(src, dst) {
+  setTrustedRemoteIp(dst, trustedRemoteIp(src));
+}
+
 /**
  * Resolve the client IP for rate-limit bucket keying.
  *
  * `trustProxy: false` (default, safe everywhere): read ONLY the
- * framework-stamped `x-webjs-remote-ip` header. Under `startServer`
- * the framework derives it from the actual TCP socket and strips
- * any inbound copy via `toWebRequest`, so clients cannot spoof it.
+ * framework-trusted remote IP. Under `startServer` the framework derives it from
+ * the actual TCP socket: the node shell stamps the `x-webjs-remote-ip` header
+ * (stripping any inbound copy via `toWebRequest`), and the Bun shell stamps it
+ * OUT OF BAND via `setTrustedRemoteIp` (a WeakMap, no per-request Request clone,
+ * #756) which `trustedRemoteIp` reads in preference to (and to the exclusion of)
+ * the header, so a client cannot spoof it either way.
  * Under `createRequestHandler` (embedded use) the host adapter MUST
  * call `stampRemoteIp(req, remoteAddress)` first, otherwise the
  * adapter may pass forged inbound headers straight through and the
@@ -122,11 +177,11 @@ export function clientIp(req, opts = {}) {
       req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
       req.headers.get('cf-connecting-ip') ||
       req.headers.get('x-real-ip') ||
-      req.headers.get(REMOTE_IP_HEADER) ||
+      trustedRemoteIp(req) ||
       '_anon_'
     );
   }
-  return req.headers.get(REMOTE_IP_HEADER) || '_anon_';
+  return trustedRemoteIp(req) || '_anon_';
 }
 
 /**

package/src/router.js

@@ -158,7 +158,7 @@ export async function buildRouteTable(appDir) {
     a.middlewares = chainDirs.map((d) => middlewares.get(d)).filter(Boolean);
   }
 
-  pages.sort((a, b) => dynScore(a) - dynScore(b));
+  pages.sort(compareSpecificity);
   return { pages, apis, notFound, notFounds, metadataRoutes, appDir };
 }
 
@@ -191,11 +191,68 @@ function isUrlSegment(seg) {
   return true;
 }
 
-/** @param {PageRoute} r */
-function dynScore(r) {
-  if (r.isCatchAll) return 3;
-  if (r.paramNames.length) return 2;
-  return 1;
+/**
+ * Per-URL-segment specificity kind: 0 = static literal, 1 = dynamic `[x]`,
+ * 2 = catch-all `[...x]` / `[[...x]]`. Lower is MORE specific. Checks the
+ * catch-all forms before the bare `[` (a `[[...x]]` also starts with `[`).
+ * @param {string} seg
+ * @returns {0 | 1 | 2}
+ */
+function segKind(seg) {
+  if (seg.startsWith('[[...') || seg.startsWith('[...')) return 2;
+  if (seg.startsWith('[') && seg.endsWith(']')) return 1;
+  return 0;
+}
+
+/**
+ * The ordered URL segments of a route (route groups + private folders removed),
+ * which is the basis for positional specificity.
+ * @param {string} routeDir
+ * @returns {string[]}
+ */
+function urlSegmentsOf(routeDir) {
+  return (routeDir === '.' ? [] : routeDir.split('/')).filter(isUrlSegment);
+}
+
+/**
+ * Deterministic route specificity ordering (#750). Replaces the old coarse
+ * 3-bucket score (static=1 / dynamic=2 / catch-all=3) whose same-bucket ties
+ * resolved by filesystem walk order, so two overlapping dynamic routes
+ * (`/[org]/[repo]` vs `/[user]/settings`) could match the WRONG page depending
+ * on traversal order. Specificity is fully POSITIONAL, like Next.js's router:
+ * compare segment by segment, and the catch-all kind is just the lowest-priority
+ * kind AT ITS POSITION, NOT a global "always last" bucket. The contract, most
+ * specific first:
+ *   1. Compare segment by segment: at the same position a static literal (kind 0)
+ *      outranks a dynamic `[x]` (kind 1), which outranks a catch-all
+ *      `[...x]` / `[[...x]]` (kind 2). So `/[user]/settings` beats `/[org]/[repo]`
+ *      (static tail wins), AND `/docs/[[...slug]]` beats `/[org]/[repo]` (a
+ *      literal first segment outranks a dynamic one, even though the former ends
+ *      in a catch-all). A global catch-all-last rule would wrongly shadow the
+ *      literal-prefixed catch-all behind every all-dynamic route.
+ *   2. With an identical kind prefix, the SHORTER (prefix) route ranks first, so
+ *      an explicit `/docs` beats the optional-catch-all base `/docs/[[...slug]]`
+ *      for `/docs` (the optional catch-all also matches zero trailing segments,
+ *      so the shorter exact route is the more specific match). Standard
+ *      lexicographic order on the kind arrays.
+ *   3. A genuine tie (identical kinds + length, e.g. `/[a]/[b]` vs `/[c]/[d]`)
+ *      resolves by an alphabetical `routeDir` key, NOT walk order, so the match
+ *      is deterministic across environments.
+ *
+ * The result is a valid total order (lexicographic on kind arrays with a unique
+ * final tiebreak), so `Array.sort` is correct and deterministic regardless of
+ * the filesystem traversal order.
+ * @param {PageRoute} a
+ * @param {PageRoute} b
+ * @returns {number}
+ */
+export function compareSpecificity(a, b) {
+  const sa = urlSegmentsOf(a.routeDir).map(segKind);
+  const sb = urlSegmentsOf(b.routeDir).map(segKind);
+  const n = Math.min(sa.length, sb.length);
+  for (let i = 0; i < n; i++) if (sa[i] !== sb[i]) return sa[i] - sb[i];
+  if (sa.length !== sb.length) return sa.length - sb.length; // shorter (prefix) first
+  return a.routeDir < b.routeDir ? -1 : a.routeDir > b.routeDir ? 1 : 0;
 }
 
 /**

package/src/ssr.js

@@ -1,11 +1,11 @@
 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, basePath, vendorPreconnectOrigins } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
-import { transitiveDeps } from './module-graph.js';
+import { transitiveDeps, bareImports } from './module-graph.js';
 import { seedingEnabled, collectSeeds, buildSeedScript } from './action-seed.js';
 import { BUFFERED_MARKER, STREAM_MARKER } from './conditional-get.js';
 import {
@@ -189,6 +189,26 @@ export async function ssrPage(route, params, url, opts) {
       opts.serverFiles,
       opts.elidableComponents,
     );
+    // Vendor modulepreload (#754): flatten the npm CDN waterfall by hinting the
+    // vendor URLs the page's SHIPPED modules actually import, fetched in parallel
+    // instead of discovered level by level. The walk roots are the BOOT's shipped
+    // module set (`moduleUrls`, which already drops inert page/layout modules and
+    // substitutes an import-only page with its components) plus the rendered
+    // components, so a vendor reached ONLY through a dropped module (a page's
+    // SSR-only direct import OR its SSR-only relative helper) is never preloaded
+    // (no over-fetch).
+    const shippedRoots = moduleUrls.map((u) =>
+      resolve(opts.appDir, u.startsWith('/') ? u.slice(1) : u));
+    const vendorPreloads = vendorPreloadTargets(
+      reachedVendorSpecifiers(
+        opts.moduleGraph,
+        shippedRoots,
+        eagerComponents,
+        opts.appDir,
+        opts.elidableComponents,
+        opts.serverFiles,
+      ),
+    );
     // Extract CSP nonce from request headers (if present).
     const nonce = opts.req ? getNonce(opts.req) : undefined;
     const wrapOpts = {
@@ -197,6 +217,7 @@ export async function ssrPage(route, params, url, opts) {
       dev: opts.dev,
       streaming: suspenseCtx.pending.length > 0,
       preloads,
+      vendorPreloads,
       lazyComponents,
       nonce,
     };
@@ -1232,6 +1253,26 @@ function wrapHead(opts) {
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
+  // Vendor modulepreload (#754): the npm CDN dependencies the page reaches,
+  // hinted up front to flatten the cross-origin waterfall. The href comes
+  // straight from the importmap target (byte-identical, no `fp()` rewrite, so
+  // the browser does not double-fetch) and carries the importmap's `integrity`.
+  // `preloadCrossOriginAttr` adds `crossorigin` for a cross-origin CDN url (a
+  // same-origin pinned `/__webjs/vendor/*` url gets none). Deduped against the
+  // app module/component preloads already emitted above.
+  const emittedPreloadHrefs = new Set([
+    ...opts.moduleUrls.map((u) => fp(u)),
+    ...(opts.preloads || []).map((u) => fp(u)),
+  ]);
+  for (const v of opts.vendorPreloads || []) {
+    if (emittedPreloadHrefs.has(v.href)) continue;
+    emittedPreloadHrefs.add(v.href);
+    const integrity = v.integrity ? ` integrity="${escapeAttr(v.integrity)}"` : '';
+    linkTags.push(
+      `<link rel="modulepreload" href="${escapeAttr(v.href)}"` +
+      `${preloadCrossOriginAttr(v.href)}${integrity}${noncePreload}>`,
+    );
+  }
   if (Array.isArray(m.preload)) {
     for (const p of m.preload) {
       if (!p || !p.href) continue;
@@ -1493,6 +1534,63 @@ function deduplicatedPreloads(componentUrls, moduleUrls, graph, entryFiles, appD
   return result;
 }
 
+/**
+ * Collect the bare npm vendor specifiers the page's SHIPPED modules import
+ * (#754). The walk ROOTS are the boot's actually-shipped module set: the caller
+ * passes `entryFiles` = the absolute paths of `moduleUrls` (which already drops
+ * inert page/layout modules and substitutes an import-only page with its
+ * components), plus `componentUrls` = the rendered components. From those roots
+ * it walks the transitive app-graph closure (elidable components and the subtree
+ * reachable only through them excluded), and collects each reached file's bare
+ * imports, excluding server files. The specifiers are resolved to `modulepreload`
+ * targets via the vendor importmap; a specifier not in the map (unpinned /
+ * unreached) drops out there.
+ *
+ * Because the roots are the SHIPPED set, a vendor reached ONLY through a module
+ * dropped from the boot, whether a dropped page's SSR-only DIRECT vendor import
+ * or its SSR-only RELATIVE HELPER's vendor, is never collected: the dropped
+ * module is not a root, and nothing that ships imports it (pages/layouts are not
+ * importable). So the canonical SSR-only-dependency pattern (which elision keeps
+ * off the client) is never preloaded (no over-fetch).
+ *
+ * @param {import('./module-graph.js').ModuleGraph | undefined} graph
+ * @param {string[]} entryFiles  absolute paths of the SHIPPED page/layout modules (from `moduleUrls`)
+ * @param {string[]} componentUrls  rendered eager component URL paths
+ * @param {string} appDir
+ * @param {Set<string>} [elidableComponents]
+ * @param {Set<string>} [serverFiles]  the action / server-file index (`'use server'`, incl. no-`.server.` files)
+ * @returns {Set<string>}
+ */
+function reachedVendorSpecifiers(graph, entryFiles, componentUrls, appDir, elidableComponents, serverFiles) {
+  /** @type {Set<string>} */
+  const specs = new Set();
+  if (!graph) return specs;
+  const bare = bareImports(graph);
+  if (!bare.size) return specs;
+  // Roots = the SHIPPED page/layout modules (already inert-dropped + import-only
+  // expanded by the caller) + the rendered components, keyed by the graph's own
+  // absolute paths. Walk their non-elided transitive closure.
+  const allEntries = [...entryFiles];
+  for (const url of componentUrls) {
+    allEntries.push(resolve(appDir, url.startsWith('/') ? url.slice(1) : url));
+  }
+  const files = new Set(allEntries);
+  for (const dep of transitiveDeps(graph, allEntries, appDir, elidableComponents)) files.add(dep);
+  for (const file of files) {
+    // A server file is never served to the browser (its source is an RPC /
+    // throw-at-load stub), so a vendor it imports never ships and must NOT be
+    // preloaded. `transitiveDeps` stops AT a server-file boundary but still
+    // returns the boundary file itself, so filter it: the `.server.*` suffix
+    // AND the action index (a `'use server'` file without the suffix), matching
+    // `deduplicatedPreloads`' `byIndex` filter.
+    if (/\.server\.m?[jt]s$/.test(file)) continue;
+    if (serverFiles && serverFiles.has && serverFiles.has(file)) continue;
+    const fileBare = bare.get(file);
+    if (fileBare) for (const spec of fileBare) specs.add(spec);
+  }
+  return specs;
+}
+
 /**
  * Build a streaming Response. Degrades to a single-flush response when
  * there are no pending Suspense boundaries.

package/src/testing.js

@@ -295,9 +295,13 @@ export async function invokeActionForTest(app, serverFilePath, fnName, args = []
 
   if (!res.ok && throwOnError) {
     const msg = (parsed && parsed.error) || `webjs action ${fnName} -> ${res.status}`;
-    const err = /** @type {Error & { status?: number, response?: Response }} */ (new Error(msg));
+    const err = /** @type {Error & { status?: number, response?: Response, digest?: string }} */ (new Error(msg));
     err.status = res.status;
     err.response = res;
+    // Prod sanitization (#749) returns a generic message + a correlation digest;
+    // surface the digest on the thrown error so a test (or a caller) can map it
+    // to the server log line, mirroring the generated client stub.
+    if (parsed && parsed.digest) err.digest = parsed.digest;
     throw err;
   }
   return parsed;