actix-extras

Session Management Overview

actix-session provides a framework for attaching state to a set of requests from the same client using session cookies.

Core Components:

• Session Cookie: The cookie sent by the server via the Set-Cookie header and returned by the client via the Cookie header.
• Session Key (Session ID): The content of the session cookie used to identify the session.
• Session State: The actual data attached to the session.
• SessionMiddleware: The underlying middleware that handles cookie management and instructs the storage backend to create, delete, or update session state.
• Session: An extractor used in request handlers to access and modify the session state.
• Storage Backend: A component (implementing the SessionStore trait) responsible for persisting the session state. Common backends include CookieSessionStore and RedisSessionStore.

To use actix-identity for tracking user identity across requests, you must register both IdentityMiddleware and SessionMiddleware on your App.

Important Middleware Ordering: actix-web invokes middleware in the OPPOSITE order of registration for incoming requests. Therefore, you must register IdentityMiddleware BEFORE SessionMiddleware so that the session middleware is processed first when a request arrives.

1. Initialize a Key (preferably from a config/env var, not Key::generate() in production).
2. Set up a session store (e.g., RedisSessionStore).
3. Register IdentityMiddleware::default().
4. Register SessionMiddleware.

use actix_web::{cookie::Key, App, HttpServer, HttpResponse};
use actix_identity::IdentityMiddleware;
use actix_session::{storage::RedisSessionStore, SessionMiddleware};

#[actix_web::main]
async fn main() {
    // Initialize key outside HttpServer::new
    let secret_key = Key::generate();

    let redis_store = RedisSessionStore::new("redis://127.0.0.1:6379")
        .await
        .unwrap();

    HttpServer::new(move || {
        App::new()
            // 1. Install identity middleware first
            .wrap(IdentityMiddleware::default())
            // 2. Install session middleware AFTER identity middleware
            // so that session is processed first on incoming requests
            .wrap(SessionMiddleware::new(
                 redis_store.clone(),
                 secret_key.clone(),
            ))
    })
    .bind("127.0.0.1:8080")
    .unwrap()
    .run()
    .await;
}

To use sessions, you must register SessionMiddleware as middleware on your App. You need a SessionStore (like RedisSessionStore) and a Key for signing/encrypting cookies.

Important: When using Key::generate(), initialize it outside of the HttpServer::new closure to ensure the same key is used across all worker threads. In production, load this key from a configuration file or environment variable.

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

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // Initialize key outside the closure
    let secret_key = Key::generate();

    let redis_store = RedisSessionStore::new("redis://127.0.0.1:6379")
        .await
        .unwrap();

    HttpServer::new(move ||
            App::new()
            // Register SessionMiddleware
            .wrap(
                SessionMiddleware::new(
                    redis_store.clone(),
                    secret_key.clone(),
                )
            )
            .default_service(web::to(|| HttpResponse::Ok())))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

The actix-protobuf crate provides tools to work with Protocol Buffers (Protobuf) in Actix Web.

Extracting Protobuf payloads

To extract a Protobuf message from an incoming request, use the ProtoBuf<T> extractor in your handler function, where T is a type that implements the prost::Message trait.

Sending Protobuf responses

To send a Protobuf message as a response, use the .protobuf() method on an HttpResponse builder, passing the inner message (accessible via .0 on the ProtoBuf wrapper).

use actix_protobuf::ProtoBuf;
use actix_web::*;
use prost::Message;

#[derive(Clone, PartialEq, Message)]
pub struct MyObj {
    #[prost(int32, tag = "1")]
    pub number: i32,

    #[prost(string, tag = "2")]
    pub name: String,
}

async fn index(msg: ProtoBuf<MyObj>) -> Result<HttpResponse> {
    // msg.0 accesses the inner MyObj
    HttpResponse::Ok().protobuf(msg.0)
}