@webjsdev/server 0.8.58 → 0.8.59

package/src/html-cache.js

@@ -27,8 +27,9 @@
 import { getStore } from './cache.js';
 import { STREAM_MARKER } from './conditional-get.js';
 import { createHash } from 'node:crypto';
-import { publishedBuildId } from './importmap.js';
-import { dynamicAccessed } from './context.js';
+import { publishedBuildId, basePath } from './importmap.js';
+import { stripBasePath } from './base-path.js';
+import { dynamicAccessed, getRequest } from './context.js';
 
 /** Namespace prefix for every cached-HTML key, so a flush can target it. */
 const KEY_PREFIX = 'webjs:html:';
@@ -109,11 +110,37 @@ export function readRevalidate(pageModule) {
 }
 
 /**
- * The cache key for a request: the FULL URL (path + search string), since
- * `searchParams` change page output. Normalized to path + sorted query so
- * `?a=1&b=2` and `?b=2&a=1` share an entry. Two more discriminators are
- * folded into the namespace:
+ * The origin component of a cache key. `url.origin` is already the normalized
+ * lowercase `scheme://host[:port]` form for an http(s) URL; a non-special
+ * scheme serializes to the literal string `null`, which is a fine constant key
+ * component (such a URL never reaches a cacheable page render anyway).
  *
+ * @param {URL} url
+ * @returns {string}
+ */
+function originKey(url) {
+  return url.origin;
+}
+
+/**
+ * The cache key for a request: the ORIGIN plus the full path + search string,
+ * since both `ctx.url.origin` and `searchParams` change page output.
+ * Normalized to path + sorted query so `?a=1&b=2` and `?b=2&a=1` share an
+ * entry. Four discriminators are folded into the namespace:
+ *
+ *  - the origin (#1097). This cache is SHARED across visitors, and `ctx.url`
+ *    is built from `X-Forwarded-Host` / `X-Forwarded-Proto`, which neither
+ *    Cloudflare nor Railway strips from a client request. Without the origin
+ *    in the key, one request carrying `X-Forwarded-Host: evil.example` baked
+ *    an attacker-chosen origin into the shared body, and every later visitor
+ *    to that path was served it until the entry expired: a poisoned
+ *    `og:image`, canonical link, OAuth callback URL, or absolute asset URL.
+ *    With the origin in the key, a clean request resolves its origin from the
+ *    proxy-set `Host` and reads its OWN entry, so the hostile body is
+ *    unreachable from any origin an attacker does not already control. A
+ *    single-host deploy has exactly one origin and so exactly one key per URL,
+ *    unchanged hit rate; a genuine multi-host deploy gets correctly separated
+ *    entries instead of cross-serving one host's HTML to another;
  *  - the in-process generation, so `revalidateAll()` (a generation bump)
  *    makes every prior key unreachable in one step;
  *  - the published build id (the importmap fingerprint), so a NEW DEPLOY
@@ -143,7 +170,7 @@ export function htmlCacheKey(url) {
   // the importmap-only build id misses. Empty (dev / no fingerprint) collapses
   // to the prior key shape, so an unconfigured app is byte-identical.
   const appfp = _appSourceFp ? `${_appSourceFp}:` : '';
-  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${url.pathname}${search}`;
+  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${originKey(url)}:${url.pathname}${search}`;
 }
 
 /**
@@ -221,17 +248,59 @@ export function isCacheableResponse(res, guards = {}) {
  * ONLY the no-query entry; pass the exact `path?query` to target a
  * specific query variant, or call `revalidateAll()` to clear everything.
  *
- * @param {string} path  e.g. '/blog' or '/blog?page=2'
+ * ORIGIN RESOLUTION (#1097). Cache keys carry the request's origin, so a bare
+ * path does not name one entry, it names one per origin the path was cached
+ * under. Two forms resolve it:
+ *
+ *  1. The CURRENT request's origin, when one is ambient. A mutation runs inside
+ *     the request of the user who triggered it, and that user is on the same
+ *     origin as the pages being evicted, so a bare path is exact for the
+ *     ordinary "server action writes, then evicts" flow, which is every
+ *     in-repo example and everything the docs show.
+ *  2. An ABSOLUTE url (`https://app.example/blog`) names its origin outright.
+ *     This is the form for a caller with NO ambient request: a cron job, a
+ *     queue worker, an `instrumentation.js` timer. Under `webjs.basePath` pass
+ *     the PUBLIC url and the mount prefix is stripped for you, so it keys the
+ *     same entry the write stored.
+ *
+ * A bare path with no ambient request cannot be resolved and WARNS ONCE naming
+ * the path, rather than silently evicting nothing.
+ *
+ * There is deliberately no process-local registry of "origins seen so far"
+ * standing in for case 2. The origin comes from `X-Forwarded-Host`, which is
+ * client-supplied and forwarded rather than stripped (the whole premise of
+ * #1097), so such a registry is attacker-writable: a flood of hostile hosts
+ * against a cold process either fills a bounded registry before the real origin
+ * is ever seen, or grows an unbounded one. Either way eviction silently stops
+ * working, which is worse than the explicit contract above.
+ *
+ * @param {string} path  e.g. '/blog', '/blog?page=2', or 'https://app.example/blog'
  * @returns {Promise<void>}
  */
 export async function revalidatePath(path) {
   if (typeof path !== 'string' || !path) return;
-  // Build the same normalized key readHtmlCache / writeHtmlCache produce.
   let url;
-  try {
-    url = new URL(path, 'http://internal.invalid');
-  } catch {
-    return;
+  if (/^https?:\/\//i.test(path)) {
+    try { url = new URL(path); } catch { return; }
+    // An absolute url is the PUBLIC one, so under `webjs.basePath` it carries
+    // the mount prefix. Cache entries key on the app-root-relative path (the
+    // write strips it in dev.js for exactly this reason), so strip it here too
+    // or the caller who was told to use this form, the one with no ambient
+    // request, computes a key nothing was ever stored under. A path that is
+    // not under the base path is left alone, matching the write's behaviour.
+    const base = basePath();
+    if (base) {
+      const stripped = stripBasePath(url.pathname, base);
+      if (stripped !== null) url.pathname = stripped;
+    }
+  } else {
+    const origin = ambientOrigin();
+    if (!origin) {
+      warnUnresolvedOriginOnce(path);
+      return;
+    }
+    // Build the same normalized key readHtmlCache / writeHtmlCache produce.
+    try { url = new URL(path, origin); } catch { return; }
   }
   try {
     await getStore().delete(htmlCacheKey(url));
@@ -240,6 +309,41 @@ export async function revalidatePath(path) {
   }
 }
 
+/**
+ * The current request's origin, or '' when there is no ambient request. Never
+ * throws: an eviction helper must not take down the mutation that called it.
+ *
+ * @returns {string}
+ */
+function ambientOrigin() {
+  try {
+    const req = getRequest();
+    return req ? new URL(req.url).origin : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Paths already warned about an unresolvable bare-path eviction, so the warning
+ * fires once per offending path rather than once per invocation.
+ * @type {Set<string>}
+ */
+const _warnedUnresolvedPaths = new Set();
+
+/** @param {string} path */
+function warnUnresolvedOriginOnce(path) {
+  if (_warnedUnresolvedPaths.has(path)) return;
+  _warnedUnresolvedPaths.add(path);
+  console.warn(
+    `[webjs] revalidatePath(${JSON.stringify(path)}) evicted nothing: HTML cache ` +
+    `keys carry the request origin, and this call has no ambient request to take ` +
+    `one from (a cron job, a queue worker, a boot-time timer). Pass an absolute ` +
+    `url instead, e.g. revalidatePath('https://your-host${path.startsWith('/') ? path : '/' + path}'), ` +
+    `or call it from a server action, where the triggering request supplies the origin.`
+  );
+}
+
 /**
  * Response-funnel step (#241): if the response carries the HTML_CACHE_MARKER
  * (the SSR opted it into caching), re-check every guard against the FINAL

package/src/listener-bun.js

@@ -154,7 +154,7 @@ export function startBunListener(ctx) {
   const shutdown = makeShutdown({ closeServer, hub, logger });
   process.once('SIGINT', () => shutdown('SIGINT'));
   process.once('SIGTERM', () => shutdown('SIGTERM'));
-  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
 
   return {
     server,

package/src/listener-core.js

@@ -383,7 +383,7 @@ export class SseHub {
  * Install once-only process error handlers. Idempotent across multiple
  * `startServer` calls in the same process. Runtime-neutral (plain `process.on`).
  * @param {import('./logger.js').Logger} logger
- * @param {() => void} onFatal
+ * @param {() => void} onFatal Starts the FATAL shutdown, which exits non-zero.
  */
 export function installProcessHandlers(logger, onFatal) {
   if (/** @type any */ (globalThis).__webjsProcHandlers) return;
@@ -405,12 +405,37 @@ export function installProcessHandlers(logger, onFatal) {
  * `closeServer()` thunk that resolves once the server has stopped accepting
  * connections (node `server.close`, Bun `server.stop(true)`). Closes the SSE hub,
  * then drains, then exits; hard-exits after 10s if the drain hangs.
+ *
+ * Exit code, in full. Three things can force a 1, and only their absence
+ * leaves a 0:
+ *   - a drain that FAILS, so a rejected `closeServer()` and a drain still
+ *     hanging at the 10s deadline both exit 1 whatever started them;
+ *   - a FATAL start (the `uncaughtException` handler calling `onFatal`), which
+ *     exits 1 even when the drain is perfectly clean;
+ *   - a FATAL arriving MID-DRAIN, which upgrades a shutdown an operator signal
+ *     had already begun (see the upgrade-only note on `code` below).
+ * So 0 does NOT mean "a signal started it", it means an operator asked for the
+ * stop AND it drained cleanly AND nothing crashed on the way out. A supervisor
+ * reads only this code (systemd `Restart=on-failure`, Docker, Railway, and a CI
+ * step running a `test/bun/*.mjs` proof script, whose failed top-level assertion
+ * arrives here as an uncaught exception, #1092), so every one of those has to
+ * come back non-zero.
  * @param {{ closeServer: () => Promise<unknown>, hub: SseHub, logger: import('./logger.js').Logger }} opts
- * @returns {(signal: string) => void}
+ * @returns {(signal: string, opts?: { fatal?: boolean }) => void}
  */
 export function makeShutdown({ closeServer, hub, logger }) {
   let shuttingDown = false;
-  return (signal) => {
+  // Read at EXIT time, not at entry, so a fatal arriving mid-drain still counts.
+  // The drain window is up to 10s wide and in-flight requests are still running
+  // in it, so an uncaught exception landing there is an ordinary event, not an
+  // exotic race. Because the re-entrancy guard below drops that second call, a
+  // code captured at entry would stay 0 and the crashed process would report a
+  // successful stop, which is the exact failure this whole mechanism exists to
+  // prevent. Upgrade only (1 never falls back to 0), so a signal arriving during
+  // a fatal shutdown cannot launder the crash into a success either.
+  let code = 0;
+  return (signal, { fatal = false } = {}) => {
+    if (fatal) code = 1;
     if (shuttingDown) return;
     shuttingDown = true;
     logger.info(`received ${signal}, shutting down`);
@@ -420,11 +445,16 @@ export function makeShutdown({ closeServer, hub, logger }) {
       process.exit(1);
     }, 10_000);
     if (typeof hard.unref === 'function') hard.unref();
+    // Disarm before exiting. In production `process.exit` ends everything so this
+    // is redundant, but it keeps the deadline from outliving the decision it was
+    // guarding, which is what let a stubbed-exit test leave a live timer armed to
+    // kill an unrelated process 10s later.
+    const done = (c) => { clearTimeout(hard); process.exit(c); };
     Promise.resolve()
       .then(closeServer)
       .then(
-        () => { logger.info('bye'); process.exit(0); },
-        (err) => { logger.error('server close error', { err: String(err) }); process.exit(1); },
+        () => { logger.info('bye'); done(code); },
+        (err) => { logger.error('server close error', { err: String(err) }); done(1); },
       );
   };
 }

package/src/rate-limit.js

@@ -23,6 +23,14 @@
  */
 
 import { getStore } from './cache.js';
+// Aliased on purpose. `rateLimit()` binds a local `const trustProxy` from its
+// own options, which would shadow a same-named import inside that function and
+// leave the middleware path on the pre-override behaviour while the direct
+// `clientIp` path changed. `forwarded.js` imports nothing, so this adds no cycle.
+import { trustProxy as proxyIsTrusted } from './forwarded.js';
+
+/** Module-scope latch so the override warns once per process, never per request. */
+let warnedProxyOverride = false;
 
 /**
  * @param {{
@@ -126,8 +134,8 @@ function trustedRemoteIp(req) {
 
 /**
  * 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
+ * (#756). When the framework re-wraps a request (the form-submission body rebuild
+ * in `form-dispatch.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
@@ -167,12 +175,32 @@ export function propagateTrustedRemoteIp(src, dst) {
  * trust-proxy reintroduces the spoofability this option exists to
  * defend against.
  *
+ * `WEBJS_NO_TRUST_PROXY=1` OVERRIDES `trustProxy: true` (#1254). The env
+ * switch is the operator's statement about the deployment topology and it can
+ * only ever SUBTRACT trust, so when it is set this call falls back to the
+ * default path above: the framework-stamped peer, or `_anon_` when there is
+ * none, and never a forwarded-IP header. The override logs once per process.
+ * An app that genuinely sits behind a trusted proxy must unset the flag; the
+ * two settings answer the same question about one socket and one topology, so
+ * leaving them in disagreement buckets every visitor behind that proxy onto
+ * one key.
+ *
  * @param {Request} req
  * @param {{ trustProxy?: boolean }} [opts]
  * @returns {string}
  */
 export function clientIp(req, opts = {}) {
-  if (opts.trustProxy === true) {
+  if (opts.trustProxy === true && !proxyIsTrusted() && !warnedProxyOverride) {
+    warnedProxyOverride = true;
+    // No request data in this line, ever. It must not become a log of
+    // client-supplied header values.
+    console.warn(
+      '[webjs] WEBJS_NO_TRUST_PROXY=1 overrides trustProxy: true; ' +
+        'forwarded-IP headers are ignored and the framework-stamped peer is used. ' +
+        'Unset the env var if a trusted proxy really is in front of this process.',
+    );
+  }
+  if (opts.trustProxy === true && proxyIsTrusted()) {
     return (
       req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
       req.headers.get('cf-connecting-ip') ||

package/src/route-types.js

@@ -11,7 +11,7 @@
  * Design choices:
  *   - PAGES ONLY. A `route.{js,ts}` handler is an API endpoint, not a
  *     navigable HTML page, so its path is excluded from the navigable `Route`
- *     union. Pages (including page-action pages) are what a valid href points
+ *     union. Pages (including ones hosting a bound form) are what a valid href points
  *     at.
  *   - The route KEY is the literal pattern (`/blog/[slug]`), derived from the
  *     page's directory with route groups `(group)` stripped and `_private`

package/src/ssr.js

@@ -1,7 +1,7 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, isForbidden, isUnauthorized, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, publishedBuildId, appSourceId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, appSourceId, basePath, vendorPreconnectOrigins, vendorPreloadTargets, buildImportMap } from './importmap.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
@@ -41,7 +41,7 @@ export async function ssrPage(route, params, url, opts) {
   // and is threaded back through `opts.pageModule` so renderChain reuses the
   // same evaluation (no double-load). A cache HIT serves the stored HTML
   // without re-running the page function. Skipped entirely (no opt-in read,
-  // no double behaviour) for the page-action re-render (actionData / a non-200
+  // no double behaviour) for the form-action re-render (actionData / a non-200
   // status) and for a partial-nav request (X-Webjs-Have), whose bytes depend
   // on the request and must not be shared under the full-URL key.
   const cacheEligible =
@@ -297,7 +297,7 @@ export async function ssrPage(route, params, url, opts) {
       outBody,
       closer,
       suspenseCtx,
-      // Normally 200. After a failed page `action` submission the caller passes
+      // Normally 200. After a failed form-action submission the caller passes
       // 422 (or another 4xx) so the re-rendered page with field errors carries
       // the right status for both the no-JS reload and the enhanced swap (#244).
       opts.status || 200,
@@ -346,7 +346,7 @@ export async function ssrPage(route, params, url, opts) {
       // navigation (an auth bounce, a gate). 302 Found is the conventional
       // code there, so it is the default when the caller did not pick one. An
       // explicit `redirect(url, status)` overrides it. (Action redirects, a
-      // POST, default to 307 in page-action.js so the method is preserved.)
+      // POST, default to 307 in form-dispatch.js so the method is preserved.)
       return new Response(null, { status: e.status || 302, headers: { location: e.url } });
     }
     if (isNotFound(err)) {
@@ -459,7 +459,7 @@ export async function ssrNotFound(notFoundFile, opts) {
 /**
  * 403 response for a thrown forbidden() (#848). Renders the nearest
  * forbidden.{js,ts} in the page's chain, else a default 403 page. Shared by the
- * page-render catch (ssr.js) and the page-action write path (page-action.js) so
+ * page-render catch (ssr.js) and the form-action write path (form-dispatch.js) so
  * both behave identically.
  * @param {{ forbiddens?: string[] }} route
  * @param {{ dev: boolean, appDir: string, req?: Request, url?: URL }} opts
@@ -674,10 +674,13 @@ async function ssrNotFoundHtml(notFoundFile, opts) {
 }
 
 async function renderChain(route, ctx, dev, suspenseCtx, have, pageModule) {
-  // Reuse a caller-supplied page module when present (the page-action
-  // re-render passes the exact module whose `action` just ran, so the
-  // failure re-render shares that single evaluation instead of re-importing
-  // and re-running the module's top-level side effects).
+  // Reuse a caller-supplied page module when present. The only producer is the
+  // HTML-cache path above, which loads the module to read `export const
+  // revalidate` and threads it back so this does not load it a second time.
+  // (The removed page `action` export used to be a second producer: it ran in
+  // the page module, so the 422 re-render could share that evaluation. A form
+  // action lives in a `.server.*` module instead, so the re-render loads the
+  // page module itself, exactly as a plain render does.)
   const page = pageModule || await loadModule(route.file, dev);
   if (!page.default) throw new Error(`Page ${route.file} must have a default export`);
   let tree = await page.default(ctx);
@@ -1657,6 +1660,36 @@ function wrapHead(opts) {
   // importmap-rails) applies nonce on every modulepreload tag for
   // the same reason.
   const noncePreload = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  // Core runtime modulepreload (#1118). Every module the boot imports pulls
+  // `@webjsdev/core`, but the boot script names only page and component URLs,
+  // so without this hint the browser discovers core only after one of those is
+  // fetched AND parsed: one full round trip into the load, which is exactly
+  // where the pre-boot click window lives on a cold, throttled connection.
+  //
+  // The href comes STRAIGHT from the importmap target (no `fp()` rewrite: the
+  // map's targets are already base-path-prefixed and content-hashed), so it is
+  // byte-identical to what the import resolves to. A differing href makes the
+  // browser treat the preload and the import as two resources and fetch core
+  // twice. That is why this copies the vendor loop below, not the module loop
+  // above. `vendorPreloadTargets` still excludes core deliberately; this hint
+  // is emitted from the head builder, not the vendor path.
+  //
+  // Gated on the boot actually shipping something. A fully elided page ships no
+  // boot module and must not be handed a preload for a runtime it never loads
+  // (#780), which also keeps it off `global-error.{js,ts}`, whose document is
+  // returned verbatim with no importmap and no boot script.
+  if (opts.moduleUrls.length || lazyEntries) {
+    const coreMap = buildImportMap();
+    const coreHref = coreMap.imports['@webjsdev/core'];
+    if (coreHref) {
+      const raw = coreMap.integrity ? coreMap.integrity[coreHref] : undefined;
+      const coreIntegrity = raw ? ` integrity="${escapeAttr(raw)}"` : '';
+      linkTags.push(
+        `<link rel="modulepreload" href="${escapeAttr(coreHref)}"` +
+        `${preloadCrossOriginAttr(coreHref)}${coreIntegrity}${noncePreload}>`,
+      );
+    }
+  }
   // 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
@@ -2039,7 +2072,7 @@ function reachedVendorSpecifiers(graph, entryFiles, componentUrls, appDir, elida
  * @param {string} prefix
  * @param {string} bodyHtml
  * @param {string} closer
- * @param {{ pending: {id: string, promise: Promise<unknown>}[], nextId: number }} ctx
+ * @param {{ pending: {id: string, promise: Promise<unknown>, formScope?: 'none'|'unbound'|'bound'|'unknown'}[], nextId: number }} ctx
  * @param {number} status
  * @param {Request | undefined} req
  * @param {URL | undefined} url
@@ -2052,7 +2085,7 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' });
   // Default: no caching. Pages are dynamic by default: the developer
   // opts in to caching explicitly via metadata.cacheControl. A non-200 does
-  // NOT inherit it (#1140): the page-action re-render is a 422 carrying the
+  // NOT inherit it (#1140): the form-action re-render is a 422 carrying the
   // submitter's own field values and errors, which must never be handed to a
   // shared cache just because the page opted into public caching.
   headers.set('cache-control', status === 200 ? (metadata?.cacheControl || 'no-store') : 'no-store');
@@ -2095,7 +2128,15 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
               try {
                 const resolved = await p.promise;
                 const sub = { pending: [], nextId: ctx.nextId, dev: ctx.dev };
-                const html = await renderToString(resolved, { ssr: true, suspenseCtx: sub });
+                // Carry the boundary's form scope (#1207). This is a fresh scan
+                // that cannot see the shell the boundary sits in, so without it
+                // a `<button formaction=${fn}>` inside a bound form's boundary
+                // reads as form-less and is refused, and the catch below turns
+                // that into an empty boundary on a 200 in production. 'unknown'
+                // when the entry predates the field: defer rather than refuse.
+                const html = await renderToString(resolved, {
+                  ssr: true, suspenseCtx: sub, formScope: p.formScope || 'unknown',
+                });
                 ctx.nextId = sub.nextId;
                 for (const n of sub.pending) ctx.pending.push(n);
                 return { id: p.id, html };
@@ -2141,13 +2182,12 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
  * serves a single evaluation; in dev a cache-bust query forces a fresh
  * evaluation so source edits take effect (which also re-runs the module's
  * top-level side effects, the reason pages/layouts must keep their top level
- * side-effect-free). Exported so page-action.js loads the page module the same
- * way the SSR re-render does.
+ * side-effect-free).
  *
  * @param {string} file
  * @param {boolean} dev
  */
-export async function loadModule(file, dev) {
+async function loadModule(file, dev) {
   const url = pathToFileURL(file).toString();
   const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
   return import(url + bust);

package/src/stream.js

@@ -6,7 +6,7 @@
  * The payload is plain HTML, a `<webjs-stream action target>` wrapping one
  * `<template>`. These helpers compose that string for the two delivery paths,
  * a content-negotiated HTTP form response and a `broadcast()` / WS message, so
- * an app never hand-writes the markup. A page `action` or a `route` handler
+ * an app never hand-writes the markup. A form-bound action or a `route` handler
  * branches on `acceptsStream(request)`, returning `streamResponse(...)` when the
  * router asked for a stream and a normal render otherwise (the JS-off degrade).
  *

package/src/testing.d.ts

@@ -42,6 +42,25 @@ export declare function withCookies(init: RequestInit | undefined, cookieValue:
 /** Merge a session cookie string into a `RequestInit`'s `Cookie` header. */
 export declare function withSessionCookie(init: RequestInit | undefined, sessionCookie: string): RequestInit;
 
+/**
+ * Submit a page's `<form action={action}>` the way a browser with JS OFF does:
+ * render the page, reuse the identity the server put in its hidden
+ * `__webjs_action` field, and POST it back with the given fields. A POST that
+ * omits that field is not a form submission and is answered `405`.
+ */
+export declare function submitForm(
+  handle: Handle,
+  path: string,
+  fields?: Record<string, string> | URLSearchParams | FormData,
+  opts?: {
+    index?: number;
+    match?: string | RegExp;
+    cookies?: string;
+    submitPath?: string;
+    headers?: Record<string, string>;
+  },
+): Promise<Response>;
+
 /**
  * Drive the REAL credentials login (`POST /api/auth/signin/credentials` by
  * default) and capture the genuine signed session `Set-Cookie`.

package/src/testing.js

@@ -33,6 +33,7 @@
  */
 
 import { hashFile, RPC_CONTENT_TYPE } from './actions.js';
+import { FORM_ACTION_FIELD } from '@webjsdev/core';
 import { getSerializer } from './serializer.js';
 import { join, sep } from 'node:path';
 
@@ -200,6 +201,118 @@ export async function loginAndGetCookies(handle, credentials, opts = {}) {
   return { cookies, setCookies, response: res };
 }
 
+/**
+ * Submit a page's `<form action=${action}>` the way a browser with JS OFF does
+ * (#1155): render the page, take the identity the server put in its hidden
+ * `__webjs_action` field, and POST it back with the author's fields.
+ *
+ * A bound form carries that field because the identity is what tells the
+ * dispatcher WHICH action to run, so a hand-written POST that omits it is not a
+ * form submission at all and is answered `405`. Reproducing the scrape in every
+ * app test is how that ends up looking like a database problem instead: the
+ * status is wrong, an assertion fails, and a `catch` around it reports a skip.
+ * Hence a helper, so the identity is never the test's business.
+ *
+ * The form is located by INDEX (`opts.index`, default the first on the page),
+ * which is enough for the common one-form page. For a page with several, pass
+ * `opts.match`: a string or RegExp that must appear in the form's markup, so
+ * the test names the form by something an author recognizes (a heading, a field
+ * name, an id) rather than by counting.
+ *
+ * @param {Handle} handle
+ * @param {string} path the page to render AND, by default, to submit back to
+ * @param {Record<string, string> | URLSearchParams | FormData} [fields]
+ * @param {{
+ *   index?: number,
+ *   match?: string | RegExp,
+ *   cookies?: string,
+ *   submitPath?: string,
+ *   headers?: Record<string, string>,
+ * }} [opts]
+ * @returns {Promise<Response>} the submission response (a `303` on success, a
+ *   `422` re-render on a failure result)
+ */
+/**
+ * The `<form>...</form>` blocks of a rendered page.
+ *
+ * A bare `/<form[\s\S]*?<\/form>/g` gets two things wrong that a test helper
+ * must not, because both fail SILENTLY: a form inside an HTML comment is
+ * matched (so `opts.index` counts a form that is not on the page), and a
+ * `</form>` sitting inside an ATTRIBUTE VALUE ends the match early (so the
+ * identity field falls outside it and the helper reports an unbound form).
+ * Comments are stripped first, and the scan skips quoted attribute values while
+ * looking for the end of the start tag.
+ *
+ * @param {string} html
+ * @returns {string[]}
+ */
+function findForms(html) {
+  const src = html.replace(/<!--[\s\S]*?-->/g, '');
+  const out = [];
+  const open = /<form\b/gi;
+  let m;
+  while ((m = open.exec(src))) {
+    // Walk the start tag, skipping quoted values so `data-x="<form>"` is inert.
+    let i = m.index + m[0].length;
+    let quote = '';
+    for (; i < src.length; i++) {
+      const c = src[i];
+      if (quote) { if (c === quote) quote = ''; continue; }
+      if (c === '"' || c === "'") { quote = c; continue; }
+      if (c === '>') break;
+    }
+    const close = src.toLowerCase().indexOf('</form>', i);
+    if (close === -1) continue;
+    out.push(src.slice(m.index, close + '</form>'.length));
+    open.lastIndex = close;
+  }
+  return out;
+}
+
+export async function submitForm(handle, path, fields = {}, opts = {}) {
+  const getInit = opts.cookies ? withCookies({}, opts.cookies) : {};
+  const page = await testRequest(handle, path, getInit);
+  const html = await page.text();
+
+  const forms = findForms(html);
+  const candidates = opts.match
+    ? forms.filter((f) => (opts.match instanceof RegExp ? opts.match.test(f) : f.includes(opts.match)))
+    : forms;
+  const form = candidates[opts.index || 0];
+  if (!form) {
+    throw new Error(
+      `submitForm: no ${opts.match ? 'matching ' : ''}<form> found on ${path} `
+      + `(status ${page.status}, ${forms.length} form(s) on the page).`,
+    );
+  }
+  const id = form.match(/name="__webjs_action"\s+value="([^"]*)"/);
+  if (!id) {
+    throw new Error(
+      `submitForm: the <form> on ${path} carries no __webjs_action field, so it `
+      + 'is not bound to a server action. Write it as `<form action=${myAction}>` '
+      + 'with the action imported from a `use server` module.',
+    );
+  }
+
+  const body = new URLSearchParams();
+  body.set(FORM_ACTION_FIELD, id[1]);
+  const entries = fields instanceof URLSearchParams || fields instanceof FormData
+    ? fields.entries()
+    : Object.entries(fields);
+  for (const [k, v] of entries) body.append(k, String(v));
+
+  const init = {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', ...(opts.headers || {}) },
+    body: body.toString(),
+  };
+  return await testRequest(
+    handle,
+    opts.submitPath || path,
+    opts.cookies ? withCookies(init, opts.cookies) : init,
+  );
+}
+
 /**
  * Compute the RPC endpoint path for an action, addressing it the same way the
  * generated client stub does: by the SHA-256 hash of the action's ABSOLUTE file