[Bug] client-hmr's SSE channel burns one HTTP connection per frontend, capping how many DSH frontends can coexist on one origin

[godcreator02]

Summary

client-hmr opens its /plugins/events channel with EventSource (SSE). SSE is a long-lived HTTP connection, so it consumes one slot from the browser's per-origin HTTP connection pool and never releases it. Every DSH frontend takes one such slot.

Once a page runs several DSH frontends against the same origin, the pool is exhausted and any further frontend can no longer even fetch its own document — its navigation request stays pending forever and the UI sits at "Loading plugins…" indefinitely. It never errors out, because nothing failed: the request is queued behind a queue that never drains.

Switching that one channel from SSE to WebSocket removes the ceiling entirely, because WebSocket connections are governed by a separate, far more permissive browser quota.

Environment

• DSH 0.1.0-rc.7 and 0.1.1-rc.2 (both reproduce; the relevant code is byte-identical in the two versions)
• Windows 11, Node 24
• Chrome (loopback origin, plain HTTP → always HTTP/1.1, so the 6-connections-per-origin rule applies)

Reproduction

1. Open a page that embeds several DSH frontends against the same origin — e.g. an HTML shell with N <iframe src="/?…">, or simply several tabs on the same origin.
2. Beyond a small N (2–3 in our environment, depending on how many frontends the origin already carries), the newly added frontends stop loading and stay on "Loading plugins…".
3. DevTools shows their main document request stuck in pending, and no new TCP connection is created for them.

The server is entirely healthy while this happens — in our measurements it answered in 1–3 ms and fetching all 39 client modules serially took 1826 ms with zero failures.

Root cause

Each DSH frontend holds exactly 3 long-lived connections:

#	Source	Quota it consumes
1	dsh-client-connection → readWebSocket(MUX_EVENTS_PATH, …)	WebSocket quota (permissive)
2	dsh-client-connection → readWebSocket(HOST_EVENTS_PATH, …)	WebSocket quota (permissive)
3	dsh-client-hmr → new EventSource(EVENTS_ENDPOINT)	HTTP quota (6 per origin)

Only #3 is the problem. packages/client/hmr — lib/client.js:

const source = new EventSource(EVENTS_ENDPOINT);

and the server half registers it as a plain HTTP route:

ctx.webServer.register({ kind: "exact", path: EVENTS_ENDPOINT, handler: … });
// res.writeHead(200, { "content-type": "text/event-stream", … })

Because this is HTTP/1.1 over a loopback origin (no HTTP/2 available — the web server is built on node:http), those SSE streams each pin one of the six per-origin HTTP slots for as long as the frontend lives.

Evidence

Measured connection counts (each frontend consistently accounts for exactly 3 connections — opening one adds 3, closing one removes 3):

• Before the change: with 30 established connections, the 4th iframe on the origin could not start. Its document request was pending with no new connection attempted. Closing one existing frontend (freeing 3 connections) caused the stalled iframe to immediately open 3 connections and proceed — a clean causal loop.
• After switching hmr to WebSocket: 9 full DSH frontends in a single page, all rendering normally, at the same 30 established connections. Identical connection count, opposite outcome — the difference is purely which quota pool those connections draw from.

Suggested fix

Move the hmr channel to WebSocket. The infrastructure is already in the codebase: ws is a dependency of dsh-client-connection, and webServer already exposes registerUpgrade — the two existing WebSocket channels are mounted exactly this way. The change is roughly a dozen lines on each half.

Server (packages/client/hmr, node half):

import { WebSocketServer } from "ws";

const wss = new WebSocketServer({ noServer: true });
const connect = (socket) => {
  socket.send(JSON.stringify({ type: "graph", graph: ctx.clientModules.graph() }));
  connections.add(socket);
  socket.on("close", () => connections.delete(socket));
  socket.on("error", () => connections.delete(socket));
};

ctx.effect(() => {
  const disposeRoute = ctx.webServer.registerUpgrade({
    path: EVENTS_ENDPOINT,
    handler: (req, socket, head) => wss.handleUpgrade(req, socket, head, connect),
  });
  const unsubscribe = ctx.clientModules.onRebuilt((id, rev) => {
    const line = JSON.stringify({ type: "rebuilt", id, rev });
    for (const socket of connections) socket.send(line);
  });
  return () => { /* unsubscribe / disposeRoute / close sockets / wss.close() */ };
}, "client-hmr: /plugins/events channel");

Browser (packages/client/hmr, client half):

const wsUrl = new URL(EVENTS_ENDPOINT, location.href);
wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
const source = new WebSocket(wsUrl);

The message listener and close() teardown below it need no changes at all — the two APIs agree on both. The wire protocol is unchanged apart from dropping the SSE data: …\n\n envelope.

Verification

We applied exactly this change locally against 0.1.1-rc.2 and confirmed:

• 9 full DSH frontends in one page, all rendering correctly (chat ×2, trajectory ×2, tool details ×2, composer ×2, plus a sidebar) — previously 1–2.
• HMR still works end to end: editing a client bundle produced 9 reload log lines within the same second, one per frontend. Detection, push over WebSocket, and module reload all function identically.

Why this matters beyond our case

Anyone embedding more than one DSH frontend on a single origin hits this — split-pane workspaces, dashboards, comparison views, or simply a few tabs. The symptom (an indefinite "Loading plugins…" with a healthy server) gives no hint about the real cause, which makes it expensive to diagnose.

It also gets worse over time within a session: connections from closed pages were observed lingering for 15+ minutes, so a developer who has been opening and closing DSH tabs can hit the ceiling with fewer live frontends than expected.

[argszero]

Confirmed against v0.1.1-rc.2 source — your table is accurate and the 30-connection causal loop evidence is the strongest part (closing one frontend immediately unblocking the stalled iframe proves the slot-pinning mechanism beyond doubt). Your WebSocket fix is the right call; I verified the alternatives so the decision has a paper trail.

Source facts (packages/client/hmr/src/index.ts)

• Server half: connect() (:148-163) writes text/event-stream + keep-alive and keeps the ServerResponse in a connections Set until close; the route is registered as a plain HTTP route via ctx.webServer.register({ kind: 'exact', path: EVENTS_ENDPOINT, ... }) (:165-179) — so it is an ordinary node:http request, not an upgrade. onRebuilt writes to every held response (:180-183). Each connect() therefore pins one HTTP/1.1 slot for the lifetime of the frontend. Matches your claim exactly.
• Client half: new EventSource(EVENTS_ENDPOINT) at client/src/index.ts:167.

Why the alternatives to WebSocket do not hold up

• HTTP/2: the web server is built on node:http (packages/host/webserver), so HTTP/2 would mean adding an http2 server — far larger than the one-channel fix. Discard.
• fetch + ReadableStream: a streamed fetch response is also a long-lived HTTP connection and consumes the same per-origin HTTP slot as EventSource. It solves nothing for the quota problem (it would only matter if you were escaping the 6-connection cap some other way, which HTTP/1.1 does not offer). Discard.
• Short polling: changes the semantics (the channel currently pushes graph snapshot + rebuild notices) and adds latency; only worth it if you specifically want zero long-lived HTTP connections at all costs. The WebSocket path is strictly better here.

Why WebSocket is the natural fit

• The repository already has two WebSocket channels per frontend with the full plumbing: dsh-client-connection uses readWebSocket(MUX_EVENTS_PATH, ...) and readWebSocket(HOST_EVENTS_PATH, ...), and the host server has registerUpgrade + a tracked upgradedSockets set (the same lifecycle that [Bug] Late ECONNRESET after an upgraded socket closes can terminate dsh web #4059 is about). So the hmr channel is the only one of the three still on SSE — migrating it to WebSocket makes all three channels uniform.
• Server-side migration shape: move from webServer.register (HTTP route) to webServer.registerUpgrade (upgrade route), keep the same /plugins/events path and the same graph/rebuilt frame payloads, write frames as WebSocket text messages instead of SSE data: lines. Client-side: replace EventSource with the same readWebSocket helper the connection client already uses. The channel is one-way (server pushes), so no client→server message handling is needed beyond the initial upgrade.
• One caveat to verify: the connections Set currently deletes on res.close (:162) — the WebSocket equivalent must delete on the socket's close event (and the same late-error listener caveat from [Bug] Late ECONNRESET after an upgraded socket closes can terminate dsh web #4059 applies to the upgraded socket; worth reading that thread since the fix there is two lines and this new channel would inherit the same lifecycle).

Severity note: client-hmr is the dev hot-reload channel — if production frontends also load it, the ceiling is reachable by ordinary users (your iframe shell is plausible outside dev). If it is dev-only, the blast radius is limited to development stacks with multiple embedded frontends. Worth stating in the issue which case holds.

Family: same connection-lifecycle domain as #4059 (teardown overreach on upgraded sockets) — the sweep I suggested there (off('error') inside once('close') patterns) and this migration touch the same upgradedSockets bookkeeping; doing both together avoids touching the upgrade lifecycle twice.