what-server 0.8.4 → 0.11.0

package/src/adapter/core.js

@@ -0,0 +1,203 @@
+// Framework-agnostic deploy adapter core. A Web-Fetch handler
+// (request) -> Response that powers Node, Vercel and Cloudflare alike:
+//   match route -> intercept actions + revalidate webhook -> ISR cache
+//   (HIT/STALE/MISS) -> render -> respond with Cache-Control headers.
+//
+// The cache engine is OPTIONAL and injected (from what-isr) so what-server
+// stays standalone. Render is owned here (renderDocument) but overridable.
+
+import { matchRoute, parseQuery } from 'what-router/match';
+import { renderDocument } from '../index.js';
+import { createActionHandler, parseActionBody, readFetchBodyCapped } from '../action-handler.js';
+import { setRevalidationHandler } from '../revalidation-registry.js';
+import { generateCsrfToken } from '../actions.js';
+
+const ACTION_PATH = '/__what_action';
+const REVALIDATE_PATH = '/__what_revalidate';
+const CSRF_COOKIE = 'what-csrf';
+
+function headersToObject(headers) {
+  const out = {};
+  if (headers && typeof headers.forEach === 'function') headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+function readCookie(cookieHeader, name) {
+  if (!cookieHeader) return null;
+  const match = String(cookieHeader).match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+// Read + parse the action body with the shared MAX_BODY_BYTES cap. Returns
+// { tooLarge: true } when over the limit so the caller can respond 413 (DoS
+// guard parity with the Node connect/express middleware).
+async function readActionBody(request) {
+  try {
+    const read = await readFetchBodyCapped(request);
+    if (read.tooLarge) return { tooLarge: true };
+    return parseActionBody(read.raw, request.headers.get('content-type') || '');
+  } catch { return {}; }
+}
+
+async function readJsonBody(request) {
+  try { return await request.json(); } catch { return {}; }
+}
+
+function defaultRenderRoute(documentOptions) {
+  return async function renderRoute(routeMatch) {
+    const { route, params, query, request } = routeMatch;
+    const pageModule = { default: route.component, loader: route.loader };
+    const opts = routeMatch.csrfToken
+      ? { ...documentOptions, csrfToken: routeMatch.csrfToken }
+      : documentOptions;
+    const html = await renderDocument(pageModule, { params, query, request }, opts);
+    return {
+      html,
+      status: 200,
+      tags: (routeMatch.config && routeMatch.config.tags) || [],
+      path: routeMatch.path,
+    };
+  };
+}
+
+/**
+ * Create the framework request handler: (Request) -> Response.
+ *
+ * CSRF is ON BY DEFAULT (double-submit cookie):
+ *   - Every HTML response ensures a `what-csrf` cookie (SameSite=Lax, NOT
+ *     HttpOnly so the fetch client can echo it in the X-CSRF-Token header).
+ *   - Uncached HTML renders also embed <meta name="what-csrf-token"> plus the
+ *     token for hidden form fields (cached/ISR pages rely on the cookie only,
+ *     so a per-user token is never baked into shared cache entries).
+ *   - POST /__what_action validates the client token (X-CSRF-Token header for
+ *     fetch clients, `_csrf` form field for plain HTML forms) against the cookie.
+ *
+ * Opt out with `csrf: false` (e.g. token-authed APIs behind another gateway),
+ * or take full control by passing your own `actionHandler` — a custom handler
+ * owns its CSRF policy and the cookie/meta auto-provisioning is skipped.
+ *
+ * Plain HTML form posts (progressive enhancement, no JS) are accepted on
+ * /__what_action as application/x-www-form-urlencoded — see createActionHandler
+ * in action-handler.js for the field contract (_action, _csrf, _redirect).
+ */
+export function createRequestHandler(options = {}) {
+  const {
+    routes = [],
+    cache,
+    render,
+    revalidateWebhook,
+    document: documentOptions = {},
+    notFound,
+    basePath = '',
+    csrf = true,
+  } = options;
+
+  // Auto-provisioning (cookie + meta tag) only applies to the built-in
+  // handler; a user-supplied actionHandler owns its own CSRF policy.
+  const autoCsrf = csrf !== false && !options.actionHandler;
+  const actionHandler = options.actionHandler || createActionHandler(
+    autoCsrf
+      ? { getCsrfToken: (reqLike) => readCookie(reqLike.headers && reqLike.headers.cookie, CSRF_COOKIE) }
+      : { skipCsrf: true }
+  );
+
+  const renderRoute = render || defaultRenderRoute(documentOptions);
+
+  // Bind the cache engine so server actions' revalidatePath/revalidateTag (and
+  // any app code calling them from what-framework/server) purge this engine.
+  if (cache && (cache.revalidatePath || cache.revalidateTag)) {
+    setRevalidationHandler({
+      revalidatePath: cache.revalidatePath,
+      revalidateTag: cache.revalidateTag,
+    });
+  }
+
+  return async function handle(request) {
+    const url = new URL(request.url, 'http://localhost');
+    let pathname = url.pathname;
+    if (basePath && pathname.startsWith(basePath)) pathname = pathname.slice(basePath.length) || '/';
+
+    // Server actions (JSON fetch path AND plain form-post fallback)
+    if (request.method === 'POST' && pathname === ACTION_PATH) {
+      const body = await readActionBody(request);
+      if (body && body.tooLarge) {
+        return new Response(JSON.stringify({ message: 'Payload too large' }), {
+          status: 413,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      const out = await actionHandler({
+        method: 'POST',
+        headers: headersToObject(request.headers),
+        body,
+        query: Object.fromEntries(url.searchParams),
+      });
+      return new Response(out.body, { status: out.status, headers: out.headers });
+    }
+
+    // CSRF provisioning for HTML responses (double-submit cookie). If the
+    // visitor has no token cookie yet, mint one and Set-Cookie it below.
+    let csrfToken = null;
+    let csrfSetCookie = null;
+    if (autoCsrf) {
+      csrfToken = readCookie(headersToObject(request.headers).cookie, CSRF_COOKIE);
+      if (!csrfToken) {
+        csrfToken = generateCsrfToken();
+        // NOT HttpOnly: the client action() wrapper reads it to send X-CSRF-Token.
+        // Secure when the request is HTTPS (direct or via a proxy's
+        // x-forwarded-proto) or in production; OFF for plain-http localhost dev
+        // so the cookie still sets and CSRF keeps working locally.
+        const reqHeaders = headersToObject(request.headers);
+        const isHttps = reqHeaders['x-forwarded-proto'] === 'https'
+          || url.protocol === 'https:'
+          || process.env.NODE_ENV === 'production';
+        csrfSetCookie = `${CSRF_COOKIE}=${encodeURIComponent(csrfToken)}; Path=/; SameSite=Lax`
+          + (isHttps ? '; Secure' : '');
+      }
+    }
+    const withCsrfCookie = (headers) => {
+      if (csrfSetCookie) headers['set-cookie'] = csrfSetCookie;
+      return headers;
+    };
+
+    // On-demand revalidation webhook
+    if (request.method === 'POST' && pathname === REVALIDATE_PATH && revalidateWebhook) {
+      const body = await readJsonBody(request);
+      const out = await revalidateWebhook({ headers: headersToObject(request.headers), body });
+      return new Response(JSON.stringify(out.body), {
+        status: out.status,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+
+    // Route match
+    const matched = matchRoute(pathname, routes);
+    if (!matched) {
+      const html = notFound ? notFound() : '<!DOCTYPE html><html><body><h1>404 — Not Found</h1></body></html>';
+      return new Response(html, { status: 404, headers: withCsrfCookie({ 'content-type': 'text/html; charset=utf-8' }) });
+    }
+
+    const { route, params } = matched;
+    const config = route.page || { mode: route.mode || 'client' };
+    const routeMatch = { path: pathname, query: parseQuery(url.search), config, route, params, request };
+
+    // ISR cache path (static/hybrid with a cache engine). Server-mode bypasses.
+    // NOTE: cached HTML is shared across users, so the per-user CSRF token is
+    // NOT embedded in the page here — clients read it from the cookie instead.
+    if (cache && config.mode !== 'server') {
+      const result = await cache.handle(routeMatch, () => renderRoute(routeMatch));
+      return new Response(result.html, {
+        status: result.status || 200,
+        headers: withCsrfCookie({ 'content-type': 'text/html; charset=utf-8', ...(result.headers || {}) }),
+      });
+    }
+
+    // Direct render (server mode, or no cache configured): per-request HTML,
+    // safe to embed the CSRF token as a <meta> tag for forms/fetch clients.
+    if (csrfToken) routeMatch.csrfToken = csrfToken;
+    const out = await renderRoute(routeMatch);
+    const headers = withCsrfCookie({ 'content-type': 'text/html; charset=utf-8' });
+    if (config.mode === 'server') headers['Cache-Control'] = 'private, no-store';
+    return new Response(out.html, { status: out.status || 200, headers });
+  };
+}

package/src/adapter/node.js

@@ -0,0 +1,77 @@
+// Node deploy adapter — wraps the framework-agnostic Web-Fetch handler from
+// core.js in a Node http.Server / connect-style middleware. Dependency-free
+// (Node 18+ ships global Request/Response/Headers).
+
+import http from 'node:http';
+import { createRequestHandler } from './core.js';
+
+async function nodeToWebRequest(req) {
+  const host = req.headers.host || 'localhost';
+  const url = `http://${host}${req.url}`;
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (v != null) headers.set(k, Array.isArray(v) ? v.join(', ') : String(v));
+  }
+  let body;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    if (chunks.length) body = Buffer.concat(chunks);
+  }
+  return new Request(url, { method: req.method, headers, body });
+}
+
+async function sendWebResponse(res, webRes) {
+  res.statusCode = webRes.status;
+  webRes.headers.forEach((value, key) => res.setHeader(key, value));
+  const text = await webRes.text();
+  res.end(text);
+}
+
+/** Convert a Web-Fetch handler into a Node (req, res) listener. */
+export function toNodeListener(handler) {
+  return async function listener(req, res) {
+    try {
+      const webReq = await nodeToWebRequest(req);
+      const webRes = await handler(webReq);
+      await sendWebResponse(res, webRes);
+    } catch (err) {
+      if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/html; charset=utf-8' });
+      res.end('<!DOCTYPE html><html><body><h1>500 — Server Error</h1></body></html>');
+      // eslint-disable-next-line no-console
+      console.error('[what-server] request error:', err);
+    }
+  };
+}
+
+/** connect/express middleware: handles app routes, calls next() on a 404. */
+export function whatMiddleware(options = {}) {
+  const handler = createRequestHandler(options);
+  return async function middleware(req, res, next) {
+    const webReq = await nodeToWebRequest(req);
+    const webRes = await handler(webReq);
+    if (webRes.status === 404 && typeof next === 'function') return next();
+    await sendWebResponse(res, webRes);
+  };
+}
+
+/**
+ * Create a ready-to-listen Node server. Starts the poll scheduler (if provided)
+ * and stops it on SIGTERM/SIGINT.
+ *   const server = createServer({ routes, cache, scheduler });
+ *   server.listen(3000);
+ */
+export function createServer(options = {}) {
+  const handler = createRequestHandler(options);
+  const server = http.createServer(toNodeListener(handler));
+
+  const { scheduler } = options;
+  if (scheduler) {
+    scheduler.start();
+    const stop = () => { try { scheduler.stop(); } catch {} server.close(); };
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+  }
+
+  return server;
+}

package/src/adapter/static.js

@@ -0,0 +1,62 @@
+// Static export adapter — build-time render of static/hybrid routes to a
+// deployable directory of .html files (+ a data.json per page for client-side
+// navigation, mirroring Next's _next/data).
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { matchRoute } from 'what-router/match';
+import { renderDocument, serializeState } from '../index.js';
+
+function isDynamic(path) {
+  return path.includes(':') || path.includes('*') || path.includes('[');
+}
+
+// Build a concrete URL from a route pattern + params (:p, [p], [...p], *p).
+function buildConcretePath(pattern, params) {
+  return pattern
+    .replace(/\[\.\.\.(\w+)\]/g, (_, n) => params[n] ?? '')
+    .replace(/\[(\w+)\]/g, (_, n) => params[n] ?? '')
+    .replace(/[:*](\w+)/g, (_, n) => params[n] ?? '');
+}
+
+export async function exportStatic({ routes = [], outDir, render, documentOptions = {} } = {}) {
+  const written = [];
+
+  for (const route of routes) {
+    const mode = (route.page && route.page.mode) || route.mode;
+    if (mode !== 'static' && mode !== 'hybrid') continue;
+
+    const pageModule = { default: route.component, loader: route.loader };
+
+    let concrete = [route.path];
+    if (isDynamic(route.path)) {
+      if (typeof route.getStaticPaths !== 'function') continue; // can't enumerate
+      const result = await route.getStaticPaths();
+      concrete = (result.paths || []).map((p) => buildConcretePath(route.path, p.params || {}));
+    }
+
+    for (const urlPath of concrete) {
+      const matched = matchRoute(urlPath, [route]);
+      const params = matched ? matched.params : {};
+      const reqCtx = { params, query: {} };
+
+      const html = render
+        ? await render(pageModule, reqCtx)
+        : await renderDocument(pageModule, reqCtx, documentOptions);
+
+      const dirPath = join(outDir, urlPath === '/' ? '' : urlPath);
+      await mkdir(dirPath, { recursive: true });
+      await writeFile(join(dirPath, 'index.html'), html);
+
+      // data.json for client-side navigation (loader data without a round-trip)
+      if (typeof route.loader === 'function') {
+        const data = await route.loader(reqCtx);
+        await writeFile(join(dirPath, '__what_data.json'), serializeState({ loaderData: data }));
+      }
+
+      written.push(urlPath);
+    }
+  }
+
+  return { pages: written };
+}

package/src/adapter/vercel.js

@@ -0,0 +1,93 @@
+// Vercel adapter. The runtime render function is the same Web-Fetch core
+// handler (deployable as a Vercel Function). ISR maps to Vercel's native
+// s-maxage/stale-while-revalidate headers emitted by the cache engine, so it
+// works on Vercel with no extra config. buildVercelOutput writes a Build
+// Output API v3 directory (config.json + functions/<name>.func layout).
+
+import { createRequestHandler } from './core.js';
+
+export function createVercelHandler(options = {}) {
+  // Vercel Functions accept a Web-Fetch (Request) -> Response handler.
+  return createRequestHandler(options);
+}
+
+/**
+ * Write a Build Output API v3 directory (https://vercel.com/docs/build-output-api/v3):
+ *
+ *   .vercel/output/
+ *     config.json                      { version: 3, routes: [...] }
+ *     static/**                        (optional) copied from `staticDir`
+ *     functions/<name>.func/
+ *       .vc-config.json                { runtime, handler, launcherType }
+ *       index.mjs (+ any `files`)      the bundled function entry
+ *
+ * Options:
+ *   - outDir        default '.vercel/output'
+ *   - functionName  default 'render'
+ *   - runtime       default 'nodejs22.x' (any Vercel Node runtime id)
+ *   - files         map of { 'relative/path.mjs': contents } written INTO the
+ *                   .func directory. Must include the handler entry (the app's
+ *                   build step bundles routes + createVercelHandler into it).
+ *   - handler       entry filename inside the .func dir, default 'index.mjs'
+ *   - staticDir     (optional) directory copied to static/ — served by Vercel's
+ *                   CDN before the function ever runs.
+ *
+ * Backward compatible: called with no `files`, it writes config.json only and
+ * the app's build step is responsible for emitting the functions/ directory.
+ *
+ * The function entry must export a Web-Fetch handler, e.g.:
+ *   // index.mjs (bundled with routes + what-server)
+ *   import { createVercelHandler } from 'what-server';
+ *   export default createVercelHandler({ routes });
+ */
+export async function buildVercelOutput({
+  outDir = '.vercel/output',
+  functionName = 'render',
+  runtime = 'nodejs22.x',
+  files = null,
+  handler = 'index.mjs',
+  staticDir = null,
+} = {}) {
+  const { mkdir, writeFile, cp } = await import('node:fs/promises');
+  const { join, dirname } = await import('node:path');
+  await mkdir(outDir, { recursive: true });
+
+  const config = {
+    version: 3,
+    routes: [
+      // CDN-served static assets win before the render function runs.
+      { handle: 'filesystem' },
+      { src: '/.*', dest: `/${functionName}` },
+    ],
+  };
+  await writeFile(join(outDir, 'config.json'), JSON.stringify(config, null, 2));
+
+  if (staticDir) {
+    await cp(staticDir, join(outDir, 'static'), { recursive: true });
+  }
+
+  let functionDir = null;
+  if (files && typeof files === 'object') {
+    functionDir = join(outDir, 'functions', `${functionName}.func`);
+    await mkdir(functionDir, { recursive: true });
+    const vcConfig = {
+      runtime,
+      handler,
+      launcherType: 'Nodejs',
+      shouldAddHelpers: false,
+      supportsResponseStreaming: true,
+    };
+    await writeFile(join(functionDir, '.vc-config.json'), JSON.stringify(vcConfig, null, 2));
+    for (const [rel, contents] of Object.entries(files)) {
+      const dest = join(functionDir, rel);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, contents);
+    }
+    if (!(handler in files)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[what-server] buildVercelOutput: files does not include the handler entry "${handler}" — the deploy will 500 until your build emits it.`);
+    }
+  }
+
+  return { config, outDir, functionDir };
+}