agglayer_errors/

lib.rs

#[cfg(feature = "tracing")]
use std::fmt::Display;

#[doc(hidden)] // Used by the macro
pub use eyre;

pub mod prelude {
    #[cfg(feature = "tracing")]
    pub use crate::ResultExt;
}

/// Extension trait for `Result` to log errors and warnings using the `tracing`
/// crate.
#[cfg(feature = "tracing")]
pub trait ResultExt {
    /// Log errors at error level with a static message.
    ///
    /// If you don't care about the error message, call eg. `log_err("")`.
    fn log_err(self, msg: impl Display) -> Self;

    /// Log errors at error level with a message generated by a closure.
    fn log_err_with<F>(self, f: F) -> Self
    where
        F: FnOnce() -> String;

    /// Log errors at warning level with a static message.
    ///
    /// If you don't care about the error message, call eg. `log_warn("")`.
    fn log_warn(self, msg: impl Display) -> Self;

    /// Log errors at warning level with a message generated by a closure.
    fn log_warn_with<F>(self, f: F) -> Self
    where
        F: FnOnce() -> String;

    /// Log errors at informational level with a static message.
    ///
    /// If you don't care about the error message, call eg. `log_warn("")`.
    fn log_info(self, msg: impl Display) -> Self;

    /// Log errors at informational level with a message generated by a closure.
    fn log_info_with<F>(self, f: F) -> Self
    where
        F: FnOnce() -> String;

    /// Log errors at debug level with a static message.
    ///
    /// If you don't care about the error message, call eg. `log_warn("")`.
    fn log_debug(self, msg: impl Display) -> Self;

    /// Log errors at debug level with a message generated by a closure.
    fn log_debug_with<F>(self, f: F) -> Self
    where
        F: FnOnce() -> String;

    /// Log errors at trace level with a static message.
    ///
    /// If you don't care about the error message, call eg. `log_warn("")`.
    fn log_trace(self, msg: impl Display) -> Self;

    /// Log errors at trace level with a message generated by a closure.
    fn log_trace_with<F>(self, f: F) -> Self
    where
        F: FnOnce() -> String;
}

#[cfg(feature = "tracing")]
impl<T, E> ResultExt for Result<T, E>
where
    E: std::fmt::Debug,
{
    fn log_err(self, msg: impl Display) -> Self {
        self.inspect_err(|error| tracing::error!(?error, "{msg}"))
    }

    fn log_err_with<F>(self, msg: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.inspect_err(|error| tracing::error!(?error, "{}", msg()))
    }

    fn log_warn(self, msg: impl Display) -> Self {
        self.inspect_err(|error| tracing::warn!(?error, "{msg}"))
    }

    fn log_warn_with<F>(self, msg: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.inspect_err(|error| tracing::warn!(?error, "{}", msg()))
    }

    fn log_info(self, msg: impl Display) -> Self {
        self.inspect_err(|error| tracing::info!(?error, "{msg}"))
    }

    fn log_info_with<F>(self, msg: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.inspect_err(|error| tracing::info!(?error, "{}", msg()))
    }

    fn log_debug(self, msg: impl Display) -> Self {
        self.inspect_err(|error| tracing::debug!(?error, "{msg}"))
    }

    fn log_debug_with<F>(self, msg: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.inspect_err(|error| tracing::debug!(?error, "{}", msg()))
    }

    fn log_trace(self, msg: impl Display) -> Self {
        self.inspect_err(|error| tracing::trace!(?error, "{msg}"))
    }

    fn log_trace_with<F>(self, msg: F) -> Self
    where
        F: FnOnce() -> String,
    {
        self.inspect_err(|error| tracing::trace!(?error, "{}", msg()))
    }
}

/// Match an `eyre::Report` against multiple error types and patterns.
///
/// # Example
/// ```rust
/// use agglayer_errors::match_err;
/// use eyre::Context as _;
///
/// #[derive(Debug, thiserror::Error)]
/// #[error("Foo")]
/// struct Foo;
///
/// #[derive(Debug, thiserror::Error)]
/// #[error("Bar")]
/// struct Bar(&'static str);
///
/// let err: eyre::Report = Foo.into();
/// let s = match_err!(err,
///     type<Foo>(_) => "foo".to_string(),
///     type<Bar>(Bar("foo")) => "bar/foo".to_string(),
///     type<Bar>(Bar(s)) => format!("bar({s})"),
///     else(_) => "other".to_string(),
/// );
/// ```
#[macro_export]
macro_rules! match_err {
    (
        $expr:expr
        $(, type<$ty:ty>($pat:pat) => $handler:expr)*
        $(, else($default_pat:pat) => $default_handler:expr)?
        $(,)?
    ) => {
        'result: {
            let expr: $crate::eyre::Report = $expr;
            $(
                #[allow(unused_variables)] // Pattern variables are unused from this downcast_ref
                if let Some($pat) = expr.downcast_ref::<$ty>() {
                    let Ok($pat) = expr.downcast::<$ty>() else {
                        // This should never happen because we just checked downcast_ref
                        unreachable!("downcast_ref succeeded but downcast failed");
                    };
                    let res = $handler;
                    break 'result res;
                }
            )*
            $(
                let $default_pat = expr;
                $default_handler
            )?
        }
    };
}

/// Match an `eyre::Result` against multiple `Ok` patterns and multiple error
/// types and patterns.
///
/// If no error pattern matches, propagate the error up.
///
/// # Example
/// ```rust
/// use agglayer_errors::match_res;
/// use eyre::Context as _;
///
/// #[derive(Debug, thiserror::Error)]
/// #[error("Foo")]
/// struct Foo;
///
/// #[derive(Debug, thiserror::Error)]
/// #[error("Bar")]
/// struct Bar(&'static str);
///
/// fn main() -> eyre::Result<()> {
///     let res: eyre::Result<u32> = Err(Bar("foo").into());
///     let s = match_res!(res,
///         Ok(42) => "the answer".to_string(),
///         Ok(n) => format!("ok({n})"),
///         Err(type<Bar>(Bar("foo"))) => "bar/foo".to_string(),
///         Err(type<Bar>(b)) => format!("bar({})", b.0),
///         // By default, propagate the error up
///     );
///
///     let res2: eyre::Result<u32> = Err(Foo.into());
///     let s2 = match_res!(res2,
///         Ok(42) => "the answer".to_string(),
///         Ok(n) => format!("ok({n})"),
///         Err(type<Bar>(Bar("foo"))) => "bar/foo".to_string(),
///         Err(type<Bar>(b)) => format!("bar({})", b.0),
///         Err(else(err)) => format!("other({err})"), // Catch-all, do not propagate
///     );
///
///     Ok(())
/// }
/// ```
#[macro_export]
macro_rules! match_res {
    (
        $expr:expr
        $(, Ok($ok:pat) => $ok_handler:expr)*
        $(, Err(type<$err_ty:ty>($err:pat)) => $err_handler:expr)*
        $(,)?
    ) => {
        $crate::match_res!($expr
            $(, Ok($ok) => $ok_handler)*
            $(, Err(type<$err_ty>($err)) => $err_handler)*
            , Err(else(err)) => { return Err(err) }
        )
    };

    (
        $expr:expr
        $(, Ok($ok:pat) => $ok_handler:expr)*
        $(, Err(type<$err_ty:ty>($err:pat)) => $err_handler:expr)*
        , Err(else($default_err:pat)) => $default_handler:expr
        $(,)?
    ) => {
        match $expr {
            $(
                Ok($ok) => $ok_handler,
            )*
            Err(err) => $crate::match_err!(err,
                $(
                    type<$err_ty>($err) => $err_handler,
                )*
                else($default_err) => $default_handler,
            ),
        }
    };
}

#[cfg(test)]
mod tests {
    use eyre::Context as _;

    #[derive(Debug, thiserror::Error)]
    #[error("Foo")]
    struct Foo;

    #[derive(Debug, thiserror::Error)]
    #[error("Bar")]
    struct Bar(&'static str);

    #[derive(Debug, thiserror::Error)]
    #[error("Quux")]
    struct Quux;

    fn use_match_err_to_make_a_value<E: Into<eyre::Report>>(err: E) -> String {
        let err: eyre::Report = err.into();
        match_err!(err,
            type<Foo>(_) => "foo".to_string(),
            type<Bar>(Bar("foo")) => "bar/foo".to_string(),
            type<Bar>(Bar(s)) => format!("bar({s})"),
            else(_) => "other".to_string(),
        )
    }

    #[test]
    fn match_err_to_make_a_value() {
        // Basic tests
        assert_eq!(use_match_err_to_make_a_value(Foo), "foo");
        assert_eq!(use_match_err_to_make_a_value(Bar("baz")), "bar(baz)");
        assert_eq!(use_match_err_to_make_a_value(Bar("foo")), "bar/foo");

        // Default works
        assert_eq!(use_match_err_to_make_a_value(Quux), "other");
        assert_eq!(use_match_err_to_make_a_value(eyre::eyre!("baz")), "other");

        // Wrapping with context has no impact
        assert_eq!(
            use_match_err_to_make_a_value(eyre::Report::from(Foo).wrap_err("with some context")),
            "foo"
        );

        // Wrapping with another match-able error shows the first match among the
        // match_err branches.
        // Not necessarily the best choice, but it should be good enough for now.
        assert_eq!(
            use_match_err_to_make_a_value(eyre::Report::from(Foo).wrap_err(Bar("baz"))),
            "foo"
        );
        assert_eq!(
            use_match_err_to_make_a_value(eyre::Report::from(Bar("baz")).wrap_err(Foo)),
            "foo"
        );

        // Wrapping an unknown error with a match-able error does show the match-able
        // error
        assert_eq!(
            use_match_err_to_make_a_value(eyre::Report::from(Quux).wrap_err(Foo)),
            "foo"
        );
        assert_eq!(
            use_match_err_to_make_a_value(eyre::Report::from(Quux).wrap_err(Foo).wrap_err(Quux)),
            "foo"
        );
    }

    fn use_match_err_to_run_code<E: Into<eyre::Report>>(err: E) -> String {
        let err: eyre::Report = err.into();
        let mut res = "other".to_string();
        match_err!(err,
            type<Foo>(_) => {
                res = "foo".to_string();
            },
            type<Bar>(Bar("foo")) => {
                res = "bar/foo".to_string();
            },
            type<Bar>(Bar(s)) => {
                res = format!("bar({s})");
            },
            // No @default branch, the result is () everywhere
        );
        res
    }

    #[test]
    fn match_err_to_run_code() {
        // Basic tests
        assert_eq!(use_match_err_to_run_code(Foo), "foo");
        assert_eq!(use_match_err_to_run_code(Bar("baz")), "bar(baz)");
        assert_eq!(use_match_err_to_run_code(Bar("foo")), "bar/foo");

        // Default works
        assert_eq!(use_match_err_to_run_code(Quux), "other");
        assert_eq!(use_match_err_to_run_code(eyre::eyre!("baz")), "other");

        // Wrapping with context has no impact
        assert_eq!(
            use_match_err_to_run_code(eyre::Report::from(Foo).wrap_err("with some context")),
            "foo"
        );

        // Wrapping with another match-able error shows the first match among the
        // match_err branches.
        // Not necessarily the best choice, but it should be good enough for now.
        assert_eq!(
            use_match_err_to_run_code(eyre::Report::from(Foo).wrap_err(Bar("baz"))),
            "foo"
        );
        assert_eq!(
            use_match_err_to_run_code(eyre::Report::from(Bar("baz")).wrap_err(Foo)),
            "foo"
        );

        // Wrapping an unknown error with a match-able error does show the match-able
        // error
        assert_eq!(
            use_match_err_to_run_code(eyre::Report::from(Quux).wrap_err(Foo)),
            "foo"
        );
        assert_eq!(
            use_match_err_to_run_code(eyre::Report::from(Quux).wrap_err(Foo).wrap_err(Quux)),
            "foo"
        );
    }

    fn use_match_res_with_default(res: eyre::Result<u32>) -> String {
        match_res!(res,
            Ok(42) => "the answer".to_string(),
            Ok(n) => format!("ok({n})"),
            Err(type<Bar>(Bar("foo"))) => "bar/foo".to_string(),
            Err(type<Bar>(b)) => format!("bar({})", b.0),
            Err(else(err)) => format!("other({err})"),
        )
    }

    #[test]
    fn match_err_with_default() {
        assert_eq!(use_match_res_with_default(Ok(42)), "the answer");
        assert_eq!(use_match_res_with_default(Ok(7)), "ok(7)");
        assert_eq!(
            use_match_res_with_default(Err(Bar("foo").into())),
            "bar/foo"
        );
        assert_eq!(
            use_match_res_with_default(Err(Bar("baz").into())),
            "bar(baz)"
        );
        assert_eq!(use_match_res_with_default(Err(Foo.into())), "other(Foo)");

        assert_eq!(
            use_match_res_with_default(Err(eyre::Report::from(Bar("baz"))).wrap_err(Quux)),
            "bar(baz)"
        );
    }

    fn use_match_res_without_default(res: eyre::Result<u32>) -> eyre::Result<String> {
        match_res!(res,
            Ok(42) => Ok("the answer".to_string()),
            Ok(n) => Ok(format!("ok({n})")),
            Err(type<Bar>(Bar("foo"))) => Ok("bar/foo".to_string()),
            Err(type<Bar>(b)) => Ok(format!("bar({})", b.0)),
            // No @default branch, will propagate other errors up
        )
    }

    #[test]
    fn match_err_without_default() {
        assert_eq!(use_match_res_without_default(Ok(42)).unwrap(), "the answer");
        assert_eq!(use_match_res_without_default(Ok(7)).unwrap(), "ok(7)");
        assert_eq!(
            use_match_res_without_default(Err(Bar("foo").into())).unwrap(),
            "bar/foo"
        );
        assert_eq!(
            use_match_res_without_default(Err(Bar("baz").into())).unwrap(),
            "bar(baz)"
        );
        assert!(use_match_res_without_default(Err(Foo.into())).is_err());

        assert_eq!(
            use_match_res_without_default(Err(eyre::Report::from(Bar("baz"))).wrap_err(Quux))
                .unwrap(),
            "bar(baz)"
        );
    }
}