Struct Session

Source

pub struct Session { /* private fields */ }

Expand description

One visitor’s session.

Implementations§

Source §

impl Session

Source

pub const TOKEN_KEY: &'static str = "_token"

Where the CSRF token lives, and the name of the form field that carries it back. Laravel’s _token, so a template ported across looks familiar.

Source

pub fn new() -> Self

Start a session with a brand new id.

Source

pub fn with_id(id: impl Into<String>) -> Self

Rebuild a session around a known id.

Source

pub fn new_id() -> String

A fresh identifier: ID_BYTES of OS entropy, hex encoded.

Source

pub fn id(&self) -> &str

Source

pub fn updated_at(&self) -> u64

When this session was last written, in unix seconds.

Source

pub fn is_dirty(&self) -> bool

Whether anything changed since the session was loaded.

The middleware uses this to avoid writing a session file for every anonymous request that never touched the session.

Source

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

Source

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

A value as a string, which is what most session data actually is.

Source

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

Source

pub fn put(&mut self, key: impl Into<String>, value: impl Into<Json>)

Source

pub fn forget(&mut self, key: &str) -> Option<Json>

Remove a key, handing back whatever was there.

Source

pub fn flush(&mut self)

Remove everything, keeping the id.

On logout prefer Session::invalidate, which also rotates the id.

Source

pub fn all(&self) -> &BTreeMap<String, Json>

Source

pub fn flash(&mut self, key: impl Into<String>, value: impl Into<Json>)

Store a value that survives exactly one further request.

The redirect-with-a-message pattern: a POST handler flashes status, redirects, and the GET that follows renders it. By the request after that, it is gone — so a refresh does not show the message twice.

Source

pub fn keep(&mut self, key: &str)

Keep one flashed value for another request.

Source

pub fn reflash(&mut self)

Keep every flashed value for another request.

Source

pub fn age_flash(&mut self)

Advance the flash lifecycle by one request.

Called by the session middleware after the handler has run: what was flashed last request has now been read and is dropped, and what was flashed this request takes its place.

Source

pub fn regenerate(&mut self) -> &str

Give this session a new id, keeping its contents.

This is the defence against session fixation. An attacker who can plant a cookie — through a subdomain, an open redirect, or a shared machine — hands the victim a session id he already knows, waits for the victim to log in, and then presents the same id to arrive inside the authenticated session. Rotating the id at the moment privileges change makes the id he planted worthless: it is no longer the id the session answers to.

crate::Guard::login calls this for exactly that reason.

Source

pub fn invalidate(&mut self) -> &str

Throw the contents away and rotate the id — what logout wants.

Source

pub fn token(&mut self) -> String

The CSRF token for this session, generated on first use.

Living in the session is what makes it available to templates: a view renders session.get("_token") into a hidden field, and the csrf middleware compares what comes back against this same value.

Source

pub fn to_json(&self) -> Json

Serialize for a store. The id is the key, so it is not in the payload.

Source

pub fn from_json(id: impl Into<String>, payload: &Json) -> Self

Rebuild from a store’s payload.

A payload that is not an object at all yields an empty session rather than an error: a corrupt session file should log the visitor out, not take the site down.

Source

pub fn touch(&mut self)

Stamp the session as written now. Stores call this before persisting so an active visitor’s session keeps sliding forward instead of expiring a fixed time after login.