Skip to main content

toddstack_frontend_engine/
policy.rs

1//! Deterministic retry and clock helpers: randomness and time come from the caller.
2
3/// Retry with exponential backoff and jitter.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub struct RetryPolicy {
6    pub max_retries: u32,
7    pub base_ms: u64,
8    pub cap_ms: u64,
9    /// Largest fraction (per mille) a delay may shrink by.
10    pub jitter_permille: u64,
11}
12
13impl RetryPolicy {
14    /// Reads retry 3 times, 0.25 s up to 4 s.
15    #[must_use]
16    pub const fn read() -> Self {
17        Self {
18            max_retries: 3,
19            base_ms: 250,
20            cap_ms: 4000,
21            jitter_permille: 250,
22        }
23    }
24
25    /// Writes retry 5 times, 0.5 s up to 8 s.
26    #[must_use]
27    pub const fn write() -> Self {
28        Self {
29            max_retries: 5,
30            base_ms: 500,
31            cap_ms: 8000,
32            jitter_permille: 250,
33        }
34    }
35
36    /// Delay before retry number `failures` (0 after the first failure); `None` when retries are
37    /// spent. `rand_permille` is the caller's random draw in 0..=1000.
38    #[must_use]
39    pub fn delay_ms(&self, failures: u32, rand_permille: u32) -> Option<u64> {
40        if failures >= self.max_retries {
41            return None;
42        }
43        let exp: u64 = self
44            .base_ms
45            .saturating_mul(1u64 << failures.min(32))
46            .min(self.cap_ms);
47        let cut: u64 = exp * self.jitter_permille * u64::from(rand_permille.min(1000)) / 1_000_000;
48        Some(exp - cut)
49    }
50
51    /// Network failure (status 0), timeout, rate limit and server errors are worth retrying.
52    #[must_use]
53    pub const fn is_retryable(status: u16) -> bool {
54        matches!(status, 0 | 408 | 429 | 500..=599)
55    }
56}
57
58/// Server clock offset from the best (lowest round trip) sample: the server's time is assumed to
59/// be read at the call midpoint.
60#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
61pub struct ClockOffset {
62    offset_ms: i64,
63    best_rtt_ms: Option<u64>,
64}
65
66impl ClockOffset {
67    /// `sent` / `recv`: local ms around the call; `server_ms`: the server's clock in the reply.
68    pub fn observe(&mut self, sent: u64, recv: u64, server_ms: u64) {
69        let rtt: u64 = recv.saturating_sub(sent);
70        if self.best_rtt_ms.is_some_and(|best| rtt > best) {
71            return;
72        }
73        let mid: i128 = i128::from(sent) + i128::from(rtt / 2);
74        let offset: i128 = i128::from(server_ms) - mid;
75        self.offset_ms = i64::try_from(offset).unwrap_or(0);
76        self.best_rtt_ms = Some(rtt);
77    }
78
79    #[must_use]
80    pub const fn offset_ms(&self) -> i64 {
81        self.offset_ms
82    }
83
84    /// Server time for a local wall-clock reading.
85    #[must_use]
86    pub fn server_now(&self, local_ms: u64) -> u64 {
87        let v: i128 = i128::from(local_ms) + i128::from(self.offset_ms);
88        u64::try_from(v.max(0)).unwrap_or(0)
89    }
90}
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95
96    #[test]
97    fn backoff_doubles_to_the_cap_then_stops() {
98        let policy: RetryPolicy = RetryPolicy::write();
99        let actual: Vec<Option<u64>> = (0..6).map(|n| policy.delay_ms(n, 0)).collect();
100        let expected: Vec<Option<u64>> = vec![
101            Some(500),
102            Some(1000),
103            Some(2000),
104            Some(4000),
105            Some(8000),
106            None,
107        ];
108        assert_eq!(expected, actual);
109    }
110
111    #[test]
112    fn jitter_only_ever_shortens_a_delay() {
113        assert_eq!(Some(375), RetryPolicy::write().delay_ms(0, 1000));
114        assert_eq!(Some(375), RetryPolicy::write().delay_ms(0, 5000));
115    }
116
117    #[test]
118    fn only_transient_statuses_are_retryable() {
119        let retryable: Vec<u16> = [0, 200, 400, 404, 408, 429, 500, 503]
120            .into_iter()
121            .filter(|s| RetryPolicy::is_retryable(*s))
122            .collect();
123        assert_eq!(vec![0, 408, 429, 500, 503], retryable);
124    }
125
126    #[test]
127    fn the_offset_follows_the_lowest_round_trip() {
128        let mut clock: ClockOffset = ClockOffset::default();
129        clock.observe(1000, 1100, 5050);
130        assert_eq!(4000, clock.offset_ms());
131        clock.observe(2000, 2400, 9999);
132        assert_eq!(4000, clock.offset_ms());
133        assert_eq!(7000, clock.server_now(3000));
134    }
135}