@webjsdev/server 0.8.24 → 0.8.25

package/index.d.ts

@@ -844,3 +844,11 @@ export declare function GitHub(opts?: Record<string, unknown>): ProviderConfig;
 // ---------------------------------------------------------------------------
 
 export type { LayoutProps, PageProps, RouteHandlerContext };
+
+/** The current action request AbortSignal (#492), or a never-aborting signal outside an action. */
+export declare function actionSignal(): AbortSignal;
+/** Run a function with a request AbortSignal available to actionSignal() (#492). */
+export declare function runWithActionSignal<T>(signal: AbortSignal | undefined, fn: () => T): T;
+
+/** The accumulated per-action middleware context (#490), or {} outside an action. */
+export declare function actionContext(): Record<string, unknown>;

package/index.js

@@ -48,6 +48,8 @@ export { cors, resolveOrigin, applyCorsHeaders } from './src/cors.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
 export { revalidateTag, revalidateTags } from './src/cache-tags.js';
+export { actionSignal, runWithActionSignal } from './src/action-signal.js';
+export { actionContext } from './src/action-middleware.js';
 export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';

package/package.json

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

package/src/action-config.js

@@ -0,0 +1,162 @@
+/**
+ * HTTP-verb server actions (#488): read the per-action configuration declared as
+ * RESERVED sibling exports in a `'use server'` action file, and the helpers that
+ * turn that config into transport + caching behavior.
+ *
+ * The function stays a plain `export async function`; the framework reads these
+ * statically-named exports the same way a page declares `export const
+ * revalidate` / `metadata`:
+ *
+ *   'use server';
+ *   export const method = 'GET';                 // 'GET'|'POST'|'PUT'|'PATCH'|'DELETE'; absent => POST
+ *   export const cache = 60;                      // seconds, or { maxAge, swr, public }
+ *   export const tags = (id) => [`user:${id}`];   // GET: tags the cached read
+ *   export const invalidates = (id) => [...];     // mutation: tags to evict
+ *   export const validate = (input) => ...;       // boundary validator
+ *   export async function getUser(id) { ... }     // THE action (one per file)
+ *
+ * No folder automation: an action with no `method` export stays a POST, exactly
+ * as before this feature (additive, non-breaking).
+ */
+
+/** The HTTP verbs an action may declare. */
+export const RPC_VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** Reserved config export names (special only in a `'use server'` file). */
+export const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'validate', 'middleware']);
+
+/** Verbs whose args ride the URL (so the read is cacheable / the URL is the key). */
+export const URL_ARG_VERBS = new Set(['GET', 'DELETE']);
+
+/** Verbs that are CSRF-exempt (safe, no state change). */
+export const SAFE_VERBS = new Set(['GET']);
+
+/**
+ * Max length of the URL-encoded args for a URL-arg verb before the client stub
+ * falls back to a POST with the args in the body (uncacheable). Conservative so
+ * the URL stays within common browser / CDN limits. TanStack Start uses 1MB for
+ * its server-side GET cap; the browser/CDN URL ceiling is the tighter bound.
+ */
+export const MAX_URL_ARGS = 4096;
+
+/**
+ * The exported function names that are ACTIONS (callable), i.e. every function
+ * export whose name is not a reserved config key. With one-function-per-file
+ * there is exactly one; the framework still returns the list so a misconfigured
+ * multi-function file is detectable (a `webjs check` rule).
+ * @param {Record<string, unknown>} mod
+ * @returns {string[]}
+ */
+export function actionFunctionNames(mod) {
+  const names = Object.keys(mod).filter(
+    (k) => typeof mod[k] === 'function' && !RESERVED_CONFIG.has(k),
+  );
+  if (typeof mod.default === 'function' && !names.includes('default')) names.push('default');
+  return names;
+}
+
+/**
+ * The action's HTTP method: the declared `method` export uppercased and
+ * validated against {@link RPC_VERBS}, defaulting to POST (an unknown value
+ * falls back to POST rather than throwing, the #232 fail-safe posture).
+ * @param {Record<string, unknown>} mod
+ * @returns {string}
+ */
+export function actionMethod(mod) {
+  const raw = mod && mod.method;
+  if (typeof raw !== 'string') return 'POST';
+  const m = raw.trim().toUpperCase();
+  return RPC_VERBS.has(m) ? m : 'POST';
+}
+
+/**
+ * Normalize the `cache` export to `{ maxAge, swr, public }` or null (no
+ * caching). A number is `maxAge` seconds; an object carries `maxAge` / `swr`
+ * (stale-while-revalidate) / `public`. Default `private` (a read is per-user
+ * safe unless the author opts into shared caching with `public: true`).
+ * @param {Record<string, unknown>} mod
+ * @returns {{ maxAge: number, swr: number, public: boolean } | null}
+ */
+export function actionCache(mod) {
+  const raw = mod && mod.cache;
+  if (raw == null) return null;
+  if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) {
+    return { maxAge: Math.floor(raw), swr: 0, public: false };
+  }
+  if (typeof raw === 'object') {
+    const maxAge = Number.isFinite(raw.maxAge) && raw.maxAge >= 0 ? Math.floor(raw.maxAge) : 0;
+    const swr = Number.isFinite(raw.swr) && raw.swr >= 0 ? Math.floor(raw.swr) : 0;
+    return { maxAge, swr, public: raw.public === true };
+  }
+  return null;
+}
+
+/**
+ * The action's per-action middleware chain (#490): the `middleware` export, an
+ * array of `(ctx, next) => result` functions, or [] when absent / malformed.
+ * @param {Record<string, unknown>} mod
+ * @returns {Function[]}
+ */
+export function actionMiddleware(mod) {
+  const raw = mod && mod.middleware;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((m) => typeof m === 'function');
+}
+
+/**
+ * Resolve the `tags` / `invalidates` / `validate` config functions off the
+ * module (each is a function or absent).
+ * @param {Record<string, unknown>} mod
+ * @param {'tags'|'invalidates'|'validate'} name
+ * @returns {Function | null}
+ */
+export function actionConfigFn(mod, name) {
+  return mod && typeof mod[name] === 'function' ? mod[name] : null;
+}
+
+/**
+ * Compute the tag list for a `tags` / `invalidates` config given the call args.
+ * A function is invoked with the args (so `(id) => [`user:${id}`]` works); an
+ * array is used verbatim. Never throws into the caller; a bad tag fn yields [].
+ * @param {Function | unknown[] | null} tagsConfig
+ * @param {unknown[]} args
+ * @returns {string[]}
+ */
+export function resolveTags(tagsConfig, args) {
+  try {
+    const out = typeof tagsConfig === 'function' ? tagsConfig(...args) : tagsConfig;
+    if (!Array.isArray(out)) return [];
+    return out.filter((t) => typeof t === 'string' && t.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The `Cache-Control` value for a GET action response, or null (caller emits
+ * `no-store`). A cached GET is `public|private, max-age=N[, stale-while-
+ * revalidate=M]`; a GET with no `cache` config is uncached (null -> no-store).
+ * @param {string} method
+ * @param {{ maxAge: number, swr: number, public: boolean } | null} cache
+ * @returns {string | null}
+ */
+export function cacheControlFor(method, cache) {
+  if (method !== 'GET' || !cache) return null;
+  const scope = cache.public ? 'public' : 'private';
+  let h = `${scope}, max-age=${cache.maxAge}`;
+  if (cache.swr > 0) h += `, stale-while-revalidate=${cache.swr}`;
+  return h;
+}
+
+/**
+ * The set of request methods the action endpoint accepts for an action whose
+ * declared method is `method`. A URL-arg verb (GET/DELETE) ALSO accepts POST as
+ * the too-large-args fallback; a body verb accepts only itself.
+ * @param {string} method
+ * @returns {Set<string>}
+ */
+export function allowedRequestMethods(method) {
+  const s = new Set([method]);
+  if (URL_ARG_VERBS.has(method)) s.add('POST');
+  return s;
+}

package/src/action-middleware.d.ts

@@ -0,0 +1,21 @@
+/** Per-action middleware (#490). */
+
+/** The context object middleware accumulate and the action reads via actionContext(). */
+export interface ActionContext { [key: string]: unknown }
+
+/** A middleware's ctx: the request, the action args, the abort signal, and the shared context. */
+export interface ActionMiddlewareCtx {
+  request?: Request;
+  args?: unknown[];
+  signal?: AbortSignal;
+  context: ActionContext;
+}
+
+/** A per-action middleware: run `next()` to proceed, or return a value to short-circuit. */
+export type ActionMiddleware = (ctx: ActionMiddlewareCtx, next: () => Promise<unknown>) => unknown;
+
+/** The accumulated middleware context for the current action, or {} outside one. */
+export declare function actionContext(): ActionContext;
+
+/** Run an action through its middleware chain (framework-internal). */
+export declare function runActionChain(middleware: ActionMiddleware[], baseCtx: Partial<ActionMiddlewareCtx>, finalFn: () => unknown): Promise<unknown>;

package/src/action-middleware.js

@@ -0,0 +1,68 @@
+/**
+ * Per-action middleware (#490). An action file declares `export const middleware
+ * = [mw1, mw2]` (a reserved config export). Each middleware is
+ * `async (ctx, next) => result`, run around the action on BOTH the RPC endpoint
+ * and the `route.ts`/`expose()` boundary, like `validate`.
+ *
+ *   - `ctx` carries `{ request, args, signal, context }`. `context` is a shared
+ *     mutable object the chain accumulates; the action reads it via
+ *     `actionContext()` (no signature change, the same plumbing as
+ *     `actionSignal()`).
+ *   - `next()` runs the next middleware, ending at the action; its return value
+ *     flows back up. A middleware SHORT-CIRCUITS by returning a value (an
+ *     `ActionResult` envelope, e.g. `{ success: false, status: 401 }`) WITHOUT
+ *     calling `next()`, so the action never runs. A short-circuit is NOT a
+ *     completion: a GET short-circuit is served `no-store` (never cached) and a
+ *     mutation short-circuit does not run `invalidates`. On the RPC boundary the
+ *     short-circuit must be an `ActionResult` (serialized as the result, the
+ *     `status` riding inside per the #245 contract); on the `route.ts` / REST
+ *     boundary it may also be a `Response`, and an `ActionResult`'s `status`
+ *     maps to the HTTP status.
+ *
+ * The framework ships no middleware; it only runs the chain. Server-only.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** Per-request accumulated context, readable by the action via actionContext(). */
+const als = new AsyncLocalStorage();
+
+/** Shared empty context returned outside an action (a direct server-to-server call). */
+const EMPTY = Object.freeze({});
+
+/**
+ * The accumulated middleware context for the current action, or a frozen empty
+ * object outside an action. The action reads `actionContext().user` etc.
+ * @returns {Record<string, unknown>}
+ */
+export function actionContext() {
+  return als.getStore() || EMPTY;
+}
+
+/**
+ * Run `finalFn` (the action) through the middleware chain, with a fresh shared
+ * `context` available to `actionContext()` for the whole chain. A middleware
+ * that does not call `next()` short-circuits (its return is the result). Guards
+ * against a middleware calling `next()` more than once.
+ * @param {Function[]} middleware
+ * @param {{ request?: Request, args?: unknown[], signal?: AbortSignal }} baseCtx
+ * @param {() => unknown} finalFn
+ * @returns {Promise<unknown>}
+ */
+export function runActionChain(middleware, baseCtx, finalFn) {
+  if (!middleware || middleware.length === 0) return finalFn();
+  const context = {};
+  const ctx = { ...baseCtx, context };
+  return als.run(context, () => {
+    let lastCalled = -1;
+    const dispatch = (i) => {
+      if (i <= lastCalled) {
+        return Promise.reject(new Error('next() called multiple times in a webjs action middleware'));
+      }
+      lastCalled = i;
+      const mw = middleware[i];
+      if (!mw) return finalFn();
+      return mw(ctx, () => dispatch(i + 1));
+    };
+    return dispatch(0);
+  });
+}

package/src/action-signal.js

@@ -0,0 +1,39 @@
+/**
+ * Server-side action AbortSignal (#492). The RPC endpoint runs an action inside
+ * `runWithActionSignal(req.signal, fn)`, so the action can read the request's
+ * AbortSignal via `actionSignal()` and stop expensive work (a DB query, an
+ * upstream fetch) when the client disconnects or aborts the call.
+ *
+ * Isomorphic-friendly: `actionSignal()` returns a never-aborting signal when
+ * called outside an action (e.g. a direct server-to-server call), so the same
+ * `fetch(url, { signal: actionSignal() })` line is safe everywhere.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const als = new AsyncLocalStorage();
+
+/** A shared signal that never aborts, returned outside an action. */
+const NEVER = (() => {
+  const c = new AbortController();
+  return c.signal;
+})();
+
+/**
+ * Run `fn` with `signal` available to `actionSignal()` for its async extent.
+ * @template T
+ * @param {AbortSignal | undefined} signal
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithActionSignal(signal, fn) {
+  return als.run(signal || NEVER, fn);
+}
+
+/**
+ * The current action's request AbortSignal (fires on client disconnect / abort),
+ * or a never-aborting signal outside an action.
+ * @returns {AbortSignal}
+ */
+export function actionSignal() {
+  return als.getStore() || NEVER;
+}

package/src/actions.js

@@ -8,6 +8,15 @@ 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 { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
@@ -327,66 +336,116 @@ 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'];
+  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') || '';`);
+  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(`}`);
+  // 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 +458,62 @@ 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).
+  // Validation is a BOUNDARY concern (#488): the validator is the `validate`
+  // config export (the new model), or the legacy `expose`/`validateInput`
+  // attachment. It runs on this RPC boundary on the FIRST arg (the conventional
+  // single input object), never on a direct server-to-server call.
   const attached = getExposed(fn);
-  if (attached && typeof attached.validate === 'function') {
-    const v = runValidate(attached.validate, args[0]);
+  const validate = actionConfigFn(mod, 'validate') || (attached && attached.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,14 +531,67 @@ 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); }));
+    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);
   }
 }
 
+/**
+ * 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
+ * @returns {Promise<Response>}
+ */
+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(','));
+  }
+  if (ifNoneMatchSatisfied(req.headers.get('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bodyStr, { status: 200, headers });
+}
+
 /**
  * Match an incoming request against an expose()d action route.
  * Returns the single matched route+params for normal methods.
@@ -603,8 +743,21 @@ export async function invokeExposedAction(idx, route, params, req, onError) {
   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 });
+    // The REST boundary wires the request signal (#492) and the per-action
+    // middleware chain (#490) too, symmetric with the RPC path. `ranAction`
+    // marks whether the action ran (vs a middleware short-circuit).
+    const middleware = actionMiddleware(mod);
+    let ranAction = false;
+    const result = await runWithActionSignal(req.signal, () =>
+      runActionChain(middleware, { request: req, args: [arg], signal: req.signal }, () => { ranAction = true; return fn(arg, { req, params }); }));
     if (result instanceof Response) return result;
+    // A middleware short-circuit on the REST boundary maps the envelope's
+    // `status` to the HTTP status (like the validate failure above), so a
+    // non-webjs REST client sees the real status, not a 200 with it in the body.
+    if (!ranAction && result && typeof result === 'object' && typeof result.status === 'number') {
+      const { status, ...payload } = result;
+      return Response.json(payload, { status });
+    }
     return Response.json(result ?? null);
   } catch (e) {
     if (typeof onError === 'function') onError(e);

package/src/check.js

@@ -10,6 +10,7 @@ import { buildModuleGraph, transitiveDeps } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
 import { buildRouteTable } from './router.js';
 import { analyzeElision } from './component-elision.js';
+import { RESERVED_CONFIG } from './action-config.js';
 
 /**
  * Convention validator for webjs apps.
@@ -107,6 +108,11 @@ export const RULES = [
     description:
       'A page / layout / component module that SHIPS to the browser (the build does NOT elide it) must not transitively import a server-only `.server.{ts,js}` module. The server module is replaced by a stub in the browser, so the import is fine while the page is display-only and elided (its server import is stripped), but the moment the page also does client work (it imports a component to register, enables the client router, uses a reactive primitive, …) it stops being elided and must load in the browser, dragging the server import with it. The stub then throws (or a server-only export like `auth` is missing) the instant the module loads, a runtime browser crash that `webjs typecheck` and the rest of `webjs check` miss. The rule reuses the build\'s own elision verdict, so it ONLY fires on modules that genuinely ship; a display-only page the framework elides is never flagged. The fix is to keep the server call off the browser-shipped module: gate the route in `middleware.ts`, call the server through a `\'use server\'` action, or register the component in a layout so the page elides again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
   },
+  {
+    name: 'one-action-per-configured-file',
+    description:
+      'A `\'use server\'` action file that declares HTTP-verb config (any of `method` / `cache` / `tags` / `invalidates` / `validate`, #488) must export exactly ONE callable action function. The config is file-level (it applies to the action in the file), so a second exported function would silently inherit the same verb / cache, which is almost never intended and makes the contract ambiguous. Move the extra function to its own `.server.ts` file (the one-function-per-file convention), or, if it is a private helper, do not export it. Files with no verb config are unaffected.',
+  },
   {
     name: 'no-scaffold-placeholder',
     description:
@@ -727,6 +733,37 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: one-action-per-configured-file (#488) ---
+  // A `'use server'` file that declares HTTP-verb config (method/cache/tags/
+  // invalidates/validate) must export exactly one callable action; the config
+  // is file-level, so a second exported function would silently inherit it.
+  {
+    for (const { rel, content, scan } of files) {
+      if (!/\.server\.m?[jt]s$/.test(rel)) continue;
+      if (!hasUseServerDirective(content)) continue;
+      if (!/\bexport\s+const\s+(?:method|cache|tags|invalidates|validate|middleware)\b/.test(scan)) continue;
+      const names = new Set();
+      let m;
+      const reFn = /\bexport\s+(?:async\s+)?function\s*\*?\s+([A-Za-z_$][\w$]*)/g;
+      while ((m = reFn.exec(scan))) names.add(m[1]);
+      // An arrow-const action: `export const x = (...) => ...`, the paren-less
+      // `export const x = id => ...`, or a function expression. The `=>` /
+      // `function` anchor keeps a plain `export const N = 5` from counting.
+      const reArrow = /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/g;
+      while ((m = reArrow.exec(scan))) names.add(m[1]);
+      if (/\bexport\s+default\b/.test(scan)) names.add('default');
+      const actions = [...names].filter((n) => !RESERVED_CONFIG.has(n));
+      if (actions.length > 1) {
+        violations.push({
+          rule: 'one-action-per-configured-file',
+          file: rel,
+          message: `Configured action file exports ${actions.length} callable functions (${actions.join(', ')}); the verb/cache config is file-level, so only one action per file is allowed.`,
+          fix: 'Move the extra function to its own .server.{js,ts} file, or keep it private (do not export it).',
+        });
+      }
+    }
+  }
+
   // --- Rule: tag-name-has-hyphen ---
   {
     for (const { rel, scan } of files) {

package/src/dev.js

@@ -1695,7 +1695,12 @@ async function handleCore(req, ctx) {
   // Internal server-action RPC endpoint
   const actMatch = /^\/__webjs\/action\/([a-f0-9]+)\/([A-Za-z0-9_$]+)$/.exec(path);
   if (actMatch) {
-    if (method !== 'POST') return new Response('POST only', { status: 405 });
+    // HTTP-verb actions (#488): any RPC verb may hit the endpoint; invokeAction
+    // enforces the action's DECLARED method (405 + Allow on a mismatch) and
+    // reads args from the URL (GET/DELETE) or the body (POST/PUT/PATCH).
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+      return new Response('method not allowed', { status: 405 });
+    }
     // Pass the onError sink (issue #239): a server action that throws
     // unexpectedly is reported to the APM hook before the sanitized 500.
     const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;