@webjsdev/server 0.8.25 → 0.8.26

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.26",
   "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

@@ -749,7 +749,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',