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(expiry: Option<Expiry>) -> Self

Create a new session with the given expiry.

Examples

use time::{Duration, OffsetDateTime};
use tower_sessions::{Expiry, Session};

// Uses a so-called "session cookie".
let expiry = Expiry::OnSessionEnd;
Session::new(Some(expiry));

// Uses an inactivity expiry.
let expiry = Expiry::OnInactivity(Duration::hours(1));
Session::new(Some(expiry));

// Uses a date and time expiry.
let expired_at = OffsetDateTime::now_utc().saturating_add(Duration::hours(1));
let expiry = Expiry::AtDateTime(expired_at);
Session::new(Some(expiry));

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

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>, Error>

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>, Error>

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, Error>

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 Deletion::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::Deletion, Session};

let session = Session::default();
session.delete();
assert!(matches!(session.deleted(), Some(Deletion::Deleted)));

pub fn cycle_id(&self)

Sets deleted on the session to Deletion::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::Deletion, Session};

let session = Session::default();
session.insert("foo", 42);
session.cycle_id();
assert!(matches!(
    session.deleted(),
    Some(Deletion::Cycled(ref cycled_id)) if cycled_id == session.id()
));

pub fn flush(&self)

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

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

Examples

use tower_sessions::{session::Deletion, Session};

let session = Session::default();
session.insert("foo", 42).unwrap();
session.flush();
assert!(session.get_value("foo").is_none());
assert!(matches!(session.deleted(), Some(Deletion::Deleted)));

pub fn id(&self) -> &Id

Get the session ID.

Examples

use tower_sessions::Session;

let session = Session::default();
session.id();

pub fn expiry(&self) -> Option<Expiry>

Get the session expiry.

Examples

use time::{Duration, OffsetDateTime};
use tower_sessions::{Expiry, Session};

let expiry = Expiry::OnInactivity(Duration::hours(1));
let session = Session::default();
session.set_expiry(Some(expiry));
assert_eq!(
    session.expiry(),
    Some(Expiry::OnInactivity(Duration::hours(1)))
);

pub fn set_expiry(&self, expiry: Option<Expiry>)

Set expiry 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::{Expiry, Session};

let session = Session::default();
let expiry = Expiry::AtDateTime(OffsetDateTime::from_unix_timestamp(0).unwrap());
session.set_expiry(Some(expiry));
session.insert("foo", 42);
assert!(session.is_modified());

let expiry = Expiry::OnInactivity(Duration::weeks(2));
session.set_expiry(Some(expiry));
assert!(session.is_modified());

pub fn expiry_date(&self) -> OffsetDateTime

Get session expiry as OffsetDateTime.

Examples

use time::OffsetDateTime;
use tower_sessions::Session;

let session = Session::default();
assert!(session.expiry_date() > OffsetDateTime::now_utc());

pub fn expiry_age(&self) -> Duration

Get session expiry as Duration.

Examples

use time::Duration;
use tower_sessions::Session;

let session = Session::default();
assert!(session.expiry_age() > Duration::days(11));   

pub fn is_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.is_modified());

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

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

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

Examples

use tower_sessions::{session::Deletion, Session};

let session = Session::default();
session.insert("foo", 42);
assert!(session.deleted().is_none());

session.delete();
assert!(matches!(session.deleted(), Some(Deletion::Deleted)));

session.cycle_id();
assert!(matches!(session.deleted(), Some(Deletion::Cycled(_))))

pub fn is_empty(&self) -> bool

Returns true if the session is empty.

Examples

use tower_sessions::Session;

let session = Session::default();
assert!(session.is_empty());

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

Trait Implementations

impl Borrow<Id> for Session

fn borrow(&self) -> &Id

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<'de> Deserialize<'de> for Session

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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 Serialize for Session

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Session