Trait rocket::request::FromRequest

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.

• Success(S)

  If the Outcome is Success, then the Success value will be used as the value for the corresponding parameter. As long as all other guards succeed, the request will be handled.

• Failure(Status, E)

  If the Outcome is Failure, the request will fail with the given status code and error. The designated error Catcher will be used to respond to the request. Note that users can request types of Result<S, E> and Option<S> to catch Failures and retrieve the error value.

• Forward

  If the Outcome is Forward, the request will be forwarded to the next matching request. Note that users can request an Option<S> to catch Forwards.

Provided Implementations

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

• Method

  Extracts the Method from the incoming request.

  This implementation always returns successfully.

• &URI

  Extracts the URI from the incoming request.

  This implementation always returns successfully.

• &Route

  Extracts the Route from the request if one is available. If a route is not available, the request is forwarded.

  For information on when an &Route is available, see the Request::route documentation.

• Cookies

  Returns a borrow to the Cookies in the incoming request. Note that Cookies implements internal mutability, so a handle to Cookies allows you to get and set cookies in the request.

  This implementation always returns successfully.

• ContentType

  Extracts the ContentType from the incoming request. If the request didn't specify a Content-Type, the request is forwarded.

• SocketAddr

  Extracts the remote address of the incoming request as a SocketAddr. If the remote address is not known, the request is forwarded.

  This implementation always returns successfully.

• Option<T> where T: FromRequest

  The type T is derived from the incoming request using T's FromRequest implementation. If the derivation is a Success, the dervived value is returned in Some. Otherwise, a None is returned.

  This implementation always returns successfully.

• Result<T, T::Error> where T: FromRequest

  The type T is derived from the incoming request using T's FromRequest implementation. If derivation is a Success, the value is returned in Ok. If the derivation is a Failure, the error value is returned in Err. If the derivation is a Forward, the request is forwarded.

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

type Error: Debug

The associated error to be returned if derivation fails.

Required Methods

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

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.

Implementations on Foreign Types

impl<'a, 'r> FromRequest<'a, 'r> for SocketAddr

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Result<T, T::Error>

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Option<T>

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

Implementors

impl<'a, 'r> FromRequest<'a, 'r> for &'a Accept

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for &'a ContentType

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for &'a URI<'a>

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for &'r Route

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for Cookies<'a>

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for Method

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r> FromRequest<'a, 'r> for Flash<()>

Retrieves a flash message from a flash cookie and deletes the flash cookie. If there is no flash cookie, an empty Err is returned.

The suggested use is through an Option and the FlashMessage type alias in request: Option<FlashMessage>.

type Error = ()

fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>

impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T>

type Error = ()

fn from_request(req: &'a Request<'r>) -> Outcome<State<'r, T>, ()>