@webjsdev/server 0.8.27 → 0.8.29

package/src/file-storage.js

@@ -19,8 +19,10 @@
  * Design notes:
  *
  *   - **Streaming write.** `put` never buffers the whole file. It pipes
- *     `file.stream()` -> `Readable.fromWeb` -> `createWriteStream` via
- *     `node:stream/promises.pipeline`, so a large upload uses constant memory.
+ *     `file.stream()` -> a reader-loop async generator (`webStreamChunks`) ->
+ *     `createWriteStream` via `node:stream/promises.pipeline`, so a large upload
+ *     uses constant memory (the reader loop instead of `Readable.fromWeb` so a
+ *     mid-stream source error propagates through `pipeline` on Bun too, #509).
  *     The upstream body-size cap (#237, `maxMultipartBytes`) bounds the size
  *     BEFORE the bytes ever reach the store, so the store does not re-implement
  *     a limit; it only stays streaming.
@@ -44,6 +46,7 @@ import { dirname, join, resolve, sep, extname } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { randomUUID, createHmac, timingSafeEqual } from 'node:crypto';
+import { webStreamChunks } from './listener-core.js';
 
 /**
  * @typedef {Object} StoredObjectHandle
@@ -181,15 +184,19 @@ export function assertSafeKey(dir, key) {
  * @returns {{ stream: import('node:stream').Readable, contentType: string | null }}
  */
 function toNodeStream(file) {
-  // A Blob / File exposes a web ReadableStream via `.stream()`; converting it
-  // with Readable.fromWeb keeps it streaming (no `.arrayBuffer()`).
+  // A Blob / File exposes a web ReadableStream via `.stream()`; consuming it
+  // through a reader-loop async generator (NOT `Readable.fromWeb`) keeps it
+  // streaming AND propagates a mid-stream source error reliably on both Node and
+  // Bun. `Readable.fromWeb` does NOT forward a web-stream error through
+  // `stream/promises.pipeline` on Bun (the `pipeline` promise never settles, so
+  // `put` would hang instead of rejecting + cleaning up the partial file, #509).
   if (file && typeof file.stream === 'function' && typeof file.size === 'number') {
     const contentType = typeof file.type === 'string' && file.type ? file.type : null;
-    return { stream: Readable.fromWeb(file.stream()), contentType };
+    return { stream: Readable.from(webStreamChunks(file.stream())), contentType };
   }
   // A web ReadableStream directly.
   if (file && typeof file.getReader === 'function') {
-    return { stream: Readable.fromWeb(/** @type {ReadableStream} */ (file)), contentType: null };
+    return { stream: Readable.from(webStreamChunks(/** @type {ReadableStream} */ (file))), contentType: null };
   }
   // A Uint8Array / Buffer: wrap as a single-chunk readable. This DOES hold the
   // bytes the caller already has in memory, but it does not COPY-buffer them

package/src/listener-bun.js

@@ -0,0 +1,359 @@
+/**
+ * Bun.serve listener adapter (#511): the `Bun.serve` shell for `startServer`,
+ * selected when the host runtime is Bun. Bun's server is `Request`/`Response`
+ * native, so this path skips the node:http `toWebRequest` / `sendWebResponse`
+ * bridge entirely and hands the app's `handle(req): Response` straight to
+ * `Bun.serve({ fetch })`. A benchmark on the full listening path (node:http
+ * compat on Bun vs `Bun.serve`) measured ~1.9x more req/s, which is what justifies
+ * a second shell rather than running the node compat path on Bun.
+ *
+ * Feature parity with the node shell, routed through the shared
+ * `listener-core.js` so the two cannot drift:
+ *   - **SSE live-reload** (#264): a streaming `text/event-stream` `Response` whose
+ *     `ReadableStream` controller is registered in the shared `SseHub`; the
+ *     request `AbortSignal` (and the stream `cancel`) deregister it on disconnect.
+ *   - **WebSocket upgrade**: a `route.ts` `WS` export. Bun's native WS dispatches
+ *     through server-level `websocket` handlers (not the node `ws`-library
+ *     EventEmitter contract the `WS(ws, …)` export expects), so a small
+ *     `BunWsAdapter` re-exposes `.on('message')` / `.on('close')` / `.send()` /
+ *     `.readyState` over Bun's `ServerWebSocket`, keeping the handler contract and
+ *     the `broadcast()` registry identical across runtimes.
+ *   - **Compression**: brotli / gzip / deflate via `node:zlib` (which runs
+ *     natively on Bun), the SAME negotiation + compressor factory the node shell
+ *     uses (shared in `listener-core.js`), so the Bun path gets brotli too (#517).
+ *   - **Timeouts** (#237): the node `requestTimeout` maps to Bun's single
+ *     `idleTimeout` (seconds), clamped above the 25s SSE keepalive so a dev
+ *     live-reload stream is never reaped.
+ *   - **Proxy IP**: `server.requestIP(req).address` stamps the framework-trusted
+ *     `x-webjs-remote-ip` (the node socket-address equivalent), after stripping
+ *     any spoofed inbound value.
+ *
+ * Not supported on Bun (documented, node-only): **103 Early Hints**. `Bun.serve`
+ * exposes no API to write an informational response before the body.
+ *
+ * This module is imported DYNAMICALLY by `dev.js` only when `serverRuntime()` is
+ * `'bun'`, so the `Bun.*` global is never referenced on Node. It still LINKS on
+ * Node (the global is only read inside functions), but it is never loaded there.
+ */
+import { EventEmitter } from 'node:events';
+import { Readable, pipeline } from 'node:stream';
+import { matchApi } from './router.js';
+import { registerClient } from './broadcast.js';
+import {
+  isCompressible,
+  isEventsPath,
+  loadWsModule,
+  installProcessHandlers,
+  makeShutdown,
+  negotiateEncoding,
+  createCompressor,
+  varyWithAcceptEncoding,
+  webStreamChunks,
+} from './listener-core.js';
+
+/* global Bun */
+
+/**
+ * Start the Bun.serve listener.
+ * @param {import('./listener-types.js').ListenerContext} ctx
+ * @returns {{ server: any, close: () => Promise<void> }}
+ */
+export function startBunListener(ctx) {
+  const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
+
+  const server = Bun.serve({
+    port,
+    idleTimeout: bunIdleTimeout(timeouts),
+    // webjs owns its dev error overlay (over SSE) and handles thrown errors in
+    // `fetch`, so Bun's own development error page must never interfere; keep it
+    // deterministic (off) rather than tied to NODE_ENV.
+    development: false,
+    /**
+     * @param {Request} req
+     * @param {any} srv  the Bun server (requestIP / upgrade)
+     */
+    async fetch(req, srv) {
+      try {
+        const url = new URL(req.url);
+
+        // SSE live-reload stream (dev only); does not fit the req->Response model
+        // on node, but on Bun it is a perfectly ordinary streaming Response.
+        if (isEventsPath(url.pathname, basePathStr)) {
+          if (!dev) return new Response(null, { status: 404 });
+          return bunSseResponse(req, hub, app);
+        }
+
+        // WebSocket upgrade: a route.ts exporting WS.
+        if ((req.headers.get('upgrade') || '').toLowerCase() === 'websocket') {
+          return await bunUpgrade(req, srv, ctx);
+        }
+
+        // 103 Early Hints are intentionally skipped: Bun.serve has no API to
+        // write an informational response before the body. The modulepreload
+        // hints still ship in the rendered <head>, so the only loss is the
+        // head-start during SSR compute, not the preloads themselves.
+
+        const webReq = stampRemoteIp(req, srv);
+        const resp = await app.handle(webReq);
+        return compress ? maybeCompress(resp, req) : resp;
+      } catch (e) {
+        logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
+        return new Response(
+          dev && e instanceof Error ? `webjs error: ${e.stack}` : 'Internal server error',
+          { status: 500, headers: { 'content-type': 'text/plain' } },
+        );
+      }
+    },
+    websocket: {
+      /** @param {any} ws */
+      open(ws) {
+        const d = ws.data;
+        try {
+          d.wrapper._bind(ws);
+          registerClient(d.pathname, d.wrapper);
+          d.mod.WS(d.wrapper, d.req, { params: d.params });
+        } catch (e) {
+          logger.error('WebSocket handler threw', {
+            err: e instanceof Error ? e.stack || e.message : String(e),
+          });
+          try { ws.close(1011, 'Internal error'); } catch {}
+        }
+      },
+      /** @param {any} ws @param {string | Buffer} message */
+      message(ws, message) {
+        try { ws.data.wrapper.emit('message', message); } catch {}
+      },
+      /** @param {any} ws @param {number} code @param {string} reason */
+      close(ws, code, reason) {
+        const w = ws.data.wrapper;
+        w.readyState = 3;
+        try { w.emit('close', code, reason); } catch {}
+      },
+    },
+  });
+
+  logger.info(
+    `webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${server.port} (Bun ${process.versions.bun})`,
+  );
+  // Warm the first-request analysis in the background; listening does not wait
+  // on it, matching the node shell.
+  app.warmup();
+
+  const closeServer = () => Promise.resolve(server.stop(true));
+  const shutdown = makeShutdown({ closeServer, hub, logger });
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+
+  return {
+    server,
+    close: () => {
+      if (watcherAbort) watcherAbort.abort();
+      hub.closeAll();
+      return Promise.resolve(server.stop(true)).then(() => undefined);
+    },
+  };
+}
+
+/**
+ * The node `ws`-library WebSocket contract (`.on('message')` / `.on('close')` /
+ * `.send()` / `.readyState` / `.close()`) re-exposed over a Bun `ServerWebSocket`,
+ * which otherwise dispatches messages through server-level handlers rather than
+ * per-socket events. Constructed at upgrade time and bound to the real socket in
+ * the `open` handler; messages/close are forwarded to its emitter from the
+ * `websocket.message` / `websocket.close` handlers.
+ *
+ * Only `'message'` and `'close'` are forwarded (the events webjs WS handlers and
+ * `broadcast()` use). Bun exposes no per-socket `'error'` / `'ping'` / `'pong'`
+ * handler to bridge; a socket failure on Bun surfaces as a `'close'`, so
+ * `'close'`-keyed cleanup still runs. Documented in the WebSockets doc.
+ */
+class BunWsAdapter extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {any} */
+    this._ws = null;
+    // WebSocket.readyState constants: 0 CONNECTING, 1 OPEN, 2 CLOSING, 3 CLOSED.
+    this.readyState = 0;
+  }
+
+  /** @param {any} ws  the Bun ServerWebSocket, available once `open` fires */
+  _bind(ws) {
+    this._ws = ws;
+    this.readyState = 1;
+  }
+
+  /** @param {string | ArrayBufferView | ArrayBuffer} data */
+  send(data) {
+    try { if (this._ws) this._ws.send(data); } catch {}
+  }
+
+  /** @param {number} [code] @param {string} [reason] */
+  close(code, reason) {
+    try { if (this._ws) this._ws.close(code, reason); } catch {}
+  }
+
+  get bufferedAmount() {
+    try { return this._ws ? this._ws.getBufferedAmount() : 0; } catch { return 0; }
+  }
+}
+
+/**
+ * Resolve a `route.ts` `WS` export and upgrade the connection. Mirrors the node
+ * `attachWebSocket` path (match the route, load the module, require a `WS`
+ * function) but drives Bun's `server.upgrade`. Returns `undefined` on a
+ * successful upgrade (Bun's contract: the fetch handler must not return a
+ * Response once the socket is taken over).
+ * @param {Request} req
+ * @param {any} srv
+ * @param {import('./listener-types.js').ListenerContext} ctx
+ */
+async function bunUpgrade(req, srv, ctx) {
+  const url = new URL(req.url);
+  // Matches the node WS path, which keys on the full pathname (no base-path
+  // stripping) and on `registerClient(url.pathname, …)`.
+  const match = matchApi(ctx.app.getRouteTable(), url.pathname);
+  if (!match) return new Response('Not Found', { status: 404 });
+
+  let mod;
+  try {
+    mod = await loadWsModule(match.route.file, ctx.dev);
+  } catch (e) {
+    ctx.logger.error('WebSocket module load failed', { err: String(e) });
+    return new Response('Upgrade failed', { status: 500 });
+  }
+  if (typeof mod.WS !== 'function') {
+    return new Response('Upgrade not supported at this route', { status: 426 });
+  }
+
+  const wrapper = new BunWsAdapter();
+  const handlerReq = upgradeRequest(req, url);
+  const ok = srv.upgrade(req, {
+    data: { wrapper, mod, req: handlerReq, params: match.params, pathname: url.pathname },
+  });
+  if (ok) return undefined;
+  return new Response('Upgrade failed', { status: 500 });
+}
+
+/**
+ * Best-effort `Request` for the WS handler: headers + GET + URL, no body (it is a
+ * handshake). Mirrors the node `buildRequestFromUpgrade` so the handler reads the
+ * same cookies/auth either side.
+ * @param {Request} req
+ * @param {URL} url
+ */
+function upgradeRequest(req, url) {
+  const headers = new Headers();
+  req.headers.forEach((v, k) => { if (!k.startsWith(':')) headers.set(k, v); });
+  return new Request(url, { method: 'GET', headers });
+}
+
+/**
+ * Build the dev live-reload SSE `Response`: a streaming `text/event-stream` whose
+ * controller is registered in the shared `SseHub`. The request `AbortSignal` and
+ * the stream `cancel` both deregister the client on disconnect.
+ * @param {Request} req
+ * @param {import('./listener-core.js').SseHub} hub
+ * @param {any} app
+ */
+function bunSseResponse(req, hub, app) {
+  const enc = new TextEncoder();
+  /** @type {{ send: (s: string) => void, close: () => void } | null} */
+  let client = null;
+  const stream = new ReadableStream({
+    start(controller) {
+      client = {
+        send: (s) => { try { controller.enqueue(enc.encode(s)); } catch {} },
+        close: () => { try { controller.close(); } catch {} },
+      };
+      controller.enqueue(enc.encode('event: hello\ndata: webjs\n\n'));
+      hub.add(client);
+      // Replay an unresolved dev error (#264) so a tab connecting AFTER the
+      // breaking edit still shows the overlay.
+      const pending = app.getLastDevError && app.getLastDevError();
+      if (pending) {
+        try { controller.enqueue(enc.encode(`event: webjs-error\ndata: ${JSON.stringify(pending)}\n\n`)); } catch {}
+      }
+    },
+    cancel() { if (client) hub.remove(client); },
+  });
+  if (req.signal) {
+    req.signal.addEventListener('abort', () => { if (client) hub.remove(client); });
+  }
+  return new Response(stream, {
+    status: 200,
+    headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' },
+  });
+}
+
+/**
+ * Stamp the framework-trusted remote IP from Bun's `server.requestIP`, after
+ * stripping any spoofed inbound `x-webjs-remote-ip` (the node `toWebRequest`
+ * equivalent, which reads `req.socket.remoteAddress`). Re-wraps the request with
+ * the adjusted headers, preserving method + body.
+ * @param {Request} req
+ * @param {any} srv
+ */
+function stampRemoteIp(req, srv) {
+  const headers = new Headers(req.headers);
+  headers.delete('x-webjs-remote-ip');
+  let ip;
+  try { ip = srv.requestIP(req)?.address; } catch {}
+  if (ip) headers.set('x-webjs-remote-ip', ip);
+  return new Request(req, { headers });
+}
+
+/**
+ * Compress a `Response` via `node:zlib` (brotli / gzip / deflate), the SAME
+ * negotiation + compressor factory the node shell uses (shared in
+ * `listener-core.js`). `node:zlib` runs natively on Bun, so this gives **brotli
+ * on Bun** (the web `CompressionStream` used before had no brotli) and full
+ * compression parity with the node shell. The body is bridged web -> node ->
+ * web (`Readable.from(webStreamChunks(...))` -> `compressor` -> `Readable.toWeb`,
+ * driven by `pipeline`; NOT `Readable.fromWeb`, which does not propagate a
+ * mid-stream source error through `pipeline` on Bun, the #509 hang). Skips an
+ * already-encoded body and a non-compressible media type (`isCompressible`
+ * already excludes `text/event-stream`).
+ * @param {Response} resp
+ * @param {Request} req
+ */
+function maybeCompress(resp, req) {
+  if (!resp.body) return resp;
+  if (resp.headers.has('content-encoding')) return resp;
+  if (!isCompressible(resp.headers.get('content-type'))) return resp;
+  const encoding = negotiateEncoding(req.headers.get('accept-encoding'));
+  const compressor = createCompressor(encoding);
+  if (!compressor) return resp;
+
+  const headers = new Headers(resp.headers);
+  headers.set('content-encoding', encoding);
+  headers.delete('content-length');
+  headers.set('vary', varyWithAcceptEncoding(headers.get('vary')));
+  // Feed the web body into the compressor through the reader-loop generator (NOT
+  // Readable.fromWeb, which does not propagate a mid-stream source error through
+  // `pipeline` on Bun, the #509 hang) and drive it with `pipeline` so a source
+  // error (or a client disconnect destroying the output) tears down the whole
+  // chain instead of leaking/hanging the compressor. Backpressure is preserved:
+  // a slow client stalls `toWeb`, which stalls the compressor, which pauses the
+  // source.
+  const source = Readable.from(webStreamChunks(resp.body));
+  pipeline(source, compressor, () => {});
+  const body = Readable.toWeb(compressor);
+  return new Response(body, { status: resp.status, statusText: resp.statusText, headers });
+}
+
+/**
+ * Map the node `requestTimeout` (ms) to Bun's single `idleTimeout` (seconds). Bun
+ * caps it at 255s; we clamp it above the 25s SSE keepalive so a dev live-reload
+ * stream is never reaped as idle. `0` (the node "disable" sentinel) disables it
+ * on Bun too.
+ * @param {{ requestTimeout?: number } | undefined} timeouts
+ */
+function bunIdleTimeout(timeouts) {
+  const reqMs = timeouts && timeouts.requestTimeout;
+  if (reqMs === 0) return 0;
+  let secs = Math.ceil((reqMs || 30_000) / 1000);
+  if (secs < 30) secs = 30;
+  if (secs > 255) secs = 255;
+  return secs;
+}

package/src/listener-core.js

@@ -0,0 +1,245 @@
+/**
+ * Runtime-neutral listener core (#511): the pieces both the node:http shell and
+ * the `Bun.serve` shell share, so the two adapters cannot drift.
+ *
+ * `createRequestHandler` already returns a runtime-agnostic `handle(req): Response`.
+ * The remaining shell work (accept a socket, dispatch SSE live-reload, upgrade a
+ * WebSocket, apply timeouts + compression, run graceful shutdown) is split here
+ * into the genuinely-shared decision logic (this module) and the irreducibly
+ * transport-specific glue (the node `res.write` path in `dev.js`, the `Bun.serve`
+ * streaming-`Response` path in `listener-bun.js`). The SSE registry + fanout, the
+ * live-reload path predicate, the WS module loader, the runtime detector, and the
+ * lifecycle wiring all live here so a feature added to one shell is added to both.
+ *
+ * The seam also sets up future `Deno.serve` / embedded-host adapters: a new shell
+ * supplies its own client wrapper to `SseHub`, its own socket-to-`Request` bridge,
+ * and its own `closeServer` thunk, and reuses everything else verbatim.
+ */
+import { pathToFileURL } from 'node:url';
+import { createBrotliCompress, createGzip, createDeflate, constants as zlibConstants } from 'node:zlib';
+import { stripBasePath } from './base-path.js';
+
+/** The dev live-reload SSE path (matched after base-path stripping). */
+export const EVENTS_PATH = '/__webjs/events';
+
+/**
+ * Detect the host runtime so `startServer` can pick an adapter. Bun sets
+ * `process.versions.bun` (and also reports a `node` version via its compat
+ * layer, so the Bun check must come first).
+ * @returns {'bun' | 'node'}
+ */
+export function serverRuntime() {
+  return (typeof process !== 'undefined' && process.versions && process.versions.bun)
+    ? 'bun'
+    : 'node';
+}
+
+/**
+ * Is this request the dev live-reload SSE stream? Base-path-aware so the stream
+ * answers at `<basePath>/__webjs/events` under a sub-path deploy (#256); a no-op
+ * pass-through when there is no base path.
+ * @param {string} pathname
+ * @param {string} basePathStr
+ */
+export function isEventsPath(pathname, basePathStr) {
+  return stripBasePath(pathname, basePathStr) === EVENTS_PATH;
+}
+
+/**
+ * Whether a response body of this content type is worth compressing. Shared by
+ * the node `sendWebResponse` and the Bun `maybeCompress` so both shells gzip the
+ * exact same set of media types.
+ * @param {string | string[] | null | undefined} contentType
+ */
+export function isCompressible(contentType) {
+  if (!contentType) return false;
+  const ct = Array.isArray(contentType) ? contentType[0] : contentType;
+  // Never compress an event stream: a compressor buffers/chunk-delays bytes that
+  // an SSE body (a user route.ts returning text/event-stream) is meant to flush
+  // incrementally, so it would stall the stream. The framework's own
+  // /__webjs/events stream is intercepted before compression; this guards a
+  // user-authored one on both shells.
+  if (/^text\/event-stream/i.test(ct)) return false;
+  return /^(?:text\/|application\/(?:javascript|json|xml|wasm|manifest)|image\/svg\+xml)/i.test(ct);
+}
+
+/**
+ * Negotiate a response content-encoding from a request's `Accept-Encoding`,
+ * preferring brotli (best ratio), then gzip, then deflate. Returns `''` when
+ * none is acceptable. Shared by BOTH listener shells so they negotiate
+ * identically; the matching uses the same `(?:^|,\s*)<enc>(?:;|,|$)` token test
+ * the node shell has always used.
+ * @param {string | string[] | undefined | null} acceptEncoding
+ * @returns {'br' | 'gzip' | 'deflate' | ''}
+ */
+export function negotiateEncoding(acceptEncoding) {
+  const accept = Array.isArray(acceptEncoding) ? acceptEncoding.join(',') : String(acceptEncoding || '');
+  if (/(?:^|,\s*)br(?:;|,|$)/.test(accept)) return 'br';
+  if (/(?:^|,\s*)gzip(?:;|,|$)/.test(accept)) return 'gzip';
+  if (/(?:^|,\s*)deflate(?:;|,|$)/.test(accept)) return 'deflate';
+  return '';
+}
+
+/**
+ * Create a `node:zlib` compressor Transform for a negotiated encoding, or null.
+ * `node:zlib` runs NATIVELY on Bun, so both shells get brotli through it (the web
+ * `CompressionStream` the Bun shell used before had gzip/deflate only, no brotli).
+ * Brotli quality 4 / gzip + deflate level 6 match the node shell's prior tuning
+ * (fast, good ratio for on-the-fly compression).
+ * @param {'br' | 'gzip' | 'deflate' | ''} encoding
+ * @returns {import('node:stream').Transform | null}
+ */
+export function createCompressor(encoding) {
+  if (encoding === 'br') return createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } });
+  if (encoding === 'gzip') return createGzip({ level: 6 });
+  if (encoding === 'deflate') return createDeflate({ level: 6 });
+  return null;
+}
+
+/**
+ * Merge `Accept-Encoding` into an existing `Vary` header (or create it) without
+ * duplicating, so compressing a response that already varies (on `Cookie`, an
+ * `Origin`, etc.) does not clobber that. Shared so both shells behave identically.
+ * @param {string | null | undefined} existingVary
+ * @returns {string}
+ */
+export function varyWithAcceptEncoding(existingVary) {
+  const vary = existingVary || '';
+  return vary && !/accept-encoding/i.test(vary) ? `${vary}, Accept-Encoding` : (vary || 'Accept-Encoding');
+}
+
+/**
+ * Read a web `ReadableStream` chunk by chunk as an async iterable. A read error
+ * (a source body that errors mid-stream) throws OUT of the generator, which
+ * `Readable.from` surfaces as a node stream `error` that `pipeline` then
+ * propagates by destroying the whole chain. This is the cross-runtime-reliable
+ * way to feed a web body into a node stream: `Readable.fromWeb` does NOT
+ * propagate a web-stream error through `pipeline` on Bun (the #509 hang), so the
+ * Bun compression path must NOT use it. On early termination (the consumer
+ * aborted, e.g. a client disconnect destroyed the compressor) the source is
+ * cancelled so an upstream producer stops.
+ * @param {ReadableStream} web
+ */
+export async function* webStreamChunks(web) {
+  const reader = web.getReader();
+  let finished = false;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) { finished = true; return; }
+      yield value;
+    }
+  } finally {
+    if (!finished) { try { await reader.cancel(); } catch {} }
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+/**
+ * Load a `route.{js,ts}` module for its `WS` export, cache-busting in dev so a
+ * code edit is picked up per connection. Shared by the node WebSocket subsystem
+ * (`websocket.js`) and the Bun upgrade path so both resolve the handler identically.
+ * @param {string} file
+ * @param {boolean} dev
+ */
+export function loadWsModule(file, dev) {
+  const url = pathToFileURL(file).toString();
+  const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+  return import(url + bust);
+}
+
+/**
+ * Runtime-neutral SSE registry + fanout for dev live-reload and the dev error
+ * overlay (#264). Owns the connected-client Set and the keepalive timer; the
+ * fanout writes plain SSE frames through each client's `send`. Each shell adds a
+ * thin client wrapper over its own transport (node `res.write`, a Bun
+ * `ReadableStreamDefaultController`), so this fanout logic is written once.
+ */
+export class SseHub {
+  /** @param {{ keepaliveMs?: number }} [opts] */
+  constructor(opts = {}) {
+    /** @type {Set<{ send: (s: string) => void, close: () => void }>} */
+    this.clients = new Set();
+    // Keepalive: a comment frame every 25s defeats proxy idle timeouts (and, on
+    // Bun, keeps the connection under the server idleTimeout). Cheap and safe:
+    // SSE comments are ignored by the client. Unref'd so it never holds the
+    // process open.
+    this._timer = setInterval(() => this._raw(': ka\n\n'), opts.keepaliveMs ?? 25_000);
+    if (typeof this._timer.unref === 'function') this._timer.unref();
+  }
+
+  /** @param {{ send: (s: string) => void, close: () => void }} client */
+  add(client) { this.clients.add(client); }
+  /** @param {{ send: (s: string) => void, close: () => void }} client */
+  remove(client) { this.clients.delete(client); }
+
+  /** @param {string} frame */
+  _raw(frame) {
+    for (const c of this.clients) {
+      try { c.send(frame); } catch { /* a dead client is dropped by its own close handler */ }
+    }
+  }
+
+  /** Push a live-reload event to every open tab. */
+  reload() { this._raw('event: reload\ndata: now\n\n'); }
+
+  /** Push a dev-error overlay frame (#264) to every open tab. @param {object} frame */
+  devError(frame) { this._raw(`event: webjs-error\ndata: ${JSON.stringify(frame)}\n\n`); }
+
+  /** Close every client and stop the keepalive (graceful shutdown). */
+  closeAll() {
+    for (const c of this.clients) { try { c.close(); } catch {} }
+    this.clients.clear();
+    clearInterval(this._timer);
+  }
+}
+
+/**
+ * Install once-only process error handlers. Idempotent across multiple
+ * `startServer` calls in the same process. Runtime-neutral (plain `process.on`).
+ * @param {import('./logger.js').Logger} logger
+ * @param {() => void} onFatal
+ */
+export function installProcessHandlers(logger, onFatal) {
+  if (/** @type any */ (globalThis).__webjsProcHandlers) return;
+  /** @type any */ (globalThis).__webjsProcHandlers = true;
+  process.on('unhandledRejection', (reason) => {
+    logger.error('unhandledRejection', {
+      err: reason instanceof Error ? reason.stack || reason.message : String(reason),
+    });
+  });
+  process.on('uncaughtException', (err) => {
+    logger.error('uncaughtException', { err: err.stack || err.message });
+    // Begin orderly shutdown; process state may be corrupt.
+    try { onFatal(); } catch {}
+  });
+}
+
+/**
+ * Build a graceful-shutdown signal handler. Runtime-neutral: the shell supplies a
+ * `closeServer()` thunk that resolves once the server has stopped accepting
+ * connections (node `server.close`, Bun `server.stop(true)`). Closes the SSE hub,
+ * then drains, then exits; hard-exits after 10s if the drain hangs.
+ * @param {{ closeServer: () => Promise<unknown>, hub: SseHub, logger: import('./logger.js').Logger }} opts
+ * @returns {(signal: string) => void}
+ */
+export function makeShutdown({ closeServer, hub, logger }) {
+  let shuttingDown = false;
+  return (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info(`received ${signal}, shutting down`);
+    try { hub.closeAll(); } catch {}
+    const hard = setTimeout(() => {
+      logger.warn('shutdown timed out, forcing exit');
+      process.exit(1);
+    }, 10_000);
+    if (typeof hard.unref === 'function') hard.unref();
+    Promise.resolve()
+      .then(closeServer)
+      .then(
+        () => { logger.info('bye'); process.exit(0); },
+        (err) => { logger.error('server close error', { err: String(err) }); process.exit(1); },
+      );
+  };
+}

package/src/listener-types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared shape passed from `startServer` to whichever listener shell it selects
+ * (the node:http path in `dev.js`, the `Bun.serve` path in `listener-bun.js`).
+ * Types only; no runtime exports.
+ *
+ * @typedef {object} ListenerContext
+ * @property {any} app  the `createRequestHandler` result (`handle`, `routeFor`,
+ *   `getRouteTable`, `getLastDevError`, `warmup`, `appDir`).
+ * @property {boolean} dev
+ * @property {boolean} compress
+ * @property {import('./logger.js').Logger} logger
+ * @property {import('./listener-core.js').SseHub} hub
+ * @property {number} port
+ * @property {string} basePathStr  the configured base path (`''` when unset).
+ * @property {{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }} timeouts
+ * @property {AbortController | null} watcherAbort  the dev fs.watch controller, aborted on close.
+ */
+
+export {};