The basics
Sessions
Every route from routes/web.rs runs inside the session middleware; /api routes do not. A handler takes the
session as an argument:
use smeltery::prelude::*;
async fn save(session: Session) -> Redirect {
session.insert("theme", "dark");
session.flash("status", "Settings saved.");
Redirect::to("/settings")
}
async fn show(session: Session) -> String {
session.get::<String>("theme").unwrap_or_default()
}
| Call | Does |
|---|---|
get::<T>(key) |
the value, if present and of type T |
insert(key, value), remove(key), has(key) |
store, drop, check (any Serialize value) |
flash(key, value) |
store for the next request only; reflash() keeps this request's flash values one more |
regenerate() |
a new session id, same data (done on login) |
invalidate() |
a new session id, no data (done on logout) |
token() |
the CSRF token |
errors(), old(field) |
validation errors and input flashed by the previous request |
smeltery::session::run_web_stack(app, req, next) (middleware) |
the session stack of web routes around any route: the same code, CSRF check included |
flash_errors(&app, &errors, &input) |
flash validation errors and the form's input for the next request, as a failed validation does (the input filtered the same way: no secret-looking or dont_flash field, at most 100 fields); answer with a redirect to any page after it |
With SESSION_DRIVER=cookie (the framework's default; new apps' .env sets database) the whole session is
stored in one cookie, encrypted and authenticated with
AES-256-GCM under a key derived from APP_KEY (HKDF-SHA256). A browser keeps about 4 KB per cookie; a larger
session logs a warning. With SESSION_DRIVER=database the cookie holds only the encrypted session id and the data
lives in the sessions table (id, payload, last_activity); expired rows are deleted on about one request in a
hundred. With SESSION_DRIVER=file the cookie holds the encrypted session id and the data lives in
storage/framework/sessions/<id>, one file per session, readable by its owner only; the file's modification time is
the session's last activity, each save writes a temp file and renames it over the old one, and expired files are
deleted on about one request in a hundred. Cookies are HttpOnly, SameSite=Lax and Path=/. When APP_URL
starts with https:// (in any letter case) they are Secure, and the session and remember-me cookies carry the
__Host- prefix (__Host-my_app_session), which browsers accept only from this host over HTTPS, so neither a
subdomain nor a plain-HTTP page can plant one. A missing, tampered or expired session cookie gives a new, empty
session.
A session lives SESSION_LIFETIME minutes after its last request, and at most SESSION_ABSOLUTE_LIFETIME minutes
(7 days) after it started or its user signed in, however active it is; a remember-me cookie then signs the user in
again. A visitor who came without a session and whose request stored nothing (no value, no flash message, no CSRF
token) gets none: no cookie, no row, no file. A page rendered from a view gets one, since its forms need the CSRF
token, and so does every response of an app that sends the XSRF-TOKEN cookie (Alloy).
APP_KEY must hold at least 32 bytes (base64:… as smeltery key:generate writes it, or plain text; in
production a plain-text key logs a warning at boot, since a typed phrase is far easier to guess than 32 random
bytes). Without a usable one (missing, malformed or too short), the server of an app with web routes refuses to start
and says to run smeltery key:generate. APP_ENV=testing with an empty APP_KEY signs with a fixed test key that
is public; serve and work refuse to run under APP_ENV=testing (see The server), so it serves
only TestApp and other in-process tests.