From 560213a7b7aa772de322419a2cda124c4b1c1fe0 Mon Sep 17 00:00:00 2001 From: "Dotan J. Nahum" Date: Fri, 29 Dec 2023 15:19:16 +0200 Subject: [PATCH] docs: add clarification about building middleware and error types (#2448) --- axum/src/docs/middleware.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/axum/src/docs/middleware.md b/axum/src/docs/middleware.md index 4496b721..4ba977b4 100644 --- a/axum/src/docs/middleware.md +++ b/axum/src/docs/middleware.md @@ -264,6 +264,21 @@ where } ``` +Note that your error type being defined as `S::Error` means that your middleware typically _returns no errors_. As a principle always try to return a response and try not to bail out with a custom error type. For example, if a 3rd party library you are using inside your new middleware returns its own specialized error type, try to convert it to some reasonable response and return `Ok` with that response. + +If you choose to implement a custom error type such as `type Error = BoxError` (a boxed opaque error), or any other error type that is not `Infallible`, you must use a `HandleErrorLayer`, here is an example using a `ServiceBuilder`: + +```ignore +ServiceBuilder::new() + .layer(HandleErrorLayer::new(|_: BoxError| async { + // because Axum uses infallible errors, you must handle your custom error type from your middleware here + StatusCode::BAD_REQUEST + })) + .layer( + // + ); +``` + ## `tower::Service` and custom futures If you're comfortable implementing your own futures (or want to learn it) and