Smeltery
Get started

The basics

v0.1

Sessions

Every route from routes/web.rs runs inside the session middleware; /api routes do not. A handler takes the session as an argument:

rust
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.

↑↓ moveEnter openEsc close