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:
#[get("/")] 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.
Outcomes
The returned Outcome of a from_request
call
determines how the incoming request will be processed.
-
Success(S)
If the
Outcome
isSuccess
, then theSuccess
value will be used as the value for the corresponding parameter. As long as all other parsed types succeed, the request will be handled. -
Failure(Status, E)
If the
Outcome
isFailure
, 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 ofResult<S, E>
andOption<S>
to catchFailure
s and retrieve the error value. -
Forward
If the
Outcome
isForward
, the request will be forwarded to the next matching request. Note that users can request anOption<S>
to catchForward
s.
Provided Implementations
Rocket implements FromRequest
for several built-in types. Their behavior
is documented here.
-
&URI
Extracts the URI from the incoming request.
This implementation always returns successfully.
-
Method
Extracts the Method from the incoming request.
This implementation always returns successfully.
-
&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 usingT
'sFromRequest
implementation. If the derivation is aSuccess
, the dervived value is returned inSome
. Otherwise, aNone
is returned.This implementation always returns successfully.
-
Result<T, T::Error> where T: FromRequest
The type
T
is derived from the incoming request usingT
'sFromRequest
implementation. If derivation is aSuccess
, the value is returned inOk
. If the derivation is aFailure
, the error value is returned inErr
. If the derivation is aForward
, 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
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.
Implementors
impl<'a, 'r> FromRequest<'a, 'r> for &'a URI<'a>
impl<'a, 'r> FromRequest<'a, 'r> for Method
impl<'a, 'r> FromRequest<'a, 'r> for &'a Cookies
impl<'a, 'r> FromRequest<'a, 'r> for ContentType
impl<'a, 'r> FromRequest<'a, 'r> for SocketAddr
impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Result<T, T::Error>
impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Option<T>
impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T>
impl<'a, 'r> FromRequest<'a, 'r> for Flash<()>