1 //! Types and traits for generating responses.
2 //!
3 //! See [`axum::response`] for more details.
4 //!
5 //! [`axum::response`]: https://docs.rs/axum/latest/axum/response/index.html
6 
7 use crate::body::BoxBody;
8 
9 mod append_headers;
10 mod into_response;
11 mod into_response_parts;
12 
13 pub use self::{
14     append_headers::AppendHeaders,
15     into_response::IntoResponse,
16     into_response_parts::{IntoResponseParts, ResponseParts, TryIntoHeaderError},
17 };
18 
19 /// Type alias for [`http::Response`] whose body type defaults to [`BoxBody`], the most common body
20 /// type used with axum.
21 pub type Response<T = BoxBody> = http::Response<T>;
22 
23 /// An [`IntoResponse`]-based result type that uses [`ErrorResponse`] as the error type.
24 ///
25 /// All types which implement [`IntoResponse`] can be converted to an [`ErrorResponse`]. This makes
26 /// it useful as a general purpose error type for functions which combine multiple distinct error
27 /// types that all implement [`IntoResponse`].
28 ///
29 /// # Example
30 ///
31 /// ```
32 /// use axum::{
33 ///     response::{IntoResponse, Response},
34 ///     http::StatusCode,
35 /// };
36 ///
37 /// // two fallible functions with different error types
38 /// fn try_something() -> Result<(), ErrorA> {
39 ///     // ...
40 ///     # unimplemented!()
41 /// }
42 ///
43 /// fn try_something_else() -> Result<(), ErrorB> {
44 ///     // ...
45 ///     # unimplemented!()
46 /// }
47 ///
48 /// // each error type implements `IntoResponse`
49 /// struct ErrorA;
50 ///
51 /// impl IntoResponse for ErrorA {
52 ///     fn into_response(self) -> Response {
53 ///         // ...
54 ///         # unimplemented!()
55 ///     }
56 /// }
57 ///
58 /// enum ErrorB {
59 ///     SomethingWentWrong,
60 /// }
61 ///
62 /// impl IntoResponse for ErrorB {
63 ///     fn into_response(self) -> Response {
64 ///         // ...
65 ///         # unimplemented!()
66 ///     }
67 /// }
68 ///
69 /// // we can combine them using `axum::response::Result` and still use `?`
70 /// async fn handler() -> axum::response::Result<&'static str> {
71 ///     // the errors are automatically converted to `ErrorResponse`
72 ///     try_something()?;
73 ///     try_something_else()?;
74 ///
75 ///     Ok("it worked!")
76 /// }
77 /// ```
78 ///
79 /// # As a replacement for `std::result::Result`
80 ///
81 /// Since `axum::response::Result` has a default error type you only have to specify the `Ok` type:
82 ///
83 /// ```
84 /// use axum::{
85 ///     response::{IntoResponse, Response, Result},
86 ///     http::StatusCode,
87 /// };
88 ///
89 /// // `Result<T>` automatically uses `ErrorResponse` as the error type.
90 /// async fn handler() -> Result<&'static str> {
91 ///     try_something()?;
92 ///
93 ///     Ok("it worked!")
94 /// }
95 ///
96 /// // You can still specify the error even if you've imported `axum::response::Result`
97 /// fn try_something() -> Result<(), StatusCode> {
98 ///     // ...
99 ///     # unimplemented!()
100 /// }
101 /// ```
102 pub type Result<T, E = ErrorResponse> = std::result::Result<T, E>;
103 
104 impl<T> IntoResponse for Result<T>
105 where
106     T: IntoResponse,
107 {
into_response(self) -> Response108     fn into_response(self) -> Response {
109         match self {
110             Ok(ok) => ok.into_response(),
111             Err(err) => err.0,
112         }
113     }
114 }
115 
116 /// An [`IntoResponse`]-based error type
117 ///
118 /// See [`Result`] for more details.
119 #[derive(Debug)]
120 pub struct ErrorResponse(Response);
121 
122 impl<T> From<T> for ErrorResponse
123 where
124     T: IntoResponse,
125 {
from(value: T) -> Self126     fn from(value: T) -> Self {
127         Self(value.into_response())
128     }
129 }
130