lemon_bugsnag_rs 0.1.2

use super::builder::error::BuilderError;
use serde_json::Error as JsonError;
use std::{error::Error as StdError, fmt::Display};

#[cfg_attr(docsrs, doc(cfg(feature = "reqwest")))]
#[cfg(feature = "reqwest")]
use reqwest::Error as ReqwestError;

/// Distinguishes between different types of errors carried by the [Error] struct.
/// For a non-exhaustive example, see [BuilderError].
///
/// # Example
/// ```
/// // This example requires the sync feature.
///
/// use lemon_bugsnag_rs::common::builder::client_builder::ClientBuilder;
/// use lemon_bugsnag_rs::common::error::ErrorType;
/// use lemon_bugsnag_rs::common::builder::error::BuilderError;
/// use lemon_bugsnag_rs::common::traits::decider_trait_sync::DeciderTraitSync;
/// use lemon_bugsnag_rs::common::traits::backend_builder_trait_sync::BackendBuilderTraitSync;
///
/// match ClientBuilder::error().reqwest().blocking().build() {
///     Ok(_) => {
///         // Do stuff
///     },
///     Err(error) => {
///         match error.error_type() {
///             // Handle errors as appropriate
///             ErrorType::ClientBuildError(builder_error) => {
///                 // This error contains another enum to further
///                 // distinguish the exact cause of the problem.
///                 match builder_error {
///                     // Both of these error types provide { context, fields }
///                     // which give more information about the error. These
///                     // fields are ommitted for brevity in this example.
///                     BuilderError::MissingField { .. } => (),
///                     BuilderError::ConflictingField { .. } => ()
///                 }
///             },
///             ErrorType::ClientBuildErrorForeign => (),
///             ErrorType::ClientRequestError => (),
///             ErrorType::SerializeError => (),
///             ErrorType::Unknown => (),
///         }
///     }
/// }
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ErrorType {
    /// For build errors caused by our own code. Contains a [BuilderError],
    /// which is generated by all lemon-bugsnag-rs build() functions when a
    /// problem is encountered, for further processing.
    ClientBuildError(BuilderError),
    /// For build errors caused by external code.
    ClientBuildErrorForeign,
    /// For error generated by back-end networking libraries while making or
    /// processing a request.
    ClientRequestError,
    /// For errors generated during serialization and deserialization of data,
    /// such as turning the data structs of a builder into a JSON payload.
    SerializeError,
    /// Catch-all error which ideally will not be used.
    Unknown,
}

mod test {
    #[test]
    fn test_create_error() {
        use crate::common::error::Error;
        use crate::common::error::ErrorType;

        // Generate a Rust error to serve as the source error for
        // this example.
        let std_error = "invalid".parse::<i32>().unwrap_err();

        // Create a lemon_bugsnag_rs error with a SerializeError type and
        // std_error as the source error.
        let error_message = "This is an error";
        let error_type = ErrorType::SerializeError;
        let error = Error::new(
            error_message,
            error_type.clone(),
            Some(Box::new(std_error)),
        );

        assert_eq!(error.error(), error_message);
        assert_eq!(error.error_type(), error_type);
    }
}

/// Error struct used to consolidate and standardize errors from multiple
/// sources.
///
/// # Example
/// ```
/// use lemon_bugsnag_rs::common::builder::client_builder::ClientBuilder;
/// use lemon_bugsnag_rs::common::traits::backend_builder_trait_sync::BackendBuilderTraitSync;
/// use lemon_bugsnag_rs::common::error::ErrorType;
/// use std::error::Error;
///
/// let client_builder = ClientBuilder::error();
///
/// match client_builder.ureq().build() {
///     Ok(_client) => {
///         // This is where you would handle a successful build
///     },
///     Err(error) => {
///         // Log this to your local logging system
///         // my_logger.log_error(builder_error.error);
///
///         // Process nested error, if any.
///         if error.source().is_some() {
///             let source_error = error.source().as_ref();
///             // Do stuff with the source error.
///         }
///
///         // Handle the error.
///         match error.error_type() {
///             ErrorType::ClientBuildError(builder_error) => {
///                 // This is where the builder error is handled.
///             },
///             _ => {
///                 // There are other types of error that you might want to
///                 // handle in production code. However, those additional
///                 // errors are irrelevant to this example.
///             },
///         }
///     },
/// };
/// ```
#[derive(Debug)]
pub struct Error {
    /// Discriminator used to determine the type of error represented by this
    /// struct.
    pub(crate) error_type: ErrorType,
    /// A string representation of the error.
    pub(crate) error: String,
    /// The source error. This can be used to pass along raw errors from
    /// third-party libraries, as long as those errors implement
    /// [std::error::Error].
    pub(crate) source: Option<Box<dyn StdError>>,
}

impl Error {
    pub(crate) fn new(
        error: impl Into<String>,
        error_type: ErrorType,
        source: Option<Box<dyn StdError>>,
    ) -> Error {
        Error { error_type, error: error.into(), source }
    }

    /// Retrieve the error message for this Error.
    ///
    /// #Example    
    /// ```
    /// use lemon_bugsnag_rs::common::builder::client_builder::ClientBuilder;
    /// use lemon_bugsnag_rs::common::traits::decider_trait_sync::DeciderTraitSync;
    /// use lemon_bugsnag_rs::common::traits::backend_builder_trait_sync::BackendBuilderTraitSync;
    /// use lemon_bugsnag_rs::common::error::Error;
    ///
    /// fn causes_error() -> Result<(), Error> {
    ///     ClientBuilder::error()
    ///         .reqwest().blocking().build()?;
    ///
    ///     Ok(())
    /// }
    ///
    /// let error = causes_error();
    /// # assert!(error.is_err());
    ///
    /// println!("{}", error.unwrap_err().error())
    /// ```
    pub fn error(&self) -> String {
        self.error.clone()
    }

    /// Retrieve the error type for this Error. See the [ErrorType#example]
    /// example for more information.
    ///
    /// #Example
    /// ```
    /// use lemon_bugsnag_rs::common::builder::client_builder::ClientBuilder;
    /// use lemon_bugsnag_rs::common::traits::decider_trait_sync::DeciderTraitSync;
    /// use lemon_bugsnag_rs::common::traits::backend_builder_trait_sync::BackendBuilderTraitSync;
    /// use lemon_bugsnag_rs::common::builder::error::BuilderError;
    /// use lemon_bugsnag_rs::common::error::ErrorType;
    /// use lemon_bugsnag_rs::common::error::Error;
    ///
    /// fn causes_error() -> Result<(), Error> {
    ///     ClientBuilder::error()
    ///         .reqwest().blocking().build()?;
    ///
    ///     Ok(())
    /// }
    ///
    /// let error = causes_error().unwrap_err();
    /// match error.error_type() {
    ///     ErrorType::ClientBuildError(builder_error) => {
    ///         // Error is processed here
    ///         # assert!(true)
    ///     },
    ///     _ => {
    ///         // We should not end up in here, becauses causes_error() should
    ///         // have generated a ClientBuildError.
    ///         assert!(false)
    ///     }
    /// }
    /// ```
    pub fn error_type(&self) -> ErrorType {
        self.error_type.clone()
    }
}

impl StdError for Error {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        self.source.as_ref().map(|e| &**e)
    }
}

impl Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let (error_type, error, source) = match self.error_type {
            ErrorType::ClientBuildError(_) => {
                ("ClientBuilderError", &self.error, &self.source)
            }
            ErrorType::ClientBuildErrorForeign => {
                ("ClientBuilderErrorForeign", &self.error, &self.source)
            }
            ErrorType::ClientRequestError => {
                ("ClientRequestError", &self.error, &self.source)
            }
            ErrorType::SerializeError => {
                ("SerializeError", &self.error, &self.source)
            }
            ErrorType::Unknown => ("Unknown", &self.error, &self.source),
        };

        write!(f, "{}: {} ({:?})", error_type, error, source)
    }
}

impl From<BuilderError> for Error {
    fn from(builder_error: BuilderError) -> Self {
        Error::new(
            builder_error.to_string(),
            ErrorType::ClientBuildError(builder_error),
            None,
        )
    }
}

#[cfg_attr(docsrs, doc(cfg(feature = "ureq")))]
#[cfg(feature = "ureq")]
impl From<ureq::Error> for Error {
    fn from(error: ureq::Error) -> Self {
        match error {
            // We don't expect to ever enter this block, since the send()
            // functions of the Ureq clients consume this type of error.
            // However, we don't want to blow up the code on the off chance
            // that this changes later. Therefore, we make a best-effort
            // attempt to translate this error into our own Error. Note that
            // this makes the Response that exists on the Ureq Status error
            // essentially unreachable.
            //
            // ToDo: Possibly restructure this to use unreachable/assert(false).
            ureq::Error::Status(_, _) => Error::new(
                error.to_string(),
                ErrorType::ClientRequestError,
                Some(Box::new(error)),
            ),
            ureq::Error::Transport(transport_error) => Error::new(
                transport_error
                    .message()
                    .unwrap_or("Unknown Ureq Transport Error")
                    .to_string(),
                ErrorType::ClientRequestError,
                Some(Box::new(transport_error)),
            ),
        }
    }
}

#[cfg_attr(docsrs, doc(cfg(feature = "convenience-intos")))]
#[cfg(all(feature = "reqwest", feature = "convenience-intos"))]
impl Into<Vec<Error>> for Error {
    fn into(self) -> Vec<Error> {
        let mut vector = Vec::new();
        vector.push(self);

        vector
    }
}

#[cfg_attr(docsrs, doc(cfg(feature = "reqwest")))]
#[cfg(feature = "reqwest")]
impl From<ReqwestError> for Error {
    fn from(error: ReqwestError) -> Self {
        if error.is_builder() {
            Error::new(
                error.to_string(),
                ErrorType::ClientBuildErrorForeign,
                Some(Box::new(error)),
            )
        } else if error.is_body() {
            Error::new(
                error.to_string(),
                ErrorType::ClientRequestError,
                Some(Box::new(error)),
            )
        } else {
            Error::new(
                error.to_string(),
                ErrorType::Unknown,
                Some(Box::new(error)),
            )
        }
    }
}

impl From<JsonError> for Error {
    fn from(error: JsonError) -> Self {
        Error::new(
            error.to_string(),
            ErrorType::SerializeError,
            Some(Box::new(error)),
        )
    }
}

impl From<url::ParseError> for Error {
    fn from(error: url::ParseError) -> Self {
        Error::new(
            error.to_string(),
            ErrorType::ClientBuildErrorForeign,
            Some(Box::new(error)),
        )
    }
}

/// Can be used to hold multiple [Error]s in cases where a function may generate
/// more than one user-addressable error in a single call. For example,
/// [ClientBuilderReqwestSessionSync's](
///   crate::session::reqwest::builder::blocking::ClientBuilderReqwestSessionSync
/// ) implementation of [BackendBuilderTrait::build](
///   crate::common::traits::backend_builder_trait_sync::BackendBuilderTraitSync::build
/// ) can return both [MissingField](
///   crate::common::builder::error::BuilderError::MissingField
/// ) and [ConflictingField](
///   crate::common::builder::error::BuilderError::ConflictingField
/// ) variants of [BuilderError] at the same
/// time.
///
/// # Example
/// ```
/// // This example requires the optional-builders feature.
/// // This example requires the convenience-intos feature.
/// // This example requires the session-client feature.
///
/// use chrono::DateTime;
///
/// use lemon_bugsnag_rs::{
///     common::traits::{backend_builder_trait_sync::BackendBuilderTraitSync, client_trait_sync::ClientTraitSync},
///     session::{
///         payload::{
///             notifier::Notifier, session_counts::session_count::SessionCount, sessions::Session,
///         },
///         session_client_builder::SessionClientBuilder,
///     },
/// };
///
/// use lemon_bugsnag_rs::common::builder::client_builder::ClientBuilder;
///
/// let timestamp = chrono::Utc::now();
///
/// let mut client_builder = ClientBuilder::session();
///
/// let session = Session {
///     id: "0123".to_string()
///     , started_at: timestamp
///     , user: None
/// };
///
/// let mut session_count_builder = SessionCount::builder();
/// let session_count = session_count_builder
///     .set_started_at(timestamp)
///     .set_sessions_started(4)
///     .build().unwrap();
///
/// // We configure both session and sesion_counts, which will result in a
/// // ConflictingField error when we call build() on client_builder.
/// // We also failed to configure the notifier, app, and device fields, which
/// // will result in a MissingField error when we try to build() this struct.
/// client_builder
///     .set_sessions(session)
///     .add_session_count(session_count);
///
/// let result = client_builder.ureq().build();
///
/// match result {
///     Ok(mut client) => {
///         // In a production environment, you would want to gracefully
///         // handle potential Error values when unwrapping.
///         client.send().unwrap();
///     },
///     Err(error_stack) => {
///         error_stack.errors.into_iter().for_each(|error| {
///             match error.error_type() {
///                 lemon_bugsnag_rs::common::error::ErrorType::ClientBuildError(builder_error) => {
///                     match builder_error {
///                         lemon_bugsnag_rs::common::builder::error::BuilderError::MissingField {context, fields } => {
///                             // In this example, we encounter this error
///                             // because we did not configure all required
///                             // fields on the SessionBuilder.
///
///                             // Handle MissingField error, here.
///                         },
///                         lemon_bugsnag_rs::common::builder::error::BuilderError::ConflictingField { context, fields } => {
///                             // In this example, we encounter this error
///                             // because we configured both the session
///                             // and session_counts keys, which are
///                             // mutually exclusive.
///
///                             // Handle ConflictingField error, here.
///                         },
///                     }
///                 },
///
///                 // These are other possible errors that are not relevant
///                 // to the error stack example.
///                 lemon_bugsnag_rs::common::error::ErrorType::ClientBuildErrorForeign => {},
///                 lemon_bugsnag_rs::common::error::ErrorType::ClientRequestError => {},
///                 lemon_bugsnag_rs::common::error::ErrorType::SerializeError => {},
///                 lemon_bugsnag_rs::common::error::ErrorType::Unknown => {},
///                 // Reserved for future error types.
///                 _ => {}
///             }
///         });
///     },
/// }
/// ```
#[derive(Debug, Default)]
pub struct ErrorStack {
    /// A Vec containing one or more [Error]s.
    pub errors: Vec<Error>,
}

impl Display for ErrorStack {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        for error in &self.errors {
            write!(f, "{}\n", error)?;
        }

        Ok(())
    }
}

impl StdError for ErrorStack {}

impl From<Error> for ErrorStack {
    fn from(error: Error) -> Self {
        let mut vector = Vec::new();
        vector.push(error);

        ErrorStack { errors: vector }
    }
}

#[cfg_attr(docsrs, doc(cfg(feature = "reqwest")))]
#[cfg(feature = "reqwest")]
impl From<ReqwestError> for ErrorStack {
    fn from(error: ReqwestError) -> Self {
        Error::from(error).into()
    }
}

impl From<BuilderError> for ErrorStack {
    fn from(builder_error: BuilderError) -> Self {
        Error::from(builder_error).into()
    }
}