anyhow-based error handling example should be advertised more broadly

[vi]

• I have looked for existing issues (including closed) about this

Feature Request

Motivation

Primary place where I end up when looking how to make fallible handlers is axum::error_handling module documentation page. It even contains mentions of "anyhow" in "Routing to fallible services" section, but it is not clear how just upgrade existing infallible handlers to anyhow-fallible ones.

Fortunately, there is already an example of how to wrap Anyhow errors for Axum consumption (even with a properly working ? operator), but it is not obvious how to get there.

Proposal

Include a link to anyhow-error-response in axum::error_handling module documentation, e.g. in "axum’s error handling model" section.

Alternatives

• Inline the example of anyhow-wrapping AppError directly in the docs (instead of a link).
• Maybe also introduce "Routing to fallible handlers" section after "model", before "fallible services" which is oriented on practical approaches of making fallible handlers, with only theoretical things retained in the "model" section.

[davidpdrsn]

Like described in the error handling docs axum does not consider a handler returning Result<_, _> as fallible. Thats just something that'll be converted into a response. Only service level errors are considered errors since they don't send back a response at all and instead hyper terminates the connection.

With that said I think it's fine to link to the anyhow example from the docs. Do you want to submit a PR for that?

[vi]

Like described in the error handling docs axum does not consider a handler returning Result<_, _> as fallible. Thats just something that'll be converted into a response. Only service level errors are considered errors since they don't send back a response at all and instead hyper terminates the connection.

Do I understand that there can be two meanings of the word "fallible" in this context:

• "fallible service", in tower_service::Service<Error != Infallible> sense. This is banned for axum::handler::Handlers, as they do not have error type inside. So "real", hard errors should be already handled within a Hander before it reaches the router.
• "fallible endpoint/handler", meaning request that can fail in user code (because it uses fallible operations inside and contains ? operators). Router does not "see" those errors, as they are converted to responses just like successful outcomes.

With that said I think it's fine to link to the anyhow example from the docs. Do you want to submit a PR for that?

Maybe, but I want to ensure I understand it properly myself first.
Shall it be a minimal change to just include the link or more substantial one to make the doc easier to understand for beginners?

[davidpdrsn]

I don't think we should document returning Result from handlers in the "error handling" module as that module is about service level errors.

I think we should just link to the anyhow example.

[davidpdrsn]

Fixed in #2049