32 releases

0.7.2 Sep 11, 2022
0.7.1 Jul 24, 2022
0.6.2 Mar 25, 2022
0.5.0-beta.7 Dec 29, 2021
0.1.0-alpha.2 Mar 30, 2019

#143 in HTTP server

Download history 3188/week @ 2022-08-19 3125/week @ 2022-08-26 3756/week @ 2022-09-02 4247/week @ 2022-09-09 3644/week @ 2022-09-16 3211/week @ 2022-09-23 4071/week @ 2022-09-30 3939/week @ 2022-10-07 3228/week @ 2022-10-14 3583/week @ 2022-10-21 3795/week @ 2022-10-28 4241/week @ 2022-11-04 4175/week @ 2022-11-11 3393/week @ 2022-11-18 3370/week @ 2022-11-25 2314/week @ 2022-12-02

13,909 downloads per month
Used in 28 crates (22 directly)

MIT/Apache

115KB
2K SLoC

actix-session

Session management for Actix Web.

crates.io Documentation Apache 2.0 or MIT licensed Dependency Status

Documentation & Resources


lib.rs:

Session management for Actix Web.

The HTTP protocol, at a first glance, is stateless: the client sends a request, the server parses its content, performs some processing and returns a response. The outcome is only influenced by the provided inputs (i.e. the request content) and whatever state the server queries while performing its processing.

Stateless systems are easier to reason about, but they are not quite as powerful as we need them to be - e.g. how do you authenticate a user? The user would be forced to authenticate for every single request. That is, for example, how 'Basic' Authentication works. While it may work for a machine user (i.e. an API client), it is impractical for a person—you do not want a login prompt on every single page you navigate to!

There is a solution - sessions. Using sessions the server can attach state to a set of requests coming from the same client. They are built on top of cookies - the server sets a cookie in the HTTP response (Set-Cookie header), the client (e.g. the browser) will store the cookie and play it back to the server when sending new requests (using the Cookie header).

We refer to the cookie used for sessions as a session cookie. Its content is called session key (or session ID), while the state attached to the session is referred to as session state.

actix-session provides an easy-to-use framework to manage sessions in applications built on top of Actix Web. [SessionMiddleware] is the middleware underpinning the functionality provided by actix-session; it takes care of all the session cookie handling and instructs the storage backend to create/delete/update the session state based on the operations performed against the active [Session].

actix-session provides some built-in storage backends: (CookieSessionStore, RedisSessionStore, and RedisActorSessionStore) - you can create a custom storage backend by implementing the SessionStore trait.

Further reading on sessions:

Getting started

To start using sessions in your Actix Web application you must register [SessionMiddleware] as a middleware on your App:

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

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // The secret key would usually be read from a configuration file/environment variables.
    let secret_key = Key::generate();
    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
}

The session state can be accessed and modified by your request handlers using the [Session] extractor.

use actix_web::Error;
use actix_session::Session;

fn index(session: Session) -> Result<&'static str, Error> {
    // access the session state
    if let Some(count) = session.get::<i32>("counter")? {
        println!("SESSION value: {}", count);
        // modify the session state
        session.insert("counter", count + 1)?;
    } else {
        session.insert("counter", 1)?;
    }

    Ok("Welcome!")
}

Choosing A Backend

By default, actix-session does not provide any storage backend to retrieve and save the state attached to your sessions. You can enable:

  • a purely cookie-based "backend", CookieSessionStore, using the cookie-session feature flag.

    [dependencies]
    # ...
    actix-session = { version = "...", features = ["cookie-session"] }
    
  • a Redis-based backend via actix-redis, RedisActorSessionStore, using the redis-actor-session feature flag.

    [dependencies]
    # ...
    actix-session = { version = "...", features = ["redis-actor-session"] }
    
  • a Redis-based backend via redis-rs, RedisSessionStore, using the redis-rs-session feature flag.

    [dependencies]
    # ...
    actix-session = { version = "...", features = ["redis-rs-session"] }
    

    Add the redis-rs-tls-session feature flag if you want to connect to Redis using a secured connection:

    [dependencies]
    # ...
    actix-session = { version = "...", features = ["redis-rs-session", "redis-rs-tls-session"] }
    

You can implement your own session storage backend using the SessionStore trait.

Dependencies

~15–23MB
~530K SLoC