actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2025-02-17 08:33:30 +01:00
Code Issues Releases Wiki Activity

improve actix-cors docs

Browse Source
This commit is contained in:
Rob Ede 2023-11-03 19:44:12 +00:00
parent 077c6edced
commit 471f07e27f
No known key found for this signature in database
GPG Key ID: 97C636207D3EF933
2 changed files with 78 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
actix-cors/src/builder.rs
View File

@ -52,13 +52,20 @@ static ALL_METHODS_SET: Lazy<HashSet<Method>> = Lazy::new(|| {
/// The alternative [`Cors::permissive()`] constructor is available for local development, allowing /// 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.** /// 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
///
/// Errors surface in the middleware initialization phase. This means that, if you have logs enabled /// 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 /// 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 /// 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. /// server will fail to start up or serve requests.
/// ///
/// # Example /// # Example
///
/// ``` /// ```
/// use actix_cors::Cors; /// use actix_cors::Cors;
/// use actix_web::http::header; /// use actix_web::http::header;
@ -72,6 +79,8 @@ static ALL_METHODS_SET: Lazy<HashSet<Method>> = Lazy::new(|| {
/// ///
/// // `cors` can now be used in `App::wrap`. /// // `cors` can now be used in `App::wrap`.
/// ``` /// ```
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
#[derive(Debug)] #[derive(Debug)]
pub struct Cors { pub struct Cors {
inner: Rc<Inner>, inner: Rc<Inner>,
@ -79,7 +88,8 @@ pub struct Cors {
} }
impl Cors { impl Cors {
/// A very permissive set of default for quick development. Not recommended for production use. /// 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. /// *All* origins, methods, request headers and exposed headers allowed. Credentials supported.
/// Max age 1 hour. Does not send wildcard. /// Max age 1 hour. Does not send wildcard.
@ -124,7 +134,7 @@ impl Cors {
self self
} }
/// Add an origin that is allowed to make requests. /// 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` /// 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]. /// request header. These are `origin-or-null` types in the [Fetch Standard].
@ -177,7 +187,7 @@ impl Cors {
self self
} }
/// Determinate allowed origins by processing requests which didn't match any origins specified /// Determinates allowed origins by processing requests which didn't match any origins specified
/// in the `allowed_origin`. /// in the `allowed_origin`.
/// ///
/// The function will receive two parameters, the Origin header value, and the `RequestHead` of /// The function will receive two parameters, the Origin header value, and the `RequestHead` of
@ -209,14 +219,11 @@ impl Cors {
self self
} }
/// Set a list of methods which allowed origins can perform. /// Sets a list of methods which allowed origins can perform.
/// ///
/// These will be sent in the `Access-Control-Allow-Methods` response header as specified in /// These will be sent in the `Access-Control-Allow-Methods` response header.
/// the [Fetch Standard CORS protocol].
/// ///
/// This defaults to an empty set. /// This defaults to an empty set.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn allowed_methods<U, M>(mut self, methods: U) -> Cors pub fn allowed_methods<U, M>(mut self, methods: U) -> Cors
where where
U: IntoIterator<Item = M>, U: IntoIterator<Item = M>,
@ -279,16 +286,13 @@ impl Cors {
self self
} }
/// Set a list of request header field names which can be used when this resource is accessed by /// Sets a list of request header field names which can be used when this resource is accessed
/// allowed origins. /// by allowed origins.
/// ///
/// If `All` is set, whatever is requested by the client in `Access-Control-Request-Headers` /// 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 as specified in /// will be echoed back in the `Access-Control-Allow-Headers` header.
/// the [Fetch Standard CORS protocol].
/// ///
/// This defaults to an empty set. /// This defaults to an empty set.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn allowed_headers<U, H>(mut self, headers: U) -> Cors pub fn allowed_headers<U, H>(mut self, headers: U) -> Cors
where where
U: IntoIterator<Item = H>, U: IntoIterator<Item = H>,
@ -329,13 +333,11 @@ impl Cors {
self self
} }
/// Set a list of headers which are safe to expose to the API of a CORS API specification. /// 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 as specified in ///
/// the [Fetch Standard CORS protocol]. /// This corresponds to the `Access-Control-Expose-Headers` response header.
/// ///
/// This defaults to an empty set. /// This defaults to an empty set.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn expose_headers<U, H>(mut self, headers: U) -> Cors pub fn expose_headers<U, H>(mut self, headers: U) -> Cors
where where
U: IntoIterator<Item = H>, U: IntoIterator<Item = H>,
@ -364,12 +366,11 @@ impl Cors {
self self
} }
/// Set a maximum time (in seconds) for which this CORS request may be cached. This value is set /// Sets a maximum time (in seconds) for which this CORS request may be cached.
/// as the `Access-Control-Max-Age` header as specified in the [Fetch Standard CORS protocol]. ///
/// 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. /// Pass a number (of seconds) or use None to disable sending max age header.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn max_age(mut self, max_age: impl Into<Option<usize>>) -> Cors { pub fn max_age(mut self, max_age: impl Into<Option<usize>>) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) { if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.max_age = max_age.into(); cors.max_age = max_age.into();
@ -378,17 +379,17 @@ impl Cors {
self self
} }
/// Set to use wildcard origins. /// Configures use of wildcard (`*`) origin in responses when appropriate.
/// ///
/// If send wildcard is set and the `allowed_origins` parameter is `All`, a wildcard /// 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 /// `Access-Control-Allow-Origin` response header is sent, rather than the request’s
/// `Origin` header. /// `Origin` header.
/// ///
/// This **CANNOT** be used in conjunction with `allowed_origins` set to `All` and /// This option **CANNOT** be used in conjunction with a [credential
/// `allow_credentials` set to `true`. Depending on the mode of usage, this will either result /// supported](Self::supports_credentials()) configuration. Doing so will result in an error
/// in an `CorsError::CredentialsWithWildcardOrigin` error during actix launch or runtime. /// during server startup.
/// ///
/// Defaults to `false`. /// Defaults to disabled.
pub fn send_wildcard(mut self) -> Cors { pub fn send_wildcard(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) { if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.send_wildcard = true; cors.send_wildcard = true;
@ -397,21 +398,16 @@ impl Cors {
self self
} }
/// Allows users to make authenticated requests /// Allows users to make authenticated requests.
/// ///
/// If true, injects the `Access-Control-Allow-Credentials` header in responses. This allows /// If true, injects the `Access-Control-Allow-Credentials` header in responses. This allows
/// cookies and credentials to be submitted across domains as specified in /// cookies and credentials to be submitted across domains.
/// the [Fetch Standard CORS protocol].
/// ///
/// This option cannot be used in conjunction with an `allowed_origin` set to `All` and /// This option **CANNOT** be used in conjunction with option cannot be used in conjunction
/// `send_wildcards` set to `true`. /// with [wildcard origins](Self::send_wildcard()) configured. Doing so will result in an error
/// during server startup.
/// ///
/// Defaults to `false`. /// Defaults to disabled.
///
/// A server initialization error will occur if credentials are allowed, but the Origin is set
/// to send wildcards (`*`); this is not allowed by the CORS protocol.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn supports_credentials(mut self) -> Cors { pub fn supports_credentials(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) { if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.supports_credentials = true; cors.supports_credentials = true;
@ -439,7 +435,7 @@ impl Cors {
self self
} }
/// Disable `Vary` header support. /// Disables `Vary` header support.
/// ///
/// When enabled the header `Vary: Origin` will be returned as per the Fetch Standard /// When enabled the header `Vary: Origin` will be returned as per the Fetch Standard
/// implementation guidelines. /// implementation guidelines.
@ -457,12 +453,12 @@ impl Cors {
self self
} }
/// Disable support for preflight requests. /// Disables preflight request handling.
/// ///
/// When enabled CORS middleware automatically handles `OPTIONS` requests. /// When enabled CORS middleware automatically handles `OPTIONS` requests. This is useful for
/// This is useful for application level middleware. /// application level middleware.
/// ///
/// By default *preflight* support is enabled. /// By default, preflight support is enabled.
pub fn disable_preflight(mut self) -> Cors { pub fn disable_preflight(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) { if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.preflight = false; cors.preflight = false;
@ -480,7 +476,7 @@ impl Cors {
/// and block requests based on pre-flight requests. Use this setting to allow cURL and other /// 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. /// non-browser HTTP clients to function as normal, no matter what `Origin` the request has.
/// ///
/// Defaults to `true`. /// Defaults to true.
pub fn block_on_origin_mismatch(mut self, block: bool) -> Cors { pub fn block_on_origin_mismatch(mut self, block: bool) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) { if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.block_on_origin_mismatch = block; cors.block_on_origin_mismatch = block;

37
justfile Normal file
View File

@ -0,0 +1,37 @@
_list:
@just --list
# Document crates in workspace.
doc:
RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc --no-deps --workspace --all-features
# Document crates in workspace and watch for changes.
doc-watch:
RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc --no-deps --workspace --all-features --open
cargo watch -- RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc --no-deps --workspace --all-features
# Check for unintentional external type exposure on all crates in workspace.
check-external-types-all toolchain="+nightly":
#!/usr/bin/env bash
set -euo pipefail
exit=0
for f in $(find . -mindepth 2 -maxdepth 2 -name Cargo.toml | grep -vE "\-codegen/|\-derive/|\-macros/"); do
if ! just check-external-types-manifest "$f" {{toolchain}}; then exit=1; fi
echo
echo
done
exit $exit
# Check for unintentional external type exposure on all crates in workspace.
check-external-types-all-table toolchain="+nightly":
#!/usr/bin/env bash
set -euo pipefail
for f in $(find . -mindepth 2 -maxdepth 2 -name Cargo.toml | grep -vE "\-codegen/|\-derive/|\-macros/"); do
echo
echo "Checking for $f"
just check-external-types-manifest "$f" {{toolchain}} --output-format=markdown-table
done
# Check for unintentional external type exposure on a crate.
check-external-types-manifest manifest_path toolchain="+nightly" *extra_args="":
cargo {{toolchain}} check-external-types --manifest-path "{{manifest_path}}" {{extra_args}}