axum_core/extract/
default_body_limit.rs

1use self::private::DefaultBodyLimitService;
2use http::Request;
3use tower_layer::Layer;
4
5/// Layer for configuring the default request body limit.
6///
7/// For security reasons, [`Bytes`] will, by default, not accept bodies larger than 2MB. This also
8/// applies to extractors that uses [`Bytes`] internally such as `String`, [`Json`], and [`Form`].
9///
10/// This middleware provides ways to configure that.
11///
12/// Note that if an extractor consumes the body directly with [`Body::poll_frame`], or similar, the
13/// default limit is _not_ applied.
14///
15/// # Difference between `DefaultBodyLimit` and [`RequestBodyLimit`]
16///
17/// `DefaultBodyLimit` and [`RequestBodyLimit`] serve similar functions but in different ways.
18///
19/// `DefaultBodyLimit` is local in that it only applies to [`FromRequest`] implementations that
20/// explicitly apply it (or call another extractor that does). You can apply the limit with
21/// [`RequestExt::with_limited_body`] or [`RequestExt::into_limited_body`]
22///
23/// [`RequestBodyLimit`] is applied globally to all requests, regardless of which extractors are
24/// used or how the body is consumed.
25///
26/// # Example
27///
28/// ```
29/// use axum::{
30///     Router,
31///     routing::post,
32///     body::Body,
33///     extract::{Request, DefaultBodyLimit},
34/// };
35///
36/// let app = Router::new()
37///     .route("/", post(|request: Request| async {}))
38///     // change the default limit
39///     .layer(DefaultBodyLimit::max(1024));
40/// # let _: Router = app;
41/// ```
42///
43/// In general using `DefaultBodyLimit` is recommended but if you need to use third party
44/// extractors and want to make sure a limit is also applied there then [`RequestBodyLimit`] should
45/// be used.
46///
47/// # Different limits for different routes
48///
49/// `DefaultBodyLimit` can also be selectively applied to have different limits for different
50/// routes:
51///
52/// ```
53/// use axum::{
54///     Router,
55///     routing::post,
56///     body::Body,
57///     extract::{Request, DefaultBodyLimit},
58/// };
59///
60/// let app = Router::new()
61///     // this route has a different limit
62///     .route("/", post(|request: Request| async {}).layer(DefaultBodyLimit::max(1024)))
63///     // this route still has the default limit
64///     .route("/foo", post(|request: Request| async {}));
65/// # let _: Router = app;
66/// ```
67///
68/// [`Body::poll_frame`]: http_body::Body::poll_frame
69/// [`Bytes`]: bytes::Bytes
70/// [`Json`]: https://docs.rs/axum/0.8/axum/struct.Json.html
71/// [`Form`]: https://docs.rs/axum/0.8/axum/struct.Form.html
72/// [`FromRequest`]: crate::extract::FromRequest
73/// [`RequestBodyLimit`]: tower_http::limit::RequestBodyLimit
74/// [`RequestExt::with_limited_body`]: crate::RequestExt::with_limited_body
75/// [`RequestExt::into_limited_body`]: crate::RequestExt::into_limited_body
76#[derive(Debug, Clone, Copy)]
77#[must_use]
78pub struct DefaultBodyLimit {
79    kind: DefaultBodyLimitKind,
80}
81
82#[derive(Debug, Clone, Copy)]
83pub(crate) enum DefaultBodyLimitKind {
84    Disable,
85    Limit(usize),
86}
87
88impl DefaultBodyLimit {
89    /// Disable the default request body limit.
90    ///
91    /// This must be used to receive bodies larger than the default limit of 2MB using [`Bytes`] or
92    /// an extractor built on it such as `String`, [`Json`], [`Form`].
93    ///
94    /// Note that if you're accepting data from untrusted remotes it is recommend to add your own
95    /// limit such as [`tower_http::limit`].
96    ///
97    /// # Example
98    ///
99    /// ```
100    /// use axum::{
101    ///     Router,
102    ///     routing::get,
103    ///     body::{Bytes, Body},
104    ///     extract::DefaultBodyLimit,
105    /// };
106    /// use tower_http::limit::RequestBodyLimitLayer;
107    ///
108    /// let app: Router<()> = Router::new()
109    ///     .route("/", get(|body: Bytes| async {}))
110    ///     // Disable the default limit
111    ///     .layer(DefaultBodyLimit::disable())
112    ///     // Set a different limit
113    ///     .layer(RequestBodyLimitLayer::new(10 * 1000 * 1000));
114    /// ```
115    ///
116    /// [`Bytes`]: bytes::Bytes
117    /// [`Json`]: https://docs.rs/axum/0.8/axum/struct.Json.html
118    /// [`Form`]: https://docs.rs/axum/0.8/axum/struct.Form.html
119    pub const fn disable() -> Self {
120        Self {
121            kind: DefaultBodyLimitKind::Disable,
122        }
123    }
124
125    /// Set the default request body limit.
126    ///
127    /// By default the limit of request body sizes that [`Bytes::from_request`] (and other
128    /// extractors built on top of it such as `String`, [`Json`], and [`Form`]) is 2MB. This method
129    /// can be used to change that limit.
130    ///
131    /// # Example
132    ///
133    /// ```
134    /// use axum::{
135    ///     Router,
136    ///     routing::get,
137    ///     body::{Bytes, Body},
138    ///     extract::DefaultBodyLimit,
139    /// };
140    ///
141    /// let app: Router<()> = Router::new()
142    ///     .route("/", get(|body: Bytes| async {}))
143    ///     // Replace the default of 2MB with 1024 bytes.
144    ///     .layer(DefaultBodyLimit::max(1024));
145    /// ```
146    ///
147    /// [`Bytes::from_request`]: bytes::Bytes
148    /// [`Json`]: https://docs.rs/axum/0.8/axum/struct.Json.html
149    /// [`Form`]: https://docs.rs/axum/0.8/axum/struct.Form.html
150    pub const fn max(limit: usize) -> Self {
151        Self {
152            kind: DefaultBodyLimitKind::Limit(limit),
153        }
154    }
155
156    /// Apply a request body limit to the given request.
157    ///
158    /// This can be used, for example, to modify the default body limit inside a specific
159    /// extractor.
160    ///
161    /// # Example
162    ///
163    /// An extractor similar to [`Bytes`](bytes::Bytes), but limiting the body to 1 KB.
164    ///
165    /// ```
166    /// use axum::{
167    ///     extract::{DefaultBodyLimit, FromRequest, rejection::BytesRejection, Request},
168    ///     body::Bytes,
169    /// };
170    ///
171    /// struct Bytes1KB(Bytes);
172    ///
173    /// impl<S: Sync> FromRequest<S> for Bytes1KB {
174    ///     type Rejection = BytesRejection;
175    ///
176    ///     async fn from_request(mut req: Request, _: &S) -> Result<Self, Self::Rejection> {
177    ///         DefaultBodyLimit::max(1024).apply(&mut req);
178    ///         Ok(Self(Bytes::from_request(req, &()).await?))
179    ///     }
180    /// }
181    /// ```
182    pub fn apply<B>(self, req: &mut Request<B>) {
183        req.extensions_mut().insert(self.kind);
184    }
185}
186
187impl<S> Layer<S> for DefaultBodyLimit {
188    type Service = DefaultBodyLimitService<S>;
189
190    fn layer(&self, inner: S) -> Self::Service {
191        DefaultBodyLimitService {
192            inner,
193            kind: self.kind,
194        }
195    }
196}
197
198mod private {
199    use super::DefaultBodyLimitKind;
200    use http::Request;
201    use std::task::Context;
202    use tower_service::Service;
203
204    #[derive(Debug, Clone, Copy)]
205    pub struct DefaultBodyLimitService<S> {
206        pub(super) inner: S,
207        pub(super) kind: DefaultBodyLimitKind,
208    }
209
210    impl<B, S> Service<Request<B>> for DefaultBodyLimitService<S>
211    where
212        S: Service<Request<B>>,
213    {
214        type Response = S::Response;
215        type Error = S::Error;
216        type Future = S::Future;
217
218        #[inline]
219        fn poll_ready(&mut self, cx: &mut Context<'_>) -> std::task::Poll<Result<(), Self::Error>> {
220            self.inner.poll_ready(cx)
221        }
222
223        #[inline]
224        fn call(&mut self, mut req: Request<B>) -> Self::Future {
225            req.extensions_mut().insert(self.kind);
226            self.inner.call(req)
227        }
228    }
229}
axum_core/extract/default_body_limit.rs

axum_core/extract/
default_body_limit.rs
