Struct actix_web::middleware::cors::CorsBuilder

pub struct CorsBuilder<S = ()> { /* fields omitted */ }

Structure that follows the builder pattern for building Cors middleware structs.

To construct a cors:

1. Call Cors::build to start building.
2. Use any of the builder methods to set fields in the backend.
3. Call finish to retrieve the constructed backend.

Example

use actix_web::middleware::cors;
use http::header;

let cors = cors::Cors::build()
    .allowed_origin("https://www.rust-lang.org/")
    .allowed_methods(vec!["GET", "POST"])
    .allowed_headers(vec![header::AUTHORIZATION, header::ACCEPT])
    .allowed_header(header::CONTENT_TYPE)
    .max_age(3600)
    .finish();

Methods

impl<S: 'static> CorsBuilder<S>

pub fn allowed_origin(&mut self, origin: &str) -> &mut CorsBuilder<S>

Add an origin 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.

Builder panics if supplied origin is not valid uri.

pub fn allowed_methods<U, M>(&mut self, methods: U) -> &mut CorsBuilder<S> where
    U: IntoIterator<Item = M>,
    Method: HttpTryFrom<M>, 

Set a list of methods which the allowed origins are allowed to access for requests.

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

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

pub fn allowed_header<H>(&mut self, header: H) -> &mut CorsBuilder<S> where
    HeaderName: HttpTryFrom<H>, 

Set an allowed header

pub fn allowed_headers<U, H>(&mut self, headers: U) -> &mut CorsBuilder<S> where
    U: IntoIterator<Item = H>,
    HeaderName: HttpTryFrom<H>, 

Set a 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.

pub fn expose_headers<U, H>(&mut self, headers: U) -> &mut CorsBuilder<S> where
    U: IntoIterator<Item = H>,
    HeaderName: HttpTryFrom<H>, 

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

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

This defaults to an empty set.

pub fn max_age(&mut self, max_age: usize) -> &mut CorsBuilder<S>

Set a 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).

pub fn send_wildcard(&mut self) -> &mut CorsBuilder<S>

Set a wildcard origins

If send wildcard is set 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 actix launch or runtime.

Defaults to false.

pub fn supports_credentials(&mut self) -> &mut CorsBuilder<S>

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 option cannot be used in conjunction with an allowed_origin set to All and send_wildcards set to true.

Defaults to false.

Builder panics if credentials are allowed, but the Origin is set to "*". This is not allowed by W3C

pub fn disable_vary_header(&mut self) -> &mut CorsBuilder<S>

Disable Vary header support.

When enabled the header Vary: Origin will be returned as per the W3 implementation guidelines.

Setting this header when the Access-Control-Allow-Origin is dynamically generated (e.g. when there is more than one allowed origin, and an Origin than '*' is returned) informs CDNs and other caches that the CORS headers are dynamic, and cannot be cached.

By default vary header support is enabled.

pub fn disable_preflight(&mut self) -> &mut CorsBuilder<S>

Disable preflight request support.

When enabled cors middleware automatically handles OPTIONS request. This is useful application level middleware.

By default preflight support is enabled.

pub fn resource<F, R>(&mut self, path: &str, f: F) -> &mut CorsBuilder<S> where
    F: FnOnce(&mut Resource<S>) -> R + 'static, 

Configure resource for a specific path.

This is similar to a App::resource() method. Except, cors middleware get registered for the resource.

use actix_web::middleware::cors::Cors;
use actix_web::{http, App, HttpResponse};

fn main() {
    let app = App::new().configure(
        |app| {
            Cors::for_app(app)   // <- Construct CORS builder
            .allowed_origin("https://www.rust-lang.org/")
            .allowed_methods(vec!["GET", "POST"])
            .allowed_header(http::header::CONTENT_TYPE)
            .max_age(3600)
            .resource("/resource1", |r| {       // register resource
                 r.method(http::Method::GET).f(|_| HttpResponse::Ok());
            })
            .resource("/resource2", |r| {       // register another resource
                 r.method(http::Method::HEAD)
                     .f(|_| HttpResponse::MethodNotAllowed());
            })
            .register()
        }, // construct CORS and return application instance
    );
}

pub fn finish(&mut self) -> Cors

Finishes building and returns the built Cors instance.

This method panics in case of any configuration error.

pub fn register(&mut self) -> App<S>

Finishes building Cors middleware and register middleware for application

This method panics in case of any configuration error or if non of resources are registered.