dsh web: HTTP keep-alive connections killed at node-default 5s cause browser requests to hang forever (panels "always loading")

[huangziyuan-general]

Summary

dsh-host-webserver creates the HTTP server (createServer(listener)) but never sets keepAliveTimeout / headersTimeout. Node's defaults apply: keepAliveTimeout = 5000ms. Any browser page that stays open >5s without requests has its pooled keep-alive sockets closed by the server; reusing one of these half-dead sockets makes the request hang forever (no response, no reset to the client until timeout). This makes web-UI plugin panels ("always loading") break after the page idles for a few seconds.

Reproduction (dsh 0.2.1-rc.2, dsh web on 127.0.0.1:3080)

import http.client, time
c = http.client.HTTPConnection('127.0.0.1', 3080, timeout=10)
c.request('GET', '/'); r = c.getresponse(); r.read(); print('1st (fresh conn):', r.status)
time.sleep(8)   # > node default keepAliveTimeout (5s)
c.request('GET', '/'); r = c.getresponse(); r.read(); print('2nd (reused conn):', r.status)
# 2nd request raises ConnectionResetError / hangs — server closed the idle socket at ~5s
# A fresh connection always succeeds immediately.

Also visible in lsof -nP -iTCP:3080: the browser holds CLOSE_WAIT sockets (server closed, client unaware).

Impact

• Any plugin panel served via client-modules: after the page idles >5s, subsequent fetch calls write into dead sockets → promise never settles → spinner forever. (curl / fresh connections always work, which makes it look like "server fine, UI broken".)
• Workaround we shipped in our plugin (client side): 10s AbortSignal.timeout + one automatic retry (new socket). It self-heals but wastes 10-20s.
• Real fix belongs on the server side.

Suggested fix

In dsh-host-webserver after createServer / before listen:

server.keepAliveTimeout = 60_000;
server.headersTimeout = 65_000; // must be > keepAliveTimeout

(Or expose both as webserver config options.)

Side note

While debugging we also noticed the web login (?token=…) guards pages but plugin-registered /api/... routes respond to unauthenticated requests that carry a custom header convention — worth a look as a separate hardening item.

Environment

• dsh 0.2.1-rc.2, macOS, dsh web (port 3080), Chrome
• Reproduced 2026-10-18; fixed locally in our plugin by tuning the server instance from plugin scope (patch works, which further confirms the root cause).

[PerryLink]

The missing configuration is real, but one link in the causal chain does not hold, and it changes what the fix should be.

What is true

packages/host/webserver/src/index.ts:462 is this.server = createServer(listener) — no timeout options. Repo-wide code search on master (687f282e86) returns 0 hits for both keepAliveTimeout and headersTimeout. So Node's defaults apply for both, and keepAliveTimeout is 5000 ms. Confirmed.

What does not hold: the client is not blind

Node advertises the idle timeout on every keep-alive response. Measured just now on Node v22.22.3 with a bare http.createServer and a raw socket client:

HTTP/1.1 200 OK
Content-Type: text/plain
Connection: keep-alive
Keep-Alive: timeout=5

So a browser pooling that socket is told, in the response, that the server will drop it after 5 s. Chrome/Firefox/Safari all use that header to age pooled idle sockets with a grace margin. Your own reproduction shows ConnectionResetError, which is a FIN/RST arriving — a reset, not silence.

That matters because the unexplained symptom in your report is "the promise never settles, spinner forever". A socket the client already knows is expiring cannot produce that on its own. The mechanism that does produce it is the close/send race: the client writes a request onto a socket at the exact moment the server's timer fires. The request bytes are accepted by a socket that is being torn down, no response is generated, and the client sees either a reset it may not retry (non-idempotent requests, plugin RPCs) or a stall until its own timeout. This is a well-known Node behaviour, and it is why servers are usually configured with an idle timeout comfortably longer than a browser's own idle threshold.

So the fix is still "set the timeouts", but with one constraint

If you raise keepAliveTimeout, keep headersTimeout above it as well. Node does not enforce that relation — I set keepAliveTimeout to 65 s with headersTimeout at 60 s on Node 22 and the server starts without complaint — but the semantics do: once a connection outlives the idle timeout, the next request's headers can arrive inside that window, and a headers timeout shorter than the keep-alive timeout pre-empts it. Both settings are 0-hit today, so both have to be set in the same change, and the value should be chosen against whatever sits in front (dsh web behind a proxy also has the proxy's idle timeout to consider).

Two side notes on the diagnosis

• compression: 'gzip' is not a webserver default — :106 is DEFAULT_COMPRESSION = 'none'. Whatever enables gzip does it from the bundle layer, so a server-side timeout fix will not interact with it.
• Your client-side 10 s workaround is compensating at the wrong layer: it keeps sockets away from the 5 s boundary instead of removing the boundary. Fine as a plugin-side stopgap, not something to carry once the host is fixed.

I would keep the report, reword the impact paragraph to name the close/send race rather than "client unaware", and add the headersTimeout > keepAliveTimeout requirement — otherwise the obvious fix can be applied incorrectly.