@webjsdev/server 0.8.24 → 0.8.26

package/src/actions.js

@@ -1,13 +1,21 @@
 import { digestHex } from './crypto-utils.js';
 import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
-import { join, relative, sep } from 'node:path';
-import { getExposed } from '@webjsdev/core';
+import { join, sep } from 'node:path';
 import { walk } from './fs-walk.js';
 import { verify as verifyCsrf, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
 import { getSerializer } from './serializer.js';
-import { resolveOrigin } from './cors.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
+import {
+  actionMethod, actionFunctionNames, actionCache, actionConfigFn, resolveTags,
+  cacheControlFor, allowedRequestMethods, URL_ARG_VERBS, SAFE_VERBS, MAX_URL_ARGS,
+  RESERVED_CONFIG, actionMiddleware,
+} from './action-config.js';
+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 { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
@@ -35,9 +43,9 @@ export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 
 /**
  * Run an attached input validator against an action's input, shared by the RPC
- * path (`invokeAction`) and the `expose()` REST path (`invokeExposedAction`) so
- * the contract is identical across transports (#245). The framework only CALLS
- * the validator and shapes the result; it ships no validation library.
+ * path (`invokeAction`) and the `route()` REST adapter so the contract is
+ * identical across transports (#245). The framework only CALLS the validator and
+ * shapes the result; it ships no validation library.
  *
  * @param {(input: any) => any} validate the attached validator
  * @param {any} input the value handed to the validator (the action's first arg
@@ -118,56 +126,41 @@ async function rpcResponse(payload, init = {}) {
  * The server:
  *   1. Scans the app tree lazily on the first request (in `ensureReady`),
  *      classifying server files into RPC-callable actions vs. server-only
- *      utilities. Hashing is eager-per-file; only `expose()` files load.
+ *      utilities. Hashing is eager-per-file; no module is loaded here.
  *   2. Serves a generated ES-module stub when the browser imports
  *      the file URL (an RPC stub for actions, a throw-at-load stub
  *      for server-only utilities).
- *   3. Exposes POST endpoints at /__webjs/action/:hash/:fn for
- *      RPC-callable actions only.
- *   4. If an exported function was wrapped in `expose('METHOD /path', fn)`,
- *      also registers it as a first-class REST endpoint.
- *
- * @typedef {{
- *   method: string,
- *   pattern: RegExp,
- *   paramNames: string[],
- *   file: string,
- *   fnName: string,
- *   validate: ((input: any) => any) | null,
- *   cors: { origin: string | string[], credentials: boolean, maxAge: number, headers: string[] | null } | null,
- * }} ExposedRoute
+ *   3. Exposes endpoints at /__webjs/action/:hash/:fn for
+ *      RPC-callable actions only. A public REST endpoint is a `route.ts`
+ *      that imports and calls the action (optionally via the `route()`
+ *      adapter in `action-route.js`).
  *
  * @typedef {{
  *   hashToFile: Map<string,string>,
  *   fileToHash: Map<string,string>,
- *   httpRoutes: ExposedRoute[],
  *   appDir: string,
  *   dev: boolean,
  * }} ActionIndex
  */
 
 /**
- * Build the action index by scanning the app directory.
+ * Build the action index by scanning the app directory. This is a pure
+ * file -> hash mapping: it walks `app/`, classifies `.server.*` + `'use server'`
+ * files as RPC-callable actions, and records the hash both ways. It loads NO
+ * module (the hash index is all the analysis needs; a module is imported on
+ * demand by `invokeAction` / `serveActionStub`), so it is safe for a read-only
+ * introspection caller (the MCP `list_actions` tool, #262) with no top-level
+ * side effects (Prisma init, DB connect).
  *
  * @param {string} appDir
  * @param {boolean} dev
- * @param {{ skipExposeLoad?: boolean }} [opts]
- *   `skipExposeLoad: true` builds the (load-free) `fileToHash` / `hashToFile`
- *   maps WITHOUT importing any `expose()`-referencing module, so `httpRoutes`
- *   stays empty. A read-only introspection caller (the MCP `list_actions` tool,
- *   #262) uses this to derive RPC endpoint hashes without running a server
- *   module's top-level side effects (Prisma init, DB connect) or risking a
- *   stray stdout write. The request pipeline keeps the default (loads expose
- *   routes, which the router must know before a request can hit them).
  * @returns {Promise<ActionIndex>}
  */
-export async function buildActionIndex(appDir, dev, opts = {}) {
+export async function buildActionIndex(appDir, dev) {
   /** @type {Map<string,string>} */
   const hashToFile = new Map();
   /** @type {Map<string,string>} */
   const fileToHash = new Map();
-  /** @type {ExposedRoute[]} */
-  const httpRoutes = [];
 
   for await (const file of walk(appDir, (p) => /\.m?[jt]s$/.test(p))) {
     // Path-level: only `.server.{ts,js,mts,mjs}` files are server-only.
@@ -189,50 +182,10 @@ export async function buildActionIndex(appDir, dev, opts = {}) {
     // serveActionStub import the module on demand (first RPC call / first stub
     // fetch), so the hash index above is all the analysis needs. Eagerly
     // running every server module (and its transitive Prisma init, DB
-    // connects, etc.) would be wasted work. The one thing that DOES need eager loading is expose(),
-    // which registers a REST route the router must know before any request can
-    // hit it. So load only files that REFERENCE expose. We match the bare
-    // `expose` identifier (not `expose(`) so an aliased import
-    // (`import { expose as exp }`, whose import clause still names `expose`) is
-    // not missed: missing it would silently 404 that file's REST route. A stray
-    // mention in a comment or string only over-matches, costing one harmless
-    // extra module load; the common pure-RPC file never names `expose` and so
-    // still defers entirely.
-    // A read-only caller (MCP introspection) only needs the file -> hash maps
-    // above, so skip the expose-load entirely (no module side effects).
-    if (opts.skipExposeLoad) continue;
-    let src = '';
-    try { src = await readFile(file, 'utf8'); } catch {}
-    if (!/\bexpose\b/.test(src)) continue;
-    try {
-      const mod = await loadModule(file, dev);
-      for (const [name, fn] of Object.entries(mod)) {
-        if (typeof fn !== 'function') continue;
-        const http = getExposed(fn);
-        if (!http) continue;
-        // A `validateInput(fn, ...)` attachment writes `__webjsHttp` with a
-        // `validate` but NO `method`/`path` (it does not create a REST route),
-        // so it is not an exposed route. Only `expose()` sets a path; skip a
-        // validate-only attachment here (its validator is read at RPC call
-        // time via getExposed in invokeAction).
-        if (!http.path || !http.method) continue;
-        const { pattern, paramNames } = pathToPattern(http.path);
-        httpRoutes.push({
-          method: http.method,
-          pattern,
-          paramNames,
-          file,
-          fnName: name,
-          validate: http.validate || null,
-          cors: http.cors || null,
-        });
-      }
-    } catch (e) {
-      console.error(`[webjs] failed to scan server module ${file}:`, e);
-    }
+    // connects, etc.) would be wasted work.
   }
 
-  return { hashToFile, fileToHash, httpRoutes, appDir, dev };
+  return { hashToFile, fileToHash, appDir, dev };
 }
 
 /** @param {string} file @returns {Promise<string>} */
@@ -327,66 +280,152 @@ throw new Error(${JSON.stringify(msg)});
 export async function serveActionStub(idx, absFile) {
   const mod = await loadModule(absFile, idx.dev);
   const hash = idx.fileToHash.get(absFile) || await hashFile(absFile);
-  const fnNames = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
-  if (typeof mod.default === 'function' && !fnNames.includes('default')) {
-    fnNames.push('default');
-  }
+  // HTTP-verb actions (#488): the file declares its verb via `export const
+  // method` (default POST). The function exports are the actions; the reserved
+  // config exports (method/cache/tags/invalidates/validate/middleware) are excluded.
+  const fnNames = actionFunctionNames(mod);
+  const method = actionMethod(mod);
   // The RPC endpoint is a framework-emitted same-origin URL, so it must
   // carry the basePath prefix under a sub-path deploy (#256), exactly like
   // the importmap targets and the boot module specifiers. Without this the
   // stub would POST to a bare /__webjs/action/... that the ingress strip
   // 404s, breaking every server action when webjs.basePath is set.
   const actionUrl = withBasePath(`/__webjs/action/${hash}/`, basePath());
-  const body = `// webjs: generated server-action stub for ${relative(idx.appDir, absFile)}\n` +
-    `import { stringify as __wjStringify, parse as __wjParse, takeSeed as __seedTake, SEED_MISS as __SEED_MISS } from '@webjsdev/core';\n` +
-    `const __HASH = ${JSON.stringify(hash)};\n` +
-    `function __csrf() {\n` +
-    `  const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/);\n` +
-    `  return m ? decodeURIComponent(m[1]) : '';\n` +
-    `}\n` +
-    // The first client call of an async-render action reads the SSR seed
-    // (#472): __wjStringify(args) is BOTH the seed lookup key and the RPC body,
-    // so a miss reuses it for the POST with no double serialization. A hit
-    // resolves synchronously (no network), so hydration does not re-fetch; a
-    // later refetch / arg-change misses (consume-once) and goes to RPC.
-    `async function __call(fn, args) {\n` +
-    `  const body = await __wjStringify(args);\n` +
-    `  const seeded = __seedTake(__HASH, fn, body);\n` +
-    `  if (seeded !== __SEED_MISS) return seeded;\n` +
-    `  return __rpc(fn, args, body);\n` +
-    `}\n` +
-    `async function __rpc(fn, args, body) {\n` +
-    `  if (body === undefined) body = await __wjStringify(args);\n` +
-    `  const res = await fetch(${JSON.stringify(actionUrl)} + fn, {\n` +
-    `    method: 'POST',\n` +
-    `    headers: {\n` +
-    `      'content-type': ${JSON.stringify(RPC_CONTENT_TYPE)},\n` +
-    `      ${JSON.stringify(CSRF_HEADER)}: __csrf()\n` +
-    `    },\n` +
-    `    credentials: 'same-origin',\n` +
-    `    body\n` +
-    `  });\n` +
-    `  const ct = res.headers.get('content-type') || '';\n` +
-    `  const text = await res.text();\n` +
-    `  const parsed = ct.includes(${JSON.stringify(RPC_CONTENT_TYPE)})\n` +
-    `    ? __wjParse(text)\n` +
-    `    : (ct.includes('application/json') ? JSON.parse(text) : text);\n` +
-    `  if (!res.ok) {\n` +
-    `    const msg = (parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status);\n` +
-    `    throw new Error(msg);\n` +
-    `  }\n` +
-    `  return parsed;\n` +
-    `}\n` +
-    fnNames
-      .map((name) =>
-        name === 'default'
-          ? `export default (...args) => __call('default', args);`
-          : `export const ${name} = (...args) => __call(${JSON.stringify(name)}, args);`
-      )
-      .join('\n') + '\n';
+  const body = buildStubBody({ hash, method, fnNames, actionUrl });
   return body;
 }
 
+/**
+ * Build the generated client stub source for a `'use server'` action file. The
+ * transport depends on the file's declared `method`:
+ *   - GET: args ride the URL (`?a=`), the SSR seed (#472) is read first, the
+ *     browser HTTP cache is consulted, and a tag-invalidated key revalidates;
+ *     CSRF-exempt (a safe read). Over-large args fall back to a POST.
+ *   - DELETE: args ride the URL, CSRF-protected, over-large args fall back to a
+ *     POST.
+ *   - POST / PUT / PATCH: rich body, CSRF-protected.
+ * Every path reads `X-Webjs-Invalidate` (mark tags stale) and a GET reads
+ * `X-Webjs-Tags` (register the key's tags), so a later read sees a mutation.
+ * @param {{ hash: string, method: string, fnNames: string[], actionUrl: string }} opts
+ * @returns {string}
+ */
+function buildStubBody({ hash, method, fnNames, actionUrl }) {
+  const URL_ARG = URL_ARG_VERBS.has(method);
+  const SAFE = SAFE_VERBS.has(method);
+  const J = JSON.stringify;
+  const lines = [];
+  lines.push(`// webjs: generated server-action stub (${method})`);
+  // Every verb reads the SSR seed (#472) first: an async-render READ invoked
+  // during SSR is seeded regardless of its declared verb (a read with no
+  // `method` is a default POST), so the first client call resolves from the
+  // seed with no hydration round-trip. The browser-cache staleness check is
+  // GET-only (only a GET is browser-cached).
+  const imports = ['stringify as __s', 'parse as __p', 'takeSeed as __seedTake', 'SEED_MISS as __MISS', 'markStale as __markStale', 'parseTagHeader as __tagHdr', 'activeActionSignal as __sig',
+    // Streaming RPC (#489): an action returning a stream / async iterable sends
+    // back a framed body; the stub decodes it into an async iterable the caller
+    // `for await`s. The imports are small constants + one decoder factory.
+    'STREAM_CONTENT_TYPE as __STREAM_CT', 'createFrameDecoder as __frameDec', 'FRAME_CHUNK as __F_CHUNK', 'FRAME_END as __F_END', 'FRAME_ERROR as __F_ERR'];
+  if (method === 'GET') {
+    imports.push('registerKeyTags as __regTags', 'consumeStale as __stale', 'fetchMark as __mark');
+  }
+  lines.push(`import { ${imports.join(', ')} } from '@webjsdev/core';`);
+  lines.push(`const __URL = ${J(actionUrl)};`);
+  lines.push(`const __HASH = ${J(hash)};`);
+  lines.push(`const __METHOD = ${J(method)};`);
+  lines.push(`const __MAX = ${MAX_URL_ARGS};`);
+  lines.push(`const __CT = ${J(RPC_CONTENT_TYPE)};`);
+  lines.push(`function __csrf() { const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/); return m ? decodeURIComponent(m[1]) : ''; }`);
+  // Shared: parse a response, surface invalidation, register a GET's tags
+  // (stamped with the clock SAMPLED BEFORE the fetch, so a mutation in flight is
+  // caught on the next read).
+  lines.push(`async function __handle(res, fn, key, since) {`);
+  lines.push(`  const inv = __tagHdr(res.headers.get('x-webjs-invalidate')); if (inv.length) __markStale(inv);`);
+  lines.push(`  if (key != null) { const t = __tagHdr(res.headers.get('x-webjs-tags')); if (t.length) __regTags(key, t, since); }`);
+  lines.push(`  const ct = res.headers.get('content-type') || '';`);
+  // A streamed result (#489): the action returned a stream / async iterable.
+  // Return an async iterable that decodes the framed body and yields each
+  // deserialized chunk. The response is 200 (the stream started), so errors
+  // arrive as ERROR frames, not an HTTP status.
+  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(`  return parsed;`);
+  lines.push(`}`);
+  // Decode a framed streamed body into an async generator of rich-deserialized
+  // chunks. A CHUNK frame yields a value, END returns, ERROR throws the
+  // (author-controlled) message. The reader is released on completion / abort.
+  lines.push(`async function* __readStream(res, fn) {`);
+  lines.push(`  if (!res.body) throw new Error('webjs stream ' + fn + ' has no body');`);
+  lines.push(`  const reader = res.body.getReader();`);
+  lines.push(`  const dec = __frameDec();`);
+  lines.push(`  const td = new TextDecoder();`);
+  lines.push(`  let ended = false;`);
+  lines.push(`  try {`);
+  lines.push(`    for (;;) {`);
+  lines.push(`      const { value, done } = await reader.read();`);
+  lines.push(`      if (done) break;`);
+  lines.push(`      for (const f of dec.push(value)) {`);
+  lines.push(`        if (f.type === __F_CHUNK) yield __p(td.decode(f.payload));`);
+  lines.push(`        else if (f.type === __F_END) { ended = true; return; }`);
+  lines.push(`        else if (f.type === __F_ERR) throw new Error(td.decode(f.payload) || ('webjs stream ' + fn));`);
+  lines.push(`      }`);
+  lines.push(`    }`);
+  // The body ended without a terminal END/ERROR frame: the stream was truncated
+  // (a server crash, a dropped connection, an upstream timeout). A healthy
+  // stream always ends in END or ERROR, so surface this as an error rather than
+  // a silent clean completion. (A consumer that breaks early goes through the
+  // generator's return(), which skips this and runs only the finally.)
+  lines.push(`    if (!ended) throw new Error('webjs stream ' + fn + ' truncated (no end frame)');`);
+  lines.push(`  } finally { try { reader.cancel(); } catch {} try { reader.releaseLock(); } catch {} }`);
+  lines.push(`}`);
+  // Body sender (POST/PUT/PATCH, and the URL-arg too-large fallback). `sig` is
+  // captured SYNCHRONOUSLY at __call entry (#492): the active render signal must
+  // be read before the stub's first await (stringify), or the render's
+  // synchronous window has already closed and cleared it.
+  lines.push(`async function __body(fn, body, m, csrf, sig) {`);
+  lines.push(`  const headers = { 'content-type': __CT }; if (csrf) headers[${J(CSRF_HEADER)}] = __csrf();`);
+  lines.push(`  const res = await fetch(__URL + fn, { method: m, headers, credentials: 'same-origin', body, signal: sig });`);
+  lines.push(`  return __handle(res, fn, null);`);
+  lines.push(`}`);
+  if (URL_ARG) {
+    // GET/DELETE: args in the URL, with a POST fallback when too large.
+    lines.push(`async function __call(fn, args) {`);
+    lines.push(`  const sig = __sig();`); // sync capture before any await
+    lines.push(`  const key = await __s(args);`);
+    lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
+    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', ${SAFE ? 'false' : 'true'}, sig);`);
+    if (method === 'GET') {
+      lines.push(`  const bypass = __stale(key);`);
+      lines.push(`  const since = __mark();`);
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: 'GET', credentials: 'same-origin', cache: bypass ? 'no-cache' : 'default', signal: sig });`);
+      lines.push(`  return __handle(res, fn, key, since);`);
+    } else {
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, headers: { ${J(CSRF_HEADER)}: __csrf() }, credentials: 'same-origin', signal: sig });`);
+      lines.push(`  return __handle(res, fn, null);`);
+    }
+    lines.push(`}`);
+  } else {
+    // POST/PUT/PATCH: rich body. The seed read makes a default-POST async-render
+    // read resolve from the SSR seed on hydration (#472); a true mutation is
+    // never SSR-invoked, so the seed simply misses.
+    lines.push(`async function __call(fn, args) {`);
+    lines.push(`  const sig = __sig();`); // sync capture before any await
+    lines.push(`  const key = await __s(args);`);
+    lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
+    lines.push(`  return __body(fn, key, __METHOD, true, sig);`);
+    lines.push(`}`);
+  }
+  for (const name of fnNames) {
+    lines.push(
+      name === 'default'
+        ? `export default (...args) => __call('default', args);`
+        : `export const ${name} = (...args) => __call(${J(name)}, args);`,
+    );
+  }
+  return lines.join('\n') + '\n';
+}
+
 /**
  * Invoke a server action via the internal RPC wire format.
  * @param {ActionIndex} idx
@@ -399,34 +438,58 @@ export async function serveActionStub(idx, absFile) {
  *   it so a throwing sink can never affect the response.
  */
 export async function invokeAction(idx, hash, fnName, req, onError) {
-  if (!verifyCsrf(req)) {
-    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
-  }
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
-  // Bounded read (issue #237): reject an over-limit RPC body with 413 without
-  // buffering it whole (Content-Length fast-reject, plus a streaming cap for a
-  // chunked body with no declared length).
-  const { tooLarge, text: body } = await readTextBounded(req, jsonBodyLimit());
-  if (tooLarge) return payloadTooLarge();
+  const mod = await loadModule(file, idx.dev);
+  const fn = fnName === 'default' ? mod.default : mod[fnName];
+  // A reserved config export (method/cache/tags/invalidates/validate/middleware) is never
+  // a callable action even though some are functions (#488).
+  if (typeof fn !== 'function' || RESERVED_CONFIG.has(fnName)) {
+    return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
+  }
+
+  // HTTP-verb dispatch (#488). The action declares its method (default POST). A
+  // URL-arg verb (GET/DELETE) also accepts a POST fallback for over-large args.
+  const method = actionMethod(mod);
+  const reqMethod = req.method.toUpperCase();
+  const allowed = allowedRequestMethods(method);
+  if (!allowed.has(reqMethod)) {
+    return rpcResponse(
+      { error: `expected ${method} for ${fnName}, got ${reqMethod}` },
+      { status: 405, headers: { allow: [...allowed].join(', ') } },
+    );
+  }
+  // CSRF: required for every verb except a safe GET (a read with no state
+  // change, which is also browser-cacheable so it cannot carry a fresh token).
+  if (!SAFE_VERBS.has(method) && !verifyCsrf(req)) {
+    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
+  }
+
+  // Args ride the URL for a URL-arg request (GET / DELETE), else the body.
   let args = [];
+  const fromUrl = reqMethod === 'GET' || reqMethod === 'DELETE';
   try {
-    args = body ? getSerializer().deserialize(body) : [];
+    if (fromUrl) {
+      const a = new URL(req.url).searchParams.get('a');
+      args = a ? getSerializer().deserialize(a) : [];
+    } else {
+      const { tooLarge, text: body } = await readTextBounded(req, jsonBodyLimit());
+      if (tooLarge) return payloadTooLarge();
+      args = body ? getSerializer().deserialize(body) : [];
+    }
     if (!Array.isArray(args)) args = [args];
   } catch {
     return rpcResponse({ error: 'Invalid request body' }, { status: 400 });
   }
-  const mod = await loadModule(file, idx.dev);
-  const fn = fnName === 'default' ? mod.default : mod[fnName];
-  if (typeof fn !== 'function') return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
-  // Input validation (#245): a validator attached via `validateInput(fn, ...)`
-  // or `expose(spec, fn, { validate })` runs SERVER-SIDE before the body on
-  // this RPC path too, not just the REST path. The RPC stub sends an args
-  // array; an action conventionally takes one input object, so validate the
-  // FIRST arg (matching how the REST path validates its single merged object).
-  const attached = getExposed(fn);
-  if (attached && typeof attached.validate === 'function') {
-    const v = runValidate(attached.validate, args[0]);
+  // Input validation (#245): a validator declared via the `validate` config
+  // export (#488) runs SERVER-SIDE before the body on this RPC path. The RPC
+  // stub sends an args array; an action conventionally takes one input object,
+  // so validate the FIRST arg. Validation is a BOUNDARY concern: it runs on
+  // this RPC boundary (and the `route()` REST adapter), never on a direct
+  // server-to-server call.
+  const validate = actionConfigFn(mod, 'validate');
+  if (typeof validate === 'function') {
+    const v = runValidate(validate, args[0]);
     if (!v.ok) {
       if (v.thrown !== undefined) {
         // A THROWN validator behaves like a thrown action: a sanitized error
@@ -444,8 +507,45 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
     args = [v.value, ...args.slice(1)];
   }
   try {
-    const result = await fn(...args);
-    return rpcResponse(result ?? null);
+    // Run inside the request's AbortSignal scope (#492) and the per-action
+    // middleware chain (#490): the chain wraps the action, can short-circuit
+    // (an auth middleware returning an ActionResult), and accumulates context
+    // the action reads via actionContext(). `ranAction` distinguishes a real
+    // action completion from a middleware short-circuit (the action never ran).
+    const middleware = actionMiddleware(mod);
+    let ranAction = false;
+    const result = await runWithActionSignal(req.signal, () =>
+      runActionChain(middleware, { request: req, args, signal: req.signal }, () => { ranAction = true; return fn(...args); }));
+    // Streaming result (#489): a COMPLETED action returning a ReadableStream /
+    // async iterable streams its chunks over the RPC wire instead of buffering.
+    // A streamed result is never cached, ETagged, or seeded (it is not a
+    // serializer-safe value). A middleware short-circuit (the action never ran)
+    // is a plain envelope and falls through to the normal verb handling below.
+    if (ranAction && isStreamable(result)) {
+      const headers = {};
+      if (method !== 'GET') {
+        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 });
+    }
+    if (method === 'GET') {
+      // A short-circuit (the action did not run, e.g. an auth denial) is NEVER
+      // cached: serve the envelope no-store so a denial is not stored or shared.
+      if (!ranAction) return rpcResponse(result ?? null, { headers: { 'cache-control': 'no-store' } });
+      return await getActionResponse(result, mod, args, req);
+    }
+    // A mutation (POST/PUT/PATCH/DELETE): only a COMPLETED action evicts its
+    // `invalidates` tags; a short-circuit (the action never ran) does not.
+    const headers = {};
+    if (ranAction) {
+      const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
+      if (inv.length) {
+        await revalidateTags(inv);
+        headers['x-webjs-invalidate'] = inv.join(',');
+      }
+    }
+    return rpcResponse(result ?? null, { headers });
   } catch (e) {
     if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
@@ -453,163 +553,32 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
 }
 
 /**
- * Match an incoming request against an expose()d action route.
- * Returns the single matched route+params for normal methods.
- * @param {ActionIndex} idx
- * @param {string} method
- * @param {string} pathname
- */
-export function matchExposedAction(idx, method, pathname) {
-  for (const r of idx.httpRoutes) {
-    if (r.method !== method) continue;
-    const m = r.pattern.exec(pathname);
-    if (!m) continue;
-    /** @type {Record<string,string>} */
-    const params = {};
-    r.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1] || '')));
-    return { route: r, params };
-  }
-  return null;
-}
-
-/**
- * Find ALL exposed routes at a given path (any method). Used to build OPTIONS
- * preflight responses and Allow headers.
- * @param {ActionIndex} idx
- * @param {string} pathname
- */
-export function matchAllAtPath(idx, pathname) {
-  const out = [];
-  for (const r of idx.httpRoutes) {
-    if (r.pattern.exec(pathname)) out.push(r);
-  }
-  return out;
-}
-
-/**
- * Build CORS response headers given a route's CORS config + the request.
- * Returns null if CORS isn't configured for this route.
- *
- * @param {ExposedRoute} route
- * @param {Request} req
- */
-export function corsHeadersFor(route, req) {
-  if (!route.cors) return null;
-  const cfg = route.cors;
-  const origin = req.headers.get('origin') || '';
-  const allowed = matchOrigin(cfg.origin, origin);
-  if (!allowed && origin) return null;
-  const h = new Headers();
-  h.set('access-control-allow-origin', allowed === true ? '*' : allowed || origin);
-  if (cfg.credentials) h.set('access-control-allow-credentials', 'true');
-  h.append('vary', 'Origin');
-  return h;
-}
-
-/** @param {ExposedRoute} route @param {Request} req */
-export function buildPreflightResponse(route, req) {
-  const headers = corsHeadersFor(route, req);
-  if (!headers) return new Response(null, { status: 403 });
-  headers.set('access-control-allow-methods', `${route.method}, OPTIONS`);
-  const reqHdrs =
-    route.cors?.headers?.join(',') || req.headers.get('access-control-request-headers') || 'content-type';
-  headers.set('access-control-allow-headers', reqHdrs);
-  headers.set('access-control-max-age', String(route.cors?.maxAge ?? 86400));
-  return new Response(null, { status: 204, headers });
-}
-
-/** Apply CORS headers (if any) to an existing response. */
-export function withCors(resp, route, req) {
-  const h = corsHeadersFor(route, req);
-  if (!h) return resp;
-  const newHeaders = new Headers(resp.headers);
-  h.forEach((v, k) => newHeaders.set(k, v));
-  return new Response(resp.body, { status: resp.status, statusText: resp.statusText, headers: newHeaders });
-}
-
-/**
- * Match a route's configured origin policy against the request origin,
- * preserving the expose() path's historical contract: `*` returns `true`
- * (literal wildcard), an allowed concrete origin echoes back, and a
- * mismatch returns `null`. Delegates the per-rule decision to the shared
- * cors.js resolver (so RegExp + function policies work here too) but keeps
- * the wildcard-as-`true` and echo-vs-null shape this caller expects.
- *
- * @param {string|string[]|RegExp|((origin: string) => boolean)} configured
- * @param {string} origin
- * @returns {true | string | null}
- */
-function matchOrigin(configured, origin) {
-  if (configured === '*') return true;
-  const resolved = resolveOrigin(configured, origin, false);
-  if (!resolved) return null;
-  return resolved.allowOrigin === '*' ? true : resolved.allowOrigin;
-}
-
-/**
- * Invoke an exposed action as a REST endpoint.
- * Builds a single object argument from URL params + query + JSON body.
- * @param {ActionIndex} idx
- * @param {ExposedRoute} route
- * @param {Record<string,string>} params
+ * Build a GET action's response (#488): the serialized body plus a weak ETag
+ * (content hash), the `Cache-Control` from the `cache` config (else `no-store`),
+ * and `X-Webjs-Tags`. Answers `If-None-Match` with a 304 itself rather than
+ * relying on the conditional-GET funnel, which EXCLUDES `private` responses (the
+ * default here); a per-user browser cache may still revalidate to a 304.
+ * @param {unknown} result
+ * @param {Record<string, unknown>} mod
+ * @param {unknown[]} args
  * @param {Request} req
- * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
- *   invoked when the exposed REST handler throws unexpectedly, BEFORE the
- *   sanitized 500 is returned, so an APM integration sees the original error.
- *   The caller wraps it so a throwing sink can never affect the response.
+ * @returns {Promise<Response>}
  */
-export async function invokeExposedAction(idx, route, params, req, onError) {
-  const url = new URL(req.url);
-  const query = Object.fromEntries(url.searchParams.entries());
-  let body = {};
-  if (req.method !== 'GET' && req.method !== 'HEAD') {
-    // Bounded read (issue #237): an over-limit body is a 413 before any parse.
-    const { tooLarge, text } = await readTextBounded(req, jsonBodyLimit());
-    if (tooLarge) return payloadTooLarge();
-    if (text) {
-      try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) body = parsed;
-        else body = { body: parsed };
-      } catch {
-        return new Response('Invalid JSON body', { status: 400 });
-      }
-    }
-  }
-  let arg = { ...query, ...params, ...body };
-  if (route.validate) {
-    // Run the validator through the SHARED contract (#245) so the REST path and
-    // the RPC path interpret a `{ success, fieldErrors }` envelope, a throw, and
-    // a transform-return identically. A structured failure becomes a 422 JSON
-    // `{ error?, fieldErrors }` (not just a thrown 400); a throw stays a 400; a
-    // transform-return keeps replacing the input (back-compat).
-    const v = runValidate(route.validate, arg);
-    if (!v.ok) {
-      if (v.thrown !== undefined) {
-        // A thrown validator (the classic `Schema.parse` style): keep the exact
-        // legacy REST shape, including a schema lib's structured `issues` array.
-        const msg = v.result.error || 'Invalid input';
-        const issues = v.thrown && typeof v.thrown === 'object' && 'issues' in v.thrown
-          ? /** @type any */ (v.thrown).issues
-          : undefined;
-        return Response.json({ error: msg, issues }, { status: 400 });
-      }
-      const { status, ...payload } = v.result;
-      return Response.json(payload, { status });
-    }
-    arg = v.value;
+async function getActionResponse(result, mod, args, req) {
+  const s = getSerializer();
+  const bodyStr = await s.serialize(result ?? null);
+  const cache = actionCache(mod);
+  const etag = `W/"${(await digestHex('SHA-256', bodyStr)).slice(0, 16)}"`;
+  const headers = new Headers({ 'content-type': s.contentType, etag });
+  headers.set('cache-control', cacheControlFor('GET', cache) || 'no-store');
+  if (cache) {
+    const tags = resolveTags(actionConfigFn(mod, 'tags'), args);
+    if (tags.length) headers.set('x-webjs-tags', tags.join(','));
   }
-  const mod = await loadModule(route.file, idx.dev);
-  const fn = mod[route.fnName];
-  if (typeof fn !== 'function') return new Response(`Unknown action ${route.fnName}`, { status: 404 });
-  try {
-    const result = await fn(arg, { req, params });
-    if (result instanceof Response) return result;
-    return Response.json(result ?? null);
-  } catch (e) {
-    if (typeof onError === 'function') onError(e);
-    return actionErrorResponse(e, idx.dev);
+  if (ifNoneMatchSatisfied(req.headers.get('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
   }
+  return new Response(bodyStr, { status: 200, headers });
 }
 
 /**
@@ -636,20 +605,6 @@ function actionErrorResponse(err, dev) {
   return rpcResponse({ error: msg }, { status: 500 });
 }
 
-/**
- * Convert an `expose()` path like `/api/posts/:slug` to a regex + param list.
- * Also accepts NextJs-style `[slug]` brackets for familiarity.
- * @param {string} path
- */
-function pathToPattern(path) {
-  const paramNames = [];
-  const re = path.replace(/:([A-Za-z_][A-Za-z0-9_]*)|\[([A-Za-z_][A-Za-z0-9_]*)\]/g, (_, a, b) => {
-    paramNames.push(a || b);
-    return '([^/]+)';
-  });
-  return { pattern: new RegExp(`^${re}/?$`), paramNames };
-}
-
 /**
  * @param {string} file
  * @param {boolean} dev