feat(video): pause/resume video stream via JSON-RPC for client bandwidth savings

[mcuelenaere]

Summary

Adds two JSON-RPC notifications — pauseVideo and resumeVideo — that let a client release and re-acquire the video encoder on demand without renegotiating the WebRTC session. Outbound RTP drops from the 1–3 Mbps stream to keepalive levels (~50 B/s) while the encoder is stopped; HID input and every data channel stay live. The web frontend wires the toggle to the Page Visibility API; the native macOS client we're building consumes the same protocol.

Why

The native macOS client wants to stop wasting WAN bandwidth when the user occludes its window. SDP renegotiation (direction: .inactive on the recv transceiver) was the obvious alternative, but JetKVM's signaling treats "offer" as "new session, kick the old one" — same payoff, much more code on both ends. The browser frontend gets the same bandwidth saving for free by reusing this RPC pair from the visibility listener.

Design

Refcounted capture pipeline

The video encoder is owned by a named-consumer refcount in video.go:

acquireVideoStream(consumer string)
releaseVideoStream(consumer string)
videoStreamHasConsumers() bool

The first acquirer starts the native encoder and pauses the HDMI sleep ticker; the last releaser stops the encoder and restarts the ticker. Both helpers are idempotent per consumer key.

Each WebRTC Session gets a stable UUID id (generated in newSession) and holds the consumer key "webrtc:<id>". The slot is acquired when ICE reaches Connected and released when it reaches Closed.

Generic session-aware, ordering-aware JSON-RPC dispatch

RPCHandler gains two orthogonal flags:

• TakesSession — the dispatcher injects the receiving *Session as the handler's first reflected argument. Lets session-bound RPCs act on the session that delivered the message rather than on the global currentSession.
• Synchronous — the handler runs inline on the per-session rpcQueue pump goroutine instead of in a fresh per-message goroutine. Preserves dequeue order for ordering-sensitive RPCs.

onRPCMessage is now split into a dispatcher (parse + lookup + sync/async decision) and an invokeRPCHandler helper. The goroutine-per-message spawn previously living in the WebRTC pump (the old webrtc.go:381 go onRPCMessage(...), which the TODO comment already flagged as a wart) is now the dispatcher's responsibility — async by default for slow handlers (mountWithHTTP, tryUpdateComponents, …), inline for the new Synchronous ones. Every existing handler keeps zero-value defaults, so dispatch behaviour is unchanged for them.

pauseVideo and resumeVideo register as regular rpcHandlers entries with TakesSession: true, Synchronous: true. They take *Session and call releaseVideoStream(s.videoConsumerKey()) / acquireVideoStream(s.videoConsumerKey()) respectively.

Why this fixes the three race classes Cursor Bugbot flagged

1. Handover-while-paused. The new session's own acquireVideoStream is the 0→1 refcount transition that calls VideoStart and emits the IDR — no special-case "restart if outgoing was paused" code at the handover site.
2. Stale-session pause. TakesSession injection means the handler acts on the session that delivered the message; a pauseVideo from the soon-to-close session releases only its own consumer key. The incoming session's key keeps the encoder running. No session != currentSession gate needed.
3. Goroutine reordering of pause/resume pairs. Synchronous: true runs both handlers inline on the rpcQueue pump goroutine — the single sequential consumer of the per-session queue. The Go scheduler can no longer interleave a tight pause→resume pair to leave the encoder stopped while the tab is visible.

Commit history

#	SHA	Title
1	a31c82a	feat(video): refcount the capture pipeline; expose pauseVideo / resumeVideo
2	c0ab7ac	feat(ui): pause video stream when tab is hidden via Page Visibility API
3	e7bc932	refactor(jsonrpc): support session injection and synchronous handlers in dispatcher
4	eeabe73	fix(video): make pause/resume race-free by routing through the new dispatcher

Commit 3 is a pure infrastructure change — no caller uses the new flags yet, so dispatch behaviour is preserved. Commit 4 is a tiny semantic change that adopts the new mechanism for pause/resume.

Notes

• The refcount helpers in commit 1 are byte-identical to those in PR #1447 commit dec25e1 — that PR will merge cleanly on top of this one. Whichever lands first, the other rebases trivially.
• Documented limitation: during the 1s handover overlap, a paused session's track may briefly receive frames if the other session is keeping the encoder alive. Bounded by the existing time.Sleep(1 * time.Second) before peerConn.Close() in web.go / cloud.go. Acceptable for a feature aimed at sustained idle bandwidth saving (minutes/hours).

Constraints honoured

• Connect flow unchanged; new sessions start with their slot acquired.
• Pion video track and data channels stay alive throughout pause; only the encoder is stopped.
• No otherSessionConnected or other side effects from pauseVideo / resumeVideo themselves.
• Idempotent under rapid re-fire (60 Hz pause/resume bursts from window-state animations are safe).

Checklist

• Ran make test_e2e locally and passed
• Linked to issue(s) above by issue number (e.g. Closes #<issue-number>)
• One problem per PR (no unrelated changes)
• Lints pass; CI green (go vet ./... clean inside buildkit container; oxlint+oxfmt ran via pre-commit hook on the frontend)
• Tricky parts are commented in code (refcount semantics on acquire/release, RPCHandler.TakesSession and Synchronous doc-comments)

Test plan

End-to-end (requires hardware):

1. Connect with the JetKVM web frontend or any WebRTC client. Confirm video flows.
2. Send {"jsonrpc": "2.0", "method": "pauseVideo"} on the rpc data channel.
3. RTP traffic to the client drops to keepalive levels (~few hundred B/s). Verify with tcpdump / iftop / pion outbound-rtp stats.
4. Send {"jsonrpc": "2.0", "method": "resumeVideo"}.
5. Video resumes within ~100 ms with no decode artifacts (no green block patches, no smear).
6. Repeat pause/resume 10 cycles in 5 seconds. No hangs, no leaked goroutines, no stuck states.

For the browser path: switch tabs / minimize the window with the JetKVM tab open and verify the bandwidth drop, then return and verify clean resume.

Race regression scenarios:

7. Handover-while-paused. Open tab A, hide it (A pauses → A's slot released → encoder off). Open tab B (visible). B's acquire is a 0→1 refcount transition → VideoStart → IDR. B should see video within ~100 ms.
8. Stale-tab pause during handover. Tab A active and visible. Open tab B. While A is still in its 1s grace, hide A (focus B). A's pauseVideo releases only A's slot (via TakesSession injection); B's slot keeps the encoder running.
9. Disconnect-while-paused. Pause then close the tab. Reconnect a fresh session — video flows immediately on connect (new session's acquire is the 0→1 transition).
10. Pause/resume goroutine reordering. Programmatically send ~100 back-to-back alternating pauseVideo/resumeVideo messages and assert the final encoder state matches the last message. Before commit eeabe73 this fails non-deterministically; after the fix the dispatcher runs both inline on the pump and the test passes every time. Spot-check that slow handlers (mountWithHTTP) still get goroutine-per-message dispatch so they can't head-of-line block the queue.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches WebRTC session lifecycle, JSON-RPC dispatch concurrency, and native video start/stop behavior; mistakes could cause stuck video, leaked consumers, or ordering races, but changes are localized and add idempotent guards.

Overview
Adds pauseVideo/resumeVideo JSON-RPC notifications that let clients stop/restart the native video encoder without tearing down the WebRTC session, and wires the web UI to automatically toggle this via the Page Visibility API.

Refactors JSON-RPC dispatch to support session-injected handlers (TakesSession) and ordered, inline execution for select RPCs (Synchronous), while keeping other handlers async to avoid queue head-of-line blocking.

Introduces a named-consumer refcount for the capture pipeline (acquireVideoStream/releaseVideoStream) and updates WebRTC session connect/close to acquire/release a per-session consumer key, including waiting for the RPC queue to drain before teardown to avoid pause/resume races.

^{Reviewed by Cursor Bugbot for commit 9638825. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit eeabe73. Configure here.}