aix-rs 1.0.0

Manage AI gateway profiles and launch AI coding tools with the right credentials
use crate::error::{AixError, DoctorFailureCategory};

pub(super) struct CheckFailure {
    pub(super) message: String,
    pub(super) hint: &'static str,
    pub(super) category: DoctorFailureCategory,
}

impl CheckFailure {
    pub(super) fn new(
        message: impl Into<String>,
        hint: &'static str,
        category: DoctorFailureCategory,
    ) -> Self {
        Self {
            message: message.into(),
            hint,
            category,
        }
    }
}

pub(super) fn safe_load_failure(error: &AixError) -> CheckFailure {
    match error {
        AixError::UnknownFormat { .. } => CheckFailure::new(
            "config file has an unsupported format",
            "check the config file format, syntax, and read permissions",
            DoctorFailureCategory::Config,
        ),
        _ => CheckFailure::new(
            "config file could not be read or parsed",
            "check the config file format, syntax, and read permissions",
            DoctorFailureCategory::Config,
        ),
    }
}

pub(super) fn safe_validation_failure(error: &AixError) -> CheckFailure {
    let (message, hint) = match error {
        AixError::NoProfilesConfigured => (
            "config defines no profiles",
            "define at least one profile under [profiles]",
        ),
        AixError::UnknownDefaultProfile(_) => (
            "default_profile does not name a configured profile",
            "set default_profile to a name defined under [profiles]",
        ),
        AixError::DuplicateLabel { .. } => (
            "profile labels must be unique",
            "give every profile a distinct label",
        ),
        AixError::EmptyModelDefault { .. } => (
            "a configured model default is empty",
            "configure a non-empty model default or remove it",
        ),
        AixError::EmptyModelAliasName { .. } => (
            "a configured model alias name is empty",
            "give each model alias a non-empty name",
        ),
        AixError::EmptyModelAliasTarget { .. } => (
            "a configured model alias target is empty",
            "set each model alias to a non-empty model ID",
        ),
        AixError::InvalidEnvironmentVariableName { .. }
        | AixError::InvalidToolEnvironmentVariableName { .. } => (
            "a configured environment variable name is invalid",
            "use a valid environment variable name",
        ),
        AixError::EmptyToolName => (
            "a configured tool name is empty",
            "set a non-empty name under [tools.<name>]",
        ),
        AixError::EmptyToolCommand { .. } => (
            "a configured tool command is empty",
            "set a non-empty command for the configured tool",
        ),
        AixError::SecretMissingEnvVar { .. }
        | AixError::SecretFileRead { .. }
        | AixError::SecretCommandFailed { .. }
        | AixError::SecretCommandSpawn { .. }
        | AixError::SecretCommandEncoding { .. } => (
            "a configured dynamic profile label could not be resolved",
            "check the configured profile label source",
        ),
        _ => (
            "config failed structural validation",
            "run `aix config validate` and correct the reported configuration issue",
        ),
    };

    CheckFailure::new(message, hint, DoctorFailureCategory::Config)
}

pub(super) fn gateway_failure(error: &AixError) -> CheckFailure {
    if let Some(status) = http_status(error) {
        return match status {
            401 | 403 => CheckFailure::new(
                format!("gateway rejected authentication (HTTP {status})"),
                "verify the API key and its gateway permissions",
                DoctorFailureCategory::Authentication,
            ),
            402 => CheckFailure::new(
                "gateway rejected the request because a budget limit was reached (HTTP 402)",
                "review the key's effective remaining budget before retrying",
                DoctorFailureCategory::Budget,
            ),
            _ => CheckFailure::new(
                format!("gateway returned HTTP {status}"),
                "verify gateway availability and endpoint configuration",
                DoctorFailureCategory::Network,
            ),
        };
    }

    if is_timeout(error) {
        CheckFailure::new(
            "gateway request timed out",
            "verify gateway availability and network connectivity",
            DoctorFailureCategory::Network,
        )
    } else {
        CheckFailure::new(
            "gateway request failed",
            "verify endpoint.base_url and network access",
            DoctorFailureCategory::Network,
        )
    }
}

pub(super) fn budget_failure(error: &AixError) -> CheckFailure {
    if let Some(status) = http_status(error) {
        return match status {
            401 | 403 => CheckFailure::new(
                format!("budget information request was rejected (HTTP {status})"),
                "verify that the API key can read its own budget information",
                DoctorFailureCategory::Authentication,
            ),
            402 => CheckFailure::new(
                "GET /v1/key/info was rejected because a budget limit was reached (HTTP 402)",
                "review the key's effective remaining budget before retrying",
                DoctorFailureCategory::Budget,
            ),
            _ => CheckFailure::new(
                format!("GET /v1/key/info returned HTTP {status}"),
                "verify the gateway's native budget information endpoint",
                DoctorFailureCategory::Network,
            ),
        };
    }

    if is_timeout(error) {
        CheckFailure::new(
            "GET /v1/key/info timed out",
            "verify gateway availability and network connectivity",
            DoctorFailureCategory::Network,
        )
    } else if matches!(error, AixError::GatewayProtocolError(_)) {
        CheckFailure::new(
            "GET /v1/key/info returned malformed budget information",
            "ensure the gateway returns the documented native budget fields",
            DoctorFailureCategory::Network,
        )
    } else {
        CheckFailure::new(
            "budget information request failed",
            "verify the gateway's native budget information endpoint",
            DoctorFailureCategory::Network,
        )
    }
}

fn http_status(error: &AixError) -> Option<u16> {
    match error {
        AixError::GatewayError { status, .. } | AixError::GatewayRequestFailed { status } => {
            Some(*status)
        }
        _ => None,
    }
}

fn is_timeout(error: &AixError) -> bool {
    matches!(error, AixError::HttpError(error) if error.is_timeout())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::Duration;
    use wiremock::matchers::{method, path};
    use wiremock::{Mock, MockServer, ResponseTemplate};

    fn gateway_error(status: u16) -> AixError {
        AixError::GatewayError {
            status,
            body: "upstream-body-private-detail".to_string(),
        }
    }

    fn assert_budget_exit(failure: &CheckFailure) {
        assert!(matches!(failure.category, DoctorFailureCategory::Budget));
        let error = AixError::DoctorChecksFailed {
            category: failure.category,
        };
        assert_eq!(error.exit_code(), 6);
        assert!(!failure.message.contains("upstream-body-private-detail"));
        assert!(!failure.hint.contains("upstream-body-private-detail"));
    }

    #[test]
    fn gateway_402_is_a_safe_budget_failure_with_exit_code_six() {
        let failure = gateway_failure(&gateway_error(402));

        assert_budget_exit(&failure);
        assert_eq!(
            failure.message,
            "gateway rejected the request because a budget limit was reached (HTTP 402)"
        );
    }

    #[test]
    fn budget_endpoint_402_is_a_safe_budget_failure_with_exit_code_six() {
        let failure = budget_failure(&gateway_error(402));

        assert_budget_exit(&failure);
        assert_eq!(
            failure.message,
            "GET /v1/key/info was rejected because a budget limit was reached (HTTP 402)"
        );
    }

    #[test]
    fn gateway_and_budget_endpoint_keep_auth_network_and_protocol_classes() {
        assert!(matches!(
            gateway_failure(&gateway_error(403)).category,
            DoctorFailureCategory::Authentication
        ));
        assert!(matches!(
            budget_failure(&gateway_error(403)).category,
            DoctorFailureCategory::Authentication
        ));
        assert!(matches!(
            gateway_failure(&gateway_error(503)).category,
            DoctorFailureCategory::Network
        ));

        let malformed = budget_failure(&AixError::GatewayProtocolError(
            "gateway returned malformed native budget information",
        ));
        assert!(matches!(malformed.category, DoctorFailureCategory::Network));
        assert!(malformed.message.contains("malformed budget information"));
    }

    #[tokio::test]
    async fn gateway_timeout_has_a_safe_network_diagnostic() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/slow"))
            .respond_with(ResponseTemplate::new(200).set_delay(Duration::from_millis(500)))
            .mount(&server)
            .await;

        let error = reqwest::Client::builder()
            .timeout(Duration::from_millis(50))
            .build()
            .unwrap()
            .get(format!("{}/slow", server.uri()))
            .send()
            .await
            .unwrap_err();
        let failure = gateway_failure(&AixError::HttpError(error));

        assert_eq!(failure.message, "gateway request timed out");
        assert_eq!(
            failure.hint,
            "verify gateway availability and network connectivity"
        );
        assert!(matches!(failure.category, DoctorFailureCategory::Network));
    }
}