llm-wasm 0.4.2

If your cost guard needs Tokio, it cannot run where the call starts. LLM call logic with no I/O for wasm32 and native: real prices and budget ledger, retry with Retry-After, guards, routing, cache, stream decoding, JSON repair, JS bindings.
Documentation
//! Error types for the llm-wasm crate.
//!
//! All fallible operations in this crate return [`LlmWasmError`]. Every variant
//! is named, typed, and propagatable via `?`.

/// The unified error type for all llm-wasm operations.
///
/// # Variants
/// Each variant covers a distinct failure domain so callers can match precisely.
/// Marked `#[non_exhaustive]` since 0.3: a `match` needs a `_` arm, and new
/// variants can arrive in minor releases.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum LlmWasmError {
    /// A value could not be serialized or deserialized.
    #[error("Serialization error: {0}")]
    Serialization(String),

    /// A configuration field contains an invalid value.
    #[error("Invalid configuration: {field}: {reason}")]
    InvalidConfig {
        /// Which setting.
        field: String,
        /// What is wrong with it.
        reason: String,
    },

    /// A guard rejected the request.
    #[error("Request blocked by guard '{guard}': {reason}")]
    GuardBlocked {
        /// Name of the guard that blocked.
        guard: String,
        /// What is wrong with it.
        reason: String,
    },

    /// All retry attempts were consumed without success.
    #[error("Retry budget exhausted after {attempts} attempts")]
    RetryExhausted {
        /// How many attempts were made.
        attempts: u32,
    },

    /// The accumulated cost exceeded the configured budget.
    #[error("Cost budget exceeded: used ${used:.4}, limit ${limit:.4}")]
    BudgetExceeded {
        /// Total in USD the request would have reached.
        used: f64,
        /// The budget in USD.
        limit: f64,
    },

    /// A template could not be rendered.
    #[error("Template render error: {0}")]
    TemplateError(String),

    /// No routing rule matched the request and no fallback was available.
    #[error("No route matched for request")]
    NoRouteMatched,

    /// A cache operation failed.
    #[error("Cache error: {0}")]
    CacheError(String),

    /// The model is not in the built-in price table. Not worth retrying:
    /// record its cost with `CostLedger::record_usd` or price it with
    /// `ModelPricing::new`.
    #[error("Unknown model '{0}': no pricing data available")]
    UnknownModel(String),

    /// The provider reported an error (for example an `error` event inside a
    /// streamed response). Unlike [`LlmWasmError::InvalidConfig`], this is
    /// about the provider's side; `kind` says whether a retry makes sense.
    #[error("Provider error{}: {message}", kind_suffix(.kind))]
    Provider {
        /// The provider's error type or code, when it sent one
        /// (`"overloaded_error"`, `"rate_limit_exceeded"`, ...).
        kind: Option<String>,
        /// The provider's message.
        message: String,
    },
}

fn kind_suffix(kind: &Option<String>) -> String {
    kind.as_deref()
        .map(|k| format!(" ({k})"))
        .unwrap_or_default()
}

impl From<serde_json::Error> for LlmWasmError {
    fn from(e: serde_json::Error) -> Self {
        LlmWasmError::Serialization(e.to_string())
    }
}

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

    #[test]
    fn test_serialization_error_display() {
        let e = LlmWasmError::Serialization("bad json".into());
        assert!(e.to_string().contains("bad json"));
    }

    #[test]
    fn test_invalid_config_display() {
        let e = LlmWasmError::InvalidConfig {
            field: "temperature".into(),
            reason: "must be in [0,2]".into(),
        };
        let s = e.to_string();
        assert!(s.contains("temperature"));
        assert!(s.contains("must be in [0,2]"));
    }

    #[test]
    fn test_guard_blocked_display() {
        let e = LlmWasmError::GuardBlocked {
            guard: "content".into(),
            reason: "blocklist hit".into(),
        };
        let s = e.to_string();
        assert!(s.contains("content"));
        assert!(s.contains("blocklist hit"));
    }

    #[test]
    fn test_retry_exhausted_display() {
        let e = LlmWasmError::RetryExhausted { attempts: 3 };
        assert!(e.to_string().contains("3"));
    }

    #[test]
    fn test_budget_exceeded_display() {
        let e = LlmWasmError::BudgetExceeded {
            used: 1.5,
            limit: 1.0,
        };
        let s = e.to_string();
        assert!(s.contains("1.5000"));
        assert!(s.contains("1.0000"));
    }

    #[test]
    fn test_template_error_display() {
        let e = LlmWasmError::TemplateError("missing var".into());
        assert!(e.to_string().contains("missing var"));
    }

    #[test]
    fn test_no_route_matched_display() {
        let e = LlmWasmError::NoRouteMatched;
        assert!(e.to_string().contains("No route"));
    }

    #[test]
    fn test_cache_error_display() {
        let e = LlmWasmError::CacheError("expired".into());
        assert!(e.to_string().contains("expired"));
    }

    #[test]
    fn test_unknown_model_and_provider_display() {
        assert_eq!(
            LlmWasmError::UnknownModel("gpt-9".into()).to_string(),
            "Unknown model 'gpt-9': no pricing data available"
        );
        let e = LlmWasmError::Provider {
            kind: Some("overloaded_error".into()),
            message: "Overloaded".into(),
        };
        assert_eq!(
            e.to_string(),
            "Provider error (overloaded_error): Overloaded"
        );
        let e = LlmWasmError::Provider {
            kind: None,
            message: "boom".into(),
        };
        assert_eq!(e.to_string(), "Provider error: boom");
    }

    #[test]
    fn test_from_serde_json_error() {
        let json_err = serde_json::from_str::<serde_json::Value>("{bad}").unwrap_err();
        let e = LlmWasmError::from(json_err);
        assert!(matches!(e, LlmWasmError::Serialization(_)));
    }
}