Skip to main content

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}