klieo_llm_common/

error.rs

//! Shared error-mapping helpers used by every LLM provider crate.
//!
//! The full HTTP-status-→-`LlmError` mapping stays in each provider
//! crate because the trailing message format embeds provider-specific
//! detail (Anthropic `type=...`, Gemini `googleStatus=...`, etc.) and
//! parity with existing wiremock tests is important.
//!
//! What's shared:
//!
//! - [`map_reqwest`] — `reqwest::Error` → [`LlmError`] dispatch. Identical
//!   across all four providers before extraction.
//! - [`retry_after_from_headers`] — RFC 7231 `Retry-After` parsing. The
//!   per-provider `map_status` helpers previously hardcoded
//!   `retry_after_secs = 1` and ignored the header — this fixes that
//!   class of bug in one place.

use klieo_core::error::LlmError;
use reqwest::header::HeaderMap;

/// Map a [`reqwest::Error`] into the right [`LlmError`] variant.
///
/// Distinguishes connect / timeout (transient) from request-shape
/// errors (permanent) and leaves status-code mapping to each
/// provider's `map_status`.
///
/// The `provider` argument is included in the rendered message so that
/// downstream `tracing` filters and human-readable errors can identify
/// which provider raised the failure.
pub fn map_reqwest(provider: &str, error: reqwest::Error) -> LlmError {
    if error.is_timeout() {
        LlmError::Timeout
    } else if error.is_connect() {
        LlmError::Network(format!("{provider}: {error}"))
    } else if error.is_decode() {
        LlmError::Decoding(format!("{provider}: {error}"))
    } else if error.is_request() || error.is_body() {
        LlmError::BadRequest(format!("{provider}: {error}"))
    } else if error.is_status() {
        LlmError::Server(format!("{provider}: {error}"))
    } else {
        LlmError::Network(format!("{provider}: {error}"))
    }
}

/// Selects which wording the [`map_status_code`] message builder produces, so a
/// provider can phrase a handled error differently from one outside the ranges
/// the ladder knows about. The builder receives this rather than the raw status
/// to keep providers from re-deriving the range arithmetic.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StatusMessageKind {
    /// The status fell in a handled error range.
    Recognised,
    /// The status fell outside every handled range.
    Unexpected,
}

/// Map an HTTP error status to the corresponding [`LlmError`], with the
/// trailing message supplied by `message`.
///
/// Centralises the status-code dispatch that every provider's `map_status`
/// otherwise duplicates. `message` is invoked at most once — only for the arms
/// whose `LlmError` variant carries a detail string — and receives a
/// [`StatusMessageKind`] so the provider can decode its own envelope and phrase
/// the message without re-deriving the status ranges.
pub fn map_status_code(
    status: reqwest::StatusCode,
    headers: &HeaderMap,
    message: impl FnOnce(StatusMessageKind) -> String,
) -> LlmError {
    match status.as_u16() {
        401 | 403 => LlmError::Unauthorized,
        408 => LlmError::Timeout,
        429 => LlmError::RateLimit {
            retry_after_secs: retry_after_from_headers(headers),
        },
        s if (500..600).contains(&s) => LlmError::Server(message(StatusMessageKind::Recognised)),
        s if (400..500).contains(&s) => {
            LlmError::BadRequest(message(StatusMessageKind::Recognised))
        }
        _ => LlmError::Server(message(StatusMessageKind::Unexpected)),
    }
}

/// Max characters of provider-supplied error detail (a response body or parsed
/// envelope message) that may be embedded into an [`LlmError`]. Provider error
/// responses can echo request content (e.g. the prompt on a validation failure),
/// so bounding the length caps how much of that reaches logs / error messages
/// while keeping enough to diagnose.
const MAX_ERROR_DETAIL_CHARS: usize = 512;

/// Appended when [`truncate_error_detail`] drops trailing content.
const TRUNCATION_MARKER: &str = "…(truncated)";

/// Bound a provider-supplied error detail to [`MAX_ERROR_DETAIL_CHARS`],
/// appending [`TRUNCATION_MARKER`] when content is dropped. Truncates on a
/// character boundary so the result is always valid UTF-8.
pub fn truncate_error_detail(detail: &str) -> String {
    if detail.chars().count() <= MAX_ERROR_DETAIL_CHARS {
        return detail.to_string();
    }
    let truncated: String = detail.chars().take(MAX_ERROR_DETAIL_CHARS).collect();
    format!("{truncated}{TRUNCATION_MARKER}")
}

const DEFAULT_RETRY_AFTER_SECS: u32 = 1;

/// Parse the `Retry-After` header into a wait duration in seconds.
///
/// Returns 1 (`DEFAULT_RETRY_AFTER_SECS`) when the header is absent,
/// malformed, or expresses an HTTP-date instead of a delta-seconds
/// integer (the latter is rare in practice for LLM APIs and a default
/// of 1 s keeps the existing pre-extraction behaviour).
pub fn retry_after_from_headers(headers: &HeaderMap) -> u32 {
    headers
        .get(reqwest::header::RETRY_AFTER)
        .and_then(|value| value.to_str().ok())
        .and_then(|raw| raw.trim().parse::<u32>().ok())
        .unwrap_or(DEFAULT_RETRY_AFTER_SECS)
}

#[cfg(test)]
mod tests {
    use super::*;
    use reqwest::header::{HeaderMap, HeaderValue};
    use reqwest::StatusCode;

    fn headers_with_retry_after(value: &str) -> HeaderMap {
        let mut headers = HeaderMap::new();
        headers.insert(
            reqwest::header::RETRY_AFTER,
            HeaderValue::from_str(value).unwrap(),
        );
        headers
    }

    #[test]
    fn missing_retry_after_defaults_to_one_second() {
        assert_eq!(retry_after_from_headers(&HeaderMap::new()), 1);
    }

    #[test]
    fn integer_retry_after_parses() {
        assert_eq!(retry_after_from_headers(&headers_with_retry_after("7")), 7);
    }

    #[test]
    fn whitespace_padded_retry_after_parses() {
        assert_eq!(
            retry_after_from_headers(&headers_with_retry_after("  42  ")),
            42
        );
    }

    #[test]
    fn http_date_retry_after_falls_back_to_default() {
        let headers = headers_with_retry_after("Wed, 21 Oct 2026 07:28:00 GMT");
        assert_eq!(retry_after_from_headers(&headers), 1);
    }

    #[test]
    fn negative_retry_after_falls_back_to_default() {
        assert_eq!(retry_after_from_headers(&headers_with_retry_after("-3")), 1);
    }

    fn detail(kind: StatusMessageKind) -> String {
        match kind {
            StatusMessageKind::Recognised => "recognised".to_string(),
            StatusMessageKind::Unexpected => "unexpected".to_string(),
        }
    }

    fn map(status: StatusCode) -> LlmError {
        map_status_code(status, &HeaderMap::new(), detail)
    }

    #[test]
    fn auth_statuses_map_to_unauthorized() {
        assert!(matches!(
            map(StatusCode::UNAUTHORIZED),
            LlmError::Unauthorized
        ));
        assert!(matches!(map(StatusCode::FORBIDDEN), LlmError::Unauthorized));
    }

    #[test]
    fn request_timeout_maps_to_timeout() {
        assert!(matches!(
            map(StatusCode::REQUEST_TIMEOUT),
            LlmError::Timeout
        ));
    }

    #[test]
    fn too_many_requests_maps_to_rate_limit_with_header() {
        let mut headers = HeaderMap::new();
        headers.insert(reqwest::header::RETRY_AFTER, HeaderValue::from_static("23"));
        match map_status_code(StatusCode::TOO_MANY_REQUESTS, &headers, detail) {
            LlmError::RateLimit { retry_after_secs } => assert_eq!(retry_after_secs, 23),
            other => panic!("expected RateLimit, got {other:?}"),
        }
    }

    #[test]
    fn server_5xx_uses_recognised_message() {
        match map(StatusCode::INTERNAL_SERVER_ERROR) {
            LlmError::Server(msg) => assert_eq!(msg, "recognised"),
            other => panic!("expected Server, got {other:?}"),
        }
    }

    #[test]
    fn client_4xx_uses_recognised_message_as_bad_request() {
        match map(StatusCode::BAD_REQUEST) {
            LlmError::BadRequest(msg) => assert_eq!(msg, "recognised"),
            other => panic!("expected BadRequest, got {other:?}"),
        }
    }

    #[test]
    fn out_of_range_status_uses_unexpected_message_as_server() {
        // 3xx is outside the 4xx/5xx ranges the ladder handles.
        match map(StatusCode::MOVED_PERMANENTLY) {
            LlmError::Server(msg) => assert_eq!(msg, "unexpected"),
            other => panic!("expected Server, got {other:?}"),
        }
    }

    #[test]
    fn short_error_detail_passes_through_unchanged() {
        assert_eq!(truncate_error_detail("brief error"), "brief error");
    }

    #[test]
    fn long_error_detail_is_truncated_with_marker() {
        let long = "x".repeat(MAX_ERROR_DETAIL_CHARS + 100);
        let out = truncate_error_detail(&long);
        assert!(out.ends_with("…(truncated)"));
        assert_eq!(
            out.chars().filter(|c| *c == 'x').count(),
            MAX_ERROR_DETAIL_CHARS
        );
    }

    #[test]
    fn truncation_respects_char_boundaries() {
        // Multibyte chars must not be split mid-codepoint (no panic, valid UTF-8).
        let long = "é".repeat(MAX_ERROR_DETAIL_CHARS + 10);
        let out = truncate_error_detail(&long);
        assert!(out.starts_with('é'));
        assert!(out.ends_with("…(truncated)"));
    }
}