diff --git a/actix-session/src/lib.rs b/actix-session/src/lib.rs index 6f42f9841..b5ac90486 100644 --- a/actix-session/src/lib.rs +++ b/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`], -//! [`storage::RedisSessionStore`], and [`storage::RedisActorSessionStore`]) - you can create a -//! custom storage backend by implementing the [`SessionStore`](storage::SessionStore) trait. +//! `actix-session` provides some built-in storage backends: ([`CookieSessionStore`], +//! [`RedisSessionStore`], and [`RedisActorSessionStore`]) - you can create a custom storage backend +//! 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::("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` -//! feature flag. +//! - a purely cookie-based "backend", [`CookieSessionStore`], using the `cookie-session` feature +//! flag. //! -//! ```toml -//! [dependencies] -//! # ... -//! actix-session = { version = "...", features = ["cookie-session"] } -//! ``` +//! ```toml +//! [dependencies] +//! # ... +//! actix-session = { version = "...", features = ["cookie-session"] } +//! ``` //! -//! - a Redis-based backend via `actix-redis`, [`storage::RedisActorSessionStore`], using the -//! `redis-actor-session` feature flag. +//! - a Redis-based backend via [`actix-redis`](https://docs.rs/acitx-redis), +//! [`RedisActorSessionStore`], using the `redis-actor-session` feature flag. //! -//! ```toml -//! [dependencies] -//! # ... -//! actix-session = { version = "...", features = ["redis-actor-session"] } -//! ``` +//! ```toml +//! [dependencies] +//! # ... +//! actix-session = { version = "...", features = ["redis-actor-session"] } +//! ``` //! -//! - a Redis-based backend via [`redis-rs`](https://github.com/mitsuhiko/redis-rs), -//! [`storage::RedisSessionStore`], using the `redis-rs-session` feature flag. +//! - a Redis-based backend via [`redis-rs`](https://docs.rs/redis-rs), [`RedisSessionStore`], using +//! the `redis-rs-session` feature flag. //! -//! ```toml -//! [dependencies] -//! # ... -//! actix-session = { version = "...", features = ["redis-rs-session"] } -//! ``` +//! ```toml +//! [dependencies] +//! # ... +//! 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 -//! connection: +//! Add the `redis-rs-tls-session` feature flag if you want to connect to Redis using a secured +//! connection: //! -//! ```toml -//! [dependencies] -//! # ... -//! actix-session = { version = "...", features = ["redis-rs-session", "redis-rs-tls-session"] } -//! ``` +//! ```toml +//! [dependencies] +//! # ... +//! 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)] diff --git a/actix-session/src/middleware.rs b/actix-session/src/middleware.rs index d2aaf4f07..2c2b6241a 100644 --- a/actix-session/src/middleware.rs +++ b/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/ - /// JavaScript cannot tamper with its content nor decode it (i.e., it preserves confidentiality, - /// as long the as the encryption key is not breached). + /// `CookieContentSecurity::Private` selects encrypted cookie content. + /// + /// 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/ - /// JavaScript cannot tamper with its content, but they can read it (i.e., no confidentiality). + /// `CookieContentSecurity::Signed` selects signed cookie content. + /// + /// The client cannot tamper with its contents, but they can read it (i.e., no confidentiality). Signed, } @@ -327,8 +329,8 @@ impl SessionMiddlewareBuilder { /// Choose how the session cookie content should be secured. /// - /// - `CookieContentSecurity::Private` translates into an encrypted cookie content. - /// - `CookieContentSecurity::Signed` translates into a signed cookie content. + /// - [`CookieContentSecurity::Private`] selects encrypted cookie content. + /// - [`CookieContentSecurity::Signed`] selects signed cookie content. /// /// # Default /// By default, the cookie content is encrypted. Encrypted was chosen instead of signed as diff --git a/actix-session/src/storage/interface.rs b/actix-session/src/storage/interface.rs index 0419de954..64b10338f 100644 --- a/actix-session/src/storage/interface.rs +++ b/actix-session/src/storage/interface.rs @@ -10,6 +10,10 @@ pub(crate) type SessionState = HashMap; /// 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.