Struct Session

pub struct Session<SessionData, const COOKIE_LENGTH: usize = 32> { /* private fields */ }

A session with a client. This type handles the creation, updating and deletion of sessions. It is marked #[must_use], as dropping it will not update the session store. Instead, it should be passed to SessionStore::store_session.

SessionData is the data associated with a session. COOKIE_LENGTH is the length of the session cookie, in characters. The default choice is 32, which is secure. It should be a multiple of 32, which is the block size of blake3.

Implementations

impl<SessionData, const COOKIE_LENGTH: usize> Session<SessionData, COOKIE_LENGTH>

pub fn into_data_expiry_pair( self, ) -> (Option<SessionData>, Option<SessionExpiry>)

Extract the optionally associated data and expiry while consuming the session.

This function is supposed to be used in tests only. This loses the association of the data to the actual session, making it useless for most purposes.

impl<SessionData: Default, const COOKIE_LENGTH: usize> Session<SessionData, COOKIE_LENGTH>

pub fn new() -> Self

Create a new session with default data. Does not set an expiry. Using this method does not mark the session as changed, i.e. it will be silently dropped if neither the data nor the expiry are accessed mutably.

Example

let session: Session<i32> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
assert_eq!(i32::default(), *session.data());

impl<SessionData, const COOKIE_LENGTH: usize> Session<SessionData, COOKIE_LENGTH>

pub fn new_with_data(data: SessionData) -> Self

Create a new session with the given session data. Does not set an expiry. Using this method marks the session as changed, i.e. it will be stored in the backend and communicated to the client even if it was created with default data and never accessed mutably.

Example

let session: Session<_> = Session::new_with_data(4);
assert_eq!(&SessionExpiry::Never, session.expiry());
assert_eq!(4, *session.data());

pub fn new_from_session_store( current_id: SessionId, expiry: SessionExpiry, data: SessionData, ) -> Self

This method should only be called by a session store!

Create a session instance from parts loaded by a session store. The session state will be Unchanged.

pub fn is_deleted(&self) -> bool

Returns true if this session is marked for destruction.

Example

let mut session: Session<()> = Session::new();
assert!(!session.is_deleted());
session.delete();
assert!(session.is_deleted());

pub fn is_changed(&self) -> bool

Returns true if this session was changed since it was loaded from the session store.

Example

let mut session: Session<()> = Session::new();
assert!(!session.is_changed());
session.data_mut();
assert!(session.is_changed());

pub fn is_changed_or_deleted(&self) -> bool

Returns true if this session was changed since it was loaded from the session store, or if it is marked for destruction.

Example

let mut session: Session<()> = Session::new();
assert!(!session.is_changed_or_deleted());
session.data_mut();
assert!(session.is_changed_or_deleted());
let mut session: Session<()> = Session::new();
assert!(!session.is_changed_or_deleted());
session.delete();
assert!(session.is_changed_or_deleted());

impl<SessionData: Debug, const COOKIE_LENGTH: usize> Session<SessionData, COOKIE_LENGTH>

pub fn expiry(&self) -> &SessionExpiry

Returns the expiry timestamp of this session, if there is one.

Example

let mut session: Session<()> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
session.expire_in(Utc::now(), std::time::Duration::from_secs(1));
assert!(matches!(session.expiry(), SessionExpiry::DateTime { .. }));

pub fn data(&self) -> &SessionData

Returns a reference to the data associated with this session. This does not mark the session as changed.

pub fn data_mut(&mut self) -> &mut SessionData

Returns a mutable reference to the data associated with this session, and marks the session as changed.

Note that the session gets marked as changed, even if the returned reference is never written to.

Panics if the session was marked for deletion before.

pub fn delete(&mut self)

Mark this session for destruction. Further access to this session will result in a panic. Note that the session is only deleted from the session store if SessionStore::store_session is called.

Example

let mut session: Session<()> = Session::new();
assert!(!session.is_deleted());
session.delete();
assert!(session.is_deleted());

pub fn regenerate(&mut self)

Forces the generation of a new id and cookie for this session, unless the session is new and its data was not accessed mutably.

pub fn set_expiry(&mut self, expiry: DateTime<Utc>)

Updates the expiry timestamp of this session.

Example

let mut session: Session<()> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
session.set_expiry(chrono::Utc::now());
assert!(matches!(session.expiry(), SessionExpiry::DateTime { .. }));

pub fn do_not_expire(&mut self)

Sets this session to never expire.

Example

let mut session: Session<()> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
session.set_expiry(chrono::Utc::now());
assert!(matches!(session.expiry(), SessionExpiry::DateTime { .. }));
session.do_not_expire();
assert!(matches!(session.expiry(), SessionExpiry::Never));

pub fn expire_in(&mut self, now: DateTime<Utc>, ttl: Duration)

Sets this session to expire ttl time into the future.

Example

let mut session: Session<()> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
session.expire_in(Utc::now(), std::time::Duration::from_secs(1));
assert!(matches!(session.expiry(), SessionExpiry::DateTime { .. }));

pub fn is_expired(&self, now: DateTime<Utc>) -> bool

Return true if the session is expired. The session is expired if it has an expiry timestamp that is in the future.

Example

let mut session: Session<()> = Session::new();
assert_eq!(&SessionExpiry::Never, session.expiry());
assert!(!session.is_expired(Utc::now()));
session.expire_in(Utc::now(), Duration::from_secs(1));
assert!(!session.is_expired(Utc::now()));
task::sleep(Duration::from_secs(2)).await;
assert!(session.is_expired(Utc::now()));

pub fn expires_in(&self, now: DateTime<Utc>) -> Option<Duration>

Returns the duration from now to the expiry time of this session. Returns None if it is expired.

Example

let mut session: Session<()> = Session::new();
session.expire_in(Utc::now(), Duration::from_secs(123));
let expires_in = session.expires_in(Utc::now()).unwrap();
assert!(123 - expires_in.as_secs() < 2);

Trait Implementations

impl<SessionData: Clone, const COOKIE_LENGTH: usize> Clone for Session<SessionData, COOKIE_LENGTH>

fn clone(&self) -> Session<SessionData, COOKIE_LENGTH>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<SessionData: Debug, const COOKIE_LENGTH: usize> Debug for Session<SessionData, COOKIE_LENGTH>

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

Formats the value using the given formatter.

impl<SessionData: Default, const COOKIE_LENGTH: usize> Default for Session<SessionData, COOKIE_LENGTH>

fn default() -> Self

Returns the “default value” for a type.