axum_core/extract/
mod.rs

1//! Types and traits for extracting data from requests.
2//!
3//! See [`axum::extract`] for more details.
4//!
5//! [`axum::extract`]: https://docs.rs/axum/0.7/axum/extract/index.html
6
7use crate::{body::Body, response::IntoResponse};
8use async_trait::async_trait;
9use http::request::Parts;
10use std::convert::Infallible;
11
12pub mod rejection;
13
14mod default_body_limit;
15mod from_ref;
16mod request_parts;
17mod tuple;
18
19pub(crate) use self::default_body_limit::DefaultBodyLimitKind;
20pub use self::{default_body_limit::DefaultBodyLimit, from_ref::FromRef};
21
22/// Type alias for [`http::Request`] whose body type defaults to [`Body`], the most common body
23/// type used with axum.
24pub type Request<T = Body> = http::Request<T>;
25
26mod private {
27    #[derive(Debug, Clone, Copy)]
28    pub enum ViaParts {}
29
30    #[derive(Debug, Clone, Copy)]
31    pub enum ViaRequest {}
32}
33
34/// Types that can be created from request parts.
35///
36/// Extractors that implement `FromRequestParts` cannot consume the request body and can thus be
37/// run in any order for handlers.
38///
39/// If your extractor needs to consume the request body then you should implement [`FromRequest`]
40/// and not [`FromRequestParts`].
41///
42/// See [`axum::extract`] for more general docs about extractors.
43///
44/// [`axum::extract`]: https://docs.rs/axum/0.7/axum/extract/index.html
45#[async_trait]
46#[rustversion::attr(
47    since(1.78),
48    diagnostic::on_unimplemented(
49        note = "Function argument is not a valid axum extractor. \nSee `https://docs.rs/axum/0.7/axum/extract/index.html` for details",
50    )
51)]
52pub trait FromRequestParts<S>: Sized {
53    /// If the extractor fails it'll use this "rejection" type. A rejection is
54    /// a kind of error that can be converted into a response.
55    type Rejection: IntoResponse;
56
57    /// Perform the extraction.
58    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection>;
59}
60
61/// Types that can be created from requests.
62///
63/// Extractors that implement `FromRequest` can consume the request body and can thus only be run
64/// once for handlers.
65///
66/// If your extractor doesn't need to consume the request body then you should implement
67/// [`FromRequestParts`] and not [`FromRequest`].
68///
69/// See [`axum::extract`] for more general docs about extractors.
70///
71/// [`axum::extract`]: https://docs.rs/axum/0.7/axum/extract/index.html
72#[async_trait]
73#[rustversion::attr(
74    since(1.78),
75    diagnostic::on_unimplemented(
76        note = "Function argument is not a valid axum extractor. \nSee `https://docs.rs/axum/0.7/axum/extract/index.html` for details",
77    )
78)]
79pub trait FromRequest<S, M = private::ViaRequest>: Sized {
80    /// If the extractor fails it'll use this "rejection" type. A rejection is
81    /// a kind of error that can be converted into a response.
82    type Rejection: IntoResponse;
83
84    /// Perform the extraction.
85    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection>;
86}
87
88#[async_trait]
89impl<S, T> FromRequest<S, private::ViaParts> for T
90where
91    S: Send + Sync,
92    T: FromRequestParts<S>,
93{
94    type Rejection = <Self as FromRequestParts<S>>::Rejection;
95
96    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
97        let (mut parts, _) = req.into_parts();
98        Self::from_request_parts(&mut parts, state).await
99    }
100}
101
102#[async_trait]
103impl<S, T> FromRequestParts<S> for Option<T>
104where
105    T: FromRequestParts<S>,
106    S: Send + Sync,
107{
108    type Rejection = Infallible;
109
110    async fn from_request_parts(
111        parts: &mut Parts,
112        state: &S,
113    ) -> Result<Option<T>, Self::Rejection> {
114        Ok(T::from_request_parts(parts, state).await.ok())
115    }
116}
117
118#[async_trait]
119impl<S, T> FromRequest<S> for Option<T>
120where
121    T: FromRequest<S>,
122    S: Send + Sync,
123{
124    type Rejection = Infallible;
125
126    async fn from_request(req: Request, state: &S) -> Result<Option<T>, Self::Rejection> {
127        Ok(T::from_request(req, state).await.ok())
128    }
129}
130
131#[async_trait]
132impl<S, T> FromRequestParts<S> for Result<T, T::Rejection>
133where
134    T: FromRequestParts<S>,
135    S: Send + Sync,
136{
137    type Rejection = Infallible;
138
139    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
140        Ok(T::from_request_parts(parts, state).await)
141    }
142}
143
144#[async_trait]
145impl<S, T> FromRequest<S> for Result<T, T::Rejection>
146where
147    T: FromRequest<S>,
148    S: Send + Sync,
149{
150    type Rejection = Infallible;
151
152    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
153        Ok(T::from_request(req, state).await)
154    }
155}