Struct SessionConfig 

pub struct SessionConfig { /* private fields */ }

Available on crate feature auth only.

Resolved session configuration.

Construct with SessionConfig::new (a signed-cookie layer), then pass to SessionConfig::into_layer with a session store to build a SessionLayer for Axum. Configuration is explicit and resolved; the library never reads environment variables inside layer construction or request handling.

Signing key

The cookie signing key must be exactly 64 bytes, the master-key length required by the certified cookie crate’s signed jar. Use SessionKey::generate to produce a cryptographically random key. The key is held in a secrecy::SecretSlice; its Debug output never exposes the bytes.

Two lifetimes

A session has two independent expiry bounds:

• Idle/inactivity (max_age, Self::with_max_age) – a sliding window mapped to tower_sessions::Expiry::OnInactivity: each request that saves the session resets it.
• Absolute (absolute_max_age, Self::with_absolute_max_age) – the maximum authenticated lifetime measured from the authentication timestamp stored in the session at login, enforced at the auth boundary.

Implementations

impl SessionConfig

pub fn new(signing_key: &[u8]) -> Result<Self, SessionConfigError>

Build session configuration with a signed-cookie key.

signing_key must be exactly 64 bytes. The cookie attributes default to secure values: name "__Host-id", SameSite=Strict, Secure=true, HttpOnly=true, path "/", no domain, idle Max-Age 14 days, absolute lifetime 30 days. Override any with the with_* builder methods.

The __Host- prefix

The default cookie name is __Host-id. A __Host- prefix mandates Secure, no Domain, and path / (RFC 6265bis), which the default attributes already satisfy, so the rename is strictly tighter. It defeats session-fixation/cookie-tossing from a sibling subdomain. For development over plain HTTP use SessionConfig::dev (a __Host- cookie is silently dropped by the browser when it is not Secure).

Errors

Returns SessionConfigError::InvalidSigningKey if the key is not exactly 64 bytes.

pub fn dev(signing_key: &[u8]) -> Result<Self, SessionConfigError>

Build session configuration with the development defaults: cookie name arcature-id (no __Host- prefix), SameSite=Strict, Secure = false, HttpOnly=true, path "/", no domain, idle Max-Age 14 days, absolute lifetime 30 days.

A development server on plain HTTP cannot use the __Host- prefix (the browser drops a non-Secure __Host- cookie); this policy uses a plain cookie name so the session cookie reaches the browser over HTTP. Production keeps SessionConfig::new (__Host-id, Secure = true).

Errors

Returns SessionConfigError::InvalidSigningKey if the key is not exactly 64 bytes.

pub fn with_cookie_name(self, name: impl Into<String>) -> Self

Override the session cookie name.

pub fn with_same_site(self, same_site: SameSite) -> Self

Override the SameSite attribute. Default SameSite::Strict.

pub fn with_secure(self, secure: bool) -> Self

Override the Secure attribute (default true).

pub fn with_http_only(self, http_only: bool) -> Self

Override the HttpOnly attribute (default true).

pub fn with_path(self, path: impl Into<String>) -> Self

Override the cookie Path attribute (default "/").

pub fn with_domain(self, domain: impl Into<String>) -> Self

Override the cookie Domain attribute (default: none).

pub fn with_max_age(self, max_age: Duration) -> Self

Override the session idle/inactivity timeout. Default 14 days.

This is a sliding window: it is mapped to tower_sessions::Expiry::OnInactivity, so each request that saves the session resets the clock. The maximum authenticated lifetime is a separate bound – see Self::with_absolute_max_age.

pub fn with_absolute_max_age(self, absolute_max_age: Duration) -> Self

Override the absolute authenticated session lifetime. Default 30 days.

pub fn absolute_max_age(&self) -> Duration

The configured absolute authenticated session lifetime.

pub fn into_layer<Store>( self, store: Store, ) -> Result<SessionLayer<Store>, SessionBuildError>

where Store: SessionStore,

Build a SessionLayer over store. Validates the configuration before constructing the tower-sessions layer.

Errors

Returns SessionBuildError if the configuration is internally inconsistent (empty name/path, zero max-age, wrong key length, a __Host- cookie combined with Secure = false).

Trait Implementations

impl Clone for SessionConfig

fn clone(&self) -> SessionConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionConfig

Manual Debug – the signing key is never exposed.

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.