Struct tower_sessions::Session

pub struct Session { /* private fields */ }

A session which allows HTTP applications to associate key-value pairs with visitors.

Implementations

impl Session

pub fn new() -> Self

Create a new session with defaults.

Note that an expiration_time of None results in a cookie with expiration "Session".

Examples

 use tower_sessions::Session;
 let session = Session::new();

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

A method for setting expiration_time in accordance with max_age.

Examples

use time::Duration;
use tower_sessions::Session;
let session = Session::new().with_max_age(Duration::minutes(5));

pub fn insert( &self, key: &str, value: impl Serialize ) -> Result<(), SessionError>

Inserts a impl Serialize value into the session.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).expect("Serialization error.");

Errors

This method can fail when serde_json::to_value fails.

pub fn insert_value(&self, key: &str, value: Value) -> Option<Value>

Inserts a serde_json::Value into the session.

If the key was not present in the underlying map, None is returned and modified is set to true.

If the underlying map did have the key and its value is the same as the provided value, None is returned and modified is not set.

Examples

use tower_sessions::Session;
let session = Session::new();
let value = session.insert_value("foo", serde_json::json!(42));
assert!(value.is_none());

let value = session.insert_value("foo", serde_json::json!(42));
assert!(value.is_none());

let value = session.insert_value("foo", serde_json::json!("bar"));
assert_eq!(value, Some(serde_json::json!(42)));

pub fn get<T: DeserializeOwned>( &self, key: &str ) -> Result<Option<T>, SessionError>

Gets a value from the store.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();
let value = session.get::<usize>("foo").unwrap();
assert_eq!(value, Some(42));

Errors

This method can fail when serde_json::from_value fails.

pub fn get_value(&self, key: &str) -> Option<Value>

Gets a serde_json::Value from the store.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();
let value = session.get_value("foo").unwrap();
assert_eq!(value, serde_json::json!(42));

pub fn remove<T: DeserializeOwned>( &self, key: &str ) -> Result<Option<T>, SessionError>

Removes a value from the store, retuning the value of the key if it was present in the underlying map.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();
let value: Option<usize> = session.remove("foo").unwrap();
assert_eq!(value, Some(42));
let value: Option<usize> = session.get("foo").unwrap();
assert!(value.is_none());

Errors

This method can fail when serde_json::from_value fails.

pub fn remove_value(&self, key: &str) -> Option<Value>

Removes a serde_json::Value from the store.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();
let value = session.remove_value("foo").unwrap();
assert_eq!(value, serde_json::json!(42));
let value: Option<usize> = session.get("foo").unwrap();
assert!(value.is_none());

pub fn replace_if_equal( &self, key: &str, old_value: impl Serialize, new_value: impl Serialize ) -> Result<bool, SessionError>

Replaces a value in the session with a new value if the current value matches the old value.

If the key was not present in the underlying map or the current value does not match, false is returned, indicating failure.

If the key was present and its value matches the old value, the new value is inserted, and true is returned, indicating success.

This method is essential for scenarios where data races need to be prevented. For instance, reading from and writing to a session is not transactional. To ensure that read values are not stale, it’s crucial to use replace_if_equal when modifying the session.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();

let success = session.replace_if_equal("foo", 42, 43).unwrap();
assert_eq!(success, true);

let success = session.replace_if_equal("foo", 42, 44).unwrap();
assert_eq!(success, false);

Errors

This method can fail when serde_json::to_value fails.

pub fn clear(&self)

Clears the session data.

Examples

use tower_sessions::Session;
let session = Session::new();
session.insert("foo", 42).unwrap();
session.clear();
assert!(session.get_value("foo").is_none());

pub fn delete(&self)

Sets deleted on the session to SessionDeletion::Deleted.

Setting this flag indicates the session should be deleted from the underlying store.

This flag is consumed by a session management system to ensure session life cycle progression.

Examples

use tower_sessions::{session::SessionDeletion, Session};
let session = Session::new();
session.delete();
assert!(matches!(session.deleted(), Some(SessionDeletion::Deleted)));

pub fn cycle_id(&self)

Sets deleted on the session to SessionDeletion::Cycled(self.id)).

Setting this flag indicates the session ID should be cycled while retaining the session’s data.

This flag is consumed by a session management system to ensure session life cycle progression.

Examples

use tower_sessions::{session::SessionDeletion, Session};
let session = Session::new();
session.cycle_id();
assert!(matches!(
    session.deleted(),
    Some(SessionDeletion::Cycled(cycled_id)) if cycled_id == session.id()
));

pub fn flush(&self)

Sets deleted on the session to SessionDeletion::Deleted and clears the session data.

This helps ensure that session data cannot be accessed beyond this invocation.

Examples

use tower_sessions::{session::SessionDeletion, Session};
let session = Session::new();
session.insert("foo", 42).unwrap();
session.flush();
assert!(session.get_value("foo").is_none());
assert!(matches!(session.deleted(), Some(SessionDeletion::Deleted)));

pub fn id(&self) -> SessionId

Get the session ID.

Examples

use tower_sessions::Session;
let session = Session::new();
session.id();

pub fn expiration_time(&self) -> Option<OffsetDateTime>

Get the session expiration time.

Examples

use time::{Duration, OffsetDateTime};
use tower_sessions::Session;
let session = Session::new().with_max_age(Duration::hours(1));
assert!(session
    .expiration_time()
    .is_some_and(|et| et > OffsetDateTime::now_utc()));

pub fn active(&self) -> bool

Returns true if the session is active and false otherwise.

Examples

use time::Duration;
use tower_sessions::Session;
let session = Session::new();
assert!(session.active());

let session = Session::new().with_max_age(Duration::hours(1));
assert!(session.active());

let session = Session::new().with_max_age(Duration::ZERO);
assert!(!session.active());

pub fn modified(&self) -> bool

Returns true if the session has been modified and false otherwise.

Examples

use tower_sessions::Session;
let session = Session::new();
assert!(!session.modified());
session.insert("foo", 42);
assert!(session.modified());

pub fn deleted(&self) -> Option<SessionDeletion>

Returns Some(SessionDeletion) if one has been set and None otherwise.

Examples

use tower_sessions::{session::SessionDeletion, Session};
let session = Session::new();
assert!(session.deleted().is_none());
session.delete();
assert!(matches!(session.deleted(), Some(SessionDeletion::Deleted)));
session.cycle_id();
assert!(matches!(
    session.deleted(),
    Some(SessionDeletion::Cycled(_))
))

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Session

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

Formats the value using the given formatter.

impl Default for Session

fn default() -> Session

Returns the “default value” for a type.

impl From<&CookieConfig> for Session

fn from(cookie_config: &CookieConfig) -> Self

Converts to this type from the input type.

impl From<&Session> for SessionRecord

fn from(session: &Session) -> Self

Converts to this type from the input type.

impl From<SessionRecord> for Session

fn from(_: SessionRecord) -> Self

Converts to this type from the input type.

impl<S> FromRequestParts<S> for Sessionwhere S: Sync + Send,

Available on crate feature axum-core only.

type Rejection = (StatusCode, &'static str)

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

fn from_request_parts<'life0, 'life1, 'async_trait>( parts: &'life0 mut Parts, _state: &'life1 S ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Rejection>> + Send + 'async_trait>>where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform the extraction.