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 implemented by request guards to derive a value from incoming requests.

Request Guards

A request guard is a type that represents an arbitrary validation policy. The validation policy is implemented through FromRequest. In other words, every type that implements FromRequest is a request guard.

Request guards appear as inputs to handlers. An arbitrary number of request guards can appear as arguments in a route handler. Rocket will automatically invoke the FromRequest implementation for request guards before calling the handler. Rocket only dispatches requests to a handler when all of its guards pass.

Example

The following dummy handler makes use of three request guards, A, B, and C. An input type can be identified as a request guard if it is not named in the route attribute. This is why, for instance, param is not a request guard.

#[get("/<param>")]
fn index(param: isize, a: A, b: B, c: C) -> ... { ... }

Request guards always fire in left-to-right declaration order. In the example above, for instance, the order will be a followed by b followed by c. Failure is short-circuiting; if one guard fails, the remaining are not attempted.

Outcomes

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.

Example

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

#[get("/sensitive")]
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.

Implementors