@webjsdev/server 0.8.12 → 0.8.14

package/index.js

@@ -27,6 +27,7 @@ export {
   listPinned,
   auditPinned,
   findOutdated,
+  hasVendorPin,
   updatePinned,
   readPinFile,
   serveDownloadedBundle,
@@ -46,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,12 +1,13 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./check": "./src/check.js",
+    "./testing": "./src/testing.js",
     "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [

package/src/actions.js

@@ -33,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();
@@ -145,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,
@@ -241,7 +301,8 @@ export function serveServerOnlyStub(relPath) {
     `Cannot import "${relPath}" from browser code. ` +
     `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
     `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
-    `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead.`;
+    `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead. ` +
+    `Docs: https://docs.webjs.com/docs/server-actions`;
   return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
 throw new Error(${JSON.stringify(msg)});
 `;
@@ -335,6 +396,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);
@@ -470,17 +555,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/asset-hash.js

@@ -0,0 +1,266 @@
+/**
+ * Content-hash asset URLs for immutable caching (issue #243, feature 1).
+ *
+ * The problem: every served app module (`.js` / `.ts`) and `public/` asset
+ * ships `Cache-Control: public, max-age=3600` because its URL is
+ * un-versioned. The framework cannot serve them `immutable` (1 year) without
+ * a per-file fingerprint, because a deploy that changes a module's bytes
+ * keeps the SAME url, so a year-long immutable copy at an edge CDN would
+ * silently brick the next deploy (a real regression, see the core-serve note
+ * in `dev.js`). The importmap build id (`publishedBuildId`) does NOT change
+ * on an app-module byte change, so it cannot be the per-asset fingerprint.
+ *
+ * The fix: a PER-FILE content hash computed at serve time (no build step).
+ *
+ *   1. `withAssetHash(url)` appends `?v=<hash>` to a framework-emitted
+ *      SAME-ORIGIN absolute url (the importmap targets, the modulepreload
+ *      hrefs, the boot script specifiers). It is a NO-OP in DEV (so dev
+ *      output is byte-identical to before), a NO-OP for a CROSS-ORIGIN url
+ *      (a `https://` jspm vendor target, which jspm already versions and
+ *      which carries SRI keyed by the un-hashed url), and for a same-origin
+ *      `/`-rooted url it resolves the underlying file, looks up its hash, and
+ *      appends `?v=<hash>`.
+ *
+ *   2. The serve path (`dev.js`) serves any request carrying a `?v` query
+ *      `Cache-Control: public, max-age=31536000, immutable`. An un-fingerprinted
+ *      request keeps the 1h fallback. Dev stays `no-cache` regardless.
+ *
+ * Deploy-busts invariant: a deploy that changes a module's bytes changes its
+ * hash, so its emitted url changes, so a returning client fetches the new url
+ * instead of serving the stale immutable copy.
+ *
+ * The hash is a short prefix of a sha-256 over the file BYTES, computed
+ * synchronously (so the emit hot path stays sync) and memoized in a
+ * `Map<absPath, hash>`. The cache is cleared on the fs.watch rebuild (dev) so
+ * a changed file re-hashes, wired next to `clearVendorCache` in `dev.js`.
+ *
+ * @module asset-hash
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+/**
+ * Length of the emitted hex hash. 12 hex chars (48 bits) is plenty to
+ * distinguish builds of one file while keeping the url short. Collisions
+ * across DIFFERENT bytes of the SAME url are the only failure mode, and at
+ * 48 bits that is astronomically unlikely; a same-bytes-same-hash is exactly
+ * the desired behaviour.
+ *
+ * @type {number}
+ */
+const HASH_LEN = 12;
+
+/**
+ * Whether fingerprinting is active. Off in dev (so dev output is
+ * byte-identical to before this feature) and off until `setAssetRoots`
+ * binds the app + core roots. Both gates make `withAssetHash` a pure
+ * pass-through, which is what keeps the inert case byte-identical.
+ *
+ * @type {boolean}
+ */
+let _enabled = false;
+
+/** @type {string} */
+let _appDir = '';
+/** @type {string} */
+let _coreDir = '';
+
+/**
+ * A fingerprint of the current elision verdict (the elidable-component +
+ * inert-route set), folded into an APP MODULE's hash. An app module's SERVED
+ * body is not its raw source: `dev.js` runs `elideImportsFromSource` over it,
+ * stripping a side-effect import of a display-only component. That strip is a
+ * property of the IMPORTED component's verdict, not of the importer's own
+ * bytes, so when a component flips display-only <-> interactive the importer's
+ * served body changes while its source is byte-identical. Hashing the source
+ * alone would keep the same `?v`, and a returning client would hold the stale
+ * immutable copy (the now-interactive component never imported, so never
+ * hydrated) for the full immutable TTL. Folding the verdict fingerprint into
+ * the hash busts every app module's url on a verdict change, so the stale-copy
+ * window cannot open. Empty when no module is elidable (then an app module's
+ * hash is exactly `sha256(bytes)`), and only mixed for files under `_appDir`
+ * (core / public assets are never elision-transformed). Set by `dev.js`'s
+ * `ensureReady` after `analyzeElision`, re-set on every rebuild.
+ *
+ * @type {string}
+ */
+let _elisionFp = '';
+
+/**
+ * Memoized per-file content hash. Keyed by absolute path. Cleared on the
+ * fs.watch rebuild so a changed file re-hashes.
+ *
+ * @type {Map<string, string>}
+ */
+const _hashCache = new Map();
+
+/**
+ * Bind the asset-hash module to the app + core install roots and enable
+ * fingerprinting. Called once at boot by `dev.js` for a PROD server only
+ * (`dev === false`); a dev server never calls this, so `_enabled` stays
+ * false and `withAssetHash` is a pure no-op.
+ *
+ * @param {{ appDir: string, coreDir: string, enabled: boolean }} opts
+ * @returns {void}
+ */
+export function setAssetRoots(opts) {
+  _appDir = opts.appDir || '';
+  _coreDir = opts.coreDir || '';
+  _enabled = !!opts.enabled && !!_appDir && !!_coreDir;
+}
+
+/**
+ * Set the elision-verdict fingerprint folded into app-module hashes (see
+ * `_elisionFp`). A no-op when the value is unchanged; on a change it clears the
+ * hash cache so every app module re-hashes against the new verdict. `dev.js`
+ * calls this from `ensureReady` after `analyzeElision` (and again on each
+ * rebuild), passing a stable digest of the elidable-component + inert-route set
+ * (or `''` when nothing is elidable).
+ *
+ * @param {string} fp
+ * @returns {void}
+ */
+export function setElisionFingerprint(fp) {
+  const next = fp || '';
+  if (next === _elisionFp) return;
+  _elisionFp = next;
+  _hashCache.clear();
+}
+
+/**
+ * Clear the per-file hash cache. Wired into the dev rebuild path next to
+ * `clearVendorCache` so a changed file re-hashes (dev never fingerprints,
+ * but a future serve that re-derives the map after a rebuild stays correct,
+ * and tests rely on the clear to observe a re-hash after a byte change).
+ *
+ * @returns {void}
+ */
+export function clearAssetHashCache() {
+  _hashCache.clear();
+}
+
+/**
+ * Compute (and memoize) the short content hash for an absolute file path.
+ * Returns `''` when the file cannot be read, so the caller emits the url
+ * UNCHANGED (no `?v`), failing safe to the 1h fallback rather than breaking
+ * the url.
+ *
+ * @param {string} absPath
+ * @returns {string} the short hex hash, or `''` on a read failure
+ */
+export function assetHashFor(absPath) {
+  const cached = _hashCache.get(absPath);
+  if (cached !== undefined) return cached;
+  try {
+    const bytes = readFileSync(absPath);
+    const h = createHash('sha256').update(bytes);
+    // An app module's served body is elision-transformed, so fold the verdict
+    // fingerprint in (see `_elisionFp`). Core / public files are never
+    // transformed, so they hash over their bytes alone. Empty fp leaves an app
+    // module's hash at exactly `sha256(bytes)`.
+    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)) {
+      h.update('\0');
+      h.update(_elisionFp);
+    }
+    const hash = h.digest('hex').slice(0, HASH_LEN);
+    _hashCache.set(absPath, hash);
+    return hash;
+  } catch {
+    // A transient read failure is NOT memoized (returning '' fails safe to the
+    // 1h fallback), so a later emit re-attempts instead of pinning the file to
+    // the fallback for the process lifetime.
+    return '';
+  }
+}
+
+/**
+ * Resolve a framework-emitted same-origin absolute url to the absolute file
+ * path it serves, or `null` when the url does not map to a fingerprintable
+ * same-origin file. Mirrors the serve-path resolution in `dev.js`:
+ *   - `/__webjs/core/<rel>`  -> `<coreDir>/<rel>`  (the core runtime)
+ *   - any other `/<rel>`     -> `<appDir>/<rel>`   (app modules + public/)
+ *
+ * Containment-checked against the respective root (the same trailing-separator
+ * boundary guard the serve path uses), so a `..`-laden url that escapes the
+ * root resolves to `null` and is emitted unchanged.
+ *
+ * The `?v` query / `#hash` are stripped before resolution (a freshly-emitted
+ * url never carries one, but stay robust). A cross-origin / protocol-relative
+ * / relative url is NOT a `/`-rooted same-origin path and returns `null`.
+ *
+ * @param {string} url
+ * @returns {string | null}
+ */
+function resolveUrlToFile(url) {
+  // Only a single-leading-slash same-origin path. A protocol-relative
+  // `//host` or an absolute `scheme://` url (a vendor CDN target) is not ours.
+  if (typeof url !== 'string' || url[0] !== '/' || url[1] === '/') return null;
+  // Strip any query / hash before mapping to a file.
+  let pathname = url;
+  const q = pathname.indexOf('?');
+  if (q !== -1) pathname = pathname.slice(0, q);
+  const h = pathname.indexOf('#');
+  if (h !== -1) pathname = pathname.slice(0, h);
+  let decoded = pathname;
+  try { decoded = decodeURIComponent(pathname); } catch { /* keep raw */ }
+
+  const CORE_PREFIX = '/__webjs/core/';
+  if (decoded.startsWith(CORE_PREFIX)) {
+    const rel = decoded.slice(CORE_PREFIX.length);
+    const abs = resolve(_coreDir, rel);
+    if (abs !== _coreDir && !abs.startsWith(_coreDir + sep)) return null;
+    return abs;
+  }
+  // A `/__webjs/*` path that is not a core module (e.g. a downloaded
+  // `/__webjs/vendor/<pkg>@<ver>.js` bundle) is already version-named, so it
+  // does not need fingerprinting and is left unchanged.
+  if (decoded.startsWith('/__webjs/')) return null;
+
+  const abs = join(_appDir, decoded);
+  if (abs !== _appDir && !abs.startsWith(_appDir + sep)) return null;
+  return abs;
+}
+
+/**
+ * Append `?v=<content-hash>` to a framework-emitted same-origin absolute url
+ * for immutable caching. Composes with `withBasePath`: call ORDER is basePath
+ * then `withAssetHash` (the `?v` is a query the ingress base-path strip never
+ * touches, and the file resolution here works on the post-basePath url because
+ * a `<basePath>/app/foo.js` still resolves under `_appDir` only after the
+ * basePath is stripped, so callers apply `withAssetHash` to the ALREADY
+ * base-path-prefixed url and pass the base path so we strip it for resolution).
+ *
+ * No-op when:
+ *   - fingerprinting is disabled (dev, or roots unset) -> byte-identical output;
+ *   - the url is cross-origin / protocol-relative / relative (a vendor CDN
+ *     target keeps its exact url, so its SRI key, computed over the un-hashed
+ *     url in #235, still matches, and jspm already versions it);
+ *   - the url does not resolve to a readable same-origin file (fail-safe to the
+ *     1h fallback).
+ *
+ * @param {string} url   the (possibly base-path-prefixed) same-origin url
+ * @param {string} [basePath]  the active base path, stripped before file resolution
+ * @returns {string}
+ */
+export function withAssetHash(url, basePath = '') {
+  if (!_enabled) return url;
+  if (typeof url !== 'string' || url[0] !== '/' || url[1] === '/') return url;
+  // Resolve against the file system using the base-path-stripped url, so a
+  // sub-path-deployed `<basePath>/app/foo.js` maps to `<appDir>/app/foo.js`.
+  let forResolve = url;
+  if (basePath && url.startsWith(basePath + '/')) {
+    forResolve = url.slice(basePath.length);
+  } else if (basePath && url === basePath) {
+    forResolve = '/';
+  }
+  const abs = resolveUrlToFile(forResolve);
+  if (!abs) return url;
+  const hash = assetHashFor(abs);
+  if (!hash) return url;
+  // The freshly-emitted url never already carries a query, but stay robust:
+  // merge with `&` if one is somehow present.
+  const sepChar = url.includes('?') ? '&' : '?';
+  return `${url}${sepChar}v=${hash}`;
+}