[debug] Add debug::Error, a wrapper for attaching context to errors

This type cannot be created except via special macros in the `debug`
module that generate log statements. We may eventually also attach
extra debugging information to errors, and this type is a good place
to do so.

Signed-off-by: Miguel Young de la Sota <[email protected]>

Author: mcy

src/cert/mod.rs

@@ -95,6 +95,8 @@ impl From<untrusted::EndOfInput> for Error {
     }
 }
 
+debug_from!(Error => io::Error, untrusted::EndOfInput);
+
 impl<'cert> Cert<'cert> {
     /// Parses `cert`, producing a parsed certificate in the given format.
     ///

src/debug.rs

@@ -11,42 +11,137 @@
 //! Manticore code *should not* call into the [`log`] crate directly outside of
 //! this module.
 
+// TODO: Remove this once we start using these macros in Manticore.
 #![allow(unused)]
 
+use core::fmt;
+
 #[cfg(doc)]
 use __raw_log as log;
 
+/// A wrapped Manticore error.
+///
+/// This type should always be referred to as `manticore::Error`. It represents
+/// an error with extra (potentially redacted) information attached. This type
+/// cannot be directly created by users of the library.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Error<E> {
+    inner: E,
+}
+
+impl<E> Error<E> {
+    /// Creates a new `Error`. This function is an implementation detail,
+    /// and should not be called by users.
+    #[doc(hidden)]
+    pub fn __new(inner: E) -> Self {
+        Self { inner }
+    }
+
+    /// Transforms the wrapper error by way of an [`Into`] conversion.
+    ///
+    /// Generally, this function should not be necessary, because Manticore-
+    /// defined error types manually implement the relevant [`From`]
+    /// implementations for `manticore::Error`, which in turn call `cast()`.
+    pub fn cast<F>(self) -> Error<F>
+    where
+        F: From<E>,
+    {
+        Error {
+            inner: self.inner.into(),
+        }
+    }
+
+    /// Gets the wrapper error.
+    pub fn into_inner(self) -> E {
+        self.inner
+    }
+}
+
+impl<E> AsRef<E> for Error<E> {
+    fn as_ref(&self) -> &E {
+        &self.inner
+    }
+}
+
+impl<E> AsMut<E> for Error<E> {
+    fn as_mut(&mut self) -> &mut E {
+        &mut self.inner
+    }
+}
+
+impl<E: fmt::Display> fmt::Display for Error<E> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        struct DisplayAsDebug<'a, E>(&'a E);
+        impl<E: fmt::Display> fmt::Debug for DisplayAsDebug<'_, E> {
+            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+                self.0.fmt(f)
+            }
+        }
+
+        f.debug_struct("manticore::Error")
+            .field("inner", &DisplayAsDebug(&self.inner))
+            .finish()
+    }
+}
+
+/// Generates `From` implementations for `manticore::Error`.
+///
+/// We would like to write this `impl`:
+/// ```compile_fail
+/// # use manticore::Error;
+/// impl<E1, E2> From<Error<E1>> for Error<E2> where E2: From<E1> {
+///     fn from(e: Error<E1>) -> Error<E2> {
+///         e.cast()
+///     }
+/// }
+/// ```
+///
+/// Unfortunately, the trait coherence rules mean that for `E1 == E2`,
+/// this conflicts with the standard library's `impl<T> From<T> for T`
+/// impl. We work around this by calling this macro for every Manticore
+/// error definition that has `From` impls.
+macro_rules! debug_from {
+    ($e:ty => $($f:ty),+ $(,)?) => {$(
+        impl From<$crate::Error<$f>> for $crate::Error<$e> {
+            fn from(e: $crate::Error<$f>) -> Self {
+                e.cast()
+            }
+        }
+    )*}
+}
+
 /// Checks a condition, logging if it fails.
 ///
 /// If the condition does not hold, constructs the given error, logs it, and
 /// returns out of the current function with it.
 macro_rules! check {
     ($cond:expr, $error:expr) => {
         if !$cond {
-            let e = $error;
-            error!(
+            let error = $error;
+            trace!(
+                error,
                 "check failure: `{}`; returned {:?}"
-                stringify!($cond), e
-            );
-            return Err(e);
+                stringify!($cond), error,
+            )?;
         }
     }
 }
 
 /// Logs a newly-created error value and returns it.
 ///
-/// This function is useful for marking where errors originate in tests.
+/// This macro is the main way to generate [`Error`] values.
+///
 /// For example, instead of writing `foo.ok_or(MyError)`, instead write
 /// `foo.ok_or_else(|| trace!(MyError))`.
 macro_rules! trace {
     ($error:expr, $($format:tt)+) => {{
         error!($($format)+);
-        $error
+        $crate::debug::Error::__new($error)
     }};
     ($error:expr) => {{
-        let e = $error;
-        error!("generated error: `{:?}`", e);
-        e
+        let error = $error;
+        error!("generated error: `{:?}`", error);
+        $crate::debug::Error::__new(error)
     }};
 }
 

src/hardware/flash.rs

@@ -56,6 +56,7 @@ impl From<OutOfMemory> for Error {
         Error::Internal
     }
 }
+debug_from!(Error => OutOfMemory);
 
 /// Provides access to a flash-like storage device.
 ///

src/lib.rs

@@ -56,11 +56,11 @@
 // `debug`.
 #[cfg(feature = "log")]
 extern crate log as __raw_log;
+#[macro_use]
+mod debug;
 
 #[macro_use]
 pub mod protocol;
-#[macro_use]
-mod debug;
 
 #[cfg(feature = "serde")]
 mod serde;
@@ -73,3 +73,12 @@ pub mod manifest;
 pub mod mem;
 pub mod net;
 pub mod server;
+
+pub use debug::Error;
+
+/// [`Result`] type to use throughout Manticore, which incorporates the
+/// [`manticore::Error`] type.
+///
+/// [`Result`]: std::result::Result
+/// [`manticore::Error`]: crate::Error
+pub type Result<T, E> = core::result::Result<T, Error<E>>;

src/manifest/mod.rs

@@ -218,6 +218,8 @@ impl From<sha256::Error> for Error {
     }
 }
 
+debug_from!(Error => io::Error, flash::Error, OutOfMemory, sig::Error, sha256::Error);
+
 /// A manifest type.
 ///
 /// A type that implements this trait is not itself a "parsed" instance of the

src/net.rs

@@ -50,6 +50,8 @@ impl From<io::Error> for Error {
     }
 }
 
+debug_from!(Error => io::Error);
+
 /// Represents a physical port that can be used to interact with host devices.
 ///
 /// This trait provides a generic mechanism for recieving and responding to

src/protocol/wire.rs

@@ -57,6 +57,8 @@ impl From<OutOfMemory> for FromWireError {
     }
 }
 
+debug_from!(FromWireError => io::Error, OutOfMemory);
+
 /// A type which can be serialized into the Cerberus wire format.
 pub trait ToWire: Sized {
     /// Serializes `self` into `w`.
@@ -76,6 +78,8 @@ impl From<io::Error> for ToWireError {
     }
 }
 
+debug_from!(ToWireError => io::Error);
+
 /// Represents a C-like enum that can be converted to and from a wire
 /// representation as well as to and from a string representation.
 ///
@@ -231,7 +235,12 @@ macro_rules! wire_enum {
         impl core::str::FromStr for $name {
             type Err = $crate::protocol::wire::WireEnumFromStrError;
 
-            fn from_str(s: &str) -> Result<Self, $crate::protocol::wire::WireEnumFromStrError> {
+            fn from_str(
+                s: &str
+            ) -> core::result::Result<
+                Self,
+                $crate::protocol::wire::WireEnumFromStrError
+            > {
                 use $crate::protocol::wire::WireEnum;
 
                 match $name::from_name(s) {

src/server/handler.rs

@@ -128,6 +128,8 @@ impl From<net::Error> for Error {
     }
 }
 
+debug_from!(Error => FromWireError, ToWireError, net::Error);
+
 /// A request handler builder.
 ///
 /// See the module documentation for more information.