Struct Session

pub struct Session(/* private fields */);

The primary interface to access and modify session state.

Session is an extractor—you can specify it as an input type for your request handlers and it will be automatically extracted from the incoming request.

use actix_session::Session;

async fn index(session: Session) -> actix_web::Result<&'static str> {
    // access session data
    if let Some(count) = session.get::<i32>("counter")? {
        session.insert("counter", count + 1)?;
    } else {
        session.insert("counter", 1)?;
    }

    // or use the shorthand
    session.update_or("counter", 1, |count: i32| count + 1);

    Ok("Welcome!")
}

You can also retrieve a Session object from an HttpRequest or a ServiceRequest using SessionExt.

Implementations

impl Session

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

Get a value from the session.

It returns an error if it fails to deserialize as T the JSON value associated with key.

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

Returns true if the session contains a value for the specified key.

pub fn entries(&self) -> Ref<'_, HashMap<String, String>>

Get all raw key-value data from the session.

Note that values are JSON encoded.

pub fn status(&self) -> SessionStatus

Returns session status.

pub fn insert<T: Serialize>( &self, key: impl Into<String>, value: T, ) -> Result<(), SessionInsertError>

Inserts a key-value pair into the session.

Any serializable value can be used and will be encoded as JSON in session data, hence why only a reference to the value is taken.

Errors

Returns an error if JSON serialization of value fails.

pub fn update<T: Serialize + DeserializeOwned, F>( &self, key: impl Into<String>, updater: F, ) -> Result<(), SessionUpdateError>

where F: FnOnce(T) -> T,

Updates a key-value pair into the session.

If the key exists then update it to the new value and place it back in. If the key does not exist it will not be updated.

Any serializable value can be used and will be encoded as JSON in the session data, hence why only a reference to the value is taken.

Errors

Returns an error if JSON serialization of the value fails.

pub fn update_or<T: Serialize + DeserializeOwned, F>( &self, key: &str, default_value: T, updater: F, ) -> Result<(), SessionUpdateError>

where F: FnOnce(T) -> T,

Updates a key-value pair into the session, or inserts a default value.

If the key exists then update it to the new value and place it back in. If the key does not exist the default value will be inserted instead.

Any serializable value can be used and will be encoded as JSON in session data, hence why only a reference to the value is taken.

Errors

Returns error if JSON serialization of a value fails.

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

Remove value from the session.

If present, the JSON encoded value is returned.

pub fn remove_as<T: DeserializeOwned>( &self, key: &str, ) -> Option<Result<T, String>>

Remove value from the session and deserialize.

Returns None if key was not present in session. Returns T if deserialization succeeds, otherwise returns un-deserialized JSON string.

pub fn clear(&self)

Clear the session.

pub fn purge(&self)

Removes session both client and server side.

pub fn renew(&self)

Renews the session key, assigning existing session state to new key.

Trait Implementations

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

Extractor implementation for Sessions.

Examples

use actix_session::Session;

#[get("/")]
async fn index(session: Session) -> Result<impl Responder> {
    // access session data
    if let Some(count) = session.get::<i32>("counter")? {
        session.insert("counter", count + 1)?;
    } else {
        session.insert("counter", 1)?;
    }

    let count = session.get::<i32>("counter")?.unwrap();
    Ok(format!("Counter: {}", count))
}

type Error = Error

The associated error which can be returned.

type Future = Ready<Result<Session, Error>>

Future that resolves to a Self.

fn from_request(req: &HttpRequest, _: &mut Payload) -> Self::Future

Create a Self from request parts asynchronously.

fn extract(req: &HttpRequest) -> Self::Future

Create a Self from request head asynchronously.