Struct Form

pub struct Form<T>(/* private fields */);

A data guard for FromForm types.

This type implements the FromData trait. It provides a generic means to parse arbitrary structures from incoming form data.

See the forms guide for general form support documentation.

Leniency

A Form<T> will parse successfully from an incoming form if the form contains a superset of the fields in T. Said another way, a Form<T> automatically discards extra fields without error. For instance, if an incoming form contains the fields “a”, “b”, and “c” while T only contains “a” and “c”, the form will parse as Form<T>. To parse strictly, use the Strict form guard.

Usage

This type can be used with any type that implements the FromForm trait. The trait can be automatically derived; see the FromForm documentation for more information on deriving or implementing the trait.

Because Form implements FromData, it can be used directly as a target of the data = "<param>" route parameter as long as its generic type implements the FromForm trait:

use rocket::form::Form;
use rocket::http::RawStr;

#[derive(FromForm)]
struct UserInput<'r> {
    value: &'r str
}

#[post("/submit", data = "<user_input>")]
fn submit_task(user_input: Form<UserInput<'_>>) -> String {
    format!("Your value: {}", user_input.value)
}

A type of Form<T> automatically dereferences into an &T or &mut T, though you can also transform a Form<T> into a T by calling into_inner(). Thanks to automatic dereferencing, you can access fields of T transparently through a Form<T>, as seen above with user_input.value.

Errors

A Form<T> data guard may fail, forward, or succeed.

If a request’s content-type is neither ContentType::Form nor ContentType::FormData, the guard forwards.

If the request ContentType does identify as a form but the form data does not parse as T, according to T’s FromForm implementation, the guard fails. The Error variant contains a vector of the Errors emitted by T’s FromForm parser. If the error is not caught by a form::Result<T> or Option<Form<T>> data guard, the status code is set to Errors::status(), and the corresponding error catcher is called.

Otherwise the guard succeeds.

Data Limits

The total amount of data accepted by the Form data guard is limited by the following limits:

Limit Name	Default	Description
form	32KiB	total limit for url-encoded forms
data-form	2MiB	total limit for multipart forms
*	N/A	each field type has its own limits

As noted above, each form field type (a form guard) typically imposes its own limits. For example, the &str form guard imposes a data limit of string when multipart data is streamed.

URL-Encoded Forms

The form limit specifies the data limit for an entire url-encoded form data. It defaults to 32KiB. URL-encoded form data is percent-decoded, stored in-memory, and parsed into ValueFields. If the incoming data exceeds this limit, the Form data guard fails without attempting to parse fields with a 413: Payload Too Large error.

Multipart Forms

The data-form limit specifies the data limit for an entire multipart form data stream. It defaults to 2MiB. Multipart data is streamed, and form fields are processed into DataFields or ValueFields as they arrive. If the commutative data received while streaming exceeds the limit, parsing is aborted, an error is created and pushed via FromForm::push_error(), and the form is finalized.

Individual Fields

Individual fields may have data limits as well. The type of the field determines whether there is a data limit. For instance, the &str type imposes the string data limit. Consult the type’s documentation or FromFormField for details.

Changing Limits

To change data limits, set the limits.form and/or limits.data-form configuration parameters. For instance, to increase the URL-encoded forms limit to 128KiB for all environments, you might add the following to your Rocket.toml:

[global.limits]
form = 128KiB

See the Limits and config docs for more.

Implementations

impl<T> Form<T>

pub fn into_inner(self) -> T

Consumes self and returns the inner value.

Note that since Form implements Deref and DerefMut with target T, reading and writing an inner value can be accomplished transparently.

Example

use rocket::form::Form;

#[derive(FromForm)]
struct MyForm {
    field: String,
}

#[post("/submit", data = "<form>")]
fn submit(form: Form<MyForm>) -> String {
    // We can read or mutate a value transparently:
    let field: &str = &form.field;

    // To gain ownership, however, use `into_inner()`:
    form.into_inner().field
}

impl<'r, T: FromForm<'r>> Form<T>

pub fn parse(string: &'r str) -> Result<'r, T>

Leniently parses a T from a percent-decoded x-www-form-urlencoded form string. Specifically, this method implements §5.1 of the WHATWG URL Living Standard with the exception of steps 3.4 and 3.5, which are assumed to already be reflected in string, and then parses the fields as T.

Example

use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct Pet<'r> {
    name: &'r str,
    wags: bool,
}

let string = "name=Benson Wagger!&wags=true";
let pet: Pet<'_> = Form::parse(string).unwrap();
assert_eq!(pet.name, "Benson Wagger!");
assert_eq!(pet.wags, true);

pub fn parse_iter<I>(fields: I) -> Result<'r, T>

where I: IntoIterator<Item = ValueField<'r>>,

Leniently parses a T from the percent-decoded fields. Specifically, this method implements §5.1 of the WHATWG URL Living Standard with the exception of step 3.

Example

use rocket::form::{Form, FromForm, ValueField};

#[derive(FromForm)]
struct Pet<'r> {
    name: &'r str,
    wags: bool,
}

let fields = vec![
    ValueField::parse("name=Bob, the cat. :)"),
    ValueField::parse("wags=no"),
];

let pet: Pet<'_> = Form::parse_iter(fields).unwrap();
assert_eq!(pet.name, "Bob, the cat. :)");
assert_eq!(pet.wags, false);

impl<T: for<'a> FromForm<'a> + 'static> Form<T>

pub fn parse_encoded(string: &RawStr) -> Result<'static, T>

Leniently parses a T from a raw, x-www-form-urlencoded form string. Specifically, this method implements §5.1 of the WHATWG URL Living Standard. Because percent-decoding might modify the input string, the output type T must be 'static.

Example

use rocket::http::RawStr;
use rocket::form::{Form, FromForm};

#[derive(FromForm)]
struct Pet {
    name: String,
    wags: bool,
}

let string = RawStr::new("name=Benson+Wagger%21&wags=true");
let pet: Pet = Form::parse_encoded(string).unwrap();
assert_eq!(pet.name, "Benson Wagger!");
assert_eq!(pet.wags, true);

impl Form<()>

pub fn values(string: &str) -> impl Iterator<Item = ValueField<'_>>

Returns an iterator of fields parsed from a x-www-form-urlencoded form string. Specifically, this method implements steps 1, 2, and 3.1 - 3.3 of §5.1 of the WHATWG URL Living Standard. Fields in the returned iterator are not percent-decoded.

Example

use rocket::form::{Form, ValueField};

let string = "name=Bobby Brown&&&email=me@rocket.rs";
let mut values = Form::values(string);
assert_eq!(values.next().unwrap(), ValueField::parse("name=Bobby Brown"));
assert_eq!(values.next().unwrap(), ValueField::parse("email=me@rocket.rs"));
assert!(values.next().is_none());

Trait Implementations

impl<T: Debug> Debug for Form<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Deref for Form<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Form<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T> From<T> for Form<T>

fn from(val: T) -> Form<T>

Converts to this type from the input type.

impl<'r, T: FromForm<'r>> FromData<'r> for Form<T>

type Error = Errors<'r>

The associated error to be returned when the guard fails.

fn from_data<'life0, 'async_trait>( req: &'r Request<'life0>, data: Data<'r>, ) -> Pin<Box<dyn Future<Output = Outcome<'r, Self>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Asynchronously validates, parses, and converts an instance of Self from the incoming request body data.

impl<T: Ord> Ord for Form<T>

fn cmp(&self, other: &Form<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq for Form<T>

fn eq(&self, other: &Form<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd> PartialOrd for Form<T>

fn partial_cmp(&self, other: &Form<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq> Eq for Form<T>

impl<T> StructuralPartialEq for Form<T>