@webjsdev/server 0.8.9 → 0.8.11

package/src/html-cache.js

@@ -0,0 +1,305 @@
+/**
+ * Server HTML response cache with TTL and on-demand revalidation: the
+ * no-build equivalent of Next.js's Full Route Cache + ISR.
+ *
+ * A fully-static / inert route re-runs the entire SSR pipeline (layout
+ * chain, renderToString, metadata merge, importmap splice) on every
+ * request even though it proves identical HTML each time. This module
+ * caches the rendered HTML in the existing pluggable store
+ * (`getStore()` / `memoryStore` in dev, `redisStore` when configured)
+ * under a namespaced key, and serves it WITHOUT re-running the page
+ * function on a hit within the revalidation window.
+ *
+ * SAFETY: caching is OPT-IN and conservative. A wrongly-cached per-user
+ * page served to the wrong visitor is a data leak, so the page author
+ * MUST opt in by declaring a revalidation window, and the framework
+ * applies several defense-in-depth guards before it stores anything.
+ *
+ * The opt-in trigger is `export const revalidate = N` (seconds) on the
+ * page module (the Next idiom, read once cheaply before the cache lookup).
+ * The contract: declaring `revalidate` is the author asserting "this page
+ * is the same for everyone for N seconds". A page that reads `cookies()` /
+ * a session (per-user output) MUST NOT set `revalidate`.
+ *
+ * @module html-cache
+ */
+
+import { getStore } from './cache.js';
+import { STREAM_MARKER } from './conditional-get.js';
+import { publishedBuildId } from './importmap.js';
+import { dynamicAccessed } from './context.js';
+
+/** Namespace prefix for every cached-HTML key, so a flush can target it. */
+const KEY_PREFIX = 'webjs:html:';
+
+/**
+ * Internal response header `ssrPage` stamps on a render that opted into the
+ * HTML cache (its value is the revalidate TTL in seconds). The response
+ * funnel reads it, re-checks the guards against the FINAL response (after
+ * segment middleware, which may have appended a per-user Set-Cookie the SSR
+ * side could not see), writes the cache, and strips the marker so it never
+ * reaches the client. Mirrors the BUFFERED / STREAM marker pattern.
+ */
+export const HTML_CACHE_MARKER = 'x-webjs-html-cache';
+
+/**
+ * Generation counter folded into every key namespace. `revalidateAll()`
+ * bumps it so every previously-cached HTML entry becomes unreachable in one
+ * step (the CacheStore interface has no key-scan primitive, so a global
+ * clear cannot enumerate keys), and the store TTL eventually reclaims the
+ * orphaned entries. A single process clears its own memory store this way
+ * synchronously; a Redis-backed multi-process deploy bumps per process and
+ * leans on the TTL for the rest (a best-effort global flush).
+ */
+let _generation = 0;
+
+/**
+ * Read the revalidation window (seconds) a page module opted into via
+ * `export const revalidate = N` (the Next idiom). Returns a positive finite
+ * number of seconds, or `null` when the page did not opt in (the default:
+ * no server HTML caching, current behavior).
+ *
+ * `revalidate = 0`, a negative, NaN, Infinity, or a non-number is treated
+ * as "no caching" (opt-out), matching the Next semantics where 0 means
+ * always-dynamic. The trigger is the page-module export ONLY (read once,
+ * cheaply, before the cache lookup), so a per-user page that never declares
+ * it is never cached.
+ *
+ * @param {Record<string, any> | null | undefined} pageModule
+ * @returns {number | null}
+ */
+export function readRevalidate(pageModule) {
+  const raw = pageModule ? pageModule.revalidate : undefined;
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) return null;
+  return raw;
+}
+
+/**
+ * The cache key for a request: the FULL URL (path + search string), since
+ * `searchParams` change page output. Normalized to path + sorted query so
+ * `?a=1&b=2` and `?b=2&a=1` share an entry. Two more discriminators are
+ * folded into the namespace:
+ *
+ *  - the in-process generation, so `revalidateAll()` (a generation bump)
+ *    makes every prior key unreachable in one step;
+ *  - the published build id (the importmap fingerprint), so a NEW DEPLOY
+ *    naturally writes and reads under fresh keys. The cached HTML bakes the
+ *    deploy's `data-webjs-build` importmap into its boot script, so a Redis
+ *    store that survives a deploy must NOT let a v2 process serve a v1-body
+ *    (resolving modules against stale vendor URLs). Folding the build id in
+ *    means a deploy effectively invalidates all cached HTML for free.
+ *
+ * @param {URL} url
+ * @returns {string}
+ */
+export function htmlCacheKey(url) {
+  const params = [...url.searchParams.entries()].sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0
+  );
+  const search = params.length
+    ? '?' + params.map(([k, v]) => `${k}=${v}`).join('&')
+    : '';
+  const build = publishedBuildId() || 'nobuild';
+  return `${KEY_PREFIX}${build}:${_generation}:${url.pathname}${search}`;
+}
+
+/**
+ * Read a cached HTML entry for a URL. Returns the parsed record (body +
+ * the headers needed to faithfully rebuild the response) or null on a
+ * miss / expiry / parse error (fail open to a fresh render).
+ *
+ * @param {URL} url
+ * @returns {Promise<{ body: string, contentType: string, cacheControl: string, status: number } | null>}
+ */
+export async function readHtmlCache(url) {
+  try {
+    const raw = await getStore().get(htmlCacheKey(url));
+    if (!raw) return null;
+    const rec = JSON.parse(raw);
+    if (!rec || typeof rec.body !== 'string') return null;
+    return rec;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a rendered HTML response for a URL with TTL = revalidate seconds.
+ * Best-effort: a store error never affects the live response.
+ *
+ * @param {URL} url
+ * @param {{ body: string, contentType: string, cacheControl: string, status: number }} rec
+ * @param {number} revalidateSeconds
+ */
+export async function writeHtmlCache(url, rec, revalidateSeconds) {
+  try {
+    await getStore().set(htmlCacheKey(url), JSON.stringify(rec), revalidateSeconds * 1000);
+  } catch {
+    /* a store write failure must never crash the response */
+  }
+}
+
+/**
+ * Decide whether a freshly-rendered Response is SAFE to cache. This is the
+ * defense-in-depth gate that runs AFTER the page opted in via `revalidate`.
+ * Returns true only when every guard passes:
+ *
+ *  - status 200 (an error / redirect / 404 is request-specific)
+ *  - NOT a streamed Suspense body (it cannot be buffered cheaply, and an
+ *    unflushed stream has no stable bytes to cache)
+ *  - NO non-framework Set-Cookie. A page that sets a session / per-user
+ *    cookie is per-user output and must not be shared. The framework's own
+ *    CSRF cookie (`webjs_csrf`) is allowed and re-minted per response on a
+ *    cache hit, so its presence does not block caching.
+ *  - CSP is OFF. With CSP enabled the inline boot script carries a fresh
+ *    per-request nonce, so the body varies per request and a cached body
+ *    would replay a stale nonce that the response's CSP header rejects.
+ *
+ * @param {Response} res
+ * @param {{ cspEnabled?: boolean }} [guards]
+ * @returns {boolean}
+ */
+export function isCacheableResponse(res, guards = {}) {
+  if (res.status !== 200) return false;
+  if (res.headers.has(STREAM_MARKER)) return false;
+  if (guards.cspEnabled) return false;
+  if (hasNonFrameworkSetCookie(res)) return false;
+  return true;
+}
+
+/**
+ * True when the response carries a Set-Cookie OTHER than the framework's
+ * own CSRF cookie. Reads each cookie individually via `getSetCookie()`, the
+ * only correct way to enumerate multiple Set-Cookie values (a combined
+ * `get('set-cookie')` cannot be split safely, since a cookie value or an
+ * Expires date can contain a comma). When `getSetCookie` is unavailable
+ * (a runtime older than Node 24) this FAILS SAFE: it reports a
+ * non-framework cookie (do not cache) rather than parsing only the first of
+ * a combined header and wrongly judging it framework-only.
+ *
+ * @param {Response} res
+ * @returns {boolean}
+ */
+function hasNonFrameworkSetCookie(res) {
+  const h = res.headers;
+  if (typeof h.getSetCookie !== 'function') {
+    // No reliable per-cookie enumeration: fail safe (treat as per-user).
+    return h.has('set-cookie');
+  }
+  for (const c of h.getSetCookie()) {
+    const name = c.split('=', 1)[0].trim().toLowerCase();
+    if (name !== 'webjs_csrf') return true;
+  }
+  return false;
+}
+
+/**
+ * Evict the cached HTML for one path (server-side, on-demand
+ * revalidation: the no-build ISR revalidation hook). A server action that
+ * mutates the data a cached page renders calls this so the next request
+ * re-renders. Distinct from the client-side `revalidate()` (which evicts
+ * the browser snapshot cache).
+ *
+ * The path may include a search string. A bare path with no query evicts
+ * ONLY the no-query entry; pass the exact `path?query` to target a
+ * specific query variant, or call `revalidateAll()` to clear everything.
+ *
+ * @param {string} path  e.g. '/blog' or '/blog?page=2'
+ * @returns {Promise<void>}
+ */
+export async function revalidatePath(path) {
+  if (typeof path !== 'string' || !path) return;
+  // Build the same normalized key readHtmlCache / writeHtmlCache produce.
+  let url;
+  try {
+    url = new URL(path, 'http://internal.invalid');
+  } catch {
+    return;
+  }
+  try {
+    await getStore().delete(htmlCacheKey(url));
+  } catch {
+    /* a store delete failure is non-fatal: the TTL still expires the entry */
+  }
+}
+
+/**
+ * Response-funnel step (#241): if the response carries the HTML_CACHE_MARKER
+ * (the SSR opted it into caching), re-check every guard against the FINAL
+ * response and, when it passes, buffer the body and store it under the URL
+ * key with TTL = the marked revalidate seconds. Always strips the marker so
+ * it never reaches the client. Returns the same response (the marker removal
+ * mutates its headers in place). Best-effort: any failure leaves the live
+ * response untouched. The CSP guard was already applied on the SSR side (the
+ * marker is only stamped when CSP is off), so it is not re-checked here.
+ *
+ * @param {Request} req
+ * @param {Response} res
+ * @param {URL} url
+ * @returns {Promise<Response>}
+ */
+export async function commitHtmlCache(req, res, url) {
+  const marker = res.headers.get(HTML_CACHE_MARKER);
+  if (!marker) return res;
+  res.headers.delete(HTML_CACHE_MARKER);
+  const revalidateSeconds = Number(marker);
+  if (!Number.isFinite(revalidateSeconds) || revalidateSeconds <= 0) return res;
+  // Per-user leak defense (#241). The page set `revalidate` (asserting "same
+  // for everyone"), but if the render actually read per-user request state
+  // (cookies() / headers() / getSession()), its body varies by visitor and
+  // must NOT be cached, even though it set no new Set-Cookie. Fail safe (skip
+  // caching) and warn the author ONCE per path so the wrong `revalidate` is
+  // visible without spamming the log.
+  if (dynamicAccessed()) {
+    warnDynamicRevalidateOnce(url.pathname);
+    return res;
+  }
+  // Re-check status / streaming / cookie guards against the final response.
+  if (!isCacheableResponse(res)) return res;
+  try {
+    const body = await res.clone().text();
+    await writeHtmlCache(
+      url,
+      {
+        body,
+        contentType: res.headers.get('content-type') || 'text/html; charset=utf-8',
+        cacheControl: res.headers.get('cache-control') || 'no-store',
+        status: res.status,
+      },
+      revalidateSeconds,
+    );
+  } catch {
+    /* a buffer / store failure must never affect the live response */
+  }
+  return res;
+}
+
+/**
+ * Paths already warned about a `revalidate` on a per-user page, so the
+ * console.warn fires once per offending route rather than once per request.
+ * @type {Set<string>}
+ */
+const _warnedDynamicPaths = new Set();
+
+/** @param {string} pathname */
+function warnDynamicRevalidateOnce(pathname) {
+  if (_warnedDynamicPaths.has(pathname)) return;
+  _warnedDynamicPaths.add(pathname);
+  console.warn(
+    `[webjs] not caching ${pathname}: it exported \`revalidate\` but read ` +
+    `per-user request state (cookies() / headers() / getSession()) during ` +
+    `render, so its output varies by visitor. Remove \`revalidate\` from a ` +
+    `per-user page, or stop reading request state if it is the same for ` +
+    `everyone. The page is being served fresh (uncached) to avoid a leak.`
+  );
+}
+
+/** Evict ALL cached HTML for this process. @returns {void} */
+export function revalidateAll() {
+  _generation++;
+}
+
+/** Internal: current generation, folded into keys by `htmlCacheKey`. */
+export function htmlCacheGeneration() {
+  return _generation;
+}

package/src/json.js

@@ -1,6 +1,7 @@
 import { stringify as wjStringify, parse as wjParse } from '@webjsdev/core';
-import { getRequest } from './context.js';
+import { getRequest, getBodyLimits } from './context.js';
 import { RPC_CONTENT_TYPE } from './actions.js';
+import { readTextBounded, BodyLimitError, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 
 /**
  * Content-negotiated JSON helper for API routes (`route.js` handlers).
@@ -51,11 +52,19 @@ export async function json(data, init = {}) {
  * that accept rich bodies from the `richFetch` helper but plain JSON
  * from everyone else.
  *
+ * Enforces the request body-size limit (issue #237): an over-limit body throws
+ * a `BodyLimitError`, which the API dispatcher (`handleApi`) maps to a 413, so a
+ * `route.{js,ts}` handler doing `await readBody(req)` is protected with no extra
+ * code. The over-limit body is never buffered whole (see `readTextBounded`).
+ *
  * @param {Request} req
  */
 export async function readBody(req) {
   const ct = req.headers.get('content-type') || '';
-  const text = await req.text();
+  const limits = getBodyLimits();
+  const limit = limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
+  const { tooLarge, text } = await readTextBounded(req, limit);
+  if (tooLarge) throw new BodyLimitError();
   if (!text) return null;
   if (ct.includes(RPC_CONTENT_TYPE)) return wjParse(text);
   return JSON.parse(text);

package/src/node-version.js

@@ -0,0 +1,102 @@
+/**
+ * Node-version preflight guard (issue #238).
+ *
+ * webjs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
+ * no-build TypeScript strip) and recursive `fs.watch` (dev live-reload). On an
+ * older Node the failure surfaces late and cryptically (a strip error or a
+ * missing API deep inside a request), not as a clear "you need Node 24+". This
+ * module is the single early preflight that fails fast with an actionable
+ * message naming the exact version found and the version required.
+ *
+ * The check is a PURE function (`checkNodeVersion`) so it unit-tests with
+ * injected version strings, no spawning an old Node. `assertNodeVersion` is the
+ * thin side-effecting wrapper the CLI and the server entry both call: it prints
+ * to stderr + exits non-zero (CLI), or throws a clear Error (embedded server),
+ * depending on the `onFail` mode.
+ *
+ * The minimum is sourced from ONE place, this package's own `engines.node`
+ * field, so it never drifts from what npm enforces on install.
+ */
+import { createRequire } from 'node:module';
+
+/**
+ * Parse the leading major-version integer out of a Node version string.
+ * Handles `'24.1.0'`, `'v24.1.0'`, and prerelease tags like
+ * `'24.0.0-nightly20240101'`. Returns `NaN` when no leading integer is found.
+ * @param {string} version
+ * @returns {number}
+ */
+export function parseMajor(version) {
+  const m = String(version).trim().match(/^v?(\d+)/);
+  return m ? Number(m[1]) : NaN;
+}
+
+/**
+ * Parse the minimum major version out of an `engines.node` range like
+ * `'>=24.0.0'`, `'>= 24'`, or `'24.x'`. Returns `NaN` when no integer is found.
+ * @param {string} engines
+ * @returns {number}
+ */
+export function parseRequiredMajor(engines) {
+  const m = String(engines).match(/(\d+)/);
+  return m ? Number(m[1]) : NaN;
+}
+
+/**
+ * Pure version check. Compares the running Node major against the required
+ * minimum and returns a structured result (no side effects).
+ * @param {string} current the running Node version (e.g. `process.versions.node`)
+ * @param {number} requiredMajor the minimum acceptable major version
+ * @returns {{ ok: boolean, current: string, currentMajor: number, requiredMajor: number, message: string }}
+ */
+export function checkNodeVersion(current, requiredMajor) {
+  const currentMajor = parseMajor(current);
+  // If we cannot parse the running version, fail open: do not block a runtime
+  // that reports an unusual version string. The deep APIs guard themselves.
+  const ok = Number.isNaN(currentMajor) || currentMajor >= requiredMajor;
+  const message = ok
+    ? ''
+    : `webjs requires Node ${requiredMajor}+ but found Node ${current}. ` +
+      `webjs is buildless and relies on Node ${requiredMajor}'s built-in ` +
+      `TypeScript strip (module.stripTypeScriptTypes) and recursive fs.watch, ` +
+      `neither of which exists on Node ${currentMajor}. ` +
+      `Upgrade to Node ${requiredMajor} or newer (see https://nodejs.org).`;
+  return { ok, current, currentMajor, requiredMajor, message };
+}
+
+/**
+ * Read the minimum required Node major from this package's own
+ * `engines.node` field, so the minimum lives in exactly one place. Falls back
+ * to 24 if the field is missing or unparseable (defensive only).
+ * @returns {number}
+ */
+export function requiredNodeMajor() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    const major = parseRequiredMajor(pkg?.engines?.node || '');
+    if (!Number.isNaN(major)) return major;
+  } catch {}
+  return 24;
+}
+
+/**
+ * Side-effecting preflight: assert the running Node satisfies the minimum.
+ * On an unsupported Node, either exits the process non-zero (CLI, `onFail:
+ * 'exit'`) or throws a clear Error (embedded server, `onFail: 'throw'`).
+ * A no-op on a supported Node.
+ * @param {{ current?: string, requiredMajor?: number, onFail?: 'exit'|'throw' }} [opts]
+ * @returns {void}
+ */
+export function assertNodeVersion(opts = {}) {
+  const current = opts.current ?? process.versions.node;
+  const requiredMajor = opts.requiredMajor ?? requiredNodeMajor();
+  const onFail = opts.onFail ?? 'throw';
+  const result = checkNodeVersion(current, requiredMajor);
+  if (result.ok) return;
+  if (onFail === 'exit') {
+    console.error(result.message);
+    process.exit(1);
+  }
+  throw new Error(result.message);
+}

package/src/page-action.js

@@ -0,0 +1,225 @@
+import { isNotFound, isRedirect } from '@webjsdev/core';
+import { ssrPage, ssrNotFound, loadModule } from './ssr.js';
+import { readBytesBounded, payloadTooLarge, DEFAULT_MAX_MULTIPART_BYTES } from './body-limit.js';
+import { getBodyLimits } from './context.js';
+
+/**
+ * Page server actions: a `page.{js,ts}` may export an `action` function that
+ * handles a non-GET/HEAD submission to the page's own URL. This is webjs's
+ * Remix-style page-action path, adapted to the no-build progressive-enhancement
+ * model: a `<form method="POST">` submits with JS disabled, the action runs on
+ * the server, and a validation failure re-renders the SAME page with field
+ * errors and the user's typed values preserved.
+ *
+ * Behavior (see #244):
+ *   - Action throws `redirect(url)` or `notFound()` => honored exactly as a page
+ *     render does (3xx / 404). A thrown `redirect()` may target an external URL
+ *     (it is the explicit nav sentinel, author-controlled).
+ *   - Action returns a SUCCESS result => 303 See Other to `result.redirect` if
+ *     present, else to the page's own path (Post/Redirect/Get, so a reload does
+ *     not resubmit). `result.redirect` MUST be a same-site local path (see
+ *     `sameSiteRedirect`), a non-local value is ignored to avoid an
+ *     open-redirect through a user-controlled action result.
+ *   - Action returns a FAILURE result => re-SSR the SAME page (status 422) with
+ *     the result on `ctx.actionData`, so the page template can read
+ *     `actionData.fieldErrors` / `actionData.values` and repopulate inputs.
+ *
+ * Failure detection is robust (it does not require a literal `success: false`):
+ * see `isFailureResult`.
+ *
+ * @typedef {{
+ *   success?: boolean,
+ *   data?: unknown,
+ *   error?: string,
+ *   fieldErrors?: Record<string,string>,
+ *   values?: Record<string,string>,
+ *   status?: number,
+ *   redirect?: string,
+ * }} ActionResult
+ */
+
+/**
+ * Whether an action result is a FAILURE (re-render the page) rather than a
+ * success (PRG redirect). A result is a failure when ANY of these hold:
+ *   - `result.success === false` (explicit), OR
+ *   - `result.fieldErrors` is present (per-field validation messages), OR
+ *   - `result.error` is present AND `result.success !== true`.
+ *
+ * Success is the explicit `success: true`, or a bare value (or
+ * undefined/null) carrying no error markers. This means an action that returns
+ * `{ error, status }` or `{ fieldErrors }` WITHOUT a literal `success: false`
+ * is still treated as a failure and its error is surfaced, not swallowed.
+ *
+ * @param {ActionResult | null | undefined} result
+ * @returns {boolean}
+ */
+function isFailureResult(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (result.success === false) return true;
+  if (result.fieldErrors != null) return true;
+  if (result.error != null && result.success !== true) return true;
+  return false;
+}
+
+/**
+ * Restrict a page action's `result.redirect` to a SAME-SITE local target.
+ * Allowed: a path beginning with a single `/` (e.g. `/login`, `/a?b=1#c`).
+ * Rejected: a protocol-relative `//host/...` and any absolute `scheme://...`
+ * URL. A user-controlled redirect target is an open-redirect vector, so a
+ * non-local value is dropped and the caller falls back to the page's own path.
+ *
+ * A thrown `redirect(absoluteUrl)` (the nav sentinel) is intentionally NOT
+ * routed through here: that is the author-controlled escape hatch for a
+ * legitimate external redirect.
+ *
+ * @param {unknown} target
+ * @returns {string | null} the safe local path, or null when not same-site
+ */
+function sameSiteRedirect(target) {
+  if (typeof target !== 'string') return null;
+  // Must start with a single slash (a leading `//` is protocol-relative and
+  // would navigate cross-origin).
+  if (!target.startsWith('/') || target.startsWith('//')) return null;
+  // A backslash after the leading slash (`/\evil.com`) is normalized by some
+  // browsers into a protocol-relative URL, so reject it too.
+  if (target.startsWith('/\\')) return null;
+  return target;
+}
+
+/**
+ * Load a page module and return its `action` export, or null if it has none.
+ * Uses ssr.js's shared `loadModule`, so page-action loading is consistent with
+ * the SSR re-render. In prod the URL is stable and Node's module cache serves
+ * one evaluation; in dev a cache-bust forces a fresh evaluation.
+ *
+ * @param {string} file absolute path to the page module
+ * @param {boolean} dev
+ * @returns {Promise<{ action: Function, module: Record<string, unknown> } | null>}
+ */
+export async function loadPageAction(file, dev) {
+  try {
+    const mod = await loadModule(file, dev);
+    return typeof mod.action === 'function'
+      ? { action: /** @type {Function} */ (mod.action), module: mod }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the submitted body ONCE, bounded by the form/multipart limit (issue
+ * #237), and return both a `FormData` (handed to the action as `formData`) and a
+ * rebuilt `Request` carrying the already-read bytes (handed to the action as
+ * `request`, so it can still call `request.json()` / `request.formData()`). The
+ * body is consumed off the ORIGINAL request directly, NOT via `req.clone()`: a
+ * tee'd clone whose reader is cancelled mid-stream (the over-limit case)
+ * deadlocks the untaken branch, hanging the response.
+ *
+ * An over-limit body is reported as `tooLarge` (the caller returns 413) and is
+ * never buffered whole. A form posts more than a JSON RPC call (textarea, small
+ * upload), so it uses the higher `multipart` cap. A non-form content type yields
+ * an empty FormData so the action signature stays stable; the rebuilt request
+ * still carries the raw bytes for the action to parse however it likes.
+ *
+ * @param {Request} req
+ * @returns {Promise<{ tooLarge: boolean, formData: FormData, request: Request }>}
+ */
+async function parseFormBody(req) {
+  const ct = req.headers.get('content-type') || '';
+  const limits = getBodyLimits();
+  const limit = limits ? limits.multipart : DEFAULT_MAX_MULTIPART_BYTES;
+  const { tooLarge, bytes } = await readBytesBounded(req, limit);
+  if (tooLarge) return { tooLarge: true, formData: new FormData(), request: req };
+
+  // Rebuild a fresh Request from the bytes so the action can re-read the body.
+  const headers = new Headers(req.headers);
+  const rebuilt = new Request(req.url, {
+    method: req.method,
+    headers,
+    body: bytes && bytes.byteLength ? bytes : undefined,
+  });
+
+  const isForm = /multipart\/form-data|application\/x-www-form-urlencoded/i.test(ct);
+  let formData = new FormData();
+  if (isForm) {
+    // Parse a SECOND fresh Request (the rebuilt one is reserved for the action).
+    const forParse = new Request(req.url, {
+      method: 'POST',
+      headers: ct ? { 'content-type': ct } : undefined,
+      body: bytes && bytes.byteLength ? bytes : undefined,
+    });
+    formData = await forParse.formData();
+  }
+  return { tooLarge: false, formData, request: rebuilt };
+}
+
+/**
+ * Run a page `action` for a non-GET/HEAD request and produce the HTTP response.
+ * The caller has already confirmed the path matches a page route AND that the
+ * page module exports an `action` (via `loadPageAction`). The action runs inside
+ * the same segment middleware as the page (the caller wraps this).
+ *
+ * The failure re-render reuses the SAME page module instance whose `action` just
+ * ran (passed through as `pageModule`), so the page module is loaded once per
+ * POST rather than evaluated a second time.
+ *
+ * @param {import('./router.js').PageRoute} route
+ * @param {Record<string,string>} params
+ * @param {URL} url
+ * @param {{ action: Function, module: Record<string, unknown> }} loaded the page module's `action` plus the loaded module
+ * @param {Request} req
+ * @param {object} ssrOpts the same opts object `ssrPage` receives in dev.js
+ * @returns {Promise<Response>}
+ */
+export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
+  const { action, module: pageModule } = loaded;
+  const searchParams = Object.fromEntries(url.searchParams.entries());
+  let formData = new FormData();
+  // The body is read ONCE here (bounded). `actionReq` is a rebuilt request the
+  // action can re-read; on a parse failure it falls back to the original `req`.
+  let actionReq = req;
+  try {
+    const parsed = await parseFormBody(req);
+    // Over the form/multipart limit (issue #237): 413 before the action runs.
+    if (parsed.tooLarge) return payloadTooLarge();
+    formData = parsed.formData;
+    actionReq = parsed.request;
+  } catch {
+    formData = new FormData();
+  }
+
+  /** @type {ActionResult | undefined} */
+  let result;
+  try {
+    result = await action({ request: actionReq, params, searchParams, url, formData });
+  } catch (err) {
+    if (isRedirect(err)) {
+      const e = /** @type any */ (err);
+      // A thrown redirect from an action is honored as the page render does.
+      // Use the action's chosen status (307/308) so an explicit redirect()
+      // keeps its semantics; PRG (303) is the SUCCESS-result path below.
+      return new Response(null, { status: e.status || 307, headers: { location: e.url } });
+    }
+    if (isNotFound(err)) {
+      return ssrNotFound(ssrOpts.notFoundFile ?? null, { ...ssrOpts, req, url });
+    }
+    throw err;
+  }
+
+  if (!isFailureResult(result)) {
+    // SUCCESS: Post/Redirect/Get. A user-controlled `result.redirect` is only
+    // honored when it is a same-site local path; otherwise fall back to the
+    // page's own path so a poisoned value cannot become an open redirect.
+    const ownPath = (url.pathname + url.search) || '/';
+    const safe = result ? sameSiteRedirect(result.redirect) : null;
+    return new Response(null, { status: 303, headers: { location: safe || ownPath } });
+  }
+
+  // FAILURE: re-render the SAME page with the action result available on
+  // ctx.actionData, status 422. Repopulation is the page author's job (native
+  // `value=${actionData.values?.field}`). Pass the already-loaded page module so
+  // the re-render shares this POST's single evaluation.
+  const status = typeof result.status === 'number' && result.status >= 400 ? result.status : 422;
+  return ssrPage(route, params, url, { ...ssrOpts, req, actionData: result, status, pageModule });
+}

package/src/session.js

@@ -21,6 +21,7 @@
  */
 
 import { getStore } from './cache.js';
+import { markDynamicAccess } from './context.js';
 
 // -- Web Crypto helpers ------------------------------------------------------
 // Same shape as auth.js. We duplicate here rather than share a module
@@ -378,5 +379,8 @@ export function session(opts = {}) {
 export function getSession(req) {
   const s = sessionMap.get(req);
   if (!s) throw new Error('getSession() called outside of session middleware');
+  // A session read is per-user, so mark the request dynamic so the server HTML
+  // cache excludes it even when the page declared `revalidate` (#241).
+  markDynamicAccess();
   return s;
 }