@webjsdev/server 0.8.11 → 0.8.13

package/index.js

@@ -2,6 +2,7 @@ export { startServer, createRequestHandler } from './src/dev.js';
 export { assertNodeVersion, checkNodeVersion, requiredNodeMajor, parseMajor, parseRequiredMajor } from './src/node-version.js';
 export { validateEnv, formatEnvErrors, loadEnvSchema, applyEnvValidation } from './src/env-schema.js';
 export { buildRouteTable, matchPage, matchApi } from './src/router.js';
+export { generateRouteTypes } from './src/route-types.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';
 export { handleApi } from './src/api.js';
 export {
@@ -26,6 +27,7 @@ export {
   listPinned,
   auditPinned,
   findOutdated,
+  hasVendorPin,
   updatePinned,
   readPinFile,
   serveDownloadedBundle,
@@ -45,8 +47,25 @@ 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';
 export { json, readBody } from './src/json.js';
+export { sitemap, sitemapIndex } from './src/sitemap.js';
 export { attachWebSocket } from './src/websocket.js';
 export { getSerializer, setSerializer, defaultSerializer } from './src/serializer.js';
 
 // Auth (NextAuth-style)
 export { createAuth, Credentials, Google, GitHub } from './src/auth.js';
+
+// Test harness helpers (issue #267): thin builders over handle()
+export {
+  testRequest,
+  toRequest,
+  getCsrf,
+  readCsrfCookie,
+  getSetCookies,
+  cookiesToHeader,
+  withCookies,
+  withSessionCookie,
+  loginAndGetCookies,
+  actionEndpoint,
+  invokeActionForTest,
+  rawActionRequest,
+} from './src/testing.js';

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
-    "./check": "./src/check.js"
+    "./check": "./src/check.js",
+    "./testing": "./src/testing.js",
+    "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [
     "index.js",
     "src",
+    "webjs-config.schema.json",
     "README.md"
   ],
   "dependencies": {

package/src/actions.js

@@ -9,6 +9,8 @@ import { getSerializer } from './serializer.js';
 import { resolveOrigin } from './cors.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
+import { basePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -31,6 +33,60 @@ function jsonBodyLimit() {
  */
 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.
+ *
+ * @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 }}
+ *   `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) {
+  let out;
+  try {
+    out = 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`.
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, result: { success: false, error: msg, status: 400 }, thrown: e };
+  }
+  // Disambiguate an ActionResult envelope from a plain transformed value: a
+  // return is an envelope ONLY when it is an object carrying a boolean
+  // `success` OR a `fieldErrors`. Anything else is a transformed input.
+  if (out && typeof out === 'object' && !Array.isArray(out) &&
+      (typeof (/** @type any */ (out).success) === 'boolean' || 'fieldErrors' in out)) {
+    const env = /** @type any */ (out);
+    if (env.success === true) {
+      // `{ success: true, data? }` → valid; use `data` when present, else input.
+      return { ok: true, value: 'data' in env ? env.data : input };
+    }
+    // Failure: `{ success: false, ... }` or `{ fieldErrors }` (no literal
+    // success). Shape the structured field-error result.
+    return {
+      ok: false,
+      result: {
+        success: false,
+        ...(env.fieldErrors ? { fieldErrors: env.fieldErrors } : {}),
+        ...(env.message || env.error ? { error: env.message || env.error } : {}),
+        status: typeof env.status === 'number' ? env.status : 422,
+      },
+    };
+  }
+  // A non-envelope return transforms the input (back-compat with
+  // `validate: Schema.parse`); `undefined` means "no transform", keep input.
+  return { ok: true, value: out === undefined ? input : out };
+}
+
 /** Build a serialized Response with webjs content-type. */
 async function rpcResponse(payload, init = {}) {
   const s = getSerializer();
@@ -143,6 +199,12 @@ export async function buildActionIndex(appDir, dev) {
         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,
@@ -257,6 +319,12 @@ export async function serveActionStub(idx, absFile) {
   if (typeof mod.default === 'function' && !fnNames.includes('default')) {
     fnNames.push('default');
   }
+  // The RPC endpoint is a framework-emitted same-origin URL, so it must
+  // carry the basePath prefix under a sub-path deploy (#256), exactly like
+  // the importmap targets and the boot module specifiers. Without this the
+  // stub would POST to a bare /__webjs/action/... that the ingress strip
+  // 404s, breaking every server action when webjs.basePath is set.
+  const actionUrl = withBasePath(`/__webjs/action/${hash}/`, basePath());
   const body = `// webjs: generated server-action stub for ${relative(idx.appDir, absFile)}\n` +
     `import { stringify as __wjStringify, parse as __wjParse } from '@webjsdev/core';\n` +
     `function __csrf() {\n` +
@@ -265,7 +333,7 @@ export async function serveActionStub(idx, absFile) {
     `}\n` +
     `async function __rpc(fn, args) {\n` +
     `  const body = await __wjStringify(args);\n` +
-    `  const res = await fetch(${JSON.stringify(`/__webjs/action/${hash}/`)} + fn, {\n` +
+    `  const res = await fetch(${JSON.stringify(actionUrl)} + fn, {\n` +
     `    method: 'POST',\n` +
     `    headers: {\n` +
     `      'content-type': ${JSON.stringify(RPC_CONTENT_TYPE)},\n` +
@@ -327,6 +395,30 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
   const mod = await loadModule(file, idx.dev);
   const fn = fnName === 'default' ? mod.default : mod[fnName];
   if (typeof fn !== 'function') return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
+  // Input validation (#245): a validator attached via `validateInput(fn, ...)`
+  // or `expose(spec, fn, { validate })` runs SERVER-SIDE before the body on
+  // this RPC path too, not just the REST path. The RPC stub sends an args
+  // array; an action conventionally takes one input object, so validate the
+  // FIRST arg (matching how the REST path validates its single merged object).
+  const attached = getExposed(fn);
+  if (attached && typeof attached.validate === 'function') {
+    const v = runValidate(attached.validate, args[0]);
+    if (!v.ok) {
+      if (v.thrown !== undefined) {
+        // 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
+      // 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.
+      return rpcResponse(v.result);
+    }
+    args = [v.value, ...args.slice(1)];
+  }
   try {
     const result = await fn(...args);
     return rpcResponse(result ?? null);
@@ -462,17 +554,26 @@ export async function invokeExposedAction(idx, route, params, req, onError) {
   }
   let arg = { ...query, ...params, ...body };
   if (route.validate) {
-    try {
-      arg = route.validate(arg);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      // Many schema libs (zod, valibot) throw structured errors: pass their
-      // `issues` array through when present for easier client-side handling.
-      const issues = e && typeof e === 'object' && 'issues' in e
-        ? /** @type any */ (e).issues
-        : undefined;
-      return Response.json({ error: msg, issues }, { status: 400 });
+    // 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];

package/src/base-path.js

@@ -0,0 +1,149 @@
+/**
+ * Sub-path deployment support: `webjs.basePath` (issue #256).
+ *
+ * An app deployed under a sub-path (example.com/app/) behind a proxy that
+ * does NOT strip the prefix is broken without this: every
+ * framework-emitted absolute URL (the importmap targets, the modulepreload
+ * hints, the boot script's `/__webjs/core/*` specifiers and per-route
+ * module URLs, the dev reload `src`) assumes the app sits at the origin
+ * root, so they point at `/__webjs/core/*` instead of
+ * `/app/__webjs/core/*`, module resolution 404s, and the page never
+ * hydrates. `createRequestHandler` explicitly targets embedding, where a
+ * sub-path mount is the norm.
+ *
+ * The model is strip-at-ingress + prefix-on-emit, two seams only:
+ *
+ *   1. STRIP AT INGRESS. At the very start of request handling, when the
+ *      request pathname starts with the basePath, strip it so all
+ *      downstream logic (route matching, the `/__webjs/*` checks, the
+ *      source-file gate, redirects, trailing-slash) sees a ROOT-relative
+ *      path and works UNCHANGED. This single strip is why the rest of the
+ *      framework needs no per-site changes. `stripBasePath` does the path
+ *      computation; `dev.js` rewrites the Request URL with it.
+ *
+ *   2. PREFIX ON EMIT. Every framework-emitted same-origin absolute URL
+ *      (begins with a single `/`) gets the basePath prepended via the one
+ *      `withBasePath` helper. Applied to the importmap targets
+ *      (`importmap.js`), the modulepreload hrefs + boot module specifiers +
+ *      dev reload `src` (`ssr.js`). A cross-origin URL (a `https://` CDN
+ *      vendor target) is absolute and is left untouched.
+ *
+ * Empty basePath (the default) makes both seams pure no-ops, so an
+ * unconfigured app is byte-identical to before this feature. That
+ * invariant is the #1 risk and is guarded differentially in the tests.
+ *
+ * OUT OF SCOPE (a documented follow-up, the same boundary Next draws):
+ * rewriting AUTHOR-written `<a href="/about">` links and client-router
+ * navigation prefixing. This module covers framework-emitted URLs and the
+ * ingress match only.
+ */
+
+/**
+ * Normalize a raw `webjs.basePath` value to the canonical internal form:
+ * either `''` (the no-op default) or a string with exactly one leading
+ * `/` and no trailing `/`. So `'app'`, `'/app'`, and `'/app/'` all map to
+ * `'/app'`, and a nested `'/foo/bar'` is preserved.
+ *
+ * Empty / undefined / non-string / `'/'` all map to `''` (no base path).
+ * A value that cannot be a safe, single-origin path prefix is rejected to
+ * `''`: anything containing `..` (path traversal), a protocol (`://`), a
+ * backslash, whitespace, or a network-path `//host` reference. So a typo
+ * or a hostile value fails safe to "no base path" rather than poisoning
+ * every emitted URL.
+ *
+ * @param {unknown} raw the configured value
+ * @returns {string} `''` or `/segment[/segment...]`
+ */
+export function normalizeBasePath(raw) {
+  if (typeof raw !== 'string') return '';
+  let v = raw.trim();
+  if (v === '' || v === '/') return '';
+  // Reject anything that is not a plain same-origin path prefix.
+  if (v.includes('..')) return '';
+  if (v.includes('://')) return '';
+  if (v.includes('\\')) return '';
+  if (/\s/.test(v)) return '';
+  // Reject a network-path reference (`//host`) BEFORE collapsing leading
+  // slashes: such a value would emit a protocol-relative, cross-origin URL
+  // once prefixed (an open redirect / origin escape), so it fails safe to
+  // "no base path" rather than being collapsed to `/host`.
+  if (v.startsWith('//')) return '';
+  // Ensure exactly one leading slash.
+  v = '/' + v.replace(/^\/+/, '');
+  // Strip any trailing slash(es).
+  v = v.replace(/\/+$/, '');
+  // A leading-slash-only value collapses to '' here (already handled as
+  // '/' above, but guard a value like '//' that slipped a different path).
+  if (v === '' || v === '/') return '';
+  return v;
+}
+
+/**
+ * Read and normalize the `webjs.basePath` config from a parsed
+ * package.json (or any object). Pure; `dev.js` wraps it with the
+ * package.json read like the other `webjs.*` readers.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {string} the normalized base path (`''` when unset)
+ */
+export function readBasePath(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.basePath;
+  return normalizeBasePath(raw);
+}
+
+/**
+ * Prefix a framework-emitted same-origin absolute URL with the base path.
+ * Returns the URL unchanged when basePath is empty (the no-op default) or
+ * when the URL is not a same-origin absolute path (a cross-origin
+ * `https://` CDN target, a protocol-relative `//host` reference, or a
+ * relative URL), so only the framework's own `/`-rooted paths are moved.
+ *
+ * @param {string} url the URL to (maybe) prefix
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+export function withBasePath(url, basePath) {
+  if (!basePath) return url;
+  if (typeof url !== 'string') return url;
+  // Only a single-leading-slash same-origin path is prefixed. A
+  // protocol-relative `//host` or an absolute `scheme://` URL is left
+  // alone (a vendor CDN target), as is a relative URL.
+  if (url[0] !== '/' || url[1] === '/') return url;
+  return basePath + url;
+}
+
+/**
+ * Compute the root-relative pathname for an incoming request pathname
+ * under the base path (the ingress strip). Returns:
+ *   - the stripped, root-relative pathname (always begins with `/`) when
+ *     the request is for this app, OR
+ *   - `null` when the request path is NOT under the base path, so the
+ *     caller can 404 it (the request is not for this mounted app).
+ *
+ * Mapping: `<basePath>` and `<basePath>/` both map to the root `/`.
+ * `<basePath>/foo` maps to `/foo`. A path that merely shares a prefix but
+ * is not a real segment boundary (e.g. `/application` under basePath
+ * `/app`) is NOT under the base path and returns null. When basePath is
+ * empty this is a pure pass-through (returns the input unchanged).
+ *
+ * @param {string} pathname the incoming request pathname (begins with `/`)
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string | null}
+ */
+export function stripBasePath(pathname, basePath) {
+  if (!basePath) return pathname;
+  if (pathname === basePath) return '/';
+  const withSlash = basePath + '/';
+  if (pathname.startsWith(withSlash)) {
+    // Slice off the base path; keep the leading slash of the remainder.
+    const rest = pathname.slice(basePath.length);
+    return rest || '/';
+  }
+  // Not under the base path (`/application` vs basePath `/app`, or an
+  // unrelated path): not this app.
+  return null;
+}