models_dev/

client.rs

//! Smart HTTP client for interacting with the models.dev API with caching.

use std::time::Duration;
use std::sync::{Arc, Mutex};

use crate::error::ModelsDevError;

/// Cache metadata for tracking ETags and last modified times.
#[derive(Debug, Clone)]
struct CacheMetadata {
    etag: Option<String>,
    last_modified: Option<String>,
}

/// Smart HTTP client for the models.dev API with intelligent caching.
///
/// This client provides HTTP communication with automatic caching that only
/// updates when the API data has actually changed, using conditional requests.
#[derive(Debug, Clone)]
pub struct ModelsDevClient {
    /// The HTTP client for making API requests.
    http_client: reqwest::Client,
    /// Base URL for the models.dev API.
    api_base_url: String,
    /// Request timeout.
    timeout: Duration,
    /// Cache metadata for conditional requests.
    cache_metadata: Arc<Mutex<Option<CacheMetadata>>>,
}

impl ModelsDevClient {
    /// Create a new ModelsDevClient with default settings.
    ///
    /// Uses the default API base URL and 30-second timeout.
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a new ModelsDevClient with a custom API base URL.
    ///
    /// # Arguments
    /// * `api_base_url` - The base URL for the models.dev API
    ///
    /// # Examples
    /// ```
    /// use models_dev::ModelsDevClient;
    /// let client = ModelsDevClient::with_base_url("https://custom.api.models.dev");
    /// ```
    pub fn with_base_url(api_base_url: impl Into<String>) -> Self {
        Self {
            http_client: reqwest::Client::builder()
                .timeout(Duration::from_secs(30))
                .build()
                .expect("Failed to build HTTP client"),
            api_base_url: api_base_url.into(),
            timeout: Duration::from_secs(30),
            cache_metadata: Arc::new(Mutex::new(None)),
        }
    }

    /// Fetch providers with smart caching - only updates if API changed.
    ///
    /// This method uses conditional HTTP requests to check if the API data
    /// has changed before fetching the full response. It combines disk caching
    /// with conditional requests for optimal performance.
    ///
    /// # Returns
    /// * `Ok(ModelsDevResponse)` - The API response containing providers
    /// * `Err(ModelsDevError)` - If the request fails or the response is invalid
    ///
    /// # Examples
    /// ```
    /// # async fn example() -> Result<(), models_dev::ModelsDevError> {
    /// use models_dev::ModelsDevClient;
    /// let client = ModelsDevClient::new();
    /// let response = client.fetch_providers().await?;
    /// println!("Found {} providers", response.providers.len());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn fetch_providers(&self) -> Result<crate::types::ModelsDevResponse, ModelsDevError> {
        let url = format!("{}/api.json", self.api_base_url);

        // Try HEAD request first to check if modified
        let head_response = self.http_client.head(&url).timeout(Duration::from_secs(5)).send().await;

        if let Ok(head_resp) = head_response {
            if let Some(etag) = head_resp.headers().get("etag") {
                let cached_etag = self.get_cached_etag().await?;

                if cached_etag == Some(etag.to_str().unwrap_or("").to_string()) {
                    // Not modified, return cached data
                    return self.load_cached_response().await;
                }
            }
        }

        // Either HEAD failed or data changed, fetch full response
        let response = self.http_client.get(&url).timeout(self.timeout).send().await?;
        let api_response = self.process_response(response).await?;

        // Update cache metadata
        self.update_cache_metadata(&api_response).await?;

        Ok(api_response)
    }

    /// Process HTTP response and parse JSON.
    async fn process_response(
        &self,
        response: reqwest::Response,
    ) -> Result<crate::types::ModelsDevResponse, ModelsDevError> {
        if !response.status().is_success() {
            let error_msg = response
                .text()
                .await
                .unwrap_or_else(|_| "Unknown error".to_string());
            return Err(ModelsDevError::ApiError(error_msg));
        }

        let response_text = response.text().await?;
        let api_response: crate::types::ModelsDevResponse =
            serde_json::from_str(&response_text).map_err(ModelsDevError::JsonError)?;

        Ok(api_response)
    }

    /// Get cached ETag for conditional requests.
    async fn get_cached_etag(&self) -> Result<Option<String>, ModelsDevError> {
        let cache_meta = self.cache_metadata.lock().unwrap();
        Ok(cache_meta.as_ref().and_then(|m| m.etag.clone()))
    }

    /// Update cache metadata from response headers.
    async fn update_cache_metadata(
        &self,
        _response: &crate::types::ModelsDevResponse,
    ) -> Result<(), ModelsDevError> {
        // For now, we'll just store a placeholder ETag
        // In a real implementation, you'd extract this from HTTP headers
        // or calculate a hash of the response content
        let metadata = CacheMetadata {
            etag: Some(format!("\"{}\"", std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_secs())), // Simple timestamp-based ETag
            last_modified: None,
        };

        let mut cache_meta = self.cache_metadata.lock().unwrap();
        *cache_meta = Some(metadata);

        Ok(())
    }

    /// Load cached response from disk.
    async fn load_cached_response(&self) -> Result<crate::types::ModelsDevResponse, ModelsDevError> {
        // For now, this is a placeholder
        // In a real implementation, you'd load from disk cache
        Err(ModelsDevError::CacheError(
            "Cached response not available".to_string(),
        ))
    }

    /// Get the API base URL.
    ///
    /// # Returns
    /// The base URL used for API requests
    pub fn api_base_url(&self) -> &str {
        &self.api_base_url
    }

    /// Get the request timeout.
    ///
    /// # Returns
    /// The timeout duration for HTTP requests
    pub fn timeout(&self) -> Duration {
        self.timeout
    }

    /// Clear cache metadata.
    ///
    /// Clears the cache metadata, forcing a fresh API request on next call.
    ///
    /// # Examples
    /// ```
    /// use models_dev::ModelsDevClient;
    /// let client = ModelsDevClient::new();
    /// client.clear_cache().unwrap();
    /// ```
    pub fn clear_cache(&self) -> Result<(), ModelsDevError> {
        let mut cache_meta = self.cache_metadata.lock().unwrap();
        *cache_meta = None;
        Ok(())
    }

    /// Get cache information for debugging.
    ///
    /// Returns information about the current cache state.
    pub fn cache_info(&self) -> CacheInfo {
        let cache_meta = self.cache_metadata.lock().unwrap();
        CacheInfo {
            has_metadata: cache_meta.is_some(),
            etag: cache_meta.as_ref().and_then(|m| m.etag.clone()),
            last_modified: cache_meta.as_ref().and_then(|m| m.last_modified.clone()),
        }
    }
}

/// Cache information for debugging and monitoring.
#[derive(Debug, Clone)]
pub struct CacheInfo {
    pub has_metadata: bool,
    pub etag: Option<String>,
    pub last_modified: Option<String>,
}

impl Default for ModelsDevClient {
    fn default() -> Self {
        Self {
            http_client: reqwest::Client::builder()
                .timeout(Duration::from_secs(30))
                .build()
                .expect("Failed to build HTTP client"),
            api_base_url: "https://models.dev".to_string(),
            timeout: Duration::from_secs(30),
            cache_metadata: Arc::new(Mutex::new(None)),
        }
    }
}

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

    #[test]
    fn test_client_creation() {
        let client = ModelsDevClient::new();
        assert_eq!(client.api_base_url(), "https://models.dev");
        assert_eq!(client.timeout(), Duration::from_secs(30));
    }

    #[test]
    fn test_client_with_custom_base_url() {
        let client = ModelsDevClient::with_base_url("https://custom.api.com");
        assert_eq!(client.api_base_url(), "https://custom.api.com");
    }

    #[test]
    fn test_client_default() {
        let client = ModelsDevClient::default();
        assert_eq!(client.api_base_url(), "https://models.dev");
        assert_eq!(client.timeout(), Duration::from_secs(30));
    }

    #[test]
    fn test_client_is_send_and_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<ModelsDevClient>();
    }

    #[test]
    fn test_client_debug_format() {
        let client = ModelsDevClient::new();
        let debug_str = format!("{:?}", client);
        assert!(debug_str.contains("ModelsDevClient"));
        assert!(debug_str.contains("models.dev"));
    }

    #[test]
    fn test_cache_info() {
        let client = ModelsDevClient::new();
        let info = client.cache_info();
        assert!(!info.has_metadata);
        assert!(info.etag.is_none());
        assert!(info.last_modified.is_none());
    }

    #[test]
    fn test_clear_cache() {
        let client = ModelsDevClient::new();
        assert!(client.clear_cache().is_ok());
    }

    #[test]
    fn test_cache_metadata() {
        let metadata = CacheMetadata {
            etag: Some("\"abc123\"".to_string()),
            last_modified: Some("Wed, 21 Oct 2015 07:28:00 GMT".to_string()),
        };
        
        assert_eq!(metadata.etag, Some("\"abc123\"".to_string()));
        assert_eq!(metadata.last_modified, Some("Wed, 21 Oct 2015 07:28:00 GMT".to_string()));
    }
}