Struct SessionBag 

pub struct SessionBag { /* private fields */ }

A request’s session.

Cheap to clone — every clone is the same underlying bag, which is what lets the middleware hold one while the handler writes through another.

Reached from a handler with request.session(), which is Some exactly when the StartSession middleware ran.

Implementations

impl Session

pub fn new() -> Session

A fresh, empty session with a new id.

pub fn restore(id: impl Into<String>, data: SessionData) -> Session

A session loaded from a store.

pub fn id(&self) -> String

The session id, as it appears in the cookie.

pub fn is_dirty(&self) -> bool

Whether anything has changed and the session needs writing back.

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

where T: DeserializeOwned,

A value, deserialised.

pub fn string(&self, key: &str) -> Option<String>

A value as a string, if it is one.

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

The raw value.

pub fn has(&self, key: &str) -> bool

Whether the key is present and not null.

pub fn all(&self) -> Map<String, Value>

Every value.

pub fn len(&self) -> usize

How many values are held.

pub fn is_empty(&self) -> bool

Whether the session holds nothing.

pub fn put( &self, key: impl Into<String>, value: impl Serialize, ) -> Result<(), Error>

Store a value.

pub fn pull<T>(&self, key: &str) -> Option<T>

where T: DeserializeOwned,

Read a value and remove it in one step.

pub fn forget(&self, key: &str)

Remove a value.

pub fn flush(&self)

Remove every value, keeping the id.

pub fn flash( &self, key: impl Into<String>, value: impl Serialize, ) -> Result<(), Error>

Store a value for the next request only.

The redirect-then-show-a-message pattern: the value survives exactly one further request and is then deleted, without anything having to remember to clean it up.

pub fn keep(&self, keys: &[&str])

Keep the named flashed values for one further request.

What a redirect chain needs: without it, a value flashed before a redirect that itself redirects is gone before anything renders it.

pub fn reflash(&self)

Keep every flashed value for one further request.

pub fn token(&self) -> String

The CSRF token, minted on first use.

pub fn regenerate(&self)

Give the session a new id, keeping its contents.

Call this on login. Without it, an attacker who can set a victim’s session cookie before they authenticate ends up holding a cookie for their authenticated session — session fixation, and it is invisible in testing because everything works.

pub fn invalidate(&self)

Give the session a new id and throw its contents away. Logging out.

pub fn superseded_ids(&self) -> Vec<String>

Ids this session has left behind, for the store to delete.

pub fn age_and_take(&self) -> SessionData

Age the flash data and produce what should be written back.

Called once by the middleware, after the handler has run: values flashed by a previous request are dropped unless they were kept, and values flashed by this one become the next request’s.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Session

Deliberately opaque: a session holds whatever the application put in it, which in practice includes user ids and CSRF tokens.

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

Formats the value using the given formatter.

impl Default for Session

fn default() -> Session

Returns the “default value” for a type.