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

package/index.js

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

package/package.json

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

package/src/action-config.js

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

package/src/action-middleware.d.ts

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

package/src/action-middleware.js

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

package/src/action-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-signal.js

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