code_ownership 2.1.4 → 2.2.0

data/ext/cargo-vendor/error-stack-0.8.0/src/sink.rs

@@ -0,0 +1,672 @@
+#[cfg(any(all(not(target_arch = "wasm32"), feature = "std"), feature = "tracing"))]
+use core::panic::Location;
+#[cfg(nightly)]
+use core::{
+    convert::Infallible,
+    ops::{FromResidual, Try},
+};
+
+use crate::Report;
+
+/// The `Bomb` type is used to enforce proper usage of `ReportSink` at runtime.
+///
+/// It addresses a limitation of the `#[must_use]` attribute, which becomes ineffective
+/// when methods like `&mut self` are called, marking the value as used prematurely.
+///
+/// By moving this check to runtime, `Bomb` ensures that `ReportSink` is properly
+/// consumed.
+///
+/// This runtime check complements the compile-time `#[must_use]` attribute,
+/// providing a more robust mechanism to prevent `ReportSink` not being consumed.
+#[derive(Debug)]
+enum BombState {
+    /// Panic if the `ReportSink` is dropped without being used.
+    Panic,
+    /// Emit a warning to stderr if the `ReportSink` is dropped without being used.
+    Warn(
+        // We capture the location if either `tracing` is enabled or `std` is enabled on non-WASM
+        // targets.
+        #[cfg(any(all(not(target_arch = "wasm32"), feature = "std"), feature = "tracing"))]
+        &'static Location<'static>,
+    ),
+    /// Do nothing if the `ReportSink` is properly consumed.
+    Defused,
+}
+
+impl Default for BombState {
+    #[track_caller]
+    fn default() -> Self {
+        Self::Warn(
+            #[cfg(any(all(not(target_arch = "wasm32"), feature = "std"), feature = "tracing"))]
+            Location::caller(),
+        )
+    }
+}
+
+#[derive(Debug, Default)]
+struct Bomb(BombState);
+
+impl Bomb {
+    const fn panic() -> Self {
+        Self(BombState::Panic)
+    }
+
+    #[track_caller]
+    const fn warn() -> Self {
+        Self(BombState::Warn(
+            #[cfg(any(all(not(target_arch = "wasm32"), feature = "std"), feature = "tracing"))]
+            Location::caller(),
+        ))
+    }
+
+    const fn defuse(&mut self) {
+        self.0 = BombState::Defused;
+    }
+}
+
+impl Drop for Bomb {
+    fn drop(&mut self) {
+        // If we're in release mode, we don't need to do anything
+        if !cfg!(debug_assertions) {
+            return;
+        }
+
+        match self.0 {
+            BombState::Panic => panic!("ReportSink was dropped without being consumed"),
+            #[cfg_attr(not(feature = "tracing"), expect(clippy::print_stderr))]
+            #[cfg(any(all(not(target_arch = "wasm32"), feature = "std"), feature = "tracing"))]
+            BombState::Warn(location) => {
+                #[cfg(feature = "tracing")]
+                tracing::warn!(
+                    target: "error_stack",
+                    %location,
+                    "`ReportSink` was dropped without being consumed"
+                );
+                #[cfg(not(feature = "tracing"))]
+                eprintln!("`ReportSink` was dropped without being consumed at {location}");
+            }
+            _ => {}
+        }
+    }
+}
+/// A sink for collecting multiple [`Report`]s into a single [`Result`].
+///
+/// [`ReportSink`] allows you to accumulate multiple errors or reports and then
+/// finalize them into a single `Result`. This is particularly useful when you
+/// need to collect errors from multiple operations before deciding whether to
+/// proceed or fail.
+///
+/// The sink is equipped with a "bomb" mechanism to ensure proper usage,
+/// if the sink hasn't been finished when dropped, it will emit a warning or panic,
+/// depending on the constructor used.
+///
+/// # Examples
+///
+/// ```
+/// use error_stack::{Report, ReportSink};
+///
+/// #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// struct InternalError;
+///
+/// impl core::fmt::Display for InternalError {
+///     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+///         f.write_str("Internal error")
+///     }
+/// }
+///
+/// impl core::error::Error for InternalError {}
+///
+/// fn operation1() -> Result<u32, Report<InternalError>> {
+///     // ...
+///     # Ok(42)
+/// }
+///
+/// fn operation2() -> Result<(), Report<InternalError>> {
+///     // ...
+///     # Ok(())
+/// }
+///
+/// fn process_data() -> Result<(), Report<[InternalError]>> {
+///     let mut sink = ReportSink::new();
+///
+///     if let Some(value) = sink.attempt(operation1()) {
+///         // process value
+///         # let _value = value;
+///     }
+///
+///     if let Err(e) = operation2() {
+///         sink.append(e);
+///     }
+///
+///     sink.finish()
+/// }
+/// # let _result = process_data();
+/// ```
+#[must_use]
+pub struct ReportSink<C> {
+    report: Option<Report<[C]>>,
+    bomb: Bomb,
+}
+
+impl<C> ReportSink<C> {
+    /// Creates a new [`ReportSink`].
+    ///
+    /// If the sink hasn't been finished when dropped, it will emit a warning.
+    #[track_caller]
+    pub const fn new() -> Self {
+        Self {
+            report: None,
+            bomb: Bomb::warn(),
+        }
+    }
+
+    /// Creates a new [`ReportSink`].
+    ///
+    /// If the sink hasn't been finished when dropped, it will panic.
+    pub const fn new_armed() -> Self {
+        Self {
+            report: None,
+            bomb: Bomb::panic(),
+        }
+    }
+
+    /// Adds a [`Report`] to the sink.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::{ReportSink, Report};
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// sink.append(Report::new(io::Error::new(
+    ///     io::ErrorKind::Other,
+    ///     "I/O error",
+    /// )));
+    /// ```
+    #[track_caller]
+    pub fn append(&mut self, report: impl Into<Report<[C]>>) {
+        let report = report.into();
+
+        match self.report.as_mut() {
+            Some(existing) => existing.append(report),
+            None => self.report = Some(report),
+        }
+    }
+
+    /// Captures a single error or report in the sink.
+    ///
+    /// This method is similar to [`append`], but allows for bare errors without prior [`Report`]
+    /// creation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// sink.capture(io::Error::new(io::ErrorKind::Other, "I/O error"));
+    /// ```
+    ///
+    /// [`append`]: ReportSink::append
+    #[track_caller]
+    pub fn capture(&mut self, error: impl Into<Report<C>>) {
+        let report = error.into();
+
+        match self.report.as_mut() {
+            Some(existing) => existing.push(report),
+            None => self.report = Some(report.into()),
+        }
+    }
+
+    /// Attempts to execute a fallible operation and collect any errors.
+    ///
+    /// This method takes a [`Result`] and returns an [`Option`]:
+    /// - If the [`Result`] is [`Ok`], it returns <code>[Some]\(T)</code> with the successful value.
+    /// - If the [`Result`] is [`Err`], it captures the error in the sink and returns [`None`].
+    ///
+    /// This is useful for concisely handling operations that may fail, allowing you to
+    /// collect errors while continuing execution.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// fn fallible_operation() -> Result<u32, io::Error> {
+    ///     // ...
+    ///     # Ok(42)
+    /// }
+    ///
+    /// let mut sink = ReportSink::new();
+    /// let value = sink.attempt(fallible_operation());
+    /// if let Some(v) = value {
+    ///     // Use the successful value
+    ///     # let _v = v;
+    /// }
+    /// // Any errors are now collected in the sink
+    /// # let _result = sink.finish();
+    /// ```
+    #[track_caller]
+    pub fn attempt<T, R>(&mut self, result: Result<T, R>) -> Option<T>
+    where
+        R: Into<Report<C>>,
+    {
+        match result {
+            Ok(value) => Some(value),
+            Err(error) => {
+                self.capture(error);
+                None
+            }
+        }
+    }
+
+    /// Finishes the sink and returns a [`Result`].
+    ///
+    /// This method consumes the sink, and returns `Ok(())` if no errors
+    /// were collected, or `Err(Report<[C]>)` containing all collected errors otherwise.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// # // needed for type inference
+    /// # sink.capture(io::Error::new(io::ErrorKind::Other, "I/O error"));
+    /// // ... add errors ...
+    /// let result = sink.finish();
+    /// # let _result = result;
+    /// ```
+    pub fn finish(mut self) -> Result<(), Report<[C]>> {
+        self.bomb.defuse();
+        self.report.map_or(Ok(()), Err)
+    }
+
+    /// Finishes the sink and returns a [`Result`] with a custom success value.
+    ///
+    /// Similar to [`finish`], but allows specifying a function to generate the success value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// # // needed for type inference
+    /// # sink.capture(io::Error::new(io::ErrorKind::Other, "I/O error"));
+    /// // ... add errors ...
+    /// let result = sink.finish_with(|| "Operation completed");
+    /// # let _result = result;
+    /// ```
+    ///
+    /// [`finish`]: ReportSink::finish
+    pub fn finish_with<T>(mut self, ok: impl FnOnce() -> T) -> Result<T, Report<[C]>> {
+        self.bomb.defuse();
+        self.report.map_or_else(|| Ok(ok()), Err)
+    }
+
+    /// Finishes the sink and returns a [`Result`] with a default success value.
+    ///
+    /// Similar to [`finish`], but uses `T::default()` as the success value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// # // needed for type inference
+    /// # sink.capture(io::Error::new(io::ErrorKind::Other, "I/O error"));
+    /// // ... add errors ...
+    /// let result: Result<Vec<String>, _> = sink.finish_default();
+    /// # let _result = result;
+    /// ```
+    ///
+    /// [`finish`]: ReportSink::finish
+    pub fn finish_default<T: Default>(mut self) -> Result<T, Report<[C]>> {
+        self.bomb.defuse();
+        self.report.map_or_else(|| Ok(T::default()), Err)
+    }
+
+    /// Finishes the sink and returns a [`Result`] with a provided success value.
+    ///
+    /// Similar to [`finish`], but allows specifying a concrete value for the success case.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use error_stack::ReportSink;
+    /// # use std::io;
+    /// let mut sink = ReportSink::new();
+    /// # // needed for type inference
+    /// # sink.capture(io::Error::new(io::ErrorKind::Other, "I/O error"));
+    /// // ... add errors ...
+    /// let result = sink.finish_ok(42);
+    /// # let _result = result;
+    /// ```
+    ///
+    /// [`finish`]: ReportSink::finish
+    pub fn finish_ok<T>(mut self, ok: T) -> Result<T, Report<[C]>> {
+        self.bomb.defuse();
+        self.report.map_or(Ok(ok), Err)
+    }
+}
+
+impl<C> Default for ReportSink<C> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(nightly)]
+impl<C> FromResidual for ReportSink<C> {
+    fn from_residual(residual: <Self as Try>::Residual) -> Self {
+        match residual {
+            Err(report) => Self {
+                report: Some(report),
+                bomb: Bomb::default(),
+            },
+        }
+    }
+}
+
+#[cfg(nightly)]
+impl<C> Try for ReportSink<C> {
+    type Output = ();
+    // needs to be infallible, not `!` because of the `Try` of `Result`
+    type Residual = Result<Infallible, Report<[C]>>;
+
+    fn from_output((): ()) -> Self {
+        Self {
+            report: None,
+            bomb: Bomb::default(),
+        }
+    }
+
+    fn branch(mut self) -> core::ops::ControlFlow<Self::Residual, Self::Output> {
+        self.bomb.defuse();
+        self.report.map_or(
+            core::ops::ControlFlow::Continue(()), //
+            |report| core::ops::ControlFlow::Break(Err(report)),
+        )
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use alloc::collections::BTreeSet;
+    use core::fmt::Display;
+
+    use crate::{Report, sink::ReportSink};
+
+    #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+    struct TestError(u8);
+
+    impl Display for TestError {
+        fn fmt(&self, fmt: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+            fmt.write_str("TestError(")?;
+            core::fmt::Display::fmt(&self.0, fmt)?;
+            fmt.write_str(")")
+        }
+    }
+
+    impl core::error::Error for TestError {}
+
+    #[test]
+    fn add_single() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+
+        let report = sink.finish().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 1);
+        assert!(contexts.contains(&TestError(0)));
+    }
+
+    #[test]
+    fn add_multiple() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+        sink.append(Report::new(TestError(1)));
+
+        let report = sink.finish().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn capture_single() {
+        let mut sink = ReportSink::new();
+
+        sink.capture(TestError(0));
+
+        let report = sink.finish().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 1);
+        assert!(contexts.contains(&TestError(0)));
+    }
+
+    #[test]
+    fn capture_multiple() {
+        let mut sink = ReportSink::new();
+
+        sink.capture(TestError(0));
+        sink.capture(TestError(1));
+
+        let report = sink.finish().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn new_does_not_panic() {
+        let _sink: ReportSink<TestError> = ReportSink::new();
+    }
+
+    #[cfg(nightly)]
+    #[test]
+    fn try_none() {
+        fn sink() -> Result<(), Report<[TestError]>> {
+            let sink = ReportSink::new();
+
+            sink?;
+
+            Ok(())
+        }
+
+        sink().expect("should not have failed");
+    }
+
+    #[cfg(nightly)]
+    #[test]
+    fn try_single() {
+        fn sink() -> Result<(), Report<[TestError]>> {
+            let mut sink = ReportSink::new();
+
+            sink.append(Report::new(TestError(0)));
+
+            sink?;
+            Ok(())
+        }
+
+        let report = sink().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 1);
+        assert!(contexts.contains(&TestError(0)));
+    }
+
+    #[cfg(nightly)]
+    #[test]
+    fn try_multiple() {
+        fn sink() -> Result<(), Report<[TestError]>> {
+            let mut sink = ReportSink::new();
+
+            sink.append(Report::new(TestError(0)));
+            sink.append(Report::new(TestError(1)));
+
+            sink?;
+            Ok(())
+        }
+
+        let report = sink().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[cfg(nightly)]
+    #[test]
+    fn try_arbitrary_return() {
+        fn sink() -> Result<u8, Report<[TestError]>> {
+            let mut sink = ReportSink::new();
+
+            sink.append(Report::new(TestError(0)));
+
+            sink?;
+            Ok(8)
+        }
+
+        let report = sink().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 1);
+        assert!(contexts.contains(&TestError(0)));
+    }
+
+    #[test]
+    #[should_panic(expected = "without being consumed")]
+    fn panic_on_unused() {
+        #[expect(clippy::unnecessary_wraps)]
+        fn sink() -> Result<(), Report<[TestError]>> {
+            let mut sink = ReportSink::new_armed();
+
+            sink.append(Report::new(TestError(0)));
+
+            Ok(())
+        }
+
+        let _result = sink();
+    }
+
+    #[test]
+    fn panic_on_unused_with_defuse() {
+        fn sink() -> Result<(), Report<[TestError]>> {
+            let mut sink = ReportSink::new_armed();
+
+            sink.append(Report::new(TestError(0)));
+
+            sink?;
+            Ok(())
+        }
+
+        let report = sink().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 1);
+        assert!(contexts.contains(&TestError(0)));
+    }
+
+    #[test]
+    fn finish() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+        sink.append(Report::new(TestError(1)));
+
+        let report = sink.finish().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn finish_ok() {
+        let sink: ReportSink<TestError> = ReportSink::new();
+
+        sink.finish().expect("should have succeeded");
+    }
+
+    #[test]
+    fn finish_with() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+        sink.append(Report::new(TestError(1)));
+
+        let report = sink.finish_with(|| 8).expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn finish_with_ok() {
+        let sink: ReportSink<TestError> = ReportSink::new();
+
+        let value = sink.finish_with(|| 8).expect("should have succeeded");
+        assert_eq!(value, 8);
+    }
+
+    #[test]
+    fn finish_default() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+        sink.append(Report::new(TestError(1)));
+
+        let report = sink.finish_default::<u8>().expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn finish_default_ok() {
+        let sink: ReportSink<TestError> = ReportSink::new();
+
+        let value = sink.finish_default::<u8>().expect("should have succeeded");
+        assert_eq!(value, 0);
+    }
+
+    #[test]
+    fn finish_with_value() {
+        let mut sink = ReportSink::new();
+
+        sink.append(Report::new(TestError(0)));
+        sink.append(Report::new(TestError(1)));
+
+        let report = sink.finish_ok(8).expect_err("should have failed");
+
+        let contexts: BTreeSet<_> = report.current_contexts().collect();
+        assert_eq!(contexts.len(), 2);
+        assert!(contexts.contains(&TestError(0)));
+        assert!(contexts.contains(&TestError(1)));
+    }
+
+    #[test]
+    fn finish_with_value_ok() {
+        let sink: ReportSink<TestError> = ReportSink::new();
+
+        let value = sink.finish_ok(8).expect("should have succeeded");
+        assert_eq!(value, 8);
+    }
+}