Struct rocket_cors::Cors

pub struct Cors {
    pub allowed_origins: AllowedOrigins,
    pub allowed_methods: AllowedMethods,
    pub allowed_headers: AllOrSome<HashSet<HeaderFieldName>>,
    pub allow_credentials: bool,
    pub expose_headers: HashSet<String>,
    pub max_age: Option<usize>,
    pub send_wildcard: bool,
    pub fairing_route_base: String,
    pub fairing_route_rank: isize,
}

Response generator and Fairing for CORS

This struct can be as Fairing or in an ad-hoc manner to generate CORS response. See the documentation at the crate root for usage information.

You create a new copy of this struct by defining the configurations in the fields below. This struct can also be deserialized by serde with the serialization feature which is enabled by default.

Default is implemented for this struct. The default for each field is described in the docuementation for the field.

Examples

You can run an example from the repository to demonstrate the JSON serialization with cargo run --example json.

Pure default

let default = rocket_cors::Cors::default();

JSON Examples

Default

{
  "allowed_origins": "All",
  "allowed_methods": [
    "POST",
    "PATCH",
    "PUT",
    "DELETE",
    "HEAD",
    "OPTIONS",
    "GET"
  ],
  "allowed_headers": "All",
  "allow_credentials": false,
  "expose_headers": [],
  "max_age": null,
  "send_wildcard": false,
  "fairing_route_base": "/cors",
  "fairing_route_rank": 0
}

Defined

{
  "allowed_origins": {
    "Some": [
      "https://www.acme.com/"
    ]
  },
  "allowed_methods": [
    "POST",
    "DELETE",
    "GET"
  ],
  "allowed_headers": {
    "Some": [
      "Accept",
      "Authorization"
    ]
  },
  "allow_credentials": true,
  "expose_headers": [
    "Content-Type",
    "X-Custom"
  ],
  "max_age": 42,
  "send_wildcard": false,
  "fairing_route_base": "/mycors"
}

Fields

allowed_origins: AllowedOrigins

Origins that are allowed to make requests. Will be verified against the Origin request header.

When All is set, and send_wildcard is set, "*" will be sent in the Access-Control-Allow-Origin response header. Otherwise, the client's Origin request header will be echoed back in the Access-Control-Allow-Origin response header.

When Some is set, the client's Origin request header will be checked in a case-sensitive manner.

This is the list of origins in the Resource Processing Model.

Defaults to All.

allowed_methods: AllowedMethods

The list of methods which the allowed origins are allowed to access for non-simple requests.

This is the list of methods in the Resource Processing Model.

Defaults to [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE]

allowed_headers: AllOrSome<HashSet<HeaderFieldName>>

The list of header field names which can be used when this resource is accessed by allowed origins.

If All is set, whatever is requested by the client in Access-Control-Request-Headers will be echoed back in the Access-Control-Allow-Headers header.

This is the list of headers in the Resource Processing Model.

Defaults to All.

allow_credentials: bool

Allows users to make authenticated requests. If true, injects the Access-Control-Allow-Credentials header in responses. This allows cookies and credentials to be submitted across domains.

This CANNOT be used in conjunction with allowed_origins set to All and send_wildcard set to true. Depending on the mode of usage, this will either result in an Error::CredentialsWithWildcardOrigin error during Rocket launch or runtime.

Defaults to false.

expose_headers: HashSet<String>

The list of headers which are safe to expose to the API of a CORS API specification. This corresponds to the Access-Control-Expose-Headers responde header.

This is the list of exposed headers in the Resource Processing Model.

This defaults to an empty set.

max_age: Option<usize>

The maximum time for which this CORS request maybe cached. This value is set as the Access-Control-Max-Age header.

This defaults to None (unset).

send_wildcard: bool

If true, and the allowed_origins parameter is All, a wildcard Access-Control-Allow-Origin response header is sent, rather than the request’s Origin header.

This is the supports credentials flag in the Resource Processing Model.

This CANNOT be used in conjunction with allowed_origins set to All and allow_credentials set to true. Depending on the mode of usage, this will either result in an Error::CredentialsWithWildcardOrigin error during Rocket launch or runtime.

Defaults to false.

fairing_route_base: String

When used as Fairing, Cors will need to redirect failed CORS checks to a custom route mounted by the fairing. Specify the base of the route so that it doesn't clash with any of your existing routes.

Defaults to "/cors"

fairing_route_rank: isize

When used as Fairing, Cors will need to redirect failed CORS checks to a custom route mounted by the fairing. Specify the rank of the route so that it doesn't clash with any of your existing routes. Remember that a higher ranked route has lower priority.

Defaults to 0

Methods

impl Cors

pub fn validate(&self) -> Result<(), Error>

Validates if any of the settings are disallowed or incorrect

This is run during initial Fairing attachment

pub fn respond_owned<'r, F, R>(
    self,
    handler: F
) -> Result<ManualResponder<'r, F, R>, Error> where
    F: FnOnce(Guard<'r>) -> R + 'r,
    R: Responder<'r>, 

Manually respond to a request with CORS checks and headers using an Owned Cors.

Use this variant when your Cors struct will not live at least as long as the whole 'r lifetime of the request.

After the CORS checks are done, the passed in handler closure will be run to generate a final response. You will have to merge your response with the Guard that you have been passed in to include the CORS headers.

See the documentation at the crate root for usage information.

pub fn respond_borrowed<'r, F, R>(
    &'r self,
    handler: F
) -> Result<ManualResponder<'r, F, R>, Error> where
    F: FnOnce(Guard<'r>) -> R + 'r,
    R: Responder<'r>, 

Manually respond to a request with CORS checks and headers using a borrowed Cors.

Use this variant when your Cors struct will live at least as long as the whole 'r lifetime of the request. If you are getting your Cors from Rocket's state, you will have to use the inner function to get a longer borrowed lifetime.

After the CORS checks are done, the passed in handler closure will be run to generate a final response. You will have to merge your response with the Guard that you have been passed in to include the CORS headers.

See the documentation at the crate root for usage information.

Trait Implementations

impl Fairing for Cors

fn info(&self) -> Info

Returns an Info structure containing the name and Kind of this fairing. The name can be any arbitrary string. Kind must be an ord set of Kind variants.

fn on_attach(&self, rocket: Rocket) -> Result<Rocket, Rocket>

The attach callback. Returns Ok if launch should proceed and Err if launch should be aborted.

fn on_request(&self, request: &mut Request, _: &Data)

The request callback.

fn on_response(&self, request: &Request, response: &mut Response)

The response callback.

fn on_launch(&self, rocket: &Rocket)

The launch callback.

impl Eq for Cors

impl PartialEq for Cors

fn eq(&self, __arg_0: &Cors) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Cors) -> bool

This method tests for !=.

impl Clone for Cors

fn clone(&self) -> Cors

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cors

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Cors

fn default() -> Self

Returns the "default value" for a type.