hyprstream_rpc/transport/backoff.rs
1//! Reconnect backoff for lazy transports (#156).
2//!
3//! [`ReconnectBackoff`] tracks consecutive failed dial attempts and computes an
4//! exponential-backoff cooldown window between them. The lazy transports hold one
5//! `ReconnectBackoff` alongside their cached session so failed dials don't
6//! tight-loop on a downed peer — matching the explicit `tokio::time::sleep`
7//! backoff that `zmq_connection.rs` used to perform.
8//!
9//! ## Design
10//!
11//! - [`LazyState`] bundles the optional cached transport + backoff so they stay
12//! consistent under a single lock: "no cached session" always implies "may be in
13//! backoff."
14//! - `invalidate()` calls `record_failure()` so a *send-path* transport error
15//! also counts against the backoff budget (not only dial failures).
16//! - `INITIAL_BACKOFF` is 1 s; subsequent failures double up to `MAX_BACKOFF`
17//! (30 s), matching the ZMQ reconnect interval cap observed in practice.
18//!
19//! ## What #156 defers
20//!
21//! DID-doc re-resolve on re-dial (so the manager picks up a moved `service`
22//! entry) requires async resolution which can't run inside the sync lock; that
23//! layer is left for a future incremental PR and documented with a TODO below.
24
25use std::time::{Duration, Instant};
26
27const INITIAL_BACKOFF: Duration = Duration::from_secs(1);
28const BACKOFF_MULTIPLIER: f64 = 2.0;
29const MAX_BACKOFF: Duration = Duration::from_secs(30);
30
31/// Exponential-backoff cooldown tracker for RPC reconnect attempts.
32#[derive(Debug, Default)]
33pub struct ReconnectBackoff {
34 /// Number of consecutive failed dials (saturates at u32::MAX).
35 failures: u32,
36 /// Reconnect is blocked until this instant; `None` means "go ahead."
37 cooldown_until: Option<Instant>,
38}
39
40impl ReconnectBackoff {
41 /// How long the caller must wait before a reconnect attempt is allowed.
42 /// Returns `None` if a dial may proceed immediately.
43 pub fn cooldown_remaining(&self) -> Option<Duration> {
44 let until = self.cooldown_until?;
45 let now = Instant::now();
46 if now >= until {
47 None
48 } else {
49 Some(until - now)
50 }
51 }
52
53 /// Record a failed dial (or send-path fatal) and schedule the next window.
54 pub fn record_failure(&mut self) {
55 self.failures = self.failures.saturating_add(1);
56 let secs = INITIAL_BACKOFF.as_secs_f64()
57 * BACKOFF_MULTIPLIER.powi(self.failures.saturating_sub(1) as i32);
58 let delay = Duration::from_secs_f64(secs).min(MAX_BACKOFF);
59 self.cooldown_until = Some(Instant::now() + delay);
60 }
61
62 /// Reset backoff after a successful connection.
63 pub fn record_success(&mut self) {
64 self.failures = 0;
65 self.cooldown_until = None;
66 }
67}
68
69/// Combined lazy-connect state: the optional cached transport + reconnect backoff.
70///
71/// Keeping both behind a single lock ensures "session = None" is always
72/// consistent with the backoff state — a race cannot observe a stale cooldown
73/// after a successful reconnect resets it.
74pub struct LazyState<T> {
75 /// `None` until the first successful dial; reset to `None` on transport error.
76 pub cached: Option<T>,
77 pub backoff: ReconnectBackoff,
78}
79
80impl<T> Default for LazyState<T> {
81 fn default() -> Self {
82 Self {
83 cached: None,
84 backoff: ReconnectBackoff::default(),
85 }
86 }
87}
88
89#[cfg(test)]
90mod tests {
91 use super::*;
92
93 #[test]
94 fn first_failure_sets_cooldown() {
95 let mut b = ReconnectBackoff::default();
96 assert!(
97 b.cooldown_remaining().is_none(),
98 "no cooldown before first failure"
99 );
100 b.record_failure();
101 assert!(
102 b.cooldown_remaining().is_some(),
103 "cooldown after first failure"
104 );
105 }
106
107 #[test]
108 fn success_resets_backoff() {
109 let mut b = ReconnectBackoff::default();
110 b.record_failure();
111 b.record_success();
112 assert_eq!(b.failures, 0);
113 assert!(b.cooldown_remaining().is_none());
114 }
115
116 #[test]
117 fn backoff_caps_at_max() {
118 let mut b = ReconnectBackoff::default();
119 for _ in 0..64 {
120 b.record_failure();
121 }
122 // Can't inspect the raw cooldown_until, but record_failure must not panic
123 // on saturation and the remaining duration must be ≤ MAX_BACKOFF + epsilon.
124 if let Some(remaining) = b.cooldown_remaining() {
125 assert!(remaining <= MAX_BACKOFF + Duration::from_millis(50));
126 }
127 }
128}