From 5dc5a7cb6e7dc126e7591ad766faa91ff3943158 Mon Sep 17 00:00:00 2001 From: David Pedersen Date: Thu, 7 Oct 2021 15:33:49 +0200 Subject: [PATCH] Document debugging handler type errors with "axum-debug" (#372) * Document debugging handler type errors with "axum-debug" * Apply suggestions from code review Co-authored-by: Jonas Platte Co-authored-by: Jonas Platte --- src/lib.rs | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index d2a7bf26..4acbd1f1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,6 +5,7 @@ //! - [High level features](#high-level-features) //! - [Compatibility](#compatibility) //! - [Handlers](#handlers) +//! - [Debugging handler type errors](#debugging-handler-type-errors) //! - [Routing](#routing) //! - [Precedence](#precedence) //! - [Matching multiple methods](#matching-multiple-methods) @@ -106,6 +107,41 @@ //! } //! ``` //! +//! ## Debugging handler type errors +//! +//! For a function to used as a handler it must implement the [`Handler`] trait. +//! axum provides blanket implementations for functions that: +//! +//! - Are `async fn`s. +//! - Take no more than 16 arguments that all implement [`FromRequest`]. +//! - Returns something that implements [`IntoResponse`]. +//! - If a closure is used it must implement `Clone + Send + Sync` and be +//! `'static`. +//! - Returns a future that is `Send`. The most common way to accidentally make a +//! future `!Send` is to hold a `!Send` type across an await. +//! +//! Unfortunately Rust gives poor error messages if you try to use a function +//! that doesn't quite match what's required by [`Handler`]. +//! +//! You might get an error like this: +//! +//! ```not_rust +//! error[E0277]: the trait bound `fn(bool) -> impl Future {handler}: Handler<_, _>` is not satisfied +//! --> src/main.rs:13:44 +//! | +//! 13 | let app = Router::new().route("/", get(handler)); +//! | ^^^^^^^ the trait `Handler<_, _>` is not implemented for `fn(bool) -> impl Future {handler}` +//! | +//! ::: axum/src/handler/mod.rs:116:8 +//! | +//! 116 | H: Handler, +//! | ------------- required by this bound in `axum::handler::get` +//! ``` +//! +//! This error doesn't tell you _why_ your function doesn't implement +//! [`Handler`]. It's possible to improve the error with the [`debug_handler`] +//! proc-macro from the [axum-debug] crate. +//! //! # Routing //! //! Routing between handlers looks like this: @@ -1150,6 +1186,9 @@ //! [`HeaderMap`]: http::header::HeaderMap //! [`Request`]: http::Request //! [customize-extractor-error]: https://github.com/tokio-rs/axum/blob/main/examples/customize-extractor-error/src/main.rs +//! [axum-debug]: https://docs.rs/axum-debug +//! [`debug_handler`]: https://docs.rs/axum-debug/latest/axum_debug/attr.debug_handler.html +//! [`Handler`]: crate::handler::Handler #![warn( clippy::all,