actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2024-11-27 09:12:57 +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
/// 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;
@ -72,6 +79,8 @@ static ALL_METHODS_SET: Lazy<HashSet<Method>> = Lazy::new(|| {
///
/// // `cors` can now be used in `App::wrap`.
/// ```
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
#[derive(Debug)]
pub struct Cors {
inner: Rc<Inner>,
@ -79,7 +88,8 @@ pub struct 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.
/// Max age 1 hour. Does not send wildcard.
@ -124,7 +134,7 @@ impl Cors {
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`
/// request header. These are `origin-or-null` types in the [Fetch Standard].
@ -177,7 +187,7 @@ impl Cors {
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`.
///
/// The function will receive two parameters, the Origin header value, and the `RequestHead` of
@ -209,14 +219,11 @@ impl Cors {
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
/// the [Fetch Standard CORS protocol].
/// These will be sent in the `Access-Control-Allow-Methods` response header.
///
/// 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
where
U: IntoIterator<Item = M>,
@ -279,16 +286,13 @@ impl Cors {
self
}
/// Set a list of request header field names which can be used when this resource is accessed by
/// allowed origins.
/// 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 as specified in
/// the [Fetch Standard CORS protocol].
/// will be echoed back in the `Access-Control-Allow-Headers` header.
///
/// 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
where
U: IntoIterator<Item = H>,
@ -329,13 +333,11 @@ impl Cors {
self
}
/// 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 as specified in
/// the [Fetch Standard CORS protocol].
/// 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.
///
/// [Fetch Standard CORS protocol]: https://fetch.spec.whatwg.org/#http-cors-protocol
pub fn expose_headers<U, H>(mut self, headers: U) -> Cors
where
U: IntoIterator<Item = H>,
@ -364,12 +366,11 @@ impl Cors {
self
}
/// Set a maximum time (in seconds) for which this CORS request may be cached. This value is set
/// as the `Access-Control-Max-Age` header as specified in the [Fetch Standard CORS protocol].
/// 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.
///
/// [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 {
if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.max_age = max_age.into();
@ -378,17 +379,17 @@ impl Cors {
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
/// `Access-Control-Allow-Origin` response header is sent, rather than the request’s
/// `Origin` header.
///
/// 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 `CorsError::CredentialsWithWildcardOrigin` error during actix launch or runtime.
/// This option **CANNOT** be used in conjunction with a [credential
/// supported](Self::supports_credentials()) configuration. Doing so will result in an error
/// during server startup.
///
/// Defaults to `false`.
/// Defaults to disabled.
pub fn send_wildcard(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.send_wildcard = true;
@ -397,21 +398,16 @@ impl Cors {
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
/// cookies and credentials to be submitted across domains as specified in
/// the [Fetch Standard CORS protocol].
/// 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`.
/// This option **CANNOT** be used in conjunction with option cannot be used in conjunction
/// with [wildcard origins](Self::send_wildcard()) configured. Doing so will result in an error
/// during server startup.
///
/// Defaults to `false`.
///
/// 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
/// Defaults to disabled.
pub fn supports_credentials(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) {
cors.supports_credentials = true;
@ -439,7 +435,7 @@ impl Cors {
self
}
/// Disable `Vary` header support.
/// Disables `Vary` header support.
///
/// When enabled the header `Vary: Origin` will be returned as per the Fetch Standard
/// implementation guidelines.
@ -457,12 +453,12 @@ impl Cors {
self
}
/// Disable support for preflight requests.
/// Disables preflight request handling.
///
/// When enabled CORS middleware automatically handles `OPTIONS` requests.
/// This is useful for application level middleware.
/// When enabled CORS middleware automatically handles `OPTIONS` requests. This is useful for
/// application level middleware.
///
/// By default *preflight* support is enabled.
/// By default, preflight support is enabled.
pub fn disable_preflight(mut self) -> Cors {
if let Some(cors) = cors(&mut self.inner, &self.error) {
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
/// 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 {
if let Some(cors) = cors(&mut self.inner, &self.error) {
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}}