@webjsdev/server 0.8.15 → 0.8.17

package/src/html-cache.js

@@ -26,6 +26,7 @@
 
 import { getStore } from './cache.js';
 import { STREAM_MARKER } from './conditional-get.js';
+import { createHash } from 'node:crypto';
 import { publishedBuildId } from './importmap.js';
 import { dynamicAccessed } from './context.js';
 
@@ -53,6 +54,39 @@ export const HTML_CACHE_MARKER = 'x-webjs-html-cache';
  */
 let _generation = 0;
 
+/**
+ * A fingerprint of the served app source, folded into every cache key (#318).
+ * The published build id keys on the IMPORTMAP (core + vendor) only, so a deploy
+ * that changes ONLY an app module's bytes does not move it, and a Redis-cached
+ * `revalidate` page survives that deploy still serving its baked-in OLD `?v`
+ * boot URLs (under #243 immutable caching those then content-address to stale
+ * bytes). dev.js sets this to a deterministic, location-independent digest of
+ * the browser-bound file set's content hashes (PROD only; '' in dev, where
+ * fs.watch handles staleness), so an app-source-changing deploy re-keys (a fresh
+ * render) while a no-change redeploy keeps the key (a warm cache survives). The
+ * client-router build id deliberately stays importmap-only: a partial-swap
+ * fragment already carries the new `?v` boot URLs, so app updates propagate on
+ * the next navigation without a destructive hard reload.
+ *
+ * @type {string}
+ */
+let _appSourceFp = '';
+
+/**
+ * Set the app-source fingerprint folded into the HTML cache key (see
+ * `_appSourceFp`). Called by dev.js from `ensureReady` after the browser-bound
+ * file set + asset hashes are known, and again on each rebuild. The input is a
+ * deterministic, location-independent STRING (sorted `relpath:contentHash`
+ * lines); it is digested to a short hex so the key stays compact. An empty
+ * input clears the fingerprint (the key collapses to its prior shape).
+ *
+ * @param {string} raw
+ * @returns {void}
+ */
+export function setAppSourceFingerprint(raw) {
+  _appSourceFp = raw ? createHash('sha256').update(raw).digest('hex').slice(0, 16) : '';
+}
+
 /**
  * Read the revalidation window (seconds) a page module opted into via
  * `export const revalidate = N` (the Next idiom). Returns a positive finite
@@ -86,8 +120,13 @@ export function readRevalidate(pageModule) {
  *    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.
+ *    (resolving modules against stale vendor URLs);
+ *  - the app-source fingerprint (#318), so a deploy that changes ONLY an app
+ *    module's bytes (which does not move the importmap build id) also re-keys,
+ *    instead of serving a cached body with stale `?v` boot URLs. Together the
+ *    build id (vendor) and the app-source fingerprint (app modules) mean ANY
+ *    deploy that changes the served output re-keys, while a no-change redeploy
+ *    keeps every key so a warm cache survives.
  *
  * @param {URL} url
  * @returns {string}
@@ -100,7 +139,11 @@ export function htmlCacheKey(url) {
     ? '?' + params.map(([k, v]) => `${k}=${v}`).join('&')
     : '';
   const build = publishedBuildId() || 'nobuild';
-  return `${KEY_PREFIX}${build}:${_generation}:${url.pathname}${search}`;
+  // The app-source fingerprint (#318) re-keys on an app-module-only deploy that
+  // the importmap-only build id misses. Empty (dev / no fingerprint) collapses
+  // to the prior key shape, so an unconfigured app is byte-identical.
+  const appfp = _appSourceFp ? `${_appSourceFp}:` : '';
+  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${url.pathname}${search}`;
 }
 
 /**

package/src/page-action.js

@@ -207,6 +207,13 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
     throw err;
   }
 
+  // A page action MAY return a `Response` directly (e.g. a content-negotiated
+  // `streamResponse`, #248). Honor it verbatim, so the action owns the status +
+  // content type and the router applies it (a stream body surgically). With JS
+  // off the same action returns a normal ActionResult instead, so the PRG /
+  // re-render paths below still drive the no-JS form.
+  if (result instanceof Response) return result;
+
   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

package/src/ssr.js

@@ -13,6 +13,7 @@ import {
   readHtmlCache,
   HTML_CACHE_MARKER,
 } from './html-cache.js';
+import { requestedFrameId, extractFrameSubtree } from './frame-render.js';
 
 /**
  * SSR a matched page route to a Response.
@@ -94,6 +95,31 @@ export async function ssrPage(route, params, url, opts) {
       ? new Set(haveHeader.split(',').map((s) => s.trim()).filter(Boolean))
       : null;
     const body = await renderChain(route, ctx, opts.dev, suspenseCtx, have, opts.pageModule);
+
+    // Frame subtree render (#253). A `<webjs-frame src>` self-load (or a
+    // click-driven frame nav) sends `x-webjs-frame: <id>` and applies ONLY the
+    // matching `<webjs-frame id>` subtree from the response, discarding the rest
+    // of the page. So when that header is present AND the requested frame is in
+    // the rendered output (the "isolable" case), return JUST that subtree: the
+    // bytes are extracted verbatim from the same full render, so the result is
+    // BYTE-EQUIVALENT to what the client would slice from a full-page response,
+    // but the full document shell + all the other regions never go on the wire.
+    // The frame swap path (applySwap in router-client.js) parses this body and
+    // does `doc.querySelector('webjs-frame#<id>')`, which finds the lone
+    // subtree exactly as it would in the full page. A streamed (Suspense)
+    // render is skipped (its bytes are not yet final). When the frame id is NOT
+    // found (an auth redirect to a login page, a route that dropped the frame),
+    // we fall through to the normal full-page render, where the client's
+    // existing `webjs:frame-missing` fallback handles the absence. A request
+    // with NO `x-webjs-frame` header never reaches this branch, so a normal
+    // page request is byte-identical to before this feature.
+    const frameId = requestedFrameId(opts.req);
+    if (frameId && suspenseCtx.pending.length === 0) {
+      const subtree = extractFrameSubtree(body, frameId);
+      if (subtree !== null) {
+        return htmlResponse(subtree, opts.status || 200, opts.req, url);
+      }
+    }
     // Module URLs for the page + every layout in its chain. These ride
     // the importmap; the browser fetches each file as it walks the
     // import graph. Combined with the modulepreload hints below, this
@@ -187,6 +213,11 @@ export async function ssrPage(route, params, url, opts) {
     if (typeof opts.onError === 'function') {
       try { opts.onError(err); } catch { /* a throwing sink must not affect the response */ }
     }
+    // Dev error overlay (#264): push a rich frame to the open tab so the
+    // overlay appears live. Dev-only + best-effort; never affects the response.
+    if (typeof opts.onDevError === 'function') {
+      try { opts.onDevError(err); } catch { /* a throwing sink must not affect the response */ }
+    }
     // Error paths still need to honor the request's CSP nonce so the
     // error page's boot scripts (when moduleUrls is non-empty) and
     // the meta csp-nonce tag both pass strict-CSP enforcement.

package/src/stream.js

@@ -0,0 +1,95 @@
+/**
+ * Server-side stream-action helpers (#248) that build the `<webjs-stream>` HTML
+ * the client applier (`renderStream` / the `webjs-stream` element) applies
+ * surgically.
+ *
+ * The payload is plain HTML, a `<webjs-stream action target>` wrapping one
+ * `<template>`. These helpers compose that string for the two delivery paths,
+ * a content-negotiated HTTP form response and a `broadcast()` / WS message, so
+ * an app never hand-writes the markup. A page `action` or a `route` handler
+ * branches on `acceptsStream(request)`, returning `streamResponse(...)` when the
+ * router asked for a stream and a normal render otherwise (the JS-off degrade).
+ *
+ * The helpers do NOT escape the CONTENT (it is server-authored HTML, like a
+ * template result). Escape any user-supplied substring yourself, the same way
+ * you would inside an `html` template hole.
+ */
+
+/** The content type that negotiates and carries a stream-action response. */
+export const STREAM_MIME = 'text/vnd.webjs-stream.html';
+
+/**
+ * Report whether a request opted into a stream-action response. The client
+ * router adds the stream MIME to `Accept` on a form submission. With JS off the
+ * browser sends no such Accept, so this returns false and the app returns a
+ * normal render (the progressive-enhancement degrade).
+ *
+ * @param {Request | { headers?: Headers }} req
+ * @returns {boolean}
+ */
+export function acceptsStream(req) {
+  const accept = req && req.headers && req.headers.get ? (req.headers.get('accept') || '') : '';
+  return accept.toLowerCase().includes(STREAM_MIME);
+}
+
+/** Escape the target id for safe placement in a double-quoted attribute. */
+function escapeAttr(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Build one `<webjs-stream>` action element.
+ * @param {string} action  One of append, prepend, before, after, replace, update, remove.
+ * @param {string} target  The target element id.
+ * @param {string} [content]  Inner HTML for the insert actions (ignored by remove).
+ * @returns {string}
+ */
+function build(action, target, content) {
+  const t = escapeAttr(target);
+  if (action === 'remove') {
+    return `<webjs-stream action="remove" target="${t}"></webjs-stream>`;
+  }
+  const inner = content == null ? '' : String(content);
+  return `<webjs-stream action="${action}" target="${t}"><template>${inner}</template></webjs-stream>`;
+}
+
+/**
+ * The stream-action builder. Each method returns one `<webjs-stream>` HTML
+ * string. Concatenate several and pass them to `streamResponse` or a
+ * `broadcast()`.
+ */
+export const stream = {
+  /** @param {string} target @param {string} content @returns {string} */
+  append: (target, content) => build('append', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  prepend: (target, content) => build('prepend', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  before: (target, content) => build('before', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  after: (target, content) => build('after', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  replace: (target, content) => build('replace', target, content),
+  /** @param {string} target @param {string} content @returns {string} */
+  update: (target, content) => build('update', target, content),
+  /** @param {string} target @returns {string} */
+  remove: (target) => build('remove', target),
+};
+
+/**
+ * Wrap one or more stream-action strings in a `Response` carrying the stream
+ * content type, so the client router applies it surgically. A non-200 status is
+ * fine (the router applies a stream body of any status).
+ *
+ * @param {...string} parts  `<webjs-stream>` HTML strings from `stream.*`.
+ * @returns {Response}
+ */
+export function streamResponse(...parts) {
+  return new Response(parts.join('\n'), {
+    status: 200,
+    headers: { 'content-type': STREAM_MIME + '; charset=utf-8' },
+  });
+}