tracing_result/

lib.rs

#![cfg_attr(unstable_never_type, feature(never_type))]
#![cfg_attr(unstable_try_trait_v2, feature(try_trait_v2))]

//! A library for ergonomic error handling with tracing support.
//!
//! This crate provides a wrapper around [`Result`], [`Option`] & any other types
//! which implement [`Try`] that automatically emits tracing messages at configurable log levels
//! when unpacked via the `?` operator.
//!
//! # Overview
//!
//! The [`Trace`] trait extends all `Try`-types `T` with methods that wrap it in a [`Traced<T>`]
//! with a custom tracing message. The message is emitted automatically when the [`Traced<T>`] is
//! used with the `?` operator.
//!
//! Simply `use tracing_result::Trace` to bring the methods into scope. The blanket implementation
//! ensures availability on all `Try`-types, not only `Result`& `Option`.
//!
//! There are two families of methods:
//! - **`or_*` methods** ([`or_error`][Trace::or_error], [`or_warn`][Trace::or_warn],
//!   [`or_info`][Trace::or_info], [`or_debug`][Trace::or_debug], [`or_trace`][Trace::or_trace]):
//!   Log the message when an **`Err`**/**`None`** etc. is unpacked
//! - **`and_*` methods** ([`and_error`][Trace::and_error], [`and_warn`][Trace::and_warn],
//!   [`and_info`][Trace::and_info], [`and_debug`][Trace::and_debug], [`and_trace`][Trace::and_trace]):
//!   Log the message when an **`Ok`**/**`Some`** etc. is unpacked
//!
//! # Examples
//!
//! ## `Traced<Result>`
//!
//! ```
//! use std::io;
//! use tracing_result::Trace;
//!
//! fn might_fail() -> io::Result<u32> {
//!     Err(io::Error::other("something went wrong"))
//! }
//!
//! fn compute() -> io::Result<u32> {
//!     // If might_fail() returns Err, "Failed to compute value" will be logged as a warning
//!     might_fail().or_warn("Failed to compute value")?;
//!     Ok(42)
//! }
//!
//! fn unexpected_success() -> io::Result<u32> {
//!     // If Ok is returned, "Unexpected: computation succeeded" will be logged as a warning
//!     let res = io::Result::Ok(42).and_warn("Unexpected: computation succeeded")?;
//!     Ok(res)
//! }
//! ```
//!
//! ## `Traced<Option>`
//!
//! ```
//! use tracing_result::Trace;
//! use try_v2::{Extract, Transform};
//!
//! #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
//! struct Data {
//!     value: Option<i32>,
//! }
//!
//! let data: Vec<Data> = Vec::new();
//!
//! let first_value = data
//!     .first()
//!     .or_warn("No entries found") // Emitted if `None`
//!     .and_then(|d| d.value) // `Transform` methods call `Try::branch` and therefore emit
//!     .or_warn("No value in first entry") // Emitted if `None`
//!     .unwrap_or_default(); // `Extract` methods call `Try::branch` and therefore emit
//!
//! assert_eq!(first_value, 0);
//! ```

use std::ops::{ControlFlow, FromResidual, Try};
use tracing::Level;
use try_v2::{Extract, Transform};

use crate::TracingConfig::{OnOutput, OnResidual};

/// The [`Trace`] trait extends all `Try`-types `T` with methods that wrap it in a [`Traced<T>`]
/// with a custom tracing message. The message is emitted automatically when the [`Traced<T>`] is
/// used with the `?` operator.
///
/// Simply `use tracing_result::Trace` to bring the methods into scope. The blanket implementation
/// ensures availability on all `Try`-types, not only `Result`& `Option`.
///
/// There are two families of methods:
/// - **`or_*` methods** ([`or_error`][Trace::or_error], [`or_warn`][Trace::or_warn],
///   [`or_info`][Trace::or_info], [`or_debug`][Trace::or_debug], [`or_trace`][Trace::or_trace]):
///   Log the message when an **`Err`**/**`None`** etc. is unpacked
/// - **`and_*` methods** ([`and_error`][Trace::and_error], [`and_warn`][Trace::and_warn],
///   [`and_info`][Trace::and_info], [`and_debug`][Trace::and_debug], [`and_trace`][Trace::and_trace]):
///   Log the message when an **`Ok`**/**`Some`** etc. is unpacked
///
/// # Examples
///
/// ## `Traced<Result>`
///
/// ```
/// use std::io;
/// use tracing_result::Trace;
///
/// fn might_fail() -> io::Result<u32> {
///     Err(io::Error::other("something went wrong"))
/// }
///
/// fn compute() -> io::Result<u32> {
///     // If might_fail() returns Err, "Failed to compute value" will be logged as a warning
///     might_fail().or_warn("Failed to compute value")?;
///     Ok(42)
/// }
///
/// fn unexpected_success() -> io::Result<u32> {
///     // If Ok is returned, "Unexpected: computation succeeded" will be logged as a warning
///     let res = io::Result::Ok(42).and_warn("Unexpected: computation succeeded")?;
///     Ok(res)
/// }
/// ```
///
/// ## `Traced<Option>`
///
/// ```
/// use tracing_result::Trace;
/// use try_v2::{Extract, Transform};
///
/// #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
/// struct Data {
///     value: Option<i32>,
/// }
///
/// let data: Vec<Data> = Vec::new();
///
/// let first_value = data
///     .first()
///     .or_warn("No entries found") // Emitted if `None`
///     .and_then(|d| d.value) // `Transform` methods call `Try::branch` and therefore emit
///     .or_warn("No value in first entry") // Emitted if `None`
///     .unwrap_or_default(); // `Extract` methods call `Try::branch` and therefore emit
///
/// assert_eq!(first_value, 0);
/// ```
pub trait Trace<T: Try> {
    /// Attaches an error-level message to the `Residual` case.
    fn or_error(self, name: &'static str) -> Traced<T>;

    /// Attaches an error-level message to the `Output` case.
    fn and_error(self, name: &'static str) -> Traced<T>;

    /// Attaches a warning message to the `Residual` case.
    fn or_warn(self, name: &'static str) -> Traced<T>;

    /// Attaches a warning message to the `Output` case.
    fn and_warn(self, name: &'static str) -> Traced<T>;

    /// Attaches an info message to the `Residual` case.
    fn or_info(self, name: &'static str) -> Traced<T>;

    /// Attaches an info message to the `Output` case.
    fn and_info(self, name: &'static str) -> Traced<T>;

    /// Attaches a debug message to the `Residual` case.
    fn or_debug(self, name: &'static str) -> Traced<T>;

    /// Attaches a debug message to the `Output` case.
    fn and_debug(self, name: &'static str) -> Traced<T>;

    /// Attaches a trace-level message to the `Residual` case.
    fn or_trace(self, name: &'static str) -> Traced<T>;

    /// Attaches a trace-level message to the `Output` case.
    fn and_trace(self, name: &'static str) -> Traced<T>;
}

impl<T: Try> Trace<T> for T {
    fn or_error(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnResidual(Event {
                level: Level::ERROR,
                message: name,
            }),
        }
    }

    fn and_error(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnOutput(Event {
                level: Level::ERROR,
                message: name,
            }),
        }
    }

    fn or_warn(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnResidual(Event {
                level: Level::WARN,
                message: name,
            }),
        }
    }

    fn and_warn(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnOutput(Event {
                level: Level::WARN,
                message: name,
            }),
        }
    }

    fn or_info(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnResidual(Event {
                level: Level::INFO,
                message: name,
            }),
        }
    }

    fn and_info(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnOutput(Event {
                level: Level::INFO,
                message: name,
            }),
        }
    }

    fn or_debug(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnResidual(Event {
                level: Level::DEBUG,
                message: name,
            }),
        }
    }

    fn and_debug(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnOutput(Event {
                level: Level::DEBUG,
                message: name,
            }),
        }
    }

    fn or_trace(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnResidual(Event {
                level: Level::TRACE,
                message: name,
            }),
        }
    }

    fn and_trace(self, name: &'static str) -> Traced<T> {
        Traced {
            inner: self,
            event: TracingConfig::OnOutput(Event {
                level: Level::TRACE,
                message: name,
            }),
        }
    }
}

/// The wrapper around a `Try`-type with associated tracing event. You will usually not
/// interact directly with this type but rather with the trait [`Trace`].
#[must_use = "The wrapped type may be an `Err`, `None`, or other `Residual` which requires handling."]
pub struct Traced<T>
where
    T: Try,
{
    inner: T,
    event: TracingConfig,
}

/// Calling any of the extraction functions *will emit* the enclosed tracing entries related
/// to the relevant variant.
impl<T, O> Extract<O> for Traced<T> where T: Try<Output = O> {}

/// Calling any of the transformation functions *will emit* the enclosed tracing entries related
/// to the relevant variant.
impl<T, O> Transform<O> for Traced<T> where T: Try<Output = O> {}

/// # Note
///
/// - Any attached events are emitted when `branch` is called and all wrappings are
///   removed, leaving either the `Output` or `Resdiual` of the wrapped `Try`-type.
///   For example: using `?` on a `Traced<Traced<Option<T>>>` will result in either a
///   `T` or `None`.
/// - `Traced<T>` does not implement its own `Output` or `Residual` types but immediately
///   unwraps to the `Output` / `Residual` of the wrapped `Try`-type.
impl<T: Try> Try for Traced<T> {
    type Output = T::Output;

    type Residual = T::Residual;

    fn from_output(output: Self::Output) -> Self {
        Self {
            inner: Try::from_output(output),
            event: Default::default(),
        }
    }

    /// Used in `?` to decide whether the operator should produce a value
    /// (because this returned [`ControlFlow::Continue`])
    /// or propagate a value back to the caller
    /// (because this returned [`ControlFlow::Break`]).
    ///
    /// # Note
    ///
    /// Any attached events are emitted when `branch` is called and all wrappings are
    /// removed, leaving either the `Output` or `Resdiual` of the wrapped `Try`-type.
    /// For example: using `?` on a `Traced<Traced<Option<T>>>` will result in either a
    /// `T` or `None`.
    fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
        match self.inner.branch() {
            ControlFlow::Continue(output) => {
                self.event.emit_output();
                ControlFlow::Continue(output)
            }
            ControlFlow::Break(residual) => {
                self.event.emit_residual();
                ControlFlow::Break(residual)
            }
        }
    }
}

/// # Note
///
/// - The `Traced<T>` returned from ` try { Traced<T>? } ` will have no attached tracing
///   events, as all will be emitted by the `?` inside the `try` block
/// - `FromResidual` is primarily implemented as a formality, normal usage will likely be
///   in the form `try bikeshed T { Traced<T>? }`
impl<T: Try> FromResidual for Traced<T> {
    fn from_residual(residual: <Self as Try>::Residual) -> Self {
        Self {
            inner: FromResidual::from_residual(residual),
            event: Default::default(),
        }
    }
}

pub type TracedResult<T, E> = Traced<Result<T, E>>;
pub type TracedOption<T> = Traced<Option<T>>;

impl<T, E> TracedResult<T, E> {
    /// Converts from `TracedResult<T, E>` to `Option<E>`, emitting any tracing entry in the process.
    pub fn err(self) -> Option<E> {
        match self.branch() {
            ControlFlow::Continue(_) => None,
            ControlFlow::Break(Result::Err(err)) => Some(err),
        }
    }

    /// Converts from `TracedResult<T, E>` to `Option<T>`, emitting any tracing entry in the process.
    pub fn ok(self) -> Option<T> {
        self.output()
    }
}

/// Configuration for tracing log level and message.
#[derive(Debug, Clone, Copy)]
struct Event {
    /// The tracing level to use when logging.
    level: Level,
    /// The message to log.
    message: &'static str,
}

impl Event {
    fn emit(&self) {
        match self.level {
            Level::ERROR => tracing::error!("{}", self.message),
            Level::WARN => tracing::warn!("{}", self.message),
            Level::INFO => tracing::info!("{}", self.message),
            Level::DEBUG => tracing::debug!("{}", self.message),
            Level::TRACE => tracing::trace!("{}", self.message),
        }
    }
}

#[derive(Debug, Clone, Copy, Default)]
enum TracingConfig {
    OnOutput(Event),
    OnResidual(Event),
    #[default]
    None,
}

impl TracingConfig {
    fn emit_output(&self) {
        if let OnOutput(event) = self {
            event.emit();
        }
    }

    fn emit_residual(&self) {
        if let OnResidual(event) = self {
            event.emit();
        }
    }
}

#[cfg(test)]
mod tests {
    use std::io;

    use tracing_test::traced_test;

    use super::*;

    /// Tests that `or_error` on an Ok result does not log.
    #[traced_test]
    #[test]
    fn or_error_ok() {
        fn no_error() -> io::Result<()> {
            io::Result::Ok(()).or_error("should not log")?;
            Ok(())
        }

        assert!(no_error().is_ok());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_error` on an Err result logs at ERROR level.
    #[traced_test]
    #[test]
    fn or_error_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).or_error("error message")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(logs_contain("error message"));
    }

    /// Tests that `and_error` on an Ok result logs at ERROR level.
    #[traced_test]
    #[test]
    fn and_error_ok() {
        fn ok() -> io::Result<()> {
            io::Result::Ok(()).and_error("error on ok")?;
            Ok(())
        }

        assert!(ok().is_ok());
        assert!(logs_contain("error on ok"));
    }

    /// Tests that `and_error` on an Err result does not log.
    #[traced_test]
    #[test]
    fn and_error_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).and_error("should not log")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_warn` on an Ok result does not log.
    #[traced_test]
    #[test]
    fn or_warn_ok() {
        fn no_error() -> io::Result<()> {
            io::Result::Ok(()).or_warn("stuff")?;
            Ok(())
        }

        assert!(no_error().is_ok());
        assert!(!logs_contain("stuff"));
    }

    /// Tests that `or_warn` on an Err result logs the warning message.
    #[traced_test]
    #[test]
    fn or_warn_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).or_warn("stuff")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(!logs_contain("name"));
        assert!(logs_contain("stuff"));
    }

    /// Tests that `and_warn` on an Ok result logs the warning message.
    #[traced_test]
    #[test]
    fn and_warn_ok() {
        fn ok() -> io::Result<()> {
            io::Result::Ok(()).and_warn("ok warn")?;
            Ok(())
        }

        assert!(ok().is_ok());
        assert!(logs_contain("ok warn"));
    }

    /// Tests that `and_warn` on an Err result does not log.
    #[traced_test]
    #[test]
    fn and_warn_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).and_warn("should not log")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_debug` on an Ok result does not log.
    #[traced_test]
    #[test]
    fn or_debug_ok() {
        fn no_error() -> io::Result<()> {
            io::Result::Ok(()).or_debug("should not log")?;
            Ok(())
        }

        assert!(no_error().is_ok());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_debug` on an Err result logs at DEBUG level.
    #[traced_test]
    #[test]
    fn or_debug_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).or_debug("debug message")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(logs_contain("debug message"));
    }

    /// Tests that `and_debug` on an Ok result logs at DEBUG level.
    #[traced_test]
    #[test]
    fn and_debug_ok() {
        fn ok() -> io::Result<()> {
            io::Result::Ok(()).and_debug("debug on ok")?;
            Ok(())
        }

        assert!(ok().is_ok());
        assert!(logs_contain("debug on ok"));
    }

    /// Tests that `and_debug` on an Err result does not log.
    #[traced_test]
    #[test]
    fn and_debug_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).and_debug("should not log")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_trace` on an Ok result does not log.
    #[traced_test]
    #[test]
    fn or_trace_ok() {
        fn no_error() -> io::Result<()> {
            io::Result::Ok(()).or_trace("should not log")?;
            Ok(())
        }

        assert!(no_error().is_ok());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `or_trace` on an Err result logs at TRACE level.
    #[traced_test]
    #[test]
    fn or_trace_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).or_trace("trace message")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(logs_contain("trace message"));
    }

    /// Tests that `and_trace` on an Ok result logs at TRACE level.
    #[traced_test]
    #[test]
    fn and_trace_ok() {
        fn ok() -> io::Result<()> {
            io::Result::Ok(()).and_trace("trace on ok")?;
            Ok(())
        }

        assert!(ok().is_ok());
        assert!(logs_contain("trace on ok"));
    }

    /// Tests that `and_trace` on an Err result does not log.
    #[traced_test]
    #[test]
    fn and_trace_err() {
        fn err() -> io::Result<()> {
            Err(io::Error::other("oops")).and_trace("should not log")?;
            Ok(())
        }

        assert!(err().is_err());
        assert!(!logs_contain("should not log"));
    }

    /// Tests that `ok` on an Ok(v) with no log entry returns Some(v) and does not emit.
    #[traced_test]
    #[test]
    fn ok_or_ok() {
        let good = io::Result::Ok(5).or_warn("should not log");
        let v = good.ok();
        assert_eq!(v, Some(5));
        assert!(!logs_contain("should not log"));
    }

    #[traced_test]
    #[test]
    fn ok_and_ok() {
        let good = io::Result::Ok(5).and_warn("should log");
        let v = good.ok();
        assert_eq!(v, Some(5));
        assert!(logs_contain("should log"));
    }

    #[traced_test]
    #[test]
    fn err_or_err() {
        let err: TracedResult<i32, _> = Err(io::Error::other("oops")).or_warn("should log");
        let v = err.err();
        assert_eq!(v.map(|e| e.to_string()), Some("oops".to_string()));
        assert!(logs_contain("should log"));
    }

    #[traced_test]
    #[test]
    fn err_and_err() {
        let err: TracedResult<i32, _> = Err(io::Error::other("oops")).and_warn("should not log");
        let v = err.err();
        assert_eq!(v.map(|e| e.to_string()), Some("oops".to_string()));
        assert!(!logs_contain("should not log"));
    }

    #[traced_test]
    #[test]
    fn err_conversion() {
        fn convert() -> Result<(), u32> {
            let err: Result<(), u16> = Err(5);
            err.or_error("conversion")?;
            Ok(())
        }
        assert!(convert().is_err());
        assert!(logs_contain("conversion"));
    }

    #[traced_test]
    #[test]
    fn option() {
        fn opt() -> Option<usize> {
            let n = Some(5).or_warn("wibble")?;
            Some(n)
        }

        assert_eq!(opt(), Some(5));
        assert!(!logs_contain("wibble"));
    }

    #[traced_test]
    #[test]
    fn none_and_then() {
        let _: Option<usize> = Option::<usize>::None
            .or_warn("wibble")
            .and_then(|x| Some(x + 1));
        assert!(logs_contain("wibble"));
    }

    #[traced_test]
    #[test]
    fn some_and_then() {
        let n = Some(4).or_warn("wibble").and_then(|x| Some(x + 1));
        assert_eq!(n, Some(5));
        assert!(!logs_contain("wibble"));
    }

    #[traced_test]
    #[test]
    fn chain() {
        fn chained() -> Option<usize> {
            let n = Some(4).or_warn("empty").and_debug("full")?;
            Some(n + 1)
        }
        assert_eq!(chained(), Some(5));
        assert!(logs_contain("full"));
        assert!(!logs_contain("empty"));
    }
}