pub trait FromRequest<'a, 'r>: Sized {
type Error: Debug;
// Required method
fn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>;
}
Expand description
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) -> T { /* ... */ }
Request guards always fire in left-to-right declaration order. In the
example above, the order is 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
isSuccess
, then theSuccess
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
isFailure
, the request will fail with the given status code and error. The designated errorCatcher
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.
-
Method
Extracts the
Method
from the incoming request.This implementation always returns successfully.
-
&Origin
Extracts the
Origin
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, seeRequest::route()
. -
Cookies
Returns a borrow to the
Cookies
in the incoming request. Note thatCookies
implements internal mutability, so a handle toCookies
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 derived 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
sensitive
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"
}
#[derive(Debug)]
enum ApiKeyError {
BadCount,
Missing,
Invalid,
}
impl<'a, 'r> FromRequest<'a, 'r> for ApiKey {
type Error = ApiKeyError;
fn from_request(request: &'a Request<'r>) -> request::Outcome<Self, Self::Error> {
let keys: Vec<_> = request.headers().get("x-api-key").collect();
match keys.len() {
0 => Outcome::Failure((Status::BadRequest, ApiKeyError::Missing)),
1 if is_valid(keys[0]) => Outcome::Success(ApiKey(keys[0].to_string())),
1 => Outcome::Failure((Status::BadRequest, ApiKeyError::Invalid)),
_ => Outcome::Failure((Status::BadRequest, ApiKeyError::BadCount)),
}
}
}
#[get("/sensitive")]
fn sensitive(key: ApiKey) -> &'static str {
"Sensitive data."
}
§Request-Local State
Request guards that perform expensive operations, such as those that query a database or an external service, should use the request-local state cache to store results if they might be invoked multiple times during the routing of a single request.
For example, consider a pair of User
and Admin
guards and a pair of
routes (admin_dashboard
and user_dashboard
):
impl<'a, 'r> FromRequest<'a, 'r> for User {
type Error = ();
fn from_request(request: &'a Request<'r>) -> request::Outcome<User, ()> {
let db = request.guard::<Database>()?;
request.cookies()
.get_private("user_id")
.and_then(|cookie| cookie.value().parse().ok())
.and_then(|id| db.get_user(id).ok())
.or_forward(())
}
}
impl<'a, 'r> FromRequest<'a, 'r> for Admin {
type Error = ();
fn from_request(request: &'a Request<'r>) -> request::Outcome<Admin, ()> {
// This will unconditionally query the database!
let user = request.guard::<User>()?;
if user.is_admin {
Outcome::Success(Admin { user })
} else {
Outcome::Forward(())
}
}
}
#[get("/dashboard")]
fn admin_dashboard(admin: Admin) { }
#[get("/dashboard", rank = 2)]
fn user_dashboard(user: User) { }
When a non-admin user is logged in, the database will be queried twice: once
via the Admin
guard invoking the User
guard, and a second time via the
User
guard directly. For cases like these, request-local state should be
used, as illustrated below:
impl<'a, 'r> FromRequest<'a, 'r> for &'a User {
type Error = !;
fn from_request(request: &'a Request<'r>) -> request::Outcome<&'a User, !> {
// This closure will execute at most once per request, regardless of
// the number of times the `User` guard is executed.
let user_result = request.local_cache(|| {
let db = request.guard::<Database>().succeeded()?;
request.cookies()
.get_private("user_id")
.and_then(|cookie| cookie.value().parse().ok())
.and_then(|id| db.get_user(id).ok())
});
user_result.as_ref().or_forward(())
}
}
impl<'a, 'r> FromRequest<'a, 'r> for Admin<'a> {
type Error = !;
fn from_request(request: &'a Request<'r>) -> request::Outcome<Admin<'a>, !> {
let user = request.guard::<&User>()?;
if user.is_admin {
Outcome::Success(Admin { user })
} else {
Outcome::Forward(())
}
}
}
Notice that these request guards provide access to borrowed data (&'a User
and Admin<'a>
) as the data is now owned by the request’s cache.
Required Associated Types§
Required Methods§
Sourcefn from_request(request: &'a Request<'r>) -> Outcome<Self, Self::Error>
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.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.
Implementations on Foreign Types§
Source§impl<'a, 'r> FromRequest<'a, 'r> for SocketAddr
impl<'a, 'r> FromRequest<'a, 'r> for SocketAddr
Source§impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Option<T>
impl<'a, 'r, T: FromRequest<'a, 'r>> FromRequest<'a, 'r> for Option<T>
Source§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 Result<T, T::Error>
Implementors§
Source§impl<'a, 'r> FromRequest<'a, 'r> for &'a ContentType
impl<'a, 'r> FromRequest<'a, 'r> for &'a ContentType
Source§impl<'a, 'r> FromRequest<'a, 'r> for Flash<&'a Request<'r>>
impl<'a, 'r> FromRequest<'a, 'r> for Flash<&'a Request<'r>>
Retrieves a flash message from a flash cookie. If there is no flash cookie,
or if the flash cookie is malformed, an empty Err
is returned.
The suggested use is through an Option
and the FlashMessage
type alias
in request
: Option<FlashMessage>
.