Some quickly scribbled notes, based on recent conversations:

• Use failure
• Always return Fail implementations
• Default policy for most APIs: just return failure::Error
• In cases where consumers of an error are likely to need the extra structured data, return the more specific error type
• Whenever a higher abstraction layer consumes a lower abstraction layer's errors, use with_context
• Have a top-level trait for "is going to be seen by the human" errors, and require Notion errors to define a conversion to that
• A few different ways we can report information at the top level:
  • one-liner default error message
  • verbose details
  • possibly a log generated even by default?
• Notion error trait (extends Fail) should also include a method for returning the exit code, to keep them organized

from volta.

Rough plan

Fail subtrait for Notion failures

All Notion failures should implement an extended version of the Fail trait.

The NotionFail trait has an is_user_friendly() method for determining whether a type's error messages are fit for end-user consumption, and an exit_code() method for determining what exit code the error should produce. (The latter might need to evolve later to accommodate signals, depending on how we do #36 and #37.)

    trait NotionFail: Fail {
        fn is_user_friendly(&self) -> bool;
        fn exit_code(&self) -> i32;
    }

Make all Notion error types coercible to NotionError

To allow the distributed creation of Notion error types that can all be intermixed via ?, define an Into coercion from NotionFail types to NotionError.

    impl<T: NotionFail> Into<NotionError> for T { ... }

Explicit conversion method for turning external Fails into NotionError

An extension method .unknown() makes it easy to explicitly mark an error as an "unknown error," i.e. a non-user-friendly error.

    trait FailExt {
        fn unknown(self) -> NotionError;
    }
    
    #[derive(Fail)]
    #[fail(...)]
    struct UnknownNotionError { ... }
    
    impl NotionFail for UnknownNotionError {
        fn is_user_friendly() -> bool { false }
        fn exit_code() -> i32 { 1 }
    }
    
    impl<T: Fail> FailExt for T {
        fn unknown(self) -> NotionError {
            UnknownNotionError { ... }.into()
        }
    }

Mark Context as a NotionFail

In order for with_context to work with the Notion error types, it should implement NotionFail whenever its inner error does.

    impl<D: NotionFail> NotionFail for failure::Context<D> { ... }

Usage patterns

• functions return Result<T, NotionError> by default, except in rare cases when we need more specific error types
• any Notion errors interop freely with NotionError via ?
• non-Notion errors get converted to Notion errors either via:
  • with_context to create a user-friendly error
  • e.unknown() which marks an error as non-user-friendly

from volta.