Struct rocket::request::Form

pub struct Form<'f, T: FromForm<'f> + 'f> { /* fields omitted */ }

A FromData type for parsing FromForm types strictly.

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

Strictness

A Form<T> will parse successfully from an incoming form only if the form contains the exact set of fields in T. Said another way, a Form<T> will error on missing and/or extra fields. For instance, if an incoming form contains the fields "a", "b", and "c" while T only contains "a" and "c", the form will not parse as Form<T>. If you would like to admit extra fields without error, see LenientForm.

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. For instance, if some structure of type T implements the FromForm trait, an incoming form can be automatically parsed into the T structure with the following route and handler:

#[post("/form_submit", data = "<param>")]
fn submit(form: Form<T>) ... { ... }

To preserve memory safety, if the underlying structure type contains references into form data, the type can only be borrowed via the get or get_mut methods. Otherwise, the parsed structure can be retrieved with the into_inner method.

With References

The simplest data structure with a reference into form data looks like this:

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

This corresponds to a form with a single field named value that should be a string. A handler for this type can be written as:

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

Note that the `r lifetime is used twice in the handler's signature: this is necessary to tie the lifetime of the structure to the lifetime of the request data.

Without References

The owned analog of the UserInput type above is:

#[derive(FromForm)]
struct OwnedUserInput {
    value: String
}

The handler is written similarly:

#[post("/submit", data = "<user_input>")]
fn submit_task(user_input: Form<OwnedUserInput>) -> String {
    let input: OwnedUserInput = user_input.into_inner();
    format!("Your value: {}", input.value)
}

Note that no lifetime annotations are required: Rust is able to infer the lifetime as `static. Because the lifetime is `static, the into_inner method can be used to directly retrieve the parsed value.

Performance and Correctness Considerations

Whether you should use a &RawStr or String in your FromForm type depends on your use case. The primary question to answer is: Can the input contain characters that must be URL encoded? Note that this includes commmon characters such as spaces. If so, then you must use String, whose FromFormValue implementation automatically URL decodes strings. Because the &RawStr references will refer directly to the underlying form data, they will be raw and URL encoded.

If your string values will not contain URL encoded characters, using &RawStr will result in fewer allocation and is thus preferred.

Incoming Data Limits

The default size limit for incoming form data is 32KiB. Setting a limit protects your application from denial of service (DOS) attacks and from resource exhaustion through high memory consumption. The limit can be increased by setting the limits.forms configuration parameter. For instance, to increase the forms limit to 512KiB for all environments, you may add the following to your Rocket.toml:

[global.limits]
forms = 524288

Methods

impl<'f, T: FromForm<'f> + 'f> Form<'f, T>

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn get(&'f self) -> &T

Immutably borrow the parsed type.

Example

use rocket::request::Form;

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

#[post("/submit", data = "<form>")]
fn submit(form: Form<MyForm>) -> String {
    format!("Form field is: {}", form.get().field)
}

pub fn raw_form_string(&'f self) -> &str

Returns the raw form string that was used to parse the encapsulated object.

Example

use rocket::request::Form;

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

#[post("/submit", data = "<form>")]
fn submit(form: Form<MyForm>) -> String {
    format!("Raw form string is: {}", form.raw_form_string())
}

impl<'f, T: FromForm<'f> + 'static> Form<'f, T>

pub fn into_inner(self) -> T

Consumes self and returns the parsed value. For safety reasons, this method may only be called when the parsed value contains no non-'static references.

Example

use rocket::request::Form;

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

#[post("/submit", data = "<form>")]
fn submit(form: Form<MyForm>) -> String {
    form.into_inner().field
}

Trait Implementations

impl<'f, T: FromForm<'f> + Debug + 'f> Debug for Form<'f, T>

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

Formats the value using the given formatter.

impl<'f, T: FromForm<'f>> FromData for Form<'f, T> where     T::Error: Debug,

type Error = Option<String>

The raw form string, if it was able to be retrieved from the request.

fn from_data(request: &Request, data: Data) -> Outcome<Self, Self::Error>

Parses a Form from incoming form data.

If the content type of the request data is not application/x-www-form-urlencoded, Forwards the request. If the form data cannot be parsed into a T, a Failure with status code UnprocessableEntity is returned. If the form string is malformed, a Failure with status code BadRequest is returned. Finally, if reading the incoming stream fails, returns a Failure with status code InternalServerError. In all failure cases, the raw form string is returned if it was able to be retrieved from the incoming stream.

All relevant warnings and errors are written to the console in Rocket logging format.