@webjsdev/server 0.8.62 → 0.8.64

package/src/form-dispatch.js

@@ -561,13 +561,22 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
       // the SUCCESS-result path below.
       return new Response(null, { status: e.status || 307, headers: { location: e.url } });
     }
+    // `route` and `params` ride along so the boundary renders inside its
+    // layouts, exactly as it does on the page-render path (#1298).
     if (isNotFound(err)) {
-      return ssrNotFound(ssrOpts.notFoundFile ?? null, { ...ssrOpts, req, url });
+      // NEAREST-wins, like the page-render path (#848). `ssrOpts.notFoundFile`
+      // is the ROOT one only, so a nested form action throwing notFound()
+      // rendered the root boundary while the same throw from the page render
+      // rendered the nested one. Two paths, one url, different 404s.
+      const nearestNotFound = route.notFounds && route.notFounds.length
+        ? route.notFounds[route.notFounds.length - 1]
+        : (ssrOpts.notFoundFile ?? null);
+      return ssrNotFound(nearestNotFound, { ...ssrOpts, req, url, route, params });
     }
     // forbidden()/unauthorized() from a form action render the same 403/401
     // boundary as the page-render path (#848), not a generic 500.
-    if (isForbidden(err)) return ssrForbidden(route, { ...ssrOpts, req, url });
-    if (isUnauthorized(err)) return ssrUnauthorized(route, { ...ssrOpts, req, url });
+    if (isForbidden(err)) return ssrForbidden(route, { ...ssrOpts, req, url, route, params });
+    if (isUnauthorized(err)) return ssrUnauthorized(route, { ...ssrOpts, req, url, route, params });
     if (typeof onError === 'function') onError(err);
     return await formActionErrorResponse(err, ssrOpts.dev);
   }

package/src/importmap.js

@@ -6,9 +6,12 @@ import { jsonForScriptTag } from './script-tag-json.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 
-// Local attribute escaper. Matches ssr.js's escapeAttr (the source
-// of truth for HTML attribute escaping in this package). Kept inline
-// to avoid a cross-file dependency for one small helper.
+// Local attribute escaper, byte-identical to the pair in `ssr/escape.js`,
+// which is the source of truth for HTML attribute escaping in this package.
+// Kept inline to avoid a cross-file dependency for one small helper, so the
+// two must stay in step: this one escapes an attribute in the served head
+// (the importmap script's nonce), so a divergence here moves served bytes
+// exactly as a divergence there would.
 function escapeAttr(s) {
   return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
 }

package/src/listener-core.js

@@ -365,8 +365,22 @@ export class SseHub {
     }
   }
 
-  /** Push a live-reload event to every open tab. */
-  reload() { this._raw('event: reload\ndata: now\n\n'); }
+  /**
+   * Push a live-reload event to every open tab.
+   *
+   * The frame carries the change's `{ v, by, why }` classification (#1398) as a
+   * single-line JSON payload, matching `devError` below. The browser relay
+   * resolves ANY payload it cannot read to `reload`, and an absent or malformed
+   * verdict is emitted as `reload` here too, so the fail-safe holds on both ends
+   * of the wire and a tab running against a restarted server can never be
+   * skewed into a lighter response than the change deserves.
+   *
+   * @param {{ v?: string, by?: string, why?: string } | null} [verdict]
+   */
+  reload(verdict) {
+    const v = verdict && typeof verdict.v === 'string' ? verdict : { v: 'reload' };
+    this._raw(`event: reload\ndata: ${JSON.stringify(v)}\n\n`);
+  }
 
   /** Push a dev-error overlay frame (#264) to every open tab. @param {object} frame */
   devError(frame) { this._raw(`event: webjs-error\ndata: ${JSON.stringify(frame)}\n\n`); }

package/src/module-graph.js

@@ -174,6 +174,28 @@ export function bareImports(graph) {
   return BARE_EDGES.get(graph) || new Map();
 }
 
+/**
+ * Bare (npm vendor) specifiers imported DYNAMICALLY (`await import('dayjs')`),
+ * kept apart from `BARE_EDGES` for the same reason `DYNAMIC_EDGES` is kept
+ * apart from the static graph: a lazily-imported vendor must RESOLVE when the
+ * import finally runs, so it belongs in the importmap, but it must not be
+ * preloaded (that would fetch a bundle the author deliberately deferred). So
+ * `reachableBareSpecifiers` (the importmap) unions both maps while
+ * `bareImports` (the #754 modulepreload source) stays static-only.
+ * @type {WeakMap<ModuleGraph, Map<string, Set<string>>>}
+ */
+const BARE_DYNAMIC_EDGES = new WeakMap();
+
+/**
+ * The dynamically-imported bare specifiers per file for a built graph, or an
+ * empty map if none.
+ * @param {ModuleGraph} graph
+ * @returns {Map<string, Set<string>>}
+ */
+export function dynamicBareImports(graph) {
+  return BARE_DYNAMIC_EDGES.get(graph) || new Map();
+}
+
 /**
  * Every app source file walked while building a graph (#899). `graph` itself
  * holds only files that HAVE imports, so a leaf (e.g. a no-import `.server.ts`)
@@ -224,12 +246,16 @@ export async function buildModuleGraph(appDir) {
   const dynamic = new Map();
   /** @type {Map<string, Set<string>>} bare vendor specifiers per file (#754) */
   const bare = new Map();
+  /** @type {Map<string, Set<string>>} DYNAMICALLY-imported bare vendor specifiers
+   * per file: importmap-bound but never preloaded (#1399) */
+  const bareDynamic = new Map();
   /** @type {Set<string>} every file walked this build (graph holds only files
    * with deps, so a separate set is needed to know what is still live). */
   const seen = new Set();
-  await walk(appDir, appDir, graph, seen, dynamic, bare);
+  await walk(appDir, appDir, graph, seen, dynamic, bare, bareDynamic);
   if (dynamic.size) DYNAMIC_EDGES.set(graph, dynamic);
   if (bare.size) BARE_EDGES.set(graph, bare);
+  if (bareDynamic.size) BARE_DYNAMIC_EDGES.set(graph, bareDynamic);
   if (seen.size) SEEN_FILES.set(graph, seen);
   // Evict parse-cache entries for files no longer in the tree (a rebuild after
   // a rename or delete), so a long dev session does not accumulate dead
@@ -374,13 +400,82 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
   return visited;
 }
 
+/**
+ * Bare npm vendor specifiers reachable from `entryFiles`, the importmap
+ * analogue of ssr.js's per-page `reachedVendorSpecifiers` (#754).
+ *
+ * Walks the SAME edges the authorization gate walks (static + dynamic, #751,
+ * stopping at `.server.*` boundaries) so the answer is exactly "what a browser
+ * could load from these entries", then unions each reached file's recorded
+ * bare edges, static AND dynamic. Both dynamic forms are included here even
+ * though `transitiveDeps` (preload) ignores them, for the same reason: a
+ * lazily imported module is not preloaded, but its bare specifier still has to
+ * resolve when the import finally runs, so it belongs in the importmap. That
+ * is why a dynamically-imported VENDOR gets its own map (`dynamicBareImports`)
+ * rather than joining `bareImports`, which feeds the preload hints.
+ *
+ * `.server.*` files are reached (the browser fetches a stub at that URL) but
+ * their bare imports are NOT collected: the source never ships, so a DB driver
+ * imported by a server file must never enter the importmap.
+ *
+ * `skip` files are neither collected nor traversed into, so a specifier
+ * reachable ONLY through an elided component drops out along with the subtree
+ * behind it (#197 / #170). Omit `skip` for the un-pruned superset the pin path
+ * needs.
+ *
+ * @param {ModuleGraph} graph
+ * @param {string[]} entryFiles  absolute paths
+ * @param {string} appDir
+ * @param {Set<string>} [skip]  absolute paths to exclude and not traverse
+ * @returns {Set<string>}
+ */
+export function reachableBareSpecifiers(graph, entryFiles, appDir, skip) {
+  /** @type {Set<string>} */
+  const specs = new Set();
+  const bare = BARE_EDGES.get(graph);
+  const bareDynamic = BARE_DYNAMIC_EDGES.get(graph);
+  if (!bare?.size && !bareDynamic?.size) return specs;
+  const dynamic = DYNAMIC_EDGES.get(graph);
+  /** @type {Set<string>} */
+  const visited = new Set();
+  /** @type {string[]} */
+  const queue = [];
+  for (const entry of entryFiles) {
+    if (!entry || !entry.startsWith(appDir)) continue;
+    if (skip && skip.has(entry)) continue;
+    visited.add(entry);
+    queue.push(entry);
+  }
+  while (queue.length) {
+    const file = /** @type {string} */ (queue.shift());
+    if (SERVER_FILE_RE.test(file)) continue;
+    for (const map of [bare, bareDynamic]) {
+      const fileBare = map?.get(file);
+      if (fileBare) for (const spec of fileBare) specs.add(spec);
+    }
+    const staticDeps = graph.get(file);
+    const dynDeps = dynamic && dynamic.get(file);
+    for (const set of [staticDeps, dynDeps]) {
+      if (!set) continue;
+      for (const dep of set) {
+        if (visited.has(dep)) continue;
+        if (!dep.startsWith(appDir)) continue;
+        if (skip && skip.has(dep)) continue;
+        visited.add(dep);
+        queue.push(dep);
+      }
+    }
+  }
+  return specs;
+}
+
 /**
  * Recursively walk a directory, parse imports, and populate the graph.
  * @param {string} dir
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function walk(dir, appDir, graph, seen, dynamic, bare) {
+async function walk(dir, appDir, graph, seen, dynamic, bare, bareDynamic) {
   let entries;
   try { entries = await readdir(dir, { withFileTypes: true }); }
   catch { return; }
@@ -398,9 +493,9 @@ async function walk(dir, appDir, graph, seen, dynamic, bare) {
     if (e.name.startsWith('.')) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) {
-      await walk(full, appDir, graph, seen, dynamic, bare);
+      await walk(full, appDir, graph, seen, dynamic, bare, bareDynamic);
     } else if (/\.(js|ts|mjs|mts)$/.test(e.name)) {
-      await parseFile(full, appDir, graph, seen, dynamic, bare);
+      await parseFile(full, appDir, graph, seen, dynamic, bare, bareDynamic);
     }
   }
 }
@@ -428,7 +523,7 @@ export function _parseCacheHas(file) { return PARSE_CACHE.has(file); }
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function parseFile(file, appDir, graph, seen, dynamic, bare) {
+async function parseFile(file, appDir, graph, seen, dynamic, bare, bareDynamic) {
   let mtimeMs, size;
   try { const st = await stat(file); mtimeMs = st.mtimeMs; size = st.size; }
   catch { return; }
@@ -438,6 +533,7 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
     if (cached.deps.size) graph.set(file, cached.deps);
     if (cached.dynDeps && cached.dynDeps.size && dynamic) dynamic.set(file, cached.dynDeps);
     if (cached.bareDeps && cached.bareDeps.size && bare) bare.set(file, cached.bareDeps);
+    if (cached.bareDynDeps && cached.bareDynDeps.size && bareDynamic) bareDynamic.set(file, cached.bareDynDeps);
     return;
   }
 
@@ -541,19 +637,28 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
   // `,`/`)`), preserving the documented limitation.
   const { redacted: holeAware, literals } = redactToPlaceholders(src);
   const dynDeps = new Set();
+  const bareDynDeps = new Set();
   for (const m of holeAware.matchAll(DYNAMIC_IMPORT_RE)) {
     const token = m[1];
     const pm = /^__STR_(\d+)__$/.exec(token);
     const spec = pm ? literals[Number(pm[1])] : token;
     if (spec == null) continue;
-    if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
+    if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) {
+      // A dynamically-imported VENDOR (`await import('dayjs')`). Not a graph
+      // edge (there is no local file to serve) and not a preload (lazy by
+      // intent), but it still needs an importmap entry or the import fails to
+      // resolve when it runs. Recorded in its own map for that one consumer.
+      if (isVendorSpecifier(spec)) bareDynDeps.add(spec);
+      continue;
+    }
     const resolved = resolveImport(spec, file, appDir);
     if (resolved && !deps.has(resolved)) dynDeps.add(resolved);
   }
-  PARSE_CACHE.set(file, { mtimeMs, size, deps, dynDeps, bareDeps });
+  PARSE_CACHE.set(file, { mtimeMs, size, deps, dynDeps, bareDeps, bareDynDeps });
   if (deps.size) graph.set(file, deps);
   if (dynDeps.size && dynamic) dynamic.set(file, dynDeps);
   if (bareDeps.size && bare) bare.set(file, bareDeps);
+  if (bareDynDeps.size && bareDynamic) bareDynamic.set(file, bareDynDeps);
 }
 
 /**

package/src/rate-limit.js

@@ -40,6 +40,7 @@ let warnedProxyOverride = false;
  *   message?: string,
  *   store?: import('./cache.js').CacheStore,
  *   trustProxy?: boolean,
+ *   clientIpHeader?: string,
  * }} opts
  * @returns {(req: Request, next: () => Promise<Response>) => Promise<Response>}
  */
@@ -50,13 +51,17 @@ export function rateLimit(opts = {}) {
   const keyPrefix = typeof opts.key === 'string' ? opts.key : '';
   const message = opts.message ?? 'Too Many Requests';
   const trustProxy = opts.trustProxy === true;
+  // The header carrying the visitor, when the app knows which one that is.
+  // Inert without `trustProxy: true`, since naming a wire header to trust IS
+  // the trust decision and must not be grantable by a second option.
+  const header = typeof opts.clientIpHeader === 'string' ? opts.clientIpHeader : undefined;
   // Use the provided store, or fall back to the global cache store.
   // Whatever was set via `setStore()` at app startup (in-memory by default).
   const store = opts.store || null;
 
   return async function rateLimitMiddleware(req, next) {
     const s = store || getStore();
-    const raw = keyFn ? await keyFn(req) : clientIp(req, { trustProxy });
+    const raw = keyFn ? await keyFn(req) : clientIp(req, { trustProxy, header });
     const key = `rl:${keyPrefix}${raw}`;
 
     const count = await s.increment(key, windowMs);
@@ -185,10 +190,42 @@ export function propagateTrustedRemoteIp(src, dst) {
  * leaving them in disagreement buckets every visitor behind that proxy onto
  * one key.
  *
+ * `header` names the ONE forwarded header to trust, and it is the option a
+ * CDN deployment needs (#1389). The default chain reads the leftmost
+ * `X-Forwarded-For` entry first, which behind Cloudflare is CLOUDFLARE'S
+ * EGRESS address rather than the visitor: Cloudflare pins an egress IP per
+ * connection, so a limiter keyed on it gives one bucket per connection, which
+ * counts down convincingly and limits nobody. The visitor is in
+ * `CF-Connecting-IP`, and naming it here is how the app says so.
+ *
+ * The framework does NOT reorder the default chain to prefer that header,
+ * because which header is trustworthy is a property of the TOPOLOGY, not of
+ * the framework. Cloudflare overwrites `CF-Connecting-IP`, so it is
+ * unforgeable behind Cloudflare and forgeable everywhere else; preferring it
+ * globally would let a client on an nginx or bare-Railway deploy outrank the
+ * `X-Forwarded-For` the real proxy set. So the app names its header and owns
+ * the claim. When `header` is set it is the only forwarded header consulted,
+ * falling back to the stamped peer and then `_anon_`, and a blank value falls
+ * through rather than becoming a shared literal key.
+ *
  * @param {Request} req
- * @param {{ trustProxy?: boolean }} [opts]
+ * @param {{ trustProxy?: boolean, header?: string }} [opts]
  * @returns {string}
  */
+/**
+ * First entry of a forwarded-IP header, trimmed, or `''` when there is nothing
+ * usable. A blank value must FALL THROUGH rather than resolve: an empty string
+ * as a bucket key is one key shared by every visitor whose proxy sent the
+ * header empty, which is a limiter that throttles strangers together.
+ *
+ * @param {string | null | undefined} raw
+ * @returns {string}
+ */
+function firstForwardedEntry(raw) {
+  if (!raw) return '';
+  return raw.split(',')[0].trim();
+}
+
 export function clientIp(req, opts = {}) {
   if (opts.trustProxy === true && !proxyIsTrusted() && !warnedProxyOverride) {
     warnedProxyOverride = true;
@@ -201,10 +238,18 @@ export function clientIp(req, opts = {}) {
     );
   }
   if (opts.trustProxy === true && proxyIsTrusted()) {
+    if (opts.header) {
+      // One named header, and nothing else from the wire. A chain is still
+      // split on the comma so a proxy that appends to the named header cannot
+      // turn the key into a growing string, which would mint a fresh bucket per
+      // hop and reproduce the very failure this option exists to fix.
+      const named = req.headers.get(String(opts.header).toLowerCase());
+      return firstForwardedEntry(named) || trustedRemoteIp(req) || '_anon_';
+    }
     return (
-      req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
-      req.headers.get('cf-connecting-ip') ||
-      req.headers.get('x-real-ip') ||
+      firstForwardedEntry(req.headers.get('x-forwarded-for')) ||
+      req.headers.get('cf-connecting-ip')?.trim() ||
+      req.headers.get('x-real-ip')?.trim() ||
       trustedRemoteIp(req) ||
       '_anon_'
     );

package/src/router.js

@@ -1,5 +1,6 @@
 import { join, relative, sep, posix } from 'node:path';
 import { walk } from './fs-walk.js';
+import { findInstrumentationClient } from './instrumentation.js';
 
 /**
  * @typedef {{
@@ -35,6 +36,7 @@ import { walk } from './fs-walk.js';
  *   globalError: string | null,
  *   globalNotFound: string | null,
  *   metadataRoutes: MetadataRoute[],
+ *   instrumentationClient: string | null,
  *   appDir: string
  * }} RouteTable
  */
@@ -185,7 +187,15 @@ export async function buildRouteTable(appDir) {
   }
 
   pages.sort(compareSpecificity);
-  return { pages, apis, notFound, notFounds, globalError, globalNotFound, metadataRoutes, appDir };
+  // `instrumentation-client.*` is an app-ROOT convention file, not a router
+  // stem, but it is a browser-bound entry (the boot imports it first), so the
+  // table is where every consumer already looks for one. Resolved HERE rather
+  // than by each caller: it used to be attached by the dev server alone, and a
+  // second consumer that built its own table (the vendor scan) silently lost
+  // the entry, which inverted the pin-is-a-superset invariant. Deriving it in
+  // the one place that builds the table makes that class of miss impossible.
+  const instrumentationClient = await findInstrumentationClient(appDir);
+  return { pages, apis, notFound, notFounds, globalError, globalNotFound, metadataRoutes, instrumentationClient, appDir };
 }
 
 /**

package/src/ssr/client-router-flag.js

@@ -0,0 +1,42 @@
+/**
+ * The app-wide client-router opt-out flag (#629).
+ *
+ * Default ON (the framework's automatic-nav thesis): the router auto-enables in
+ * the browser when `@webjsdev/core` loads. `webjs.clientRouter: false` flips it
+ * off app-wide; the dev server reads the config at boot and on each rebuild and
+ * calls `setClientRouterEnabled`, and `wrapHead` then emits a
+ * `window.__WEBJS_CLIENT_ROUTER__=false` flag BEFORE the deferred boot module
+ * so the bundle's module-end auto-enable skips.
+ *
+ * A module-level switch (mirroring `setBasePath` / `setElisionFingerprint`) so
+ * no opt has to thread through every render path. Default true keeps every
+ * existing app and test byte-identical.
+ *
+ * It sits in its own module rather than beside its readers because it has TWO
+ * of them, in `head.js` and `render.js`, and parking it in either made the
+ * other import across what was otherwise a one-way edge. That was the second
+ * half of the ssr import cycle. The rule the pre-split file stated, that module
+ * state belongs with the code that uses and writes it, is unchanged for state
+ * with a single reader: `_metadataIconRoutes` still lives in `head.js`, whose
+ * `wrapHead` is the only thing that reads it.
+ */
+
+let _clientRouterEnabled = true;
+
+/**
+ * Set the app-wide client-router flag.
+ *
+ * @param {boolean} enabled  anything but `false` enables
+ */
+export function setClientRouterEnabled(enabled) {
+  _clientRouterEnabled = enabled !== false;
+}
+
+/**
+ * Whether the client router is enabled app-wide.
+ *
+ * @returns {boolean}
+ */
+export function clientRouterEnabled() {
+  return _clientRouterEnabled;
+}