iota_sdk_graphql_client/

error.rs

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2025 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

use std::{
    num::{ParseIntError, TryFromIntError},
    string::FromUtf8Error,
};

use cynic::serde::Deserialize;
use iota_types::{
    AddressParseError, DigestParseError, TypeParseError, TypeTag, iota_names::error::IotaNamesError,
};
use reqwest::{StatusCode, Url};

use crate::faucet::FaucetError;

type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;

pub type GraphQLResult<T> = std::result::Result<T, GraphQLError>;

/// Maximum number of body bytes retained in an HTTP/decode error. Load
/// balancer and gateway pages can be hundreds of KB, so the body is truncated
/// before being stored in the error.
const MAX_ERROR_BODY_BYTES: usize = 512;

/// Render a response body as a truncated, UTF-8-lossy string suitable for
/// inclusion in an error message.
fn truncated_body(bytes: &[u8]) -> String {
    let truncated = bytes.len() > MAX_ERROR_BODY_BYTES;
    let slice = &bytes[..bytes.len().min(MAX_ERROR_BODY_BYTES)];
    let mut body = String::from_utf8_lossy(slice).into_owned();
    if truncated {
        body.push_str("… (truncated)");
    }
    body
}

/// A GraphQL error as reported by the server, with its [`ErrorExtensions`]
/// decoded.
pub type QueryError = cynic::GraphQlError<ErrorExtensions>;

/// The `extensions` object of a GraphQL error returned by the server.
#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq)]
#[serde(crate = "cynic::serde")]
#[non_exhaustive]
pub struct ErrorExtensions {
    /// Machine-readable error kind, e.g. `BAD_USER_INPUT`.
    pub code: Option<String>,
}

/// Convert an error whose extensions were not decoded; `code` is `None`.
pub(crate) fn query_error(error: cynic::GraphQlError) -> QueryError {
    QueryError::new(error.message, error.locations, error.path, None)
}

fn display_graphql_errors(errors: &[QueryError]) -> String {
    errors
        .iter()
        .map(|e| e.to_string())
        .collect::<Vec<_>>()
        .join(", ")
}

/// Errors returned by the GraphQL client.
///
/// A queried object, transaction or checkpoint that does not exist is reported
/// as `Ok(None)`, so absence never surfaces here.
///
/// A variant that wraps another error renders that error inline and also
/// exposes it through [`std::error::Error::source`], so the message is
/// self-contained and the cause stays matchable.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum GraphQLError {
    /// The request could not be sent, or the response could not be read.
    #[error("request error: {0}")]
    Request(#[from] reqwest::Error),
    /// The server answered with a non-success HTTP status.
    #[error(
        "GraphQL request to {url} failed with HTTP {status} while decoding `{target_type}`, \
         body={body:?}",
        url = .response.url,
        status = .response.status,
        target_type = .response.target_type,
        body = .response.body,
    )]
    Http { response: Box<HttpResponse> },
    /// The response body could not be parsed as JSON.
    #[error(
        "GraphQL request to {url} returned HTTP {status} but the body could not be parsed as JSON \
         while decoding `{target_type}` (body={body:?}): {source}",
        url = .response.url,
        status = .response.status,
        target_type = .response.target_type,
        body = .response.body,
    )]
    Json {
        response: Box<HttpResponse>,
        #[source]
        source: serde_json::Error,
    },
    /// The server returned errors for the query. The server sends no
    /// [`ErrorExtensions::code`] for subscription errors.
    #[error("query error: [{}]", display_graphql_errors(.0))]
    Query(Vec<QueryError>),
    /// The response carried neither data nor errors.
    #[error("empty response: the server returned neither data nor errors")]
    EmptyResponse,
    /// A response field the client needs to build its return value was empty.
    #[error("empty response field: {0}")]
    EmptyResponseField(&'static str),
    /// The server returned a variant of a GraphQL union or enum this client
    /// does not know.
    #[error("unknown {0} variant")]
    UnknownVariant(&'static str),
    /// A response value could not be deserialized into its SDK type.
    #[error("deserialization error: {0}")]
    Deserialization(#[source] BoxError),
    /// A response value or a caller-supplied string could not be parsed.
    #[error("parse error: {0}")]
    Parse(#[source] BoxError),
    /// An IOTA name could not be parsed.
    #[error("invalid name `{name}`: {source}")]
    InvalidName {
        /// The name that could not be parsed.
        name: String,
        #[source]
        source: IotaNamesError,
    },
    /// A dynamic field holds a different type than the caller asked for.
    #[error("type mismatch: expected `{expected}`, got `{actual}`")]
    TypeMismatch {
        /// The type the caller asked for.
        expected: TypeTag,
        /// The type the field actually holds.
        actual: TypeTag,
    },
    /// The caller-supplied arguments cannot be combined, or a caller-supplied
    /// value is not usable for this operation.
    #[error("invalid argument: {0}")]
    InvalidArgument(&'static str),
    /// The RPC URL scheme is not usable for subscriptions.
    #[error("unsupported RPC scheme `{0}` for subscriptions, expected http, https, ws or wss")]
    UnsupportedSubscriptionScheme(String),
    /// The RPC URL needs TLS, which this build does not have.
    #[error(
        "scheme `{0}` needs TLS: enable the `tls-ring` or `tls-aws-lc` feature, or pass your own \
         client to `new_with_reqwest_client`"
    )]
    TlsUnavailable(String),
    /// The operation did not complete within its deadline.
    #[error("timed out")]
    Timeout,
    /// A faucet request failed.
    #[error("faucet error: {0}")]
    Faucet(#[from] FaucetError),
    /// The subscription transport failed.
    #[error("subscription error: {0}")]
    Subscription(#[source] BoxError),
    /// The subscription server dropped `count` payloads before the next one
    /// because the client could not keep up. The stream continues after this
    /// error.
    #[error("subscription lagged: {count} payload(s) dropped by the server")]
    Lagged { count: u32 },
}

/// The HTTP response a [`GraphQLError::Http`] or [`GraphQLError::Json`] was
/// raised for.
#[derive(Debug)]
pub struct HttpResponse {
    url: Url,
    status: StatusCode,
    body: String,
    target_type: &'static str,
}

impl HttpResponse {
    fn new(url: Url, status: StatusCode, body: &[u8], target_type: &'static str) -> Box<Self> {
        Box::new(Self {
            url,
            status,
            body: truncated_body(body),
            target_type,
        })
    }

    /// URL the request was sent to.
    pub fn url(&self) -> &Url {
        &self.url
    }

    /// HTTP status the server answered with.
    pub fn status(&self) -> StatusCode {
        self.status
    }

    /// Truncated, UTF-8-lossy snapshot of the response body.
    pub fn body(&self) -> &str {
        &self.body
    }

    /// Name of the type the response was being decoded into. A bare status or
    /// `serde_json` error does not reveal what the client was decoding.
    pub fn target_type(&self) -> &'static str {
        self.target_type
    }
}

impl GraphQLError {
    /// Build a [`GraphQLError::Http`] from a non-success response, retaining a
    /// truncated, UTF-8-lossy snapshot of the body.
    pub(crate) fn http(
        url: Url,
        status: StatusCode,
        body: &[u8],
        target_type: &'static str,
    ) -> Self {
        Self::Http {
            response: HttpResponse::new(url, status, body, target_type),
        }
    }

    /// Build a [`GraphQLError::Json`] from a response whose body is not valid
    /// JSON, retaining a truncated, UTF-8-lossy snapshot of the body.
    pub(crate) fn json(
        url: Url,
        status: StatusCode,
        body: &[u8],
        target_type: &'static str,
        source: serde_json::Error,
    ) -> Self {
        Self::Json {
            response: HttpResponse::new(url, status, body, target_type),
            source,
        }
    }

    /// Wrap an error raised while turning a response value into its SDK type.
    pub(crate) fn deserialization<E: Into<BoxError>>(error: E) -> Self {
        Self::Deserialization(error.into())
    }

    /// Wrap a subscription transport failure.
    pub(crate) fn subscription<E: Into<BoxError>>(error: E) -> Self {
        Self::Subscription(error.into())
    }
}

impl From<iota_types::BcsError> for GraphQLError {
    fn from(error: iota_types::BcsError) -> Self {
        Self::Deserialization(error.into())
    }
}

impl From<url::ParseError> for GraphQLError {
    fn from(error: url::ParseError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<ParseIntError> for GraphQLError {
    fn from(error: ParseIntError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<AddressParseError> for GraphQLError {
    fn from(error: AddressParseError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<DigestParseError> for GraphQLError {
    fn from(error: DigestParseError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<TryFromIntError> for GraphQLError {
    fn from(error: TryFromIntError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<TypeParseError> for GraphQLError {
    fn from(error: TypeParseError) -> Self {
        Self::Parse(error.into())
    }
}

impl From<FromUtf8Error> for GraphQLError {
    fn from(error: FromUtf8Error) -> Self {
        Self::Parse(error.into())
    }
}

#[cfg(feature = "move-types")]
impl From<iota_move_types::FromObjectError> for GraphQLError {
    fn from(error: iota_move_types::FromObjectError) -> Self {
        Self::Deserialization(error.into())
    }
}

#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
    use super::*;

    #[test]
    fn http_error_surfaces_status_body_and_decode_target() {
        let url = Url::parse("https://graphql.devnet.iota.cafe").unwrap();
        let error = GraphQLError::http(
            url,
            StatusCode::TOO_MANY_REQUESTS,
            b"Too Many Requests",
            "my_crate::MyResponse",
        );
        assert_eq!(
            error.to_string(),
            "GraphQL request to https://graphql.devnet.iota.cafe/ failed with HTTP 429 Too Many \
             Requests while decoding `my_crate::MyResponse`, body=\"Too Many Requests\""
        );
        // The status stays inspectable instead of only being rendered.
        assert!(
            matches!(error, GraphQLError::Http { response } if response.status == StatusCode::TOO_MANY_REQUESTS)
        );
    }

    #[test]
    fn json_error_surfaces_status_body_and_source() {
        use std::error::Error as _;

        let url = Url::parse("https://graphql.devnet.iota.cafe").unwrap();
        let serde_error = serde_json::from_slice::<serde_json::Value>(b"not json").unwrap_err();
        let error = GraphQLError::json(
            url,
            StatusCode::OK,
            b"not json",
            "my_crate::MyResponse",
            serde_error,
        );
        // The message is self-contained, and the cause stays matchable.
        assert_eq!(
            error.to_string(),
            "GraphQL request to https://graphql.devnet.iota.cafe/ returned HTTP 200 OK but the \
             body could not be parsed as JSON while decoding `my_crate::MyResponse` (body=\"not \
             json\"): expected ident at line 1 column 2"
        );
        assert_eq!(
            error.source().expect("expected a cause").to_string(),
            "expected ident at line 1 column 2"
        );
    }

    /// Rendering the message inline and exposing the same error through
    /// `source` means a cause-chain formatter (`anyhow`/`eyre` `{:#}`, `{:?}`)
    /// prints the wrapped message twice. That is the accepted cost of a
    /// self-contained `Display`: a consumer that reads only the top frame,
    /// such as the FFI layer, still sees the whole failure.
    #[test]
    fn chain_formatters_repeat_the_wrapped_message() {
        use std::error::Error as _;

        let error = GraphQLError::from(iota_types::BcsError::new(
            bcs::from_bytes::<u64>(&[]).unwrap_err(),
        ));

        assert_eq!(
            error.to_string(),
            "deserialization error: unexpected end of input"
        );

        let mut chain = vec![error.to_string()];
        let mut next = error.source();
        while let Some(error) = next {
            chain.push(error.to_string());
            next = error.source();
        }

        assert_eq!(
            chain,
            [
                "deserialization error: unexpected end of input",
                "unexpected end of input",
            ]
        );
    }

    #[test]
    fn body_is_truncated() {
        let body = vec![b'a'; MAX_ERROR_BODY_BYTES + 100];
        let rendered = truncated_body(&body);
        assert!(rendered.contains("… (truncated)"));
        assert_eq!(rendered.len(), MAX_ERROR_BODY_BYTES + "… (truncated)".len());
    }
}