use rand::Rng;
use serde::{Deserialize, Serialize};
use std::future::Future;
use std::time::Duration;
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
#[non_exhaustive]
pub enum JitterStrategy {
#[default]
None,
Full,
Equal,
Decorrelated,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct RetryPolicy {
pub max_attempts: u32,
pub initial_interval: Duration,
pub max_interval: Duration,
pub backoff_coefficient: f64,
#[serde(default)]
pub jitter: JitterStrategy,
#[serde(default)]
pub non_retryable_errors: Vec<String>,
}
impl Default for RetryPolicy {
fn default() -> Self {
Self {
max_attempts: 3,
initial_interval: Duration::from_secs(1),
max_interval: Duration::from_secs(60),
backoff_coefficient: 2.0,
jitter: JitterStrategy::None,
non_retryable_errors: Vec::new(),
}
}
}
impl RetryPolicy {
pub fn new(
max_attempts: u32,
initial_interval: Duration,
max_interval: Duration,
backoff_coefficient: f64,
) -> Self {
Self {
max_attempts,
initial_interval,
max_interval,
backoff_coefficient,
jitter: JitterStrategy::None,
non_retryable_errors: Vec::new(),
}
}
pub fn with_max_attempts(mut self, max_attempts: u32) -> Self {
self.max_attempts = max_attempts;
self
}
pub fn with_initial_interval(mut self, interval: Duration) -> Self {
self.initial_interval = interval;
self
}
pub fn with_max_interval(mut self, interval: Duration) -> Self {
self.max_interval = interval;
self
}
pub fn with_backoff_coefficient(mut self, coefficient: f64) -> Self {
self.backoff_coefficient = coefficient;
self
}
pub fn with_non_retryable_errors<I, S>(mut self, error_types: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.non_retryable_errors = error_types.into_iter().map(Into::into).collect();
self
}
pub fn with_jitter(mut self, jitter: JitterStrategy) -> Self {
self.jitter = jitter;
self
}
pub fn no_retry() -> Self {
Self {
max_attempts: 1,
initial_interval: Duration::from_secs(0),
max_interval: Duration::from_secs(0),
backoff_coefficient: 1.0,
jitter: JitterStrategy::None,
non_retryable_errors: Vec::new(),
}
}
pub fn exponential_backoff(max_attempts: u32, initial_interval: Duration) -> Self {
Self {
max_attempts,
initial_interval,
max_interval: Duration::from_secs(3600), backoff_coefficient: 2.0,
jitter: JitterStrategy::None,
non_retryable_errors: Vec::new(),
}
}
pub fn retry_interval(&self, attempt: u32) -> Duration {
let base = self.base_interval(attempt);
self.apply_jitter(base, base)
}
pub fn retry_interval_decorrelated(&self, prev_interval: Duration) -> Duration {
match self.jitter {
JitterStrategy::Decorrelated => {
let mut rng = rand::thread_rng();
let min = self.initial_interval.as_secs_f64();
let max = (prev_interval.as_secs_f64() * 3.0).min(self.max_interval.as_secs_f64());
let jittered = if max > min {
rng.gen_range(min..max)
} else {
min
};
Duration::from_secs_f64(jittered)
}
_ => {
let base = prev_interval;
self.apply_jitter(base, base)
}
}
}
fn base_interval(&self, attempt: u32) -> Duration {
if attempt <= 1 {
return self.initial_interval;
}
let multiplier = self.backoff_coefficient.powi((attempt - 1) as i32);
let interval_secs = self.initial_interval.as_secs_f64() * multiplier;
let capped_secs = interval_secs.min(self.max_interval.as_secs_f64());
Duration::from_secs_f64(capped_secs)
}
fn apply_jitter(&self, base: Duration, _prev: Duration) -> Duration {
let base_secs = base.as_secs_f64();
match self.jitter {
JitterStrategy::None => base,
JitterStrategy::Full => {
let jittered = rand::thread_rng().gen_range(0.0..base_secs.max(f64::MIN_POSITIVE));
Duration::from_secs_f64(jittered)
}
JitterStrategy::Equal => {
let half = base_secs / 2.0;
let jittered =
half + rand::thread_rng().gen_range(0.0..half.max(f64::MIN_POSITIVE));
Duration::from_secs_f64(jittered)
}
JitterStrategy::Decorrelated => {
let jittered = rand::thread_rng().gen_range(0.0..base_secs.max(f64::MIN_POSITIVE));
Duration::from_secs_f64(jittered)
}
}
}
}
pub async fn retry_with_policy<F, Fut, T>(policy: &RetryPolicy, f: F) -> crate::error::Result<T>
where
F: Fn() -> Fut,
Fut: Future<Output = crate::error::Result<T>>,
{
let mut prev_interval = policy.initial_interval;
let mut attempt = 0u32;
loop {
attempt = attempt.saturating_add(1);
match f().await {
Ok(value) => return Ok(value),
Err(e) => {
if !e.is_retryable() || (policy.max_attempts != 0 && attempt >= policy.max_attempts)
{
return Err(e);
}
let interval = if policy.jitter == JitterStrategy::Decorrelated {
let interval = policy.retry_interval_decorrelated(prev_interval);
prev_interval = interval;
interval
} else {
policy.retry_interval(attempt)
};
tracing::debug!(
attempt = attempt,
max_attempts = policy.max_attempts,
next_interval_ms = interval.as_millis() as u64,
error = %e,
"Retrying after error"
);
tokio::time::sleep(interval).await;
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_retry_policy_defaults() {
let policy = RetryPolicy::default();
assert_eq!(policy.max_attempts, 3);
assert_eq!(policy.initial_interval, Duration::from_secs(1));
assert_eq!(policy.max_interval, Duration::from_secs(60));
assert_eq!(policy.backoff_coefficient, 2.0);
}
#[test]
fn test_retry_policy_no_retry() {
let policy = RetryPolicy::no_retry();
assert_eq!(policy.max_attempts, 1);
}
#[test]
fn test_retry_policy_exponential_backoff() {
let policy = RetryPolicy::exponential_backoff(5, Duration::from_secs(1));
assert_eq!(policy.max_attempts, 5);
assert_eq!(policy.initial_interval, Duration::from_secs(1));
assert_eq!(policy.backoff_coefficient, 2.0);
}
#[test]
fn test_retry_interval_calculation() {
let policy = RetryPolicy {
max_attempts: 5,
initial_interval: Duration::from_secs(1),
max_interval: Duration::from_secs(10),
backoff_coefficient: 2.0,
jitter: JitterStrategy::None,
non_retryable_errors: vec![],
};
assert_eq!(policy.retry_interval(1), Duration::from_secs(1));
assert_eq!(policy.retry_interval(2), Duration::from_secs(2));
assert_eq!(policy.retry_interval(3), Duration::from_secs(4));
assert_eq!(policy.retry_interval(4), Duration::from_secs(8));
assert_eq!(policy.retry_interval(5), Duration::from_secs(10));
}
#[test]
fn test_retry_policy_serialization() {
let policy = RetryPolicy::default();
let json = serde_json::to_string(&policy).unwrap();
assert!(json.contains("max_attempts"));
let deserialized: RetryPolicy = serde_json::from_str(&json).unwrap();
assert_eq!(deserialized.max_attempts, policy.max_attempts);
}
#[test]
fn test_retry_policy_new() {
let policy = RetryPolicy::new(10, Duration::from_secs(2), Duration::from_secs(300), 1.5);
assert_eq!(policy.max_attempts, 10);
assert_eq!(policy.initial_interval, Duration::from_secs(2));
assert_eq!(policy.max_interval, Duration::from_secs(300));
assert_eq!(policy.backoff_coefficient, 1.5);
assert_eq!(policy.jitter, JitterStrategy::None);
}
#[test]
fn test_with_jitter_builder() {
let policy = RetryPolicy::exponential_backoff(5, Duration::from_secs(1))
.with_jitter(JitterStrategy::Full);
assert_eq!(policy.jitter, JitterStrategy::Full);
assert_eq!(policy.max_attempts, 5);
}
#[test]
fn test_full_jitter_bounded() {
let policy = RetryPolicy::exponential_backoff(5, Duration::from_secs(10))
.with_jitter(JitterStrategy::Full);
for attempt in 1..=5 {
let base = policy.base_interval(attempt);
let interval = policy.retry_interval(attempt);
assert!(interval <= base, "Full jitter should be <= base interval");
}
}
#[test]
fn test_equal_jitter_bounded() {
let policy = RetryPolicy::exponential_backoff(5, Duration::from_secs(10))
.with_jitter(JitterStrategy::Equal);
for attempt in 1..=5 {
let base = policy.base_interval(attempt);
let interval = policy.retry_interval(attempt);
let half = base / 2;
assert!(interval >= half, "Equal jitter should be >= base/2");
assert!(interval <= base, "Equal jitter should be <= base");
}
}
#[test]
fn test_jitter_strategy_default() {
assert_eq!(JitterStrategy::default(), JitterStrategy::None);
}
#[test]
fn test_jitter_serialization() {
let policy = RetryPolicy::default().with_jitter(JitterStrategy::Full);
let json = serde_json::to_string(&policy).unwrap();
assert!(json.contains("Full"));
let deserialized: RetryPolicy = serde_json::from_str(&json).unwrap();
assert_eq!(deserialized.jitter, JitterStrategy::Full);
}
#[tokio::test]
async fn test_retry_with_policy_success() {
let policy = RetryPolicy::new(3, Duration::from_millis(1), Duration::from_millis(10), 2.0);
let result = retry_with_policy(&policy, || async { Ok(42) }).await;
assert_eq!(result.unwrap(), 42);
}
#[tokio::test]
async fn test_retry_with_policy_retries_then_succeeds() {
use std::sync::atomic::{AtomicU32, Ordering};
let attempts = std::sync::Arc::new(AtomicU32::new(0));
let attempts_clone = attempts.clone();
let policy = RetryPolicy::new(3, Duration::from_millis(1), Duration::from_millis(10), 2.0);
let result = retry_with_policy(&policy, || {
let attempts = attempts_clone.clone();
async move {
let n = attempts.fetch_add(1, Ordering::SeqCst) + 1;
if n < 3 {
Err(crate::Error::Client(
crate::error::ClientError::ConnectionFailed {
url: "http://test".to_string(),
reason: "transient".to_string(),
},
))
} else {
Ok(42)
}
}
})
.await;
assert_eq!(result.unwrap(), 42);
assert_eq!(attempts.load(Ordering::SeqCst), 3);
}
#[tokio::test]
async fn zero_max_attempts_retries_until_success() {
use std::sync::atomic::{AtomicU32, Ordering};
let attempts = std::sync::Arc::new(AtomicU32::new(0));
let attempts_clone = attempts.clone();
let policy = RetryPolicy::default()
.with_max_attempts(0)
.with_initial_interval(Duration::ZERO);
let result = retry_with_policy(&policy, || {
let attempts = attempts_clone.clone();
async move {
if attempts.fetch_add(1, Ordering::SeqCst) < 2 {
Err(crate::Error::Client(
crate::error::ClientError::ConnectionFailed {
url: "http://test".to_string(),
reason: "transient".to_string(),
},
))
} else {
Ok(42)
}
}
})
.await;
assert_eq!(result.unwrap(), 42);
assert_eq!(attempts.load(Ordering::SeqCst), 3);
}
#[tokio::test]
async fn test_retry_with_policy_permanent_error_no_retry() {
use std::sync::atomic::{AtomicU32, Ordering};
let attempts = std::sync::Arc::new(AtomicU32::new(0));
let attempts_clone = attempts.clone();
let policy = RetryPolicy::new(5, Duration::from_millis(1), Duration::from_millis(10), 2.0);
let result: crate::error::Result<i32> = retry_with_policy(&policy, || {
let attempts = attempts_clone.clone();
async move {
attempts.fetch_add(1, Ordering::SeqCst);
Err(crate::Error::Configuration("permanent".to_string()))
}
})
.await;
assert!(result.is_err());
assert_eq!(attempts.load(Ordering::SeqCst), 1);
}
}