@webjsdev/server 0.8.39 → 0.8.40

package/index.d.ts

@@ -59,6 +59,15 @@ export interface CacheStore {
   delete(key: string): Promise<void>;
   /** Atomically increment a counter; returns the new value (TTL set on creation only). */
   increment(key: string, ttlMs?: number): Promise<number>;
+  /**
+   * OPTIONAL atomic set insert for the tag index (#752): add `member` to the set
+   * at `key`, refreshing the key TTL. Eliminates the lost-update race of the
+   * read-modify-write JSON path. A store omitting it falls back to that path.
+   * Paired with `setMembers` (implement both or neither).
+   */
+  setAdd?(key: string, member: string, ttlMs?: number): Promise<void>;
+  /** OPTIONAL set read, the counterpart of `setAdd` (empty array on a miss). */
+  setMembers?(key: string): Promise<string[]>;
 }
 
 /** The pluggable logger interface. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.39",
+  "version": "0.8.40",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/action-error.js

@@ -0,0 +1,56 @@
+/**
+ * Server-action error sanitization (#749).
+ *
+ * A thrown server action must NOT leak its raw error message to the client in
+ * production. Most thrown errors are NOT author-controlled (a Postgres driver
+ * error carries the constraint / column name, an `ECONNREFUSED` carries an
+ * internal host / IP, an fs error carries an absolute server path), and the RPC
+ * client surfaces the message. So in prod we return a GENERIC message plus a
+ * short `digest`, and log the full error server-side keyed by that digest, the
+ * same model as Next.js's server-action errors. An author-facing user-safe
+ * message belongs on the `ActionResult` `{ success: false, error }` envelope
+ * (the expected-failure channel), not on a throw.
+ *
+ * Used by both the buffered RPC error path (`actions.js`) and the streaming
+ * error frame (`action-stream.js`); it is a leaf module so neither importer
+ * creates a cycle.
+ *
+ * @module action-error
+ */
+
+import { isRedirect, isNotFound } from '@webjsdev/core';
+import { digestHex } from './crypto-utils.js';
+
+/** The generic client-facing message for a sanitized prod action error. */
+export const GENERIC_ERROR_MESSAGE = 'Internal server error';
+
+/**
+ * `redirect()` / `notFound()` throw `Error` sentinels tagged with a `__webjs`
+ * SYMBOL VALUE. They are control flow, not errors to sanitize, and their
+ * message is not sensitive, so the error path passes them through unchanged.
+ *
+ * Reuses core's authoritative `isRedirect` / `isNotFound`, which match the exact
+ * sentinel symbol value (`__webjs === REDIRECT` / `=== NOT_FOUND`), NOT mere
+ * property presence: a genuine error that happens to carry a `__webjs` property
+ * must still be sanitized, never passed through.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isControlFlowThrow(err) {
+  return isRedirect(err) || isNotFound(err);
+}
+
+/**
+ * A short, stable correlation digest for a thrown error (a hash of its message
+ * and stack). The SAME value is logged server-side and returned to the client,
+ * so a generic client error maps back to the full server log line, and two
+ * occurrences of the same error share a digest (groupable in an APM).
+ *
+ * @param {unknown} err
+ * @returns {Promise<string>}
+ */
+export async function errorDigest(err) {
+  const basis = err instanceof Error ? `${err.message}\n${err.stack || ''}` : String(err);
+  return (await digestHex('SHA-256', basis)).slice(0, 10);
+}

package/src/action-stream.js

@@ -21,6 +21,7 @@
  */
 import { encodeFrame, FRAME_CHUNK, FRAME_END, FRAME_ERROR, STREAM_CONTENT_TYPE } from '@webjsdev/core';
 import { getSerializer } from './serializer.js';
+import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 
 /**
  * Whether an action's return value should stream over the RPC wire rather than
@@ -73,11 +74,11 @@ function toAsyncIterator(source) {
  * iterator, stopping a server generator.
  *
  * @param {any} source the streamable action return value
- * @param {{ signal?: AbortSignal, onError?: (e: unknown) => void, headers?: Record<string,string> }} [opts]
+ * @param {{ signal?: AbortSignal, onError?: (e: unknown) => void, headers?: Record<string,string>, dev?: boolean }} [opts]
  * @returns {Response}
  */
 export function streamActionResponse(source, opts = {}) {
-  const { signal, onError, headers } = opts;
+  const { signal, onError, headers, dev } = opts;
   const s = getSerializer();
   const enc = new TextEncoder();
   const iter = toAsyncIterator(source);
@@ -125,8 +126,23 @@ export function streamActionResponse(source, opts = {}) {
         // like the buffered error path, then ship the author-controlled message
         // on the frame channel (the status is already 200, mid-stream).
         if (typeof onError === 'function') { try { onError(e); } catch {} }
-        console.error('[webjs] streaming action threw:', e);
-        const msg = e instanceof Error && e.message ? e.message : 'Internal server error';
+        // Sanitize like the buffered path (#749): dev ships the real message,
+        // prod ships a generic message + correlation digest (logged with the
+        // full error), never the raw message. A redirect()/notFound() sentinel
+        // passes through. The status is already 200 here, so the error rides the
+        // frame channel; the client stub throws Error(frame text).
+        let msg;
+        if (dev) {
+          msg = e instanceof Error && e.message ? e.message : GENERIC_ERROR_MESSAGE;
+          console.error('[webjs] streaming action threw:', e);
+        } else if (isControlFlowThrow(e)) {
+          msg = e instanceof Error ? e.message : String(e);
+          console.error('[webjs] streaming action threw:', e);
+        } else {
+          const digest = await errorDigest(e);
+          msg = `${GENERIC_ERROR_MESSAGE} [digest=${digest}]`;
+          console.error(`[webjs] streaming action threw [digest=${digest}]:`, e);
+        }
         try { controller.enqueue(encodeFrame(FRAME_ERROR, enc.encode(msg))); } catch {}
         await releaseSource(e);
         detach();

package/src/actions.js

@@ -15,6 +15,7 @@ import { revalidateTags } from './cache-tags.js';
 import { runWithActionSignal } from './action-signal.js';
 import { runActionChain } from './action-middleware.js';
 import { isStreamable, streamActionResponse } from './action-stream.js';
+import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
@@ -349,7 +350,7 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   lines.push(`  if (ct.includes(__STREAM_CT)) return __readStream(res, fn);`);
   lines.push(`  const text = await res.text();`);
   lines.push(`  const parsed = ct.includes(__CT) ? __p(text) : (ct.includes('application/json') ? JSON.parse(text) : text);`);
-  lines.push(`  if (!res.ok) throw new Error((parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status));`);
+  lines.push(`  if (!res.ok) { const __e = new Error((parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status)); if (parsed && parsed.digest) __e.digest = parsed.digest; throw __e; }`);
   lines.push(`  return parsed;`);
   lines.push(`}`);
   // Decode a framed streamed body into an async generator of rich-deserialized
@@ -533,7 +534,7 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
         if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
       }
-      return streamActionResponse(result, { signal: req.signal, onError, headers });
+      return streamActionResponse(result, { signal: req.signal, onError, headers, dev: idx.dev });
     }
     if (method === 'GET') {
       // A short-circuit (the action did not run, e.g. an auth denial) is NEVER
@@ -588,27 +589,38 @@ async function getActionResponse(result, mod, args, req) {
 }
 
 /**
- * Return a JSON error response with dev-vs-prod sanitization.
- * In prod we return only the error message (not the stack), and we log the
- * full error server-side. Internal errors with no message become a generic
- * 500.
+ * Return a JSON error response with dev-vs-prod sanitization (#749).
+ *
+ * Dev returns the real message + stack. PROD returns a GENERIC message plus a
+ * short `digest`, and logs the full error server-side keyed by that digest, so
+ * a raw error (a DB driver message with a constraint name, an `ECONNREFUSED`
+ * with an internal IP, an fs path) never reaches the client while staying
+ * diagnosable from the logs. `redirect()` / `notFound()` control-flow sentinels
+ * pass through unchanged (not errors, message not sensitive). An author-facing
+ * user-safe message belongs on the `ActionResult` `{ success: false, error }`
+ * envelope, not on a throw.
  *
  * @param {unknown} err
  * @param {boolean} dev
+ * @returns {Promise<Response>}
  */
-function actionErrorResponse(err, dev) {
-  console.error('[webjs] action threw:', err);
+async function actionErrorResponse(err, dev) {
   if (dev) {
+    console.error('[webjs] action threw:', err);
     const msg = err instanceof Error ? err.message : String(err);
     const stack = err instanceof Error ? err.stack : undefined;
     return rpcResponse({ error: msg, stack }, { status: 500 });
   }
-  // Prod: only expose the thrown message (author-controlled), never the stack.
-  const msg =
-    err instanceof Error && typeof err.message === 'string' && err.message
-      ? err.message
-      : 'Internal server error';
-  return rpcResponse({ error: msg }, { status: 500 });
+  // Control-flow sentinels (redirect/notFound) are not errors to sanitize.
+  if (isControlFlowThrow(err)) {
+    console.error('[webjs] action threw:', err);
+    const msg = err instanceof Error ? err.message : String(err);
+    return rpcResponse({ error: msg }, { status: 500 });
+  }
+  // Prod genuine error: generic message + correlation digest, full error logged.
+  const digest = await errorDigest(err);
+  console.error(`[webjs] action threw [digest=${digest}]:`, err);
+  return rpcResponse({ error: GENERIC_ERROR_MESSAGE, digest }, { status: 500 });
 }
 
 /**

package/src/cache-fn.js

@@ -23,9 +23,21 @@
  * @module cache-fn
  */
 
+import { stringify, parse } from '@webjsdev/core';
 import { getStore } from './cache.js';
 import { addKeyToTags } from './cache-tags.js';
 
+// Cache value/key encoding version. Entries written by an older encoding used
+// a DIFFERENT key namespace, so a reader never deserializes them with the new
+// format. Before this segment existed, values were JSON and keys were the
+// unversioned `cache:<prefix>`; a JSON-format entry is still valid JSON that
+// `parse` would silently accept as a lossy value (a Date as a string) without
+// recomputing, so the version segment forces those pre-upgrade entries to miss
+// and expire by their own TTL instead of being served stale. Bump it whenever
+// the value/key encoding changes. Distinct from the `cache:tag:` tag-index
+// namespace in cache-tags.js.
+const CACHE_FORMAT = 'r1';
+
 /**
  * Wrap an async function with server-side caching.
  *
@@ -70,17 +82,28 @@ export function cache(fn, opts) {
   const wrapped = /** @type {T & { invalidate: () => Promise<void> }} */ (
     async function (...args) {
       const store = getStore();
+      // Both the key fingerprint and the stored value go through the same
+      // rich serializer the RPC wire uses (@webjsdev/core stringify/parse),
+      // NOT JSON. JSON collapses Date to a string and Map/Set to {} / [], so
+      // (a) a cached value would change shape between a cold miss (the real
+      // value) and a warm hit (the lossy JSON value), and (b) two distinct
+      // Map/Set args would collide to the same key. Going through core's
+      // serializer makes a hit byte-faithful to a miss and keys collision-safe.
+      // We use core stringify/parse DIRECTLY rather than getSerializer() so the
+      // cache preserves full fidelity even when an app swaps the wire format to
+      // a lossy one (e.g. plain JSON); cache fidelity is a storage concern, not
+      // a wire concern.
       const cacheKey = args.length
-        ? `cache:${prefix}:${JSON.stringify(args)}`
-        : `cache:${prefix}`;
+        ? `cache:${CACHE_FORMAT}:${prefix}:${await stringify(args)}`
+        : `cache:${CACHE_FORMAT}:${prefix}`;
 
       const hit = await store.get(cacheKey);
       if (hit !== null) {
-        try { return JSON.parse(hit); } catch { /* corrupted: recompute */ }
+        try { return parse(hit); } catch { /* corrupted: recompute */ }
       }
 
       const result = await fn(...args);
-      await store.set(cacheKey, JSON.stringify(result), ttlMs);
+      await store.set(cacheKey, await stringify(result), ttlMs);
       // Record tag -> cacheKey in the thin tag index so a later
       // revalidateTag can find and evict this entry (including
       // arg-specific keys the no-args invalidate() cannot reach).
@@ -115,7 +138,7 @@ export function cache(fn, opts) {
   wrapped.invalidate = async function () {
     const store = getStore();
     // Delete the base key (no-args call)
-    await store.delete(`cache:${prefix}`);
+    await store.delete(`cache:${CACHE_FORMAT}:${prefix}`);
     // Note: arg-specific keys are not tracked. If the cached function
     // is called with different arguments, those entries expire via TTL.
     // For full invalidation of arg-specific keys, use a short TTL.

package/src/cache-tags.js

@@ -16,20 +16,22 @@
  * clears the index entry. A mutation in ANY module can therefore evict every
  * read tagged `'posts'` across modules with one explicit call.
  *
- * It stays a thin index over `store.get/set/delete`: no new store method, a
- * plain JSON array (a Set is trivial in the memory store; the same get/set of
- * a JSON array works for Redis). The cohesive companion for HTML paths is
- * `revalidatePath` in `html-cache.js`; together they are the server cache
- * invalidation surface (this one for `cache()` DATA, that one for cached HTML).
+ * The cohesive companion for HTML paths is `revalidatePath` in
+ * `html-cache.js`; together they are the server cache invalidation surface
+ * (this one for `cache()` DATA, that one for cached HTML).
  *
- * MULTI-INSTANCE CAVEAT (mirrors #241): the index is a plain read-modify-write
- * of a JSON array, NOT atomic across processes. With a shared Redis store,
- * `revalidateTag` deletes the keys it can see and reaches every instance for
- * those keys, but two instances appending to the same tag concurrently can
- * lose an append (last write wins), so a freshly-stored key on a peer might
- * miss eviction and live until its TTL. The tag index entry itself also
- * carries the cache TTL, so the index self-prunes and never grows unbounded.
- * For strict cross-instance invalidation, prefer a short `ttl` as the floor.
+ * ATOMICITY (#752): when the store exposes the optional `setAdd` / `setMembers`
+ * primitives, the tag index is a real SET, so adding a cache key is an atomic
+ * insert (`SADD` on Redis, a native `Set` in the single-process memory store).
+ * This eliminates the lost-update race the previous JSON-array read-modify-write
+ * had: two concurrent mutations appending to the same tag (whether across Redis
+ * instances or interleaved in one process at the read/write await gap) no longer
+ * drop an entry, so `revalidateTag` reliably evicts every tagged key. The index
+ * key carries the cache TTL (refreshed on each add), so it self-prunes. A custom
+ * store WITHOUT the primitives falls back to the old JSON-array path, which keeps
+ * the documented non-atomic caveat (prefer a short `ttl` as the cross-instance
+ * floor there). The HTML-side analog `revalidatePath` (#241) still carries the
+ * older caveat and is a separate follow-up.
  *
  * @module cache-tags
  */
@@ -44,16 +46,30 @@ function tagKey(tag) {
   return `${TAG_PREFIX}${tag}`;
 }
 
+/** @param {import('./cache.js').CacheStore} store */
+function supportsAtomicSets(store) {
+  return typeof store.setAdd === 'function' && typeof store.setMembers === 'function';
+}
+
 /**
  * Read the cache-key set stored under one tag. Returns a plain array (empty
- * on a miss / parse error, failing open). The store holds a JSON array.
+ * on a miss / parse error, failing open). Reads via the store's SET primitive
+ * when available (the atomic path), else parses the legacy JSON array.
  *
  * @param {string} tag
  * @returns {Promise<string[]>}
  */
 async function readTagKeys(tag) {
+  const store = getStore();
+  if (supportsAtomicSets(store)) {
+    try {
+      return await store.setMembers(tagKey(tag));
+    } catch {
+      return [];
+    }
+  }
   try {
-    const raw = await getStore().get(tagKey(tag));
+    const raw = await store.get(tagKey(tag));
     if (!raw) return [];
     const arr = JSON.parse(raw);
     return Array.isArray(arr) ? arr : [];
@@ -79,13 +95,21 @@ async function readTagKeys(tag) {
 export async function addKeyToTags(tags, cacheKey, ttlMs) {
   if (!Array.isArray(tags) || tags.length === 0) return;
   const store = getStore();
+  const atomic = supportsAtomicSets(store);
   for (const tag of tags) {
     if (typeof tag !== 'string' || !tag) continue;
     try {
-      const keys = await readTagKeys(tag);
-      if (keys.includes(cacheKey)) continue;
-      keys.push(cacheKey);
-      await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+      if (atomic) {
+        // Atomic set insert: no read-modify-write, so a concurrent add to the
+        // same tag (across instances or interleaved in-process) cannot lose
+        // this key. SADD dedups, so no membership pre-check is needed.
+        await store.setAdd(tagKey(tag), cacheKey, ttlMs);
+      } else {
+        const keys = await readTagKeys(tag);
+        if (keys.includes(cacheKey)) continue;
+        keys.push(cacheKey);
+        await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+      }
     } catch {
       /* a tag-index write failure must never affect the cached value */
     }

package/src/cache.js

@@ -23,6 +23,15 @@
  * @property {(key: string, ttlMs?: number) => Promise<number>} increment
  *   Atomically increment a counter. Returns the new value. Creates the
  *   key with value 1 if it doesn't exist. TTL is set on creation only.
+ * @property {((key: string, member: string, ttlMs?: number) => Promise<void>)} [setAdd]
+ *   OPTIONAL. Atomically add `member` to the SET stored at `key`, refreshing the
+ *   key's TTL. Eliminates the lost-update race of a read-modify-write JSON array
+ *   (the tag index in `cache-tags.js`, #752). A store WITHOUT this method makes
+ *   the tag index fall back to the non-atomic JSON path (the documented caveat).
+ *   Paired with `setMembers`; implement both or neither.
+ * @property {((key: string) => Promise<string[]>)} [setMembers]
+ *   OPTIONAL. Return the members of the SET stored at `key` (empty array on a
+ *   miss). The read counterpart of `setAdd`.
  */
 
 /**
@@ -98,6 +107,28 @@ export function memoryStore(opts = {}) {
       map.set(key, entry);
       return next;
     },
+    // Atomic SET ops (#752). The entry value for a set key is a native `Set`
+    // (not a JSON string), so the add is a single synchronous mutation with no
+    // read-modify-write await gap: concurrent `setAdd` calls in one process
+    // cannot lose an entry. Only the tag index uses these keys, so the mixed
+    // value type (string for normal keys, Set for set keys) never collides with
+    // `get`/`increment`. The key still rides the same LRU + TTL machinery.
+    async setAdd(key, member, ttlMs) {
+      const entry = map.get(key);
+      const set = entry && !isExpired(entry) && entry.value instanceof Set
+        ? entry.value
+        : new Set();
+      set.add(member);
+      map.delete(key); // re-insert at the end (LRU) + refresh TTL like Redis EXPIRE
+      map.set(key, { value: set, expiresAt: expiresAtFrom(ttlMs) });
+      evict();
+    },
+    async setMembers(key) {
+      const entry = map.get(key);
+      if (!entry) return [];
+      if (isExpired(entry)) { map.delete(key); return []; }
+      return entry.value instanceof Set ? [...entry.value] : [];
+    },
   };
 }
 
@@ -172,6 +203,28 @@ export function redisStore(opts = {}) {
       }
       return val;
     },
+    // Atomic SET ops (#752): SADD is an atomic set insert across instances, so
+    // the tag index no longer loses a concurrent append the way a JSON-array
+    // read-modify-write did. A per-member TTL is not native to a Redis set, so
+    // refresh the whole key's expiry on each add (PEXPIRE), keeping the
+    // short-TTL floor as defense-in-depth. ioredis uses lowercase command names
+    // (`sadd`); node-redis v4 uses camelCase (`sAdd`), so probe both.
+    async setAdd(key, member, ttlMs) {
+      const c = await getClient();
+      if (typeof c.sadd === 'function') await c.sadd(key, member);
+      else await c.sAdd(key, member);
+      if (ttlMs) {
+        if (typeof c.pexpire === 'function') await c.pexpire(key, ttlMs);
+        else await c.pExpire(key, ttlMs);
+      }
+    },
+    async setMembers(key) {
+      const c = await getClient();
+      const members = typeof c.smembers === 'function'
+        ? await c.smembers(key)
+        : await c.sMembers(key);
+      return Array.isArray(members) ? members : [];
+    },
   };
 }
 

package/src/check.js

@@ -1030,14 +1030,18 @@ export async function checkConventions(appDir) {
  * `middleware.ts` / `route.ts` (server-only, never page/layout/component
  * entries, so they are not in the candidate set to begin with).
  *
- * Known limitation: a DYNAMIC `import('./x.server.ts')` is invisible to this
- * rule. The framework's import scanner (`IMPORT_RE` in module-graph.js) matches
- * only static `import`/`export … from`, not the `import(` call form, so a
- * dynamic server import is not a graph edge here. This is deliberate and
- * consistent with the framework-wide graph: a dynamic import is also not elided
- * framework-wide, and its crash is deferred to call time (when the chunk is
- * fetched), not module load. Catching it would mean teaching the shared scanner
- * about `import(`, which is out of scope for this rule.
+ * Scope note for dynamic imports: a string-literal `import('./widget.ts')` IS
+ * tracked by the module graph now (#751), but only as a GATE edge (so the
+ * lazily-imported module is servable); this rule's server-import detection
+ * still runs over STATIC edges only (`transitiveDeps`), so a dynamic
+ * `import('./x.server.ts')` of a no-`'use server'` utility is not flagged here.
+ * That is deliberate: the throw-at-load crash is deferred to call time (when
+ * the module is actually fetched), not module load, and a dynamic import is
+ * also not elided framework-wide. A computed `import(expr)` cannot be resolved
+ * statically at all; rather than a false-positive-prone check rule (a computed
+ * import of an npm specifier or an otherwise-reachable app module is perfectly
+ * valid, so it fails the check-is-correctness-only dividing line), the dev
+ * server surfaces it with a 404 hint when the target 404s (see dev.js #751).
  *
  * @param {string} appDir
  * @param {Violation[]} violations  appended to in place

package/src/dev.js

@@ -87,6 +87,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
+import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
@@ -1221,18 +1222,31 @@ export async function createRequestHandler(opts) {
             // Rewrite the Request with the stripped URL, preserving method,
             // headers, and body. `duplex: 'half'` is required by the spec when
             // a body stream is present on a non-GET/HEAD request.
+            //
+            // SECURITY (#756): this is a fresh Request object, so it is NOT in
+            // the listener's out-of-band trusted-IP WeakMap (the Bun shell
+            // stamps the IP there instead of cloning the Request to set the
+            // header). Without carrying it forward, `clientIp` would fall back
+            // to the inbound `x-webjs-remote-ip` header that the copied
+            // `req.headers` still carries, which a client can spoof. So strip
+            // that header on the rebuild and propagate the framework-trusted IP
+            // across the new object, the same pattern page-action.js uses.
+            const headers = new Headers(req.headers);
+            headers.delete('x-webjs-remote-ip');
             const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
-            req = new Request(
+            const next = new Request(
               reqUrl.toString(),
               /** @type {any} */ ({
                 method: req.method,
-                headers: req.headers,
+                headers,
                 body: hasBody ? req.body : undefined,
                 duplex: hasBody ? 'half' : undefined,
                 redirect: req.redirect,
                 signal: req.signal,
               }),
             );
+            propagateTrustedRemoteIp(req, next);
+            req = next;
           }
         }
       }
@@ -1903,6 +1917,20 @@ async function handleCore(req, ctx) {
       }
       return fileResponse(abs, { dev, immutable: versioned });
     }
+    // Dev hint (#751): the request is for a real app source module that EXISTS
+    // on disk but is NOT in the browser-bound graph, so the gate 404s it. The
+    // most common cause is a dynamic `import()` the static scanner cannot
+    // track: a string-literal `import('./x.ts')` IS tracked and servable, but a
+    // computed `import(expr)` / `import('./' + name)` cannot be resolved
+    // statically and falls through here. Surface the likely cause instead of a
+    // bare 404 so the author is not left guessing. Dev-only and diagnostic; it
+    // does not change the 404 status, only the body + a server log line.
+    if (dev && abs.startsWith(appDir) && /\.m?[jt]s$/.test(abs) && (await exists(abs))) {
+      const rel = relative(appDir, abs);
+      const hint = `[webjs] 404: ${rel} exists but is not reachable from any browser-bound entry, so it is not servable. If you load it via a dynamic import(), use a STRING-LITERAL specifier (e.g. import('./x.ts')) so the scanner can track it; a computed import(expr) cannot be resolved statically and will 404. Otherwise this module is simply unreferenced by client code.`;
+      console.warn(hint);
+      return new Response(hint, { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+    }
   }
 
   // Metadata routes: /sitemap.xml, /robots.txt, /icon, /opengraph-image, etc.

package/src/importmap.js

@@ -459,6 +459,42 @@ export function buildImportMap(opts = {}) {
   return out;
 }
 
+/**
+ * Resolve a set of bare vendor specifiers to `modulepreload` targets (#754), so
+ * SSR can flatten the vendor CDN waterfall: instead of discovering each vendor
+ * module level by level (fetch app module -> parse -> fetch vendor -> parse ...),
+ * the reached vendor URLs are hinted up front and fetched in parallel.
+ *
+ * The href is taken DIRECTLY from `buildImportMap().imports[spec]`, so it is
+ * BYTE-IDENTICAL to the importmap target (same base-path + `?v` rewrite): a
+ * differing href would make the browser treat the preload and the import as two
+ * resources and double-fetch. The matching `integrity` comes from the same map.
+ * A specifier NOT in the importmap (an unpinned / unreached / elided vendor)
+ * yields nothing, so this never over-fetches. Duplicate hrefs are collapsed.
+ *
+ * Framework runtime specifiers (`@webjsdev/core`...) are excluded: core is
+ * served same-origin and already on the boot path, not a CDN-waterfall vendor.
+ *
+ * @param {Iterable<string>} specifiers  bare specifiers reached by the page
+ * @returns {Array<{ href: string, integrity?: string }>}
+ */
+export function vendorPreloadTargets(specifiers) {
+  const specs = [...(specifiers || [])];
+  if (!specs.length) return [];
+  const map = buildImportMap();
+  /** @type {Array<{ href: string, integrity?: string }>} */
+  const out = [];
+  const seen = new Set();
+  for (const spec of specs) {
+    if (spec === '@webjsdev/core' || spec.startsWith('@webjsdev/core/')) continue;
+    const href = map.imports[spec];
+    if (!href || seen.has(href)) continue;
+    seen.add(href);
+    out.push({ href, integrity: map.integrity ? map.integrity[href] : undefined });
+  }
+  return out;
+}
+
 /**
  * Derive the cross-origin vendor CDN origins from the resolved vendor
  * importmap, most-common first (issue #243, auto vendor preconnect). For an