Struct rocket_cors::CorsOptions

pub struct CorsOptions {
    pub allowed_origins: AllowedOrigins,
    pub allowed_methods: AllowedMethods,
    pub allowed_headers: AllowedHeaders,
    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,
}

Configuration options for CORS request handling.

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 documentation for the field.

Before you can use this with Rocket, you will need to call the CorsOptions::to_cors method.

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::CorsOptions::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": {
        "exact": ["https://www.acme.com"],
        "regex": ["^https://www.example-[A-z0-9]*.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: AllowedHeaders

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

Implementations

impl CorsOptions

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

Validates if any of the settings are disallowed, incorrect, or illegal

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

Creates a Cors struct that can be used to respond to requests or as a Rocket Fairing

pub fn allowed_origins(self, allowed_origins: AllowedOrigins) -> Self

Sets the allowed origins

pub fn allowed_methods(self, allowed_methods: AllowedMethods) -> Self

Sets the allowed methodes

pub fn allowed_headers(self, allowed_headers: AllowedHeaders) -> Self

Sets the allowed headers

pub fn allow_credentials(self, allow_credentials: bool) -> Self

Marks if credentials are allowed

pub fn expose_headers(self, expose_headers: HashSet<String>) -> Self

Sets the expose headers

pub fn max_age(self, max_age: Option<usize>) -> Self

Sets the max age

pub fn send_wildcard(self, send_wildcard: bool) -> Self

Marks if wildcards are send

pub fn fairing_route_base<S: Into<String>>(self, fairing_route_base: S) -> Self

Sets the base of the fairing route

pub fn fairing_route_rank(self, fairing_route_rank: isize) -> Self

Sets the rank of the fairing route

Trait Implementations

impl Clone for CorsOptions

fn clone(&self) -> CorsOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CorsOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CorsOptions

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CorsOptions

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<CorsOptions> for CorsOptions

fn eq(&self, other: &CorsOptions) -> bool

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

fn ne(&self, other: &CorsOptions) -> bool

This method tests for !=.

impl Serialize for CorsOptions

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl Eq for CorsOptions

impl StructuralEq for CorsOptions

impl StructuralPartialEq for CorsOptions