Expand description
Route guards.
Guards are used during routing to help select a matching service or handler using some aspect of the request; though guards should not be used for path matching since it is a built-in function of the Actix Web router.
Guards can be used on Scope
s, Resource
s, Route
s, and other custom services.
Fundamentally, a guard is a predicate function that receives a reference to a request context
object and returns a boolean; true if the request should be handled by the guarded service
or handler. This interface is defined by the Guard
trait.
Commonly-used guards are provided in this module as well as a way of creating a guard from a
closure (fn_guard
). The Not
, Any
, and All
guards are noteworthy, as they can be
used to compose other guards in a more flexible and semantic way than calling .guard(...)
on
services multiple times (which might have different combining behavior than you want).
There are shortcuts for routes with method guards in the web
module:
web::get()
, web::post()
, etc. The routes created by
the following calls are equivalent:
web::get()
(recommended form)web::route().guard(guard::Get())
Guards can not modify anything about the request. However, it is possible to store extra
attributes in the request-local data container obtained with GuardContext::req_data_mut
.
Guards can prevent resource definitions from overlapping which, when only considering paths,
would result in inaccessible routes. See the Host
guard for an example of virtual hosting.
Examples
In the following code, the /guarded
resource has one defined route whose handler will only be
called if the request method is POST
and there is a request header with name and value equal
to x-guarded
and secret
, respectively.
use actix_web::{web, http::Method, guard, HttpResponse};
web::resource("/guarded").route(
web::route()
.guard(guard::Any(guard::Get()).or(guard::Post()))
.guard(guard::Header("x-guarded", "secret"))
.to(|| HttpResponse::Ok())
);
Structs
A collection of guards that match if the conjunction of their check
outcomes is true.
A collection of guards that match if the disjunction of their check
outcomes is true.
Provides access to request parts that are useful during routing.
Wraps a guard and inverts the outcome of its Guard
implementation.
Traits
Interface for routing guards.
Functions
Creates a guard that matches if all added guards match.
Creates a guard that matches if any added guards match.
Creates a guard that matches the CONNECT
request method.
Creates a guard that matches the DELETE
request method.
Creates a guard that matches the GET
request method.
Creates a guard that matches the HEAD
request method.
Creates a guard that matches if request contains given header name and value.
Creates a guard that matches requests targetting a specific host.
Creates a guard that matches a specified HTTP method.
Creates a guard that matches the OPTIONS
request method.
Creates a guard that matches the PATCH
request method.
Creates a guard that matches the POST
request method.
Creates a guard that matches the PUT
request method.
Creates a guard that matches the TRACE
request method.
Creates a guard using the given function.