Struct actix_cors::Cors
source · pub struct Cors { /* private fields */ }
Expand description
Builder for CORS middleware.
To construct a CORS middleware, call Cors::default()
to create a blank, restrictive builder.
Then use any of the builder methods to customize CORS behavior.
The alternative Cors::permissive()
constructor is available for local development, allowing
all origins and headers, etc. The permissive constructor should not be used in production.
§Behavior
In all cases, behavior for this crate follows the Fetch Standard CORS protocol. See that document for information on exact semantics for configuration options and combinations.
§Errors
Errors surface in the middleware initialization phase. This means that, if you have logs enabled
in Actix Web (using env_logger
or other crate that exposes logs from the log
crate), error
messages will outline what is wrong with the CORS configuration in the server logs and the
server will fail to start up or serve requests.
§Example
use actix_cors::Cors;
use actix_web::http::header;
let cors = Cors::default()
.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);
// `cors` can now be used in `App::wrap`.
Implementations§
source§impl Cors
impl Cors
sourcepub fn permissive() -> Self
pub fn permissive() -> Self
Constructs a very permissive set of defaults for quick development. (Not recommended for production use.)
All origins, methods, request headers and exposed headers allowed. Credentials supported. Max age 1 hour. Does not send wildcard.
sourcepub fn allow_any_origin(self) -> Cors
pub fn allow_any_origin(self) -> Cors
Resets allowed origin list to a state where any origin is accepted.
See Cors::allowed_origin
for more info on allowed origins.
sourcepub fn allowed_origin(self, origin: &str) -> Cors
pub fn allowed_origin(self, origin: &str) -> Cors
Adds an origin that is allowed to make requests.
This method allows specifying a finite set of origins to verify the value of the Origin
request header. These are origin-or-null
types in the Fetch Standard.
By default, no origins are accepted.
When this list is set, the client’s Origin
request header will be checked in a
case-sensitive manner.
When all origins are allowed and send_wildcard
is set, *
will be sent in the
Access-Control-Allow-Origin
response header. If send_wildcard
is not set, the client’s
Origin
request header will be echoed back in the Access-Control-Allow-Origin
response header.
If the origin of the request doesn’t match any allowed origins and at least one
allowed_origin_fn
function is set, these functions will be used to determinate
allowed origins.
§Initialization Errors
- If supplied origin is not valid uri
- If supplied origin is a wildcard (
*
).Cors::send_wildcard
should be used instead.
sourcepub fn allowed_origin_fn<F>(self, f: F) -> Cors
pub fn allowed_origin_fn<F>(self, f: F) -> Cors
Determinates allowed origins by processing requests which didn’t match any origins specified
in the allowed_origin
.
The function will receive two parameters, the Origin header value, and the RequestHead
of
each request, which can be used to determine whether to allow the request or not.
If the function returns true
, the client’s Origin
request header will be echoed back
into the Access-Control-Allow-Origin
response header.
sourcepub fn allow_any_method(self) -> Cors
pub fn allow_any_method(self) -> Cors
Resets allowed methods list to all methods.
See Cors::allowed_methods
for more info on allowed methods.
sourcepub fn allowed_methods<U, M>(self, methods: U) -> Cors
pub fn allowed_methods<U, M>(self, methods: U) -> Cors
Sets a list of methods which allowed origins can perform.
These will be sent in the Access-Control-Allow-Methods
response header.
This defaults to an empty set.
sourcepub fn allow_any_header(self) -> Cors
pub fn allow_any_header(self) -> Cors
Resets allowed request header list to a state where any header is accepted.
See Cors::allowed_headers
for more info on allowed request headers.
sourcepub fn allowed_header<H>(self, header: H) -> Cors
pub fn allowed_header<H>(self, header: H) -> Cors
Add an allowed request header.
See Cors::allowed_headers
for more info on allowed request headers.
sourcepub fn allowed_headers<U, H>(self, headers: U) -> Corswhere
U: IntoIterator<Item = H>,
H: TryInto<HeaderName>,
<H as TryInto<HeaderName>>::Error: Into<HttpError>,
pub fn allowed_headers<U, H>(self, headers: U) -> Corswhere
U: IntoIterator<Item = H>,
H: TryInto<HeaderName>,
<H as TryInto<HeaderName>>::Error: Into<HttpError>,
Sets a list of request 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 defaults to an empty set.
sourcepub fn expose_any_header(self) -> Cors
pub fn expose_any_header(self) -> Cors
Resets exposed response header list to a state where all headers are exposed.
See Cors::expose_headers
for more info on exposed response headers.
sourcepub fn expose_headers<U, H>(self, headers: U) -> Corswhere
U: IntoIterator<Item = H>,
H: TryInto<HeaderName>,
<H as TryInto<HeaderName>>::Error: Into<HttpError>,
pub fn expose_headers<U, H>(self, headers: U) -> Corswhere
U: IntoIterator<Item = H>,
H: TryInto<HeaderName>,
<H as TryInto<HeaderName>>::Error: Into<HttpError>,
Sets 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 defaults to an empty set.
sourcepub fn max_age(self, max_age: impl Into<Option<usize>>) -> Cors
pub fn max_age(self, max_age: impl Into<Option<usize>>) -> Cors
Sets a maximum time (in seconds) for which this CORS request may be cached.
This value is set as the Access-Control-Max-Age
header.
Pass a number (of seconds) or use None to disable sending max age header.
sourcepub fn send_wildcard(self) -> Cors
pub fn send_wildcard(self) -> Cors
Configures use of wildcard (*
) origin in responses when appropriate.
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 option CANNOT be used in conjunction with a credential supported configuration. Doing so will result in an error during server startup.
Defaults to disabled.
sourcepub fn supports_credentials(self) -> Cors
pub fn supports_credentials(self) -> Cors
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 option cannot be used in conjunction with wildcard origins configured. Doing so will result in an error during server startup.
Defaults to disabled.
sourcepub fn disable_vary_header(self) -> Cors
pub fn disable_vary_header(self) -> Cors
Disables Vary
header support.
When enabled the header Vary: Origin
will be returned as per the Fetch Standard
implementation guidelines.
Setting this header when the Access-Control-Allow-Origin
is dynamically generated
(eg. when there is more than one allowed origin, and an Origin other 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.
sourcepub fn disable_preflight(self) -> Cors
pub fn disable_preflight(self) -> Cors
Disables preflight request handling.
When enabled CORS middleware automatically handles OPTIONS
requests. This is useful for
application level middleware.
By default, preflight support is enabled.
sourcepub fn block_on_origin_mismatch(self, block: bool) -> Cors
pub fn block_on_origin_mismatch(self, block: bool) -> Cors
Configures whether requests should be pre-emptively blocked on mismatched origin.
If true
, a 400 Bad Request is returned immediately when a request fails origin validation.
If false
, the request will be processed as normal but relevant CORS headers will not be
appended to the response. In this case, the browser is trusted to validate CORS headers and
and block requests based on pre-flight requests. Use this setting to allow cURL and other
non-browser HTTP clients to function as normal, no matter what Origin
the request has.
Defaults to true.