Module rouille::input::post [−] [src]

Parsing data sent with a <form method="POST">.

In order to parse the body of a request, you can use the post_input! macro.

use rouille::Request;
use rouille::Response;

fn handle_request(request: &Request) -> Response {
    let input = try_or_400!(post_input!(request, {
        field1: u32,
        field2: String,
    }));

    Response::text(format!("the value of field1 is: {}", input.field1))
}

In this example, the macro will read the body of the request and try to find fields whose names are field1 and field2. If the body was already retreived earlier, if the content-type is not one of the possible values, or if a field is missing or can't be parsed, then an error is returned. Usually you want to handle this error by returning an error to the client.

The macro will define and build a struct whose members are the field names that are passed. The macro then returns a Result<TheGeneratedStruct, PostError>.

Data types

The types that can be used with this macro are the following:

  • String: The value sent by the client is directly put in the String.
  • u8/i8/u16/i16/ u32/i32/ u64/i64/usize/isize/f32/f64: Rouille will try to parse the number from the data passed by the client. An error is produced if the client sent a value that failed to parse or that overflows the capacity of the number.
  • Option<T>: This is equivalent to T, but if the field is missing or fails to parse then the Option will contain None and no error will be produced.
  • bool: Will be true if the field is present at least once and false if it is absent. This is suitable to know whether a <input type="checkbox" /> is checked or not.
  • Vec<T>: Same as T, except that if the client sends multiple fields with that name then they are merged together. If you don't use a Vec then an error is returned in that situation. If the client provides multiple values and some of them fail to parse, an error is returned. You can use a Vec<Option<T>> if you don't want an error on parse failure. Empty vecs are possible.
  • The file-uploads-related types. See below.

Note: You may find resources on the web telling you that you must put brackets ([ ]) after the name of inputs of type <select multiple> and <input type="file" multiple>. This is only necessary for some programming languages and frameworks, and is not relevant for rouille. With rouille you just need to use a Vec for the data type.

You can also use your own types by implementing the DecodePostField trait. See below.

Handling file uploads

In order to receive a file sent with a <form>, you should use one of the provided structs that represent a file:

  • BufferedFile, in which case the body of the file will be stored in memory.

Example:

use rouille::Request;
use rouille::Response;
use rouille::input::post::BufferedFile;

fn handle_request(request: &Request) -> Response {
    let input = try_or_400!(post_input!(request, {
        file: BufferedFile,
    }));

    Response::text("everything ok")
}

How it works internally

In order for the macro to work, each type of data (like u32, String or BufferedFile) must implement the DecodePostField trait.

The template parameter of the trait represents the type of the configuration object that is accepted by the methods. If the user doesn't specify any configuration, the type will be ().

When rouille's parser finds a field with the correct name it will attempt to call the from_field method, and if it find a file with the correct name it will attempt to call the from_file method. You should return PostFieldError::WrongFieldType if you're expecting a file and from_field was called, or vice-versa.

Structs

BufferedFile

Implementation of the DecodePostField that puts the body of the file in memory.

Enums

PostError

Error that can happen when decoding POST data.
PostFieldError

Error returned by the methods of the DecodePostField trait.

Traits

DecodePostField

Must be implemented on types used with the post_input! macro.

Functions

raw_urlencoded_post_input

Attempts to decode the POST data received by the request.