fix(sse): send torrent page deltas instead of full snapshots

[s0up4200]

Fixes #2046. Since v1.20 the torrent-list SSE re-sent the full page on every tick: measured ~577 KB every ~2s (~290 KB/s sustained per open tab) on a 4.8k-torrent instance. That is wasted CPU and bandwidth for every user, and on a slow-drained connection (a constrained link, or a backgrounded tab that stops draining) it fills the HTTP/2 connection-level flow-control window and head-of-line-blocks other requests like auth/me. This keeps a per-group baseline and sends delta frames of only the rows whose meaningful fields changed, with per-second counters (reannounce, time_active, peer counts) excluded from change-detection so an otherwise-idle row no longer flags every tick. Measured steady delta is ~22 KB vs ~577 KB, roughly 26x less; aggregate metadata still travels whole so existing stream consumers stay correct unchanged.

init seeds the baseline so the first delta applies cleanly, with no periodic keyframe (a recurring full re-send would re-jam the connection on a bad link); correctness rests on init-seeds-baseline plus a fresh init on reconnect. The frontend rebuilds the page from deltas with stable row references, and the stream watchdog gets a grace window before the first event so a large init is not killed mid-download into a reconnect storm. Hard cutover, no capability flag, since qui ships frontend and backend as one binary.

[coderabbitai]

Walkthrough

Replaces full-page SSE snapshots on every 2-second tick with incremental delta frames. The server computes per-row FNV-1a fingerprints, emits only changed rows plus an optional order list, and forces a full keyframe every 30 seconds. The client reconstructs the full page from the previous baseline plus the delta patch, gating downstream React state updates on actual row changes. Additionally, the connection stale-watchdog adopts a longer initial grace window (60s) to accommodate slow or large init downloads before the 15s steady-state heartbeat budget applies.

Changes

SSE Delta/Keyframe Feature

Layer / File(s)	Summary
Type contracts: StreamDelta and TorrentStreamDelta internal/api/sse/manager.go, web/src/types/torrents.ts	Go adds streamEventDelta constant, extends StreamPayload with Delta *StreamDelta, and exports StreamDelta{Order *[]string}; TypeScript adds TorrentStreamDelta{order?} and extends TorrentStreamPayload with delta?: TorrentStreamDelta.
Server-side delta computation internal/api/sse/delta.go	Introduces buildUpdatePayload (full-vs-delta selection with 30s keyframe interval), seedBaselineIfEmpty (baseline from first subscriber), computeRowDelta (fingerprint diffing), maskVolatile/writeTorrentFingerprint/singleRowFingerprint/crossRowFingerprint (FNV-1a JSON hash with volatile masking), and row key helpers (singleRowKey, crossRowKey, subsetRows).
Server manager wiring for delta ticks internal/api/sse/manager.go	Extends subscriptionGroup with delta-baseline state; drops eventType from publishInstance/enqueueGroup; seeds baseline from init snapshot; introduces buildGroupUpdatePayload for tick frames; refactors materializeGroupResponse to return (response, payload) separately; switches processGroup to buildGroupUpdatePayload.
Client-side delta reconstruction helpers web/src/lib/stream-merge.ts, web/src/lib/cross-instance-torrents.ts	applyOrderedDelta reconstructs ordered page from prevRows + changedRows + optional order, preserving referential stability for unchanged rows. applyStreamDelta branches on single/cross-instance mode, normalizes snake_case instance fields, applies applyOrderedDelta with appropriate identity key, and returns {data, changed}.
Client hook and SSE context wiring web/src/hooks/useTorrentsList.ts, web/src/contexts/SyncStreamContext.tsx	useTorrentsList adds lastFullSnapshotRef to retain baseline snapshots, reworks handleStreamPayload to apply deltas incrementally, introduces rowsChanged flag to gate setAllTorrents conditionally, and clears the ref on view reset. SyncStreamContext registers/removes "delta" listener, adds initial-grace watchdog (60s) for large inits, marks deltas as liveness-proving events, and tracks firstEventSeen to distinguish pre-first-event grace from steady-state timeout.
Tests internal/api/sse/delta_test.go, internal/api/sse/manager_delivery_test.go, internal/api/sse/manager_isolation_test.go, internal/api/sse/manager_test.go, web/src/lib/__tests__/stream-merge.test.ts, web/src/lib/__tests__/cross-instance-torrents.test.ts, web/src/contexts/SyncStreamContext.test.tsx	Go tests cover buildUpdatePayload across seed/delta/keyframe/cross-instance/drain/reorder scenarios, volatile-field masking, and computeRowDelta. Manager integration tests updated to wait for tick frames (update or delta). TypeScript tests add applyOrderedDelta and applyStreamDelta suites covering reference stability, reorder, drain, and cross-instance normalization. Watchdog tests verify initial-grace behavior, CONNECTING escalation, and cold-start timing.

Sequence Diagram(s)

sequenceDiagram
  participant qBit as qBittorrent Poller
  participant mgr as SSE Manager
  participant delta as buildUpdatePayload
  participant sub as Subscriber Session

  Note over mgr,delta: Init path (first connection)
  mgr->>sub: writeInitToSession → streamEventInit (full snapshot)
  mgr->>delta: seedBaselineIfEmpty(initData)

  Note over mgr,delta: Tick path (~2s)
  qBit->>mgr: HandleMainData(instanceID, meta)
  mgr->>mgr: publishInstance → enqueueGroup (meta only)
  mgr->>mgr: processGroup → buildGroupUpdatePayload
  mgr->>delta: buildUpdatePayload(response, now)

  alt baseline unseeded OR keyframe interval elapsed (30s)
    delta-->>mgr: StreamPayload{type:"update", Data:fullSnapshot}
  else rows changed
    delta-->>mgr: StreamPayload{type:"delta", Data:{changedRowsOnly}, Delta:{order?}}
  else aggregate-only change
    delta-->>mgr: StreamPayload{type:"delta", Data:{}, Delta:{}}
  end

  mgr->>sub: broadcast payload

  Note over sub: Client reconstruction
  rect rgba(100, 149, 237, 0.5)
    sub->>sub: SyncStreamContext receives "update" or "delta"
    sub->>sub: useTorrentsList.handleStreamPayload
    sub->>sub: applyStreamDelta(lastFullSnapshotRef, payload)
    sub->>sub: applyOrderedDelta(prevRows, changedRows, order)
    sub->>sub: rowsChanged → setAllTorrents (conditional)
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• autobrr/qui#551: Introduces the core SSE StreamManager and /api/stream pipeline that this PR extends with delta-frame and keyframe mechanics.
• autobrr/qui#1985: Both PRs modify useTorrentsList.ts cross-instance SSE handling and the mergeStreamedCrossInstanceFirstPage call site for row merging.

Suggested labels

sse, bugfix

Poem

🐇 No more full pages every two seconds flat,
Just the rows that changed — imagine that!
A fingerprint here, a delta there,
Keyframes every thirty, play fair.
The bandwidth drops, the CPU sighs with glee,
This bunny hops lightly, streaming efficiently! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.89% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'fix(sse): send torrent page deltas instead of full snapshots' clearly and concisely summarizes the main change: replacing full snapshot transmission with delta-based updates.
Linked Issues check	✅ Passed	The PR comprehensively addresses issue #2046 by implementing delta-based SSE streaming to eliminate full-page resends, reducing bandwidth waste and HTTP/2 flow-control issues that were causing UI black screens.
Out of Scope Changes check	✅ Passed	All code changes are directly scoped to implementing delta-based SSE streaming as required by issue #2046. Backend changes handle delta baseline seeding and computation; frontend changes handle delta deserialization and snapshot reconstruction.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sse-stream-deltas

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}