Skip to content

feat: adaptive WebSocket reconnection with full-jitter backoff. - #81

Merged
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/adaptive-ws-reconnection
Jun 25, 2026
Merged

feat: adaptive WebSocket reconnection with full-jitter backoff.#81
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/adaptive-ws-reconnection

Conversation

@real-venus

Copy link
Copy Markdown
Contributor

Adaptive WebSocket Reconnection Stratum (#57)

Closes #57

File Responsibility
src/types/connection.ts Invariants (500 ms→30 s backoff ×2, 12-attempt cap, 15 s/5 s heartbeat, 500-frame buffer, sticky-node storage key) and the state/event/recovery-frame types.
src/utils/backoff.ts backoffCeiling + fullJitterBackoff — AWS-style full jitter (random(0, min(cap, base·2^n))), overflow-safe, injectable RNG.
src/utils/frameBuffer.ts 500-slot circular buffer of telemetry frames; push/toArray/drain, evicts oldest, preserves the high-water sequence id across drains.
src/services/reconnectMachine.ts Custom FSM: idle → connecting → connected with reconnecting / recovering / failed branches; computes the next jittered delay and declares terminal failure after 12 attempts. Pure transitions (the hook owns the timers) → fully unit-testable.
src/store/slices/connectionSlice.ts Connection store (codebase's singleton pattern) + useConnectionState hook, with green/yellow/red quality derivation.
src/hooks/useWebSocket.ts Delegates the lifecycle to the machine: full-jitter reconnect scheduling, heartbeat ping/pong watchdog, sticky nodeId in sessionStorage, recovery handshake (recoveryrecovery_ack) replaying the buffer, and REST backfill (GET /ws/replay?from=&to=) when frames were missed. Injectable transport/clock/RNG/storage.
src/components/panels/ConnectionStatusBar.tsx Fixed top bar (green/yellow/red) with attempt counter and a persistent terminal-failure banner + retry.
tests/unit/* + tests/hooks/useWebSocket.test.ts Backoff bounds/cap, ring-buffer eviction/drain, FSM transitions + max-attempts→failed, slice/quality, and a fake-socket/fake-timer hook test covering connect, ping/pong, reconnect→recovery→backfill, heartbeat timeout, and terminal failure.

…icky recovery (Utility-Protocol#57)

Adds an adaptive reconnection stratum for the real-time dashboard WebSocket so a
failure cascade costs the operator at most ~3s of data loss instead of a retry
storm and lost subscription state.

- types/connection.ts: invariants (500ms→30s backoff, 12-attempt cap, 15s/5s
  heartbeat, 500-frame buffer) plus state/event and recovery-frame types
- utils/backoff.ts: capped exponential with AWS full-jitter (overflow-safe)
- utils/frameBuffer.ts: 500-slot ring buffer for telemetry replay
- services/reconnectMachine.ts: custom FSM (idle/connecting/connected/
  reconnecting/recovering/failed) computing the next jittered delay
- store/slices/connectionSlice.ts: connection store + useConnectionState hook,
  with green/yellow/red quality derivation
- hooks/useWebSocket.ts: delegates lifecycle to the machine — full-jitter
  reconnect scheduling, heartbeat ping/pong watchdog, sticky nodeId in
  sessionStorage, recovery handshake (recovery/recovery_ack) and REST backfill
- components/panels/ConnectionStatusBar.tsx: fixed quality bar + terminal-failure
  banner with retry
- unit tests (backoff, frameBuffer, machine, slice) + a fake-socket/fake-timer
  hook test covering connect, ping/pong, reconnect+recovery+backfill, heartbeat
  timeout and terminal failure
@elizabetheonoja-art
elizabetheonoja-art merged commit 0762a18 into Utility-Protocol:main Jun 25, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adaptive WebSocket Reconnection Stratum with Exponential Backoff, Full-Jitter, and Sticky Session Affinity

2 participants