WebSocket downlinks have no heartbeat; live events (approval prompts) silently stop behind a tunnel/proxy

[CislinkNL]

Issue 1 draft — WebSocket downlinks have no heartbeat; live events (e.g. approval prompts) silently stop behind a tunnel/proxy

Problem

When the web UI is served behind a WebSocket-terminating proxy or tunnel (Cloudflare Tunnel, nginx, many corporate proxies), an idle events.mux / events.host WebSocket is silently reaped by the middlebox after an idle period. No close frame is delivered to either end.

The client reconnect logic only fires on a detected close/error. A silently-dead socket is never detected, so the UI keeps believing it is connected and stops receiving live frames — most visibly, approval prompts (approval/requested) never pop up; the user only sees them after a manual page refresh (which rebuilds state from the baseline replay).

Why it happens

packages/client/connection/src/websocket-downlink.ts pumps frames server→client but sends no protocol-level ping/keepalive, and the client likewise sends nothing upstream (the downlink is intentionally one-way: any client message is rejected with 1008 downlink only). With no traffic in either direction during idle periods, the proxy drops the connection without notice.

Reproduction

1. dsh web behind Cloudflare Tunnel (cloudflared), open the UI through the public hostname.
2. In a session, trigger an action that needs approval (e.g. a write outside the workspace under workspace-write + ask).
3. Let the tab sit idle, or lock/background the phone (mobile browsers suspend the page and the socket).
4. Return: the approval prompt does not appear. Refresh the page → it appears (baseline replay).
5. Meanwhile, on a directly-attached events.mux listener the server does emit approval/requested the moment the tool asks — so the server push is fine; the frame is lost in the dead socket.

Evidence captured while diagnosing

• Silent mux listener received 16k+ live frames (streaming works), but on the affected client the approval frame never arrived until refresh.
• Server log/mux dump shows approval/asked (session event) immediately followed by an approval/requested mux frame on a healthy connection.

Proposed fix

Send a protocol-level ping on a short interval from the server on each downlink. Browsers answer pongs in the background without page activity, which (a) keeps the tunnel/proxy segment alive and (b) lets genuinely dead peers surface quickly so the existing reconnect logic fires.

Reference implementation that fixed it for us (in websocket-downlink.ts, inside upgrade):

const heartbeat = setInterval(() => {
  if (websocket.readyState === WebSocket.OPEN) websocket.ping()
}, 25_000)
websocket.once('close', () => { clearInterval(heartbeat) })
websocket.once('error', () => { clearInterval(heartbeat) })

A missed-pong timeout (terminate after N missed pongs) would additionally make the server actively reap dead peers so the client reconnects on resume.

Impact

Anyone deploying the web UI behind a tunnel/reverse proxy — a documented, common deployment (--trusted-host exists precisely for it) — hits this on every approval/question/steering prompt. It reads as "the UI is frozen" and only a manual refresh recovers it.

[weijiafu14]

诊断和修法都对——服务端 ping 是这类"中间盒静默收割空闲连接"的标准解法，25 秒也选得合适（nginx 的 proxy_read_timeout 默认 60 秒，Cloudflare Tunnel 的空闲上限也在这个量级之上，25 秒有足够余量）。补两件，第一件是你复现步骤里藏着的一个区分。

一、你的第 3 步其实是两种故障，而你的修法只治得了其中一种

3. Let the tab sit idle, or lock/background the phone

这两个"或"是不同的东西：

	空闲的桌面标签页	被锁屏/切后台的手机
连接为什么死	中间盒因无流量而回收	操作系统挂起了整个应用/网络栈
服务端 ping 有用吗	有，它就是用来产生流量的	未必——对端根本没在运行，谁来回 pong
恢复时机	中间盒回收前就避免了	只能在回到前台之后补救

你的心跳完美解决了左边那一列：让通道上一直有流量，中间盒就不会认为它空闲。但右边那一列它治不了——手机被系统挂起时，服务端 ping 得再勤，那头也可能不会应。更麻烦的是，如果按你说的再加一个"漏 N 个 pong 就 terminate"的收割器，它会主动杀掉那些本来切回前台就能继续用的手机连接，把一个"回来时可能已经断了"变成"回来时保证已经断了"。

所以这两个目标（保活 vs 探活）在移动场景下是互相打架的，而这正是心跳实现最容易做错的地方。

建议把右边那一列交给客户端的 visibilitychange：页面回到前台时不要信任现有连接，主动验一次（发个轻量的探测，或者直接重建 downlink 并靠既有的 baseline replay 补齐）。这条的好处是它不依赖连接是不是真的死了——反正回前台重连一次的成本，远低于"以为连着但其实没有"。

这样两边各管各的：服务端 ping 防中间盒回收，visibilitychange 防系统挂起。 如果只做一半，我建议先做你这个服务端 ping（受影响的人更多），但在提案里把手机那一半单独列出来，别让它被"心跳修好了"给盖过去——否则手机用户会看到问题变少但没消失，而那种残留最难被再次报出来。

二、这条 bug 的伤害等级值得在原帖里说得更重

你写的是"It reads as 'the UI is frozen'"。我觉得可以更进一步：丢的是审批提示，而审批是一个安全控制。

用户看到的是"UI 卡住了"，实际发生的是一个需要人拍板的动作正在等待，而拍板的人根本不知道有这回事。两种后果都不好：

• 用户以为卡死了，去刷新/重开——误以为工具没执行；
• 或者干脆放着不管，那个待审批的动作就一直悬着。

而且这跟你写的部署形态叠加起来更糟：恰恰是"通过隧道从外面访问"的人最可能在手机上、最可能切后台，也就是最容易丢审批提示的那批人。--trusted-host 的存在说明这是官方支持的部署方式，那么"审批提示在这种部署下会静默丢失"就不是边缘情况。

建议把"approval prompts 属于安全控制面，静默丢帧意味着一个安全提示没有送达"这句话直接写进 Impact 段。同样一份技术报告，定性成"UI 体验问题"还是"安全提示投递不可靠"，得到的优先级会完全不同，而按你自己给的证据，后者才是准确的描述。

三、一个小的实现提醒

你的片段里清了 close 和 error 上的定时器，这是对的。再确认一下 upgrade 之后握手失败、以及进程/服务被 dispose 时也走得到清理路径——长连接上的 setInterval 泄漏在正常测试里不会暴露，只会在长时间运行的实例上表现为"重启之后就好了"，排查成本很高。

边界与利益相关

我们不修 DSH 自家组件——websocket-downlink.ts、events.mux、客户端重连逻辑全在 DSH 里，上面是意见不是我能替你落地的东西。我也没有在 Cloudflare Tunnel 后面复现过你这个场景，第一节关于移动端挂起的分析是按浏览器/操作系统的通行行为推的，不是实测——如果你手上有那套环境，"手机挂起时服务端 ping 到底还应不应 pong"是个十分钟就能测出来的事实，测出来比我这段推论有用得多。

利益相关：我维护 pi2dsh（Pi 生态兼容层），它在 DSH Web 里也有自己的一半。这条不推销：我们的浏览器半边走的是自己注册的 HTTP 前缀路由、不碰 events.mux 这条 WebSocket 下行，所以既不会受这个 bug 影响，也帮不上你——你要修的是 DSH 自己的下行通道。