@webjsdev/server 0.8.25 → 0.8.27

package/index.d.ts

@@ -257,8 +257,8 @@ export declare function handleApi(
 // actions.js (server-action scanner + RPC endpoint)
 // ---------------------------------------------------------------------------
 
-/** Scan the app for `.server.{js,ts}` files and build the RPC + expose index. */
-export declare function buildActionIndex(appDir: string, dev: boolean, opts?: { skipExposeLoad?: boolean }): Promise<unknown>;
+/** Scan the app for `.server.{js,ts}` files and build the pure file -> hash RPC index. */
+export declare function buildActionIndex(appDir: string, dev: boolean): Promise<unknown>;
 /** Whether a file path is a `.server.{js,ts,mjs,mts}` server file. */
 export declare function isServerFile(file: string): boolean;
 /** SHA-256 hash of an action file's absolute path (the RPC endpoint addressing scheme). */
@@ -276,6 +276,22 @@ export declare function invokeAction(
   onError?: (error: unknown) => void,
 ): Promise<Response>;
 
+// ---------------------------------------------------------------------------
+// action-route.js
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a plain `'use server'` action as a `route.ts`-style REST handler (#488).
+ * Merges query + route params + JSON body into one input object, runs the
+ * optional boundary validator, and dispatches through the request abort signal
+ * + the optional middleware chain. The always-works baseline is a hand-written
+ * `route.ts` that imports and calls the action; this is the convenience.
+ */
+export declare function route<A, R>(
+  action: (input: A, ctx: { req: Request; params: Record<string, string> }) => R | Promise<R>,
+  opts?: { validate?: (input: any) => any; middleware?: Function[] },
+): (req: Request, ctx?: { params?: Record<string, string> }) => Promise<Response>;
+
 // ---------------------------------------------------------------------------
 // importmap.js
 // ---------------------------------------------------------------------------

package/index.js

@@ -13,6 +13,7 @@ export {
   serveActionStub,
   invokeAction,
 } from './src/actions.js';
+export { route } from './src/action-route.js';
 export { buildImportMap, importMapTag, setVendorEntries } from './src/importmap.js';
 export {
   scanBareImports,

package/package.json

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

package/src/action-middleware.js

@@ -2,7 +2,7 @@
  * 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`.
+ * and the `route.ts` boundary (including the `route()` adapter), like `validate`.
  *
  *   - `ctx` carries `{ request, args, signal, context }`. `context` is a shared
  *     mutable object the chain accumulates; the action reads it via

package/src/action-route.js

@@ -0,0 +1,147 @@
+/**
+ * The optional `route(action, opts?)` convenience adapter (#488).
+ *
+ * REST endpoints in webjs go through `route.ts` (the framework's first-class
+ * HTTP handler). The ALWAYS-WORKS baseline is a hand-written `route.ts` that
+ * imports a `'use server'` action and calls it:
+ *
+ * ```js
+ * // app/api/posts/route.ts
+ * import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+ * export async function POST(req) {
+ *   const body = await req.json();
+ *   const result = await createPost(body);
+ *   return Response.json(result);
+ * }
+ * ```
+ *
+ * `route()` is the one-liner shortcut for that pattern. It returns a
+ * `route.ts`-style handler that merges the URL query, the route params, and the
+ * JSON body into ONE input object, runs an optional boundary validator, and
+ * dispatches the action through the request abort signal + the per-action
+ * middleware chain, JSON-responding the result:
+ *
+ * ```js
+ * // app/api/posts/route.ts
+ * import { route } from '@webjsdev/server';
+ * import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+ * export const POST = route(createPost, { validate: createPostSchema });
+ * ```
+ *
+ * Adapter rules when invoked over HTTP:
+ *   - URL query params, route params (`ctx.params`), and the parsed JSON body
+ *     (for a method with a body) are merged into a single object argument
+ *     (body wins over params wins over query). A non-object JSON body becomes
+ *     `{ body: parsed }`; invalid JSON is a 400. An over-limit body is a 413.
+ *   - `opts.validate` (when present) runs through the SHARED `runValidate` seam,
+ *     so a `{ success, fieldErrors }` envelope, a throw, and a transform-return
+ *     are interpreted exactly as on the RPC path: a structured failure is a 422
+ *     JSON, a thrown validator is a 400 (keeping a schema lib's `issues`), and a
+ *     transform-return replaces the input.
+ *   - The action runs inside the request's `AbortSignal` scope (#492) and the
+ *     `opts.middleware` chain (#490); a middleware short-circuit carrying a
+ *     numeric `status` maps that to the HTTP status (else a 200 JSON envelope).
+ *   - A returned `Response` passes through verbatim; any other value is
+ *     `Response.json`'d.
+ *
+ * This is purely a convenience: it ships no behaviour a hand-written `route.ts`
+ * cannot express. For full control (custom headers, content negotiation,
+ * streaming), write the `route.ts` by hand.
+ */
+import { runValidate } from './actions.js';
+import { runWithActionSignal } from './action-signal.js';
+import { runActionChain } from './action-middleware.js';
+import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
+import { getBodyLimits } from './context.js';
+
+/**
+ * The JSON body cap in effect for the current request: the per-request limit
+ * the handler stamped, or the secure default outside a request scope. `0`
+ * disables the cap.
+ * @returns {number}
+ */
+function jsonBodyLimit() {
+  const limits = getBodyLimits();
+  return limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
+}
+
+/**
+ * Expose a plain `'use server'` action over REST as a `route.ts`-style handler.
+ *
+ * @template A, R
+ * @param {(input: A, ctx: { req: Request, params: Record<string,string> }) => R | Promise<R>} action
+ *   the server action to call (its source is unchanged; this only wraps the
+ *   HTTP-to-action adapter around it).
+ * @param {{
+ *   validate?: (input: any) => any,
+ *   middleware?: Function[],
+ * }} [opts]
+ * @returns {(req: Request, ctx?: { params?: Record<string,string> }) => Promise<Response>}
+ */
+export function route(action, opts = {}) {
+  return async function handler(req, ctx) {
+    const params = (ctx && ctx.params) || {};
+    const url = new URL(req.url);
+    const query = Object.fromEntries(url.searchParams.entries());
+
+    /** @type {Record<string, unknown>} */
+    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 (typeof opts.validate === 'function') {
+      // Run the validator through the SHARED contract (#245) so the REST adapter
+      // and the RPC path interpret a `{ success, fieldErrors }` envelope, a
+      // throw, and a transform-return identically. A structured failure becomes
+      // a 422 JSON; a throw stays a 400 (keeping a schema lib's `issues`); a
+      // transform-return replaces the input.
+      const v = runValidate(opts.validate, arg);
+      if (!v.ok) {
+        if (v.thrown !== undefined) {
+          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;
+    }
+
+    // The action runs inside the request signal scope (#492) and the per-action
+    // middleware chain (#490). `ranAction` distinguishes a real completion from
+    // a middleware short-circuit (the action never ran).
+    const middleware = opts.middleware || [];
+    let ranAction = false;
+    const result = await runWithActionSignal(req.signal, () =>
+      runActionChain(middleware, { request: req, args: [arg], signal: req.signal }, () => {
+        ranAction = true;
+        return action(/** @type any */ (arg), { req, params });
+      }));
+
+    if (result instanceof Response) return result;
+    // A middleware short-circuit carrying a numeric `status` maps the envelope
+    // status to the HTTP status, so a non-webjs REST client sees the real status
+    // rather than a 200 with it in the body.
+    if (!ranAction && result && typeof result === 'object' && typeof (/** @type any */ (result).status) === 'number') {
+      const { status, ...payload } = /** @type any */ (result);
+      return Response.json(payload, { status });
+    }
+    return Response.json(result ?? null);
+  };
+}

package/src/action-seed.js

@@ -47,6 +47,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { stringify } from '@webjsdev/core';
 import { hashFile } from './actions.js';
+import { isStreamable } from './action-stream.js';
 
 /** Ambient per-render seed collector. `Map<key, value>` or undefined. */
 const als = new AsyncLocalStorage();
@@ -103,6 +104,10 @@ async function hashFor(absPath) {
  * @param {unknown} value resolved action result
  */
 async function recordSeed(collector, file, fnName, args, value) {
+  // A streamed result (#489) is not a serializer-safe value: recording it would
+  // make buildSeedScript's stringify throw and drop EVERY seed on the page. A
+  // streamed action is never seeded; the client streams it fresh on each call.
+  if (isStreamable(value)) return;
   try {
     const hash = await hashFor(file);
     const argsKey = await stringify(args);
@@ -116,9 +121,9 @@ async function recordSeed(collector, file, fnName, args, value) {
  * Wrap one exported action function so that, when a collector is active, its
  * resolved result is recorded. Outside a collector (the RPC endpoint path) it is
  * a transparent passthrough. Non-functions (a `const VERSION = '1.0'` export)
- * pass through untouched, and the Proxy forwards property reads, so `expose()` /
- * `validateInput()` metadata stored on the function (`__webjsHttp`) still
- * resolves through `getExposed()`.
+ * pass through untouched, and the Proxy forwards property reads, so any
+ * metadata an app or the framework attaches to the function still resolves
+ * through the wrapper.
  * @param {string} file absolute action file path
  * @param {string} fnName
  * @param {unknown} orig

package/src/action-stream.js

@@ -0,0 +1,158 @@
+/**
+ * Streaming RPC results (#489), server side.
+ *
+ * When a `'use server'` action returns a `ReadableStream`, an async iterable, an
+ * async generator, or a Node `Readable` (all carry `Symbol.asyncIterator`, and a
+ * web `ReadableStream` is normalized to one), the framework streams the chunks
+ * over the single RPC response instead of buffering the whole thing. Each chunk
+ * is rich-serialized and length-prefixed via the shared wire protocol in
+ * `@webjsdev/core` (`encodeFrame`), so a `Date` / `Map` / `BigInt` inside a chunk
+ * round-trips exactly like a normal RPC value. The generated client stub
+ * (`actions.js`) decodes the frames and yields the chunks from an async iterable.
+ *
+ * Composes with the rest of the RPC stack:
+ *   - #492 abort: the response is driven from the request's `AbortSignal`; a
+ *     client disconnect (or a superseded async render) aborts the fetch, which
+ *     cancels the source iterator, so a server generator stops producing.
+ *   - #472 seeding: a streamed result is NOT seeded (a stream is not a
+ *     serializer-safe value); `action-seed.js` skips a streamable result.
+ *   - #488 verbs: streaming is orthogonal to the verb; detection is purely on the
+ *     RETURN value, so a GET or a POST action can both stream.
+ */
+import { encodeFrame, FRAME_CHUNK, FRAME_END, FRAME_ERROR, STREAM_CONTENT_TYPE } from '@webjsdev/core';
+import { getSerializer } from './serializer.js';
+
+/**
+ * Whether an action's return value should stream over the RPC wire rather than
+ * buffer. True for a web `ReadableStream`, any async iterable (an async
+ * generator, a Node `Readable`), but NOT for a plain object / array / string /
+ * Promise / ActionResult envelope (none of which carry `Symbol.asyncIterator`).
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function isStreamable(v) {
+  if (!v || typeof v !== 'object') return false;
+  if (typeof ReadableStream !== 'undefined' && v instanceof ReadableStream) return true;
+  return typeof (/** @type any */ (v)[Symbol.asyncIterator]) === 'function';
+}
+
+/**
+ * Normalize a streamable source to an async iterator with `next()` / `return()`.
+ * A source with `Symbol.asyncIterator` (async generator, Node Readable, and a
+ * web ReadableStream in modern Node) uses it directly; a ReadableStream lacking
+ * async iteration falls back to a reader.
+ * @param {any} source
+ * @returns {{ next(): Promise<{ value: any, done?: boolean }>, return?(v?: any): Promise<any> }}
+ */
+function toAsyncIterator(source) {
+  if (source && typeof source[Symbol.asyncIterator] === 'function') {
+    return source[Symbol.asyncIterator]();
+  }
+  // A ReadableStream without async-iterator support: drive it from a reader.
+  const reader = source.getReader();
+  return {
+    next: () => reader.read(),
+    return: (v) => {
+      try { reader.cancel(v); } catch {}
+      try { reader.releaseLock(); } catch {}
+      return Promise.resolve({ value: undefined, done: true });
+    },
+  };
+}
+
+/**
+ * Build the streaming RPC `Response` for a streamable action result. The body is
+ * a back-pressured `ReadableStream` of frames: one CHUNK frame per serialized
+ * source value, a terminal END frame on clean completion, or an ERROR frame
+ * carrying the (author-controlled) message if the source throws mid-flight (the
+ * HTTP status is already 200 by then, so the error rides the frame channel).
+ *
+ * Back-pressure: chunks are pulled (and serialized) one at a time as the consumer
+ * reads, so a slow client throttles a fast producer. Cancellation: an aborted
+ * request signal (client disconnect / superseded render, #492) returns the source
+ * iterator, stopping a server generator.
+ *
+ * @param {any} source the streamable action return value
+ * @param {{ signal?: AbortSignal, onError?: (e: unknown) => void, headers?: Record<string,string> }} [opts]
+ * @returns {Response}
+ */
+export function streamActionResponse(source, opts = {}) {
+  const { signal, onError, headers } = opts;
+  const s = getSerializer();
+  const enc = new TextEncoder();
+  const iter = toAsyncIterator(source);
+  let closed = false;
+  /** @type {(() => void) | null} */
+  let onAbort = null;
+
+  const releaseSource = (reason) => {
+    if (typeof iter.return === 'function') {
+      try { return Promise.resolve(iter.return(reason)).catch(() => {}); } catch {}
+    }
+    return Promise.resolve();
+  };
+  const detach = () => { if (onAbort && signal) { try { signal.removeEventListener('abort', onAbort); } catch {} onAbort = null; } };
+
+  const body = new ReadableStream({
+    async pull(controller) {
+      if (closed) return;
+      try {
+        if (signal && signal.aborted) {
+          closed = true;
+          // Emit an ERROR frame so a still-reading client sees an explicit abort
+          // rather than a silent truncation (a clean close with no terminal
+          // frame is indistinguishable from success). Best-effort: the
+          // connection may already be gone, in which case enqueue throws.
+          try { controller.enqueue(encodeFrame(FRAME_ERROR, enc.encode('stream aborted'))); } catch {}
+          await releaseSource();
+          detach();
+          controller.close();
+          return;
+        }
+        const { value, done } = await iter.next();
+        if (done) {
+          closed = true;
+          controller.enqueue(encodeFrame(FRAME_END));
+          detach();
+          controller.close();
+          return;
+        }
+        const bytes = enc.encode(await s.serialize(value));
+        controller.enqueue(encodeFrame(FRAME_CHUNK, bytes));
+      } catch (e) {
+        closed = true;
+        // Surface the original error to an APM sink + the server log, exactly
+        // like the buffered error path, then ship the author-controlled message
+        // on the frame channel (the status is already 200, mid-stream).
+        if (typeof onError === 'function') { try { onError(e); } catch {} }
+        console.error('[webjs] streaming action threw:', e);
+        const msg = e instanceof Error && e.message ? e.message : 'Internal server error';
+        try { controller.enqueue(encodeFrame(FRAME_ERROR, enc.encode(msg))); } catch {}
+        await releaseSource(e);
+        detach();
+        try { controller.close(); } catch {}
+      }
+    },
+    async cancel(reason) {
+      closed = true;
+      detach();
+      await releaseSource(reason);
+    },
+  });
+
+  // A client disconnect / superseded render aborts the request signal: cancel the
+  // source promptly even if the consumer is not actively pulling. The listener is
+  // detached on completion / cancel so it cannot outlive the stream.
+  if (signal) {
+    onAbort = () => { releaseSource(); };
+    signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  // A streamed result is never cacheable; mark it streamed so the conditional-GET
+  // funnel never tries to buffer it into memory for an ETag.
+  const h = new Headers(headers || {});
+  h.set('content-type', STREAM_CONTENT_TYPE);
+  h.set('cache-control', 'no-store');
+  h.set('x-webjs-stream-rpc', '1');
+  return new Response(body, { status: 200, headers: h });
+}

package/src/actions.js

@@ -1,12 +1,10 @@
 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,
@@ -16,6 +14,7 @@ import {
 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';
@@ -44,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
@@ -127,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.
@@ -198,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>} */
@@ -376,7 +320,11 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // `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'];
+  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');
   }
@@ -394,11 +342,43 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   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
@@ -501,17 +481,13 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
   } catch {
     return rpcResponse({ error: 'Invalid request body' }, { status: 400 });
   }
-  // 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);
-  const validate = actionConfigFn(mod, 'validate') || (attached && attached.validate);
+  // 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) {
@@ -540,6 +516,19 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
     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.
@@ -592,179 +581,6 @@ async function getActionResponse(result, mod, args, req) {
   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.
- * @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
- * @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.
- */
-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;
-  }
-  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 {
-    // 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);
-    return actionErrorResponse(e, idx.dev);
-  }
-}
-
 /**
  * Return a JSON error response with dev-vs-prod sanitization.
  * In prod we return only the error message (not the stack), and we log the
@@ -789,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

package/src/check.js

@@ -93,6 +93,11 @@ export const RULES = [
     description:
       'Files that declare the `\'use server\'` directive at the top must also have the `.server.{js,ts,mts,mjs}` extension. The two markers are complementary, not interchangeable: `.server.ts` is the path-level boundary that triggers source protection by the file router; `\'use server\'` is the semantic opt-in that registers exports as RPC-callable from client code. A `\'use server\'` directive without the extension is silently ignored: the file is served to the browser as plain source, exports are NOT registered as RPC, and code the developer expects to run on the server actually runs in the browser. Rename the file to add the `.server.` infix.',
   },
+  {
+    name: 'use-server-exports-callable',
+    description:
+      'A `.server.{js,ts}` file that declares the `\'use server\'` directive registers its function exports as RPC-callable server actions, but only its FUNCTION exports: `buildActionIndex` / the stub generator register an export only when `typeof export === \'function\'`, so a `\'use server\'` file that exports zero functions (or only a non-function `const` / a type / only verb config like `method` / `cache`) registers NOTHING and gives no signal. The developer believes they exposed an action; nothing did, and the failure only surfaces as a 404 / undefined at the first call site. This is the complement of `use-server-needs-extension` (the directive without the extension) and of `one-action-per-configured-file` (more than one action in a configured file); this rule catches the directive-present-but-nothing-callable case. The rule asserts only that the file exports at least one callable, NOT that the action returns a value (a server action may be a void side-effect or throw `redirect()` / `notFound()` and never return). Conservative: a re-export (`export ... from`, `export *`) or an `export const NAME = <identifier-or-call>` (a possible factory-produced function such as `export const get = cache(fetch)`) is treated as a possible callable and NOT flagged, so the rule fires only when every export is provably non-callable. Fix: export an `async function` action, or drop the `\'use server\'` directive if the file is a plain server-only utility.',
+  },
   {
     name: 'no-non-erasable-typescript',
     description:
@@ -733,6 +738,75 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: use-server-exports-callable (#464) ---
+  // A `.server.{js,ts}` file with the `'use server'` directive registers only
+  // its FUNCTION exports as RPC actions (the registrar checks `typeof === 'function'`).
+  // A file that declares the directive but exports no callable registers nothing,
+  // silently: the developer thinks they exposed an action, and the only signal is
+  // a 404 / undefined at the first call site. Flag it. The complement of
+  // use-server-needs-extension (the directive without the extension) and of
+  // one-action-per-configured-file (more than one action).
+  {
+    for (const { rel, content, scan } of files) {
+      // Only properly-marked action files (the extension boundary). A `'use
+      // server'` file WITHOUT the .server. extension is the use-server-needs-
+      // extension rule's job; do not double-flag it here.
+      if (!/\.server\.m?[jt]s$/.test(rel)) continue;
+      if (!hasUseServerDirective(content)) continue;
+      // Count function-shaped EXPORTED callables, the SAME way the action
+      // registrar sees them: function declarations + arrow / function-expression
+      // consts (with an optional `: Type` annotation, #495). Reserved verb-config
+      // names (method/cache/...) are config, never a callable action.
+      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]);
+      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]);
+      const callables = [...names].filter((n) => !RESERVED_CONFIG.has(n));
+      if (callables.length > 0) continue; // exports at least one callable -> fine
+      // A default export is assumed callable (an action commonly default-exports).
+      if (/\bexport\s+default\b/.test(scan)) continue;
+      // Conservative, avoid a FALSE POSITIVE: the runtime registrar
+      // (`actionFunctionNames`) keeps EVERY export whose value is a function at
+      // load time, regardless of the export syntax, so any export shape these
+      // patterns cannot prove is non-callable must NOT be flagged. Skip when the
+      // file has:
+      //   - a named-export clause `export { a, b as c }` (with or WITHOUT `from`):
+      //     it can surface a local function (`function getX(){}; export { getX }`)
+      //     or a re-exported / imported function, neither matched above;
+      //   - a star re-export `export * from ...`;
+      //   - a destructuring export `export const { x } = obj` / `export const [x] = arr`,
+      //     which may bind a function;
+      //   - an `export const NAME = <identifier-or-call>`, a factory-produced
+      //     function (`export const get = cache(fetch)`).
+      // A sole `export { aConst }` of a non-function is then a tolerated FALSE
+      // NEGATIVE, which is the right bias for a non-overridable correctness rule.
+      if (/\bexport\s*\{/.test(scan)) continue;
+      if (/\bexport\s*\*/.test(scan)) continue;
+      if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(scan)) continue;
+      // A factory / identifier-valued const could be a callable ACTION, so skip,
+      // BUT only when its name is NOT a reserved config key: the registrar
+      // excludes reserved names from actions (`actionFunctionNames`), so a file
+      // whose only ambiguous const is `validate` / `tags` / ... (config produced
+      // by an arrow or a factory) still has zero actions and must flag. Skip only
+      // for a NON-reserved ambiguous const (a real possible action).
+      const reFactory = /\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::(?:[^=]|=>)*?)?=\s*[A-Za-z_$(]/g;
+      let ambiguousAction = false;
+      while ((m = reFactory.exec(scan))) { if (!RESERVED_CONFIG.has(m[1])) { ambiguousAction = true; break; } }
+      if (ambiguousAction) continue;
+      // Every export is provably non-callable (a literal const, a type) or there
+      // are none: the directive exposes nothing.
+      violations.push({
+        rule: 'use-server-exports-callable',
+        file: rel,
+        message:
+          "File declares `'use server'` but exports no callable action. The `'use server'` directive registers FUNCTION exports as RPC-callable; a file exporting only a non-function (a `const` / a type / only verb config) registers nothing, so a client import resolves to nothing and the call 404s.",
+        fix: "Export an `async function` action from this file, or remove the `'use server'` directive if it is a plain server-only utility.",
+      });
+    }
+  }
+
   // --- 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
@@ -749,7 +823,13 @@ export async function checkConventions(appDir) {
       // 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;
+      // An OPTIONAL `: Type` annotation may sit between the name and the `=`
+      // (#495); the type itself can contain a function-type `=>`, so the
+      // annotation matcher consumes any non-`=` char OR a literal `=>`, and the
+      // assignment is the first `=` NOT followed by `>` (`=(?!>)`). The
+      // alternation is unambiguous at each position (a `=` can only start `=>`),
+      // so there is no catastrophic backtracking.
+      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));

package/src/cors.js

@@ -1,14 +1,11 @@
 /**
  * Reusable CORS primitive for webjs.
  *
- * Two surfaces share one origin-resolution + header-building core:
- *
- * 1. `cors(options)` returns a webjs MIDDLEWARE `(req, next) => Response`,
- *    usable in `middleware.js` (root or per-segment) or wrapped around a
- *    `route.js` handler. This is the public app-facing API.
- * 2. The `expose()` REST path (`actions.js`) reuses `resolveOrigin` and
- *    `applyCorsHeaders` so a route's `cors` config and a standalone
- *    `cors()` middleware compute identical headers.
+ * `cors(options)` returns a webjs MIDDLEWARE `(req, next) => Response`,
+ * usable in `middleware.js` (root or per-segment) or wrapped around a
+ * `route.js` handler. This is the public app-facing API. The shared
+ * origin-resolution + header-building core (`resolveOrigin` /
+ * `applyCorsHeaders`) is exported for reuse.
  *
  * Web-standards-first: the option shape mirrors the well-trodden
  * `cors` npm package and the Fetch CORS protocol. We reflect the

package/src/csrf.js

@@ -20,10 +20,11 @@ const webCrypto = /** @type {Crypto} */ (globalThis.crypto);
  * they cannot set the header to the matching value.
  *
  * Notes on scope:
- *   - Applies to internal RPC only. `expose()`d REST endpoints are *not*
- *     CSRF-protected by default because they're intended for external
- *     consumers; those endpoints should carry their own auth (bearer token,
- *     signed request, API key) which the app provides via middleware.
+ *   - Applies to internal RPC only. A `route.ts` REST endpoint (hand-written
+ *     or via the `route()` adapter) is *not* CSRF-protected because it is
+ *     intended for external consumers; such an endpoint should carry its own
+ *     auth (bearer token, signed request, API key) the app provides via
+ *     middleware.
  */
 
 export const CSRF_COOKIE = 'webjs_csrf';

package/src/dev.js

@@ -56,11 +56,6 @@ import {
   serveActionStub,
   serveServerOnlyStub,
   invokeAction,
-  matchExposedAction,
-  matchAllAtPath,
-  invokeExposedAction,
-  buildPreflightResponse,
-  withCors,
   isServerFile,
   hasUseServerDirective,
   hashFile,
@@ -1707,34 +1702,6 @@ async function handleCore(req, ctx) {
     return invokeAction(state.actionIndex, actMatch[1], actMatch[2], req, onActionError);
   }
 
-  // expose()d server actions (first-class REST), with optional CORS support.
-  if (method === 'OPTIONS') {
-    const allAtPath = matchAllAtPath(state.actionIndex, path);
-    if (allAtPath.length) {
-      const corsRoute = allAtPath.find((r) => r.cors);
-      const methods = [...new Set(allAtPath.map((r) => r.method))];
-      if (corsRoute) {
-        // Preflight: respond with cors headers + the union of methods at this path.
-        const preflight = buildPreflightResponse(corsRoute, req);
-        const newHeaders = new Headers(preflight.headers);
-        newHeaders.set('access-control-allow-methods', `${methods.join(', ')}, OPTIONS`);
-        return new Response(null, { status: preflight.status, headers: newHeaders });
-      }
-      return new Response(null, { status: 204, headers: { allow: `${methods.join(', ')}, OPTIONS` } });
-    }
-  } else {
-    const exposed = matchExposedAction(state.actionIndex, method, path);
-    if (exposed) {
-      // Pass the onError sink (issue #239): an exposed REST handler that throws
-      // unexpectedly is reported to the APM hook before the sanitized 500, the
-      // same as the RPC action path (phase 'action' covers both server-action
-      // invocation shapes).
-      const onActionError = reportError ? (e) => reportError(e, req, 'action') : undefined;
-      const resp = await invokeExposedAction(state.actionIndex, exposed.route, exposed.params, req, onActionError);
-      return withCors(resp, exposed.route, req);
-    }
-  }
-
   // Static: /public/*
   if (path.startsWith('/public/') || path === '/favicon.ico') {
     const p = path === '/favicon.ico' ? '/public/favicon.ico' : path;

package/src/importmap.js

@@ -265,9 +265,9 @@ export function buildCoreEntries(coreDir, distMode) {
   /** @type {Record<string, string>} */
   const out = {
     // Bare specifier: browser-only entry, slim by design (drops
-    // render-server, expose, setCspNonceProvider). Node-side
-    // consumers resolve via the package.json exports `default`
-    // condition and land on `index.js` instead.
+    // render-server, setCspNonceProvider). Node-side consumers
+    // resolve via the package.json exports `default` condition and
+    // land on `index.js` instead.
     '@webjsdev/core': distMode
       ? '/__webjs/core/dist/webjs-core-browser.js'
       : '/__webjs/core/index-browser.js',