enact_runner/

retry.rs

//! Retry handler with exponential backoff and error classification
//!
//! Classifies errors as retryable (rate-limit, network, transient) vs
//! fatal (auth, invalid request, tool not found) and manages backoff.
//! Ported from patterns in zeroclaw and openclaw.

use crate::config::RetryConfig;
use std::time::Duration;

/// Error classification for retry decisions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ErrorKind {
    /// Rate limited by provider — always retryable
    RateLimited,
    /// Network/connection error — retryable
    NetworkError,
    /// Transient server error (5xx) — retryable
    ServerError,
    /// Authentication failure — NOT retryable
    AuthError,
    /// Invalid request (bad input, schema mismatch) — NOT retryable
    InvalidRequest,
    /// Tool not found — NOT retryable
    ToolNotFound,
    /// Context window exceeded — needs compaction, not retry
    ContextOverflow,
    /// Unknown error — retryable with caution
    Unknown,
}

impl ErrorKind {
    /// Whether this error class is retryable.
    pub fn is_retryable(&self) -> bool {
        matches!(
            self,
            ErrorKind::RateLimited
                | ErrorKind::NetworkError
                | ErrorKind::ServerError
                | ErrorKind::Unknown
        )
    }
}

/// Classifies an error string into an `ErrorKind`.
///
/// Uses heuristic keyword matching on error messages.
/// This is intentionally simple — real providers should return structured errors.
pub fn classify_error(error_msg: &str) -> ErrorKind {
    let lower = error_msg.to_lowercase();

    if lower.contains("rate limit") || lower.contains("429") || lower.contains("too many requests")
    {
        ErrorKind::RateLimited
    } else if lower.contains("connection")
        || lower.contains("timeout")
        || lower.contains("network")
        || lower.contains("dns")
    {
        ErrorKind::NetworkError
    } else if lower.contains("500")
        || lower.contains("502")
        || lower.contains("503")
        || lower.contains("internal server error")
        || lower.contains("service unavailable")
    {
        ErrorKind::ServerError
    } else if lower.contains("auth")
        || lower.contains("unauthorized")
        || lower.contains("401")
        || lower.contains("403")
        || lower.contains("forbidden")
        || lower.contains("invalid api key")
    {
        ErrorKind::AuthError
    } else if lower.contains("context")
        && (lower.contains("length") || lower.contains("window") || lower.contains("exceeded"))
    {
        ErrorKind::ContextOverflow
    } else if lower.contains("not found") && lower.contains("tool") {
        ErrorKind::ToolNotFound
    } else if lower.contains("invalid")
        || lower.contains("malformed")
        || lower.contains("400")
        || lower.contains("bad request")
    {
        ErrorKind::InvalidRequest
    } else {
        ErrorKind::Unknown
    }
}

/// Manages retry state and computes backoff delays.
pub struct RetryHandler {
    config: RetryConfig,
    attempt: u32,
}

impl RetryHandler {
    /// Create a new retry handler from config.
    pub fn new(config: RetryConfig) -> Self {
        Self { config, attempt: 0 }
    }

    /// Check if we should retry the given error.
    /// Returns `Some(delay)` if retryable, `None` if fatal or max retries exceeded.
    pub fn should_retry(&mut self, error_msg: &str) -> Option<Duration> {
        let kind = classify_error(error_msg);

        if !kind.is_retryable() {
            tracing::warn!(
                error_kind = ?kind,
                "Non-retryable error, failing immediately"
            );
            return None;
        }

        if self.attempt >= self.config.max_retries {
            tracing::warn!(
                attempt = self.attempt,
                max = self.config.max_retries,
                "Max retries exceeded"
            );
            return None;
        }

        let delay = self.next_delay();
        self.attempt += 1;

        tracing::info!(
            attempt = self.attempt,
            delay_ms = delay.as_millis() as u64,
            error_kind = ?kind,
            "Retrying after transient error"
        );

        Some(delay)
    }

    /// Compute the next backoff delay using exponential backoff.
    fn next_delay(&self) -> Duration {
        let base = self.config.initial_delay.as_millis() as f64;
        let multiplied = base * self.config.backoff_multiplier.powi(self.attempt as i32);
        let capped = multiplied.min(self.config.max_delay.as_millis() as f64);
        Duration::from_millis(capped as u64)
    }

    /// Reset retry state (call after a successful operation).
    pub fn reset(&mut self) {
        self.attempt = 0;
    }
}

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

    #[test]
    fn test_classify_rate_limit() {
        assert_eq!(
            classify_error("Rate limit exceeded"),
            ErrorKind::RateLimited
        );
        assert_eq!(
            classify_error("HTTP 429 Too Many Requests"),
            ErrorKind::RateLimited
        );
    }

    #[test]
    fn test_classify_network() {
        assert_eq!(
            classify_error("Connection refused"),
            ErrorKind::NetworkError
        );
        assert_eq!(
            classify_error("Request timeout after 30s"),
            ErrorKind::NetworkError
        );
    }

    #[test]
    fn test_classify_auth() {
        assert_eq!(classify_error("401 Unauthorized"), ErrorKind::AuthError);
        assert_eq!(
            classify_error("Invalid API key provided"),
            ErrorKind::AuthError
        );
    }

    #[test]
    fn test_classify_context_overflow() {
        assert_eq!(
            classify_error("Context length exceeded: 128000 tokens"),
            ErrorKind::ContextOverflow
        );
    }

    #[test]
    fn test_classify_unknown() {
        assert_eq!(
            classify_error("Something weird happened"),
            ErrorKind::Unknown
        );
    }

    #[test]
    fn test_retryable() {
        assert!(ErrorKind::RateLimited.is_retryable());
        assert!(ErrorKind::NetworkError.is_retryable());
        assert!(ErrorKind::ServerError.is_retryable());
        assert!(ErrorKind::Unknown.is_retryable());
        assert!(!ErrorKind::AuthError.is_retryable());
        assert!(!ErrorKind::InvalidRequest.is_retryable());
        assert!(!ErrorKind::ContextOverflow.is_retryable());
    }

    #[test]
    fn test_retry_handler_backoff() {
        let config = RetryConfig {
            max_retries: 3,
            initial_delay: Duration::from_secs(1),
            max_delay: Duration::from_secs(30),
            backoff_multiplier: 2.0,
        };
        let mut handler = RetryHandler::new(config);

        // First retry: 1s
        let delay = handler.should_retry("rate limit exceeded").unwrap();
        assert_eq!(delay, Duration::from_secs(1));

        // Second retry: 2s
        let delay = handler.should_retry("rate limit exceeded").unwrap();
        assert_eq!(delay, Duration::from_secs(2));

        // Third retry: 4s
        let delay = handler.should_retry("rate limit exceeded").unwrap();
        assert_eq!(delay, Duration::from_secs(4));

        // Fourth: exceeded max_retries=3
        assert!(handler.should_retry("rate limit exceeded").is_none());
    }

    #[test]
    fn test_retry_handler_non_retryable() {
        let mut handler = RetryHandler::new(RetryConfig::default());
        assert!(handler.should_retry("401 Unauthorized").is_none());
    }

    #[test]
    fn test_retry_handler_reset() {
        let mut handler = RetryHandler::new(RetryConfig {
            max_retries: 1,
            ..Default::default()
        });

        handler.should_retry("rate limit").unwrap();
        assert!(handler.should_retry("rate limit").is_none());

        handler.reset();
        assert!(handler.should_retry("rate limit").is_some());
    }
}