@webjsdev/server 0.8.9 → 0.8.11

package/src/cache-tags.js

@@ -0,0 +1,147 @@
+/**
+ * Tag-based invalidation for server `cache()` (the Next.js revalidateTag
+ * model), built as a THIN key-index over the existing pluggable store
+ * (`get` / `set` / `delete` in `cache.js`), NOT a new subsystem.
+ *
+ * The problem it solves: `cache(fn, { key, ttl })` can only be invalidated
+ * by calling `wrapped.invalidate()` from the module that owns the wrapper,
+ * and even then only the no-args base key (arg-specific keys leak until
+ * their TTL). There was no way for an unrelated mutation (createComment)
+ * to invalidate a related read (postById) without importing every wrapper.
+ *
+ * The index: when a cached result is stored, `cache-fn.js` also records the
+ * mapping `tag -> cacheKey` here. Each tag holds a JSON array of the cache
+ * keys tagged with it, under the namespaced store key `cache:tag:<tag>`.
+ * `revalidateTag(tag)` reads that array, deletes every cache key in it, then
+ * clears the index entry. A mutation in ANY module can therefore evict every
+ * read tagged `'posts'` across modules with one explicit call.
+ *
+ * It stays a thin index over `store.get/set/delete`: no new store method, a
+ * plain JSON array (a Set is trivial in the memory store; the same get/set of
+ * a JSON array works for Redis). The cohesive companion for HTML paths is
+ * `revalidatePath` in `html-cache.js`; together they are the server cache
+ * invalidation surface (this one for `cache()` DATA, that one for cached HTML).
+ *
+ * MULTI-INSTANCE CAVEAT (mirrors #241): the index is a plain read-modify-write
+ * of a JSON array, NOT atomic across processes. With a shared Redis store,
+ * `revalidateTag` deletes the keys it can see and reaches every instance for
+ * those keys, but two instances appending to the same tag concurrently can
+ * lose an append (last write wins), so a freshly-stored key on a peer might
+ * miss eviction and live until its TTL. The tag index entry itself also
+ * carries the cache TTL, so the index self-prunes and never grows unbounded.
+ * For strict cross-instance invalidation, prefer a short `ttl` as the floor.
+ *
+ * @module cache-tags
+ */
+
+import { getStore } from './cache.js';
+
+/** Namespace prefix for every tag-index key, parallel to `cache:` entries. */
+const TAG_PREFIX = 'cache:tag:';
+
+/** @param {string} tag @returns {string} */
+function tagKey(tag) {
+  return `${TAG_PREFIX}${tag}`;
+}
+
+/**
+ * Read the cache-key set stored under one tag. Returns a plain array (empty
+ * on a miss / parse error, failing open). The store holds a JSON array.
+ *
+ * @param {string} tag
+ * @returns {Promise<string[]>}
+ */
+async function readTagKeys(tag) {
+  try {
+    const raw = await getStore().get(tagKey(tag));
+    if (!raw) return [];
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a cache key to every given tag's index (deduped). Called by
+ * `cache-fn.js` right after it stores a cached result. The index entry
+ * carries the same TTL as the cached value so it self-prunes and the tag
+ * index never outgrows the data it points at.
+ *
+ * Best-effort: a store failure here never affects the cached result that was
+ * already written (the value is still served; only its taggability is lost).
+ *
+ * @param {string[]} tags
+ * @param {string} cacheKey
+ * @param {number} [ttlMs]
+ * @returns {Promise<void>}
+ */
+export async function addKeyToTags(tags, cacheKey, ttlMs) {
+  if (!Array.isArray(tags) || tags.length === 0) return;
+  const store = getStore();
+  for (const tag of tags) {
+    if (typeof tag !== 'string' || !tag) continue;
+    try {
+      const keys = await readTagKeys(tag);
+      if (keys.includes(cacheKey)) continue;
+      keys.push(cacheKey);
+      await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+    } catch {
+      /* a tag-index write failure must never affect the cached value */
+    }
+  }
+}
+
+/**
+ * Evict every cached entry tagged with `tag`, then clear the tag index.
+ * A mutating server action calls this after a write so the next read of any
+ * tagged query recomputes. Works across modules: the read tagged `'posts'`
+ * in one module is invalidated by a `revalidateTag('posts')` issued from
+ * any other.
+ *
+ * ```js
+ * // modules/comments/actions/create-comment.server.ts
+ * 'use server';
+ * import { revalidateTag } from '@webjsdev/server';
+ * export async function createComment(input) {
+ *   await prisma.comment.create({ data: input });
+ *   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
+ *   return { success: true };
+ * }
+ * ```
+ *
+ * @param {string} tag
+ * @returns {Promise<void>}
+ */
+export async function revalidateTag(tag) {
+  if (typeof tag !== 'string' || !tag) return;
+  const store = getStore();
+  const keys = await readTagKeys(tag);
+  for (const k of keys) {
+    try {
+      await store.delete(k);
+    } catch {
+      /* a delete failure is non-fatal: the entry still expires via its TTL */
+    }
+  }
+  try {
+    await store.delete(tagKey(tag));
+  } catch {
+    /* non-fatal */
+  }
+}
+
+/**
+ * Convenience: `revalidateTag` for several tags in one call. A mutation that
+ * touches multiple cached surfaces (e.g. a post AND the post list) evicts
+ * them together.
+ *
+ * @param {string[]} tags
+ * @returns {Promise<void>}
+ */
+export async function revalidateTags(tags) {
+  if (!Array.isArray(tags)) return;
+  for (const tag of tags) {
+    await revalidateTag(tag);
+  }
+}

package/src/conditional-get.js

@@ -0,0 +1,183 @@
+/**
+ * RFC 7232 conditional GET (ETag + If-None-Match -> 304).
+ *
+ * One shared funnel that, given a Request and the buffered Response the
+ * pipeline produced, attaches a content-hash `ETag` when the response is
+ * cacheable and missing one, then turns a matching `If-None-Match` into a
+ * `304 Not Modified` with no body. Wired once at the response funnel in
+ * `dev.js`'s `handle()`, so it covers SSR HTML pages, static assets, app
+ * source modules, vendor / core runtime modules, and route-handler bodies
+ * uniformly.
+ *
+ * What is EXCLUDED, and why:
+ *   - `no-store` / `private` responses (the default for dynamic, per-user
+ *     pages). Never enable a cross-session 304 on private content: a shared
+ *     cache keyed on the URL could serve one user's validator to another.
+ *   - Any body the framework did not positively mark as fully buffered. The
+ *     funnel only hashes a response that ALREADY carries an `ETag` (a serve
+ *     branch hashed its own bytes) OR carries the internal `X-Webjs-Buffered`
+ *     marker the buffered serve branches stamp on a string / bytes body. It
+ *     never calls `arrayBuffer()` on an unmarked body. This is the guard that
+ *     keeps a user `route.{js,ts}` handler returning a `ReadableStream` (and
+ *     especially an SSE `text/event-stream`, whose stream NEVER ends) from
+ *     being buffered into memory or, worse, awaited forever so the response
+ *     hangs. A web `Response` exposes a `ReadableStream` body for a string and
+ *     for a live stream alike, with no public way to tell them apart, so a
+ *     positive opt-in marker is the only safe discriminator.
+ *   - Streaming Suspense bodies, flagged with `X-Webjs-Stream: 1` by the SSR
+ *     pipeline (a stricter form of the unmarked-body rule: the marker is
+ *     stripped and the response returned untouched). Streaming responses are
+ *     not conditional-GET cached, by design.
+ *   - Non-GET / non-HEAD methods, and any status other than 200. A validator
+ *     is only meaningful for a successful, replayable read.
+ *
+ * The ETag is WEAK (`W/"..."`). It is computed over the UNCOMPRESSED body
+ * bytes, then the prod compression step (`sendWebResponse` in `dev.js`) may
+ * stamp `Content-Encoding: gzip` / `br` on the SAME response. A STRONG
+ * validator must be unique per content-coding (RFC 7232 2.3.3), so reusing one
+ * strong ETag across identity / gzip / br would be non-conformant; a WEAK
+ * validator is the conformant choice for a hash shared across codings, and
+ * `If-None-Match` already uses weak comparison so a `304` still fires.
+ *
+ * The ETag is computed over the response's OWN body bytes, so an identical
+ * body yields an identical ETag across requests. Per-response varying bits
+ * that ride RESPONSE HEADERS (the `x-webjs-build` id, a `set-cookie` CSRF
+ * token, the CSP nonce on the header) are NOT part of the body hash, so they
+ * do not destabilise the ETag. The one body-level varying input is the CSP
+ * nonce stamped INTO the inline boot script: when CSP is enabled the HTML
+ * body changes every request, so its ETag changes every request and a 304 is
+ * simply never produced for that page (correct, not a bug). CSP is off by
+ * default, so the common case has a stable body and a stable ETag.
+ *
+ * @module conditional-get
+ */
+
+import { digestHex } from './crypto-utils.js';
+
+/**
+ * Internal header a buffered serve branch stamps to opt a response into
+ * conditional GET. Stripped at the funnel; it never reaches a client. A web
+ * `Response` exposes a `ReadableStream` body whether it was built from a
+ * string, bytes, or a live stream, so this explicit marker is how the funnel
+ * KNOWS a body is safe to hash without risking buffering a route handler's
+ * stream or hanging on an SSE response.
+ */
+export const BUFFERED_MARKER = 'x-webjs-buffered';
+
+/** Internal header the SSR pipeline stamps on a genuinely-streamed body. */
+export const STREAM_MARKER = 'x-webjs-stream';
+
+/**
+ * Headers that must not ride a 304 response (it has no body). Everything
+ * else (ETag, Cache-Control, Vary, the framework's X-Webjs-Build /
+ * X-Request-Id, Set-Cookie) is preserved so a shared cache and the client
+ * router behave identically to a 200.
+ */
+const STRIP_ON_304 = ['content-length', 'content-encoding', 'content-type'];
+
+/**
+ * Is this response cacheable enough to carry a validator?  Cacheable means a
+ * 200 whose `Cache-Control` is present and does not forbid storage. A
+ * `no-store` or `private` response is excluded (private / per-user content
+ * must never get a cross-session 304). `no-cache` is INCLUDED: it means
+ * "revalidate before reuse", and a 304 is exactly that revalidation answer,
+ * so dev's `no-cache` assets still benefit.
+ *
+ * @param {Response} res
+ * @returns {boolean}
+ */
+function isCacheable(res) {
+  if (res.status !== 200) return false;
+  const cc = res.headers.get('cache-control');
+  if (!cc) return false;
+  return !/(?:^|,)\s*(?:no-store|private)\s*(?:,|$)/i.test(cc);
+}
+
+/**
+ * Parse an `If-None-Match` request header and test it against an ETag.
+ * Honors the `*` wildcard and a comma-separated list, and compares
+ * weak-insensitively (a `W/` prefix on either side is ignored for the
+ * comparison, per RFC 7232 weak-comparison semantics, which is the correct
+ * function for `If-None-Match`).
+ *
+ * @param {string | null} header  the raw `If-None-Match` value
+ * @param {string} etag  the response ETag, e.g. `"abc123"`
+ * @returns {boolean}
+ */
+export function ifNoneMatchSatisfied(header, etag) {
+  if (!header || !etag) return false;
+  const want = stripWeak(etag);
+  for (const raw of header.split(',')) {
+    const tok = raw.trim();
+    if (tok === '*') return true;
+    if (stripWeak(tok) === want) return true;
+  }
+  return false;
+}
+
+/** @param {string} tag */
+function stripWeak(tag) {
+  return tag.startsWith('W/') ? tag.slice(2) : tag;
+}
+
+/**
+ * Apply conditional-GET semantics to a finished, buffered Response.
+ *
+ * Returns either the same response (now possibly carrying an `ETag`) or, when
+ * the request's `If-None-Match` matches, a fresh `304 Not Modified` with no
+ * body and the validators / caching headers preserved. A streaming,
+ * non-cacheable, or non-GET/HEAD response is returned unchanged.
+ *
+ * @param {Request} req
+ * @param {Response} res
+ * @returns {Promise<Response>}
+ */
+export async function applyConditionalGet(req, res) {
+  const method = req.method.toUpperCase();
+  // Always consume the internal buffered marker so it never reaches a client.
+  const buffered = res.headers.has(BUFFERED_MARKER);
+  if (buffered) res.headers.delete(BUFFERED_MARKER);
+  // A genuinely streamed Suspense response is flagged by the SSR pipeline.
+  // Strip that marker too and skip conditional-GET so the live stream is
+  // never consumed.
+  if (res.headers.has(STREAM_MARKER)) {
+    res.headers.delete(STREAM_MARKER);
+    return res;
+  }
+  if (method !== 'GET' && method !== 'HEAD') return res;
+  if (!isCacheable(res)) return res;
+
+  let etag = res.headers.get('etag');
+  if (!etag) {
+    // Only hash a body the framework positively marked as fully buffered.
+    // Without the marker we must NOT read the body, because a user route
+    // handler returning a ReadableStream would be buffered into memory, and
+    // an SSE (text/event-stream) stream never ends so the await would hang
+    // forever. A web Response exposes a ReadableStream body for a string and
+    // for a live stream alike, so the marker is the only safe discriminator.
+    if (!buffered) return res;
+    let bytes;
+    try {
+      // Clone so the caller's body is never consumed. Safe here because a
+      // marked body is built from a string / bytes, so the clone resolves
+      // at once.
+      bytes = new Uint8Array(await res.clone().arrayBuffer());
+    } catch {
+      // A body that refuses to buffer (should not happen for a marked branch)
+      // is left without a validator rather than crashing the funnel.
+      return res;
+    }
+    // WEAK validator. The hash is over the uncompressed body and is reused
+    // across identity / gzip / br codings (compression runs after this), which
+    // a STRONG ETag may not do (RFC 7232 2.3.3). If-None-Match weak-compares.
+    etag = `W/"${(await digestHex('SHA-1', bytes)).slice(0, 16)}"`;
+    res.headers.set('etag', etag);
+  }
+
+  if (ifNoneMatchSatisfied(req.headers.get('if-none-match'), etag)) {
+    const headers = new Headers(res.headers);
+    for (const h of STRIP_ON_304) headers.delete(h);
+    return new Response(null, { status: 304, headers });
+  }
+  return res;
+}

package/src/context.js

@@ -10,7 +10,32 @@ import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
  *
  * Strictly server-side: importing this module on the client is a bug.
  *
- * @typedef {{ req: Request }} Store
+ * `cspNonce` holds the per-request CSP nonce when CSP is enabled
+ * (issue #233). It is minted in the request handler and written here via
+ * `setCspNonce`, so the same value the `Content-Security-Policy` header
+ * carries is what `cspNonce()` returns for the inline boot script.
+ *
+ * `bodyLimits` holds the resolved request body-size caps (issue #237) so
+ * `readBody` (used inside `route.{js,ts}` handlers, which have no handle to the
+ * server state) can enforce the same limit the RPC and page-action paths do. The
+ * handler writes it per request via `setBodyLimits`.
+ *
+ * `requestId` holds the per-request correlation id (issue #239). The handler
+ * mints a `crypto.randomUUID()` at the start of every request (or honors an
+ * inbound `X-Request-Id` from a trusted upstream proxy) and stores it here via
+ * `setRequestId`, so server-side app code can read it with `requestId()` to
+ * stamp it on its own logs / outbound calls, and the framework includes it in
+ * the access log, the error log, and the `X-Request-Id` response header.
+ *
+ * `dynamicAccess` is set the moment the render reads per-user request state
+ * through a framework helper (`cookies()`, `headers()`, `getSession()`),
+ * mirroring Next.js auto-marking a route dynamic on a `cookies()` / `headers()`
+ * read (#241). The server HTML cache reads it at commit time and REFUSES to
+ * cache a page that opted into `revalidate` but actually varies per user, so a
+ * wrong `revalidate` on a cookie-reading page fails safe (uncached) instead of
+ * leaking one visitor's view to another.
+ *
+ * @typedef {{ req: Request, cspNonce?: string, bodyLimits?: { json: number, multipart: number }, requestId?: string, dynamicAccess?: boolean }} Store
  */
 
 /** @type {AsyncLocalStorage<Store>} */
@@ -33,10 +58,102 @@ export function getRequest() {
 }
 
 /**
- * Server-only implementation of the CSP nonce reader: pulls the
- * current request from AsyncLocalStorage, parses the
- * `script-src 'nonce-...'` value from its CSP header, returns ''
- * when none in scope.
+ * Set the per-request CSP nonce on the current AsyncLocalStorage store.
+ * Called by the request handler when CSP is enabled, AFTER it mints the
+ * nonce and BEFORE the page renders, so `cspNonce()` returns this exact
+ * value during SSR (the same value the response's
+ * `Content-Security-Policy` header carries: one source, no drift).
+ *
+ * A no-op outside a request scope, or when CSP is disabled (the handler
+ * simply never calls it, so the store's `cspNonce` stays undefined and
+ * `cspNonce()` falls through to '').
+ *
+ * @param {string} nonce
+ */
+export function setCspNonce(nonce) {
+  const store = als.getStore();
+  if (store) store.cspNonce = nonce;
+}
+
+/**
+ * Set the per-request resolved body-size limits on the current store (issue
+ * #237). The handler computes them once at boot (`readBodyLimits`) and stamps
+ * them on every request so `readBody` (json.js), which runs inside route
+ * handlers with no access to the server state, can enforce the same cap.
+ *
+ * @param {{ json: number, multipart: number }} limits
+ */
+export function setBodyLimits(limits) {
+  const store = als.getStore();
+  if (store) store.bodyLimits = limits;
+}
+
+/**
+ * Read the per-request body-size limits, or null outside a request scope.
+ * @returns {{ json: number, multipart: number } | null}
+ */
+export function getBodyLimits() {
+  return als.getStore()?.bodyLimits ?? null;
+}
+
+/**
+ * Set the per-request correlation id on the current store (issue #239). The
+ * handler calls this at the start of every request with either an inbound
+ * `X-Request-Id` (a trusted upstream proxy's trace id) or a freshly minted
+ * `crypto.randomUUID()`. A no-op outside a request scope.
+ *
+ * @param {string} id
+ */
+export function setRequestId(id) {
+  const store = als.getStore();
+  if (store) store.requestId = id;
+}
+
+/**
+ * The correlation id for the in-flight request (issue #239), or `null`
+ * outside a request scope. Server-side app code (pages, layouts, server
+ * actions, route handlers, middleware) reads it to correlate its own logs and
+ * outbound calls with the framework's access / error logs and the
+ * `X-Request-Id` response header, all of which carry the same id.
+ *
+ * @returns {string | null}
+ */
+export function requestId() {
+  return als.getStore()?.requestId ?? null;
+}
+
+/**
+ * Mark the in-flight request as having read per-user state (issue #241). The
+ * framework's request-state readers (`cookies()`, `headers()`, `getSession()`)
+ * call this, so the server HTML cache can tell at commit time that the render
+ * actually depends on the visitor and refuse to cache it even when the page
+ * declared `revalidate`. A no-op outside a request scope.
+ */
+export function markDynamicAccess() {
+  const store = als.getStore();
+  if (store) store.dynamicAccess = true;
+}
+
+/**
+ * True when the in-flight render read per-user request state via a framework
+ * helper (issue #241). Read by the server HTML cache's commit step to fail
+ * safe (do not cache) on a per-user page that wrongly set `revalidate`.
+ * Returns false outside a request scope.
+ *
+ * @returns {boolean}
+ */
+export function dynamicAccessed() {
+  return als.getStore()?.dynamicAccess === true;
+}
+
+/**
+ * Server-only implementation of the CSP nonce reader. Returns the
+ * per-request nonce that the handler MINTED and stored (issue #233) when
+ * CSP is enabled. Falls back to parsing an INBOUND
+ * `Content-Security-Policy` request header (the legacy consume-only
+ * behaviour) so an app sitting behind a proxy that already mints a nonce
+ * still works without enabling webjs's own CSP. Returns '' when neither
+ * is in scope.
  *
  * The public `cspNonce()` function lives in `@webjsdev/core` so user
  * layouts / pages can import it without dragging server-only deps
@@ -46,18 +163,16 @@ export function getRequest() {
  * `cspNonce()` returns '' (empty `nonce=""` attribute, browser
  * ignores it).
  */
-// The regex captures the first `nonce-...` token anywhere in the CSP
-// header. Webjs uses a single per-request nonce shared across all
-// directives that emit it (the standard CSP3 single-nonce model),
-// so reading the first match is correct. If a future caller emits
-// styled inline content under a separate style nonce, this reader
-// would need to become directive-scoped. Kept identical to the
-// matching helper in ssr.js so both paths interpret the header the
-// same way.
+// The regex fallback captures the first `nonce-...` token anywhere in the
+// inbound CSP header. Webjs uses a single per-request nonce shared across
+// all directives that emit it (the standard CSP3 single-nonce model), so
+// reading the first match is correct. Kept identical to the matching
+// helper in ssr.js so both paths interpret the header the same way.
 setCspNonceProvider(() => {
-  const req = als.getStore()?.req;
-  if (!req) return '';
-  const csp = req.headers.get('content-security-policy') || '';
+  const store = als.getStore();
+  if (!store) return '';
+  if (typeof store.cspNonce === 'string') return store.cspNonce;
+  const csp = store.req?.headers.get('content-security-policy') || '';
   const match = /\bnonce-([A-Za-z0-9+/=]+)/.exec(csp);
   return match ? match[1] : '';
 });
@@ -75,6 +190,10 @@ export { cspNonce };
 export function headers() {
   const req = getRequest();
   if (!req) throw new Error('headers(): called outside a request scope');
+  // Reading request headers makes the render per-user (an Authorization /
+  // Accept-Language / Cookie read varies the output), so mark the request
+  // dynamic so the HTML cache excludes it even under `revalidate` (#241).
+  markDynamicAccess();
   return req.headers;
 }
 
@@ -89,6 +208,10 @@ export function headers() {
 export function cookies() {
   const req = getRequest();
   if (!req) throw new Error('cookies(): called outside a request scope');
+  // Reading cookies makes the render per-user (a logged-in vs logged-out body
+  // keys off an auth cookie), so mark the request dynamic so the HTML cache
+  // excludes it even under `revalidate`, the core leak defense (#241).
+  markDynamicAccess();
   const map = parseCookies(req);
   return {
     get: (name) => map[name],