@webjsdev/server 0.9.0 → 0.10.1

package/src/actions.js

@@ -1,4 +1,5 @@
 import { digestHex } from './crypto-utils.js';
+import { headerSafeLocation } from './redirect-location.js';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import { walk } from './fs-walk.js';
@@ -16,10 +17,10 @@ import { runActionChain } from './action-middleware.js';
 import { isStreamable, streamActionResponse } from './action-stream.js';
 import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 import { ifNoneMatchSatisfied } from './conditional-get.js';
-import { getBodyLimits } from './context.js';
+import { getBodyLimits, refreshHeaderValue } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
-import { FORM_ACTION_ID_KEY, FORM_ACTION_FIELD } from '@webjsdev/core';
+import { FORM_ACTION_ID_KEY, FORM_ACTION_FIELD, isRedirect } from '@webjsdev/core';
 import { devImport } from './dev-import.js';
 import { formInput, isFormData } from './action-input.js';
 
@@ -44,6 +45,49 @@ function jsonBodyLimit() {
  */
 export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 
+/**
+ * The `issues` array a schema library's validation error carries (zod, valibot,
+ * Standard Schema), or null for any other throw.
+ * @param {unknown} e
+ * @returns {Array<{ path?: unknown[], message?: string }> | null}
+ */
+function schemaIssues(e) {
+  const issues = e && typeof e === 'object' ? /** @type {any} */ (e).issues : undefined;
+  return Array.isArray(issues) && issues.length > 0 ? issues : null;
+}
+
+/**
+ * A failure result from a schema error's issues: the first message per field
+ * as `fieldErrors` (a nested path joined with dots), and a form-level `error`
+ * for an issue with no path.
+ * @param {unknown} e
+ */
+function issuesResult(e) {
+  /** @type {Record<string, string>} */
+  const fieldErrors = {};
+  let error;
+  for (const issue of schemaIssues(e) || []) {
+    // A segment is a key, or Standard Schema's { key }; a symbol key is
+    // converted explicitly, since join's implicit conversion throws on one.
+    const path = Array.isArray(issue.path)
+      ? issue.path.map((p) => {
+        const k = p && typeof p === 'object' && 'key' in p ? /** @type {any} */ (p).key : p;
+        return typeof k === 'symbol' ? (k.description ?? '') : String(k);
+      }).join('.')
+      : '';
+    const message = typeof issue.message === 'string' ? issue.message : 'Invalid value.';
+    if (path) {
+      // Own keys only (a field named `constructor` is not already present),
+      // and defined rather than assigned, so `__proto__` is a field, not the
+      // object's prototype.
+      if (!Object.hasOwn(fieldErrors, path)) {
+        Object.defineProperty(fieldErrors, path, { value: message, enumerable: true, writable: true, configurable: true });
+      }
+    } else if (!error) error = message;
+  }
+  return { success: false, fieldErrors, ...(error ? { error } : {}), status: 422 };
+}
+
 /**
  * Run an attached input validator against an action's input, shared by the RPC
  * path (`invokeAction`) and the `route()` REST adapter so the contract is
@@ -53,21 +97,27 @@ export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
  * @param {(input: any) => any} validate the attached validator
  * @param {any} input the value handed to the validator (the action's first arg
  *   on RPC, the merged query/params/body object on REST)
- * @returns {{ ok: true, value: any } | { ok: false, result: { success: false, fieldErrors?: Record<string,string>, error?: string, status: number }, thrown?: unknown }}
+ * @returns {{ ok: true, value: any } | { ok: false, result: { success: false, fieldErrors?: Record<string,string>, error?: string, status: number }, thrown?: unknown, invalid?: boolean }}
  *   `ok: true` carries the value to pass to the action (the validated `data`,
  *   the transformed return, or the original input). `ok: false` carries the
  *   structured failure result the caller serializes back; on a THROWN validator
  *   it also carries the original error on `thrown` so a caller can salvage a
  *   schema lib's structured `issues` (the REST path does, for back-compat).
  */
-export function runValidate(validate, input) {
+export async function runValidate(validate, input) {
   let out;
   try {
-    out = validate(input);
+    // Awaited, so an async validator (an async schema check, a lookup) works
+    // like a sync one; a returned Promise must never read as a transformed input.
+    out = await validate(input);
   } catch (e) {
-    // Throw-to-reject (the classic `Schema.parse` contract). Map to a sanitized
-    // failure result; a thrown validator is a 400 (bad input), not a 500.
-    // Surface only the message; `thrown` lets the REST caller recover `issues`.
+    // A schema library's validation error (a throw carrying `issues`: zod's
+    // `.parse`, valibot, Standard Schema) is invalid INPUT, mapped once here so
+    // every transport answers it alike: the issues become fieldErrors with a
+    // 422, as a structured envelope failure is (`invalid` marks it).
+    if (schemaIssues(e)) return { ok: false, result: issuesResult(e), thrown: e, invalid: true };
+    // Any other throw-to-reject: a sanitized failure result, a 400 over REST;
+    // `thrown` lets the RPC path treat it as the crash it may be.
     const msg = e instanceof Error ? e.message : String(e);
     return { ok: false, result: { success: false, error: msg, status: 400 }, thrown: e };
   }
@@ -322,7 +372,7 @@ 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', 'applyActionRefresh as __refresh', 'followActionRedirect as __redirect', 'installActionBind as __bindable',
     // 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.
@@ -343,6 +393,12 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // caught on the next read).
   lines.push(`async function __handle(res, fn, key, since) {`);
   lines.push(`  const inv = __tagHdr(res.headers.get('x-webjs-invalidate')); if (inv.length) __markStale(inv);`);
+  // redirect() in the action (Next parity): navigate there; the call's promise
+  // rejects with the redirect sentinel, which the page ignores unhandled.
+  lines.push(`  const rd = res.headers.get('x-webjs-redirect'); if (rd) return __redirect(rd);`);
+  // revalidatePath() in the action: refresh the page on screen in place when
+  // it was revalidated, BEFORE the caller's await resolves (Next behaviour).
+  lines.push(`  const rf = res.headers.get('x-webjs-refresh'); if (rf) await __refresh(rf);`);
   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.
@@ -425,7 +481,9 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // load-hook registry instead; both produce the same string, which is what
   // makes the SSR'd form and the re-rendered one submit the same value.
   // Non-enumerable so `import * as actions` and a spread stay unchanged.
-  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return fn; };`);
+  // `.bind(null, id)` keeps the identity too (installActionBind), so a bound
+  // stub re-renders to the same hidden field the server emitted.
+  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return __bindable(fn); };`);
   for (const name of fnNames) {
     lines.push(
       name === 'default'
@@ -481,7 +539,7 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
   // CDN-cacheable. See csrf.js.
   if (!SAFE_VERBS.has(method)) {
     const v = verifyOrigin(req, allowedOrigins);
-    if (!v.ok) return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
+    if (!v.ok) return rpcResponse({ error: `CSRF validation failed: ${v.reason}` }, { status: 403 });
   }
 
   // Args ride the URL for a URL-arg request (GET / DELETE), else the body.
@@ -519,16 +577,17 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
   // server-to-server call.
   const validate = actionConfigFn(mod, 'validate');
   if (typeof validate === 'function') {
-    const v = runValidate(validate, args[0]);
+    const v = await runValidate(validate, args[0]);
     if (!v.ok) {
-      if (v.thrown !== undefined) {
+      if (v.thrown !== undefined && !v.invalid) {
         // A THROWN validator behaves like a thrown action: a sanitized error
         // response (non-200, so the client stub throws), with prod stack
         // sanitization. The onError sink sees the original error too.
         if (typeof onError === 'function') onError(v.thrown);
         return actionErrorResponse(v.thrown, idx.dev);
       }
-      // A structured `{ success: false, fieldErrors }` envelope is a NORMAL
+      // A structured `{ success: false, fieldErrors }` envelope, or a schema
+      // error's issues mapped to one, is a NORMAL
       // result the action author renders (`result.fieldErrors`): serialized as
       // a 200 RPC payload so the client stub returns it as a real object rather
       // than throwing, the failure status riding inside the envelope.
@@ -536,6 +595,7 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
     }
     args = [v.value, ...args.slice(1)];
   }
+  let ranAction = false;
   try {
     // Run inside the request's AbortSignal scope (#492) and the per-action
     // middleware chain (#490): the chain wraps the action, can short-circuit
@@ -543,7 +603,6 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
     // the action reads via actionContext(). `ranAction` distinguishes a real
     // action completion from a middleware short-circuit (the action never ran).
     const middleware = actionMiddleware(mod);
-    let ranAction = false;
     const result = await runWithActionSignal(req.signal, () =>
       runActionChain(middleware, { request: req, args, signal: req.signal }, () => { ranAction = true; return fn(...args); }));
     // Streaming result (#489): a COMPLETED action returning a ReadableStream /
@@ -557,6 +616,8 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
         if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
       }
+      const refresh = refreshHeaderValue();
+      if (refresh) headers['x-webjs-refresh'] = refresh;
       return streamActionResponse(result, { signal: req.signal, onError, headers, dev: idx.dev });
     }
     if (method === 'GET') {
@@ -575,8 +636,29 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         headers['x-webjs-invalidate'] = inv.join(',');
       }
     }
+    // revalidatePath() during the action (Next parity): the browser refreshes
+    // those paths, and the page on screen in place when it is one of them.
+    const refresh = refreshHeaderValue();
+    if (refresh) headers['x-webjs-refresh'] = refresh;
     return rpcResponse(result ?? null, { headers });
   } catch (e) {
+    // redirect() / permanentRedirect() in an action called over RPC (Next.js
+    // parity): not an error. The response tells the generated stub where to
+    // go (`x-webjs-redirect: <url>;<push|replace>`, push by default as in a
+    // Next server action), and the client router navigates there. A mutation
+    // that ran still evicts its `invalidates` tags and reports revalidatePath.
+    if (isRedirect(e)) {
+      const r = /** @type {any} */ (e);
+      /** @type {Record<string, string>} */
+      const headers = { 'x-webjs-redirect': `${headerSafeLocation(r.url)};${r.redirectType === 'replace' ? 'replace' : 'push'}` };
+      if (ranAction && method !== 'GET') {
+        const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
+        if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
+      }
+      const refresh = refreshHeaderValue();
+      if (refresh) headers['x-webjs-refresh'] = refresh;
+      return rpcResponse(null, { headers: { ...headers, 'cache-control': 'no-store' } });
+    }
     if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }

package/src/api.js

@@ -1,14 +1,30 @@
+import { isRedirect, isNotFound, isForbidden, isUnauthorized } from '@webjsdev/core';
+import { headerSafeLocation } from './redirect-location.js';
 import { makeThenable } from './thenable-params.js';
 import { devImport } from './dev-import.js';
+import { decorateRequest } from './middleware-load.js';
+
+/** Every method a route module may export (Next's HTTP_METHODS). */
+const HTTP_METHODS = ['GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'DELETE', 'PATCH'];
 
 /**
  * Dispatch an incoming request to a matched API route.
- * API modules export methods as named async functions: GET, POST, PUT, PATCH, DELETE.
+ * API modules export methods as named async functions: GET, HEAD, OPTIONS,
+ * POST, PUT, PATCH, DELETE.
  *
  * Handlers receive a standard `Request` and return a standard `Response`.
  *
+ * Next.js parity:
+ *   - HEAD and OPTIONS are implemented automatically when the module does not
+ *     export them (a port of Next's `autoImplementMethods`): HEAD runs GET and
+ *     drops the body; OPTIONS answers 204 with a sorted `Allow`.
+ *   - `redirect()` thrown from a handler answers 307 (308 from
+ *     `permanentRedirect()`; an explicit status wins), and `notFound()` /
+ *     `forbidden()` / `unauthorized()` answer 404 / 403 / 401 with no body.
+ *     They are answered HERE, so no caller ever sees them as errors.
+ *
  * @param {import('./router.js').ApiRoute} route
- * @param {Record<string,string>} params
+ * @param {Record<string, string | string[]>} params
  * @param {Request} webRequest
  * @param {boolean} dev
  * @returns {Promise<Response>}
@@ -16,11 +32,20 @@ import { devImport } from './dev-import.js';
 export async function handleApi(route, params, webRequest, dev) {
   const mod = await devImport(route.file, dev);
   const method = webRequest.method.toUpperCase();
-  const handler = mod[method];
+  const implemented = HTTP_METHODS.filter((m) => typeof mod[m] === 'function');
+  let handler = typeof mod[method] === 'function' ? mod[method] : null;
+  let headOnly = false;
+  if (!handler && method === 'HEAD' && typeof mod.GET === 'function') {
+    handler = mod.GET;
+    headOnly = true;
+  }
+  if (!handler && method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers: { allow: allowHeader(implemented) } });
+  }
   if (!handler) {
     return new Response(`Method ${method} not allowed`, {
       status: 405,
-      headers: { allow: allowedMethods(mod).join(', ') },
+      headers: { allow: allowHeader(implemented) },
     });
   }
   // Route-handler params are awaitable AND sync-readable (#848, Next parity:
@@ -28,6 +53,9 @@ export async function handleApi(route, params, webRequest, dev) {
   // spreads / JSON-stringifies params is unaffected.
   const thenableParams = makeThenable(params);
   /** @type any */ (webRequest).params = thenableParams;
+  // A Next.js route handler receives a NextRequest, so `request.cookies.get()`
+  // is how agents read a cookie there; it is the request's cookies() store.
+  decorateRequest(webRequest, dev);
   let result;
   try {
     result = await handler(webRequest, { params: thenableParams });
@@ -42,14 +70,43 @@ export async function handleApi(route, params, webRequest, dev) {
         headers: { 'content-type': 'text/plain; charset=utf-8' },
       });
     }
+    const control = controlFlowResponse(e);
+    if (control) return control;
     throw e;
   }
-  if (result instanceof Response) return result;
-  // Convenience: allow returning plain objects as JSON.
-  return Response.json(result);
+  const res = result instanceof Response ? result : Response.json(result);
+  if (!headOnly) return res;
+  // A synthesized HEAD answers GET's status and headers with no body. GET's own
+  // body is never read, so it is cancelled: a streamed one (SSE, a DB cursor)
+  // would otherwise keep producing for no reader until it is collected.
+  if (res.body && !res.bodyUsed) res.body.cancel().catch(() => {});
+  return new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers });
 }
 
-/** @param {Record<string,unknown>} mod */
-function allowedMethods(mod) {
-  return ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].filter((m) => typeof mod[m] === 'function');
+/**
+ * The response Next.js gives a control-flow throw inside a route handler, or
+ * null when `e` is a real error.
+ * @param {unknown} e
+ * @returns {Response | null}
+ */
+export function controlFlowResponse(e) {
+  if (isRedirect(e)) {
+    const r = /** @type any */ (e);
+    return new Response(null, { status: r.status || 307, headers: { location: headerSafeLocation(r.url) } });
+  }
+  if (isNotFound(e)) return new Response(null, { status: 404 });
+  if (isForbidden(e)) return new Response(null, { status: 403 });
+  if (isUnauthorized(e)) return new Response(null, { status: 401 });
+  return null;
+}
+
+/**
+ * The `Allow` header Next sends: the implemented methods plus OPTIONS (always
+ * answered) and HEAD (when GET exists), sorted.
+ * @param {string[]} implemented
+ */
+function allowHeader(implemented) {
+  const allow = new Set(['OPTIONS', ...implemented]);
+  if (allow.has('GET')) allow.add('HEAD');
+  return [...allow].sort().join(', ');
 }

package/src/app-layout.js

@@ -0,0 +1,133 @@
+/**
+ * App layout validation: file arrangements that can never serve correctly,
+ * found from the route table alone (no code is loaded).
+ *
+ * Next.js refuses these at build time. WebJs has no build, so the same
+ * refusal happens in three places, all fed by `validateAppLayout`:
+ *   - `webjs check` reports each problem as a violation (its `rule` id);
+ *   - production refuses to boot (`createRequestHandler` throws);
+ *   - dev answers every app request with a 500 naming the problem and pushes
+ *     it to the error overlay, until an edit fixes it.
+ *
+ * @module app-layout
+ */
+import { relative, sep } from 'node:path';
+
+/**
+ * @typedef {{ rule: string, file: string, message: string, fix: string }} LayoutProblem
+ */
+
+/**
+ * The thrown form of one or more layout problems. `code` lets the request
+ * handler tell it apart from an ordinary analysis failure.
+ */
+export class AppLayoutError extends Error {
+  /** @param {LayoutProblem[]} problems */
+  constructor(problems) {
+    super(problems.map((p) => `[${p.rule}] ${p.file}: ${p.message} Fix: ${p.fix}`).join('\n'));
+    this.name = 'AppLayoutError';
+    this.code = 'WEBJS_APP_LAYOUT';
+    this.problems = problems;
+  }
+}
+
+/**
+ * @param {string} appDir
+ * @param {string} file
+ */
+function rel(appDir, file) {
+  return relative(appDir, file).split(sep).join('/');
+}
+
+/**
+ * Every layout problem in the app, in a stable order.
+ *
+ * @param {string} appDir
+ * @param {import('./router.js').RouteTable} table
+ * @param {Set<string>} [publicFiles] url paths of the files under `public/`
+ * @returns {LayoutProblem[]}
+ */
+export function validateAppLayout(appDir, table, publicFiles) {
+  /** @type {LayoutProblem[]} */
+  const problems = [];
+
+  // A public file at the url of a static page, a route handler or a metadata
+  // route: one would silently shadow the other (public files are served
+  // before routes, as in Next, which refuses the same conflict). A DYNAMIC
+  // route is not a conflict: the public file simply wins for its one url.
+  if (publicFiles && publicFiles.size) {
+    const staticOwner = new Map();
+    for (const r of [...(table.pages || []), ...(table.apis || [])]) {
+      if (r.paramNames && r.paramNames.length) continue;
+      const dir = /** @type {any} */ (r).routeDir;
+      const url = '/' + (dir === '.' ? '' : dir.split('/').filter((s) => !(s.startsWith('(') && s.endsWith(')'))).join('/'));
+      staticOwner.set(url, r.file);
+    }
+    for (const m of table.metadataRoutes || []) staticOwner.set(m.urlPath, m.file);
+    for (const url of publicFiles) {
+      const owner = staticOwner.get(url);
+      if (!owner) continue;
+      problems.push({
+        rule: 'no-public-route-conflict',
+        file: `public${url}`,
+        message: `public${url} is served at ${url}, the same url as ${rel(appDir, owner)}, so one of them can never be reached.`,
+        fix: `Rename or move one of them: public files are served at the url root (public/logo.png is /logo.png), before every route.`,
+      });
+    }
+  }
+
+  // A page and a route handler answering the same URL. Next refuses this
+  // ("Conflicting route and page"); WebJs used to let the route handler win
+  // silently, so the page never rendered.
+  for (const c of table.conflicts || []) {
+    problems.push({
+      rule: 'no-page-route-conflict',
+      file: rel(appDir, c.route),
+      message: `${rel(appDir, c.page)} and ${rel(appDir, c.route)} both answer ${c.url}, so the page can never render.`,
+      fix: 'Keep one: move the route handler to its own folder (for example app/api/...), or delete the page.',
+    });
+  }
+  // A routing file written as `.tsx` / `.jsx`: JSX needs a build step, so the
+  // router never sees it and the route silently does not exist.
+  for (const file of table.ignoredJsx || []) {
+    const r = rel(appDir, file);
+    const ts = r.replace(/\.(t|j)sx$/, (_, t) => `.${t}s`);
+    problems.push({
+      rule: 'no-jsx-route-file',
+      file: r,
+      message: `${r} is a routing file written as JSX, which WebJs never loads (there is no build step), so this route does not exist.`,
+      fix: `Rename it to ${ts} and return an html\`...\` template from @webjsdev/core instead of JSX (interactive parts become a WebComponent).`,
+    });
+  }
+  return problems;
+}
+
+/** The fix every CSS-import refusal names. */
+export const CSS_IMPORT_FIX = 'Load a stylesheet with <link rel="stylesheet" href="..."> in the root layout (Tailwind\'s output included), or scope CSS to a component with `static styles = css`...`` and `static shadow = true`.';
+
+/**
+ * Every `import './x.css'` in the app's module graph, as layout problems. A
+ * CSS import is a bundler feature: Node refuses the extension, Bun silently
+ * turns it into a no-op on the server, and the browser refuses a stylesheet as
+ * a module script, so the importing module never loads there.
+ * @param {Map<string, Set<string>>} graph
+ * @param {(abs: string) => string} rel
+ * @returns {LayoutProblem[]}
+ */
+export function cssImportProblems(graph, rel) {
+  /** @type {LayoutProblem[]} */
+  const out = [];
+  for (const [file, deps] of graph) {
+    if (/[\\/]node_modules[\\/]/.test(file)) continue;
+    for (const dep of deps) {
+      if (!/\.css$/i.test(dep)) continue;
+      out.push({
+        rule: 'no-css-import',
+        file: rel(file),
+        message: `Imports ${rel(dep)}, a stylesheet. WebJs has no bundler: the import fails on Node, is silently dropped on Bun, and stops the module from loading in the browser.`,
+        fix: CSS_IMPORT_FIX,
+      });
+    }
+  }
+  return out;
+}