Module actix_web::guard

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

• Acceptable
  A guard that verifies that an Accept header is present and it contains a compatible MIME type.
• AllGuard
  A collection of guards that match if the conjunction of their check outcomes is true.
• AnyGuard
  A collection of guards that match if the disjunction of their check outcomes is true.
• GuardContext
  Provides access to request parts that are useful during routing.
• Not
  Wraps a guard and inverts the outcome of its Guard implementation.

Traits

• Guard
  Interface for routing guards.

Functions

• All
  Creates a guard that matches if all added guards match.
• Any
  Creates a guard that matches if any added guards match.
• Connect
  Creates a guard that matches the CONNECT request method.
• Delete
  Creates a guard that matches the DELETE request method.
• Get
  Creates a guard that matches the GET request method.
• Head
  Creates a guard that matches the HEAD request method.
• Header
  Creates a guard that matches if request contains given header name and value.
• Host
  Creates a guard that matches requests targetting a specific host.
• Method
  Creates a guard that matches a specified HTTP method.
• Options
  Creates a guard that matches the OPTIONS request method.
• Patch
  Creates a guard that matches the PATCH request method.
• Post
  Creates a guard that matches the POST request method.
• Put
  Creates a guard that matches the PUT request method.
• Trace
  Creates a guard that matches the TRACE request method.
• fn_guard
  Creates a guard using the given function.