Extend custom rejection examples (#1276)

* examples: Created new `error-handling` example

* examples(error-handling): Add error codes and responses

* examples(error-handling): `custom_extractor`

* examples(error-handling): `derive_from_request`

* examples(error-handling): Using POST instead of GET

* examples(error-handling): Using `thiserror` for `derive_from_request`

* examples(error-handling): Using `snake-case` for routes

* revert(error-handling): Use `From` impl instead of `thiserror`

refs: 3533d96215

* examples(error-handling): Removed chrono

* examples: merged `error-handling` and `customize-extractor-error`

* examples(customize-extractor-error): Improved error codes

* examples(customize-extractor-error): rustfmt

* examples(customize-extractor-error): Removed `matched-path` feature

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

* examples(customize-extractor-error): added `publish=false` to `Cargo.toml`

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

* examples(customize-extractor-error): Fix env filter

* examples(customize-extractor-error): Added README

* examples(customize-extractor-error): Added `with_rejection` comments

* examples(customize-extractor-error): Added `custom_extractor` comments

* examples(customize-extractor-error):Typo on `with_rejection`

* examples(customize-extractor-error): Added `boilerplate` con to `custom_extractor`

* examples(customize-extractor-error): Added `derive_from_request` comments

* examples(customize-extractor-error): typo impossible

* examples(customize-extractor-error): typos

* examples(customize-extractor-error): replaced `extensions` with `extract`

* examples(customize-extractor-error): typo `from`

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

Co-authored-by: David Pedersen <david.pdrsn@gmail.com>

examples/customize-extractor-error/Cargo.toml

@@ -6,8 +6,11 @@ publish = false
 
 [dependencies]
 axum = { path = "../../axum" }
+axum-extra = { path = "../../axum-extra" }
+axum-macros = { path = "../../axum-macros" }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
-tokio = { version = "1.0", features = ["full"] }
+thiserror = "1.0"
+tokio = { version = "1.20", features = ["full"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }

examples/customize-extractor-error/README.md

@@ -0,0 +1,16 @@
+This example explores 3 different ways you can create custom rejections for
+already existing extractors
+
+- [`with_rejection`](src/with_rejection.rs): Uses
+  `axum_extra::extract::WithRejection` to transform one rejection into another
+- [`derive_from_request`](src/derive_from_request.rs): Uses
+  `axum_macros::FromRequest` to wrap another extractor and customize the
+  rejection
+- [`custom_extractor`](src/custom_extractor.rs): Manual implementation of
+  `FromRequest` that wraps another extractor
+
+Run with
+
+```sh
+cd examples && cargo run -p example-customize-extractor-error
+```

examples/customize-extractor-error/src/custom_extractor.rs

@@ -0,0 +1,69 @@
+//! Manual implementation of `FromRequest` that wraps another extractor
+//!
+//! + Powerful API: Implementing `FromRequest` grants access to `RequestParts`
+//!   and `async/await`. This means that you can create more powerful rejections
+//! - Boilerplate: Requires creating a new extractor for every custom rejection
+//! - Complexity: Manually implementing `FromRequest` results on more complex code
+use axum::extract::MatchedPath;
+use axum::{
+    async_trait,
+    extract::{rejection::JsonRejection, FromRequest, RequestParts},
+    http::StatusCode,
+    response::IntoResponse,
+    BoxError,
+};
+use serde::de::DeserializeOwned;
+use serde_json::{json, Value};
+
+pub async fn handler(Json(value): Json<Value>) -> impl IntoResponse {
+    Json(dbg!(value));
+}
+
+// We define our own `Json` extractor that customizes the error from `axum::Json`
+pub struct Json<T>(T);
+
+#[async_trait]
+impl<S, B, T> FromRequest<S, B> for Json<T>
+where
+    S: Send + Sync,
+    // these trait bounds are copied from `impl FromRequest for axum::Json`
+    // `T: Send` is required to send this future across an await
+    T: DeserializeOwned + Send,
+    B: axum::body::HttpBody + Send,
+    B::Data: Send,
+    B::Error: Into<BoxError>,
+{
+    type Rejection = (StatusCode, axum::Json<Value>);
+
+    async fn from_request(req: &mut RequestParts<S, B>) -> Result<Self, Self::Rejection> {
+        match axum::Json::<T>::from_request(req).await {
+            Ok(value) => Ok(Self(value.0)),
+            // convert the error from `axum::Json` into whatever we want
+            Err(rejection) => {
+                let path = req
+                    .extract::<MatchedPath>()
+                    .await
+                    .map(|x| x.as_str().to_owned())
+                    .ok();
+
+                // We can use other extractors to provide better rejection
+                // messages. For example, here we are using
+                // `axum::extract::MatchedPath` to provide a better error
+                // message
+                let payload = json!({
+                    "message": rejection.to_string(),
+                    "origin": "custom_extractor",
+                    "path": path,
+                });
+
+                let code = match rejection {
+                    JsonRejection::JsonDataError(_) => StatusCode::UNPROCESSABLE_ENTITY,
+                    JsonRejection::JsonSyntaxError(_) => StatusCode::BAD_REQUEST,
+                    JsonRejection::MissingJsonContentType(_) => StatusCode::UNSUPPORTED_MEDIA_TYPE,
+                    _ => StatusCode::INTERNAL_SERVER_ERROR,
+                };
+                Err((code, axum::Json(payload)))
+            }
+        }
+    }
+}

examples/customize-extractor-error/src/derive_from_request.rs

@@ -0,0 +1,60 @@
+//! Uses `axum_macros::FromRequest` to wrap another extractor and customize the
+//! rejection
+//!
+//! + Easy learning curve: Deriving `FromRequest` generates a `FromRequest`
+//!   implementation for your type using another extractor. You only need
+//!   to provide a `From` impl between the original rejection type and the
+//!   target rejection. Crates like [`thiserror`] can provide such conversion
+//!   using derive macros.
+//! - Boilerplate: Requires deriving `FromRequest` for every custom rejection
+//! - There are some known limitations: [FromRequest#known-limitations]
+//!
+//! [`thiserror`]: https://crates.io/crates/thiserror
+//! [FromRequest#known-limitations]: https://docs.rs/axum-macros/*/axum_macros/derive.FromRequest.html#known-limitations
+use axum::{extract::rejection::JsonRejection, http::StatusCode, response::IntoResponse};
+use axum_macros::FromRequest;
+use serde_json::{json, Value};
+
+pub async fn handler(Json(value): Json<Value>) -> impl IntoResponse {
+    Json(dbg!(value));
+}
+
+// create an extractor that internally uses `axum::Json` but has a custom rejection
+#[derive(FromRequest)]
+#[from_request(via(axum::Json), rejection(ApiError))]
+pub struct Json<T>(T);
+
+// We create our own rejection type
+#[derive(Debug)]
+pub struct ApiError {
+    code: StatusCode,
+    message: String,
+}
+
+// We implement `From<JsonRejection> for ApiError`
+impl From<JsonRejection> for ApiError {
+    fn from(rejection: JsonRejection) -> Self {
+        let code = match rejection {
+            JsonRejection::JsonDataError(_) => StatusCode::UNPROCESSABLE_ENTITY,
+            JsonRejection::JsonSyntaxError(_) => StatusCode::BAD_REQUEST,
+            JsonRejection::MissingJsonContentType(_) => StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            _ => StatusCode::INTERNAL_SERVER_ERROR,
+        };
+        Self {
+            code,
+            message: rejection.to_string(),
+        }
+    }
+}
+
+// We implement `IntoResponse` so ApiError can be used as a response
+impl IntoResponse for ApiError {
+    fn into_response(self) -> axum::response::Response {
+        let payload = json!({
+            "message": self.message,
+            "origin": "derive_from_request"
+        });
+
+        (self.code, axum::Json(payload)).into_response()
+    }
+}

examples/customize-extractor-error/src/main.rs

@@ -3,20 +3,13 @@
 //! ```not_rust
 //! cd examples && cargo run -p example-customize-extractor-error
 //! ```
-//!
-//! See https://docs.rs/axum-extra/0.3.7/axum_extra/extract/struct.WithRejection.html
-//! example for creating custom errors from already existing extractors
 
-use axum::{
+mod custom_extractor;
-    async_trait,
+mod derive_from_request;
-    extract::{rejection::JsonRejection, FromRequest, RequestParts},
+mod with_rejection;
-    http::StatusCode,
+
-    routing::post,
+use axum::{routing::post, Router};
-    BoxError, Router,
+use std::net::SocketAddr;
-};
-use serde::{de::DeserializeOwned, Deserialize};
-use serde_json::{json, Value};
-use std::{borrow::Cow, net::SocketAddr};
 use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
 
 #[tokio::main]
@@ -29,70 +22,17 @@ async fn main() {
         .with(tracing_subscriber::fmt::layer())
         .init();
 
-    // build our application with a route
+    // Build our application with some routes
-    let app = Router::new().route("/users", post(handler));
+    let app = Router::new()
+        .route("/with-rejection", post(with_rejection::handler))
+        .route("/custom-extractor", post(custom_extractor::handler))
+        .route("/derive-from-request", post(derive_from_request::handler));
 
-    // run it
+    // Run our application
     let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
-    println!("listening on {}", addr);
+    tracing::debug!("listening on {}", addr);
     axum::Server::bind(&addr)
         .serve(app.into_make_service())
         .await
         .unwrap();
 }
-
-async fn handler(Json(user): Json<User>) {
-    dbg!(&user);
-}
-
-#[derive(Debug, Deserialize)]
-#[allow(dead_code)]
-struct User {
-    id: i64,
-    username: String,
-}
-
-// We define our own `Json` extractor that customizes the error from `axum::Json`
-struct Json<T>(T);
-
-#[async_trait]
-impl<S, B, T> FromRequest<S, B> for Json<T>
-where
-    S: Send + Sync,
-    // these trait bounds are copied from `impl FromRequest for axum::Json`
-    T: DeserializeOwned,
-    B: axum::body::HttpBody + Send,
-    B::Data: Send,
-    B::Error: Into<BoxError>,
-{
-    type Rejection = (StatusCode, axum::Json<Value>);
-
-    async fn from_request(req: &mut RequestParts<S, B>) -> Result<Self, Self::Rejection> {
-        match axum::Json::<T>::from_request(req).await {
-            Ok(value) => Ok(Self(value.0)),
-            Err(rejection) => {
-                // convert the error from `axum::Json` into whatever we want
-                let (status, body): (_, Cow<'_, str>) = match rejection {
-                    JsonRejection::JsonDataError(err) => (
-                        StatusCode::BAD_REQUEST,
-                        format!("Invalid JSON request: {}", err).into(),
-                    ),
-                    JsonRejection::MissingJsonContentType(err) => {
-                        (StatusCode::BAD_REQUEST, err.to_string().into())
-                    }
-                    err => (
-                        StatusCode::INTERNAL_SERVER_ERROR,
-                        format!("Unknown internal error: {}", err).into(),
-                    ),
-                };
-
-                Err((
-                    status,
-                    // we use `axum::Json` here to generate a JSON response
-                    // body but you can use whatever response you want
-                    axum::Json(json!({ "error": body })),
-                ))
-            }
-        }
-    }
-}

examples/customize-extractor-error/src/with_rejection.rs

@@ -0,0 +1,57 @@
+//! Uses `axum_extra::extract::WithRejection` to transform one rejection into
+//! another
+//!
+//! + Easy learning curve: `WithRejection` acts as a wrapper for another
+//!   already existing extractor. You only need to provide a `From` impl
+//!   between the original rejection type and the target rejection. Crates like
+//!   `thiserror` can provide such conversion using derive macros. See
+//!   [`thiserror`]
+//! - Verbose types: types become much larger, which makes them difficult to
+//!   read. Current limitations on type aliasing makes impossible to destructure
+//!   a type alias. See [#1116]
+//!   
+//! [`thiserror`]: https://crates.io/crates/thiserror
+//! [#1116]: https://github.com/tokio-rs/axum/issues/1116#issuecomment-1186197684
+
+use axum::{extract::rejection::JsonRejection, http::StatusCode, response::IntoResponse, Json};
+use axum_extra::extract::WithRejection;
+use serde_json::{json, Value};
+use thiserror::Error;
+
+pub async fn handler(
+    // `WitRejection` will extract `Json<Value>` from the request. If it fails,
+    // `JsonRejection` will be transform into `ApiError` and returned as response
+    // to the client.
+    //
+    // The second constructor argument is not meaningful and can be safely ignored
+    WithRejection(Json(value), _): WithRejection<Json<Value>, ApiError>,
+) -> impl IntoResponse {
+    Json(dbg!(value))
+}
+
+// We derive `thiserror::Error`
+#[derive(Debug, Error)]
+pub enum ApiError {
+    // The `#[from]` attribute generates `From<JsonRejection> for ApiError`
+    // implementation. See `thiserror` docs for more information
+    #[error(transparent)]
+    JsonExtractorRejection(#[from] JsonRejection),
+}
+// We implement `IntoResponse` so ApiError can be used as a response
+impl IntoResponse for ApiError {
+    fn into_response(self) -> axum::response::Response {
+        let payload = json!({
+            "message": self.to_string(),
+            "origin": "with_rejection"
+        });
+        let code = match self {
+            ApiError::JsonExtractorRejection(x) => match x {
+                JsonRejection::JsonDataError(_) => StatusCode::UNPROCESSABLE_ENTITY,
+                JsonRejection::JsonSyntaxError(_) => StatusCode::BAD_REQUEST,
+                JsonRejection::MissingJsonContentType(_) => StatusCode::UNSUPPORTED_MEDIA_TYPE,
+                _ => StatusCode::INTERNAL_SERVER_ERROR,
+            },
+        };
+        (code, Json(payload)).into_response()
+    }
+}