final session doc tweaks

actix-session/src/lib.rs

@@ -26,9 +26,9 @@
 //! **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: ([`storage::CookieSessionStore`],
+//! `actix-session` provides some built-in storage backends: ([`CookieSessionStore`],
-//! [`storage::RedisSessionStore`], and [`storage::RedisActorSessionStore`]) - you can create a
+//! [`RedisSessionStore`], and [`RedisActorSessionStore`]) - you can create a custom storage backend
-//! custom storage backend by implementing the [`SessionStore`](storage::SessionStore) trait.
+//! by implementing the [`SessionStore`] trait.
 //!
 //! Further reading on sessions:
 //! - [RFC6265](https://datatracker.ietf.org/doc/html/rfc6265);
@@ -72,10 +72,10 @@
 //! use actix_session::Session;
 //!
 //! fn index(session: Session) -> Result<&'static str, Error> {
-//!     // Access the session state
+//!     // access the session state
 //!     if let Some(count) = session.get::<i32>("counter")? {
 //!         println!("SESSION value: {}", count);
-//!         // Modify the session state
+//!         // modify the session state
 //!         session.insert("counter", count + 1)?;
 //!     } else {
 //!         session.insert("counter", 1)?;
@@ -90,43 +90,48 @@
 //! By default, `actix-session` does not provide any storage backend to retrieve and save the state
 //! attached to your sessions. You can enable:
 //!
-//! - a purely cookie-based "backend", [`storage::CookieSessionStore`], using the `cookie-session`
+//! - a purely cookie-based "backend", [`CookieSessionStore`], using the `cookie-session` feature
-//!   feature flag.
+//!   flag.
 //!
-//! ```toml
+//!   ```toml
-//! [dependencies]
+//!   [dependencies]
-//! # ...
+//!   # ...
-//! actix-session = { version = "...", features = ["cookie-session"] }
+//!   actix-session = { version = "...", features = ["cookie-session"] }
-//! ```
+//!   ```
 //!
-//! - a Redis-based backend via `actix-redis`, [`storage::RedisActorSessionStore`], using the
+//! - a Redis-based backend via [`actix-redis`](https://docs.rs/acitx-redis),
-//!   `redis-actor-session` feature flag.
+//!   [`RedisActorSessionStore`], using the `redis-actor-session` feature flag.
 //!
-//! ```toml
+//!   ```toml
-//! [dependencies]
+//!   [dependencies]
-//! # ...
+//!   # ...
-//! actix-session = { version = "...", features = ["redis-actor-session"] }
+//!   actix-session = { version = "...", features = ["redis-actor-session"] }
-//! ```
+//!   ```
 //!
-//! - a Redis-based backend via [`redis-rs`](https://github.com/mitsuhiko/redis-rs),
+//! - a Redis-based backend via [`redis-rs`](https://docs.rs/redis-rs), [`RedisSessionStore`], using
-//!   [`storage::RedisSessionStore`], using the `redis-rs-session` feature flag.
+//!   the `redis-rs-session` feature flag.
 //!
-//! ```toml
+//!   ```toml
-//! [dependencies]
+//!   [dependencies]
-//! # ...
+//!   # ...
-//! actix-session = { version = "...", features = ["redis-rs-session"] }
+//!   actix-session = { version = "...", features = ["redis-rs-session"] }
-//! ```
+//!   ```
 //!
-//! Add the `redis-rs-tls-session` feature flag if you want to connect to Redis using a secured
+//!   Add the `redis-rs-tls-session` feature flag if you want to connect to Redis using a secured
-//! connection:
+//!   connection:
 //!
-//! ```toml
+//!   ```toml
-//! [dependencies]
+//!   [dependencies]
-//! # ...
+//!   # ...
-//! actix-session = { version = "...", features = ["redis-rs-session", "redis-rs-tls-session"] }
+//!   actix-session = { version = "...", features = ["redis-rs-session", "redis-rs-tls-session"] }
-//! ```
+//!   ```
 //!
-//! You can provide a different session store by implementing the [`storage::SessionStore`] trait.
+//! You can implement your own session storage backend using the [`SessionStore`] trait.
+//!
+//! [`SessionStore`]: storage::SessionStore
+//! [`CookieSessionStore`]: storage::CookieSessionStore
+//! [`RedisSessionStore`]: storage::RedisSessionStore
+//! [`RedisActorSessionStore`]: storage::RedisActorSessionStore
 
 #![deny(rust_2018_idioms, nonstandard_style)]
 #![warn(future_incompatible, missing_docs)]

actix-session/src/middleware.rs

@@ -188,13 +188,15 @@ pub enum SessionLength {
 /// the content of the session cookie.
 #[derive(Debug, Clone, Copy)]
 pub enum CookieContentSecurity {
-    /// `CookieContentSecurity::Private` translates into an encrypted cookie content. The end-user/
+    /// `CookieContentSecurity::Private` selects encrypted cookie content.
-    /// JavaScript cannot tamper with its content nor decode it (i.e., it preserves confidentiality,
+    ///
-    /// as long the as the encryption key is not breached).
+    /// The client cannot tamper with its contents nor decode it (i.e., preserves confidentiality as
+    /// long the as the encryption key is not breached).
     Private,
 
-    /// `CookieContentSecurity::Signed` translates into a signed cookie content. The end-user/
+    /// `CookieContentSecurity::Signed` selects signed cookie content.
-    /// JavaScript cannot tamper with its content, but they can read it (i.e., no confidentiality).
+    ///
+    /// The client cannot tamper with its contents, but they can read it (i.e., no confidentiality).
     Signed,
 }
 
@@ -327,8 +329,8 @@ impl<Store: SessionStore> SessionMiddlewareBuilder<Store> {
 
     /// Choose how the session cookie content should be secured.
     ///
-    /// - `CookieContentSecurity::Private` translates into an encrypted cookie content.
+    /// - [`CookieContentSecurity::Private`] selects encrypted cookie content.
-    /// - `CookieContentSecurity::Signed` translates into a signed cookie content.
+    /// - [`CookieContentSecurity::Signed`] selects signed cookie content.
     ///
     /// # Default
     /// By default, the cookie content is encrypted. Encrypted was chosen instead of signed as

actix-session/src/storage/interface.rs

@@ -10,6 +10,10 @@ pub(crate) type SessionState = HashMap<String, String>;
 /// The interface to retrieve and save the current session data from/to the chosen storage backend.
 ///
 /// You can provide your own custom session store backend by implementing this trait.
+///
+/// [`async-trait`](https://docs.rs/async-trait) is used for this trait's definition. Therefore, it
+/// is required for implementations, too. In particular, we use the send-optional variant:
+/// `#[async_trait(?Send)]`.
 #[async_trait::async_trait(?Send)]
 pub trait SessionStore {
     /// Loads the session state associated to a session key.