Struct axum_session::SessionConfig

pub struct SessionConfig {

    pub(crate) store_name: Cow<'static, str>,
    pub(crate) session_name: Cow<'static, str>,
    pub(crate) key_name: Cow<'static, str>,
    pub(crate) cookie_domain: Option<Cow<'static, str>>,
    pub(crate) cookie_http_only: bool,
    pub(crate) cookie_max_age: Option<Duration>,
    pub(crate) cookie_path: Cow<'static, str>,
    pub(crate) cookie_same_site: SameSite,
    pub(crate) cookie_secure: bool,
    pub(crate) session_mode: SessionMode,
    pub(crate) lifespan: Duration,
    pub(crate) max_lifespan: Duration,
    pub(crate) purge_update: Duration,
    pub(crate) purge_database_update: Duration,
    pub(crate) always_save: bool,
    pub(crate) memory_lifespan: Duration,
    pub(crate) table_name: Cow<'static, str>,
    pub(crate) key: Option<Key>,
    pub(crate) database_key: Option<Key>,
    pub(crate) security_mode: SecurityMode,
    pub(crate) filter_expected_elements: u64,
    pub(crate) filter_false_positive_probability: f64,
    pub(crate) use_bloom_filters: bool,
    pub(crate) clear_check_on_load: bool,
    pub(crate) prefix_with_host: bool,
}

Configuration for how the Session and Cookies are used.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default();

Fields

store_name: Cow<'static, str>

The Cookie or Header name that contains a boolean for session saving. only used when session_mode is set to SessionMode::OptIn or Manual.

session_name: Cow<'static, str>

Session Cookie or Header name.

key_name: Cow<'static, str>

Session key Cookie or Header name.

cookie_domain: Option<Cow<'static, str>>

Session cookie domain.

cookie_http_only: bool

Session cookie http only flag.

cookie_max_age: Option<Duration>

Session cookie max age None means the browser deletes cookie on close. Please make sure the Duration is longer than max_lifespan.

cookie_path: Cow<'static, str>

Session cookie path.

cookie_same_site: SameSite

Resticts how Cookies are sent cross-site. Default is SameSite::Lax.

cookie_secure: bool

Session cookie secure flag.

session_mode: SessionMode

Disables the need to avoid session saving.

lifespan: Duration

Sessions the minimal lifespan a session can live in the database before expiring.

max_lifespan: Duration

Sessions the maximum lifespan a session can live in the database before expiring. This is generally used when a Session is set to be Long Term.

purge_update: Duration

This value represents the duration for how often session’s data gets purged from memory per request.

purge_database_update: Duration

This value represents the duration for how often session’s data gets purged from the database per request.

always_save: bool

Ignore’s the update checks and will always save the session to the database if set to true.

memory_lifespan: Duration

Session Memory lifespan, deturmines when to unload it from memory this works fine since the data can stay in the database till its needed if not yet expired.

table_name: Cow<'static, str>

Session Database table name default is async_sessions

key: Option<Key>

Encyption Key used to encypt cookies for confidentiality, integrity, and authenticity.

database_key: Option<Key>

Encyption Key used to encypt keys stored in the database for confidentiality.

security_mode: SecurityMode

Set how Secure you want SessionID’s to be stored as.

filter_expected_elements: u64

How many Elements could we see at one time in the Table? So if you have 1000 unique visitors a second and each generate a UUID. That would be 1000 * 60(secs) * 60(mins) * 24(hours) to get 1 days worth of visitors.

filter_false_positive_probability: f64

The probability of how many allowable false positives you want to have based on the expected elements. 0.01 is a good starting point.

use_bloom_filters: bool

This enabled using a counting bloom filter. If this is taking to much Memory or is to slow or you just dont want the false positives it can give you can disable it by setting it to false. This will reduce memory usage. By default this is enabled unless the specific database cant function with it then disabled.

clear_check_on_load: bool

This is to be used when your handling multiple Parallel Sessions to prevent the next one from unloaded data.

prefix_with_host: bool

This is used to append __Host- to the front of all Cookie names to prevent sub domain usage. This will not append to Headers only Cookies. It is enabled by default.

Implementations

impl SessionConfig

pub fn new() -> Self

Creates Default configuration of SessionConfig. This is equivalent to the SessionConfig::default().

pub fn with_store_name(self, name: impl Into<Cow<'static, str>>) -> Self

Set the session’s store Cookie or Header name.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_store_name("my_stored_cookie".to_owned());

pub fn with_cookie_domain(self, name: impl Into<Cow<'static, str>>) -> Self

Set’s the session’s cookie’s domain name.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_cookie_domain("www.helpme.com".to_string());

pub fn with_session_name(self, name: impl Into<Cow<'static, str>>) -> Self

Set’s the session’s Cookie or Header name.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_session_name("my_cookie");

pub fn with_key_name(self, name: impl Into<Cow<'static, str>>) -> Self

Set’s the session’s key Cookie or Header name.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_key_name("my_key_cookie");

pub fn with_cookie_path(self, path: impl Into<Cow<'static, str>>) -> Self

Set’s the session’s cookie’s path.

This is used to deturmine when the cookie takes effect within the website path. Leave as default (“/”) for cookie to be used site wide.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_cookie_path("/");

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

Set’s the session’s cookie’s Same Site Setting for Cross-Site restrictions.

Examples

use axum_session::SessionConfig;
use cookie::SameSite;

let config = SessionConfig::default().with_cookie_same_site(SameSite::Strict);

pub fn with_mode(self, mode: SessionMode) -> Self

Set’s whether the session Persistantly stores data or on stores if storable.

Examples

use axum_session::{SessionMode, SessionConfig};
use cookie::SameSite;

let config = SessionConfig::default().with_mode(SessionMode::Persistent);

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

Set’s the session’s cookie’s to http only.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_http_only(false);

pub fn with_lifetime(self, time: Duration) -> Self

Set’s the session’s lifetime (expiration time) within database storage. This should be equal too or less than the Cookies Expiration time.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_lifetime(Duration::days(32));

pub fn with_max_age(self, time: Option<Duration>) -> Self

Set’s the session’s cookies max_age (expiration time).

If this is set to None then the Cookie will be unloaded on browser Close. Set this to be the duration of max_lifespan or longer to prevent session drops. This is generally in a duration of how many Days a cookie should live in the browser. Please Ensure the Duration is greater or equal to max_lifespan for proper storage.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_max_age(Some(Duration::days(64)));

pub fn with_max_lifetime(self, time: Duration) -> Self

Set’s the session’s long term lifetime (expiration time) within database storage.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_max_lifetime(Duration::days(32));

pub fn with_memory_lifetime(self, time: Duration) -> Self

Set’s the session’s lifetime (expiration time) within memory storage. This setting should be Less than lifespan and max_lifespan. This is to Unload the data from memory and allow it to stay stored in the database.

Set this to Duration::zero() if you dont want it to stay in memory. Warning: This will cause it to be loaded from the database each request.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_memory_lifetime(Duration::days(32));

pub fn with_purge_update(self, duration: Duration) -> Self

This value represents the offset duration for how often session purge for memory is ran.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_purge_update(Duration::hours(1));

pub fn with_purge_database_update(self, duration: Duration) -> Self

This value represents the offset duration for how often session purge for database is ran. If using Redis or any auto purge database this Setting will be ignored.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_purge_database_update(Duration::hours(5));

pub fn with_always_save(self, always_save: bool) -> Self

This value represents if the database should check for updates to save or to just save the data regardless of updates. When set to true it will disable the update checks.

Examples

use axum_session::SessionConfig;
use chrono::Duration;

let config = SessionConfig::default().with_always_save(true);

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

Set’s the session’s secure flag for if it gets sent over https.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_secure(true);

pub fn with_table_name(self, table_name: impl Into<Cow<'static, str>>) -> Self

Set’s the session’s database table name.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_table_name("my_table");

pub fn with_key(self, key: Key) -> Self

Set’s the session’s cookie encyption key enabling private cookies.

When Set it will enforce Private cookies across all Sessions. If you use Key::generate() it will make a new key each server reboot. To prevent this make and save a key to a config file for long term usage. For Extra Security Regenerate the key every so many months to a year. A new key will invalidate all old Sessions so it be wise to run session_store.clear_store() on reboot.

Must be Set to Some() in order to use Security::PerSession.

Examples

use axum_session::{Key, SessionConfig};

let config = SessionConfig::default().with_key(Key::generate());

pub fn with_database_key(self, key: Key) -> Self

Set’s the session’s database encyption key for per session key storage.

Must be Set to Some() in order to use Security::PerSession or will panic if not.

Examples

use axum_session::{Key, SessionConfig};

let config = SessionConfig::default().with_key(Key::generate());

pub fn with_security_mode(self, mode: SecurityMode) -> Self

Set’s the session’s security mode.

Examples

use axum_session::{SecurityMode, SessionConfig};

let config = SessionConfig::default().with_security_mode(SecurityMode::PerSession);

pub fn with_filter_expected_elements(self, elements: u64) -> Self

Set’s the session’s filters expected elements. Please Set this by a daily value. Example: 1000 * 60(secs) * 60(mins) * 24(hours) to get 1 days worth of visitors.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_filter_expected_elements(100_000);

pub fn with_filter_false_positive_probability(self, probability: f64) -> Self

Set’s the session’s filters False Posistive probability when creating and comparing UUID.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_filter_false_positive_probability(0.01);

pub fn with_bloom_filter(self, enable: bool) -> Self

Set’s the session’s bloom filters to be disabled or enabled. By default they are enabled.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_bloom_filter(true);

pub fn get_session_name(&self) -> String

Get’s the session’s Cookie/Header name

Examples

use axum_session::SessionConfig;

let name = SessionConfig::default().get_session_name();

pub fn get_key_name(&self) -> String

Get’s the session’s Key Cookie/Header name

Examples

use axum_session::SessionConfig;

let name = SessionConfig::default().get_key_name();

pub fn get_store_name(&self) -> String

Get’s the session’s store booleans Cookie/Header name

Examples

use axum_session::SessionConfig;

let name = SessionConfig::default().get_store_name();

pub fn with_clear_check_on_load(self, enable: bool) -> Self

Set’s the session’s loading to either true: unload data if checks fail or false: bypass.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_bloom_filter(true);

pub fn with_prefix_with_host(self, enable: bool) -> Self

Set’s the session’s prefix_with_host to either true: __Host- gets prefixed to the cookie names false: __Host- does not get prepended.

__Host- prefix: Cookies with names starting with __Host- must be set with the secure flag, must be from a secure page (HTTPS), must not have a domain specified (and therefore, are not sent to subdomains), and the path must be /.

Examples

use axum_session::SessionConfig;

let config = SessionConfig::default().with_prefix_with_host(true);

Trait Implementations

impl Clone for SessionConfig

fn clone(&self) -> SessionConfig

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SessionConfig

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

Formats the value using the given formatter.

impl Default for SessionConfig

fn default() -> Self

Returns the “default value” for a type.