@iterant/site-runtime 3.8.0 → 3.8.1

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.1._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -720,6 +720,35 @@ one reported, and calls `POST /__iterant/refresh` if the layer is behind. Every
 timestamp in these payloads, and in the signal lines, is an ISO 8601 string in
 UTC, never an epoch number.
 
+### Restarts and the error shell (3.8.1)
+
+An in-place restart answers whatever request was already running with a 500: the
+Cloudflare plugin's miniflare goes down under it. Until 3.8.0 `preview-error-shell`
+answered a 5xx by fetching `/under-construction` back through the same port while
+it held that failing response open, and in Docker that wedged the dev server for
+good. The self-fetch itself came back 200 in 271ms, and from then on every
+request that reached workerd rendered (the worker logged its own 200) and
+never reached the client, for the whole 120 second probe window, while Node's
+own middleware kept answering in 8ms. The same edit with the self-fetch gone
+recovered in 6 seconds.
+
+So the shell no longer fetches anything from inside a request. It caches the
+branded body and serves a 5xx from memory. The one fetch that fills the cache
+runs after a page this server has already ANSWERED, which is the only moment it
+is known to be able to render its own route; it is bounded by an abort timeout,
+holds no response open, gives up after three tries, and never runs while a
+restart is in flight (`dev-server-signals` opens that window at
+`restart`/`config` and closes it at `ready`). The cached body outlives the
+server that fetched it, so a restart keeps showing the branded shell, and the
+new server's own first page refetches it, which is what picks up an edited
+navbar. Before any page of a session has rendered there is nothing to cache and
+a break that early gets the static in-progress body.
+
+The preset also pre-bundles `astro/logger/json`, which the supervisor's
+`astro dev --json` imports on every boot. Discovered mid-session instead, it
+reloaded the program and split React in two inside workerd, and every island
+render then failed on `useRef`.
+
 ## Verify: the gate
 
 `bun run verify` maps to `site-runtime verify` and is the gate. It is silent on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.8.0",
+  "version": "3.8.1",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/src/config/preset.ts

@@ -283,6 +283,10 @@ export function iterantStarter({
         "tailwind-merge",
         "class-variance-authority",
         "@radix-ui/react-slot",
+        // The supervisor runs `astro dev --json`, so astro imports this one on
+        // every boot: left out, it is discovered mid-session and the reload
+        // that follows splits React in two inside workerd (the same crash).
+        "astro/logger/json",
       ],
     },
     server: {

package/src/integrations/dev-restart-state.mjs

@@ -0,0 +1,46 @@
+// @ts-check
+
+// Dev-only: is an in-place Astro restart in flight? (3.8.1)
+//
+// Astro replaces its Vite server in place when a watched file changes
+// (`src/site-config.ts`, `package.json`), and for that stretch the port still
+// accepts connections while the server behind it is being torn down and built
+// again. A request that was already running is answered 500 `fetch failed`:
+// the Cloudflare vite plugin's miniflare went down under it.
+//
+// preview-error-shell reads this flag before it fetches /under-construction
+// back through that same port for its cache. A fetch aimed into the gap buys
+// nothing (it can only fail or hang) and it reaches back into the plugin at
+// the moment it is least able to answer, which is how the 3.8.0 shell wedged
+// the dev server for a whole 120s probe window in Docker.
+//
+// The window opens in `dev-server-signals` at `astro:config:setup` on the
+// restarted server, the same moment it emits
+// `{"event":"restart","phase":"config"}`, and closes when that server's socket
+// starts listening, the moment of `{"event":"ready","restart":true}`.
+//
+// State, not a timer: nothing here schedules work or holds a handle, and the
+// two integrations share one module instance because the preset imports both
+// from this package. A restart that never lands would otherwise leave the flag
+// up for the rest of the session and strand the cache empty, so the flag is
+// read with a bound on how long a restart can plausibly be in flight rather
+// than trusted forever. A dev boot on a cold cache is around 11s.
+
+const RESTART_WINDOW_MS = 30_000;
+
+let startedAt = 0;
+
+/** The restarted server is being built. Called once per in-place restart. */
+export function beginRestart() {
+  startedAt = Date.now();
+}
+
+/** The restarted server is listening, so a self-fetch can be answered again. */
+export function endRestart() {
+  startedAt = 0;
+}
+
+/** @returns {boolean} */
+export function restartInFlight() {
+  return startedAt !== 0 && Date.now() - startedAt < RESTART_WINDOW_MS;
+}

package/src/integrations/dev-server-signals.mjs

@@ -4,6 +4,8 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { beginRestart, endRestart } from "./dev-restart-state.mjs";
+
 // Dev-only restart signals, content re-arm and state probe (2026-09-11).
 //
 // Astro restarts its Vite server IN PLACE when a file in `settings.watchFiles`
@@ -86,6 +88,11 @@ import { fileURLToPath } from "node:url";
 // which kind of server it got. Exactly one `ready` per server, boot or restart,
 // emitted when its httpServer starts listening.
 //
+// Those two moments are also the window preview-error-shell reads before it
+// goes and fetches /under-construction for its cache (`dev-restart-state`).
+// Nothing of ours may reach back through this port while the server behind it
+// is being replaced.
+//
 // HMR EVENTS, on this server's channel:
 //
 //   iterant:server-ready    { restart, at }   as each client connects
@@ -154,7 +161,13 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
           [pagesDir, chromeDir].map((dir) => resolve(root, dir) + sep),
         );
         startedAt = new Date().toISOString();
-        if (isRestart) signal({ event: "restart", phase: "config" });
+        if (isRestart) {
+          // The same moment, shared with preview-error-shell: from here until
+          // this server listens, a fetch back through the port would be aimed
+          // at a server still being replaced (see dev-restart-state).
+          beginRestart();
+          signal({ event: "restart", phase: "config" });
+        }
       },
 
       "astro:server:setup": ({ server, refreshContent }) => {
@@ -281,9 +294,10 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
         // waited for it would never announce itself; 'listening' is the moment
         // both paths share, and it is also the first moment the routes above
         // can actually be reached.
-        server.httpServer?.once("listening", () =>
-          signal({ event: "ready", restart }),
-        );
+        server.httpServer?.once("listening", () => {
+          endRestart();
+          signal({ event: "ready", restart });
+        });
 
         // The same news over HMR, as clients arrive. It cannot be sent from a
         // hook: an HMR payload with no client attached is dropped, and on a

package/src/integrations/preview-error-shell.mjs

@@ -1,4 +1,5 @@
 // @ts-check
+import { restartInFlight } from "./dev-restart-state.mjs";
 
 // Dev-only branded fallback for broken routes (2026-07-06): mid-build there
 // is a window where a route exists but its page component doesn't (the shell
@@ -10,6 +11,33 @@
 // /under-construction shell (navbar + footer + "in progress"). The 5xx
 // status is preserved on purpose — verify probes and the save gate must
 // still see the failure; only the human-facing body changes.
+//
+// NOTHING IS FETCHED FROM INSIDE A FAILING REQUEST (3.8.1). Until 3.8.0 the
+// 5xx path fetched /under-construction back through this same port while it
+// held the failing response open, and that wedged the dev server for good.
+// Measured in Docker, on the site-config edit that restarts the server in
+// place: an in-flight request resolves 500 `fetch failed` (the Cloudflare
+// plugin's miniflare goes down under it), the shell's self-fetch answers 200
+// in 271ms, and from then on every request that reaches workerd renders (the
+// worker logs its own 200) and never reaches the client, for the whole 120s
+// probe window. Node's own middleware still answers in 8ms, so what the
+// nested request leaves broken is the node-to-workerd path, inside
+// @cloudflare/vite-plugin. With the same self-fetch gone the same edit
+// recovered in 6s, and with the whole integration off, in 11s.
+//
+// So the branded body is CACHED instead, and a 5xx answers from memory with no
+// I/O at all. The one fetch that fills the cache runs after a request this
+// server has just ANSWERED, page and all: the only moment it is known to be
+// able to render its own route, and the furthest possible moment from a
+// restart. Nothing waits on that fetch, it carries an abort timeout, and it
+// does not run while `dev-server-signals` says a restart is in flight. One
+// server fetches once, and a restarted server fetches again off its own first
+// page, which is what picks up an edited navbar.
+//
+// The cached body outlives the server that fetched it, so a preview that has
+// shown the branded shell keeps showing it across a restart. Before the first
+// page of a session renders there is nothing to cache, and a break that early
+// gets the static shell below.
 
 // vite is astro's dependency, not this package's, so the dev-server type is
 // derived from the hook astro hands it to. One vite in the type graph, whichever
@@ -20,9 +48,41 @@
  * >[0]["server"]} ViteDevServer
  */
 
+/**
+ * Whether THIS server has the branded body yet, whether a fetch for it is
+ * already out, and how many it has spent trying.
+ *
+ * @typedef {{ warmed: boolean, warming: boolean, attempts: number }} WarmState
+ */
+
 const FALLBACK_PATH = "/under-construction";
 
-// Served when /under-construction itself can't render (e.g. Layout broken).
+/**
+ * How long a warm fetch may take before it is abandoned. Nothing waits on it,
+ * so it can be patient: a cold server rendered this route in 5.3s under
+ * Docker. It is bounded all the same, because a fetch that never settles would
+ * hold `warming` up and leave the cache unfillable for the rest of the server.
+ */
+const WARM_TIMEOUT_MS = 10_000;
+
+/**
+ * The branded body, once some server has managed to fetch it. Module scope on
+ * purpose: an in-place restart builds a new server, and a preview that has
+ * been showing the branded shell should not drop back to the static one while
+ * the new server warms up.
+ */
+let cachedShell = "";
+
+/**
+ * How many times one server tries. A repo whose /under-construction route is
+ * gone answers 404 forever, and without a cap every page view would spend a
+ * fetch on it.
+ */
+const WARM_ATTEMPTS = 3;
+
+// Served until the branded body is cached, and after that only if the branded
+// fetch keeps failing: /under-construction not rendering (a broken Layout), or
+// a break before this session has rendered any page at all.
 const MINIMAL_FALLBACK = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>Page in progress</title></head>
 <body style="display:flex;min-height:100vh;align-items:center;justify-content:center;font-family:system-ui,sans-serif">
@@ -42,6 +102,14 @@ export default function previewErrorShell() {
               {
                 name: "preview-error-shell",
                 configureServer(server) {
+                  // Per server, so a restarted one warms again. The body it
+                  // fetches is shared; whether THIS server has fetched it is
+                  // not.
+                  const state = {
+                    warmed: false,
+                    warming: false,
+                    attempts: 0,
+                  };
                   server.middlewares.use((req, res, next) => {
                     const accept = String(req.headers.accept ?? "");
                     if (
@@ -51,7 +119,7 @@ export default function previewErrorShell() {
                     ) {
                       return next();
                     }
-                    intercept(server, res);
+                    intercept(server, state, res);
                     next();
                   });
                   // Astro's own dev handler registers earlier in the connect
@@ -72,13 +140,14 @@ export default function previewErrorShell() {
 
 /**
  * Buffer the response; replay it verbatim unless it resolves to a 5xx, in
- * which case serve the branded fallback body instead. Buffering trades dev
+ * which case serve the cached fallback body instead. Buffering trades dev
  * streaming for the swap — fine for a preview.
  *
  * @param {ViteDevServer} server
+ * @param {WarmState} state
  * @param {import("node:http").ServerResponse} res
  */
-function intercept(server, res) {
+function intercept(server, state, res) {
   /** @type {Array<string | Buffer>} */
   const chunks = [];
   /** @type {unknown[] | null} */
@@ -112,34 +181,45 @@ function intercept(server, res) {
         res.end = original.end;
         if (headArgs) original.writeHead(.../** @type {[number]} */ (headArgs));
         for (const c of chunks) original.write(c);
-        return original.end();
+        const answered = original.end();
+        // This server just proved it can render a page of its own. That is the
+        // moment, and the only one, to go and get the branded body.
+        if (!state.warmed) warm(server, state);
+        return answered;
       }
-      void serveFallback(server, original, status);
-      return res;
+      original.writeHead(status, {
+        "content-type": "text/html",
+        "x-preview-fallback": "1",
+      });
+      original.write(cachedShell || MINIMAL_FALLBACK);
+      return original.end();
     }
   );
 }
 
 /**
+ * Fetch the branded body into the cache. Fire and forget: nothing waits on it,
+ * no response is open on it, and a failure leaves the previous body in place.
+ *
  * @param {ViteDevServer} server
- * @param {{ writeHead: Function, write: Function, end: Function }} original
- * @param {number} status
+ * @param {WarmState} state
  */
-async function serveFallback(server, original, status) {
-  let html = MINIMAL_FALLBACK;
-  try {
-    const port = server.config.server.port;
-    const resp = await fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
-      headers: { accept: "text/html" },
+function warm(server, state) {
+  if (state.warming || state.attempts >= WARM_ATTEMPTS) return;
+  if (restartInFlight()) return;
+  state.warming = true;
+  state.attempts += 1;
+  const port = server.config.server.port;
+  void fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
+    headers: { accept: "text/html" },
+    signal: AbortSignal.timeout(WARM_TIMEOUT_MS),
+  })
+    .then((resp) => (resp.ok ? resp.text() : ""))
+    .catch(() => "")
+    .then((html) => {
+      state.warming = false;
+      if (!html) return;
+      state.warmed = true;
+      cachedShell = html;
     });
-    if (resp.ok) html = await resp.text();
-  } catch {
-    // fall through to the minimal shell
-  }
-  original.writeHead(status, {
-    "content-type": "text/html",
-    "x-preview-fallback": "1",
-  });
-  original.write(html);
-  original.end();
 }