ycdemo / axum / axum-core/ src/ response/ mod.rs

//! Types and traits for generating responses.
//!
//! See [`axum::response`] for more details.
//!
//! [`axum::response`]: https://docs.rs/axum/0.8/axum/response/index.html

use std::convert::Infallible;

use http::StatusCode;

use crate::body::Body;

mod append_headers;
mod into_response;
mod into_response_parts;

pub use self::{
    append_headers::AppendHeaders,
    into_response::IntoResponse,
    into_response_parts::{IntoResponseParts, ResponseParts, TryIntoHeaderError},
};

/// Type alias for [`http::Response`] whose body type defaults to [`Body`], the most common body
/// type used with axum.
pub type Response<T = Body> = 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)]
#[must_use]
pub struct ErrorResponse(Response);

impl<T> From<T> for ErrorResponse
where
    T: IntoResponse,
{
    fn from(value: T) -> Self {
        Self(value.into_response())
    }
}

/// Response part that stops status code overrides.
///
/// This type should be used by types implementing [`IntoResponseParts`] or
/// [`IntoResponse`] when they fail to produce the response usually expected of
/// them and return some sort of error response instead.
///
/// It is checked used by the tuple impls of [`IntoResponse`] that have a
/// [`StatusCode`] as their first element to ignore that status code.
/// Consider the following example:
///
/// ```no_run
/// # use axum::Json;
/// # use http::StatusCode;
/// # #[derive(serde::Serialize)]
/// # struct CreatedResponse { }
/// fn my_handler(/* ... */) -> (StatusCode, Json<CreatedResponse>) {
///     // This response type's serialization may fail
///     let response = CreatedResponse { /* ... */ };
///     (StatusCode::CREATED, Json(response))
/// }
/// ```
///
/// When `response` serialization succeeds, the server responds with a status
/// code of 201 Created (overwriting `Json`s default status code of 200 OK),
/// and the expected JSON payload.
///
/// When `response` serialization fails hoewever, `impl IntoResponse for Json`
/// return a response with status code 500 Internal Server Error, and
/// `IntoResponseFailed` as a response extension, and the 201 Created override
/// is ignored.
///
/// This is a behavior introduced with axum 0.9.\
/// To force a status code override even when an inner [`IntoResponseParts`] /
/// [`IntoResponse`] failed, use [`ForceStatusCode`].
#[derive(Copy, Clone, Debug)]
pub struct IntoResponseFailed;

impl IntoResponseParts for IntoResponseFailed {
    type Error = Infallible;

    fn into_response_parts(self, mut res: ResponseParts) -> Result<ResponseParts, Self::Error> {
        res.extensions_mut().insert(self);
        Ok(res)
    }
}

/// Not sure it makes sense to return `IntoResponseFailed` as the whole response. You should
/// probably at least combine it with a status code.
///
/// ```compile_fail
/// fn foo()
/// where
///     axum_core::response::IntoResponseFailed: axum_core::response::IntoResponse,
/// {}
/// ```
#[allow(dead_code)]
fn into_response_failed_doesnt_impl_into_response() {}

/// Set the status code regardless of whether [`IntoResponseFailed`] is used or not.
///
/// See the docs for [`IntoResponseFailed`] for more details.
#[derive(Debug, Copy, Clone, Default)]
pub struct ForceStatusCode(pub StatusCode);

impl IntoResponse for ForceStatusCode {
    fn into_response(self) -> Response {
        let mut res = ().into_response();
        *res.status_mut() = self.0;
        res
    }
}

impl<R> IntoResponse for (ForceStatusCode, R)
where
    R: IntoResponse,
{
    fn into_response(self) -> Response {
        let (ForceStatusCode(status), res) = self;
        let mut res = res.into_response();
        *res.status_mut() = status;
        res
    }
}