Rustango docs
← Authentication

Sessions

A session keeps a user logged in across requests by handing the browser an opaque ID in a cookie and keeping everything else server-side. Rustango's SessionStore puts that state in a cache (Redis in production, in-memory for tests), so the cookie carries no secrets and a session can be revoked instantly — delete the entry and every replica sees the logout on the next request.

Sessions in Rustango: the cookie holds only an opaque id, the SessionStore keeps the data in Redis, and destroy() revokes it everywhere

Source: rustango::sessions (Session, SessionStore, SessionLayer, CurrentSession) + rustango::cache (BoxedCache, InMemoryCache) — behind the sessions feature (on by default; pulls cache). For a Redis-backed store in production, add the cache-redis feature (off by default) to get RedisCache.

Runnable version: snippets below are copied from the tested auth_demo example — cargo test -p auth_demo --test auth_sessions.

New to a term here? session, opaque id, cookie, cache — see the glossary.

Deep dive companion to the Security guide. The Auth decorators do not read these sessions: they read the tenancy login cookie. To gate routes on a SessionStore session, write a small middleware that loads the session and calls redirect_to_login — see Single-database apps. For stateless API tokens instead, see JWT.


Table of contents


Quick start

use rustango::sessions::{Session, SessionStore};
use rustango::cache::{BoxedCache, RedisCache};
use std::sync::Arc;

let store = SessionStore::new(Arc::new(RedisCache::new("redis://localhost/0").await?) as BoxedCache);

// After the password check (see auth-passwords.md): stash who the user is,
// save → an opaque id, and set that id as the cookie.
let mut session = Session::new();
session.set("user_id", user.id);
let sid = store.save(&session).await?;
// Set-Cookie: rustango_session={sid}; HttpOnly; SameSite=Lax; Secure; Path=/

// On later requests: read the id from the cookie, load the session back.
let session = store.load(&sid).await?.unwrap_or_default();
let user_id: Option<i64> = session.get("user_id");

// Logout: drop the server-side entry — the cookie is now meaningless.
store.destroy(&sid).await?;

The id is 192 bits of OS-CSPRNG randomness, base64url-encoded to 32 chars — well above the 128-bit floor for session tokens, and unguessable.

Under tenancy, scope the store per request with store.for_tenant(&TenantSlug::of(&t.org)?): the id carries no tenant, and with apex + path-prefix routing one Path=/ cookie reaches every tenant.


The session layer

SessionLayer does the cookie work for you: it loads the session named by the cookie, hands it to handlers as CurrentSession, and saves it after the handler returns. The cookie is always HttpOnly, and Secure + SameSite=Lax by default; it lives as long as the store's TTL.

use rustango::sessions::{CurrentSession, SessionLayer, SessionStore};

let app = Router::new()
    .route("/login", post(login))
    .route("/me", get(me))
    .layer(SessionLayer::new(SessionStore::new(cache)));

async fn login(session: CurrentSession /* , form … */) -> Result<&'static str, ApiError> {
    // After the password check: a new id, bound to the user.
    session.login(&user.id.to_string()).await.map_err(ApiError::internal)?;
    session.set("theme", "dark");
    Ok("ok")
}

async fn me(session: CurrentSession) -> String {
    session.user().unwrap_or_default()
}
  • login(user) moves the session to a new id, so an id planted before login is worthless. cycle_id() does the same after a rights change.
  • logout() deletes the session and expires the cookie.
  • Options: cookie_name, cookie_path, cookie_domain, same_site, allow_insecure_for_dev() (plain-HTTP dev only) and rolling() (renew the TTL and cookie on every request).
  • Under tenancy the layer scopes the store to the request's tenant. A request with no tenant context gets a 503; allow_global() serves it from the platform-wide space instead.
  • A request never writes back a session that ended while it ran (revoked, or logged out elsewhere): the cookie is removed instead.
  • For a CSRF token kept in the session, use SessionLayer::with_csrf — see CSRF.

Listing and revoking a user's sessions

Sessions made by login are bound to the user, so you can show "where you are logged in" and end them:

let store = session.store(); // the request's store, scoped to its tenant
for s in store.sessions_of(&user_id).await? {
    println!("{} since {}", s.key, s.created_at);
}
store.revoke(&user_id, &key).await?;                 // one device
store.revoke_all(&user_id, session.id().as_deref()).await?; // all but this one

key names a session in listings; it is not the session id, so a listing never leaks a usable cookie. revoke_all also ends sessions the listing missed (two logins of one user at the same moment can drop an entry), because it bumps the user's revocation generation and older sessions stop loading. The kept session stays valid through the request's own save, cycle_id() included.

A user keeps at most MAX_SESSIONS_PER_USER (100) sessions; a login past it ends the oldest.


Sessions vs JWT

Both answer "who is this request?", with opposite trade-offs:

SessionJWT
Stateserver-side (cache lookup per request)stateless (self-contained token)
Revocationinstant — destroy() the entryhard — valid until expiry (needs a blocklist)
Best forbrowser apps, "log this user out NOW"APIs, service-to-service, no shared store

Reach for sessions when you need to forcibly log someone out (password change, "sign out all devices", a banned account). Reach for JWT when you want zero per-request lookups and have no shared cache.


The session bag

Session is a typed key→value bag with a dirty bit (so the store can skip a write when nothing changed):

let mut s = Session::new();
s.set("user_id", 42_i64);            // serialize any Serialize value
s.set("role", "editor");
let uid: Option<i64> = s.get("user_id");   // None if absent or wrong type
s.remove("role");
s.clear();                            // wipe everything (e.g. on logout)

get is fail-soft: a missing key or a value that doesn't deserialize as the requested type returns None rather than panicking — so a schema change never 500s a request.


The cookie

The cookie holds only sid. Set it with the security attributes a session cookie needs:

  • HttpOnly — JavaScript can't read it (blunts XSS token theft).
  • SameSite=Lax — not sent on cross-site sub-requests (CSRF defense; pair with CSRF tokens for form posts).
  • Secure — HTTPS only (drop only for local HTTP dev).
  • Path=/ — visible to the whole app.

Nothing sensitive is in the cookie, so a leaked cookie is exactly as powerful as the session it points at — and you can revoke that server-side at any time.


Picking a backend

SessionStore::new takes any BoxedCache:

  • RedisCache — production. Shared across replicas, so a login on one instance and a logout on another are both visible everywhere.
  • InMemoryCache — single process / tests. Fast, zero deps, but sessions don't survive a restart and aren't shared between replicas.
use rustango::cache::{BoxedCache, InMemoryCache};
use std::sync::Arc;

// Tests / single-process:
let store = SessionStore::new(Arc::new(InMemoryCache::new()) as BoxedCache);

Expiry and sliding renewal

Sessions default to a 2-week TTL. Override per store, and touch on each authenticated request for sliding expiration (active users stay logged in, idle ones age out):

use std::time::Duration;

let store = SessionStore::new(cache).ttl(Duration::from_secs(60 * 60)); // 1 hour

// On each request, after a successful load — extend without rewriting:
store.touch(&sid).await?;   // Ok(false) if the session is already gone

Updating a session in place

save always mints a fresh id (use it at login). To modify an existing session during a request, load → mutate → save_with_id under the same id:

let mut s = store.load(&sid).await?.unwrap_or_default();
s.set("last_seen", chrono::Utc::now().to_rfc3339());
store.save_with_id(&sid, &s).await?;

Notes and limits

  • Revocation is the headline feature — destroy() (logout) and TTL expiry both take effect on the next request, on every replica sharing the cache.
  • Corrupt or unknown ids load as None (fail-open): a cache schema change or a tampered cookie yields an empty session, not an error — the request is simply unauthenticated.
  • The store alone doesn't set the cookie — SessionLayer does; without it you attach and read the sid cookie in your handler.
  • Mint a fresh session id on privilege change (e.g. right after login) to avoid session fixation — save already does this since it always generates a new id.

See also