[][src]Struct async_session::Session

pub struct Session { /* fields omitted */ }

The main session type.

Cloning and Serialization

The cookie_value field is not cloned or serialized, and it can only be read through into_cookie_value. The intent of this field is that it is set either by initialization or by a session store, and read exactly once in order to set the cookie value.

Change tracking session tracks whether any of its inner data

was changed since it was last serialized. Any sessoin store that does not undergo a serialization-deserialization cycle must call Session::reset_data_changed in order to reset the change tracker on an individual record.

Change tracking example

let mut session = Session::new();
assert!(!session.data_changed());

session.insert("key", 1)?;
assert!(session.data_changed());

session.reset_data_changed();
assert_eq!(session.get::<usize>("key").unwrap(), 1);
assert!(!session.data_changed());

session.insert("key", 2)?;
assert!(session.data_changed());
assert_eq!(session.get::<usize>("key").unwrap(), 2);

session.insert("key", 1)?;
assert!(session.data_changed(), "reverting the data still counts as a change");

session.reset_data_changed();
assert!(!session.data_changed());
session.remove("nonexistent key");
assert!(!session.data_changed());
session.remove("key");
assert!(session.data_changed());

Implementations

impl Session[src]

pub fn new() -> Self[src]

Create a new session. Generates a random id and matching cookie value. Does not set an expiry by default

Example

let session = Session::new();
assert_eq!(None, session.expiry());
assert!(session.into_cookie_value().is_some());

applies a cryptographic hash function on a cookie value returned by Session::into_cookie_value to obtain the session id for that cookie. Returns an error if the cookie format is not recognized

Example

let session = Session::new();
let id = session.id().to_string();
let cookie_value = session.into_cookie_value().unwrap();
assert_eq!(id, Session::id_from_cookie_value(&cookie_value)?);

pub fn destroy(&mut self)[src]

mark this session for destruction. the actual session record is not destroyed until the end of this response cycle.

Example

let mut session = Session::new();
assert!(!session.is_destroyed());
session.destroy();
assert!(session.is_destroyed());

pub fn is_destroyed(&self) -> bool[src]

returns true if this session is marked for destruction

Example

let mut session = Session::new();
assert!(!session.is_destroyed());
session.destroy();
assert!(session.is_destroyed());

pub fn id(&self) -> &str[src]

Gets the session id

Example

let session = Session::new();
let id = session.id().to_owned();
let cookie_value = session.into_cookie_value().unwrap();
assert_eq!(id, Session::id_from_cookie_value(&cookie_value)?);

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

inserts a serializable value into the session hashmap. returns an error if the serialization was unsuccessful.

Example

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
    legs: u8
}
let mut session = Session::new();
session.insert("user", User { name: "chashu".into(), legs: 4 }).expect("serializable");
assert_eq!(r#"{"name":"chashu","legs":4}"#, session.get_raw("user").unwrap());

pub fn insert_raw(&mut self, key: &str, value: String)[src]

inserts a string into the session hashmap

Example

let mut session = Session::new();
session.insert_raw("ten", "10".to_string());
let ten: usize = session.get("ten").unwrap();
assert_eq!(ten, 10);

pub fn get<T: DeserializeOwned>(&self, key: &str) -> Option<T>[src]

deserializes a type T out of the session hashmap

Example

let mut session = Session::new();
session.insert("key", vec![1, 2, 3]);
let numbers: Vec<usize> = session.get("key").unwrap();
assert_eq!(vec![1, 2, 3], numbers);

pub fn get_raw(&self, key: &str) -> Option<String>[src]

returns the String value contained in the session hashmap

Example

let mut session = Session::new();
session.insert("key", vec![1, 2, 3]);
assert_eq!("[1,2,3]", session.get_raw("key").unwrap());

pub fn remove(&mut self, key: &str)[src]

removes an entry from the session hashmap

Example

let mut session = Session::new();
session.insert("key", "value");
session.remove("key");
assert!(session.get_raw("key").is_none());
assert_eq!(session.len(), 0);

pub fn len(&self) -> usize[src]

returns the number of elements in the session hashmap

Example

let mut session = Session::new();
assert_eq!(session.len(), 0);
session.insert("key", 0);
assert_eq!(session.len(), 1);

pub fn regenerate(&mut self)[src]

Generates a new id and cookie for this session

Example

let mut session = Session::new();
let old_id = session.id().to_string();
session.regenerate();
assert!(session.id() != &old_id);
let new_id = session.id().to_string();
let cookie_value = session.into_cookie_value().unwrap();
assert_eq!(new_id, Session::id_from_cookie_value(&cookie_value)?);

sets the cookie value that this session will use to serialize itself. this should only be called by cookie stores. any other uses of this method will result in the cookie not getting correctly deserialized on subsequent requests.

Example

let mut session = Session::new();
session.set_cookie_value("hello".to_owned());
let cookie_value = session.into_cookie_value().unwrap();
assert_eq!(cookie_value, "hello".to_owned());

pub fn expiry(&self) -> Option<&DateTime<Utc>>[src]

returns the expiry timestamp of this session, if there is one

Example

let mut session = Session::new();
assert_eq!(None, session.expiry());
session.expire_in(std::time::Duration::from_secs(1));
assert!(session.expiry().is_some());

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

assigns an expiry timestamp to this session

Example

let mut session = Session::new();
assert_eq!(None, session.expiry());
session.set_expiry(chrono::Utc::now());
assert!(session.expiry().is_some());

pub fn expire_in(&mut self, ttl: Duration)[src]

assigns the expiry timestamp to a duration from the current time.

Example

let mut session = Session::new();
assert_eq!(None, session.expiry());
session.expire_in(std::time::Duration::from_secs(1));
assert!(session.expiry().is_some());

pub fn is_expired(&self) -> bool[src]

predicate function to determine if this session is expired. returns false if there is no expiry set, or if it is in the past.

Example

let mut session = Session::new();
assert_eq!(None, session.expiry());
assert!(!session.is_expired());
session.expire_in(Duration::from_secs(1));
assert!(!session.is_expired());
task::sleep(Duration::from_secs(2)).await;
assert!(session.is_expired());

pub fn validate(self) -> Option<Self>[src]

Ensures that this session is not expired. Returns None if it is expired

Example

let session = Session::new();
let mut session = session.validate().unwrap();
session.expire_in(Duration::from_secs(1));
let session = session.validate().unwrap();
task::sleep(Duration::from_secs(2)).await;
assert_eq!(None, session.validate());

pub fn data_changed(&self) -> bool[src]

Checks if the data has been modified. This is based on the implementation of PartialEq for the inner data type.

Example

let mut session = Session::new();
assert!(!session.data_changed(), "new session is not changed");
session.insert("key", 1);
assert!(session.data_changed());

session.reset_data_changed();
assert!(!session.data_changed());
session.remove("key");
assert!(session.data_changed());

pub fn reset_data_changed(&self)[src]

Resets data_changed dirty tracking. This is unnecessary for any session store that serializes the data to a string on storage.

Example

let mut session = Session::new();
assert!(!session.data_changed(), "new session is not changed");
session.insert("key", 1);
assert!(session.data_changed());

session.reset_data_changed();
assert!(!session.data_changed());
session.remove("key");
assert!(session.data_changed());

pub fn expires_in(&self) -> Option<Duration>[src]

Ensures that this session is not expired. Returns None if it is expired

Example

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

Duration from now to the expiry time of this session

takes the cookie value and consume this session. this is generally only performed by the session store

Example

let mut session = Session::new();
session.set_cookie_value("hello".to_owned());
let cookie_value = session.into_cookie_value().unwrap();
assert_eq!(cookie_value, "hello".to_owned());

Trait Implementations

impl Clone for Session[src]

impl Debug for Session[src]

impl Default for Session[src]

impl<'de> Deserialize<'de> for Session[src]

impl PartialEq<Session> for Session[src]

impl Serialize for Session[src]

Auto Trait Implementations

impl RefUnwindSafe for Session

impl Send for Session

impl Sync for Session

impl Unpin for Session

impl UnwindSafe for Session

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> DeserializeOwned for T where
    T: for<'de> Deserialize<'de>, 
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>,