Module actix_web::guard

source ·
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 Scopes, Resources, Routes, 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())
);

Re-exports

  • pub use self::host::HostGuard;

Structs

  • A guard that verifies that an Accept header is present and it contains a compatible MIME type.
  • 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.