From b9e47d61c3557cac08b5b38bd157cca7a8c96dc8 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Tue, 11 Jun 2024 03:55:41 +0100 Subject: [PATCH] docs(httpauth): add HttpAuthentication::with_fn examples --- actix-session/README.md | 7 ++-- actix-session/src/lib.rs | 5 ++- actix-web-httpauth/src/middleware.rs | 49 ++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 7 deletions(-) diff --git a/actix-session/README.md b/actix-session/README.md index 210a81d02..3500fe77c 100644 --- a/actix-session/README.md +++ b/actix-session/README.md @@ -25,7 +25,7 @@ We refer to the cookie used for sessions as a **session cookie**. Its content is `actix-session` provides an easy-to-use framework to manage sessions in applications built on top of Actix Web. [`SessionMiddleware`] is the middleware underpinning the functionality provided by `actix-session`; it takes care of all the session cookie handling and instructs the **storage backend** to create/delete/update the session state based on the operations performed against the active [`Session`]. -`actix-session` provides some built-in storage backends: ([`CookieSessionStore`], [`RedisSessionStore`], and [`RedisActorSessionStore`]) - you can create a custom storage backend by implementing the [`SessionStore`] trait. +`actix-session` provides some built-in storage backends: ([`CookieSessionStore`], [`RedisSessionStore`]) - you can create a custom storage backend by implementing the [`SessionStore`] trait. Further reading on sessions: @@ -108,7 +108,7 @@ By default, `actix-session` does not provide any storage backend to retrieve and actix-session = { version = "...", features = ["redis-session"] } ``` - Add the `redis-session-native-tls` feature flag if you want to connect to Redis using a secured connection (via the `native-tls` crate): + Add the `redis-session-native-tls` feature flag if you want to connect to Redis using a secure connection (via the `native-tls` crate): ```toml [dependencies] @@ -116,7 +116,7 @@ By default, `actix-session` does not provide any storage backend to retrieve and actix-session = { version = "...", features = ["redis-session-native-tls"] } ``` - If you instead prefer depending on `rustls`, use the `redis-session-rustls` feature flag: + If you, instead, prefer depending on `rustls`, use the `redis-session-rustls` feature flag: ```toml [dependencies] @@ -129,6 +129,5 @@ You can implement your own session storage backend using the [`SessionStore`] tr [`SessionStore`]: storage::SessionStore [`CookieSessionStore`]: storage::CookieSessionStore [`RedisSessionStore`]: storage::RedisSessionStore -[`RedisActorSessionStore`]: storage::RedisActorSessionStore diff --git a/actix-session/src/lib.rs b/actix-session/src/lib.rs index e72edfac7..a2ba475df 100644 --- a/actix-session/src/lib.rs +++ b/actix-session/src/lib.rs @@ -27,8 +27,8 @@ //! against the active [`Session`]. //! //! `actix-session` provides some built-in storage backends: ([`CookieSessionStore`], -//! [`RedisSessionStore`], and [`RedisActorSessionStore`]) - you can create a custom storage backend -//! by implementing the [`SessionStore`] trait. +//! [`RedisSessionStore`]) - you can create a custom storage backend by implementing the +//! [`SessionStore`] trait. //! //! Further reading on sessions: //! - [RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265); @@ -136,7 +136,6 @@ //! [`SessionStore`]: storage::SessionStore //! [`CookieSessionStore`]: storage::CookieSessionStore //! [`RedisSessionStore`]: storage::RedisSessionStore -//! [`RedisActorSessionStore`]: storage::RedisActorSessionStore #![forbid(unsafe_code)] #![deny(rust_2018_idioms, nonstandard_style)] diff --git a/actix-web-httpauth/src/middleware.rs b/actix-web-httpauth/src/middleware.rs index 91cd6068e..253554e19 100644 --- a/actix-web-httpauth/src/middleware.rs +++ b/actix-web-httpauth/src/middleware.rs @@ -43,6 +43,55 @@ where { /// Construct `HttpAuthentication` middleware with the provided auth extractor `T` and /// validation callback `F`. + /// + /// This function can be used to implement optional authentication and/or custom responses to + /// missing authentication. + /// + /// # Examples + /// + /// ## Required Basic Auth + /// + /// ```no_run + /// # use actix_web_httpauth::extractors::basic::BasicAuth; + /// # use actix_web::dev::ServiceRequest; + /// async fn validator( + /// req: ServiceRequest, + /// credentials: BasicAuth, + /// ) -> Result { + /// eprintln!("{credentials:?}"); + /// + /// if credentials.user_id().contains('x') { + /// return Err((actix_web::error::ErrorBadRequest("user ID contains x"), req)); + /// } + /// + /// Ok(req) + /// } + /// # actix_web_httpauth::middleware::HttpAuthentication::with_fn(validator); + /// ``` + /// + /// ## Optional Bearer Auth + /// + /// ```no_run + /// # use actix_web_httpauth::extractors::bearer::BearerAuth; + /// # use actix_web::dev::ServiceRequest; + /// async fn validator( + /// req: ServiceRequest, + /// credentials: Option, + /// ) -> Result { + /// let Some(credentials) = credentials else { + /// return Err((actix_web::error::ErrorBadRequest("no bearer header"), req)); + /// }; + /// + /// eprintln!("{credentials:?}"); + /// + /// if credentials.token().contains('x') { + /// return Err((actix_web::error::ErrorBadRequest("token contains x"), req)); + /// } + /// + /// Ok(req) + /// } + /// # actix_web_httpauth::middleware::HttpAuthentication::with_fn(validator); + /// ``` pub fn with_fn(process_fn: F) -> HttpAuthentication { HttpAuthentication { process_fn: Arc::new(process_fn),