Guidelines for implementing Display and Error::source for library errors

[Nemo157]

I have been involved in trying to fix a couple of crates errors to work better with error reporters like anyhow/eyre recently (clap-rs/clap#2151, sunng87/handlebars-rust#398). One big issue I find with reporting these sorts of issues is not having a succinct, canonical "this is how errors should be implemented" source to link to. The only api-guideline related is C-GOOD-ERR which doesn't talk about chaining at all, and simply says:

The error message given by the Display representation of an error type should be lowercase without trailing punctuation, and typically concise.

It would be very useful to have something to link to which talks about chaining to sources, not adding unnecessary "Error: " prefixes, and not printing your source's message as part of your own message. (I'm assuming a chapter/appendix in the error-book, or a new section in the api-guidelines).

[Enet4]

Including relevant references, as they already appear to cover most of the concerns presented in this issue: #23 rust-lang/api-guidelines#210.

1. It would be very useful to have something to link to which talks about chaining to sources,

The main problem is that there isn't a well established error reporter or a consensus on how they should be reported across the ecosystem. Error reporting isn't a fully solved problem, and libraries or applications without a revamped error reporter with error chain awareness would suddenly provide subpar messages if their dependencies began expecting them.

2. not adding unnecessary "Error: " prefixes,

That sounds reasonable, and could be independently proposed as an addition to the C-GOOD-ERR guideline.

3. and not printing your source's message as part of your own message.

As per rust-lang/api-guidelines#210, that recommendation was already proposed but was put on hold mostly for the reasons stated in point 1 and in the issues linked.

[Nemo157]

1. It would be very useful to have something to link to which talks about chaining to sources,

The main problem is that there isn't a well established error reporter or a consensus on how they should be reported across the ecosystem

I don't think this necessarily needs to reference the reporting side, just provide guidance on when and how you should implement Error::source.

[mkantor]

A fundamental question in my head is: should library authors expect that end users will see source error messages?

If so, it encourages layering just a bit of extra context in each Error (e.g. Reverting to default settings -> File "foo/settings.json" could not be opened -> No such file or directory (os error 2)).

If not, it nudges library authors towards including information about lower-level Errors in their messages (e.g. Reverting to default settings because "foo/settings.json" was not found). But they may still want to attach sources to aid consumers of the library (even if end users are never meant to see them).

The former leads to subpar UX when applications don't expose source messages (Reverting to default settings is frustrating if you can't tell why) and the latter leads to overly-verbose/duplicative messages that are hard to skim when applications do print source messages (Reverting to default settings because "foo/settings.json" was not found: File "foo/settings.json" could not be opened because the file does not exist: No such file or directory (os error 2) has a low signal-to-noise ratio).

Since today libraries make different assumptions it means application developers have to either settle for crummy error messages in places or write distinct message formatting code for each individual error (which lessens the appeal of libraries like anyhow & eyre).

[mkantor]

I guess my previous comment is what #23 is about. Apologies for not clicking through before writing it up.

[epage]

A fundamental question in my head is: should library authors expect that end users will see source error messages?
...
I guess my previous comment is what #23 is about. Apologies for not clicking through before writing it up.

I actually think this is relevant in a wider context than #23. In my experience, there are different dimensions to source

• API contract says that you can rely on certain details from source while others are left undefined (leaf error is context but you want to walk to the root error for making decisions)
• source is only relevant for a developer debugging and isn't designed for displaying to an end user (error codes, debug information, etc)

In my experiments with status crate, I joined these two concepts with the idea of chaining in an internal source. The reporter then needs to explicitly enable reporting o the internal `source. Really, they are separate dimensions. No idea how we should generalize this though.

#23 provides guidance on source as part of the discussion for Display but doesn't broach the general source API and UX trade offs and how to handle them.

[yaahc]

I don't think this necessarily needs to reference the reporting side, just provide guidance on when and how you should implement Error::source.

The problem is that the guidance we would give depends on how we decide to officially conceptualize the role of the Error trait. The big question being, "Is the Error trait primarily an interface for reporting errors or primarily an interface for reacting to specific type erased errors?".

If we decide to prefer the former viewpoint then we would want to prioritize not duplicating information in the reporting interfaces of the Error trait. That would then turn into the guidance: Return source errors via Error::source unless the source error's message is included in your own error message in Display.

If we decide to prefer the latter then we would want to prioritize exposing every error type in the chain of errors to ensure users can always correctly downcast to specific error variants they want to handle. In this situation the guidance would be: Always return source errors via Error::source.

My feeling is that the former viewpoint, that the Error trait is primarily for reporting, is the ideal one. However, I feel like we're not necessarily in the best position to standardize on this approach. By saying that errors are only supposed to define how they're reported we're mandating that some sort of Reporter be present to iterate over sources / backtraces / etc. My feeling is that this is currently a missing piece and that the Error trait is really only half of a complete design for error reporting. For non-recoverable errors we already have PanicInfo as the reporting interface for non-recoverable errors and the panic hook/handler as the Reporter that consumes the interface, but for non recoverable errors the best we have for reporting is 3rd party libraries like anyhow and eyre.

I've been thinking on this specific issue a lot recently and my feeling is that if we can find some way to unify error reporting so that it is consistently defined for an entire application then we can pretty happily move forward with the former viewpoint and it should work well for everyone. I've some more thoughts on globally consistent error reporting here.

However, if we can't fix the holes around reporting for the Error trait then I don't feel that there is a clear winner for which guidance we should give...

[yaahc]

Follow up on this issue and #23

I talked with the libs team today about the primary question outlined above (Is the Error trait primarily an interface for reporting errors or primarily an interface for reacting to specific type erased errors?). We came to the consensus that the primary role of the error trait is providing a structured access to error context for the purpose of reporting, so our guidance is officially decided.

• Return source errors via Error::source unless the source error's message is included in your own error message in Display.

As part of this we've also green-lighted efforts to patch holes in error reporting for error trait objects, particularly with how they interact with panics. I expect our immediate next step will be to add an API like std::panic::panic_any for passing &dyn Error + 'static instead of a &dyn Any to the panic handler. We will then utilize specialization in the standard library to make unwrap and expect and other functions that promote errors to panics to report the error with panic_error for types that implement Error. This + updates to the default panic handler will make it so we always print all the errors in a chain of errors when we promote them to panics. We then hope to follow this up with a more comprehensive RFC proposing a unified error reporting scheme for defining how panics and runtime errors are reported across an application.

[Fishrock123]

std::panic::panic_any

I think you meant to write std::panic::panic_error.