loa_core/

http.rs

// ! Shared HTTP client with smart retry middleware
//!
//! Provides a centralized HTTP client configuration with:
//! - Automatic retry logic for transient errors
//! - Respect for server-provided Retry-After headers (429 rate limits)
//! - Exponential backoff for other errors
//! - Configurable timeouts
//!
//! This client can be used across the entire agent for consistent HTTP behavior.

use async_trait::async_trait;
use reqwest::{Request, Response, StatusCode};
use reqwest_chain::Chainer;
use reqwest_middleware::{ClientBuilder, Error};
use std::time::Duration;

/// Smart retry middleware that handles both Retry-After headers and exponential backoff
///
/// Behavior:
/// - **429 Too Many Requests**: Reads `retry-after` header and sleeps for that duration before retrying
/// - **5xx Server Errors**: Applies exponential backoff before retrying
/// - **Network Errors**: Applies exponential backoff before retrying
/// - **Other errors**: Returns immediately without retry
struct SmartRetryChainer {
    max_retries: u32,
    base_delay: Duration,
    max_delay: Duration,
}

impl SmartRetryChainer {
    fn new(max_retries: u32, base_delay: Duration, max_delay: Duration) -> Self {
        Self {
            max_retries,
            base_delay,
            max_delay,
        }
    }

    /// Parse Retry-After header value (supports both delay-seconds and HTTP-date)
    fn parse_retry_after(&self, value: &str) -> Option<Duration> {
        // Try parsing as seconds (most common format)
        if let Ok(seconds) = value.parse::<u64>() {
            return Some(Duration::from_secs(seconds));
        }

        // TODO: Add HTTP-date parsing if needed (less common for rate limiting)
        None
    }

    /// Calculate exponential backoff delay with cap
    fn calculate_backoff(&self, attempt: u32) -> Duration {
        let delay = self.base_delay * 2_u32.saturating_pow(attempt);
        delay.min(self.max_delay)
    }
}

/// State tracked across retry attempts
#[derive(Default)]
struct RetryState {
    attempt: u32,
}

#[async_trait]
impl Chainer for SmartRetryChainer {
    type State = RetryState;

    async fn chain(
        &self,
        result: Result<Response, Error>,
        state: &mut Self::State,
        _request: &mut Request,
    ) -> Result<Option<Response>, Error> {
        // Extract response or propagate network error
        let response = match result {
            Ok(resp) => resp,
            Err(err) => {
                // Network error - retry with exponential backoff if under retry limit
                if state.attempt >= self.max_retries {
                    return Err(err);
                }

                let delay = self.calculate_backoff(state.attempt);
                tracing::debug!(
                    "Network error on attempt {}/{}, retrying after {:?}",
                    state.attempt + 1,
                    self.max_retries,
                    delay
                );

                tokio::time::sleep(delay).await;
                state.attempt += 1;

                // Signal retry
                return Ok(None);
            }
        };

        let status = response.status();

        // Determine if we should retry based on status code
        let should_retry = match status {
            StatusCode::TOO_MANY_REQUESTS => true, // 429
            s if s.is_server_error() => true,      // 5xx
            StatusCode::REQUEST_TIMEOUT => true,   // 408
            _ => false,
        };

        // Accept response if no retry needed or max retries exceeded
        if !should_retry || state.attempt >= self.max_retries {
            return Ok(Some(response));
        }

        // Calculate retry delay
        let delay = if status == StatusCode::TOO_MANY_REQUESTS {
            // Try to read Retry-After header for 429
            if let Some(retry_after_header) = response.headers().get("retry-after") {
                if let Ok(value) = retry_after_header.to_str() {
                    if let Some(parsed_delay) = self.parse_retry_after(value) {
                        tracing::debug!(
                            "429 rate limited on attempt {}/{}, respecting Retry-After: {:?}",
                            state.attempt + 1,
                            self.max_retries,
                            parsed_delay
                        );
                        parsed_delay
                    } else {
                        // Failed to parse Retry-After, use exponential backoff
                        let backoff = self.calculate_backoff(state.attempt);
                        tracing::debug!(
                            "429 rate limited on attempt {}/{}, failed to parse Retry-After, using backoff: {:?}",
                            state.attempt + 1,
                            self.max_retries,
                            backoff
                        );
                        backoff
                    }
                } else {
                    // Retry-After header invalid UTF-8, use exponential backoff
                    self.calculate_backoff(state.attempt)
                }
            } else {
                // No Retry-After header, use exponential backoff
                let backoff = self.calculate_backoff(state.attempt);
                tracing::debug!(
                    "429 rate limited on attempt {}/{}, no Retry-After header, using backoff: {:?}",
                    state.attempt + 1,
                    self.max_retries,
                    backoff
                );
                backoff
            }
        } else {
            // Server error or timeout - use exponential backoff
            let backoff = self.calculate_backoff(state.attempt);
            tracing::debug!(
                "Error {} on attempt {}/{}, retrying after {:?}",
                status,
                state.attempt + 1,
                self.max_retries,
                backoff
            );
            backoff
        };

        // Sleep before retry
        tokio::time::sleep(delay).await;
        state.attempt += 1;

        // Signal retry (return None)
        Ok(None)
    }
}

/// Build a configured HTTP client with smart retry middleware
///
/// The client includes:
/// - **Smart Retry Logic**: Respects server `Retry-After` headers for 429 responses
/// - **Exponential Backoff**: For server errors (5xx) and network issues
/// - **Timeout**: 10 second request timeout
/// - **Max Retries**: 5 attempts
///
/// # Example
///
/// ```rust
/// use elo::http::build_http_client;
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     let client = build_http_client();
///     let response = client.get("https://api.example.com/status").send().await?;
///     Ok(())
/// }
/// ```
pub fn build_http_client() -> reqwest_middleware::ClientWithMiddleware {
    // Base reqwest client with timeout
    let reqwest_client = reqwest::Client::builder()
        .timeout(Duration::from_secs(10))
        .build()
        .expect("Failed to build reqwest client");

    // Create smart retry chainer
    let retry_chainer = SmartRetryChainer::new(
        5,                          // max_retries
        Duration::from_millis(500), // base_delay
        Duration::from_secs(30),    // max_delay
    );

    // Build client with chainer middleware
    ClientBuilder::new(reqwest_client)
        .with(reqwest_chain::ChainMiddleware::new(retry_chainer))
        .build()
}