docs(httpauth): add HttpAuthentication::with_fn examples

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
 
 <!-- cargo-rdme end -->

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
+//! [`RedisSessionStore`]) - you can create a custom storage backend by implementing the
-//! by implementing the [`SessionStore`] trait.
+//! [`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)]

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<ServiceRequest, (actix_web::Error, ServiceRequest)> {
+    ///     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<BearerAuth>,
+    /// ) -> Result<ServiceRequest, (actix_web::Error, ServiceRequest)> {
+    ///     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<T, F> {
         HttpAuthentication {
             process_fn: Arc::new(process_fn),