Struct actix_session::SessionMiddleware

pub struct SessionMiddleware<Store: SessionStore> { /* private fields */ }

A middleware for session management in Actix Web applications.

SessionMiddleware takes care of a few jobs:

• Instructs the session storage backend to create/update/delete/retrieve the state attached to a session according to its status and the operations that have been performed against it;
• Set/remove a cookie, on the client side, to enable a user to be consistently associated with the same session across multiple HTTP requests.

Use SessionMiddleware::new to initialize the session framework using the default parameters. To create a new instance of SessionMiddleware you need to provide:

• an instance of the session storage backend you wish to use (i.e. an implementation of SessionStore);
• a secret key, to sign or encrypt the content of client-side session cookie.

How did we choose defaults?

You should not regret adding actix-session to your dependencies and going to production using the default configuration. That is why, when in doubt, we opt to use the most secure option for each configuration parameter.

We expose knobs to change the default to suit your needs—i.e., if you know what you are doing, we will not stop you. But being a subject-matter expert should not be a requirement to deploy reasonably secure implementation of sessions.

Examples

use actix_web::{web, App, HttpServer, HttpResponse, Error};
use actix_session::{Session, SessionMiddleware, storage::RedisActorSessionStore};
use actix_web::cookie::Key;

// The secret key would usually be read from a configuration file/environment variables.
fn get_secret_key() -> Key {
    // [...]
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let secret_key = get_secret_key();
    let redis_connection_string = "127.0.0.1:6379";
    HttpServer::new(move ||
            App::new()
            // Add session management to your application using Redis for session state storage
            .wrap(
                SessionMiddleware::new(
                    RedisActorSessionStore::new(redis_connection_string),
                    secret_key.clone()
                )
            )
            .default_service(web::to(|| HttpResponse::Ok())))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

If you want to customise use builder instead of new:

use actix_web::{App, cookie::{Key, time}, Error, HttpResponse, HttpServer, web};
use actix_session::{Session, SessionMiddleware, storage::RedisActorSessionStore};
use actix_session::config::PersistentSession;

// The secret key would usually be read from a configuration file/environment variables.
fn get_secret_key() -> Key {
    // [...]
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let secret_key = get_secret_key();
    let redis_connection_string = "127.0.0.1:6379";
    HttpServer::new(move ||
            App::new()
            // Customise session length!
            .wrap(
                SessionMiddleware::builder(
                    RedisActorSessionStore::new(redis_connection_string),
                    secret_key.clone()
                )
                .session_lifecycle(
                    PersistentSession::default()
                        .session_ttl(time::Duration::days(5))
                )
                .build(),
            )
            .default_service(web::to(|| HttpResponse::Ok())))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

Implementations

impl<Store: SessionStore> SessionMiddleware<Store>

pub fn new(store: Store, key: Key) -> Self

Use SessionMiddleware::new to initialize the session framework using the default parameters.

To create a new instance of SessionMiddleware you need to provide:

• an instance of the session storage backend you wish to use (i.e. an implementation of SessionStore);
• a secret key, to sign or encrypt the content of client-side session cookie.

pub fn builder(store: Store, key: Key) -> SessionMiddlewareBuilder<Store>

A fluent API to configure SessionMiddleware.

It takes as input the two required inputs to create a new instance of SessionMiddleware:

• an instance of the session storage backend you wish to use (i.e. an implementation of SessionStore);
• a secret key, to sign or encrypt the content of client-side session cookie.

Trait Implementations

impl<Store: Clone + SessionStore> Clone for SessionMiddleware<Store>

fn clone(&self) -> SessionMiddleware<Store>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S, B, Store> Transform<S, ServiceRequest> for SessionMiddleware<Store>

where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error> + 'static, S::Future: 'static, B: MessageBody + 'static, Store: SessionStore + 'static,

type Response = ServiceResponse<B>

Responses produced by the service.

type Error = Error

Errors produced by the service.

type Transform = InnerSessionMiddleware<S, Store>

The TransformService value created by this factory

type InitError = ()

Errors produced while building a transform service.

type Future = Ready<Result<<SessionMiddleware<Store> as Transform<S, ServiceRequest>>::Transform, <SessionMiddleware<Store> as Transform<S, ServiceRequest>>::InitError>>

The future response value.

fn new_transform(&self, service: S) -> Self::Future

Creates and returns a new Transform component, asynchronously