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(expiration_time: Option<OffsetDateTime>) -> Self

Create a new session with defaults.

If an expiration_time is not specified, the session will use an expiration strategy of “Session,” which means it will persist only until the user’s session ends.

Examples

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

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::default();
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::default();
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::default();
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::default();
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::default();
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::default();
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::default();
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::default();
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::default();
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::default();
session.insert("foo", 42);
session.cycle_id();
assert!(matches!(
    session.deleted(),
    Some(SessionDeletion::Cycled(ref 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::default();
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::default();
session.id();

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

Get the session expiration time.

Examples

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

pub fn set_expiration_time(&self, expiration_time: OffsetDateTime)

Set expiration_time give the given value.

This may be used within applications directly to alter the session’s time to live.

Examples

use time::{Duration, OffsetDateTime};
use tower_sessions::Session;
let session = Session::default();
session.set_expiration_time(OffsetDateTime::now_utc());
session.insert("foo", 42);
assert!(!session.active());
assert!(session.modified());

session.set_expiration_time(OffsetDateTime::now_utc().saturating_add(Duration::hours(1)));
assert!(session.active());
assert!(session.modified());

pub fn set_expiration_time_from_max_age(&self, max_age: Duration)

Set expiration_time to current time in UTC plus the given max_age duration.

This may be used within applications directly to alter the session’s time to live.

Examples

use time::Duration;
use tower_sessions::Session;
let session = Session::default();
session.insert("foo", 42);
session.set_expiration_time_from_max_age(Duration::minutes(5));
assert!(session.active());
assert!(session.modified());

session.set_expiration_time_from_max_age(Duration::ZERO);
assert!(!session.active());
assert!(session.modified());

pub fn active(&self) -> bool

Returns true if the session is active and false otherwise.

Examples

use time::{Duration, OffsetDateTime};
use tower_sessions::Session;
let session = Session::default();
assert!(session.active());

let expiration_time = OffsetDateTime::now_utc().saturating_add(Duration::hours(1));
let session = Session::new(Some(expiration_time));
assert!(session.active());

let expiration_time = OffsetDateTime::now_utc().saturating_add(Duration::ZERO);
let session = Session::new(Some(expiration_time));
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::default();
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::default();
session.insert("foo", 42);
assert!(session.deleted().is_none());
session.delete();
assert!(matches!(session.deleted(), Some(SessionDeletion::Deleted)));
session.cycle_id();
assert!(matches!(
    session.deleted(),
    Some(SessionDeletion::Cycled(_))
))

pub fn is_empty(&self) -> bool

Returns true if the session is empty.

Examples

use tower_sessions::{Session, SessionRecord};
let session = Session::default();
assert!(session.is_empty());

session.insert("foo", 42);
assert!(!session.is_empty());

Trait Implementations

impl Borrow<SessionId> for Session

fn borrow(&self) -> &SessionId

Immutably borrows from an owned value.

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.

impl Hash for Session

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Session

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Session