Add response::ErrorResponse and response::Result (#921)

* feat: add response::{Error, Result}

This type makes for efficient use of the `?` operator when in a function
with multiple return error types that all implement `IntoResponse`.

Signed-off-by: Nathaniel McCallum <[email protected]>

* misc adjustments from PR review

* Rename to `ErrorResponse` and `ResultResponse`

* nitpicky docs changes

* update changelog

* changelog wording

* Apply suggestions from code review

Co-authored-by: Jonas Platte <[email protected]>

Co-authored-by: David Pedersen <[email protected]>
Co-authored-by: Jonas Platte <[email protected]>

axum-core/CHANGELOG.md

@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
-- None.
+- **added:** Add `response::ErrorResponse` and `response::Result` for
+  `IntoResponse`-based error handling ([#921])
+
+[#921]: https://github.com/tokio-rs/axum/pull/921 
 
 # 0.2.2 (19. April, 2022)
 

axum-core/src/response/mod.rs

@@ -19,3 +19,111 @@ pub use self::{
 /// Type alias for [`http::Response`] whose body type defaults to [`BoxBody`], the most common body
 /// type used with axum.
 pub type Response<T = BoxBody> = http::Response<T>;
+
+/// An [`IntoResponse`]-based result type that uses [`ErrorResponse`] as the error type.
+///
+/// All types which implement [`IntoResponse`] can be converted to an [`ErrorResponse`]. This makes
+/// it useful as a general purpose error type for functions which combine multiple distinct error
+/// types that all implement [`IntoResponse`].
+///
+/// # Example
+///
+/// ```
+/// use axum::{
+///     response::{IntoResponse, Response},
+///     http::StatusCode,
+/// };
+///
+/// // two fallible functions with different error types
+/// fn try_something() -> Result<(), ErrorA> {
+///     // ...
+///     # unimplemented!()
+/// }
+///
+/// fn try_something_else() -> Result<(), ErrorB> {
+///     // ...
+///     # unimplemented!()
+/// }
+///
+/// // each error type implements `IntoResponse`
+/// struct ErrorA;
+///
+/// impl IntoResponse for ErrorA {
+///     fn into_response(self) -> Response {
+///         // ...
+///         # unimplemented!()
+///     }
+/// }
+///
+/// enum ErrorB {
+///     SomethingWentWrong,
+/// }
+///
+/// impl IntoResponse for ErrorB {
+///     fn into_response(self) -> Response {
+///         // ...
+///         # unimplemented!()
+///     }
+/// }
+///
+/// // we can combine them using `axum::response::Result` and still use `?`
+/// async fn handler() -> axum::response::Result<&'static str> {
+///     // the errors are automatically converted to `ErrorResponse`
+///     try_something()?;
+///     try_something_else()?;
+///
+///     Ok("it worked!")
+/// }
+/// ```
+///
+/// # As a replacement for `std::result::Result`
+///
+/// Since `axum::response::Result` has a default error type you only have to specify the `Ok` type:
+///
+/// ```
+/// use axum::{
+///     response::{IntoResponse, Response, Result},
+///     http::StatusCode,
+/// };
+///
+/// // `Result<T>` automatically uses `ErrorResponse` as the error type.
+/// async fn handler() -> Result<&'static str> {
+///     try_something()?;
+///
+///     Ok("it worked!")
+/// }
+///
+/// // You can still specify the error even if you've imported `axum::response::Result`
+/// fn try_something() -> Result<(), StatusCode> {
+///     // ...
+///     # unimplemented!()
+/// }
+/// ```
+pub type Result<T, E = ErrorResponse> = std::result::Result<T, E>;
+
+impl<T> IntoResponse for Result<T>
+where
+    T: IntoResponse,
+{
+    fn into_response(self) -> Response {
+        match self {
+            Ok(ok) => ok.into_response(),
+            Err(err) => err.0,
+        }
+    }
+}
+
+/// An [`IntoResponse`]-based error type
+///
+/// See [`Result`] for more details.
+#[derive(Debug)]
+pub struct ErrorResponse(Response);
+
+impl<T> From<T> for ErrorResponse
+where
+    T: IntoResponse,
+{
+    fn from(value: T) -> Self {
+        Self(value.into_response())
+    }
+}

axum/CHANGELOG.md

@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
-- None.
+- **added:** Add `response::ErrorResponse` and `response::Result` for
+  `IntoResponse`-based error handling ([#921])
+
+[#921]: https://github.com/tokio-rs/axum/pull/921 
 
 # 0.5.3 (19. April, 2022)
 

axum/src/response/mod.rs

@@ -20,7 +20,7 @@ pub use crate::Extension;
 
 #[doc(inline)]
 pub use axum_core::response::{
-    AppendHeaders, IntoResponse, IntoResponseParts, Response, ResponseParts,
+    AppendHeaders, ErrorResponse, IntoResponse, IntoResponseParts, Response, ResponseParts, Result,
 };
 
 #[doc(inline)]