Trait rocket::request::FromRequest [] [src]

pub trait FromRequest<'a, 'r>: Sized {
    type Error: Debug;
    fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>;

Trait used to derive an object from incoming request metadata.

An arbitrary number of types that implement this trait can appear as parameters in a route handler, as illustrated below:

fn index(a: A, b: B, c: C) -> ... { ... }

In this example, A, B, and C can be any types that implements FromRequest. There can be any number of FromRequest types in the function signature. Note that unlike every other derived object in Rocket, FromRequest parameter names do not need to be declared in the route attribute.

Derivation of FromRequest arguments is always attemped in left-to-right declaration order. In the example above, for instance, the order will be a followed by b followed by c. If a deriviation fails, the following aren't attempted.


The returned Outcome of a from_request call determines how the incoming request will be processed.

Provided Implementations

Rocket implements FromRequest for several built-in types. Their behavior is documented here.


Imagine you're running an authenticated API service that requires that some requests be sent along with a valid API key in a header field. You want to ensure that the handlers corresponding to these requests don't get called unless there is an API key in the request and the key is valid. The following example implements this using an APIKey type and a FromRequest implementation for that type. The APIKey type is then used in the senstive handler.

use rocket::Outcome;
use rocket::http::Status;
use rocket::request::{self, Request, FromRequest};

struct APIKey(String);

/// Returns true if `key` is a valid API key string.
fn is_valid(key: &str) -> bool {
    key == "valid_api_key"

impl<'a, 'r> FromRequest<'a, 'r> for APIKey {
    type Error = ();

    fn from_request(request: &'a Request<'r>) -> request::Outcome<APIKey, ()> {
        let keys: Vec<_> = request.headers().get("x-api-key").collect();
        if keys.len() != 1 {
            return Outcome::Failure((Status::BadRequest, ()));

        let key = keys[0];
        if !is_valid(keys[0]) {
            return Outcome::Forward(());

        return Outcome::Success(APIKey(key.to_string()));

fn sensitive(key: APIKey) -> &'static str {
    "Sensitive data."

Associated Types

The associated error to be returned if derivation fails.

Required Methods

Derives an instance of Self from the incoming request metadata.

If the derivation is successful, an outcome of Success is returned. If the derivation fails in an unrecoverable fashion, Failure is returned. Forward is returned to indicate that the request should be forwarded to other matching routes, if any.