rstructor 0.6.0

use serde::{Deserialize, Serialize};
use std::{fmt, time::Duration};
use thiserror::Error;

use crate::ResponseMetadata;

/// Classification of API errors for better handling and retry logic.
///
/// This enum categorizes HTTP errors from LLM providers into actionable types,
/// making it easier to determine appropriate responses (retry, fix config, wait, etc.).
///
/// # Example
///
/// ```
/// use rstructor::{RStructorError, ApiErrorKind};
///
/// fn handle_api_error(err: &RStructorError) {
///     if let Some(kind) = err.api_error_kind() {
///         match kind {
///             ApiErrorKind::RateLimited { retry_after } => {
///                 println!("Rate limited! Wait {:?} and retry", retry_after);
///             }
///             ApiErrorKind::AuthenticationFailed => {
///                 println!("Check your API key");
///             }
///             ApiErrorKind::InvalidModel { model, suggestion } => {
///                 println!("Model '{}' not found", model);
///                 if let Some(s) = suggestion {
///                     println!("Try: {}", s);
///                 }
///             }
///             _ if err.is_retryable() => {
///                 println!("Transient error, will retry");
///             }
///             _ => {
///                 println!("Unrecoverable error");
///             }
///         }
///     }
/// }
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ApiErrorKind {
    /// Rate limit exceeded (HTTP 429)
    ///
    /// The API is rate limiting requests. Wait for the specified duration before retrying.
    RateLimited {
        /// How long to wait before retrying (if provided by the API)
        retry_after: Option<Duration>,
    },

    /// Invalid or unknown model (HTTP 404 with model context)
    ///
    /// The requested model does not exist or is not accessible.
    InvalidModel {
        /// The model name that was not found
        model: String,
        /// A suggested alternative model, if available
        suggestion: Option<String>,
    },

    /// Service temporarily unavailable (HTTP 503)
    ///
    /// The API service is temporarily down. This is usually transient.
    ServiceUnavailable,

    /// Gateway/proxy error (HTTP 520-524, Cloudflare errors)
    ///
    /// An error occurred at the gateway level. Usually transient.
    GatewayError {
        /// The specific HTTP status code
        code: u16,
    },

    /// Authentication failed (HTTP 401)
    ///
    /// The API key is invalid, expired, or missing.
    AuthenticationFailed,

    /// Permission denied (HTTP 403)
    ///
    /// The API key doesn't have permission for this operation or model.
    PermissionDenied,

    /// Request too large (HTTP 413)
    ///
    /// The request payload (usually the prompt) is too large.
    RequestTooLarge,

    /// Invalid request (HTTP 400)
    ///
    /// The request was malformed or contained invalid parameters.
    BadRequest {
        /// Details about what was invalid
        details: String,
    },

    /// Server error (HTTP 500, 502)
    ///
    /// An internal server error occurred. May be transient.
    ServerError {
        /// The specific HTTP status code
        code: u16,
    },

    /// Generic/unclassified API error
    Other {
        /// The HTTP status code
        code: u16,
        /// The error message from the API
        message: String,
    },

    /// Unexpected response format from API
    ///
    /// The API returned a successful HTTP status but the response content
    /// was missing expected fields (e.g., empty choices array, no content).
    UnexpectedResponse {
        /// Description of what was expected vs received
        details: String,
    },
}

/// Machine-readable classification for integrity failures in a streamed response.
///
/// Streaming methods can yield successful items before discovering that the
/// provider's remaining response is malformed or truncated. Callers should stop
/// consuming the stream when a [`RStructorError::StreamingError`] is yielded and
/// decide whether to retain or roll back any earlier items.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum StreamErrorKind {
    /// An SSE event contained bytes that were not valid UTF-8.
    InvalidEventEncoding,
    /// An SSE `data:` payload was not valid JSON.
    InvalidEventJson,
    /// A recognized provider event had an invalid shape.
    InvalidProviderEvent,
    /// The provider sent an explicit error inside an otherwise successful stream.
    ProviderStreamError,
    /// HTTP EOF arrived before the provider's required terminal event.
    IncompleteEventStream,
    /// A streamed array element was not valid JSON.
    InvalidArrayElement {
        /// Zero-based index of the malformed element.
        index: usize,
    },
    /// The structured response never contained the expected array.
    MissingArray,
    /// The response ended before the streamed array was closed.
    IncompleteArray {
        /// Zero-based index of the element that would have been yielded next.
        next_index: usize,
    },
    /// The JSON surrounding a complete streamed array was malformed.
    InvalidArrayEnvelope,
    /// The array closed, but its surrounding JSON object did not.
    IncompleteArrayEnvelope,
}

impl fmt::Display for StreamErrorKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::InvalidEventEncoding => f.write_str("invalid SSE event encoding"),
            Self::InvalidEventJson => f.write_str("invalid SSE event JSON"),
            Self::InvalidProviderEvent => f.write_str("invalid provider stream event"),
            Self::ProviderStreamError => f.write_str("provider stream error"),
            Self::IncompleteEventStream => {
                f.write_str("incomplete stream without a provider terminal event")
            }
            Self::InvalidArrayElement { index } => {
                write!(f, "invalid streamed array element at index {index}")
            }
            Self::MissingArray => f.write_str("missing streamed array"),
            Self::IncompleteArray { next_index } => {
                write!(
                    f,
                    "incomplete streamed array before element index {next_index}"
                )
            }
            Self::InvalidArrayEnvelope => f.write_str("invalid streamed array envelope"),
            Self::IncompleteArrayEnvelope => f.write_str("incomplete streamed array envelope"),
        }
    }
}

impl ApiErrorKind {
    /// Returns whether this error is potentially retryable.
    ///
    /// Retryable errors are transient issues that may succeed on a subsequent attempt.
    ///
    /// # Example
    ///
    /// ```
    /// use rstructor::ApiErrorKind;
    /// use std::time::Duration;
    ///
    /// let rate_limited = ApiErrorKind::RateLimited { retry_after: Some(Duration::from_secs(5)) };
    /// assert!(rate_limited.is_retryable());
    ///
    /// let auth_failed = ApiErrorKind::AuthenticationFailed;
    /// assert!(!auth_failed.is_retryable());
    /// ```
    pub fn is_retryable(&self) -> bool {
        matches!(
            self,
            ApiErrorKind::RateLimited { .. }
                | ApiErrorKind::ServiceUnavailable
                | ApiErrorKind::GatewayError { .. }
                | ApiErrorKind::ServerError { .. }
        )
    }

    /// Returns the suggested wait duration for retryable errors.
    ///
    /// For rate-limited errors, returns the `retry_after` duration if available.
    /// For other retryable errors, returns a sensible default.
    pub fn retry_delay(&self) -> Option<Duration> {
        match self {
            ApiErrorKind::RateLimited { retry_after } => {
                Some(retry_after.unwrap_or(Duration::from_secs(5)))
            }
            ApiErrorKind::ServiceUnavailable => Some(Duration::from_secs(2)),
            ApiErrorKind::GatewayError { .. } => Some(Duration::from_secs(1)),
            ApiErrorKind::ServerError { .. } => Some(Duration::from_secs(2)),
            _ => None,
        }
    }

    /// Returns a user-friendly message describing the error and suggested action.
    pub fn user_message(&self, provider_name: &str) -> String {
        match self {
            ApiErrorKind::RateLimited { retry_after } => {
                if let Some(duration) = retry_after {
                    format!(
                        "Rate limit exceeded. Please wait {} seconds and try again.",
                        duration.as_secs()
                    )
                } else {
                    "Rate limit exceeded. Please wait a moment and try again.".to_string()
                }
            }
            ApiErrorKind::InvalidModel { model, suggestion } => {
                let mut msg = format!("Model '{}' not found.", model);
                if let Some(s) = suggestion {
                    msg.push_str(&format!(" Try using '{}'.", s));
                }
                msg
            }
            ApiErrorKind::ServiceUnavailable => {
                format!(
                    "{} service is temporarily unavailable. Please try again.",
                    provider_name
                )
            }
            ApiErrorKind::GatewayError { code } => {
                format!(
                    "Gateway error ({}). This is usually transient - please retry.",
                    code
                )
            }
            ApiErrorKind::AuthenticationFailed => {
                format!(
                    "Authentication failed. Check your {}_API_KEY environment variable.",
                    provider_name.to_uppercase()
                )
            }
            ApiErrorKind::PermissionDenied => {
                "Permission denied. Your API key may not have access to this model or feature."
                    .to_string()
            }
            ApiErrorKind::RequestTooLarge => {
                "Request too large. Try reducing the prompt length or max_tokens.".to_string()
            }
            ApiErrorKind::BadRequest { details } => {
                format!("Invalid request: {}", details)
            }
            ApiErrorKind::ServerError { code } => {
                format!(
                    "{} server error ({}). This may be transient - please retry.",
                    provider_name, code
                )
            }
            ApiErrorKind::Other { code, message } => {
                format!("{} API error ({}): {}", provider_name, code, message)
            }
            ApiErrorKind::UnexpectedResponse { details } => {
                format!(
                    "{} returned an unexpected response: {}",
                    provider_name, details
                )
            }
        }
    }
}

impl std::fmt::Display for ApiErrorKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ApiErrorKind::RateLimited { retry_after } => {
                write!(f, "Rate limited")?;
                if let Some(d) = retry_after {
                    write!(f, " (retry after {}s)", d.as_secs())?;
                }
                Ok(())
            }
            ApiErrorKind::InvalidModel { model, .. } => write!(f, "Invalid model: {}", model),
            ApiErrorKind::ServiceUnavailable => write!(f, "Service unavailable"),
            ApiErrorKind::GatewayError { code } => write!(f, "Gateway error ({})", code),
            ApiErrorKind::AuthenticationFailed => write!(f, "Authentication failed"),
            ApiErrorKind::PermissionDenied => write!(f, "Permission denied"),
            ApiErrorKind::RequestTooLarge => write!(f, "Request too large"),
            ApiErrorKind::BadRequest { details } => write!(f, "Bad request: {}", details),
            ApiErrorKind::ServerError { code } => write!(f, "Server error ({})", code),
            ApiErrorKind::Other { code, message } => write!(f, "API error ({}): {}", code, message),
            ApiErrorKind::UnexpectedResponse { details } => {
                write!(f, "Unexpected response: {}", details)
            }
        }
    }
}

/// Error types for the rstructor library.
///
/// This enum defines the various error types that can occur within the rstructor library.
/// Each variant represents a different category of error and includes context about what went wrong.
///
/// # Examples
///
/// Creating and handling errors:
///
/// ```
/// use rstructor::{RStructorError, Result};
///
/// // Function that might return an error
/// fn validate_age(age: i32) -> Result<()> {
///     if age < 0 {
///         return Err(RStructorError::ValidationError("Age cannot be negative".into()));
///     }
///     if age > 150 {
///         return Err(RStructorError::ValidationError("Age is unrealistically high".into()));
///     }
///     Ok(())
/// }
///
/// // Using the function and handling errors
/// let result = validate_age(200);
/// match result {
///     Ok(()) => println!("Age is valid"),
///     Err(RStructorError::ValidationError(msg)) => println!("Invalid age: {}", msg),
///     Err(e) => println!("Unexpected error: {}", e),
/// }
/// ```
#[derive(Error, Debug)]
pub enum RStructorError {
    /// Error interacting with the LLM API (with rich error classification)
    #[error("{}", .kind.user_message(.provider))]
    ApiError {
        /// The provider that returned the error (e.g., "OpenAI", "Anthropic")
        provider: String,
        /// The classified error kind
        kind: ApiErrorKind,
        /// HTTP response diagnostics, when the provider returned a response.
        response: Option<Box<ResponseMetadata>>,
    },

    /// Error validating data against schema or business rules
    #[error("Validation error: {0}")]
    ValidationError(String),

    /// Error related to JSON Schema generation or processing
    #[error("Schema error: {0}")]
    SchemaError(String),

    /// A provider cannot represent part of the requested schema without changing
    /// which values the Rust type accepts.
    ///
    /// Dynamic map keys are one example: OpenAI strict structured outputs close
    /// every object, so rstructor reports the affected field before making an
    /// HTTP request.
    ///
    /// ```no_run
    /// use std::collections::HashMap;
    ///
    /// use rstructor::{Instructor, LLMClient, OpenAIClient, RStructorError};
    /// use serde::{Deserialize, Serialize};
    ///
    /// #[derive(Instructor, Serialize, Deserialize, Debug)]
    /// struct Portfolio {
    ///     positions: HashMap<String, i64>,
    /// }
    ///
    /// # async fn example() -> rstructor::Result<()> {
    /// let client = OpenAIClient::new("api-key")?;
    /// let error = client
    ///     .materialize::<Portfolio>("AAPL: 1,000 shares")
    ///     .await
    ///     .unwrap_err();
    ///
    /// assert!(matches!(
    ///     error,
    ///     RStructorError::SchemaCompatibilityError { provider, path, .. }
    ///         if provider.as_ref() == "OpenAI"
    ///             && path.as_ref() == "$.properties.positions"
    /// ));
    /// # Ok(())
    /// # }
    /// ```
    #[error("{provider} cannot represent {context} at {path}: {message}")]
    SchemaCompatibilityError {
        /// Provider whose structured-output dialect rejected the schema.
        provider: Box<str>,
        /// Human-readable schema context, such as a structured output or tool arguments.
        context: Box<str>,
        /// JSONPath-style location of the incompatible schema node.
        path: Box<str>,
        /// Explanation of the unsupported construct and available remediation.
        message: Box<str>,
    },

    /// Error serializing or deserializing data
    #[error("Serialization error: {0}")]
    SerializationError(String),

    /// Structured model output could not be decoded into the requested Rust type.
    #[error("Failed to decode structured output at {path}: {message}")]
    OutputDecodeError {
        /// JSONPath-style location of the first value that failed to decode.
        path: String,
        /// Serde's explanation of the type or JSON syntax mismatch.
        message: String,
    },

    /// Tool-call arguments could not be decoded into the tool's argument type.
    #[error("Failed to decode tool arguments at {path}: {message}")]
    ToolArgumentDecodeError {
        /// JSONPath-style location of the first argument that failed to decode.
        path: String,
        /// Serde's explanation of the type or JSON syntax mismatch.
        message: String,
    },

    /// A streamed response was malformed or ended before its framing completed.
    ///
    /// This error is deliberately non-retryable: a stream may already have
    /// yielded text or validated objects, so automatically replaying it could
    /// duplicate caller-visible side effects.
    #[error("Streaming error ({kind}): {message}")]
    StreamingError {
        /// Machine-readable failure category.
        kind: StreamErrorKind,
        /// Safe diagnostic context. Provider response contents are not included.
        message: Box<str>,
    },

    /// Operation timed out
    #[error("Timeout error")]
    Timeout,

    /// A requested capability is not supported by this client/provider
    /// (for example, passing media to a backend that has no media support).
    #[error("Unsupported operation: {0}")]
    Unsupported(String),

    /// HTTP client error (from reqwest)
    #[cfg(feature = "_client")]
    #[error("HTTP client error: {0}")]
    HttpError(#[from] reqwest::Error),

    /// JSON parsing error (from serde_json)
    #[error("JSON error: {0}")]
    JsonError(#[from] serde_json::Error),
}

impl RStructorError {
    /// Create a new API error with rich classification.
    ///
    /// # Arguments
    ///
    /// * `provider` - The LLM provider name (e.g., "OpenAI", "Anthropic")
    /// * `kind` - The classified error kind
    pub fn api_error(provider: impl Into<String>, kind: ApiErrorKind) -> Self {
        RStructorError::ApiError {
            provider: provider.into(),
            kind,
            response: None,
        }
    }

    /// Create a classified API error with the provider's HTTP response metadata.
    pub fn api_error_with_response(
        provider: impl Into<String>,
        kind: ApiErrorKind,
        response: ResponseMetadata,
    ) -> Self {
        RStructorError::ApiError {
            provider: provider.into(),
            kind,
            response: Some(Box::new(response)),
        }
    }

    /// Returns the API error kind if this is an API error.
    ///
    /// # Example
    ///
    /// ```
    /// use rstructor::{RStructorError, ApiErrorKind};
    ///
    /// let err = RStructorError::api_error("OpenAI", ApiErrorKind::AuthenticationFailed);
    /// assert!(matches!(err.api_error_kind(), Some(ApiErrorKind::AuthenticationFailed)));
    /// ```
    pub fn api_error_kind(&self) -> Option<&ApiErrorKind> {
        match self {
            RStructorError::ApiError { kind, .. } => Some(kind),
            _ => None,
        }
    }

    /// Return HTTP response metadata when this error came from a provider response.
    #[must_use]
    pub fn response_metadata(&self) -> Option<&ResponseMetadata> {
        match self {
            RStructorError::ApiError { response, .. } => response.as_deref(),
            _ => None,
        }
    }

    /// Return the provider's exact HTTP status code, when available.
    #[must_use]
    pub fn status_code(&self) -> Option<u16> {
        self.response_metadata().map(|response| response.status)
    }

    /// Return a preferred provider request ID, when available.
    #[must_use]
    pub fn request_id(&self) -> Option<&str> {
        self.response_metadata()
            .and_then(ResponseMetadata::request_id)
    }

    /// Returns whether this error is potentially retryable.
    ///
    /// Retryable errors include:
    /// - Rate limiting (429)
    /// - Service unavailable (503)
    /// - Gateway errors (520-524)
    /// - Server errors (500, 502)
    /// - Timeout errors
    /// - Transient connection failures (connection refused/reset, DNS errors,
    ///   connect timeouts) — these are just as transient as the 5xx errors above
    ///
    /// HTTP errors that occur after a response is received (e.g. body or decode
    /// errors) remain non-retryable.
    ///
    /// # Example
    ///
    /// ```
    /// use rstructor::{RStructorError, ApiErrorKind};
    /// use std::time::Duration;
    ///
    /// let rate_limited = RStructorError::api_error(
    ///     "OpenAI",
    ///     ApiErrorKind::RateLimited { retry_after: Some(Duration::from_secs(5)) }
    /// );
    /// assert!(rate_limited.is_retryable());
    ///
    /// let auth_error = RStructorError::api_error("OpenAI", ApiErrorKind::AuthenticationFailed);
    /// assert!(!auth_error.is_retryable());
    /// ```
    pub fn is_retryable(&self) -> bool {
        match self {
            RStructorError::ApiError { kind, .. } => kind.is_retryable(),
            RStructorError::Timeout => true,
            #[cfg(feature = "_client")]
            RStructorError::HttpError(e) => e.is_connect() || e.is_timeout(),
            _ => false,
        }
    }

    /// Returns the suggested retry delay for retryable errors.
    ///
    /// Returns `None` for non-retryable errors.
    pub fn retry_delay(&self) -> Option<Duration> {
        match self {
            RStructorError::ApiError { kind, .. } => kind.retry_delay(),
            RStructorError::Timeout => Some(Duration::from_secs(1)),
            #[cfg(feature = "_client")]
            RStructorError::HttpError(e) if e.is_connect() || e.is_timeout() => {
                Some(Duration::from_secs(1))
            }
            _ => None,
        }
    }
}

// Manual implementation of PartialEq for RStructorError
// Note: HttpError and JsonError variants are considered unequal
// because reqwest::Error and serde_json::Error don't implement PartialEq
impl PartialEq for RStructorError {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (
                Self::ApiError {
                    provider: p1,
                    kind: k1,
                    response: r1,
                },
                Self::ApiError {
                    provider: p2,
                    kind: k2,
                    response: r2,
                },
            ) => p1 == p2 && k1 == k2 && r1 == r2,
            (Self::ValidationError(a), Self::ValidationError(b)) => a == b,
            (Self::SchemaError(a), Self::SchemaError(b)) => a == b,
            (
                Self::SchemaCompatibilityError {
                    provider: provider_a,
                    context: context_a,
                    path: path_a,
                    message: message_a,
                },
                Self::SchemaCompatibilityError {
                    provider: provider_b,
                    context: context_b,
                    path: path_b,
                    message: message_b,
                },
            ) => {
                provider_a == provider_b
                    && context_a == context_b
                    && path_a == path_b
                    && message_a == message_b
            }
            (Self::SerializationError(a), Self::SerializationError(b)) => a == b,
            (
                Self::OutputDecodeError {
                    path: path_a,
                    message: message_a,
                },
                Self::OutputDecodeError {
                    path: path_b,
                    message: message_b,
                },
            ) => path_a == path_b && message_a == message_b,
            (
                Self::ToolArgumentDecodeError {
                    path: path_a,
                    message: message_a,
                },
                Self::ToolArgumentDecodeError {
                    path: path_b,
                    message: message_b,
                },
            ) => path_a == path_b && message_a == message_b,
            (
                Self::StreamingError {
                    kind: kind_a,
                    message: message_a,
                },
                Self::StreamingError {
                    kind: kind_b,
                    message: message_b,
                },
            ) => kind_a == kind_b && message_a == message_b,
            (Self::Unsupported(a), Self::Unsupported(b)) => a == b,
            (Self::Timeout, Self::Timeout) => true,
            // HttpError and JsonError don't implement PartialEq, so we always return false
            #[cfg(feature = "_client")]
            (Self::HttpError(_), Self::HttpError(_)) => false,
            (Self::JsonError(_), Self::JsonError(_)) => false,
            _ => false,
        }
    }
}

/// A specialized Result type for rstructor operations.
///
/// This type is used throughout the rstructor library to return either
/// a success value of type T or an RStructorError.
///
/// # Examples
///
/// Using Result type in functions:
///
/// ```
/// use rstructor::{RStructorError, Result};
///
/// fn parse_json_data(data: &str) -> Result<serde_json::Value> {
///     match serde_json::from_str(data) {
///         Ok(value) => Ok(value),
///         Err(e) => Err(RStructorError::JsonError(e)),
///     }
/// }
///
/// // Using the ? operator with Result
/// fn process_data(input: &str) -> Result<String> {
///     let json = parse_json_data(input)?;
///     // Process the JSON...
///     Ok("Processed successfully".to_string())
/// }
/// ```
pub type Result<T> = std::result::Result<T, RStructorError>;