logo
pub struct Form<T>(_);
Expand description

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.

Data Limits

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

Limit NameDefaultDescription
form32KiBtotal limit for url-encoded forms
data-form2MiBtotal limit for multipart forms
*N/Aeach 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 commulative 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

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
}

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);

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);

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);

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

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Converts to this type from the input type.

The associated error to be returned when the guard fails.

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

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Compare self to key and return true if they are equal.

Converts to this type from the input type.

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Converts self into a collection.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more