Crate tower_sessions

Expand description

Overview

This crate provides sessions, key-value pairs associated with a site visitor, as a tower middleware.

It offers:

Pluggable Storage Backends: Arbitrary storage backends are implemented with the SessionStore trait, fully decoupling sessions from their storage.
An axum Extractor for Session: Applications built with axum can use Session as an extractor directly in their handlers. This makes using sessions as easy as including Session in your handler.
Common Backends Out-of-the-Box: RedisStore and SQLx (SqliteStore, PostgresStore, MySqlStore) stores are available via their respective feature flags.
Simple Key-Value Interface: Sessions offer a key-value interface that supports native Rust types. So long as these types are Serialize and can be converted to JSON, it’s straightforward to insert, get, and remove any value.
Strongly-Typed Sessions: Strong typing guarantees are easy to layer on top of this foundational key-value interface.

Usage with an `axum` application

A common use-case for sessions is when building HTTP servers. Using axum, it’s straightforward to leverage sessions.

use std::net::SocketAddr;

use axum::{
    error_handling::HandleErrorLayer, response::IntoResponse, routing::get, BoxError, Router,
};
use http::StatusCode;
use serde::{Deserialize, Serialize};
use time::Duration;
use tower::ServiceBuilder;
use tower_sessions::{MemoryStore, Session, SessionManagerLayer};

const COUNTER_KEY: &str = "counter";

#[derive(Default, Deserialize, Serialize)]
struct Counter(usize);

#[tokio::main]
async fn main() {
    let session_store = MemoryStore::default();
    let session_service = ServiceBuilder::new()
        .layer(HandleErrorLayer::new(|_: BoxError| async {
            StatusCode::BAD_REQUEST
        }))
        .layer(
            SessionManagerLayer::new(session_store)
                .with_secure(false)
                .with_max_age(Duration::seconds(10)),
        );

    let app = Router::new()
        .route("/", get(handler))
        .layer(session_service);

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

async fn handler(session: Session) -> impl IntoResponse {
    let counter: Counter = session.get(COUNTER_KEY).unwrap().unwrap_or_default();

    session.insert(COUNTER_KEY, counter.0 + 1).unwrap();

    format!("Current count: {}", counter.0)
}

Sessions manifest to clients as cookies. These cookies have a configurable name and a value that is the session ID. In other words, cookies hold a pointer to the session in the form of an ID. This ID is a UUID v4.

Session IDs are considered secure if your platform’s getrandom is secure¹, and therefore are not signed or encrypted. Note that this assumption is predicated on the secure nature of the UUID crate and its ability to generate securely-random values. It’s also important to note that session cookies must never be sent over a public, insecure channel. Doing so is not secure.

An expiration time determines when the session will be considered expired. This translates to the cookie’s max-age attribute. By default, CookieConfig will set this to None. When None, this means the cookie will be treated as a “session” cookie, not to be confused with the session itself, which generally means that the cookie will expire once the user closes their browser.

Intermediary representation

Sessions manage a HashMap<String, serde_json::Value> but importantly are transparently persisted to an arbitrary storage backend. Effectively, HashMap is an intermediay, in-memory representation. By using a map-like structure, we’re able to present a familiar key-value interface for managing sessions. This also allows us to store and retrieve native Rust types, so long as our type is impl Serialize and can be represented as JSON.²

Internally, this hash map state is protected by a lock in the form of Mutex. This allows us to safely share mutable state across thread boundaries. Note that this lock is only acquired when we read from or write to this inner session state and not used when the session is provided to the request. This means that lock contention is minimized for most use cases.³

The intermediary HashMap representation is converted to a SessionRecord type which provides the structure needed to store sessions. Implementations of SessionStore consume this type in order to translate the session to its persisted form. Note that the exact details of how a session is stored within a backend is left up to the implementation but generally three things are needed:

The session ID.
The session expiration time.
The session data itself.

Together, these compose the session record and are enough to both encode and decode a session from any backend.

Session life cycle

Cookies hold a pointer to the session, rather than the session’s data and because of this the tower middleware is focused on managng the process of hydrating a session from the store. This works by first looking for a cookie that matches our configured session cookie name. If no such cookie is found or a cookie is found but the store has no such session or the session is no longer active, we create a new session. However, it’s important to note that creating a session does not save the session to the store. In fact, the store is not used at all unless one of two conditions is true:

A session cookie was found and we attempt to load it from the store via the load method or,
A session was marked as modified or deleted.

In other words, creating a new session is a lightweight process that does not incur the overhead of talking to a store. It’s also important to create a session proactively as the middleware will attach the session to the request as a request extension. This allows handlers to extract the cookie from the request and manipulate it.

Modified sessions will invoke the session store’s save method as well as send a Set-Cookie header. While deleted sessions will either be:

Deleted, invoking the delete method and setting a removal cookie or,
Cycled, invoking the delete method but setting a new ID on the session; the session will have been marked as modified and so this will also set a Set-Cookie header on the response.

Extractor pattern

When using axum, the Session will already function as an extractor. It’s possible to build further on this to create extractors of custom types.

const COUNTER_KEY: &str = "counter";

#[derive(Default, Deserialize, Serialize)]
struct Counter(usize);

#[async_trait]
impl<S> FromRequestParts<S> for Counter
where
    S: Send + Sync,
{
    type Rejection = (http::StatusCode, &'static str);

    async fn from_request_parts(req: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        let session = Session::from_request_parts(req, state).await?;
        let counter: Counter = session.get(COUNTER_KEY).unwrap().unwrap_or_default();
        session.insert(COUNTER_KEY, counter.0 + 1).unwrap();

        Ok(counter)
    }
}

Now in our handler, we can use Counter directly to read its fields.

A complete example can be found in examples/counter-extractor.rs.

Strongly-typed sessions

The extractor pattern can be extended further to provide strong typing guarantees over the key-value subtrate. Whereas our previous extractor example was effectively read-only. This pattern enables mutability of the underlying structure while also leveraging the full power of the type system.

#[derive(Clone, Deserialize, Serialize)]
struct GuestData {
    id: Uuid,
    pageviews: usize,
    first_seen: OffsetDateTime,
    last_seen: OffsetDateTime,
}

impl Default for GuestData {
    fn default() -> Self {
        Self {
            id: Uuid::new_v4(),
            pageviews: 0,
            first_seen: OffsetDateTime::now_utc(),
            last_seen: OffsetDateTime::now_utc(),
        }
    }
}

struct Guest {
    session: Session,
    guest_data: GuestData,
}

impl Guest {
    const GUEST_DATA_KEY: &'static str = "guest_data";

    fn id(&self) -> Uuid {
        self.guest_data.id
    }

    fn first_seen(&self) -> OffsetDateTime {
        self.guest_data.first_seen
    }

    fn last_seen(&self) -> OffsetDateTime {
        self.guest_data.last_seen
    }

    fn pageviews(&self) -> usize {
        self.guest_data.pageviews
    }

    fn mark_pageview(&mut self) {
        self.guest_data.pageviews += 1;
        Self::update_session(&self.session, &self.guest_data)
    }

    fn update_session(session: &Session, guest_data: &GuestData) {
        session
            .insert(Self::GUEST_DATA_KEY, guest_data.clone())
            .unwrap()
    }
}

#[async_trait]
impl<S> FromRequestParts<S> for Guest
where
    S: Send + Sync,
{
    type Rejection = (StatusCode, &'static str);

    async fn from_request_parts(req: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        let session = Session::from_request_parts(req, state).await?;

        let mut guest_data: GuestData = session
            .get(Self::GUEST_DATA_KEY)
            .unwrap()
            .unwrap_or_default();

        guest_data.last_seen = OffsetDateTime::now_utc();

        Self::update_session(&session, &guest_data);

        Ok(Self {
            session,
            guest_data,
        })
    }
}

Here we can use Guest as an extractor in our handler. We’ll be able to read values, like the ID as well as update the pageview count with our mark_pageview method.

A complete example can be found in examples/strongly-typed.rs

Name-spaced and strongly-typed buckets

Our example demonstrates a single extractor, but in a real application we might imagine a set of common extractors, all living in the same session. Each extractor forms a kind of bucketed name-space with a typed structure. Importantly, each is self-contained by its own name-space.

For instance, we might also have a site preferences bucket, an analytics bucket, a feature flag bucket and so on. All these together would live in the same session, but would be segmented by their own name-space, avoiding the mixing of domains unnecessarily.⁴

uuid uses getrandom which varies by platform; the crucial assumption tower-sessions makes is that your platform is secure. However, you must verify this for yourself. ↩
Using JSON allows us to translate arbitrary types to virtually any backend and gives us a nice interface with which to interact with the session. ↩
We might consider replacing Mutex with RwLock if this proves to be a better fit in practice. Another alternative might be dashmap or a different approach entirely. Future iterations should be based on real-world use cases. ↩
This is paricularly useful when we may have data domains that only belong with users in certain states: we can pull these into our handlers where we need a particular domain. In this way, we minimize data pollution via self-contained domains in the form of buckets. ↩

Re-exports

pub use fred;
pub use sqlx;
pub use tower_cookies::cookie;

Modules

cookie_config
Defines the configuration for the cookie belonging to the session.
service
A middleware that provides Session as a request extension.
session
A session which allows HTTP applications to associate data with visitors.
session_store
An arbitrary store which houses the session data.

Structs

CookieConfig
Defines the configuration for the cookie belonging to the session.
MemoryStorememory-store
A session store that lives only in memory.
MySqlStoremysql-store and sqlx-store
A MySQL session store.
PostgresStorepostgres-store and sqlx-store
A PostgreSQL session store.
RedisStoreredis-store
A Redis session store.
Session
A session which allows HTTP applications to associate key-value pairs with visitors.
SessionManager
A middleware that provides Session as a request extension.
SessionManagerLayer
A layer for providing Session as a request extension.
SessionRecord
A type that represents data to be persisted in a store for a session.
SqliteStoresqlite-store and sqlx-store
A SQLite session store.

Enums

SqlxStoreErrorsqlx-store
An error type for SQLx stores.

Traits

SessionStore
An arbitrary store which houses the session data.