diff --git a/examples/customize-extractor-error/Cargo.toml b/examples/customize-extractor-error/Cargo.toml index 95f99080..95e4f770 100644 --- a/examples/customize-extractor-error/Cargo.toml +++ b/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"] } diff --git a/examples/customize-extractor-error/README.md b/examples/customize-extractor-error/README.md new file mode 100644 index 00000000..5c9b8486 --- /dev/null +++ b/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 +``` diff --git a/examples/customize-extractor-error/src/custom_extractor.rs b/examples/customize-extractor-error/src/custom_extractor.rs new file mode 100644 index 00000000..781da925 --- /dev/null +++ b/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) -> impl IntoResponse { + Json(dbg!(value)); +} + +// We define our own `Json` extractor that customizes the error from `axum::Json` +pub struct Json(T); + +#[async_trait] +impl FromRequest for Json +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, +{ + type Rejection = (StatusCode, axum::Json); + + async fn from_request(req: &mut RequestParts) -> Result { + match axum::Json::::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::() + .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))) + } + } + } +} diff --git a/examples/customize-extractor-error/src/derive_from_request.rs b/examples/customize-extractor-error/src/derive_from_request.rs new file mode 100644 index 00000000..2a1625c0 --- /dev/null +++ b/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) -> 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); + +// We create our own rejection type +#[derive(Debug)] +pub struct ApiError { + code: StatusCode, + message: String, +} + +// We implement `From for ApiError` +impl From 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() + } +} diff --git a/examples/customize-extractor-error/src/main.rs b/examples/customize-extractor-error/src/main.rs index 3e41928e..b7b24f76 100644 --- a/examples/customize-extractor-error/src/main.rs +++ b/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::{ - async_trait, - extract::{rejection::JsonRejection, FromRequest, RequestParts}, - http::StatusCode, - routing::post, - BoxError, Router, -}; -use serde::{de::DeserializeOwned, Deserialize}; -use serde_json::{json, Value}; -use std::{borrow::Cow, net::SocketAddr}; +mod custom_extractor; +mod derive_from_request; +mod with_rejection; + +use axum::{routing::post, Router}; +use std::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 - let app = Router::new().route("/users", post(handler)); + // Build our application with some routes + 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) { - 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); - -#[async_trait] -impl FromRequest for Json -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, -{ - type Rejection = (StatusCode, axum::Json); - - async fn from_request(req: &mut RequestParts) -> Result { - match axum::Json::::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 })), - )) - } - } - } -} diff --git a/examples/customize-extractor-error/src/with_rejection.rs b/examples/customize-extractor-error/src/with_rejection.rs new file mode 100644 index 00000000..75f6a265 --- /dev/null +++ b/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` 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, ApiError>, +) -> impl IntoResponse { + Json(dbg!(value)) +} + +// We derive `thiserror::Error` +#[derive(Debug, Error)] +pub enum ApiError { + // The `#[from]` attribute generates `From 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() + } +}