[−][src]Trait hyperdrive::Guard
A request guard that checks a condition or extracts data out of an incoming request.
For example, this could be used to extract an Authorization
header and
verify user credentials, or to look up a session token in a database.
A Guard
can not access the request body. If you need to do that, implement
FromBody
instead.
Examples
Define a guard that ensures that required request headers are present:
struct MustFrobnicate; impl Guard for MustFrobnicate { type Context = NoContext; type Result = Result<Self, BoxedError>; fn from_request(request: &Arc<http::Request<()>>, context: &Self::Context) -> Self::Result { if request.headers().contains_key("X-Frobnicate") { Ok(MustFrobnicate) } else { let msg = "request did not contain mandatory `X-Frobnicate` header"; Err(String::from(msg).into()) } } }
Use server settings stored in a RequestContext
to exclude certain user
agents:
#[derive(RequestContext)] struct ForbiddenAgents { agents: Vec<String>, } struct RejectForbiddenAgents; impl Guard for RejectForbiddenAgents { type Context = ForbiddenAgents; type Result = Result<Self, BoxedError>; fn from_request(request: &Arc<http::Request<()>>, context: &Self::Context) -> Self::Result { let agent = request.headers().get("User-Agent") .ok_or_else(|| String::from("No User-Agent header"))?; if context.agents.iter().any(|f| f == agent) { Err(String::from("This User-Agent is forbidden!").into()) } else { Ok(RejectForbiddenAgents) } } }
Associated Types
type Context: RequestContext
A context parameter passed to Guard::from_request
.
This can be used to pass application-specific data like a database connection or server configuration (eg. for limiting the maximum HTTP request size) around.
If no context is needed, this should be set to NoContext
.
type Result: IntoFuture<Item = Self, Error = BoxedError>
The result returned by Guard::from_request
.
Because impl Trait
cannot be used inside traits (and named
existential types aren't stable), the type here might not be
nameable. In that case, you can set it to
DefaultFuture<Self, Error>
and box the returned
future.
If your guard doesn't need to return a future (eg. because it's just a
parsing step), you can set this to Result<Self, BoxedError>
and
immediately return the result of the conversion.
Required methods
fn from_request(
request: &Arc<Request<()>>,
context: &Self::Context
) -> Self::Result
request: &Arc<Request<()>>,
context: &Self::Context
) -> Self::Result
Create an instance of this type from HTTP request data, asynchronously.
This can inspect HTTP headers and other data provided by
http::Request
, but can not access the body of the request. If access
to the body is needed, FromBody
must be implemented instead.
Implementations of this function must not block, since this function is
always run on a futures executor. If you need to perform blocking I/O or
long-running computations, you can call tokio_threadpool::blocking
.
Parameters
request
: An HTTP request (without body) from thehttp
crate.context
: User-defined context needed by the guard.