wme_client/

retry.rs

use std::time::Duration;

/// Retry configuration for failed requests.
#[derive(Debug, Clone)]
pub struct RetryConfig {
    /// Maximum number of retries
    pub max_retries: u32,
    /// Base delay between retries (exponential backoff)
    pub base_delay: Duration,
    /// Maximum delay between retries
    pub max_delay: Duration,
    /// HTTP status codes that should trigger a retry
    pub retryable_status_codes: Vec<u16>,
    /// Circuit breaker: consecutive failures before opening circuit
    pub circuit_threshold: u32,
    /// Circuit breaker: timeout before transitioning from Open to HalfOpen
    pub circuit_timeout: Duration,
    /// Jitter factor (0.0-1.0) to add randomness to backoff delays
    pub jitter: f64,
}

impl Default for RetryConfig {
    fn default() -> Self {
        Self {
            max_retries: 3,
            base_delay: Duration::from_millis(500),
            max_delay: Duration::from_secs(30),
            retryable_status_codes: vec![408, 429, 500, 502, 503, 504],
            circuit_threshold: 5,
            circuit_timeout: Duration::from_secs(60),
            jitter: 0.1,
        }
    }
}

impl RetryConfig {
    /// Create a new retry configuration with default values.
    pub fn new() -> Self {
        Self::default()
    }

    /// Set maximum number of retries.
    pub fn with_max_retries(mut self, max_retries: u32) -> Self {
        self.max_retries = max_retries;
        self
    }

    /// Set base delay for exponential backoff.
    pub fn with_base_delay(mut self, delay: Duration) -> Self {
        self.base_delay = delay;
        self
    }

    /// Set maximum delay for exponential backoff.
    pub fn with_max_delay(mut self, delay: Duration) -> Self {
        self.max_delay = delay;
        self
    }

    /// Set circuit breaker threshold (consecutive failures before opening).
    pub fn with_circuit_threshold(mut self, threshold: u32) -> Self {
        self.circuit_threshold = threshold;
        self
    }

    /// Set circuit breaker timeout (time before trying again).
    pub fn with_circuit_timeout(mut self, timeout: Duration) -> Self {
        self.circuit_timeout = timeout;
        self
    }

    /// Set jitter factor (0.0-1.0) to add randomness to backoff.
    /// This helps prevent thundering herd when services recover.
    pub fn with_jitter(mut self, jitter: f64) -> Self {
        self.jitter = jitter.clamp(0.0, 1.0);
        self
    }

    /// Calculate delay for a specific retry attempt with exponential backoff and jitter.
    pub fn delay_for_attempt(&self, attempt: u32) -> Duration {
        // Exponential backoff: base_delay * 2^attempt
        let exponential = self.base_delay * 2u32.pow(attempt);
        let capped = std::cmp::min(exponential, self.max_delay);

        // Add jitter to prevent thundering herd
        if self.jitter > 0.0 {
            use rand::prelude::*;
            let mut rng = rand::rng();
            let jitter_range = capped.as_millis() as f64 * self.jitter;
            let jitter_amount = rng.random_range(-jitter_range..jitter_range);
            let jittered_millis = (capped.as_millis() as f64 + jitter_amount).max(0.0) as u64;
            Duration::from_millis(jittered_millis)
        } else {
            capped
        }
    }

    /// Check if a status code should trigger a retry.
    pub fn is_retryable(&self, status: u16) -> bool {
        self.retryable_status_codes.contains(&status)
    }
}

/// Default retry configuration for production use.
/// More conservative to be a good API citizen.
impl RetryConfig {
    /// Production-grade configuration with conservative defaults.
    pub fn production() -> Self {
        Self {
            max_retries: 5,
            base_delay: Duration::from_secs(1),
            max_delay: Duration::from_secs(60),
            retryable_status_codes: vec![408, 429, 500, 502, 503, 504],
            circuit_threshold: 10,
            circuit_timeout: Duration::from_secs(120),
            jitter: 0.25,
        }
    }

    /// Aggressive retry configuration for development/testing.
    pub fn development() -> Self {
        Self {
            max_retries: 2,
            base_delay: Duration::from_millis(100),
            max_delay: Duration::from_secs(5),
            retryable_status_codes: vec![408, 429, 500, 502, 503, 504],
            circuit_threshold: 3,
            circuit_timeout: Duration::from_secs(10),
            jitter: 0.0,
        }
    }

    /// Configuration optimized for batch processing with longer delays.
    pub fn batch_processing() -> Self {
        Self {
            max_retries: 10,
            base_delay: Duration::from_secs(5),
            max_delay: Duration::from_secs(300),
            retryable_status_codes: vec![408, 429, 500, 502, 503, 504],
            circuit_threshold: 20,
            circuit_timeout: Duration::from_secs(300),
            jitter: 0.5,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_default_config() {
        let config = RetryConfig::default();
        assert_eq!(config.max_retries, 3);
        assert_eq!(config.base_delay, Duration::from_millis(500));
        assert_eq!(config.max_delay, Duration::from_secs(30));
        assert_eq!(config.circuit_threshold, 5);
        assert_eq!(config.circuit_timeout, Duration::from_secs(60));
        assert_eq!(config.jitter, 0.1);
        assert!(config.retryable_status_codes.contains(&429));
        assert!(config.retryable_status_codes.contains(&503));
    }

    #[test]
    fn test_production_config() {
        let config = RetryConfig::production();
        assert_eq!(config.max_retries, 5);
        assert_eq!(config.base_delay, Duration::from_secs(1));
        assert_eq!(config.max_delay, Duration::from_secs(60));
        assert_eq!(config.circuit_threshold, 10);
        assert_eq!(config.circuit_timeout, Duration::from_secs(120));
        assert_eq!(config.jitter, 0.25);
    }

    #[test]
    fn test_development_config() {
        let config = RetryConfig::development();
        assert_eq!(config.max_retries, 2);
        assert_eq!(config.base_delay, Duration::from_millis(100));
        assert_eq!(config.max_delay, Duration::from_secs(5));
        assert_eq!(config.circuit_threshold, 3);
        assert_eq!(config.circuit_timeout, Duration::from_secs(10));
        assert_eq!(config.jitter, 0.0);
    }

    #[test]
    fn test_batch_processing_config() {
        let config = RetryConfig::batch_processing();
        assert_eq!(config.max_retries, 10);
        assert_eq!(config.base_delay, Duration::from_secs(5));
        assert_eq!(config.max_delay, Duration::from_secs(300));
        assert_eq!(config.circuit_threshold, 20);
        assert_eq!(config.circuit_timeout, Duration::from_secs(300));
        assert_eq!(config.jitter, 0.5);
    }

    #[test]
    fn test_builder_methods() {
        let config = RetryConfig::new()
            .with_max_retries(10)
            .with_base_delay(Duration::from_secs(2))
            .with_max_delay(Duration::from_secs(120))
            .with_circuit_threshold(15)
            .with_circuit_timeout(Duration::from_secs(180))
            .with_jitter(0.5);

        assert_eq!(config.max_retries, 10);
        assert_eq!(config.base_delay, Duration::from_secs(2));
        assert_eq!(config.max_delay, Duration::from_secs(120));
        assert_eq!(config.circuit_threshold, 15);
        assert_eq!(config.circuit_timeout, Duration::from_secs(180));
        assert_eq!(config.jitter, 0.5);
    }

    #[test]
    fn test_jitter_clamping() {
        let config = RetryConfig::new().with_jitter(1.5);
        assert_eq!(config.jitter, 1.0);

        let config = RetryConfig::new().with_jitter(-0.5);
        assert_eq!(config.jitter, 0.0);
    }

    #[test]
    fn test_delay_for_attempt_exponential() {
        let config = RetryConfig::new()
            .with_base_delay(Duration::from_millis(100))
            .with_max_delay(Duration::from_secs(10))
            .with_jitter(0.0);

        // Test exponential backoff without jitter
        let delay0 = config.delay_for_attempt(0);
        let delay1 = config.delay_for_attempt(1);
        let delay2 = config.delay_for_attempt(2);
        let delay3 = config.delay_for_attempt(3);

        // 100ms * 2^0 = 100ms
        assert_eq!(delay0, Duration::from_millis(100));
        // 100ms * 2^1 = 200ms
        assert_eq!(delay1, Duration::from_millis(200));
        // 100ms * 2^2 = 400ms
        assert_eq!(delay2, Duration::from_millis(400));
        // 100ms * 2^3 = 800ms
        assert_eq!(delay3, Duration::from_millis(800));
    }

    #[test]
    fn test_delay_for_attempt_max_cap() {
        let config = RetryConfig::new()
            .with_base_delay(Duration::from_secs(1))
            .with_max_delay(Duration::from_secs(5))
            .with_jitter(0.0);

        // After several attempts, should hit the max delay
        let delay5 = config.delay_for_attempt(5);
        assert_eq!(delay5, Duration::from_secs(5));

        let delay10 = config.delay_for_attempt(10);
        assert_eq!(delay10, Duration::from_secs(5));
    }

    #[test]
    fn test_delay_with_jitter() {
        let config = RetryConfig::new()
            .with_base_delay(Duration::from_millis(1000))
            .with_max_delay(Duration::from_secs(10))
            .with_jitter(0.1); // 10% jitter

        // Run multiple times to account for randomness
        for _ in 0..10 {
            let delay = config.delay_for_attempt(0);
            // With 10% jitter on 1000ms, delay should be between 900ms and 1100ms
            assert!(delay >= Duration::from_millis(900));
            assert!(delay <= Duration::from_millis(1100));
        }
    }

    #[test]
    fn test_is_retryable() {
        let config = RetryConfig::default();

        assert!(config.is_retryable(408)); // Request timeout
        assert!(config.is_retryable(429)); // Too many requests
        assert!(config.is_retryable(500)); // Internal server error
        assert!(config.is_retryable(502)); // Bad gateway
        assert!(config.is_retryable(503)); // Service unavailable
        assert!(config.is_retryable(504)); // Gateway timeout

        assert!(!config.is_retryable(200)); // OK
        assert!(!config.is_retryable(201)); // Created
        assert!(!config.is_retryable(400)); // Bad request
        assert!(!config.is_retryable(401)); // Unauthorized
        assert!(!config.is_retryable(403)); // Forbidden
        assert!(!config.is_retryable(404)); // Not found
    }

    #[test]
    fn test_custom_retryable_status_codes() {
        let config = RetryConfig::new()
            .with_max_retries(3)
            .with_base_delay(Duration::from_millis(500))
            .with_max_delay(Duration::from_secs(30));

        // Test default retryable codes are set
        assert!(config.is_retryable(429));
        assert!(config.is_retryable(503));
    }
}