Crate tower_sessions
source ·Expand description
Overview
This crate provides sessions, key-value pairs associated with a site
visitor, as a tower
middleware.
It offers:
- Pluggable Storage Backends: Bring your own backend simply by
implementing the
SessionStore
trait, fully decoupling sessions from their storage. - Minimal Overhead: Sessions are only loaded from their backing stores when they’re actually used and only in e.g. the handler they’re used in. That means this middleware can be installed at any point in your route graph with minimal overhead.
- An
axum
Extractor forSession
: Applications built withaxum
can useSession
as an extractor directly in their handlers. This makes using sessions as easy as includingSession
in your handler. - Common Backends Out-of-the-Box:
RedisStore
, SQLx (SqliteStore
,PostgresStore
,MySqlStore
), andMongoDBStore
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.
This crate’s session implementation is inspired by the Django sessions middleware and it provides a transliteration of those semantics.
User session management
To facilitate authentication and authorization, we’ve built axum-login
on top of this crate. Please check it out if you’re looking for a generalized auth solution.
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::{response::IntoResponse, routing::get, Router};
use serde::{Deserialize, Serialize};
use time::Duration;
use tower_sessions::{Expiry, 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_layer = SessionManagerLayer::new(session_store)
.with_secure(false)
.with_expiry(Expiry::OnInactivity(Duration::seconds(10)));
let app = Router::new().route("/", get(handler)).layer(session_layer);
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
axum::serve(listener, app.into_make_service())
.await
.unwrap();
}
async fn handler(session: Session) -> impl IntoResponse {
let counter: Counter = session.get(COUNTER_KEY).await.unwrap().unwrap_or_default();
session.insert(COUNTER_KEY, counter.0 + 1).await.unwrap();
format!("Current count: {}", counter.0)
}
Session expiry management
In cases where you are utilizing stores that lack automatic session expiry
functionality, such as SQLx or MongoDB stores, it becomes essential to
periodically clean up stale sessions. For instance, both SQLx and MongoDB
stores offer
continuously_delete_expired
which is designed to be executed as a recurring task. This process ensures
the removal of expired sessions, maintaining your application’s data
integrity and performance.
let pool = SqlitePool::connect("sqlite::memory:").await.unwrap();
let session_store = SqliteStore::new(pool);
let deletion_task = tokio::task::spawn(
session_store
.clone()
.continuously_delete_expired(tokio::time::Duration::from_secs(60)),
);
deletion_task.await.unwrap().unwrap();
Note that by default or when using browser session expiration, sessions are considered expired after two weeks.
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).await.unwrap().unwrap_or_default();
session.insert(COUNTER_KEY, counter.0 + 1).await.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 substrate. 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
}
async fn mark_pageview(&mut self) {
self.guest_data.pageviews += 1;
Self::update_session(&self.session, &self.guest_data).await
}
async fn update_session(session: &Session, guest_data: &GuestData) {
session
.insert(Self::GUEST_DATA_KEY, guest_data.clone())
.await
.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)
.await
.unwrap()
.unwrap_or_default();
guest_data.last_seen = OffsetDateTime::now_utc();
Self::update_session(&session, &guest_data).await;
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.1
Layered caching
In some cases, the canonical store for a session may benefit from a cache.
For example, rather than loading a session from a store on every request,
this roundtrip can be mitigated by placing a cache in front of the storage
backend. A specialized session store, CachingSessionStore
, is provided
for exactly this purpose.
This store manages a cache and a store. Where the cache acts as a frontend and the store a backend. When a session is loaded, the store first attempts to load the session from the cache, if that fails only then does it try to load from the store. By doing so, read-heavy workloads will incur far fewer roundtrips to the store itself.
To illustrate, this is how we might use the MokaStore
as a frontend
cache to a PostgresStore
backend.
let database_url = std::option_env!("DATABASE_URL").unwrap();
let pool = PgPool::connect(database_url).await.unwrap();
let postgres_store = PostgresStore::new(pool);
postgres_store.migrate().await.unwrap();
let moka_store = MokaStore::new(Some(10_000));
let caching_store = CachingSessionStore::new(moka_store, postgres_store);
let session_service = ServiceBuilder::new()
.layer(SessionManagerLayer::new(caching_store).with_max_age(Duration::days(1)));
While this example uses Moka, any implementor of SessionStore
may be
used. For instance, we could use the RedisStore
instead of Moka.
A cache is most helpful with read-heavy workloads, where the cache hit rate will be high. This is because write-heavy workloads will require a roundtrip to the store and therefore benefit less from caching.
Data races under concurrent conditions
Please note that it is not safe to access and mutate session state concurrently: this will result in data loss if your mutations are dependent on the state of the session.
This is because a session is loaded first from its backing store. Once loaded it’s possible for a second request to load the same session, but without the inflight changes the first request may have made.
Implementation
Sessions are composed of three pieces:
- A cookie that holds the session ID as its value,
- An in-memory hash-map, which underpins the key-value API,
- A pluggable persistence layer, the session store, where session data is housed.
Together, these pieces form the basis of this crate and allow tower
and
axum
applications to use a familiar session interface.
Cookie
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.
Secure nature of cookies
Session IDs are considered secure if your platform’s
getrandom
is
secure2, 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.
Key-value API
Sessions manage a HashMap<String, serde_json::Value>
but importantly are
transparently persisted to an arbitrary storage backend. Effectively,
HashMap
is an intermediary, in-memory representation. By using a map-like
structure, we’re able to present a familiar key-value interface for managing
sessions. This allows us to store and retrieve native Rust types, so long as
our type is impl Serialize
and can be represented as JSON.3
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.4
Session store
Sessions are serialized to arbitrary storage backends via a session record
intermediary. Implementations of SessionStore
take a record and persist
it such that it can later be loaded via the session ID.
Three components are needed for storing a session:
- The session ID.
- The session expiry.
- 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 managing the process
of hydrating a session from the store and managing its life cycle.
We load a session by 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.
It’s important to note that creating a session does not save the session to the store. In fact, the session store is not used at all unless the session is read from or written to. In other words, the middleware only introduces session store overhead when the session is actually used.
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 aSet-Cookie
header on the response.
Empty sessions are considered to be deleted and are removed from the session store as well as the user agent.
Sessions also carry with them a configurable expiry and will be deleted in accordance with this.
This is particularly 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. ↩
uuid
usesgetrandom
which varies by platform; the crucial assumptiontower-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
withRwLock
if this proves to be a better fit in practice. Another alternative might bedashmap
or a different approach entirely. Future iterations should be based on real-world use cases. ↩
Re-exports
pub use tower_sessions_core::cookie;
pub use tower_sessions_mongodb_store::mongodb;
pub use tower_sessions_redis_store::fred;
pub use tower_sessions_sqlx_store::sqlx;
Modules
- A middleware that provides
Session
as a request extension. - A session which allows HTTP applications to associate data with visitors.
- An arbitrary store which houses the session data.
Structs
- A session store for layered caching.
- MemoryStore
memory-store
A session store that lives only in memory. - MokaStore
moka-store
A session store that uses Moka, a fast and concurrent caching library. - MongoDBStore
mongodb-store
A MongoDB session store. - MySqlStore
mysql-store
A MySQL session store. - PostgresStore
postgres-store
A PostgreSQL session store. - RedisStore
redis-store
A Redis session store. - A session which allows HTTP applications to associate key-value pairs with visitors.
- A middleware that provides
Session
as a request extension. - A layer for providing
Session
as a request extension. - SqliteStore
sqlite-store
A SQLite session store.
Enums
- Session expiry configuration.
Traits
- A trait providing a deletion method for expired methods and optionally a method that runs indefinitely, deleting expired sessions.
- An arbitrary store which houses the session data.