use std::collections::hash_map::RandomState;
use std::hash::{BuildHasher, Hasher};
use std::time::Duration;
pub fn jitter_seed() -> u64 {
RandomState::new().build_hasher().finish()
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct RetryPolicy {
pub max_retries: u32,
pub base_delay: Duration,
pub max_delay: Duration,
pub budget: Option<Duration>,
}
impl Default for RetryPolicy {
fn default() -> Self {
Self {
max_retries: 2,
base_delay: Duration::from_millis(500),
max_delay: Duration::from_secs(10),
budget: Some(Duration::from_secs(30)),
}
}
}
impl RetryPolicy {
pub fn new(max_retries: u32) -> Self {
Self {
max_retries,
..Default::default()
}
}
pub fn none() -> Self {
Self {
max_retries: 0,
..Default::default()
}
}
#[must_use = "the returned RetryPolicy should be used"]
pub fn with_base_delay(mut self, delay: Duration) -> Self {
self.base_delay = delay;
self
}
#[must_use = "the returned RetryPolicy should be used"]
pub fn with_max_delay(mut self, delay: Duration) -> Self {
self.max_delay = delay;
self
}
#[must_use = "the returned RetryPolicy should be used"]
pub fn with_budget(mut self, budget: Option<Duration>) -> Self {
self.budget = budget;
self
}
pub fn delay_for(&self, attempt: u32) -> Duration {
let exp = attempt.min(30); let raw = self
.base_delay
.as_millis()
.saturating_mul(1u128 << exp)
.min(u64::MAX as u128) as u64;
let max_delay_ms = self.max_delay.as_millis().min(u64::MAX as u128) as u64;
let capped = raw.min(max_delay_ms);
Duration::from_millis(capped)
}
pub fn delay_for_with_jitter(&self, attempt: u32, jitter_seed: u64) -> Duration {
let base = self.delay_for(attempt);
let base_ms = base.as_millis() as u64;
if base_ms == 0 {
return Duration::ZERO;
}
let half = base_ms / 2;
let jitter = jitter_seed % (half + 1);
Duration::from_millis(half + jitter)
}
pub fn delay_for_retry_after(&self, attempt: u32, retry_after: Duration) -> Option<Duration> {
if retry_after > self.max_delay {
return None;
}
let own = self.delay_for(attempt);
Some(if retry_after > own { retry_after } else { own })
}
pub fn budget_exceeded(&self, elapsed: Duration, delay: Duration) -> bool {
match self.budget {
Some(budget) => elapsed + delay >= budget,
None => false,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn delay_grows_exponentially() {
let policy = RetryPolicy::default();
assert_eq!(policy.delay_for(0), Duration::from_millis(500));
assert_eq!(policy.delay_for(1), Duration::from_millis(1000));
assert_eq!(policy.delay_for(2), Duration::from_millis(2000));
}
#[test]
fn delay_is_capped() {
let policy = RetryPolicy::default().with_max_delay(Duration::from_millis(1500));
assert_eq!(policy.delay_for(0), Duration::from_millis(500));
assert_eq!(policy.delay_for(1), Duration::from_millis(1000));
assert_eq!(policy.delay_for(2), Duration::from_millis(1500));
assert_eq!(policy.delay_for(10), Duration::from_millis(1500));
}
#[test]
fn equal_jitter_stays_within_bounds() {
let policy = RetryPolicy::default();
let base = policy.delay_for(1); let jittered = policy.delay_for_with_jitter(1, 42);
assert!(jittered >= Duration::from_millis(base.as_millis() as u64 / 2));
assert!(jittered <= base);
}
#[test]
fn equal_jitter_floor_is_half_base() {
let policy = RetryPolicy::default().with_base_delay(Duration::from_millis(200));
let delay = policy.delay_for_with_jitter(0, 0);
assert_eq!(delay, Duration::from_millis(100));
let delay = policy.delay_for_with_jitter(0, 100);
assert_eq!(delay, Duration::from_millis(200));
}
#[test]
fn retry_after_respects_server_hint() {
let policy = RetryPolicy::default();
let delay = policy.delay_for_retry_after(0, Duration::from_secs(5));
assert_eq!(delay, Some(Duration::from_secs(5)));
let delay = policy.delay_for_retry_after(0, Duration::from_millis(100));
assert_eq!(delay, Some(Duration::from_millis(500)));
}
#[test]
fn retry_after_gives_up_when_hint_exceeds_max_delay() {
let policy = RetryPolicy::default(); let delay = policy.delay_for_retry_after(0, Duration::from_secs(30));
assert_eq!(delay, None);
}
#[test]
fn delay_for_handles_extreme_max_delay() {
let policy = RetryPolicy::new(1)
.with_base_delay(Duration::from_millis(500))
.with_max_delay(Duration::from_secs(u64::MAX / 2));
let delay = policy.delay_for(5);
assert_eq!(delay, Duration::from_millis(16000));
}
#[test]
fn budget_exceeded_when_elapsed_plus_delay_exceeds_budget() {
let policy = RetryPolicy::default().with_budget(Some(Duration::from_secs(10)));
assert!(policy.budget_exceeded(Duration::from_secs(8), Duration::from_secs(3)));
assert!(policy.budget_exceeded(Duration::from_secs(7), Duration::from_secs(3)));
assert!(!policy.budget_exceeded(Duration::from_secs(6), Duration::from_secs(3)));
}
#[test]
fn budget_none_never_exceeded() {
let policy = RetryPolicy::default().with_budget(None);
assert!(!policy.budget_exceeded(Duration::from_secs(999), Duration::from_secs(999)));
}
#[test]
fn with_budget_builder_sets_field() {
let policy = RetryPolicy::default().with_budget(Some(Duration::from_secs(60)));
assert_eq!(policy.budget, Some(Duration::from_secs(60)));
let policy = RetryPolicy::default().with_budget(None);
assert_eq!(policy.budget, None);
}
#[test]
fn none_policy_has_zero_retries() {
let policy = RetryPolicy::none();
assert_eq!(policy.max_retries, 0);
}
}