actix_web/types/
form.rs

1//! For URL encoded form helper documentation, see [`Form`].
2
3use std::{
4    borrow::Cow,
5    fmt,
6    future::Future,
7    ops,
8    pin::Pin,
9    rc::Rc,
10    task::{Context, Poll},
11};
12
13use actix_http::Payload;
14use bytes::BytesMut;
15use encoding_rs::{Encoding, UTF_8};
16use futures_core::{future::LocalBoxFuture, ready};
17use futures_util::{FutureExt as _, StreamExt as _};
18use serde::{de::DeserializeOwned, Serialize};
19
20#[cfg(feature = "__compress")]
21use crate::dev::Decompress;
22use crate::{
23    body::EitherBody, error::UrlencodedError, extract::FromRequest, http::header::CONTENT_LENGTH,
24    web, Error, HttpMessage, HttpRequest, HttpResponse, Responder,
25};
26
27/// URL encoded payload extractor and responder.
28///
29/// `Form` has two uses: URL encoded responses, and extracting typed data from URL request payloads.
30///
31/// # Extractor
32/// To extract typed data from a request body, the inner type `T` must implement the
33/// [`DeserializeOwned`] trait.
34///
35/// Use [`FormConfig`] to configure extraction options.
36///
37/// ## Examples
38/// ```
39/// use actix_web::{post, web};
40/// use serde::Deserialize;
41///
42/// #[derive(Deserialize)]
43/// struct Info {
44///     name: String,
45/// }
46///
47/// // This handler is only called if:
48/// // - request headers declare the content type as `application/x-www-form-urlencoded`
49/// // - request payload deserializes into an `Info` struct from the URL encoded format
50/// #[post("/")]
51/// async fn index(web::Form(form): web::Form<Info>) -> String {
52///     format!("Welcome {}!", form.name)
53/// }
54/// ```
55///
56/// # Responder
57/// The `Form` type also allows you to create URL encoded responses by returning a value of type
58/// `Form<T>` where `T` is the type to be URL encoded, as long as `T` implements [`Serialize`].
59///
60/// ## Examples
61/// ```
62/// use actix_web::{get, web};
63/// use serde::Serialize;
64///
65/// #[derive(Serialize)]
66/// struct SomeForm {
67///     name: String,
68///     age: u8
69/// }
70///
71/// // Response will have:
72/// // - status: 200 OK
73/// // - header: `Content-Type: application/x-www-form-urlencoded`
74/// // - body: `name=actix&age=123`
75/// #[get("/")]
76/// async fn index() -> web::Form<SomeForm> {
77///     web::Form(SomeForm {
78///         name: "actix".to_owned(),
79///         age: 123
80///     })
81/// }
82/// ```
83///
84/// # Panics
85/// URL encoded forms consist of unordered `key=value` pairs, therefore they cannot be decoded into
86/// any type which depends upon data ordering (eg. tuples). Trying to do so will result in a panic.
87#[derive(PartialEq, Eq, PartialOrd, Ord, Debug)]
88pub struct Form<T>(pub T);
89
90impl<T> Form<T> {
91    /// Unwrap into inner `T` value.
92    pub fn into_inner(self) -> T {
93        self.0
94    }
95}
96
97impl<T> ops::Deref for Form<T> {
98    type Target = T;
99
100    fn deref(&self) -> &T {
101        &self.0
102    }
103}
104
105impl<T> ops::DerefMut for Form<T> {
106    fn deref_mut(&mut self) -> &mut T {
107        &mut self.0
108    }
109}
110
111impl<T> Serialize for Form<T>
112where
113    T: Serialize,
114{
115    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
116    where
117        S: serde::Serializer,
118    {
119        self.0.serialize(serializer)
120    }
121}
122
123/// See [here](#extractor) for example of usage as an extractor.
124impl<T> FromRequest for Form<T>
125where
126    T: DeserializeOwned + 'static,
127{
128    type Error = Error;
129    type Future = FormExtractFut<T>;
130
131    #[inline]
132    fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future {
133        let FormConfig { limit, err_handler } = FormConfig::from_req(req).clone();
134
135        FormExtractFut {
136            fut: UrlEncoded::new(req, payload).limit(limit),
137            req: req.clone(),
138            err_handler,
139        }
140    }
141}
142
143type FormErrHandler = Option<Rc<dyn Fn(UrlencodedError, &HttpRequest) -> Error>>;
144
145pub struct FormExtractFut<T> {
146    fut: UrlEncoded<T>,
147    err_handler: FormErrHandler,
148    req: HttpRequest,
149}
150
151impl<T> Future for FormExtractFut<T>
152where
153    T: DeserializeOwned + 'static,
154{
155    type Output = Result<Form<T>, Error>;
156
157    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
158        let this = self.get_mut();
159
160        let res = ready!(Pin::new(&mut this.fut).poll(cx));
161
162        let res = match res {
163            Err(err) => match &this.err_handler {
164                Some(err_handler) => Err((err_handler)(err, &this.req)),
165                None => Err(err.into()),
166            },
167            Ok(item) => Ok(Form(item)),
168        };
169
170        Poll::Ready(res)
171    }
172}
173
174impl<T: fmt::Display> fmt::Display for Form<T> {
175    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
176        self.0.fmt(f)
177    }
178}
179
180/// See [here](#responder) for example of usage as a handler return type.
181impl<T: Serialize> Responder for Form<T> {
182    type Body = EitherBody<String>;
183
184    fn respond_to(self, _: &HttpRequest) -> HttpResponse<Self::Body> {
185        match serde_urlencoded::to_string(&self.0) {
186            Ok(body) => match HttpResponse::Ok()
187                .content_type(mime::APPLICATION_WWW_FORM_URLENCODED)
188                .message_body(body)
189            {
190                Ok(res) => res.map_into_left_body(),
191                Err(err) => HttpResponse::from_error(err).map_into_right_body(),
192            },
193
194            Err(err) => {
195                HttpResponse::from_error(UrlencodedError::Serialize(err)).map_into_right_body()
196            }
197        }
198    }
199}
200
201/// [`Form`] extractor configuration.
202///
203/// ```
204/// use actix_web::{post, web, App, FromRequest, Result};
205/// use serde::Deserialize;
206///
207/// #[derive(Deserialize)]
208/// struct Info {
209///     username: String,
210/// }
211///
212/// // Custom `FormConfig` is applied to App.
213/// // Max payload size for URL encoded forms is set to 4kB.
214/// #[post("/")]
215/// async fn index(form: web::Form<Info>) -> Result<String> {
216///     Ok(format!("Welcome {}!", form.username))
217/// }
218///
219/// App::new()
220///     .app_data(web::FormConfig::default().limit(4096))
221///     .service(index);
222/// ```
223#[derive(Clone)]
224pub struct FormConfig {
225    limit: usize,
226    err_handler: FormErrHandler,
227}
228
229impl FormConfig {
230    /// Set maximum accepted payload size. By default this limit is 16kB.
231    pub fn limit(mut self, limit: usize) -> Self {
232        self.limit = limit;
233        self
234    }
235
236    /// Set custom error handler
237    pub fn error_handler<F>(mut self, f: F) -> Self
238    where
239        F: Fn(UrlencodedError, &HttpRequest) -> Error + 'static,
240    {
241        self.err_handler = Some(Rc::new(f));
242        self
243    }
244
245    /// Extract payload config from app data.
246    ///
247    /// Checks both `T` and `Data<T>`, in that order, and falls back to the default payload config.
248    fn from_req(req: &HttpRequest) -> &Self {
249        req.app_data::<Self>()
250            .or_else(|| req.app_data::<web::Data<Self>>().map(|d| d.as_ref()))
251            .unwrap_or(&DEFAULT_CONFIG)
252    }
253}
254
255/// Allow shared refs used as default.
256const DEFAULT_CONFIG: FormConfig = FormConfig {
257    limit: 16_384, // 2^14 bytes (~16kB)
258    err_handler: None,
259};
260
261impl Default for FormConfig {
262    fn default() -> Self {
263        DEFAULT_CONFIG
264    }
265}
266
267/// Future that resolves to some `T` when parsed from a URL encoded payload.
268///
269/// Form can be deserialized from any type `T` that implements [`serde::Deserialize`].
270///
271/// Returns error if:
272/// - content type is not `application/x-www-form-urlencoded`
273/// - content length is greater than [limit](UrlEncoded::limit())
274pub struct UrlEncoded<T> {
275    #[cfg(feature = "__compress")]
276    stream: Option<Decompress<Payload>>,
277    #[cfg(not(feature = "__compress"))]
278    stream: Option<Payload>,
279
280    limit: usize,
281    length: Option<usize>,
282    encoding: &'static Encoding,
283    err: Option<UrlencodedError>,
284    fut: Option<LocalBoxFuture<'static, Result<T, UrlencodedError>>>,
285}
286
287#[allow(clippy::borrow_interior_mutable_const)]
288impl<T> UrlEncoded<T> {
289    /// Create a new future to decode a URL encoded request payload.
290    pub fn new(req: &HttpRequest, payload: &mut Payload) -> Self {
291        // check content type
292        if req.content_type().to_lowercase() != "application/x-www-form-urlencoded" {
293            return Self::err(UrlencodedError::ContentType);
294        }
295        let encoding = match req.encoding() {
296            Ok(enc) => enc,
297            Err(_) => return Self::err(UrlencodedError::ContentType),
298        };
299
300        let mut len = None;
301        if let Some(l) = req.headers().get(&CONTENT_LENGTH) {
302            if let Ok(s) = l.to_str() {
303                if let Ok(l) = s.parse::<usize>() {
304                    len = Some(l)
305                } else {
306                    return Self::err(UrlencodedError::UnknownLength);
307                }
308            } else {
309                return Self::err(UrlencodedError::UnknownLength);
310            }
311        };
312
313        let payload = {
314            cfg_if::cfg_if! {
315                if #[cfg(feature = "__compress")] {
316                    Decompress::from_headers(payload.take(), req.headers())
317                } else {
318                    payload.take()
319                }
320            }
321        };
322
323        UrlEncoded {
324            encoding,
325            stream: Some(payload),
326            limit: 32_768,
327            length: len,
328            fut: None,
329            err: None,
330        }
331    }
332
333    fn err(err: UrlencodedError) -> Self {
334        UrlEncoded {
335            stream: None,
336            limit: 32_768,
337            fut: None,
338            err: Some(err),
339            length: None,
340            encoding: UTF_8,
341        }
342    }
343
344    /// Set maximum accepted payload size. The default limit is 256kB.
345    pub fn limit(mut self, limit: usize) -> Self {
346        self.limit = limit;
347        self
348    }
349}
350
351impl<T> Future for UrlEncoded<T>
352where
353    T: DeserializeOwned + 'static,
354{
355    type Output = Result<T, UrlencodedError>;
356
357    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
358        if let Some(ref mut fut) = self.fut {
359            return Pin::new(fut).poll(cx);
360        }
361
362        if let Some(err) = self.err.take() {
363            return Poll::Ready(Err(err));
364        }
365
366        // payload size
367        let limit = self.limit;
368        if let Some(len) = self.length.take() {
369            if len > limit {
370                return Poll::Ready(Err(UrlencodedError::Overflow { size: len, limit }));
371            }
372        }
373
374        // future
375        let encoding = self.encoding;
376        let mut stream = self.stream.take().unwrap();
377
378        self.fut = Some(
379            async move {
380                let mut body = BytesMut::with_capacity(8192);
381
382                while let Some(item) = stream.next().await {
383                    let chunk = item?;
384
385                    if (body.len() + chunk.len()) > limit {
386                        return Err(UrlencodedError::Overflow {
387                            size: body.len() + chunk.len(),
388                            limit,
389                        });
390                    } else {
391                        body.extend_from_slice(&chunk);
392                    }
393                }
394
395                if encoding == UTF_8 {
396                    serde_urlencoded::from_bytes::<T>(&body).map_err(UrlencodedError::Parse)
397                } else {
398                    let body = encoding
399                        .decode_without_bom_handling_and_without_replacement(&body)
400                        .map(Cow::into_owned)
401                        .ok_or(UrlencodedError::Encoding)?;
402
403                    serde_urlencoded::from_str::<T>(&body).map_err(UrlencodedError::Parse)
404                }
405            }
406            .boxed_local(),
407        );
408
409        self.poll(cx)
410    }
411}
412
413#[cfg(test)]
414mod tests {
415    use bytes::Bytes;
416    use serde::{Deserialize, Serialize};
417
418    use super::*;
419    use crate::{
420        http::{
421            header::{HeaderValue, CONTENT_TYPE},
422            StatusCode,
423        },
424        test::{assert_body_eq, TestRequest},
425    };
426
427    #[derive(Deserialize, Serialize, Debug, PartialEq)]
428    struct Info {
429        hello: String,
430        counter: i64,
431    }
432
433    #[actix_rt::test]
434    async fn test_form() {
435        let (req, mut pl) = TestRequest::default()
436            .insert_header((CONTENT_TYPE, "application/x-www-form-urlencoded"))
437            .insert_header((CONTENT_LENGTH, 11))
438            .set_payload(Bytes::from_static(b"hello=world&counter=123"))
439            .to_http_parts();
440
441        let Form(s) = Form::<Info>::from_request(&req, &mut pl).await.unwrap();
442        assert_eq!(
443            s,
444            Info {
445                hello: "world".into(),
446                counter: 123
447            }
448        );
449    }
450
451    fn eq(err: UrlencodedError, other: UrlencodedError) -> bool {
452        match err {
453            UrlencodedError::Overflow { .. } => {
454                matches!(other, UrlencodedError::Overflow { .. })
455            }
456            UrlencodedError::UnknownLength => matches!(other, UrlencodedError::UnknownLength),
457            UrlencodedError::ContentType => matches!(other, UrlencodedError::ContentType),
458            _ => false,
459        }
460    }
461
462    #[actix_rt::test]
463    async fn test_urlencoded_error() {
464        let (req, mut pl) = TestRequest::default()
465            .insert_header((CONTENT_TYPE, "application/x-www-form-urlencoded"))
466            .insert_header((CONTENT_LENGTH, "xxxx"))
467            .to_http_parts();
468        let info = UrlEncoded::<Info>::new(&req, &mut pl).await;
469        assert!(eq(info.err().unwrap(), UrlencodedError::UnknownLength));
470
471        let (req, mut pl) = TestRequest::default()
472            .insert_header((CONTENT_TYPE, "application/x-www-form-urlencoded"))
473            .insert_header((CONTENT_LENGTH, "1000000"))
474            .to_http_parts();
475        let info = UrlEncoded::<Info>::new(&req, &mut pl).await;
476        assert!(eq(
477            info.err().unwrap(),
478            UrlencodedError::Overflow { size: 0, limit: 0 }
479        ));
480
481        let (req, mut pl) = TestRequest::default()
482            .insert_header((CONTENT_TYPE, "text/plain"))
483            .insert_header((CONTENT_LENGTH, 10))
484            .to_http_parts();
485        let info = UrlEncoded::<Info>::new(&req, &mut pl).await;
486        assert!(eq(info.err().unwrap(), UrlencodedError::ContentType));
487    }
488
489    #[actix_rt::test]
490    async fn test_urlencoded() {
491        let (req, mut pl) = TestRequest::default()
492            .insert_header((CONTENT_TYPE, "application/x-www-form-urlencoded"))
493            .insert_header((CONTENT_LENGTH, 11))
494            .set_payload(Bytes::from_static(b"hello=world&counter=123"))
495            .to_http_parts();
496
497        let info = UrlEncoded::<Info>::new(&req, &mut pl).await.unwrap();
498        assert_eq!(
499            info,
500            Info {
501                hello: "world".to_owned(),
502                counter: 123
503            }
504        );
505
506        let (req, mut pl) = TestRequest::default()
507            .insert_header((
508                CONTENT_TYPE,
509                "application/x-www-form-urlencoded; charset=utf-8",
510            ))
511            .insert_header((CONTENT_LENGTH, 11))
512            .set_payload(Bytes::from_static(b"hello=world&counter=123"))
513            .to_http_parts();
514
515        let info = UrlEncoded::<Info>::new(&req, &mut pl).await.unwrap();
516        assert_eq!(
517            info,
518            Info {
519                hello: "world".to_owned(),
520                counter: 123
521            }
522        );
523    }
524
525    #[actix_rt::test]
526    async fn test_responder() {
527        let req = TestRequest::default().to_http_request();
528
529        let form = Form(Info {
530            hello: "world".to_string(),
531            counter: 123,
532        });
533        let res = form.respond_to(&req);
534        assert_eq!(res.status(), StatusCode::OK);
535        assert_eq!(
536            res.headers().get(CONTENT_TYPE).unwrap(),
537            HeaderValue::from_static("application/x-www-form-urlencoded")
538        );
539        assert_body_eq!(res, b"hello=world&counter=123");
540    }
541
542    #[actix_rt::test]
543    async fn test_with_config_in_data_wrapper() {
544        let ctype = HeaderValue::from_static("application/x-www-form-urlencoded");
545
546        let (req, mut pl) = TestRequest::default()
547            .insert_header((CONTENT_TYPE, ctype))
548            .insert_header((CONTENT_LENGTH, HeaderValue::from_static("20")))
549            .set_payload(Bytes::from_static(b"hello=test&counter=4"))
550            .app_data(web::Data::new(FormConfig::default().limit(10)))
551            .to_http_parts();
552
553        let s = Form::<Info>::from_request(&req, &mut pl).await;
554        assert!(s.is_err());
555
556        let err_str = s.err().unwrap().to_string();
557        assert!(err_str.starts_with("URL encoded payload is larger"));
558    }
559}