From a026217c6180ffadddb08202365922a2068f744c Mon Sep 17 00:00:00 2001 From: David Pedersen Date: Thu, 7 Oct 2021 17:27:17 +0200 Subject: [PATCH] Version 0.2.8 (#374) * 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 * Version 0.2.8 - Document debugging handler type errors with "axum-debug" ([#372]) [#372]: https://github.com/tokio-rs/axum/pull/372 Co-authored-by: Jonas Platte --- CHANGELOG.md | 6 ++++++ Cargo.toml | 2 +- src/lib.rs | 39 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 839ae01f..5ab288c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - None +# 0.2.8 (07. October, 2021) + +- Document debugging handler type errors with "axum-debug" ([#372]) + +[#372]: https://github.com/tokio-rs/axum/pull/372 + # 0.2.7 (06. October, 2021) - Bump minimum version of async-trait ([#370]) diff --git a/Cargo.toml b/Cargo.toml index f4123ed7..d31b3a41 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "axum" -version = "0.2.7" +version = "0.2.8" authors = ["David Pedersen "] categories = ["asynchronous", "network-programming", "web-programming"] description = "Web framework that focuses on ergonomics and modularity" diff --git a/src/lib.rs b/src/lib.rs index ba102a0a..8f83b8b7 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: @@ -1147,6 +1183,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,