Expand description
smeltery.org · Docs · crates.io · GitHub
§Smeltery
Batteries-included full-stack Rust: routing, typed configuration from .env, an application container, middleware,
error pages, the Mold template engine, Sparks live components (zero hand-written JavaScript), Anvil for WebSockets and
broadcasting (the Pusher Channels protocol), models and migrations for SQLite, PostgreSQL and MySQL, seeders and
factories, sessions, CSRF, validation and authentication, a cache with atomic locks (database, Redis, memcached, file
and memory stores), Watchfire for supervised long-running agents, queued jobs and the scheduler, mail, console
commands, a test client, Bellows for coding agents, and the smeltery command-line tool with an app generator and
make:* generators.
Fully async on Tokio, Axum and SeaORM.
cargo install smeltery
smeltery new my-app
cd my-app && smeltery serveMinimum supported Rust version: 1.94.
§Install
cargo install smelteryThis installs the smeltery command. Apps depend on the library (the generator writes this line for you):
[dependencies]
smeltery = { version = "0.1.0", default-features = false, features = ["sqlite"] }§Create an app
smeltery new my-appsmeltery new asks a few questions. Every question is also a flag; with any flag given, or when the terminal is not
interactive, no question is asked and the defaults apply. At the end it prints the equivalent one-line command.
| Question | Flag | Choices (default first) |
|---|---|---|
| What are you building? | --kind | web (a web app), headless (Watchfire agents, jobs and the scheduler, no web pages) |
| Database | --db | sqlite, postgres, mysql |
Starter kit (not asked for headless) | --frontend | mold (Mold + Sparks), react (React, Inertia, TypeScript), vue (Vue, Inertia, TypeScript) |
Install Tailwind? / Tailwind CSS? (not asked for headless) | --tailwind / --no-tailwind | yes |
| Alpine.js? (asked for the Mold frontend) | --alpine / --no-alpine | no |
Which building blocks should we smelt into your stack? (not asked for headless; --kind headless with a block in --smelt is refused, --smelt none is accepted) | --smelt | watchfire,temper; any of watchfire, temper, hallmark, anvil, prospect (comma-separated), or none |
| Bellows (AI-agent files) | --bellows | none, or any of mcp, skills, guidelines (comma-separated), or all |
Install the npm packages now? (asked for react and vue when Node.js 20.19+ or 22.12+ is found) | --npm / --no-npm | yes |
Run the migrations now? (smeltery migrate in the new app) | --migrate / --no-migrate | yes |
Seed the basic data? (smeltery db:seed, after the migrations) | --seed / --no-seed | yes |
| Initialise git? | --git / --no-git | yes |
The building blocks of a web app:
watchfire: Watchfire agents, jobs and the scheduler in the app (app/agents/, the Watchfire tables, the/_watchfiredashboard). A headless app always has Watchfire.temper: authentication through Temper, described below.hallmark: API tokens for mobile apps, desktop apps and other clients (API tokens). It needs user accounts, so it bringstemperwith it: the checklist and--smelt hallmarkadd Temper and say so (Hallmark needs Temper: added).anvil: WebSockets and broadcasting (Broadcasting).prospect: full-text search for models (Search).
Under the checklist (and with --smelt), a chosen block that works well with one that is not chosen gets a hint,
and nothing is added for it: Anvil works with Temper (private channels for signed-in users), with Hallmark
(private channels for mobile apps and other clients) and with Watchfire (broadcasting from agents and jobs).
.env gets a fresh APP_KEY and SESSION_DRIVER=database (the sessions table is one of every new app’s
migrations); .env.example lists the same keys without secrets. Every new app’s users table has the nullable
credentials_epoch column and its User model returns it from Authenticatable::credentials_epoch, so
auth::end_credentials signs a user out everywhere.
With authentication (the temper building block, on by default), a web app has registration, log-in, log-out,
password reset by mail and a dashboard behind the auth and verified middleware, and its seeder creates a demo
user under APP_ENV local or testing. Email verification is scaffolded and off: the email_verified_at column,
MustVerifyEmail on User, the notice page, the signed link’s route and “send it again”; uncommenting
.verify_email::<app::models::User>() in bootstrap/app.rs turns it on.
The authentication is Temper in every starter kit: bootstrap/app.rs calls
.temper(app::providers::temper::temper()). app/providers/temper.rs turns on registration, password reset, e-mail
verification, profile and password updates and two-factor authentication and names the page of each GET route
(Mold views in resources/views/auth/, React or Vue pages in resources/js/pages/auth/ through alloy::render,
with the password confirmation and two-factor challenge pages); in a React or Vue app it also clears the browser’s
history state on logout. app/actions/temper/ holds the forms and what they do, with the password rules in one place
(password_rules.rs). The app adds the settings pages /settings/profile, /settings/password and
/settings/two-factor (app/controllers/settings.rs; the two-factor page sits behind password.confirm and shows
the QR code as an <img>, the key, the confirmation form and the recovery codes once; all three answer
Cache-Control: no-store; the React and Vue page fetches the QR code and the key from Temper’s JSON routes, so they
never become props, and drops the recovery codes from its props as soon as it shows them, so the back button does not
show them again), the add_two_factor_columns_to_users_table migration, the four two_factor_* fields and TwoFactorAuthenticatable on
User, AUTH_PASSWORD_TIMEOUT=10800 in .env, and tests for the profile, the password change, two-factor log-in,
recovery codes, the password confirmation and signing a user out everywhere. A React or Vue app’s shared auth.user
has two_factor_enabled.
The forms that create an account or ask for and use a password reset (POST /register, /forgot-password,
/reset-password/{token}) carry .middleware("throttle:6,1"): at most 6 requests a minute per client on each of
those routes, counted in the cache; past that the form shows “Too many attempts. Please try again in N seconds.”
(429 for JSON clients); the login form (POST /login) carries .middleware("throttle:30,1"). The auth forms read the e-mail
address trimmed and in lower case (smeltery::auth::deserialize_email), so Ada@Example.com and
ada@example.com are one account. Registering an address that has an account answers “The email has already been taken.”, which tells the visitor that the address is registered; the
throttle limits how fast addresses can be tried.
Without auth the app has none of these pages, no password_reset_tokens migration and no demo user; the
users table and the User model stay, and .temper(…) turns authentication on in such an app (its CLAUDE.md lists the steps).
With hallmark, bootstrap/app.rs calls .hallmark(Hallmark::new()), and the app has the
create_personal_access_tokens_table migration, routes/api.rs with POST /api/tokens (throttle:10,1: a token
for email, password, device_name and, for an account with two-factor authentication on, code, through
issue_for_credentials), DELETE /api/tokens/current and GET /api/user (both auth:hallmark), their
controllers in app/controllers/api/, the HALLMARK_* settings as comments in .env, and tests/api_tokens.rs,
whose tests create their own users with UserFactory. With Watchfire too, app/agents/mod.rs schedules
hallmark-prune daily (tokens expired a day or more). smeltery hallmark:install adds the same files to an app
made without the block.
With anvil, bootstrap/app.rs calls .anvil(routes::channels::channels), and the app has routes/channels.rs
(the public channel announcements; with auth also users.{user}, which only that user may join),
app/events/announcement_posted.rs (an event on announcements), the pubsub_messages migration (also without
Watchfire), the ANVIL_* settings as comments in .env (the key and the secret are derived from APP_KEY until
set; the CORS settings too) and tests/broadcasting.rs. With auth it also has app/events/user_notified.rs (an
event on private-users.<id>). A Mold app listens without JavaScript: the Spark announcements
(app/sparks/announcements.rs, on the home page) shows the newest announcements, and with auth the Spark
notifications on the dashboard listens to the user’s private channel and its “Notify me” button sends one. A React
or Vue app gets Echo: package.json pins laravel-echo 2.5.0, @laravel/echo-react or @laravel/echo-vue 2.5.0 and
pusher-js 8.6.0; resources/js/echo.ts connects to the page’s own host and port with the key the pages get as the
shared prop app.anvil_key, authorizes private and presence channels at /broadcasting/auth with the session
cookie and the XSRF-TOKEN cookie as X-XSRF-TOKEN, and adds X-Socket-ID to Inertia’s requests; the entry
calls it before the first page. The welcome page shows the announcements card; with auth the dashboard’s “Live”
card listens to the user’s private channel, sends itself an event through POST /notify-me (auth,
throttle:10,1) and shows how many people are online through the presence channel presence-dashboard, with the
viewer’s own name (“3 people online · you: Ada”). The channel shares each member’s id only, so no other user’s name
reaches the browser; routes/channels.rs shows the one line that shares names. The create_presence_tables
migration holds the members under PUBSUB_DRIVER=database.
With prospect, bootstrap/app.rs calls .prospect(app::providers::search::register), app/providers/search.rs
registers the searchable models above // smeltery:searchables, and .env has PROSPECT_DRIVER=database; no
migration is written until a model is made searchable. smeltery make:model Post title:string body:text --searchable --all then writes impl Searchable (every string / text field searched, the first with Weight::A, foreign
fields as filters), the SearchIndex in the create-table migration (without -m, a separate
add_search_index_to_posts_table migration), the registration, and a list page that searches: GET /posts?q=…&page=…
behind throttle:60,1, ranked and paginated, the label highlighted (Mold: a search form and Previous / Next buttons,
no JavaScript; React and Vue: a search box that reloads the page 300 ms after the last key). --searchable is
refused in an app without the block and for a model without a string or text field. smeltery prospect:install
adds the provider to a web app made without the block.
With Alpine.js, the app gets Alpine.js 3.17.4 (the official dist/cdn.min.js of the npm package, with its MIT
licence header) as public/assets/js/alpine.min.js, embedded in the CLI, so nothing is downloaded. The layout loads
it with defer after @sparksScripts, the welcome page shows an Alpine toggle, and the counter Spark reads its count
through $spark.
With --frontend react or --frontend vue the pages are React or Vue components in TypeScript under
resources/js/pages/, rendered in the browser by Inertia’s client packages; the controllers return them through
smeltery::alloy (alloy::render("welcome")), and resources/views/app.mold.html is the HTML of a first visit.
The app has the same routes, authentication and settings pages and tests as a Mold app, a welcome page whose “Ask the forge”
button loads an optional prop with a partial reload, and a dashboard with a deferred prop. package.json pins exact
npm versions (Vite 8.3.2, Inertia 3.8.0, React 19.3.0 or Vue 3.5.43, TypeScript 6.0.3); npm install runs in the new
app unless --no-npm is given or no usable Node.js is found, for at most 5 minutes (SMELTERY_NPM_TIMEOUT sets
the seconds), and a failed or stopped install leaves the app complete, with npm install in the next steps. The
first install writes package-lock.json, which pins every package the kit pulls in, its dependencies’ dependencies
included, with integrity hashes; with it in the repository, smeltery build (and npm ci on a CI runner or a
server) installs exactly those versions. With Tailwind the kit uses the tailwindcss npm packages through
@tailwindcss/vite (no binary download); without it, resources/css/app.css is a prebuilt stylesheet of the kit’s
pages. Node.js builds the assets only: smeltery serve starts the Vite dev server
(node node_modules/vite/bin/vite.js, on 127.0.0.1:5173) next to the app, and smeltery build runs npm run build
into public/build/ before the release build. .env gets VITE_APP_NAME; every VITE_ value is compiled into
the JavaScript and is public. Alloy: React and Vue describes the pages, the generators and
the tests of these apps.
§Pages and CSS
A new web app opens on a welcome page and has styled log-in, register, password-reset and dashboard pages, in light
and dark (following the system setting), with no JavaScript besides Sparks (and Alpine.js when chosen). They use a compiled
public/assets/css/app.css that ships with the app, so they look the same without any tool installed. It is built
from resources/css/app.css (the theme colours and the component classes btn-primary, btn-secondary,
form-input, form-label, form-error, panel, link, alert-success, alert-error) and from the classes in the
view templates, including the views the make:* generators write. In an app, Tailwind reads the classes in
resources/views/ and app/ (the @source lines of resources/css/app.css); other folders are not scanned.
To change the CSS, Smeltery runs the Tailwind CSS standalone binary. smeltery new downloads it (Tailwind v4.3.3,
about 110 MB, over HTTPS from GitHub, checked against its SHA-256) into a per-user folder:
%LOCALAPPDATA%\smeltery\bin on Windows, ~/Library/Application Support/smeltery/bin on macOS, and
$XDG_DATA_HOME/smeltery/bin or ~/.local/share/smeltery/bin elsewhere; smeltery tailwind:install does the same for an existing app. The binaries
exist for Linux (x64 and arm64, glibc and musl), macOS (x64 and arm64) and Windows (x64). smeltery serve and
smeltery build use TAILWIND_BIN when it is set, then that binary, then tailwindcss in a folder on PATH given
as an absolute path (empty, . and other relative entries are skipped). Before they run the per-user binary they
check it again: its SHA-256 (a .verified stamp file next to it skips the hashing while the binary’s size and
modification time stay the same) and, on Linux and macOS, that the binary, its folder and smeltery/ belong to the
user and are not writable by the group or others, and that the data folder above them is not writable by others. A binary that fails is not run (a warning names the reason), and smeltery tailwind:install
replaces it. When the download fails, the app is created anyway with its prebuilt CSS, and the summary shows
smeltery tailwind:install to retry.
§The app layout
my-app/
├── app/
│ ├── controllers/ models/ middleware/ providers/ services/
│ ├── commands/ jobs/ agents/ mail/ sparks/ helpers/
├── bootstrap/
│ ├── app.rs wires the app: config, routes, middleware (the library root)
│ └── main.rs the binary: hands the command line to smeltery::run
├── config/ typed config structs read from .env
├── routes/ web.rs (browser routes), api.rs (under /api)
├── database/ migrations/ seeders/ factories/ database.sqlite (SQLite apps)
├── resources/ views/ (pages, layouts/, components/, sparks/) css/
├── public/ served as-is (assets/images, assets/css, assets/js)
├── storage/ app/public app/private (the app's files) framework (Smeltery's) logs
├── tests/
├── .env .env.example
├── CLAUDE.md AGENTS.md
└── Cargo.tomlThe app is one crate: bootstrap/app.rs is the library root and pulls each folder in as a module, so
crate::app::controllers::home is app/controllers/home.rs. Every folder has a mod.rs.
storage/app/ holds only the app’s own files (public/ is served at /storage after smeltery storage:link,
private/ never is). storage/framework/ holds Smeltery’s working files, created when first needed: cache/
(CACHE_STORE=file), sessions/ (SESSION_DRIVER=file), uploads/ and sparks/ (upload temp files). With --db sqlite the database is
database/database.sqlite (?mode=rwc creates it on first connect). Git ignores the database file and everything
under storage/.
§Routes and controllers
use smeltery::prelude::*;
async fn home() -> Html<&'static str> {
Html("<h1>Welcome</h1>")
}
async fn show(Path(id): Path<u64>) -> Result<String> {
if id == 0 {
return Err(Error::not_found());
}
Ok(format!("post {id}"))
}
async fn index() -> &'static str { "all posts" }
async fn dashboard() -> &'static str { "admin" }
pub fn routes(r: &mut Router) {
r.get("/", home).name("home");
r.resource("/posts").index(index).show(show);
r.group("/admin", |r| {
r.get("/", dashboard).name("dashboard");
})
.name("admin.")
.middleware("auth");
}get,post,put,patch,delete,any;.name("…");.middleware("alias").- Paths use
{param}placeholders and{*rest}for a catch-all tail. group(prefix, …)with.name("prefix.")and.middleware("alias")for every route in it.resource("/posts")declares the actions you pick:
| Action | Method | Path | Name |
|---|---|---|---|
index | GET | /posts | posts.index |
create | GET | /posts/create | posts.create |
store | POST | /posts | posts.store |
show | GET | /posts/{post} | posts.show |
edit | GET | /posts/{post}/edit | posts.edit |
update | PUT, PATCH | /posts/{post} | posts.update |
destroy | DELETE | /posts/{post} | posts.destroy |
app.url("posts.show", &[("post", "7")])builds/posts/7; extra parameters become the query string.- HTML forms send
PUT,PATCHandDELETEas aPOSTwith a_methodfield (or theX-HTTP-Method-Overrideheader). - Routes from
routes/api.rsare registered withapi_routesand live under/api. - Files in
public/are served as-is when no route matches, withETag,Last-Modifiedand theCache-ControlofSTATIC_CACHE_CONTROL(defaultno-cache: browsers revalidate and get a 304 while the file is unchanged). Apps whose asset URLs change with their content can setpublic, max-age=31536000, immutable. - Files under
/storage(uploads, aftersmeltery storage:link) also getContent-Security-Policy: sandbox, so a stored HTML or SVG file never runs as a page of the site,X-Content-Type-Options: nosniff, andContent-Disposition: attachmentunless they are a PNG, JPEG, GIF, WebP, AVIF, BMP or icon image, a PDF, plain text, video or audio. PDFs get nosandbox(browsers do not show a sandboxed PDF). The headers follow the file that is served: any file frompublic/whose real path (links followed) lies instorage/app/publicorpublic/storagegets them, whatever URL reached it. A static-file path with a segment that ends in.or a space, or holds:or\(/storage./…,/storage%2e/…,/storage::$INDEX_ALLOCATION/…), answers 404 on every OS, because Windows opens such names as another file. - The framework adds
GET /up, a health check for load balancers and uptime monitors:200with the textOKandCache-Control: no-store, without a session or CSRF check.route:listshows it. An app route atGET /upreplaces it;AppBuilder::without_health_route()leaves it out. .middleware("throttle:5,1")allows a route 5 requests a minute per client (throttle:<max>,<minutes>;throttle:<max>counts per minute). The client is the authenticated user (the request’s principal: a signed-in session on web routes, or the principal anauth:alias listed beforethrottle:stored, see Guards and the principal), else the address afterTRUSTED_PROXIES(an IPv6 client by its /64). Each route counts on its own, by its path pattern, so/reset-password/{token}has one counter for every token. The count lives in the app’s cache store (CACHE_STORE), so the processes of an app (serve --no-agentsbesidework, several web processes) share it on thedatabase,redis,memcachedandfilestores; withCACHE_STORE=nullit lives in the process’s memory. A cache error answers 500 rather than letting the request through. Responses carryX-RateLimit-LimitandX-RateLimit-Remaining. Past the limit a form on a web route is sent back (303, its input flashed) with “Too many attempts. Please try again in N seconds.” on the fieldemail(throttle:5,1,nameputs it onname), and JSON clients and API routes get 429 “Too Many Requests” withRetry-After. An invalid value (throttle:0,throttle:x) stops the app at boot. The windows are fixed and follow the clock (throttle:5,1counts per calendar minute): a client that sends 5 requests at the end of one minute and 5 at the start of the next gets all 10 through within a few seconds.- Aliases with arguments (
throttle:5,1,auth:web) come from middleware families: a prefix and a function that builds the middleware for each route from the arguments and the route (POST /login), while the app builds. An error from it stops the app at boot. Core has the familiesthrottleandauth;AppBuilder::middleware_familyadds others:
use smeltery::middleware::{BoxedMiddleware, Next, Request};
use smeltery::{AppBuilder, Error};
fn build(app: AppBuilder) -> AppBuilder {
// `.middleware("tag:beta")` adds `X-Tag: beta` to the route's responses.
app.middleware_family("tag", |args, _route| {
let value = smeltery::http::HeaderValue::from_str(args)
.map_err(|_| Error::internal(format!("invalid tag `{args}`")))?;
Ok(BoxedMiddleware::new(move |req: Request, next: Next| {
let value = value.clone();
async move {
let mut res = next.run(req).await;
res.headers_mut().insert("x-tag", value);
res
}
}))
})
}Two families with one prefix, a prefix that is empty or holds :, and a plain alias that starts with a family’s
<prefix>: stop the app at boot. route:list shows the alias as written.
Handlers are async functions. Their arguments are extractors: Path, Query, Form, Json (Axum’s, re-exported in
smeltery::http), App, ClientInfo (the client’s IP, scheme and host, see The server), and
Config<T> for your config structs. They return anything that implements
IntoResponse, usually smeltery::Result<T>, or a Mold template struct (below).
smeltery::http::wants_json(&headers) tells whether a client asks for JSON (its Accept names application/json or
a +json type: error pages, auth and verified answer JSON then) and smeltery::http::is_inertia(&headers)
whether a request is an Inertia visit (X-Inertia: true).
§Mold templates
Views are resources/views/<name>.mold.html files with an @-directive syntax. A struct with #[derive(Mold)] names
its template; its fields are the template’s variables. A handler returns the struct (or Result<TheStruct>):
use smeltery::prelude::*;
#[derive(Mold)]
#[mold("posts/index")] // resources/views/posts/index.mold.html
pub struct PostsIndex {
pub title: String,
pub posts: Vec<Post>, // fields implement serde::Serialize
}
async fn index() -> Result<PostsIndex> {
Ok(PostsIndex { title: "Posts".into(), posts: load_posts().await? })
}@extends("layouts/app")
@section("title", title)
@section("content")
<h1>{{ title }}</h1>
@for(post in posts)
<x-card :title="post.title">
<a href="{{ route("posts.show", { post: post.id }) }}">Read</a>
</x-card>
@empty
<p>No posts yet.</p>
@endfor
@endsection| Syntax | Does |
|---|---|
{{ expr }} / {!! expr !!} | output, HTML-escaped / raw |
{{-- … --}} | comment, not rendered |
@{{ / @@ | a literal {{ / @ |
@if(expr) @elseif(expr) @else @endif, @unless(expr) @endunless | conditions |
@for(x in items) @empty @endfor, @for(key, value in map), @for x in items | loops; loop.index, loop.index0, loop.first, loop.last, loop.count |
@extends("layouts/app"), @section("name") … @endsection, @section("name", expr), @yield("name", "default") | layouts |
@include("partials/nav", { key: expr }) | include another template; it sees the current variables plus the given ones |
<x-alert type="error" :count="n">body</x-alert>, <x-forms.input /> | components from resources/views/components/ (forms/input); string attributes, :attr expressions, the body as {{ slot }}, named slots with @slot("title") … @endslot |
@csrf, @method("PUT") | hidden _token and _method form fields |
@error("field") … @enderror | the body with {{ message }} when the field has a validation error |
@auth … @else … @endauth, @guest … @endguest | by sign-in state |
@spark("counter", { start: 5 }), @sparksScripts | a live component and the Sparks runtime (see Sparks) |
Expressions have ||, &&, == != < <= > >=, + - * / %, !, field access a.b, indexing a[i], string,
number, true/false/null literals, the filters upper, lower, trim, title, len, default(x),
join(sep), json and url ({{ name | upper }}), and the functions route("name", { param: expr }), old("field"),
session("key") (a session value as text, "" when missing) and csrf_token(). false, 0, "", empty lists, and None are falsy. A line holding only a block directive leaves
no blank line in the output. An @word that is not a directive (@media) stays text, and an @ right after an
ASCII letter, digit or _ never starts a directive, so e-mail addresses (me@auth.example) stay text too. A
closing or branching directive glued to a word (x@endif, x@else) is a parse error that names the spot and says to
put a space before the @ (x @endif).
{{ }} escapes & < > " ', which is right for text and for quoted attribute values. A value that becomes
JavaScript or a link takes a filter:
jsonwrites the value (text, a number, a list, a struct) as a JavaScript literal in which<,>,&,', U+2028 and U+2029 are\uescapes. In an attribute whose value runs as JavaScript (x-data,@click,x-init,onclick, the arguments ofwire:click) write{{ value | json }}without quotes around it:x-data="{ name: {{ user.name | json }} }",wire:click="remove({{ post.id | json }}, {{ post.slug | json }})". Inside a<script>element write{!! value | json !!}, because the browser does not decode"there:<script>const post = {!! post | json !!};</script>. Text echoed between quotes in JavaScript ('{{ name }}') is not safe: the browser turns'back into'before the code runs.urlkeeps a relative URL and anhttp:,https:,mailto:ortel:URL, and writes#for any other (javascript:,data:), and for a value with an&, a byte-order mark or a control character before its first/,?or#(an entity such as:hides a scheme):<a href="{{ link | url }}">.- Attribute values are quoted (
class="{{ name }}"): an unquoted value ends at the first space of the text. {!! !!}never goes into an attribute: it writes"as it is. In attributes use{{ }}(withjsonorurl);{!! v | json !!}belongs inside<script>only.
Two modes, same output:
- Debug builds read the templates at runtime from
<root>/resources/viewsand re-read a file when it changes, so an edit shows on the next request without recompiling. - Release builds run Rust code generated from the templates at compile time. A template variable without a
matching field, a syntax error and a missing template are compile errors naming the
.mold.htmlfile and line.
A template error while rendering (for example a division by zero) answers 500. With APP_DEBUG=true the page shows
the file, line, column and the lines around it; otherwise it is the normal error page and the details go to the
log.
The values @csrf, @auth, @guest, @error, old() and session() read come from smeltery::view::ViewData,
which the session middleware of web routes fills (see Sessions). On API routes there is no session:
@csrf is a render error there and @auth renders its @else branch. route() uses the app’s named routes.
§Wiring: bootstrap/app.rs
use smeltery::AppBuilder;
use smeltery::middleware::{Next, Request};
use smeltery::Response;
#[derive(Clone)]
pub struct AppConfig {
pub name: String,
}
async fn log_requests(req: Request, next: Next) -> Response {
let path = req.uri().path().to_owned();
let res = next.run(req).await;
println!("{path} -> {}", res.status());
res
}
async fn home() -> &'static str { "home" }
pub fn build(app: AppBuilder) -> AppBuilder {
app.config(AppConfig { name: "Demo".into() })
.middleware("log", log_requests)
.routes(|r| {
r.get("/", home).name("home").middleware("log");
})
}config(value)/service(value)register a value by type; handlers takeConfig<T>, other code callsapp.config::<T>()/app.service::<T>().middleware(alias, f)registers route middleware;global_middleware(f)runs on every request;middleware_family(prefix, make)registers aliases with arguments (see Routes and controllers).on_boot(|app| async move { … })runs async setup (open connections, register services) before the server starts.migrations(register),seeders(register)andcommands(register)take theregisterfunctions ofdatabase/migrations,database/seedersandapp/commands.auth::<User>()(one model per app: two different models stop the app at boot) makesUserthe modelAuthsigns in and registers thewebguard and theauth,guest,verifiedandpassword.confirmmiddleware;credential_listener(l),second_factor(f),login_completion(c)andlogin_policy(p)register the password-change hooks, a second factor, the sign-in completion and a rule every new sign-in meets;guard(g)registers another guard (see Guards and the principal).hallmark(Hallmark::new())(smeltery::hallmark::HallmarkExt) adds API tokens and theauth:hallmarkguard (see API tokens).bellows()(smeltery::bellows::BellowsExt) adds thebellows:mcpcommand (see Bellows below).
§Configuration
Config lives in typed structs under config/, read from .env with env(key, default):
use smeltery::config::env;
pub struct AppConfig {
pub name: String,
pub debug: bool,
pub port: u16,
}
pub fn app() -> AppConfig {
AppConfig {
name: env("APP_NAME", "Smeltery"),
debug: env("APP_DEBUG", false),
port: env("SERVER_PORT", 8000),
}
}env reads String, bool (true/false, 1/0, yes/no, on/off), every integer type, f32, f64 and Option
of them. A value in the real environment wins over .env. A value that does not parse falls back to the default and
logs a warning with the key name only. Smeltery parses .env itself and never modifies the process environment.
Logging: the app logs with tracing to stderr, in colour only when stderr is a terminal and NO_COLOR is not
set (redirected output is plain text). With LOG_FILE set, every line also goes to that file as plain
text (timestamp, level, target, message and fields), appended; the directory is created (on Unix the file is 0640
and new folders 0750). A line break inside a logged value is written as \n (or \r), so a value never starts a
line of its own, on the console or in the file. A dedicated thread writes
the file through a bounded queue, so a request never waits for the disk: when the queue is full the line is dropped
and the writer then notes in the file how many lines it dropped. The file is flushed when the app exits. Secrets are
never logged. key:generate and storage:link log to stderr only. A process running as root (sudo) opens
LOG_FILE only when every folder on its path belongs to root and no other user can write to it, and never through a
symlink at the file; otherwise it logs to stderr and says why.
The framework reads these keys:
| Key | Default | Meaning |
|---|---|---|
APP_NAME | Smeltery | app name |
APP_ENV | production | environment name: local (new apps’ .env), testing (TestApp), production; a missing key means production |
APP_DEBUG | false | show error details in error pages |
APP_URL | http://127.0.0.1:8000 | public URL |
APP_KEY | empty | secret key (smeltery key:generate) |
SERVER_HOST | 127.0.0.1 | bind address |
SERVER_PORT | 8000 | port |
LOG_LEVEL | info | trace, debug, info, warn, error |
LOG_FILE | empty | a log file (relative to the app root); empty logs to stderr only. New apps set storage/logs/smeltery.log |
LOG_MAX_BYTES | 10485760 | size at which the log file is renamed to <file>.1 (one backup) and a new file starts |
REQUEST_TIMEOUT | 30 | seconds before a request gets a 408 (at least 1) |
BODY_LIMIT | 2097152 | largest request body in bytes |
UPLOAD_MAX_BYTES | 10485760 | largest multipart/form-data request Valid reads (files and fields together) |
SHUTDOWN_TIMEOUT | 30 | seconds to drain requests on shutdown |
SERVER_HEADER_TIMEOUT | 30 | seconds a client has to send a request’s headers; a connection (HTTP/1 or HTTP/2) with no request running for that long is closed |
SERVER_MAX_CONNECTIONS | 4096 | most connections open at once; further clients wait to be accepted |
SERVER_MAX_CONNECTIONS_PER_IP | 128 | most connections one client address holds open at once (an IPv6 client by its /64), and most requests it runs at once across them; a further connection is closed at once, a further request gets 429; peers in TRUSTED_PROXIES are not counted; 0 turns the limit off |
SERVER_MAX_STREAMS | 32 | most requests one HTTP/2 connection runs at once (at least 1); the client waits for a free one |
TRUSTED_PROXIES | empty | proxies whose X-Forwarded-* headers are believed: IPs and CIDR ranges, comma-separated, or * (see The server); empty trusts nobody; a range of every address (0.0.0.0/0, ::/0) stops the app at boot |
STATIC_CACHE_CONTROL | no-cache | the Cache-Control header of files served from public/ |
SECURITY_HEADERS | true | send X-Content-Type-Options, Referrer-Policy and the frame headers with every response (see The server) |
FRAME_OPTIONS | SAMEORIGIN | who may show the app’s pages in a frame: SAMEORIGIN, DENY or off; any other value stops the app at boot |
HSTS_MAX_AGE | 0 | seconds of Strict-Transport-Security, sent only when APP_URL starts with https://; 0 sends none |
CORS_ALLOWED_ORIGINS | empty | origins (exact scheme://host[:port], comma-separated) whose pages and hybrid apps may call CORS_PATHS cross-origin, without credentials (see The server); empty sends no CORS headers; * stops the app at boot |
CORS_PATHS | /api/ | path prefixes (comma-separated, each ending in /) the CORS rules cover |
PUBSUB_DRIVER | auto | how messages (Sparks pushes) reach the app’s other processes: auto, local, database or redis (see PubSub); any other value stops the app at boot |
PUBSUB_POLL_MS | 250 | milliseconds between the database driver’s reads (at least 10) |
SMELTERY_ROOT | current directory | the app root (public/, .env, storage/, a relative SQLite path) |
DATABASE_URL | empty | the database (see below); empty means the app has none |
DB_POOL_MAX | 10 | most connections in the database pool |
DB_CONNECT_TIMEOUT | 5 | seconds to open a connection or wait for a free one |
SESSION_DRIVER | cookie | where sessions live: cookie, database or file |
SESSION_LIFETIME | 120 | minutes an idle session lives |
SESSION_ABSOLUTE_LIFETIME | 10080 | minutes a session lives at most after it started or its user signed in, however active it is (7 days); 0 = no limit |
SESSION_COOKIE | <app name in snake case>_session | the session cookie’s name (with __Host- in front when APP_URL is https) |
AUTH_HOME | /dashboard | where the guest middleware sends signed-in users |
AUTH_VERIFICATION_EXPIRE | 60 | minutes an email verification link is valid (at least 1) |
AUTH_PASSWORD_TIMEOUT | 10800 | seconds a password confirmation lasts for the password.confirm middleware (at least 1) |
HASH_CONCURRENCY | the number of CPUs | argon2 password hashes and checks running at once in the process |
HASH_QUEUE | 64 | password hashes waiting for a turn; further ones answer 503 at once |
CACHE_STORE | database | the default cache store: database, redis, memcached, file, memory, array or null |
CACHE_PREFIX | <app name in snake case>_cache_ | put in front of every cache key and lock name |
CACHE_PATH | storage/framework/cache | the file store’s directory (relative to the app root) |
CACHE_TABLE | cache | the database store’s table; locks live in <table>_locks |
CACHE_MEMORY_CAPACITY | 10000 | most entries the memory store keeps |
CACHE_TIMEOUT | 5 | seconds one call to the database, redis or memcached store may take |
CACHE_MAX_VALUE_BYTES | 16777216 (16 MiB) | the largest cached value read back; a larger one is an error for get and a miss for remember (the file, database and redis stores check the size before reading the value) |
REDIS_URL | redis://127.0.0.1:6379 | the Redis server of the redis cache store, the redis PubSub driver and the redis queue driver (rediss:// for TLS) |
MEMCACHED_SERVERS | 127.0.0.1:11211 | the memcached store’s servers, comma-separated host:port; the memcached protocol is not encrypted, so the servers belong on this machine or a private network |
TEST_CACHE_STORE | array | the cache store of TestApp |
§Database and models
The database is set by DATABASE_URL in .env. Each backend is a Cargo feature of smeltery:
| Backend | Feature | DATABASE_URL |
|---|---|---|
| SQLite | sqlite | sqlite://database/database.sqlite (relative to the app root; the file is created when missing, its directory must exist), sqlite:///srv/app/database.sqlite, sqlite::memory: |
| PostgreSQL | postgres | postgres://user:password@localhost/my_app |
| MySQL / MariaDB | mysql | mysql://user:password@localhost/my_app (mariadb://… works the same) |
The app connects while it boots; when it cannot, boot fails with the reason. A URL whose backend feature is off is
an error naming the feature. Every connection and every wait for a pooled connection is bounded by
DB_CONNECT_TIMEOUT. Connection errors show the URL with *** in place of the user name and password. A /, ?,
# or @ in the password is written percent-encoded (%2F, %3F, %23, %40).
SQLite database files run in WAL journal mode with synchronous=NORMAL, and a connection waits up to 5 seconds for
another one’s lock before it reports “database is locked”. Readers do not block the writer, so serve and a
migrate run can share the file. WAL keeps two more files next to the database (database.sqlite-wal and
database.sqlite-shm): copy all three in a backup, or use SQLite’s .backup command. WAL needs a local file system
(not a network share). In-memory databases and ?mode=ro URLs keep their own journal mode. Every SQLite connection
runs with recursive_triggers on, so INSERT OR REPLACE fires the delete triggers of the row it replaces. A trigger
of the app’s own that writes to the table it fires on fires itself again: give it a guard, AFTER UPDATE OF <column>
on a column it does not write, or WHEN new.<column> IS NOT old.<column>. On Unix a new database
file is created readable by its owner only (0600), and SQLite gives the -wal / -shm files the same mode.
smeltery::db::Db is the handle: a pool, cheap to clone. Handlers take it as an argument (db: Db), other code
calls app.db()?. db.execute(sql) runs one SQL statement exactly as written, so it never holds values from a
request; db.execute_with(sql, values) (affected rows) and db.query_with(sql, values) (the rows) bind values as
parameters: ? on SQLite and MySQL, $1, $2 … on PostgreSQL. db.backend() names the engine, and db.conn() is
SeaORM’s DatabaseConnection for anything else.
db.execute_with("UPDATE users SET active = ? WHERE email = ?", [true.into(), email.into()])
.await?;
let rows = db.query_with("SELECT name FROM users WHERE id > ?", [10.into()]).await?;
for row in rows {
let name: String = row.try_get("", "name")?;
println!("{name}");
}Models are SeaORM 2.0 entities. app/models/post.rs:
use smeltery::db::prelude::*;
#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "posts")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: i64,
pub title: String,
pub body: String,
pub created_at: Option<DateTimeUtc>,
pub updated_at: Option<DateTimeUtc>,
}
impl ActiveModelBehavior for ActiveModel {}app/models/mod.rs names it: pub use post::Model as Post;. smeltery::db::prelude::* brings the sea_orm crate
itself (for the SeaORM macros), SeaORM’s entity prelude and query traits, Set / NotSet / Unchanged, the column
types (DateTimeUtc, Date, Json, Uuid …), serde’s Serialize / Deserialize, and Smeltery’s Db, Record
and Found. The serde derives expand to code that names the serde crate, so an app that uses them depends on it
(cargo add serde --features derive).
Smeltery’s Record trait gives every model the everyday calls:
| Call | Returns |
|---|---|
Post::all(&db) | every row: Result<Vec<Post>> |
Post::find(&db, id) | Result<Option<Post>> |
Post::find_or_404(&db, id) | the row, or a 404 Error |
Post::count(&db) | Result<u64> |
Post::create(&db, post::ActiveModel { title: Set(..), ..Default::default() }) | the inserted row |
post.update(&db, |m| { m.title = Set(..); }) | the updated row (the closure edits the ActiveModel) |
post.delete(&db) | Result<()> |
Post::paginate(&db, page) | one Page<Post> of every row, by primary key (see Pagination) |
Post::query() | a SeaORM Select to filter, order and run |
When the model has created_at / updated_at columns, create sets both (unless the values set them) and update
sets updated_at, to the current UTC time.
For everything else, SeaORM’s query API is available through smeltery::db::prelude, and its queries run on
db.conn():
use smeltery::db::prelude::*;
async fn latest(db: Db) -> smeltery::Result<Vec<Post>> {
let post = Post::create(&db, post::ActiveModel { title: Set("Hello".into()), ..Default::default() }).await?;
post.update(&db, |m| { m.title = Set("Hello again".into()); }).await?;
Ok(Post::query()
.filter(post::Column::Title.contains("Hello"))
.order_by_desc(post::Column::Id)
.limit(10)
.all(db.conn())
.await?)
}SeaORM’s ModelTrait is not in the prelude because its delete would take the place of Record::delete; import it
from sea_orm for find_related. Database errors convert into smeltery::Error with ? (a 500, details in the log).
Route model binding: Found<Post> loads the row whose primary key is the route’s last path parameter, and
answers 404 when there is none (or the parameter is not a valid key):
use smeltery::prelude::*;
async fn show(Found(post): Found<Post>) -> String {
post.title
}
pub fn routes(r: &mut Router) {
r.get("/posts/{post}", show).name("posts.show");
}§Pagination
PageQuery is a handler argument that reads ?page= (default 1) and ?per_page= (default 15) from the URL. It
never rejects a request: a missing or unreadable value means the default, page is kept within 1 to 10,000 and
per_page within 1 to 100 (page.max(250) raises the upper bound, page.default_per_page(30) changes the default).
Post::paginate(&db, page) returns one page of every row by primary key; smeltery::db::paginate(&db, select, page)
returns one page of any SeaORM select (give it an order so pages do not overlap). Each runs two statements: the page
and the count.
use smeltery::db::paginate;
use smeltery::db::prelude::{ColumnTrait, QueryFilter, QueryOrder};
use smeltery::prelude::*;
async fn index(db: Db, page: PageQuery) -> Result<Json<Page<Post>>> {
let select = Post::query()
.filter(post::Column::Published.eq(true))
.order_by_desc(post::Column::Id);
Ok(Json(paginate(&db, select, page).await?))
}A Page<T> holds items, page, per_page, total and last_page (at least 1), and serializes with those names
({"items": [...], "page": 2, "per_page": 15, "total": 47, "last_page": 4}), so a Mold template or an Alloy page
reads it directly. page.map(f) changes every item; has_next() and has_previous() tell whether there are pages
around it. A page past the last one has no items. Page::new(items, page, per_page, total) builds one.
§Model events
A model listener is told about every successful create, update and delete made through Record. It sees what
happened (ModelChange::Created, Updated or Deleted), the table and the row: the saved row after a create or an
update, the row as the caller of delete held it. Register it with .model_listener(…) in bootstrap/app.rs:
use std::sync::atomic::{AtomicU64, Ordering};
use smeltery::db::{Db, ModelChange, ModelEvent, ModelListener};
use smeltery::{AppBuilder, BoxFuture};
#[derive(Default)]
struct CountDeletes(AtomicU64);
impl ModelListener for CountDeletes {
fn changed<'a>(&'a self, _db: &'a Db, event: ModelEvent<'a>) -> BoxFuture<'a, ()> {
Box::pin(async move {
if event.change == ModelChange::Deleted && event.table == "posts" {
self.0.fetch_add(1, Ordering::Relaxed);
}
})
}
}
pub fn build(app: AppBuilder) -> AppBuilder {
app.model_listener(CountDeletes::default())
}event.model::<Post>() gives the row as a Post when the event concerns posts (None otherwise), and
event.is::<Post>() checks the model alone. A unit test calls a listener directly with
ModelEvent::new(ModelChange::Created, "posts", &post).
- Listeners run after the write has succeeded, outside any transaction, in registration order, and
create/update/deletewait for them before they return: a listener does quick work (or hands slow work to a queue orapp.spawn_owned). A failed write tells no listener, and adeleteof a row that is already gone deletes nothing and tells no listener. - The listeners of the app’s database run on a task the app owns: when the caller is cancelled while they run (a request timeout, a closed connection), they still finish, and shutdown waits for them like for the app’s other owned work.
- A listener returns nothing and logs its own errors; the write it is told about stays done. A listener that panics is logged and the next one still runs.
- An
updatethat changes nothing writes nothing and tells no listener. With anupdated_atcolumn everyupdatewrites. - Only writes through
Recordare seen: raw SQL (db.execute…) and SeaORM’s own calls (Entity::insert,update_many,delete_many) are not. smeltery::db::without_listeners(async { … })runs its future with listeners switched off for writes made in that task (tasks it spawns are not covered), for bulk work such as a seeder.- Writes a listener makes through
Recordare reported to the listeners too: wrap them inwithout_listenerswhen they must not be (a listener that writes to the table it listens to would loop). - An app without listeners does no listener work on a write.
§Migrations
Migrations live in database/migrations/, one file each, registered in order in database/migrations/mod.rs and
wired with .migrations(database::migrations::register) in bootstrap/app.rs:
use smeltery::db::migration::{Migration, Schema};
use smeltery::Result;
/// Creates `posts`.
pub struct CreatePostsTable;
impl Migration for CreatePostsTable {
fn name(&self) -> &'static str {
"2026_10_03_120000_create_posts_table"
}
async fn up(&self, schema: &Schema) -> Result<()> {
schema
.create("posts", |t| {
t.id();
t.foreign_id("user_id").constrained("users").cascade_on_delete();
t.string("title");
t.text("body").nullable();
t.boolean("published").default(false);
t.timestamps();
})
.await
}
async fn down(&self, schema: &Schema) -> Result<()> {
schema.drop_if_exists("posts").await
}
}
use smeltery::db::migration::Migrator;
pub fn register(m: &mut Migrator) {
m.add(m2026_10_03_120000_create_posts_table::CreatePostsTable);
// smeltery:migrations
}The table blueprint (t):
| Method | Column |
|---|---|
t.id() | id, 64-bit auto-increment primary key (i64) |
t.string(name), t.string_len(name, n) | varchar(255) / varchar(n) (String) |
t.text(name) | text (String) |
t.integer(name), t.big_integer(name) | 32-bit / 64-bit integer (i32 / i64) |
t.boolean(name) | boolean (bool) |
t.float(name), t.double(name) | f32 / f64 |
t.decimal(name, precision, scale) | fixed-point decimal |
t.date(name) | date (Date) |
t.datetime(name) | timestamp, with time zone where the backend has one (DateTimeUtc) |
t.json(name) | JSON, jsonb on PostgreSQL (Json) |
t.uuid(name) | UUID (Uuid) |
t.foreign_id(name) | 64-bit integer (i64); .constrained("users") adds a foreign key to users.id, .cascade_on_delete() makes it ON DELETE CASCADE |
t.timestamps() | nullable created_at and updated_at |
Columns are NOT NULL unless .nullable(). Every column also takes .unique(), .default(value) and .index()
(an index named <table>_<column>_index). The schema builder writes the SQL for the connected backend.
Schema has create(table, |t| …), table(table, |t| …) (add columns, and with t.drop_column(name) drop them),
drop(table), drop_if_exists(table), rename(from, to), has_table(name) and raw(sql). drop_column drops the
column’s <table>_<column>_index / _unique index first; SQLite (the bundled one supports DROP COLUMN) refuses a
column that is a primary key, UNIQUE in its CREATE TABLE, part of a foreign key or used by another index, view or
trigger, and MySQL refuses a column of a foreign key.
The migrations table records each migration’s name and batch. On SQLite and PostgreSQL each migration runs in a
transaction, so one that fails leaves neither its changes nor its record; MySQL commits schema changes as they run.
| Command | Does |
|---|---|
smeltery migrate | run every pending migration, as one new batch |
smeltery migrate:rollback | revert the last batch; --step N reverts the last N migrations |
smeltery migrate:fresh | drop every table in the database (on SQLite virtual tables such as an FTS5 index first), then run every migration; --seed then runs the seeders |
smeltery migrate:status | list each migration as Ran (with its batch) or Pending |
With APP_ENV=production, migrate, migrate:rollback, migrate:fresh and db:seed refuse to run unless
--force is given.
§Seeders and factories
A seeder fills the database; database/seeders/mod.rs registers them, wired with
.seeders(database::seeders::register):
use smeltery::db::Db;
use smeltery::db::seed::{Seeder, Seeders};
pub struct DatabaseSeeder;
impl Seeder for DatabaseSeeder {
async fn run(&self, db: &Db) -> smeltery::Result<()> {
db.execute("INSERT INTO settings (name) VALUES ('site')").await?;
Ok(())
}
}
pub fn register(s: &mut Seeders) {
s.add(DatabaseSeeder);
// smeltery:seeders
}smeltery db:seed runs every seeder in order; --class DatabaseSeeder runs only that one.
The DatabaseSeeder of a new app creates a demo user (demo@example.com, password password) only when APP_ENV
is local or testing; in any other environment, production included, it creates nothing.
A factory makes rows with made-up values:
use smeltery::db::factory::{Factory, Fake};
use smeltery::db::prelude::*;
pub struct PostFactory;
impl Factory for PostFactory {
type Entity = crate::app::models::post::Entity;
fn definition(&self, fake: &mut Fake) -> crate::app::models::post::ActiveModel {
crate::app::models::post::ActiveModel {
title: Set(fake.sentence(4)),
body: Set(fake.paragraph()),
..Default::default()
}
}
}
let post = PostFactory.create(&db).await?;
let posts = PostFactory.count(3).create(&db).await?;
let pinned = PostFactory.create_with(&db, |m| m.title = Set("Pinned".into())).await?;
let unsaved = PostFactory.make(&mut Fake::seeded(1));create inserts through Record::create (timestamps included). Fake is a small seedable generator: the same seed
gives the same values. It has word, words(n), sentence(n), paragraph, first_name, last_name, name,
email, unique_email, int(a..=b), bool, uuid (as text) and date. Each factory create uses the next seed
of a process-wide sequence.
§Cache
smeltery::cache::Cache is the app’s cache: a handler argument (or app.cache(), or ctx.cache() in Watchfire
agents and jobs) on the default store, CACHE_STORE. Values are any Serialize / Deserialize type, stored as JSON.
use std::time::Duration;
use smeltery::prelude::*;
async fn dashboard(cache: Cache) -> Result<String> {
let total: u64 = cache
.remember("posts.total", Duration::from_secs(300), || async { Ok(128) })
.await?;
cache.put("last.visit", "now", Duration::from_secs(60)).await?;
let hits = cache.increment("hits", 1).await?;
let first = cache.add("welcomed", &true, Duration::from_secs(3600)).await?;
Ok(format!("{total} posts, {hits} hits, first visit: {first}"))
}
async fn import(cache: Cache) -> Result<&'static str> {
let lock = cache.lock("import", Duration::from_secs(120));
if !lock.block(Duration::from_secs(5)).await? {
return Ok("an import is running");
}
// … the import …
lock.release().await?;
Ok("imported")
}| Method | Does |
|---|---|
get::<T>(key) | the value, or None when missing or expired (an error when it does not deserialize into T or is larger than CACHE_MAX_VALUE_BYTES; the error never quotes the value) |
put(key, &value, ttl) / forever(key, &value) | store for ttl (zero removes the key) / until removed |
add(key, &value, ttl) | store only when the key holds no live value; true when stored (atomic) |
remember(key, ttl, || async { … }) / remember_forever | the value, or compute, store and return it (a value of another shape is computed again) |
has, forget, pull | check, remove, read and remove |
increment(key, by) / decrement(key, by) | atomic counter; a missing key starts at 0, an entry keeps its time to live |
flush() / flush_all() | remove every entry and lock under this cache’s prefix except Watchfire’s leases and schedule claims (names starting with watchfire:) / everything under the prefix (memcached: both empty its servers) |
store("redis")? / with_prefix(…) | the same app’s other store / another key prefix |
lock(name, ttl) | an atomic lock: get(), block(timeout), refresh() (the owner holds it for ttl again, from now), release() (only by its owner), force_release(), owner(); restore_lock(name, owner, ttl) rebuilds it elsewhere |
| Store | Where entries live |
|---|---|
database (default) | the cache table (key, value, expiration in Unix ms) and cache_locks; new apps have the migration create_cache_tables (smeltery::cache::migrations::{up, down}). Keys of any length work: one longer than 191 characters is stored as its first 120 characters and its SHA-256. On MySQL keys compare byte for byte (utf8mb4_bin), so a and A are two keys. Expired rows are deleted on about one write in a hundred |
redis | a Redis server (REDIS_URL; feature redis of smeltery): SET NX PX for add and locks, INCRBY, a compare-and-delete script to release a lock, SCAN + UNLINK to flush a prefix; rediss:// uses rustls |
memcached | memcached servers (MEMCACHED_SERVERS; feature memcached): native add / incr / decr, lock release by cas; counters stop at 0 and expiry counts whole seconds |
file | storage/framework/cache/<2 hex>/<sha256 of the key> (CACHE_PATH; on Unix files 0600, folders 0700); writes go through a temp file and a rename, add / counters / locks hold a per-key lock file, so processes on one machine share it; flush removes only files of that shape |
memory | this process’s memory, up to CACHE_MEMORY_CAPACITY entries (moka); shared by every app in the process, not between processes |
array | the memory of one app; TestApp uses it (TEST_CACHE_STORE picks another) |
null | nothing: reads miss, add answers false, increment answers its argument, every lock is granted |
Redis is the recommended store in production: one server shared by every process and machine, with native atomic
operations and locks. Memcached is the second choice; its client is synchronous and runs on blocking threads. Calls
to the database, Redis and memcached stores time out after CACHE_TIMEOUT seconds. CACHE_PREFIX keeps apps that
share a store apart. Locks on the database, Redis and memcached stores exclude every process using the store, e.g.
serve and work running the same job; locks on the file store exclude the processes of one machine (or of a disk
they share). The database and file stores remove expired entries on about one write in a hundred.
smeltery cache:clear [store] empties a store from the command line and keeps the leases and schedule claims
Watchfire holds there, so no singleton agent starts in a second process and no tick runs twice. cache:clear --all
removes those too; the processes take their agents again within WATCHFIRE_LEASE_TTL (see “Several processes”),
and meanwhile a singleton agent can run in two processes and a tick of the current minute can run again. Memcached
cannot keep some keys while it flushes, so cache:clear memcached asks for --all. Memcached sends everything
unencrypted: run it on the app’s machine or a private network.
An app whose cache tables were created on MySQL before mysql_statements existed adds a migration that runs them
(byte-for-byte keys, MEDIUMTEXT values):
use smeltery::Result;
use smeltery::db::Backend;
use smeltery::db::migration::{Migration, Schema};
pub struct CacheKeysBinary;
impl Migration for CacheKeysBinary {
fn name(&self) -> &'static str {
"2026_10_05_000000_cache_keys_binary"
}
async fn up(&self, schema: &Schema) -> Result<()> {
if schema.backend() == Backend::MySql {
for sql in smeltery::cache::migrations::mysql_statements("cache") {
schema.raw(&sql).await?;
}
}
Ok(())
}
async fn down(&self, _schema: &Schema) -> Result<()> {
Ok(())
}
}§Rate limiting
smeltery::cache::RateLimiter counts hits per key in fixed windows in the app’s cache store, the engine of
throttle:. RateLimiter::new(name, max, window) allows max hits per key per window (a window under a second
counts as one second; max 0 refuses every hit); limiters with different names count apart.
limiter.hit(&app, key).await? counts one hit and answers RateLimit::Allowed { remaining } or
RateLimit::Limited { retry_after } (seconds until the window ends; .allowed() tells which), one atomic add +
increment, so parallel hits never get more than max through. A cache error is returned, and the caller refuses
what it guards. limiter.clear(&app, key).await? forgets the key’s hits in the current window.
limiter.peek(&app, key).await? reads the key’s state without counting a hit (Allowed { remaining } or Limited { retry_after }): a read only, so parallel callers may all see Allowed; it refuses a blocked key early, and the
work itself is guarded by hit. With
CACHE_STORE=null the counts live in the app’s process memory. Limiters with the same name, max and window share
their counts in every case.
use std::sync::LazyLock;
use std::time::Duration;
use smeltery::cache::RateLimiter;
use smeltery::prelude::*;
static CODES: LazyLock<RateLimiter> =
LazyLock::new(|| RateLimiter::new("codes", 5, Duration::from_secs(300)));
async fn check_code(app: &App, user_id: i64) -> Result<bool> {
Ok(CODES.hit(app, &format!("user:{user_id}")).await?.allowed())
}§PubSub: messages between processes
smeltery::pubsub::PubSub carries messages between the processes of one app (Sparks’ Broadcast sends through
it). Every app has one: PubSub::of(&app), or app.service::<PubSub>(). A message has a topic and a JSON payload
of at most 64 KiB:
use serde_json::json;
use smeltery::pubsub::PubSub;
use smeltery::{App, Result};
async fn watch_prices(app: App) -> Result<()> {
let pubsub = PubSub::of(&app).expect("every app has one");
let mut prices = pubsub.subscribe("prices");
pubsub.publish("prices", &json!({ "symbol": "ORE", "price": 7 })).await?;
while let Ok(message) = prices.recv().await {
println!("{} (from another process: {})", message.payload, message.remote);
}
Ok(())
}publish delivers to the subscribers in this process at once and waits for the driver to take the message for the
other processes (it returns the driver’s error). forward(topic, &payload) sends to the other processes only and
never waits: the message goes into a queue of 1024 that one task sends on; a full queue or a driver error drops it,
counts it (dropped()) and logs it at most once a minute. At shutdown the queue keeps taking messages while they
come (for work that stops on the same signal), then sends what is left within 2 s; a message forwarded after that,
or left unsent, is counted as dropped too. subscribe(topic) receives the topic’s messages from
every process. Each topic has its own buffer of 1024 messages in a process, so a burst on one topic never makes the
subscribers of another fall behind; a subscriber more than 1024 messages behind its topic gets RecvError::Lagged
and then receives again (past 256 subscribed topics in one process, further topics share one buffer; the
framework’s topics auth, anvil and sparks always have their own). publish answers an error and forward
drops the message for the topics auth and anvil: auth events go through smeltery::auth::publish_event, Anvil’s
events through Anvil.
Delivery is at most once and in order per publishing process: a message sent while the database or Redis is down is
lost, so a page or client reloads its state after a reconnect.
PUBSUB_DRIVER decides how messages reach the other processes. The process logs the driver it chose at start.
PUBSUB_DRIVER | Messages reach |
|---|---|
auto (default) | decided by what the process runs: serve with its background work uses local; serve --no-agents (or WATCHFIRE_IN_SERVE=false, or ANVIL_IN_SERVE=false), work and Anvil’s anvil process use redis when CACHE_STORE=redis (feature redis), else database when the app has a database, else local with a warning. Console commands and TestApp use local |
local | this process only |
database | every process on the app’s database: the pubsub_messages table, which each process reads every PUBSUB_POLL_MS (default 250) while something in it subscribes (a web process with Sparks always does) |
redis | every process on the Redis server of REDIS_URL (feature redis): PUBLISH / SUBSCRIBE on the channel <CACHE_PREFIX>pubsub |
Several serve processes behind a load balancer each count as one process under auto, and so does a serve that
runs its background work next to an extra work process: give them PUBSUB_DRIVER=database or redis. An explicit database or redis driver that lacks its database, APP_KEY or
feature stops serve and work from starting. TestApp uses local unless TEST_PUBSUB_DRIVER names another
driver. Messages that leave the process are encrypted and authenticated with AES-256-GCM under a key derived from
APP_KEY, so every process needs the same APP_KEY; a message sealed under another key, or sent more than 5
minutes earlier (by the sender’s clock; a message written into the table or Redis again later), is skipped, counted
and logged, so the clocks of the app’s machines must agree within 5 minutes (NTP). Each message carries a random id,
and a process delivers each id once: a message written into the table or Redis again within those 5 minutes is
skipped and logged too. A payload longer than the largest sealed message is skipped without being read. Every
process of the database driver deletes rows older than a minute, and rows dated more than 5 minutes ahead, every
10 s (in statements of 500 rows, for at most 2 s each time); its read position never runs ahead of the database’s
clock (when the clock steps back, the position follows it and the process logs it). The redis driver checks its
subscriber connection with PING every 30 s and reconnects when a PING goes unanswered for 2 s, so a connection
dropped silently by a NAT or load balancer is replaced.
New apps with Watchfire (headless apps, and web apps with the watchfire building block) and web apps with the
anvil building block have the migration of the pubsub_messages table (smeltery::pubsub::migrations::{up, down}; MEDIUMTEXT payloads on MySQL).
smeltery pubsub:install adds the same migration to an app without it; run smeltery migrate after it.
§Encryption and random tokens
smeltery::crypto holds the helpers every part of Smeltery uses: random_token(len) (letters and digits from the
OS random source, every character equally likely), random_bytes(len), sha256_hex(text) and
constant_time_eq(a, b) (compares two secrets of equal length in constant time).
app.derive_key(purpose) is a 32-byte key derived from APP_KEY for purpose: HMAC-SHA256 of APP_KEY over
smeltery-app-key:<purpose>, a label that no signature (app.sign) and no key the framework uses for its own
messages share, so none of them is ever such a key. Every purpose gives an unrelated key; Smeltery’s own crates use
dotted purposes (anvil.secret, anvil.key), so plain names are free for apps.
app.encrypt(purpose, aad, plaintext) encrypts and authenticates a value with AES-256-GCM under a key of its own
for purpose (HMAC-SHA256 of APP_KEY over smeltery-app-enc:<purpose>, never a derive_key key, so a derived key
handed out for a purpose never opens values encrypted under it) and a random 96-bit nonce, as base64 of nonce,
ciphertext and tag. aad is authenticated but not stored:
app.decrypt(purpose, aad, &sealed) returns Ok(Some(plaintext)) only for the same purpose, aad and APP_KEY,
and Ok(None) for anything edited, truncated or sealed otherwise. Both fail without a usable APP_KEY. Pass the
id of the record a secret belongs to as aad, so a value copied to another row does not open there:
use smeltery::prelude::*;
fn seal_secret(app: &App, user_id: i64, secret: &str) -> Result<String> {
app.encrypt("api-secrets", user_id.to_string().as_bytes(), secret.as_bytes())
}
fn open_secret(app: &App, user_id: i64, sealed: &str) -> Result<Option<String>> {
Ok(app
.decrypt("api-secrets", user_id.to_string().as_bytes(), sealed)?
.and_then(|bytes| String::from_utf8(bytes).ok()))
}Rotating APP_KEY makes every encrypted value unreadable.
§Console commands
The app binary runs these commands (the smeltery command forwards them):
| Command | Does |
|---|---|
serve | start the HTTP server (the default), with the app’s Watchfire agents, queue workers and scheduler (--no-agents: without them) |
work | run the Watchfire agents, queue workers and scheduler without the HTTP server |
route:list | list every route |
migrate, migrate:rollback, migrate:fresh, migrate:status | migrations (see above) |
db:seed | run the seeders |
cache:clear [store] | remove every entry of the default cache store, or of the named one, except Watchfire’s leases and schedule claims (--all: those too) |
agents:list | the running app’s agents with state, health, restarts, runs, last heartbeat, next restart |
agents:start, agents:stop, agents:pause, agents:resume, agents:restart <name> | control an agent of the running app |
agents:logs <name> | an agent’s last log lines, from the running app |
agents:token | print the Watchfire API token (derived from APP_KEY) for other API clients |
agents:runs <name> | an agent’s latest runs from the database (--limit N, default 20) |
schedule:list | the scheduled tasks with their next run |
schedule:run | run the scheduled tasks due this minute once (for system cron) |
help | list every command, the app’s own included |
An app adds its own in app/commands/, registered in app/commands/mod.rs and wired with
.commands(app::commands::register):
use smeltery::console::{Args, Command, Commands};
use smeltery::{App, Result};
pub struct Greet;
impl Command for Greet {
fn name(&self) -> &'static str {
"greet"
}
fn about(&self) -> &'static str {
"Say hello"
}
async fn run(&self, app: &App, args: Args) -> Result<()> {
println!("Hello, {}!", args.get(0).unwrap_or("world"));
Ok(())
}
}
pub fn register(c: &mut Commands) {
c.add(Greet);
// smeltery:commands
}Args gives positional words with args.get(0), flags with args.flag("force") and values with
args.value("step") (--step 2 or --step=2). An option followed by a word that does not start with - takes it
as its value, so flags go after positional words (greet Ada --loud). A built-in command’s name always runs the
built-in.
§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.
§CSRF
On web routes, every request whose method is not GET, HEAD, OPTIONS or TRACE (POST, PUT, PATCH,
DELETE, and any other method a Router::any route answers) must carry the session’s token in a _token field
(URL-encoded or multipart form) or an X-CSRF-TOKEN header. A multipart body is read only up to its _token field
(at most BODY_LIMIT bytes; @csrf comes first in a form), and the rest streams on to the handler. @csrf in a Mold form writes the field.
@csrf, csrf_token() and the Sparks csrf-token meta tag show the token masked with a fresh random pad in every
response (session.csrf_token()), so the page’s bytes never repeat it and a compressed HTTPS page cannot leak it
(BREACH); every masked form verifies, and so does the unmasked session.token(). Never put session.token() in a
page or response: render csrf_token() (or session.csrf_token()? in Rust) instead. A missing or
wrong token answers 419 “Page Expired” ({"error": "CSRF token mismatch"} for JSON clients). API routes are not
checked. Under APP_ENV=testing the check is off; TestApp::new(build).with_csrf() turns it on for a test.
Signing in and signing out give the session a new token, so a token from before is refused (a form left open in
another tab answers 419 once).
§Validation
#[derive(Validate)] puts rules on a form struct, and the Valid<T> extractor reads, checks and hands it over:
use serde::Deserialize;
use smeltery::prelude::*;
#[derive(Deserialize, Validate)]
pub struct RegisterForm {
#[validate(required, max = 255)]
pub name: String,
#[validate(required, email, unique(table = "users", column = "email"))]
pub email: String,
#[validate(required, min = 8, confirmed)]
pub password: String,
pub password_confirmation: String,
#[validate(integer, between(1, 120))]
pub age: Option<i64>,
}
async fn store(session: Session, Valid(form): Valid<RegisterForm>) -> Redirect {
session.flash("status", format!("Welcome, {}!", form.name));
Redirect::to("/")
}| Rule | Passes when | Message |
|---|---|---|
required | present and not blank | The name field is required. |
email | an e-mail address | The email field must be a valid email address. |
url | an http/https URL | The site field must be a valid URL. |
min = n, max = n, between(a, b) | text: characters; numbers: the value; lists: items; uploaded files: kilobytes | The password field must be at least 8 characters. / The name field must not be greater than 255 characters. |
mimes = "png,jpg" | an uploaded file whose name has one of the extensions | The image field must be a file of type: png, jpg. |
numeric, integer | a number / a whole number | The age field must be an integer. |
alpha, alpha_num, alpha_dash | letters / letters and digits / also - and _ | The code field must only contain letters. |
in_list("a", "b") | one of the values | The selected color is invalid. |
confirmed | equals <field>_confirmation | The password field confirmation does not match. |
same = "other" | equals field other | The email field must match other. |
accepted | yes, on, 1, true | The terms field must be accepted. |
unique(table = "users", column = "email") | no row has the value | The email has already been taken. |
exists(table = "users", column = "id") | a row has the value | The selected manager id is invalid. |
message = "…" replaces the messages of that field. unique(…, except_id) ignores the row whose id is the route’s
last path parameter (an edit form); except_id = "field" takes the id from a field of the struct. unique and
exists query the app’s database. In messages, _ in a field name becomes a space.
Valid<T> reads a URL-encoded or multipart form, or JSON when the request’s content type is JSON. Fields holding an empty string
are dropped before deserializing, so an empty input is absent: an Option field is None, and every rule except
required skips an absent field. When the input does not deserialize at all, the messages of the required,
email, url, numeric and integer rules are reported for every field at once.
File uploads. A form with enctype="multipart/form-data" reaches the same Valid<T>. A file field is an
Option<UploadedFile> (smeltery::http::UploadedFile); text fields deserialize as in a URL-encoded form:
use serde::Deserialize;
use smeltery::http::UploadedFile;
use smeltery::prelude::*;
#[derive(Deserialize, Validate)]
pub struct PhotoForm {
#[validate(required, max = 255)]
pub title: String,
#[validate(required, max = 2048, mimes = "png,jpg")]
pub image: Option<UploadedFile>,
}
async fn store(Valid(form): Valid<PhotoForm>) -> Result<Redirect> {
if let Some(image) = &form.image {
let path = image.store("public/photos").await?; // "public/photos/<random>.png"
}
Ok(Redirect::to("/photos"))
}On a file, required passes when a file was sent (a file input left empty is absent), min, max and between
count kilobytes, and mimes = "png,jpg" checks the file name’s extension (jpg and jpeg are one). Each file
streams to a temp file in storage/framework/uploads/, which is deleted when the UploadedFile is dropped unless it
was stored. Before any rule runs, the first bytes are checked against the declared type and the extension: PNG,
JPEG, GIF, WebP and PDF content must be declared and named as that type, and a file declared or named as one of them
must contain it; otherwise the field fails with “The image field must be a file whose content matches its type.”. A
multipart request may be UPLOAD_MAX_BYTES (default 10 MB) in all; a larger one fails validation on the field being
read (“must not be greater than … kilobytes”), and its text fields together stay within BODY_LIMIT (413 past it).
The whole body, boundaries and part headers included, may be at most 1 MB more than UPLOAD_MAX_BYTES, and hold at
most 1000 parts (413 past either).
name() is the browser’s file name without directories and with unsafe characters replaced, size() is in bytes,
mime() is the type read from the content (else the declared one), and bytes() reads the file. store(dir) moves
it to storage/app/<dir>/<40 random characters>.<extension> and returns that path relative to storage/app. The
extension follows the content for PNG, JPEG, GIF, WebP and PDF files (a photo.exe holding a PNG is stored as
.png), else it is the name’s own when that is on the list of safe extensions, in lower case: images (png, jpg,
jpeg, gif, webp, avif, bmp, ico, tif, tiff, heic, heif …, not svg), audio (mp3, wav, ogg,
m4a, flac …), video (mp4, webm, mov …), pdf, txt, csv, tsv, rtf, office documents (docx,
xlsx, pptx, odt …) and archives (zip, gz, 7z …). Every other extension (html, svg, xml, xsd,
js, an unknown one) is stored as .bin. smeltery::http::is_safe_extension(ext) tells whether an extension is on
the list and stored_extension(ext) gives the one store uses. mimes checks the name
only, so an image field lists its types in mimes, and the content check above covers those five types.
store_as(dir, name) picks the name itself. dir starts with public (served at /storage/… after
smeltery storage:link) or private, and every segment of dir and the name uses only [A-Za-z0-9._-] (no .,
.. or leading dot in the name). A file field in a URL-encoded or JSON body is invalid. Failed validation flashes
the text fields as old input, never the files.
When validation fails, JSON clients (an Accept or Content-Type of JSON) get 422
{"message": "The given data was invalid.", "errors": {"email": ["…"]}}. On web routes other requests are
redirected back (303 to the Referer when it is on this site, else /) with the errors and the input flashed;
fields that look like secrets are not flashed: names holding password, passwd, passphrase, passcode,
secret, token, apikey, privatekey, accesskey, cardnumber, creditcard, securitycode, twofactor or
recoverycode once everything but letters and digits is left out (private_key, privateKey and private-key all
count), names with one of the words key, pin, otp, totp, mfa, 2fa, tfa, auth, card, cvv, cvc,
cvv2, iban, ssn, answer or recovery (words split at anything but letters and digits and at camelCase, so
mfaCode and security_answer count; letter case ignored), and the fields named with
AppBuilder::dont_flash(&["nickname"]). A value over 16 KB is not flashed, nor more than 100 fields or 64 KB
in all. The next page shows them with @error("email") {{ message }} @enderror and
old("email"). A handler can fail the same way with Err(Error::validation("email", "…")).
ValidationErrors maps fields to messages: first(field), get(field), has(field), is_empty(), and it
serializes as {"field": ["message"]}.
§Flash messages
session.flash("status", "Post saved.") followed by a redirect shows the message on the next page only:
@if(session("status"))
<p class="status">{{ session("status") }}</p>
@endifBack is the previous page as a handler argument: back.redirect() answers 303 to the Referer when it is on this
site, otherwise to /.
§Authentication
The user model implements smeltery::auth::Authenticatable, and bootstrap/app.rs registers it with
.auth::<User>():
impl smeltery::auth::Authenticatable for Model {
fn auth_id(&self) -> i64 { self.id }
fn password_hash(&self) -> &str { &self.password }
fn remember_token(&self) -> Option<&str> { self.remember_token.as_deref() }
// Optional: a nullable `credentials_epoch` column lets `auth::end_credentials` end open sessions.
fn credentials_epoch(&self) -> Option<i64> { self.credentials_epoch }
}Users are found by id and by their email column; remember-me tokens are stored in remember_token. An address is
compared trimmed and with its ASCII letters in lowercase (smeltery::auth::normalize_email), and a row counts only
when its stored address equals the typed one apart from ASCII letter case, so a database collation that also folds
accents (MySQL’s and MariaDB’s defaults) never matches a look-alike address. Handlers on web routes take Auth:
| Call | Does |
|---|---|
auth.check(), auth.id() | whether someone is signed in, and who |
auth.user::<User>().await? | the signed-in user (loaded once per request) |
auth.attempt(email, password, remember).await? | true and signed in when the password matches and the login policies allow it (validate + app.check_login + login); it never asks a second factor, so with a login completion registered (below) it refuses with an error, like login |
auth.validate(email, password).await? | the user (AuthUser) when the password matches, without signing in; the same budgets as attempt |
auth.login(&user, remember).await? | sign in a user (a new session id and CSRF token); an error while a login completion is registered (sign in through app.login_completion(), whose code uses auth.login_user(&user, remember); AuthUser::of(&user) wraps a model) |
auth.logout().await? | sign out this session: it is invalidated (the database and file drivers delete it), the remember-me cookie removed and the user’s remember token replaced with a new random one, so no remember-me cookie of the user signs in any more; other devices stay signed in |
auth::cycle_remember_token(&app, user_id).await? | replace the user’s remember token with a random one (only its SHA-256 stored): no remember-me cookie of the user signs in any more; sessions stay |
auth.logout_other_devices(password).await? | sign out every other session of the user: password (the current one) is hashed again with a fresh salt, and the remember token is replaced, so no remember-me cookie signs a device in again; false and nothing changes when it is wrong. It counts against confirm_password’s five tries a minute |
auth.set_password(new).await? | store a new password for the signed-in user and keep this session signed in: every other session ends, the remember token is replaced; false for a guest. Check the current password first |
auth.confirm_password(password).await? | true when the signed-in user’s password matches, and the session remembers the time; five tries a minute per user, then 429 / a redirect back with the message on password |
auth.password_confirmed_within(duration) | whether this session confirmed the password within duration |
auth.intended(default) | a 303 to the page the auth middleware turned the visitor away from, else to default; the remembered page is forgotten |
auth.set_intended(path) | remember a page for intended: false (nothing remembered) unless path is a path on this site of at most 2048 bytes |
With remember, a remember-me cookie (remember_<session cookie>, encrypted, five years) holds the user id and a
random 60-character token whose SHA-256 is stored in users.remember_token; a request without a signed-in session
but with a valid cookie is signed in from it.
A signed-in session is bound to the user’s password hash. When it changes (a
password change or reset, logout_other_devices), every session made before is signed out on its next request, a
copied session cookie included. The check reads the user’s row on each request of a signed-in user. With
SESSION_DRIVER=cookie nothing is stored on the server, so a copy of a session cookie made before logout stays
valid until the session expires (SESSION_LIFETIME idle, SESSION_ABSOLUTE_LIFETIME at most); with database or
file the logout deletes the session, which is why new apps use the database driver.
Every attempt counts before the account is looked up and the password checked, so parallel requests get no extra
tries: thirty a minute from one client whatever the address (auth.ip(), the client address after
TRUSTED_PROXIES; an IPv6 client by its /64), five a minute for one address from one client, and twenty per five
minutes for one address from one network (an IPv4 /24, an IPv6 /48). Addresses with and without an account count
alike, so the limit tells nothing about which addresses are registered, and guesses from other networks never lock
the account’s owner out. A successful sign-in resets the address’s counts and gives its attempt back to the client’s.
Past a limit attempt returns an error that JSON clients get as 429 and web forms as a redirect back with “Too many
login attempts. Please try again in N seconds.” on email. The counts live in the process’s memory, in fixed
windows that start with the first attempt.
The auth middleware sends guests to the route named login (or /login) with a 303, and answers 401 to JSON
clients. The guest middleware sends signed-in users to AUTH_HOME.
Before that redirect, the auth middleware remembers the page in the session when the request is a GET page visit:
not from a JSON client, not a background fetch / XHR, not a subresource (an image, script, stylesheet or frame,
told apart by the browser’s Sec-Fetch-Mode and Sec-Fetch-Dest headers), not a prefetch and not an event stream;
Inertia visits count. It stores the path and query, never the host, at most 2048 bytes. Signing in keeps it,
signing out drops it. A login handler answers with auth.intended(…) after a successful attempt, so the user
lands on the page they asked for:
use serde::Deserialize;
use smeltery::prelude::*;
#[derive(Deserialize)]
struct LoginForm {
email: String,
password: String,
}
async fn login(app: App, auth: Auth, Form(form): Form<LoginForm>) -> Result<Redirect> {
if auth.attempt(&form.email, &form.password, false).await? {
return Ok(auth.intended(&app.settings().auth_home));
}
Ok(Redirect::to("/login"))
}intended only redirects to a path on this site: one that starts with a single / and holds only visible ASCII
characters other than \ (browsers read //host, /\host and /<tab>/host as another host). Anything else in the
session gives default.
smeltery::auth::hash_password(password) hashes with argon2id (default parameters) and verify_password(password, hash) checks one, both on a blocking thread. At most HASH_CONCURRENCY (default: the number of CPUs) hashes and
checks run at once in the process and up to HASH_QUEUE (64) more wait; further ones fail at once with 503, so a
flood of sign-ins, registrations or resets cannot exhaust the memory.
auth::verify_credentials(&app, client_ip, email, password).await? is the check behind validate and attempt for
code without a session (issuing an API token): the same three budgets (shared with attempt), the same dummy-hash
timing for unknown addresses, Some(AuthUser) on a match. auth::find_by_email::<User>(&app, email).await? finds a
user the way they do. #[serde(deserialize_with = "smeltery::auth::deserialize_email")] on a form’s email field
reads it trimmed and in lower case. auth::model_column::<User>("email") is a column of the model by name, and
app.auth_model() the TypeId of the model registered with .auth::<User>().
Password changes: sessions, remember-me cookies and other credentials bound to the password hash end when it
changes. auth.set_password(new) keeps the current session; app code that writes password itself calls
auth::password_changed(&app, user_id, except).await? afterwards (except: the principal of the request, whose
credential stays), which replaces the remember token. A password reset, logout_other_devices, set_password and
password_changed then run the app’s credential listeners (AppBuilder::credential_listener, a
smeltery::auth::CredentialListener told the user id, why (CredentialChange::{Reset, Changed, OtherDevicesLoggedOut, Ended}), the credential that stays, and for a reset whether it verified a previously unverified
address (was_unverified)), before the request answers. Every listener runs and the event below is published even
when one fails; then the first error fails the request, the password stays changed. password_changed refuses an
except principal of another user. Keep a credential only after checking the current password. Each also
publishes one smeltery::auth::AuthEvent on the
PubSub topic auth (auth::EVENTS_TOPIC): RevokedAll { user_id, kind, except } (as JSON {"type":"revoked_all",…}), and a logout publishes Revoked { user_id, key } for the session
it ended (key as principal.key() names it). auth::publish_event(&app, &event) publishes one. Delivery is at
most once, as every PubSub message.
Password confirmation: the password.confirm middleware (registered by .auth::<User>(), put it after auth)
lets a session through that confirmed its password with auth.confirm_password(password) within
AUTH_PASSWORD_TIMEOUT seconds (default 10800). Otherwise JSON clients and API routes get 423 {"message": "Password confirmation required."}, and a page visit is remembered (as auth does) and sent to the route named
password.confirm (or /user/confirm-password) with a 303. Every sign-in and sign-out removes the confirmation
with the other session keys a sign-in owns (names starting with _auth. or _temper.).
Second factor: AppBuilder::second_factor(f) registers a smeltery::auth::SecondFactor (required(app, user),
verify(app, user, code)); app.second_factor() returns it. verify answers a SecondFactorVerdict: Valid,
Invalid, or TooManyAttempts { retry_after } when the account’s code budget is spent (the code is then not
checked). verdict.into_result("code", message)? turns it into the endpoint’s answer: Ok(()), 422 with message
on code, or 429 with Retry-After and “Too many attempts. Please try again in N seconds.” on code.
Login policy: AppBuilder::login_policy(p) adds a smeltery::auth::LoginPolicy, a rule without a session that
every new sign-in meets: check(app, user) answers LoginDecision::Allow or LoginDecision::refuse(status, message) (a suspended account, an IP rule). app.check_login(&user).await? asks every policy in the order they
were added (none: allowed); the first refusal is an error with the policy’s status and its message on email (JSON
clients get the status, browsers are sent back with the message). auth.attempt, Temper’s login, its two-factor
challenge and registration, and Hallmark’s token endpoint ask it after the password and before the second factor.
A remember-me cookie meets it too: a refused restore stays a guest, the cookie is removed and the user’s remember
token replaced. Policies gate new sign-ins, token issuance and remember-me restores only: refusing a user does not
end an open session, issued API tokens or open sockets; auth::end_credentials (below) ends them.
Ending a user’s credentials: auth::end_credentials(&app, user_id).await? signs a user out everywhere without
a password change (a suspension, together with a login policy that refuses them): it adds one to the user’s
credentials_epoch, so every open web session of the user is signed out on its next request; it replaces the
remember token, runs the credential listeners with CredentialChange::Ended (Hallmark deletes every token of the
user) and publishes RevokedAll { kind: Every, except: None } (Anvil closes the user’s sockets). The epoch is a
nullable integer column credentials_epoch on the users table (t.big_integer("credentials_epoch").nullable())
that the model returns from Authenticatable::credentials_epoch (Option<i64>; default None). Sessions are bound
to the password hash and the epoch; sign-ins and sign-outs never change the epoch, so they never end other
sessions. A model without the column keeps working (None binds sessions as before); end_credentials then still
ends the remember token, tokens and sockets, and returns an error because open sessions stay signed in. A step
that fails never skips the others: the listeners run and the event goes out, then the first error is returned. It
does not change the password: whoever holds it (or a pending two-factor login) can sign in again unless a login
policy refuses the user.
Login completion: AppBuilder::login_completion(c) registers a smeltery::auth::LoginCompletion:
complete(app, auth, session, headers, user, remember) finishes signing in a known user (an AuthUser) and returns
the response; app.login_completion() returns it, so code that proves a user another way calls it instead of
auth.login_user(&user, remember) (Auth::login without the model type).
Password resets: auth::passwords::send_reset_link(&app, email) finds the account as attempt does, stores a
token for that account in password_reset_tokens (user_id, the token’s SHA-256, created_at; one row per
account, replaced by each new link) and sends the link APP_URL + the route named password.reset (its {token}
filled in, else /reset-password/{token}) + ?email=… to the address stored on the account, never to the typed
one. It returns Some(user id) when a link was issued and None otherwise, for the caller’s records (the answer
to the visitor stays the same either way). At most
one link a minute goes to one address (further requests in that minute do nothing), an address without an account
does nothing, and the mail leaves in the background (under APP_ENV=testing before the call returns), so neither the
answer nor its timing tells whether an account exists; a failed delivery is logged, not returned. The link goes out
with mail installed (.mail()) as the ResetPassword mail
(smeltery::mail::ResetPassword, its template part of the framework). Without mail, the link goes to the log at
info level in local development (APP_ENV local or testing and an APP_URL on this machine: localhost,
*.localhost or a loopback address); anywhere else only a warning that no mail is set up is logged, never the link.
auth::passwords::reset(&app, email, token, new_password) finds the account the same way, through the user model, and, when the token matches and is less than
60 minutes old, uses the token up (one conditional delete: of two requests with one token one wins), sets the new
password on that row by its id and clears its remember token; the new password hash signs out every session of the
user. With .verify_email::<User>() the address is marked verified when the link was mailed to the address the
account has now (a link proves control of the address it reached; the last 16 characters of a mailed token name
that address). A token from passwords::create_token verifies nothing. It returns the user’s id
(Ok(Some(id))), Ok(None) for an unknown address or a wrong, used or expired token, then runs the credential
listeners and publishes RevokedAll (above). On MySQL and MariaDB a users.email column with a binary collation
(utf8mb4_bin) also makes the database itself compare addresses byte for byte.
Email verification: a user model whose email must be verified implements smeltery::auth::MustVerifyEmail
and has a nullable email_verified_at column; bootstrap/app.rs adds .verify_email::<User>() after
.auth::<User>():
impl smeltery::auth::MustVerifyEmail for User {
fn email(&self) -> &str { &self.email }
fn email_verified_at(&self) -> Option<DateTimeUtc> { self.email_verified_at }
}
fn build(app: smeltery::AppBuilder) -> smeltery::AppBuilder {
app.auth::<User>().verify_email::<User>()
}An existing users table gets the column with smeltery make:migration add_email_verified_at_to_users_table, its
column line changed to t.datetime("email_verified_at").nullable();.
The verified middleware (put it after auth) sends guests, and users whose email_verified_at is empty, to the
route named verification.notice (or /email/verify) with a 303 and answers 403 {"error": "Your email address is not verified."} to JSON clients. Without .verify_email::<User>() it lets every signed-in user through; guests
never pass.
| Call | Does |
|---|---|
auth.send_verification_email().await? | reads the signed-in user’s row again and issues their link to the mailer: true when a link was issued; false (nothing issued) for a guest, a verified user, or without .verify_email |
auth.resend_verification_email().await? | the same, six calls a minute per user (counted atomically); then 429 for JSON clients, a redirect back with “Too many verification emails. Please try again in N seconds.” on email for forms |
auth.has_verified_email().await? | for a signed-in user: true when their email is verified, or without .verify_email; false for a guest |
EmailVerificationRequest (handler argument) | the checked link; request.fulfill().await? sets email_verified_at (and updated_at when the model has it) to now: true the first time, false when it was set already |
auth::verification::verification_url(&app, &user), send_verification_link(&app, &user).await? | the link of any user, and sending it |
app.verifies_email() | whether the app requires verified addresses (.verify_email::<User>()) |
auth::mark_verified(&app, user_id).await?, auth::mark_unverified(&app, user_id).await? | set email_verified_at to now (unless set) or empty it (after the address changed), through the user model: true when it changed; an error without .verify_email |
A link is APP_URL followed by the route named verification.verify (/email/verify/{id}/{hash}) and
?expires=…&signature=…. hash is the SHA-256 of the user’s email and signature an HMAC-SHA256 of the id, the
hash and the expiry time under a key derived from APP_KEY; the expiry time is fixed in the link when it is made,
AUTH_VERIFICATION_EXPIRE minutes later (default 60, at least 1). EmailVerificationRequest needs a signed-in user
(put the route behind auth: a link opened while signed out leads to the login, and a login handler that answers
with auth.intended(…) brings the user back to the link) and answers 403 “This verification link is invalid or
has expired.” unless the signature is valid, the expiry time has not passed, the id is the signed-in user’s and the
hash matches their current email: a link stops working when the email changes. With .verify_email, a route named verification.verify
without both {id} and {hash} stops the build with an error. A handler that changes a user’s email sets
email_verified_at to None in the same update and then calls auth.send_verification_email(), which sends the
link to the new address. The link is sent like a reset link: with mail installed as the VerifyEmail mail
(smeltery::mail::VerifyEmail, its template part of the framework); without mail it goes to the log in local
development only (as above).
A web app declares the three routes:
use smeltery::auth::EmailVerificationRequest;
use smeltery::prelude::*;
async fn notice(app: App, auth: Auth) -> Result<Response> {
if auth.has_verified_email().await? {
return Ok(Redirect::to(&app.settings().auth_home).into_response());
}
Ok("Check your inbox for the verification link.".into_response())
}
async fn verify(app: App, session: Session, request: EmailVerificationRequest) -> Result<Redirect> {
request.fulfill().await?;
session.flash("status", "Your email address is verified.");
Ok(Redirect::to(&app.settings().auth_home))
}
async fn send(auth: Auth, session: Session, back: Back) -> Result<Redirect> {
auth.resend_verification_email().await?;
session.flash("status", "verification-link-sent");
Ok(back.redirect())
}
fn routes(r: &mut Router) {
r.get("/email/verify", notice).name("verification.notice").middleware("auth");
r.get("/email/verify/{id}/{hash}", verify)
.name("verification.verify")
.middleware("auth");
r.post("/email/verification-notification", send)
.name("verification.send")
.middleware("auth");
}The register handler calls auth.send_verification_email().await? after auth.login(&user, false).await?.
§Temper: the authentication routes
Temper (smeltery::temper) puts the flows above behind routes: login, logout, registration, password reset,
e-mail verification, password confirmation and profile and password updates, each feature switched on in one
builder. The app keeps the pages (TemperViews: one closure per page returning any response, such as a
#[derive(Mold)] struct or an Alloy page), the actions (traits with a typed, validated Input:
CreatesNewUsers, ResetsUserPasswords, UpdatesUserPasswords, UpdatesUserProfileInformation) and, where it
wants, its own answers (TemperResponses). Every check runs through the core functions of this section.
use serde::Deserialize;
use smeltery::http::Html;
use smeltery::temper::{PasswordInput, ResetsUserPasswords, Temper, TemperExt as _, TemperViews};
use smeltery::Validate;
/// The reset form: the app's password rules.
#[derive(Deserialize, Validate)]
pub struct ResetForm {
#[validate(required, email)]
#[serde(deserialize_with = "smeltery::auth::deserialize_email")]
pub email: String,
#[validate(required, min = 8, confirmed)]
pub password: String,
pub password_confirmation: Option<String>,
}
impl PasswordInput for ResetForm {
fn email(&self) -> &str { &self.email }
fn password(&self) -> &str { &self.password }
}
pub struct ResetUserPassword;
impl ResetsUserPasswords<User> for ResetUserPassword {
type Input = ResetForm;
}
fn build(app: smeltery::AppBuilder) -> smeltery::AppBuilder {
app.temper(
Temper::<User>::new()
.reset_passwords(ResetUserPassword)
.email_verification()
.views(
TemperViews::new()
.login(|_| Html("<h1>Log in</h1>"))
.forgot_password(|_| Html("<h1>Forgot your password?</h1>"))
.reset_password(|ctx| Html(format!("<h1>New password</h1><p>{} chars</p>", ctx.token().len())))
.verify_email(|_| Html("<h1>Check your inbox</h1>"))
.confirm_password(|_| Html("<h1>Confirm your password</h1>")),
),
)
}.temper(…) registers User as the user model (.auth::<User>(); call .auth with no other model), the web
routes below and its login pipeline as the login completion (app.login_completion()), and never flashes a field
named code as old input. The app stops at boot when a page route has
no view (the error names the TemperViews method), when without_route names an unknown route, when the prefix is
invalid, or when .auth::<…>() registers another model.
| Route | Name | Middleware | Feature |
|---|---|---|---|
GET / POST /login | login, login.store | guest; throttle:30,1 on POST | always |
POST /logout | logout | auth | always |
GET / POST /register | register, register.store | guest; throttle:6,1 on POST | registration |
GET / POST /forgot-password | password.request, password.email | guest; throttle:6,1 on POST | reset_passwords |
GET / POST /reset-password/{token} | password.reset, password.update | guest; throttle:6,1 on POST | reset_passwords |
GET /email/verify | verification.notice | auth | email_verification |
GET /email/verify/{id}/{hash} | verification.verify | auth, throttle:6,1 | email_verification |
POST /email/verification-notification | verification.send | auth (six a minute per user) | email_verification |
PUT /user/profile-information | user-profile-information.update | auth, password.confirm, throttle:6,1 | update_profile_information |
PUT /user/password | user-password.update | auth, throttle:6,1 | update_passwords |
GET / POST /user/confirm-password | password.confirm, password.confirm.store | auth; throttle:6,1 on POST | always |
GET /user/confirmed-password-status | password.confirmation | auth | always |
GET / POST /two-factor-challenge | two-factor.login, two-factor.login.store | guest; throttle:30,1 on POST | two_factor |
POST / DELETE /user/two-factor-authentication, POST /user/confirmed-two-factor-authentication, GET /user/two-factor-qr-code, GET /user/two-factor-secret-key, GET / POST /user/two-factor-recovery-codes | two-factor.enable, two-factor.disable, two-factor.confirm, two-factor.qr-code, two-factor.secret-key, two-factor.recovery-codes, two-factor.regenerate-recovery-codes | auth, password.confirm (with confirm_password(false) only for a confirmed enrolment); throttle:6,1 on POST and DELETE | two_factor |
A login checks the password with auth.validate (the login budgets above), then runs the login pipeline: the app’s
login policies (app.check_login, see Authentication; .login_policy(|app, user| …) adds one
typed on the user model), the app’s steps (Temper::login_pipeline), the sign-in (auth.login_user; Temper is the app’s login completion), the Login event and the answer (the remembered page, else
AUTH_HOME; JSON clients get 200 {"two_factor": false}). A wrong address or password answers “These credentials
do not match our records.” on email: the login page for browsers and Inertia visits, 422 for JSON clients. A
password update checks current_password through auth.confirm_password (five tries a minute per user) and stores
the new one with auth.set_password, so this device stays signed in and every other session ends. A profile update
that changes the address empties email_verified_at through auth::mark_unverified when the app requires verified
addresses, and sends a link to the new address. JSON clients (Accept: application/json) get status codes and JSON
bodies throughout; .views(false) registers no page routes (browser requests then get redirects to pages that do
not exist). The reset page’s ctx.token() and ctx.email() come from the link as sent: render them escaped. Other options: .home(path), .prefix("/auth"), .routes(false), .without_route(name),
.limits(Limits::new().login("30,1").forms("6,1")), .listen(f) for TemperEvents (user ids only; listeners
never change the answer). smeltery::temper::login_pipeline(&ctx, &user, remember) signs a user in through the same
pipeline from another sign-in path. Pipeline steps gate new sign-ins only: an open session or a remember-me restore
never meets them, so locking an account out also ends its credentials (auth::end_credentials). Steps run for web
sign-ins only; a rule that must also hold for API tokens and remember-me cookies (a suspended account) is a login
policy. Registration asks the login policies after creating the account: a refusal (an account that awaits
approval) keeps the account, fires Registered, signs nobody in and answers the refusal. When the action returns a
user that has two-factor authentication (an existing account), the request fails with 500 and nobody is signed in.
A refusal at the two-factor challenge answers JSON clients with the message on code and sends browsers to the
login page with it on email. .two_factor(TwoFactor::new()) (a user model implementing TwoFactorAuthenticatable over the columns
two_factor_secret, two_factor_recovery_codes, two_factor_confirmed_at, two_factor_last_step) adds codes from
an authenticator app (RFC 6238 TOTP) and single-use recovery codes: a correct password then gives a pending login (a
new session id; five minutes; bound to the password hash; ended after five wrong codes) and the challenge page (JSON
clients: 200 {"two_factor": true}) instead of a sign-in. Secrets are encrypted with
App::encrypt("temper.two-factor", <user id>, …), recovery codes stored as SHA-256 hashes and shown once; a code is
accepted once (one conditional UPDATE of the last accepted time step), a recovery code removed by compare-and-set;
every code counts against the account’s budget (five per five minutes, one hundred a day, shared by processes through
the cache) before it is checked; past it the challenge answers 429 with Retry-After (browsers: the message on the
challenge page). The login policies are asked again before a code is checked. The QR code is an SVG data URI for an <img>. Turning two-factor on (confirmed) or
off replaces the remember token. It also registers core’s SecondFactor, removes an enrolment when a reset verifies
a previously unverified address, and adds temper:two-factor-disable <email> --force. A new APP_KEY makes stored
secrets unreadable: app codes are refused (two-factor stays on), recovery codes still work.
The crate’s README (smeltery-temper) has the full reference.
§Guards and the principal
Who made a request is its principal (smeltery::auth::Principal): the user’s id (user_id), the guard that proved
it (guard), the credential (credential: Credential::Session { binding } for a signed-in session,
Credential::Token { id, abilities } for a token a guard issued) and when that credential stops working
(expires_at, None for sessions). A guard (smeltery::auth::Guard) reads a request’s head and answers with the
principal it proves, or None. .auth::<User>() registers the guard web: the signed-in session, whose principal
the session stack stores on every web request of a signed-in user. AppBuilder::guard(g) registers another; two
guards with one name, a name other than lowercase ASCII letters, digits, _ and -, or a guard named web, stop
the app at boot. A guard returns a new principal for every request. A guard that reads only headers (a bearer
token) says so with stateless(): stateless guards never run on web routes, so a bearer credential never stands in
for the session and its CSRF check there.
| Call | Does |
|---|---|
.middleware("auth:web") | the plain auth middleware |
.middleware("auth:<g1>,<g2>") | runs the guards in order and stores the first principal found; without one, an API route whose list names a stateless guard answers 401 {"error":"Unauthenticated."} with WWW-Authenticate: Bearer and Cache-Control: no-store, and every other route what auth answers (on web routes the session is the only credential). An unknown guard name stops the app at boot |
Authenticated (handler argument) | the principal (it derefs to Principal): the one the session stack or an auth: alias stored, else on API routes the first a stateless guard finds; 401 without one. Option<Authenticated> gives None instead |
principal.user::<User>(&app).await? / principal.auth_user(&app).await? | the principal’s user (loaded once per principal), typed or as an AuthUser |
principal.can("orders:read") | sessions hold every ability; a token the abilities it lists, by exact name, or all with * |
principal.key() | <guard>:session:<binding> or <guard>:token:<id> (web:session:3f…, hallmark:token:12): the name of the credential in grants and revocation events, unique across guards |
auth::authenticate(&app, &mut parts, GuardSet::Stateless).await? | the first principal of the stateless guards for a request head, stored nowhere; None on web requests |
principal.with_user(user)? | the principal with its user already loaded (a guard that read it), an error for another user’s id |
session.binding() | 24 hex characters naming the session (the first 12 bytes of the SHA-256 of its CSRF secret): the <binding> of web:session:<binding> |
auth::credential_key(guard, kind, id) | the key format of principal.key() (<guard>:<kind>:<id>), for code that names credentials it revokes |
Guard::first_party(app, parts) | a guard’s answer to “does this API request come from the app’s own pages?” (default false); when a listed guard says yes, the auth: alias runs the whole web session stack around the request (smeltery::session::run_web_stack: session, remember-me, password-hash binding, the CSRF check on every state-changing method), lets a signed-in session through and otherwise runs the guards inside it |
auth::unauthenticated_bearer() | the response of a bearer endpoint without a valid credential: 401 {"error":"Unauthenticated."}, WWW-Authenticate: Bearer, Cache-Control: no-store (what auth: answers on API routes) |
app.has_stateless_guard() | whether a stateless guard is registered |
app.find_user(id).await? | the user with that id as an AuthUser: id(), downcast::<User>(), binding(purpose) |
auth.auth_user().await? | the signed-in user of a web request as an AuthUser |
AuthUser::binding(purpose) is the SHA-256 of smeltery-<purpose>|<password hash> (purpose: lowercase ASCII
letters, digits, ., _, -, else an error): a credential that stores it when issued and compares it on use
stops working after any password change. Signed-in sessions are bound this way
with the purpose session. The throttle: and verified middleware read the principal, so put auth:<guards>
before them on a route. verified checks the principal’s user (session or token) and answers 403 {"error": "Your email address is not verified."} on API routes and to JSON clients, and 401 when a guard’s principal has no user
row any more.
use smeltery::auth::{Authenticated, Credential, Guard, Principal};
use smeltery::http::request::Parts;
use smeltery::prelude::*;
use smeltery::BoxFuture;
/// Accepts `X-Demo-User: <id>` (a stand-in for a real token check).
struct DemoGuard;
impl Guard for DemoGuard {
fn name(&self) -> &'static str { "demo" }
fn stateless(&self) -> bool { true }
fn authenticate<'a>(&'a self, _app: &'a App, parts: &'a mut Parts)
-> BoxFuture<'a, Result<Option<Principal>>> {
Box::pin(async move {
let id = parts.headers.get("x-demo-user")
.and_then(|v| v.to_str().ok())
.and_then(|v| v.parse::<i64>().ok());
Ok(id.map(|id| Principal::new(id, "demo", Credential::token(0, ["orders:read"]))))
})
}
}
async fn orders(who: Authenticated) -> Result<String> {
if !who.can("orders:read") {
return Err(Error::http(smeltery::http::StatusCode::FORBIDDEN, "Forbidden"));
}
Ok(format!("orders of user {}", who.user_id))
}
fn build(app: AppBuilder) -> AppBuilder {
app.guard(DemoGuard).api_routes(|r| {
r.get("/orders", orders).middleware("auth:demo").middleware("throttle:60,1");
})
}§API tokens
Hallmark (smeltery::hallmark) gives an app personal access tokens: API clients, mobile and desktop apps,
command-line tools and other backends send Authorization: Bearer smt_… to API routes, and each token carries a
list of abilities.
use smeltery::auth::Authenticated;
use smeltery::hallmark::{CurrentToken, Hallmark, HallmarkExt as _, HasApiTokens as _};
use smeltery::http::{HeaderValue, StatusCode, header};
use smeltery::prelude::*;
/// `POST /api/tokens/cli`: a signed-in API client issues a second token for a command-line tool.
async fn issue(who: Authenticated, app: App) -> Result<Response> {
let user: User = who.user(&app).await?.ok_or_else(Error::unauthorized)?;
let new = user.create_token(&app, "cli", &["deploy"]).await?;
let mut res = Json(new.to_json()).into_response();
res.headers_mut()
.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
Ok(res)
}
async fn orders(who: Authenticated) -> String {
format!("the orders of user {}", who.user_id)
}
async fn sign_out(token: CurrentToken) -> Result<StatusCode> {
token.revoke().await?;
Ok(StatusCode::NO_CONTENT)
}
fn build(app: AppBuilder) -> AppBuilder {
app.auth::<User>()
.hallmark(Hallmark::new())
.api_routes(|r| {
r.post("/tokens/cli", issue)
.middleware("auth:hallmark")
.middleware("abilities:tokens:create");
r.get("/orders", orders)
.middleware("auth:hallmark")
.middleware("abilities:orders:read");
r.delete("/tokens/current", sign_out).middleware("auth:hallmark");
})
}A route that issues tokens to a token holder checks an ability (abilities:tokens:create above): without it any
token, even one that may do nothing, could issue itself a new one with more abilities.
.hallmark(Hallmark::new()) (after .auth::<User>(); without a user model the app stops at boot) registers the
guard hallmark, the middleware families abilities: and ability:, the Tokens service, a credential listener
and the console command hallmark:prune-expired. The table comes from a migration that calls
smeltery::hallmark::migrations::up(schema) / down(schema); serve logs an error when the table is missing.
| Call | Does |
|---|---|
Tokens::of(&app)? / tokens: Tokens (handler argument) | the token service |
tokens.create(user_id, "Ada's phone", &["orders:read"], None).await? | a new token (NewToken): plain_text() is the token, shown once and never stored; token() its stored data; to_json() the answer {"token":"smt_…","token_type":"Bearer","expires_at":…,"abilities":[…]}. Some(time) sets an earlier expiry |
user.create_token(&app, name, abilities) / user.tokens(&app) / user.revoke_tokens(&app) | the same on any user model (HasApiTokens) |
tokens.list(user_id).await? | the user’s tokens (AccessToken: id, user_id, name, abilities, last_used_at, expires_at, created_at), newest first; never a token or its hash |
tokens.find(user_id, id) / tokens.revoke(user_id, id) | one token of that user: ids from a request reach only that user’s tokens |
tokens.revoke_all(user_id) / tokens.revoke_all_except(user_id, keep_id) | delete the user’s tokens (all, or all but one); the number deleted |
tokens.prune_expired(Duration) / hallmark:prune-expired [--hours=24] | delete tokens expired at least that long ago, 500 rows per statement |
.middleware("auth:hallmark") | the request needs a valid token (on API routes) |
.middleware("abilities:a,b") / .middleware("ability:a,b") | the principal needs every listed ability / at least one; 403 {"error":"Forbidden."}, 401 without a principal. Put auth:hallmark first |
CurrentToken (handler argument) | the token of this request (id(), name(), abilities(), can(), expires_at(), revoke()); 401 when a token did not authenticate the request, None as Option<CurrentToken> |
- Tokens are
smt_followed by 64 lowercase hex characters (32 random bytes). The table stores only their SHA-256;PlainTokenhas noDisplayand noSerialize, and itsDebugprintsPlainToken(smt_…). - The guard reads one
Authorization: Bearer <token>header (the scheme in any letter case), never a query string, cookie, body or other header. A malformed token is refused before any database work; a found row is compared again in constant time. Missing, malformed, unknown, expired and revoked tokens get the same 401{"error":"Unauthenticated."}withWWW-Authenticate: BearerandCache-Control: no-store, and requests the guard looked at answer withVary: Authorization, Cookie. Web routes (routes/web.rs) never accept a bearer token: they keep the session and its CSRF check. - Guesses: one client (its address after
TRUSTED_PROXIES, an IPv6 client by its /64) may sendHALLMARK_GUESS_LIMITinvalid tokens a minute (malformed, unknown, expired and revoked ones alike). Past that, a bearer request from that address gets 429 withRetry-Afteruntil the minute ends, before any lookup, unless this process accepted its token in the last five minutes: clients sharing the address (a carrier or office network) keep working with the tokens they use. The count lives in the app’s cache store and is shared by the app’s processes (each bearer request reads it once); a cache error answers 500. Requests that reach the app without any connection information (only outside its server) are not counted. WithoutTRUSTED_PROXIESbehind a proxy every client is the proxy’s address and shares one budget. - Expiry: a new token expires after
HALLMARK_TOKEN_EXPIRATIONdays (an explicit later time is shortened to that), and every request also refuses a token older than that, so lowering the setting shortens existing tokens. An expired token is deleted when it is next presented;hallmark:prune-expireddeletes the rest. - Passwords: a token is bound to its user’s password hash. A password written by any code ends the user’s tokens
at their next use; a password reset,
Auth::logout_other_devices,Auth::set_passwordandauth::password_changeddelete them at once (password_changedkeeps the token of the request that called it). Deleting the user deletes the tokens (foreign key). - Abilities are exact names (1 to 100 of
A-Z a-z 0-9 : . _ -) or*alone (every ability), at most 64 per token; there are no patterns (orders:*is refused). A token created with&[]may do nothing; a stored list that breaks these rules grants nothing (logged as an error with the token id). A signed-in session holds every ability: abilities limit tokens, not users, so handlers still check that the user may touch a record. - Limits: a user holds at most
HALLMARK_MAX_TOKENS_PER_USERtokens; creating one more deletes the least recently used, in the same transaction.last_used_atis written at most once a minute per token, in the background with a 2 s timeout. - Events:
revoke,CurrentToken::revoke, a token deleted when presented and a token deleted by the cap publishAuthEvent::Revoked { key: "hallmark:token:<id>" };revoke_all/revoke_all_exceptpublishAuthEvent::RevokedAll { kind: Tokens }on the PubSub topicauth(see PubSub).
Clients without a browser session (mobile and desktop apps, command-line tools) get their token for an email and password:
use serde::Deserialize;
use smeltery::hallmark::{issue_for_credentials, revoke_current};
use smeltery::http::ClientInfo;
use smeltery::prelude::*;
#[derive(Deserialize)]
struct TokenRequest {
email: String,
password: String,
device_name: String,
code: Option<String>,
}
async fn store(app: App, client: ClientInfo, Json(form): Json<TokenRequest>) -> Result<Response> {
let issued = issue_for_credentials(
&app, &client, &form.email, &form.password, &form.device_name, form.code.as_deref(), &["*"],
)
.await?;
Ok(issued.created())
}
fn routes(r: &mut smeltery::routing::Router) {
r.post("/tokens", store).middleware("throttle:10,1");
r.delete("/tokens/current", revoke_current).middleware("auth:hallmark");
}issue_for_credentialschecks the address and password with core’sauth::verify_credentials: the login budgets (shared with the web login form), the same work for unknown addresses, the password-hash gate. A wrong address or password answers 422 with “These credentials do not match our records.” onemail; past a budget 429; adevice_namethat is empty, longer than 255 characters or holds control characters 422 ondevice_name.- The app’s login policies (
AppBuilder::login_policy, such as refusing a suspended account) decide next, as at the web sign-in: a refusal answers the policy’s status with its message onemail, and no token is created. - When a second factor is registered (
AppBuilder::second_factor) and the user needs one,codemust be valid before any token exists: 422 “A two-factor code is required.” or “The two-factor code is invalid.” oncode; past the second factor’s own attempt budget, 429 withRetry-After. issued.created()answers 201{"token":"smt_…","token_type":"Bearer","expires_at":…,"abilities":[…]}withCache-Control: no-store.revoke_currentdeletes the token of the request and answers 204.
.env | Builder | Default |
|---|---|---|
HALLMARK_TOKEN_EXPIRATION (days; 0 = never) | .expiration(Duration) | 365 |
HALLMARK_MAX_TOKENS_PER_USER | .max_tokens_per_user(n) | 100 |
HALLMARK_GUESS_LIMIT (invalid tokens per client a minute) | .guess_limit(n) | 60 |
HALLMARK_SPA (true / false) | .spa() | false |
HALLMARK_STATEFUL (first-party origins besides APP_URL’s) | .stateful(&[...]) | empty |
In tests, smeltery::hallmark::testing::acting_as(&app, &user, &["orders:read"]) creates a real token and sends it
with every following request; token_for(&app, &user, &["*"]) returns one without changing the app’s headers.
§SPA authentication
A JavaScript frontend served from the app’s own origin (from public/, or through a proxy or a Vite dev server
under the same origin) can call auth:hallmark API routes with the session cookie instead of a token:
use smeltery::hallmark::{Hallmark, HallmarkExt as _};
fn build(app: smeltery::AppBuilder) -> smeltery::AppBuilder {
app.hallmark(Hallmark::new().spa().stateful(&["http://localhost:5173"]))
}.spa()(orHALLMARK_SPA=true) turns it on. A request on anauth:hallmarkAPI route is first-party when it carriesSec-Fetch-Site: same-origin(a page ofAPP_URL’s origin); orSec-Fetch-Site: same-site/cross-sitewith oneOriginlisted with.stateful(...)/HALLMARK_STATEFUL(comma-separatedscheme://host[:port]; scheme, host and port compared exactly); or, from a browser that sends noSec-Fetch-Site, oneOrigin(else theReferer’s origin) equal toAPP_URL’s origin or a listed one. An unlisted sibling subdomain or port,Sec-Fetch-Site: none, anullor foreignOrigin, and requests without any of these headers (an app or server calling with a token) are not first-party. A*,nullor a URL with a path inHALLMARK_STATEFULstops the app at boot.- A listed origin is a page of the same site on another origin, such as the Vite dev server above on another port
of
localhost: it calls the API withfetch(url, { credentials: "include" })(the session cookie isSameSite=Lax, so it is sent only to the same site). Smeltery sends no CORS headers, so such a page reads the answers only when the app adds them; a proxy that serves the page and the app under one origin needs neither. - List only origins you control: any script on a listed origin acts with the signed-in user’s session. A
development origin such as
http://localhost:5173belongs in the development.envonly, never in production. - A first-party request runs the web session stack: the session cookie, remember-me, the password binding, and the
CSRF check of web routes on every method except GET, HEAD, OPTIONS and TRACE (419 without a valid
X-XSRF-TOKEN,X-CSRF-TOKENor_token). A signed-in session passes (its principal is thewebguard’s, with every ability); without one, a bearer token in the request is still checked. The CSRF check comes first, so a first-party page that sends a token instead still needsX-XSRF-TOKENon state-changing calls (419 without it), and when a first-party request carries both a signed-in session and a token, the session decides who it is. Every other request is bearer-only: the session cookie is not read. GET /hallmark/csrf-cookie(routehallmark.csrf-cookie) answers 204 and sets theXSRF-TOKENcookie, which SPA mode turns on for every web response. The SPA reads it, signs in through the app’s login route, and sends the cookie’s value asX-XSRF-TOKENon state-changing API calls. Session cookies keep their__Host-prefix under https, so a frontend on another subdomain or site uses tokens.
§Search
Prospect (smeltery::prospect) is full-text search for models. A model declares which columns are searched (with
weights), filtered and sorted; a search returns a Page of hits that hold real models, ranked by relevance, with
highlights. The database driver uses the database’s own full-text search: SQLite FTS5, PostgreSQL tsvector with a
GIN index, MySQL / MariaDB FULLTEXT. The database keeps the index current itself (triggers, a generated column, the
FULLTEXT index), so every write is searchable at once, raw SQL and bulk updates included, and no extra server runs.
§Making a model searchable
impl Searchable next to the model’s entity, register the model in bootstrap/app.rs, and add the index with a
migration:
use smeltery::db::prelude::*;
use smeltery::prospect::{IndexSpec, Searchable, Weight};
#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "posts")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: i64,
pub title: String,
pub body: String,
pub user_id: i64,
pub team_id: i64,
pub published: bool,
pub created_at: Option<DateTimeUtc>,
}
impl ActiveModelBehavior for ActiveModel {}
impl Searchable for Model {
fn index(i: &mut IndexSpec) {
i.text("title").weight(Weight::A); // searched, ranked highest
i.text("body"); // Weight::B
i.filter("user_id"); // where_eq / where_in / where_not_in / where_between on it
i.sort("created_at"); // order_by on it (relevance is the default order)
i.only_when("published"); // rows with false are not found
i.scoped_by("team_id"); // every search names a team
}
}
use smeltery::prelude::*;
pub fn build(app: AppBuilder) -> AppBuilder {
app.prospect(|p| {
p.model::<Post>();
})
}IndexSpec call | Means |
|---|---|
i.text(column), .weight(Weight::A) | a searched string column; weights A (highest) to D, default B; the order of the calls is the order of the index’s columns |
i.filter(column) | an integer, bool, string or date-time column searches may filter on |
i.sort(column) | a column searches may order by |
i.only_when(column) | a bool column: rows where it is false are not found |
i.scoped_by(column) | every search must call within(value), or across_scopes() explicitly; the column is also a filter column |
i.language(Language::English) | English stemming on SQLite and PostgreSQL (forging finds forge); the default Language::Simple compares words as they are |
i.name(name) | the memory engine’s index name (default: the table’s); the database index is always <table>_search |
The spec is checked when the app builds: every name must be a column of the model, text columns strings,
only_when a bool, at least one text, and the model needs one integer primary key (t.id()). A mistake, a model
registered twice or an unknown PROSPECT_DRIVER stops the build with the table and the column.
The migration names the same text columns, weights and language:
use smeltery::db::migration::{Migration, Schema};
use smeltery::prospect::migration::{Language, SearchIndex, Weight};
use smeltery::Result;
pub struct CreatePostsTable;
impl Migration for CreatePostsTable {
fn name(&self) -> &'static str {
"2026_10_05_120000_create_posts_table"
}
async fn up(&self, schema: &Schema) -> Result<()> {
schema
.create("posts", |t| {
t.id();
t.string("title");
t.text("body");
t.big_integer("user_id");
t.big_integer("team_id");
t.boolean("published").default(false);
t.timestamps();
})
.await?;
SearchIndex::on("posts")
.text("title", Weight::A)
.text("body", Weight::B)
.language(Language::Simple)
.create(schema)
.await
}
async fn down(&self, schema: &Schema) -> Result<()> {
SearchIndex::on("posts").drop(schema).await?;
schema.drop_if_exists("posts").await
}
}| Backend | SearchIndex::create writes | drop removes |
|---|---|---|
| SQLite | the FTS5 table posts_search (external content over posts, keyed by id), the triggers posts_search_ai, _ad, _au that keep it current, and a rebuild that indexes the rows already there | the triggers and the table |
| PostgreSQL | the stored generated column search_vector (tsvector, weighted) and the GIN index posts_search_index | the index and the column |
| MySQL / MariaDB | the FULLTEXT index posts_search over the text columns | the index |
SearchIndex::on("posts").rebuild(schema) drops and creates it again, for a migration that changes the columns,
weights or language. .key("post_id") names the integer key column when the model’s primary key is not id. Adding the generated column on PostgreSQL
rewrites the table, and the first FULLTEXT index of a MySQL table rebuilds it: run such a migration while the table
is small or during maintenance. The first search of a model checks its index: on SQLite the FTS5 table’s text
columns in order, its table and key (content, content_rowid) and the three triggers; on PostgreSQL the columns,
weights and language of the search_vector expression (read from information_schema, so the app’s database user
owns the table) and its GIN index; on MySQL the FULLTEXT index’s columns in
order. A missing or different index is logged once (ERROR) and every search of that model answers a 500 whose
message names the migration to write; serve logs it at start, and prospect:status shows it.
§Searching
use smeltery::prelude::*;
use smeltery::prospect::{Direction, Hit, Prospect};
#[derive(serde::Deserialize)]
struct SearchForm {
#[serde(default)]
q: String,
}
async fn index(prospect: Prospect, Query(s): Query<SearchForm>, page: PageQuery) -> Result<Json<Page<Hit<Post>>>> {
let team_id = 1; // from the signed-in user
let posts = Post::search(&prospect, &s.q)
.within(team_id) // the scope: required because of scoped_by
.where_eq("user_id", 7) // declared filter columns only
.order_by_relevance() // the default; or .order_by("created_at", Direction::Desc)
.highlight(["title", "body"])
.paginate(page) // ?page=&per_page=, bounded
.await?;
Ok(Json(posts))
}
pub fn routes(r: &mut Router) {
r.get("/posts", index).middleware("throttle:60,1");
}Post::search(&prospect, text) starts a search (smeltery::prelude brings the Searchable trait into scope). The
builder:
| Call | Means |
|---|---|
within(value) / across_scopes() | the scope value, or every scope (explicitly) |
where_eq(column, value), where_in(column, values), where_not_in(column, values), where_between(column, low, high) | conditions on filter columns; values of the column’s type (i64 and smaller integers, bool, strings, DateTimeUtc); where_in and where_not_in take at most 100 values |
order_by(column, Direction::Asc / Desc), order_by_relevance() | a sort column, or relevance (the default); ties by key, newest first |
highlight(columns) | highlights of at most 4 text columns |
query(|select| select.filter(…)) | a SeaORM refinement of the same SQL statement (“published or mine”); database driver only |
paginate(page) | a Page<Hit<M>>: one page and the total (two statements) |
get(limit), keys(limit), count() | the first hits, their keys, the number of matches |
An undeclared column, a value of the wrong type, a bound passed, or a scoped model searched without within /
across_scopes makes the call that runs the search return an error (a 500) before any query;
ProspectError::of(&error) reads which.
The search text. User text is never search syntax. It is trimmed and cut at PROSPECT_MAX_QUERY_LENGTH
characters (200), split into terms on everything that is not a letter or a digit, lower-cased, and at most 16 terms are
kept. Every term must match; the last one also matches as a prefix when it has two characters or more (forg finds
forge), so a search-as-you-type box works. Quotes, *, :, -, parentheses and words like AND, OR, NOT,
NEAR are plain text. A text without terms (empty, or punctuation only) has no text condition: the filtered rows come
newest key first, so an index page with an empty search box keeps working.
Results. A Hit<Post> derefs to the post (hit.title) and has score (Option<f64>, higher is better, None
without terms; scores compare the hits of one search) and highlights. It serializes as the model’s fields plus
_score and _highlights, so an Alloy page reads it directly. A highlight is a list of text segments,
{"text": …, "matched": true / false} (Segment), never HTML; render each one escaped and wrap the matched ones.
A Mold template reads struct fields, which release builds compile to Rust field access, so the handler hands it the
segments in a field (hit.highlights.get("title").map(|h| h.segments().to_vec()).unwrap_or_default(), a
Vec<Segment>, next to the record from hit.into_model()), and the template loops over them (the empty comment
keeps @endfor from touching the word before it):
@for(row in posts.items)
<h2>@for(s in row.title)@if(s.matched)<mark>{{ s.text }}</mark>@else{{ s.text }}@endif{{-- --}}@endfor</h2>
@endforIn React and Vue, render segments as text nodes inside <mark>. A column of at most 2,000 characters comes back whole
with every match marked; above that it is a snippet around the matches (SQLite: 32 tokens; PostgreSQL: two fragments
of 10 to 30 words from the first 20,000 characters). The memory engine and MySQL highlight the first 20,000
characters in Rust and show a window of about 30 words around the first match of a text longer than 60 words, with
… around it. Characters U+E000 and U+E001 never appear in a highlight.
Pages. paginate takes a PageQuery (see Pagination); per_page is at most
PROSPECT_MAX_PER_PAGE (100), and get takes a limit of 1 to that value. A search ranks and counts every matching
row, so its cost grows with the number of matches: on large tables keep a throttle: on search routes.
§Drivers
| SQLite | PostgreSQL | MySQL / MariaDB | |
|---|---|---|---|
| Index | FTS5 table + triggers | generated tsvector + GIN | FULLTEXT |
| Ranking | bm25 with column weights 10 / 5 / 2 / 1 | ts_rank_cd with weights A-D | MATCH … AGAINST relevance, no column weights |
| Stemming | Language::English (porter) | Language::English (english) | none |
| Left out of a search | nothing | nothing | words shorter than the server’s innodb_ft_min_token_size (read once; 3 when it cannot be read) and InnoDB’s default stopwords (prospect::MYSQL_STOPWORDS: the, a, for, with …); a text with no other word searches like an empty one. The default list is assumed: a server with its own innodb_ft_server_stopword_table or innodb_ft_enable_stopword=OFF differs (a required custom stopword finds nothing) |
| Highlights | FTS5 highlight / snippet | ts_headline, on the page’s rows only | in Rust |
PROSPECT_DRIVER=memory is an in-process engine for tests: documents hold the declared columns only and are written
by model events (Record writes; see Model events), searched with the same text rules, and every hit
is loaded from the database with the scope, only_when and filters applied again in SQL, so a stale document never
shows a record the database would not return. It does not take query(…), and its string filter values are letters,
digits and _ . : @ - only (1 to 128 characters).
§Settings and commands
.env | Default | Meaning |
|---|---|---|
PROSPECT_DRIVER | database | database or memory; anything else stops the build |
PROSPECT_MAX_QUERY_LENGTH | 200 | characters of search text used (1 to 1,000) |
PROSPECT_MAX_PER_PAGE | 100 | the largest page or get limit (1 to 1,000) |
PROSPECT_BATCH | 500 | rows per chunk when Prospect::import fills the memory engine (1 to 10,000) |
Values out of range are clamped with a warning. app.prospect_with(ProspectSettings::from_env().max_per_page(50), …)
sets them in code.
| Command | Does |
|---|---|
smeltery prospect:status | the driver; per searchable model its rows, text columns and whether its index is there |
smeltery prospect:import [table…] | SQLite: rebuild the FTS5 index from the table; PostgreSQL / MySQL keep theirs current (nothing to do) |
smeltery prospect:flush table | remove a model’s documents from the memory engine (refused by the database driver: its index follows the table) |
In code: prospect.import::<Post>(), prospect.sync::<Post>(keys) (for writes outside Record with the memory
engine), prospect.flush::<Post>(), and prospect.paused(async { … }), which runs a block with model listeners
switched off.
The search text is never logged; at DEBUG a search logs its table and the number of terms and filters.
§Testing search
With the database driver, searches work in tests on in-memory SQLite (TestApp) like in the app: FTS5 is part of
the bundled SQLite. prospect::testing::fake(&app) switches a TestApp to the memory engine and records what is
indexed:
use smeltery::db::prelude::*;
use smeltery::prospect::{ProspectExt as _, testing};
use smeltery::testing::TestApp;
fn drafts_are_not_indexed() {
let app = TestApp::new(|b| b.prospect(|p| { p.model::<Post>(); }));
let fake = testing::fake(&app);
let db = app.db();
let draft = app
.block_on(Post::create(&db, post::ActiveModel {
title: Set("Draft".into()),
published: Set(false),
..Default::default()
}))
.unwrap();
fake.assert_not_indexed::<Post>(draft.id);
fake.assert_synced_times::<Post>(1);
}§Sparks: live components
Sparks (smeltery::sparks) are interactive components written in Rust and Mold, with no JavaScript to write. A
Spark is a struct (its state) with #[derive(Spark)], a view in resources/views/sparks/<name>.mold.html, and
actions in an #[actions] impl block. The page renders it on the server; the client runtime (sparks.js, served
by the app at /_sparks/sparks.js) sends clicks and input to the server, which runs the action, re-renders the
view and answers the new HTML, which the runtime morphs into the page.
use smeltery::prelude::*;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Default, Spark)]
#[spark(name = "counter")] // view: resources/views/sparks/counter.mold.html
pub struct Counter {
pub count: i64, // server-only: the page cannot set it
#[spark(model)]
pub step: i64, // wire:model may set it
}
#[actions]
impl Counter {
/// Runs on the first render, with the props of `@spark("counter", { start: 5 })`.
pub async fn mount(&mut self, ctx: &mut SparkCtx) -> Result<()> {
self.count = ctx.prop("start").unwrap_or(0);
self.step = 1;
Ok(())
}
pub async fn increment(&mut self) -> Result<()> {
self.count += self.step;
Ok(())
}
pub async fn add(&mut self, ctx: &mut SparkCtx, n: i64) -> Result<()> {
self.count += n;
ctx.dispatch("counted", json!({ "count": self.count }));
Ok(())
}
#[guard(auth)] // only for a signed-in user
pub async fn reset(&mut self) -> Result<()> {
self.count = 0;
Ok(())
}
}{{-- resources/views/sparks/counter.mold.html --}}
<div>
<p>Count: {{ count }}</p>
<input type="number" wire:model.live="step">
<button wire:click="increment">+{{ step }}</button>
<button wire:click="add(10)">+10</button>
<span wire:loading>Saving…</span>
</div>A page shows it with @spark("counter", { start: 5 }) and loads the runtime once with @sparksScripts (in the
layout’s <head>; it also writes the CSRF meta tag). app/sparks/mod.rs registers the components and
bootstrap/app.rs wires them with .sparks(app::sparks::register) (the trait is smeltery::sparks::SparksExt, in
the prelude):
// app/sparks/mod.rs
pub mod counter;
pub fn register(s: &mut smeltery::sparks::Sparks) {
s.add::<counter::Counter>();
// smeltery:sparks
}#[spark(...)] takes name (default: the struct name in snake case), view (default sparks/<name>) and
stream (see below). Props whose name is a field set that field before mount; every prop is readable with
ctx.prop("name"). The view renders like any Mold view: from the template files with hot reload in debug builds,
compiled into the binary in release builds.
Actions are the pub async fn methods of the #[actions] block that take &mut self; nothing else can be
called from the page. After &mut self an action may take ctx: &mut SparkCtx, then parameters deserialized from
the call (wire:click="add(10)", remove('a')). #[guard(auth)] requires a signed-in user (#[guard(guest)]
the opposite). Three hooks (and can_stream for streamed components, below):
async fn mount(&mut self, ctx: &mut SparkCtx),
async fn updated(&mut self, ctx: &mut SparkCtx, field: &str) (after a wire:model update) and
async fn rendering(&mut self, ctx: &mut SparkCtx) (before every render, $refresh included: load fresh data).
| In the view | Does |
|---|---|
wire:click="action", wire:click="action(1, 'a')", .prevent | calls the action on click |
wire:submit="save" | calls on form submit (the browser’s submit is prevented) |
wire:keydown.enter="save" | calls on that key (enter, escape, tab, space, arrows, letters) |
wire:model="field" | binds an input to a #[spark(model)] field; sent with the next action |
wire:model.live, .debounce.300ms, .blur, .change | sends after typing pauses (150 ms, or the given time), on blur, on change |
wire:loading, .remove, .class="…", .attr="disabled", .flex, .block | shown / hidden / classes / attribute while a request runs |
wire:target="save,step" | limits wire:loading to those actions and fields |
wire:poll.5s="action" | calls the action (or re-renders) every interval while the tab is visible |
wire:key="…" | keeps list items matched across re-renders |
wire:click="$refresh" | re-renders without an action |
Inputs bound with wire:model show the component’s state; text from inputs is converted to the field’s type
("3" → 3, a checkbox → bool), and a value that does not fit shows “The step field is invalid.” through
@error("step"). A value for a #[spark(model)] field is text, a number, a boolean, null or a list of those,
never an object, and it never sets a struct (a list that serde would read as one is refused too), so the page
cannot fill a struct field with keys the view does not show; null clears an optional one. A struct field takes
the keys listed in #[spark(model(fields = "title, body"))], one at a time (wire:model="form.title", or
$spark.$set('form', { title: 'Hi' }) with listed keys only); any other key is refused (403).
When a re-render adds elements with autofocus (which browsers ignore on elements added after the page loaded),
the runtime focuses the first of them once, after filling its wire:model value, unless focus is on an element
outside that Spark (a field or button of another Spark, a link in the page).
SparkCtx gives actions app(), db(), auth(), user_id(), session(), prop(name), redirect(url)
(the browser goes there: a path on this site such as /posts/3, or an address on APP_URL), redirect_away(url)
(another site, an http:// or https:// URL; any other target given to either fails the update with 500 and a
log line, so a URL from data never runs script), dispatch(event, payload) (a CustomEvent on window, the payload as its detail),
flash(key, value) and validate(self). With #[derive(Validate)] on the component, ctx.validate(self).await?
checks its rules; on failure the component re-renders with the messages, which @error("field") inside its view
shows.
Nesting: a component’s view may use @spark("item", { key: post.id, … }). Each child keeps its own state and
updates on its own; when the parent re-renders, existing children (matched by key, or by position) stay as they
are, new keys mount new children, and children left out disappear.
Uploads: a field #[spark(upload(max = 2048, mimes = "png,jpg"))] pub photo: Option<TemporaryUpload> (max in
kilobytes, mimes as file extensions) bound with <input type="file" wire:model="photo"> receives the file as
soon as it is chosen. The file waits in storage/framework/sparks/; a file that is too large or of another
type shows its message through @error("photo"). photo.store(ctx, "public/avatars").await? moves it to
storage/app/public/avatars/<random>.png and returns public/avatars/<random>.png
(store_as(ctx, dir, name) picks the name). Only public/… and private/… directories are accepted; files under
storage/app/public are served at /storage/… after smeltery storage:link. Temp files are deleted 24 hours
after the upload (by a later upload request). mimes checks the extension of the file’s name, not its content.
store keeps the name’s extension only when it is on the list of safe extensions that UploadedFile::store uses
(smeltery::http::is_safe_extension); any other is stored as .bin.
One session may send 30 uploads and 100 MiB per 10 minutes (s.upload_quota(files, bytes, per) in
app/sparks/mod.rs), and one client address 120 uploads and 400 MiB in the same window
(s.upload_address_quota(files, bytes); the address is ClientInfo::ip, which honours TRUSTED_PROXIES); past
either an upload answers 429 without reading the file.
#[validate(...)] rules work on upload fields too (with #[derive(Validate)] and ctx.validate(self)): required
passes once a file is chosen, min, max and between count kilobytes, and mimes = "png,jpg" checks the name’s
extension.
Push from the server: a component declared with #[spark(stream)] listens on GET /_sparks/stream (one
connection per page). Broadcast (a handler argument, or app.service::<Broadcast>()) sends to it by component
name or instance id: refresh() makes the page re-fetch the component, emit(event, payload) fires a browser
event. A page subscribes with the stream token each render of the component carries (wire:stream="…", valid for
the snapshot time to live); the hook async fn can_stream(&mut self, ctx: &mut SparkCtx) -> Result<bool> in the
#[actions] block decides per render whether the visitor gets one (default: yes), so a visitor it refuses cannot
subscribe. A token is bound to the session and the signed-in user of the render: the stream accepts it only with
that session’s cookie, and ends when that session signs out (logout, logout_other_devices, a password change or
reset, end_credentials, in any process of the app) and when the tokens expire. After a sign-out the page does not
open it again; otherwise it opens it again with the tokens of its latest render, after 5 seconds, doubling with each
failure in a row up to 5 minutes. One client address (an IPv6 client by its /64) may open 60 streams a minute
(s.stream_opens_per_minute(n), counted in process memory); past that a stream answers 429. Visitors behind one NAT
or proxy address share that budget, one stream per page load: raise it for such audiences. The stream carries refresh signals (the page then sends an ordinary update with its own session and
snapshot) and emit payloads, which every page subscribed to that name or id receives, so a payload never holds
private data. A process keeps at most 1000 streams open (s.max_streams(n)); past that a stream answers 503 and the
page retries. emit refuses event names starting with anvil: (it sends nothing and returns 0): they belong to
listeners (below). refresh() and emit() deliver to the pages connected to the sending process at once and return
how many those are; they also hand the message to the app’s PubSub, which
carries it to the pages held by the app’s other processes, so an agent in a work process reaches the pages of a
serve --no-agents process. That hand-over never blocks the caller: it goes through a queue of 1024 messages, and
a message the queue or the driver cannot take is dropped, counted and logged; delivery to other processes is at most
once. A Watchfire agent can drive a live counter:
use smeltery::sparks::Broadcast;
use smeltery::watchfire::prelude::*;
pub fn register(w: &mut Watchfire) {
w.every(5.secs(), "live-counter", |ctx| async move {
if let Some(broadcast) = ctx.service::<Broadcast>() {
broadcast.to("counter").refresh();
}
Ok(())
});
}Listening to broadcasts: with Anvil installed, a #[spark(stream)] component reacts to
broadcast events without any JavaScript: a method of its #[actions] block marked
#[on("anvil:<channel>", "<event>")] runs when that event is broadcast on that channel, by any process of the app.
use smeltery::prelude::*;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Default, Spark)]
#[spark(name = "order-status", stream)]
pub struct OrderStatus {
pub order_id: i64,
pub status: String,
}
/// The event's data.
#[derive(Deserialize)]
pub struct Shipped {
pub tracking: String,
}
#[actions]
impl OrderStatus {
#[on("anvil:private-orders.{order_id}", "App\\Events\\OrderShipped")]
pub async fn shipped(&mut self, ctx: &mut SparkCtx, event: Shipped) -> Result<()> {
self.status = format!("Shipped: {}", event.tracking);
ctx.dispatch("order-shipped", smeltery::json!({ "id": self.order_id }));
Ok(())
}
}- The channel is the full name (
private-…,presence-…or a public name);{order_id}is the value of that state field when the component renders (a string or an integer of letters, digits and_ - = @ , ;). The event name is the name the event is sent with:App\Events\OrderShippedfor#[derive(BroadcastEvent)] struct OrderShipped(see Events). - Each render asks the app’s channel rules (
routes/channels.rs, the same callbacks asPOST /broadcasting/auth, with the visitor’s session) whether this visitor may receive each channel; the stream asks again when it opens. Only allowed channels reach the page. An event sent with.except(socket)reaches listeners too. - The page receives the event through its Sparks stream, as a message signed for that component instance, and sends
it back with an ordinary update request; the method then runs with the event’s data deserialized into its last
argument (400 when it does not fit), with the visitor’s session and a fresh snapshot, like an action. Before
anything of the request runs, the server checks the signature, that the message is at most 60 seconds old, that a
listener takes that event on that channel, and asks the channel rules again for the visitor (403 otherwise). At
the listener’s turn, after the request’s other updates and calls (the page sends pending
wire:modelvalues with it), the channel is resolved from the state as it is then: when the state names another channel, nothing runs. Each message runs once, whatever snapshot of the component it comes with: the app’s cache remembers it for 60 seconds (with a shared cache store, across the app’s processes), and a cache failure refuses it (503). A message that did not run because an earlier call of the same request failed validation can be sent again. - A listener is not an action: the page cannot call it by name. It may take
&mut SparkCtxand one more argument (the data), and takes no#[guard]. A method may carry several#[on]; a component at most 16. - The browser also gets the window event
anvil:<event>with the data (detail), once per listening component, for Alpine code that only shows something. It comes from the page itself and any script on the page can fire one: act on events in the listener, on the server. - Delivery is at most once: an event broadcast while the page’s stream is reconnecting does not reach the listener (the page refreshes its components after a reconnect). Event data over 64 KiB is not sent to listeners.
- Without Anvil installed, on a component without
stream, with a{field}the struct does not have, or withCACHE_STORE=null(listeners need a cache store that keeps values), the app does not start.
Alpine.js: Alpine attributes (x-data, x-show, @click, …) work in Mold views as they are; where an event
name is also a Mold directive, write the long form (x-on:error). A server value inside Alpine code goes through
the json filter, never between quotes: x-data="{ name: {{ name | json }} }", @click="pick({{ id | json }})"
(see Mold templates); inside a Spark, $spark reads the state without any echo. With Alpine.js 3.13 or newer loaded after
@sparksScripts (both scripts defer), Alpine code inside a Spark reaches that Spark as $spark:
{{-- resources/views/sparks/search.mold.html --}}
<div x-data="{ open: $spark.$entangle('open'), q: $spark.$entangle('query').live }">
<p>Found <span x-text="$spark.total"></span></p>
<button @click="$spark.more(10)">More</button>
<button @click="open = !open">Filters</button>
<div x-show="open">…</div>
<input x-model="q">
</div>| In Alpine code | Does |
|---|---|
$spark.total, $spark.$get('total') | reads a field; Alpine updates when a response changes it or a wire:model input of that field changes |
$spark.step = 2 | sets a field, sent with the next request (like wire:model) |
$spark.$set('step', 2) | sets a field and sends it now ($set('step', 2, false) waits for the next request) |
$spark.more(10), $spark.$call('more', 10) | calls an action with those parameters |
$spark.$refresh(), $spark.$commit() | re-renders; sends the recorded field updates |
$spark.$entangle('open') | in x-data: an Alpine property bound both ways to the field; Alpine’s changes go with the next request |
$spark.$entangle('open').live, $spark.$entangle('open', true) | the same, each change sent at once |
$spark.$id, $spark.$name, $spark.$el | the instance id, the component name, the Spark’s root element |
$spark goes through the same requests as wire:*, so it reaches only what the server allows: a field without
#[spark(model)] or a name that is not an action is refused (403) with the whole request, and a value set from
Alpine shows until the next response replaces it. $spark.<name> reads the field of that name when the state has
one; any other name calls the action of that name, except the $ helpers, the built-in object names (toString,
constructor, …), then, toJSON and names starting with __ (call those with $call). Read fields in bindings
(x-text, :class, …) and call actions from events (@click, …): a binding that calls an action
($spark.total()) sends it each time the binding re-runs, and an action called while the morph renders the bindings
is not sent (the console shows a warning). With an Alpine older than 3.13 there is no $spark, and the console says
so. When a Spark re-renders with Alpine 3.13 or newer on the page, the morph keeps Alpine’s state: x-data elements
keep their data, what Alpine renders (x-text, x-show, :class, …) is rendered from that data into the new HTML
before the diff (Alpine’s cloneNode, as in Alpine’s morph plugin), x-model inputs keep their values, and the
rows of x-for and the element of x-if stay. New elements from the server are initialised by Alpine. Elements
are matched by wire:key, id, or tag and position: give Alpine components in lists a wire:key. sparks.js
does not depend on Alpine: without Alpine on the page there is no $spark, and everything else is the same.
Security: the state travels in the page signed with a key derived from APP_KEY (HMAC-SHA256), so it cannot be
changed, but it can be read: secrets never go into component fields. The snapshot is bound to the session it was
rendered for (a hash of the session’s CSRF secret) and to the signed-in user, and is accepted for the session
lifetime after it was issued (s.snapshot_ttl(duration)); every response issues a fresh one. A snapshot copied to
another browser, kept past a logout or a sign-in, or older than that answers 419 and the page reloads. Within its
own session an older snapshot of the page can be sent again, so an action checks permission itself, with
ctx.auth() and the database, for every record it touches: a field set in mount is not proof that the user may
act on it. Updates are POST /_sparks/update and uploads POST /_sparks/upload, web routes with the session and
the CSRF check. A changed state, a CSRF mismatch or an APP_KEY that changed answers 419 too. Updating a field
without #[spark(model)], calling a method that is not an action, or an unknown component is refused (403 / 404)
and logged, and nothing runs. A request carries at most one component (s.max_components(n)) with at most 50 action calls
(s.max_calls(n)); a larger request answers 413 before anything runs. The limits are set on the registry in
app/sparks/mod.rs (s.max_calls(20); next to s.add::<…>()).
Testing: smeltery::sparks::testing::TestSpark drives a component on a page from TestApp:
let page = app.get("/counter");
let mut counter = TestSpark::from_html(&page.text(), "counter").unwrap();
counter.set("step", 2).call("increment", json!([])).send(&app);
assert!(counter.html().contains("Count: 7"));
assert_eq!(counter.data()["count"], 7);smeltery::sparks::testing::BroadcastSpy records what a Broadcast pushes: BroadcastSpy::of(app.app()), then
spy.pushes() returns the messages since the last call (target, kind, event, payload;
is_refresh_of("counter")). It listens like an open page, so it counts in what refresh() returns.
§Alloy: React and Vue
Alloy (smeltery::alloy) is the server side of the Inertia protocol, version 3. A
controller returns a page, a component name with its props, instead of a Mold view, and Inertia’s client packages
(@inertiajs/react, @inertiajs/vue3) render it in the browser. The first visit gets HTML from a Mold root template
with the page inside; every later visit (a link, a form, a reload) gets the page as JSON, and the client swaps the
component without reloading the browser page. smeltery new --frontend react and --frontend vue create apps set up
this way (see The React and Vue starter kits). Node.js builds the JavaScript only:
the server runs the Rust binary and serves the build from public/build/.
§Setup
use smeltery::alloy::{Alloy, AlloyExt as _, Props, SharedCtx};
/// The HTML of a first visit: resources/views/app.mold.html.
#[derive(smeltery::Mold, Default)]
#[mold("app")]
pub struct Root {}
/// Props every page gets.
async fn shared(ctx: SharedCtx) -> smeltery::Result<Props> {
Ok(Props::new().with("app", smeltery::json!({ "name": ctx.app().settings().name })))
}
pub fn build(app: smeltery::AppBuilder) -> smeltery::AppBuilder {
app.alloy(
Alloy::new()
.root::<Root>()
.entries(["resources/js/app.tsx"]) // what a bare @vite loads
.share(shared),
)
}The root template loads the assets with @vite and places the page with @alloy:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My App</title>
@vite
@alloyHead
</head>
<body>
@alloy
</body>
</html>@alloy renders <script data-page="app" type="application/json">…</script><div id="app"></div> (the page’s JSON
escaped, so no prop can close the script element); @alloy("root") uses another id, which the client’s
createInertiaApp({ id }) must name too. @alloyHead renders an empty string. @vite renders the configured
entries and @vite("resources/js/admin.ts", …) the named ones (see Vite). In an app without .alloy(…),
@alloy and @vite are template errors.
Alloy also has .version(f) (the asset version, below), .all_errors() (every message per field),
.encrypt_history() (see Redirects and history), .build_dir("build") (the folder under
public/ and the URL prefix of the build: letters, digits and _ . / @ -, no ..; anything else stops the app at
boot) and .hot_file(path) (the dev-server marker, storage/framework/vite.hot). .alloy(…) adds a middleware to
every web route (inside the session and CSRF stack), sets the XSRF-TOKEN cookie that Inertia’s client sends back
as the X-XSRF-TOKEN header, and names X-Inertia in the Vary header of every web response. API routes are not
touched.
§Rendering pages
use smeltery::alloy::{self, Page};
#[derive(serde::Serialize)]
pub struct Activity {
pub accounts: u64,
}
pub async fn dashboard() -> Page {
alloy::render("dashboard") // resources/js/pages/dashboard.tsx
.with("greeting", "Welcome back")
.optional("stats", || async { Ok(42) })
.defer("activity", || async { Ok(Activity { accounts: 3 }) })
}The component name is resolved by the client; in the kits it is the file under resources/js/pages/ without its
extension. In debug builds a component without a resources/js/pages/<name>.{tsx,jsx,vue,svelte} file logs a warning
once.
A typed page is a struct whose fields are the props:
#[derive(serde::Serialize, smeltery::Alloy)]
#[alloy("posts/index")]
pub struct PostsIndex {
pub titles: Vec<String>,
}
pub async fn index() -> PostsIndex {
PostsIndex { titles: vec!["Hello".into()] }
}
// `into_page()` adds lazy props to it:
use smeltery::alloy::{Component as _, Page};
pub async fn index_with_count() -> Page {
PostsIndex { titles: Vec::new() }
.into_page()
.defer("count", || async { Ok(0) })
}The struct must serialize to a JSON object; #[derive(Alloy)] refuses enums, tuple and unit structs.
| Method | Sent |
|---|---|
.with(key, value) | on full visits and on partial reloads that name it; serialized at once |
.with_lazy(key, f) | like .with, computed only when it is sent |
.optional(key, f) | only on partial reloads that name it (router.reload({ only: ['stats'] })) |
.defer(key, f), .defer_in(group, key, f) | not on the first visit; listed in the page’s deferredProps, and the client asks for it right after (<Deferred data="activity">); one request per group |
.merge(key, value), .prepend(key, value), .deep_merge(key, value), .match_on(key, "id") | like .with, and the client merges the value into the one it has (infinite lists) |
.always(key, value) | on every response, partial reloads included |
Lazy props are FnOnce closures (Send + 'static) returning a future of smeltery::Result<T>; they capture what
they need (a Db clone); the included ones run concurrently, and an error fails the request. A partial reload names
props with X-Inertia-Partial-Data / -Except (dot paths reach into values, user.name); a reload of another component gets
the full page. .status(code), .encrypt_history(bool) and .clear_history() are page options.
Every prop is public: the page is readable in the HTML of a first visit and in the JSON of every visit. Never pass models that hold secrets (password hashes, tokens), session values or the CSRF token; send a struct with the fields the page needs. A client can ask for any prop a page declares, optional and deferred ones included, so authorization belongs to the route’s middleware and the controller.
§Shared props
Alloy::share(f) adds props to every page, under the page’s own (a page prop with the same key wins); the page’s
sharedProps lists their keys. f gets a SharedCtx with app(), session(), auth(), headers(), uri() and
method(). The kits share the signed-in user through an allow-list, never the model:
use smeltery::alloy::{Props, SharedCtx};
use app::models::User;
/// The signed-in user as pages see it (`usePage().props.auth.user`).
#[derive(serde::Serialize)]
pub struct SharedUser {
pub id: i64,
pub name: String,
pub email: String,
}
pub async fn shared(ctx: SharedCtx) -> smeltery::Result<Props> {
let user = ctx.auth().user::<User>().await?.map(|u| SharedUser {
id: u.id,
name: u.name,
email: u.email,
});
Ok(Props::new()
.with("app", smeltery::json!({ "name": ctx.app().settings().name }))
.with("auth", smeltery::json!({ "user": user })))
}§Errors and flash
props.errors is on every page: the errors of the previous request’s failed validation, the first message per
field ({ "email": "The email field must be a valid email address." }; Alloy::all_errors() sends arrays), and
{} without errors. Inertia’s client posts forms as JSON (as multipart/form-data when a file is in them), and the
web stack answers an Inertia request whose Valid<T> fails, or whose handler returns
Err(Error::validation(field, message)), with a 303 back and the errors in the session; useForm shows them as
form.errors.email. With the X-Inertia-Error-Bag: login header the errors arrive as { "login": { … } }. A page
prop named errors is an error in debug builds.
The page’s flash (usePage().flash in the browser) holds every value the previous request flashed with
session.flash(key, value) whose key does not start with _, any JSON value. Flash values are public like
props: never flash secrets. Keys starting with _ (the framework’s errors, old input, the intended URL) never
reach a page.
CSRF needs nothing in the pages: the client reads the XSRF-TOKEN cookie (a masked token, new on every response, not
HttpOnly) and sends it as X-XSRF-TOKEN. When the token does not match, an Inertia request gets a 303 back with
flash.error = “The page expired. Please try again.” instead of the 419 page, and its handler does not run.
§Redirects and history
Redirect::to(url)andBackanswer303. A302answer to an InertiaPUT,PATCHorDELETEbecomes303. A redirect to a URL with a#fragmentbecomes409withX-Inertia-Redirect, and an empty200becomes a redirect back.alloy::location(url)leaves the app with a full page load (OAuth, a download, another site):409withX-Inertia-Locationfor Inertia visits,303otherwise. Pass only URLs the app chose, never user input.- An Inertia
GETof a Mold page (the Watchfire dashboard) gets409X-Inertia-Location: a full page load. X-Inertia-Locationfor the request itself and the page’surlhold the request’s path and query starting with exactly one/: leading slashes and backslashes become one/(//evil.example/xbecomes/evil.example/x), so the client never resolves them to another site.alloy::clear_history(&session)setsclearHistoryon the next page; the kits call it on logout.- The browser keeps every page’s props in its history. With
.encrypt_history()(on theAlloybuilder, or.encrypt_history(true)on a page) the client encrypts them with a key it drops onclearHistory, so the back button cannot show a signed-in page after logout. The client encrypts only in a secure context: over HTTPS, or on127.0.0.1/localhost; elsewhere it keeps the history unencrypted and logs a warning in the browser console. The kits with authentication turn it on.
§Vite
The kits build the JavaScript with Vite. Their vite.config.ts has a small smeltery() plugin:
it builds into public/build/ with public/build/manifest.json, and while the dev server runs (on
127.0.0.1:5173) it writes its URL to storage/framework/vite.hot.
- Dev server: in debug builds, while
storage/framework/vite.hotexists,@viteloads the dev server’s client and the entries from it (hot reloading). Release builds never read this file, and neither does any build underAPP_ENV=production. Only anhttp(s)URL on127.0.0.1,localhostor[::1]is used; any other content is ignored, with one warning in the log. - Build: with
public/build/manifest.json,@vitewrites the entries’ CSS links,modulepreloadlinks for the chunks they import, and their scripts, under/build/. Release builds read the manifest once; debug builds read it again when it changes. - Neither: a template error in debug builds (“No Vite assets”), nothing under
APP_ENV=testing(socargo testneeds no Node.js), and nothing in release builds, which log an error when the server starts.
smeltery serve logs where the assets come from when the server starts (console commands such as migrate do not).
The asset version is the first 32 hex characters of the SHA-256 of public/build/manifest.json, "" without one or
while the dev server runs (.version(f) sets another). An Inertia GET whose X-Inertia-Version differs gets 409 with
X-Inertia-Location before its handler runs (the flash is kept for the next request), so the browser loads the new
build after a deploy.
§Testing pages
use smeltery::alloy::testing::{AlloyAssertions as _, AlloyRequests as _};
use smeltery::alloy::{self, Alloy, AlloyExt as _, Page};
use smeltery::testing::TestApp;
async fn dashboard() -> Page {
alloy::render("dashboard")
.with("greeting", "Hello")
.defer("activity", || async { Ok(vec!["Signed in"]) })
}
let app = TestApp::new(|app| {
app.alloy(Alloy::new().root::<Root>())
.routes(|r| { r.get("/dashboard", dashboard); })
});
app.get_alloy("/dashboard")
.assert_component("dashboard")
.assert_prop("greeting", "Hello")
.assert_missing("activity")
.assert_deferred("default", &["activity"]);
let reload = app.reload_alloy("/dashboard", "dashboard", &["activity"]);
assert_eq!(reload.prop("activity.0"), Some(smeltery::json!("Signed in")));get_alloy(path) visits a page as Inertia’s client does (with the current asset version), reload_alloy(path, component, &[props]) is a partial reload, and post_alloy(path, &json) posts JSON as form.post does. On any
response, alloy_page() reads the page (the JSON of an Inertia visit or the <script data-page> of a first visit),
prop(path) reads a prop by dot path, and assert_component, assert_prop, assert_missing and assert_deferred
check it. assert_page_file_exists(component) checks that resources/js/pages/<component>.{tsx,jsx,vue,svelte}
exists.
§The React and Vue starter kits
smeltery new my-app --frontend react (or vue) writes the Rust side of a Mold app with Alloy instead of Mold pages
and Sparks:
bootstrap/app.rsinstalls.alloy(…)with the root templateresources/views/app.mold.html, the entryresources/js/app.tsx(Vue:resources/js/app.ts),.encrypt_history()(with authentication) and the shared props ofapp/providers/alloy.rs(app, andauth.userthroughSharedUser). Apps with the Watchfire building block also call.sparks(|_| {}), for the Watchfire dashboard’s live panels.resources/js/: the entry,pages/(React:welcome.tsx,dashboard.tsx,auth/login.tsx, …; Vue:Welcome.vue,Dashboard.vue,auth/Login.vue, …),layouts/(the app layout with the navigation and the flash messages, the auth layout),components/andtypes/global.d.ts(the shared props’ and the flash’s TypeScript types). The forms useuseFormand showform.errors; the welcome page loads an optional prop withrouter.reload({ only: ['forge'] }), and the dashboard shows a deferred prop with<Deferred>.package.json(exact versions: Vite 8.3.2,@inertiajs/reactor@inertiajs/vue33.8.0, React 19.3.0 or Vue 3.5.43, TypeScript 6.0.3) with the scriptsdev,buildandtypes(tsc --noEmit, Vue:vue-tsc --noEmit),tsconfig.jsonandvite.config.ts.tests/http.rstests every page with the helpers above.
The generators write pages in these apps (the kit is frontend in the app’s Cargo.toml, under
[package.metadata.smeltery]):
| Command | Writes |
|---|---|
smeltery make:model Post title:string body:text? published:bool --all (or -r) | app/controllers/posts.rs returning the pages, resources/js/pages/posts/index.tsx, create.tsx, show.tsx, edit.tsx (Vue: posts/Index.vue, Create.vue, Show.vue, Edit.vue) and resources/js/types/post.ts, besides the model, migration, factory, seeder and routes |
smeltery make:controller Reports [--resource] | a controller returning reports/index (Vue: reports/Index) and its page, or the resource pages of an existing model |
smeltery make:page About | app/controllers/about.rs, resources/js/pages/about.tsx (Vue: About.vue) and the route GET /about named about |
The forms use useForm, send number fields as numbers, post multipart/form-data when the model has a file field,
and show the messages of a failed validation under each field. make:spark refuses in these apps; make:page refuses
in Mold apps. The apps’ CLAUDE.md, AGENTS.md and Bellows guides describe Alloy pages, and the Bellows skill
alloy-page replaces spark.
Inertia’s prefetch links work with Alloy: a prefetch is an ordinary GET with Purpose: prefetch. The client
keeps a prefetched page for 30 seconds by default, so after a form changes a record, a page prefetched before can
show the old data until the cache expires. A prefetch request takes the
session’s flash like any request: when it runs between the request that flashes and the page that shows the flash,
the flash goes into the prefetched response. The kits’ pages do not prefetch.
§Broadcasting
Anvil (smeltery::anvil) is a WebSocket server inside the app that speaks the Pusher Channels protocol 7, on the
app’s own port. Handlers, jobs and Watchfire agents send events to channels; clients subscribe to channels and
receive them. pusher-js, laravel-echo and the Pusher client libraries for other platforms connect to it with a
custom host.
§Setup
bootstrap/app.rs installs it with the app’s channels:
use smeltery::anvil::{ChannelCtx, Channels};
use smeltery::prelude::*;
/// `routes/channels.rs`: the public channels and who may join the private ones.
pub fn channels(c: &mut Channels) {
c.public("news");
c.public("scores.{game}");
c.private("orders.{order}", |ctx: ChannelCtx| async move {
let order: i64 = ctx.param("order")?;
let Some(user_id) = ctx.user_id() else { return Ok(false) };
// Look the order up and allow its owner only.
let rows = ctx
.db()?
.query_with("SELECT user_id FROM orders WHERE id = ?", [order.into()])
.await?;
let owner: Option<i64> = rows.first().and_then(|row| row.try_get("", "user_id").ok());
Ok(owner == Some(user_id))
});
}
pub fn build(app: AppBuilder) -> AppBuilder {
app.anvil(channels)
}.anvil(channels) adds:
GET /app/<ANVIL_APP_KEY>: the socket endpoint, outside the web stack (no session, no cookies read). The app logs the path at start (anvil: socket endpoint);Anvil::app_key()returns the key.POST /broadcasting/auth: a web route (session and CSRF,throttle:600,1) that signs private subscriptions.POST /api/broadcasting/auth: the same for clients with a bearer token (an API route: no session, no cookie, no CSRF check;throttle:600,1); see Mobile apps and other clients. It answers 404 when the app has no stateless guard.- the
Anvilservice: a handler takesanvil: Anvil; jobs and agents useAnvil::of(&app)orctx.service::<Anvil>().
An invalid or repeated channel pattern, an invalid ANVIL_* value, or ANVIL_MAX_CONNECTIONS not below
SERVER_MAX_CONNECTIONS stops the app at boot.
§Channels
- Public channels are declared with
c.public(pattern). Anyone with the app key can subscribe to them, so their events are public. A public name that matches no declared pattern is refused (pusher:subscription_errorwith status 403). - Private channels are
private-<name>, declared withc.private(pattern, callback)(the pattern without the prefix:orders.{order}servesprivate-orders.7). Before it subscribes, the client postssocket_idandchannel_name(form fields or JSON) to/broadcasting/authwith the session cookie and the CSRF token (X-CSRF-TOKEN,X-XSRF-TOKENor_token). The callback decides;Ok(true)answers200with{"auth": "…"}, which the client sends with its subscription. - Patterns are dot-separated;
{name}matches one segment of letters, digits and_ - = @ , ;. A channel name is 1 to 164 characters of letters, digits and_ - = @ , . ;. - Guests are refused before the callback runs;
.guests()on a private registration lets them through (ctx.user_id()isNone). - No matching pattern, a guest,
Ok(false), and an error from the callback with a 4xx status (a parameter that does not parse, a record not found) all answer the same403 {"error":"Forbidden"}, so the endpoint never tells which channels exist. An error with a 5xx status is logged and answered with that status. Every answer carriesCache-Control: no-store. - Channel names starting with
private-encrypted-are refused.
ChannelCtx gives the callback:
| Method | Returns |
|---|---|
ctx.param::<T>("order") | the pattern parameter, parsed (a value that does not parse is a 403) |
ctx.user_id() | the signed-in user’s id, None for a guest |
ctx.user::<User>().await? | the signed-in user (loaded once) |
ctx.db()? | the app’s database |
ctx.app(), ctx.channel(), ctx.socket_id() | the app, the full channel name, the socket that subscribes |
The signature in auth is HMAC-SHA256 under ANVIL_APP_SECRET (by default a secret derived from APP_KEY), over
the socket id, the channel and who was authorized (the user id, a hash naming the session or the token’s id, the
time it was made and an expiry five minutes ahead). It works only for that socket and that channel, and only within those five minutes; the server checks it in
constant time.
§Presence channels
A presence channel (presence-<name>) is a private channel whose members see each other: who is in a chat room, who
is looking at a document. c.presence(pattern, callback) declares it; the callback returns the Member the user
joins as, or None to refuse:
use smeltery::anvil::{ChannelCtx, Channels, Member};
use smeltery::json;
pub fn channels(c: &mut Channels) {
c.presence("rooms.{room}", |ctx: ChannelCtx| async move {
let room: i64 = ctx.param("room")?;
let Some(user_id) = ctx.user_id() else { return Ok(None) };
// … check that the user may enter room `room` …
let _ = room;
Ok(Some(Member::new(user_id).info(json!({ "name": format!("User {user_id}") }))))
})
.whispers();
}- A member is a user id (a number becomes its decimal string; 1 to 128 bytes) and
user_info, which every member of the channel receives: give display fields only (a name, an avatar URL), never an email address or anything private. - Authorizing works as for private channels (the same two endpoints, the same 403 rules,
.guests()); the answer is200 {"auth": "…", "channel_data": "{\"user_id\":\"7\",\"user_info\":{…}}"}and the client sends both with its subscription. The signature coverschannel_data, so a client cannot change who it appears as. A callback that returns a member whosechannel_datais larger thanANVIL_MAX_MEMBER_BYTES(1,024), or whose user id is empty or longer than 128 bytes, gets a 500 (logged) and no signature. - Subscribing answers
pusher_internal:subscription_succeededwith the members:{"presence": {"ids": ["7", "9"], "hash": {"7": {…}, "9": {…}}, "count": 2}}. One user with several sockets is one member. When a user’s first socket joins, the other members getpusher_internal:member_addedwith{"user_id", "user_info"}; when its last socket leaves (it unsubscribes, its connection closes or drops, it is closed by a revocation, its process shuts down), they getpusher_internal:member_removedwith{"user_id"}. - Limits: a channel holds at most
ANVIL_MAX_PRESENCE_MEMBERS(100) distinct users; a new user beyond that getspusher:subscription_errorwith status 403 (“presence channel full”), while sockets of users already in it still join. A socket is in at mostANVIL_MAX_PRESENCE_CHANNELS(10) presence channels and may join 5 at once, then one a second (each join and leave writes to the member store and reaches every member; subscribing again to a channel it is in reads the member list and counts as a join); beyond either it gets status 429. - Across processes, the members live where the app’s PubSub driver says:
in the process’s memory with
local; withdatabase, in the tablespresence_socketsandpresence_users(a migration callssmeltery::anvil::presence_migrations::up/down); withredis, in Redis (featureredis). Every serving process marks its members alive every 30 seconds and removes the members of a process unseen for 90 seconds (a crashed process), announcingmember_removed; at shutdown a process removes its own. The same heartbeat checks its members against its sockets: a join or leave the database cut off halfway is finished, and members other processes removed while this one could not reach the database come back (withmember_added). Apps with many presence members or many client events usePUBSUB_DRIVER=redis: withdatabase, every join, leave and member event is a few rows. Withdatabase, the member limit is checked before the join, so joins of new users in several processes at the same moment can pass it together. A socket that joins while another process announces a member can receive thatmember_addedafter its member list, for a member already in the list. anvil.members("presence-rooms.1").await?returns the members (every process’s) to server code.- An event goes to a presence channel’s members with
Channel::presence("rooms.1")or#[broadcast(presence = "rooms.{room}")].
§Client events
A private or presence registration with .whispers() lets its subscribers send client events to each other
(typing indicators, cursors): {"event": "client-typing", "channel": "private-chat.1", "data": …} from a socket
subscribed to that channel. laravel-echo sends them with .whisper("typing", data) and receives them with
.listenForWhisper("typing", …).
- The other subscribers of the channel receive it, in every process, with
dataas it was sent; on a presence channel it also carries the sender’s"user_id". The sender never receives its own. - A client event never reaches the app’s code: it goes from socket to socket.
- The name starts with
client-and is at most 200 bytes; the frame is at mostANVIL_MAX_MESSAGE_SIZE. - A socket may send 10 client events a second, a channel carries at most 100 a second in each process, one client
address (an IPv6 client by its /64) sends at most
ANVIL_CLIENT_EVENTS_PER_CLIENT(50) a second over all its sockets, and a process accepts at mostANVIL_CLIENT_EVENTS_PER_SECOND(500) a second in all; more are dropped withpusher:error4301. Each accepted client event also reaches the app’s other processes (a row inpubsub_messageswith thedatabasedriver). Keep channels with client events small: each event reaches every other subscriber. - On a public channel, a channel the socket is not subscribed to, or a pattern without
.whispers(), a client event is answered withpusher:error4009; the socket stays open.
§Events
An event is a struct that serializes to its data:
use serde::Serialize;
use smeltery::anvil::{Anvil, BroadcastEvent, SocketId};
use smeltery::prelude::*;
#[derive(Serialize, BroadcastEvent)]
#[broadcast(private = "orders.{order_id}")]
pub struct OrderShipped {
pub order_id: i64,
pub tracking: String,
#[serde(skip)]
pub internal_note: String,
}
async fn ship(anvil: Anvil, socket: Option<SocketId>) -> Result<&'static str> {
// … mark order 7 shipped …
anvil
.send(&OrderShipped { order_id: 7, tracking: "1Z999".into(), internal_note: String::new() })
.except(socket)
.await?;
Ok("shipped")
}#[broadcast(public = "…")],#[broadcast(private = "…")]and#[broadcast(presence = "…")]name the channels (several are allowed);{field}is the field’sDisplayvalue, and a field the struct does not have is a compile error.- The event name is
App\Events\<TypeName>by default:laravel-echo’s.listen("OrderShipped")listens for that name.#[broadcast(as = "order.shipped")]sets another;laravel-echolistens for it with a leading dot (.listen(".order.shipped")). - Names starting with
pusher:orpusher_internal:are refused (the protocol reserves them). A{field}value goes into the channel name as it is, so a value with a.adds a segment: use fields such as ids. A channel named twice in one event is sent once. - The data is the struct’s JSON (
serdeattributes apply;#[serde(skip)]keeps a field out). Data on a public channel is public. - Without a derive:
impl BroadcastEvent for X { fn channels(&self) -> Vec<Channel> { … } }(the name defaults as above), or an event without a type:anvil.to(Channel::public("news")).event("posted").with(&json!({ "id": 3 })).await?. send(...).awaitreturnsDelivered { local }, the sockets of this process the event was queued for. It fails when the data is larger thanANVIL_MAX_EVENT_SIZE, a channel name is invalid, the name is empty or longer than 200 bytes, or the app’s PubSub driver fails (the sockets of this process got the event then; the other processes did not). A failed check sends nothing.- Other processes: the event also goes out on the app’s PubSub (topic
anvil); every serving process hands it to its own sockets. A job in aworkprocess reaches sockets held byserve --no-agentswhen both use a sharedPUBSUB_DRIVER. - Delivery is at most once, in order per sending process. A client that reconnects fetches the current state again.
- An event sent inside a database transaction is delivered at once, before the commit; send after it.
Leaving the sender out. A client sends its socket id with its own requests in the X-Socket-ID header.
SocketId reads it (Option<SocketId> is None without it; only <digits>.<digits> is accepted), and
.except(socket) leaves that socket out of the event. A client can name another socket’s id, which keeps one event
from that socket and reveals nothing else.
§Clients
A client connects to ws://<host>/app/<ANVIL_APP_KEY>?protocol=7 (wss:// behind HTTPS) and receives
pusher:connection_established with its socket_id and activity_timeout (ANVIL_ACTIVITY_TIMEOUT). In
pusher-js and laravel-echo options: the key, the host as wsHost, the port as wsPort / wssPort, forceTLS
for https, enabledTransports: ["ws", "wss"], and the auth endpoint /broadcasting/auth with the CSRF token in
its headers. Events arrive as {"event": name, "channel": channel, "data": "<the event's JSON as a string>"}.
A browser’s socket is accepted when its Origin is APP_URL’s origin (its scheme, host and port; a path in
APP_URL does not count) or listed in ANVIL_ALLOWED_ORIGINS
(scheme, host and port compared exactly; non-web schemes such as capacitor://localhost can be listed) or in
CORS_ALLOWED_ORIGINS. null is accepted only when one of the two lists names it. Other origins get
pusher:error 4009 and a close with 4009. A socket without an Origin (a native app, a
server) is accepted: a socket carries no identity, so it gets public channels and the private channels it holds a
signature for. Under APP_ENV=local with a loopback APP_URL, the loopback names of APP_URL’s origin
(localhost, 127.0.0.1, [::1], same port) count as that origin.
pusher:signin (user authentication) is answered with pusher:error 4009; the socket stays open.
§Mobile apps and other clients
A native app, a script or another backend connects to the same socket endpoint (it sends no Origin) and
authorizes private channels at POST /api/broadcasting/auth with Authorization: Bearer <token>, form fields or
JSON socket_id and channel_name, as the Pusher client libraries send them. The token is checked by the app’s
stateless guards (a bearer-token guard such as Hallmark’s hallmark, see API tokens), in registration
order, through auth::authenticate(&app, &mut parts, GuardSet::Stateless); the session and its cookie are never
read there.
- No valid token:
401 {"error":"Unauthenticated."}withWWW-Authenticate: Bearer. - A token without the ability
broadcasting(or*): the endpoint’s uniform403 {"error":"Forbidden"}. - Otherwise the channel rules are the cookie endpoint’s: the pattern’s callback decides,
ctx.user_id()is the token’s user,ctx.user::<User>()loads it andctx.principal()gives the principal (guard, credential, abilities). The answer is200 {"auth": "…"}. - The signature names the token by its key (
<guard>:token:<id>, such ashallmark:token:12), and expires after five minutes or when the token does, whichever comes first.
§Flutter
Flutter and Dart apps connect with the dart_pusher_channels
package, a Pusher protocol 7 client in pure Dart that takes a custom host, and sign in with Hallmark tokens over
http. examples/flutter-client is a complete app.
flutter pub add dart_pusher_channels httpSigning in. POST /api/tokens (see API tokens) answers 201 with the token; keep it in the
platform’s secure storage (the flutter_secure_storage package, for example) rather than in plain preferences.
import 'dart:convert';
import 'package:dart_pusher_channels/dart_pusher_channels.dart';
import 'package:http/http.dart' as http;
final api = Uri.parse('https://app.example.com');
Future<String> signIn(String email, String password) async {
final res = await http.post(
api.resolve('/api/tokens'),
headers: {'Content-Type': 'application/json', 'Accept': 'application/json'},
body: jsonEncode({'email': email, 'password': password, 'device_name': 'Pixel 9'}),
);
if (res.statusCode != 201) throw Exception('sign-in failed: ${res.statusCode}');
return jsonDecode(res.body)['token'] as String;
}Connecting. The key is the app’s ANVIL_APP_KEY (set it in .env: the derived key changes with APP_KEY). In
production the socket is wss on the HTTPS host and port; in development it is ws on SERVER_PORT, and the
Android emulator reaches the development machine’s 127.0.0.1 at 10.0.2.2 (ws://10.0.2.2:8000; Android refuses
plain http / ws unless the app’s manifest allows cleartext traffic, which the example does in debug builds only).
final client = PusherChannelsClient.websocket(
options: PusherChannelsOptions.fromHost(
scheme: 'wss',
host: 'app.example.com',
port: 443,
key: 'your-anvil-app-key', // ANVIL_APP_KEY
),
connectionErrorHandler: (exception, trace, refresh) => refresh(),
);Channels. Private and presence channels authorize at /api/broadcasting/auth with the bearer token; the
package’s delegate posts socket_id and channel_name as form fields:
final authUrl = api.resolve('/api/broadcasting/auth');
final headers = {'Authorization': 'Bearer $token', 'Accept': 'application/json'};
final news = client.publicChannel('news');
final orders = client.privateChannel(
'private-orders.7',
authorizationDelegate: EndpointAuthorizableChannelTokenAuthorizationDelegate.forPrivateChannel(
authorizationEndpoint: authUrl,
headers: headers,
onAuthFailed: onAuthFailed,
),
);
final room = client.presenceChannel(
'presence-rooms.1',
authorizationDelegate: EndpointAuthorizableChannelTokenAuthorizationDelegate.forPresenceChannel(
authorizationEndpoint: authUrl,
headers: headers,
onAuthFailed: onAuthFailed,
),
);
// The package reconnects after a close but does not subscribe again by itself: subscribe on every connection.
final channels = <Channel>[news, orders, room];
client.onConnectionEstablished.listen((_) {
for (final channel in channels) {
channel.subscribeIfNotUnsubscribed();
}
});
await client.connect();Events arrive with their name and the event’s JSON:
orders.bind(r'App\Events\OrderShipped').listen((event) {
final data = event.tryGetDataAsMap(); // {"order_id": 7, "tracking": "1Z999"}
});Presence members. room.state?.members holds the members’ ids, but the package drops the user_info of the
list that comes with the subscription; read it from the pusher:subscription_succeeded event’s data, and follow
member_added / member_removed:
final names = <String, String>{};
room.whenSubscriptionSucceeded().listen((event) {
final hash = event.tryGetDataAsMap()?['presence']?['hash'] as Map? ?? {};
names
..clear()
..addAll({for (final e in hash.entries) '${e.key}': '${e.value['name']}'});
});
room.whenMemberAdded().listen((event) {
final data = event.tryGetDataAsMap()!;
names['${data['user_id']}'] = '${data['user_info']['name']}';
});
room.whenMemberRemoved().listen((event) => names.remove('${event.tryGetDataAsMap()!['user_id']}'));Whispers (client events, on a registration with .whispers()): the other subscribers receive them with the
sender’s user_id on a presence channel; the sender does not.
room.trigger(eventName: 'client-typing', data: {'typing': true});
room.bind('client-typing').listen((event) => print('${event.userId} is typing'));Revocation and signing out. When the token is signed out or revoked elsewhere, the server closes the socket with
4200; the package reconnects, authorizing the channels again answers 401, and onAuthFailed gets the exception:
the app returns to its sign-in. Signing out on the device deletes the token:
void onAuthFailed(dynamic exception, StackTrace trace) {
if (exception is EndpointAuthorizableChannelTokenAuthorizationException &&
exception.response.statusCode == 401) {
// The token has ended: back to the sign-in.
}
}
Future<void> signOut() async {
await http.delete(api.resolve('/api/tokens/current'), headers: headers); // 204
await client.disconnect();
client.dispose();
}§Revocation
A private subscription ends when the credential that authorized it ends. Every serving process listens to the app’s
auth events (PubSub topic auth, see PubSub): signing out ends the
subscriptions authorized by that session’s cookie endpoint requests; a password change or logout_other_devices
ends every credential of the user except the one named; a token its guard revokes ends the subscriptions it
authorized. The sockets holding such a subscription are closed with 4200 (the client reconnects at once and
authorizes its channels again, which now fails for the ended credential), and a signature made before the event
can no longer subscribe. That check also refuses a signature dated up to 30 seconds after the event, so a process
whose clock runs a little ahead cannot slip one through; the processes’ clocks must agree (NTP). Each process
remembers the last 10,000 events for 15 minutes for that check, and refuses what it cannot check: a signature made
before the process started, before an event it forgot early (more than 10,000 events within 15 minutes), or before
the moment it started listening to them or fell behind them (its PubSub subscription lagged). When it falls
behind, it also closes every socket holding a subscription such a signature authorized with 4200, each at a random
moment within 30 seconds from the next second on, and at most once a minute (later lags join the next round), so
after a lag such a socket can keep its subscription for up to about 90 seconds (60 s for the per-minute limit plus
the 30 s spread). The clients authorize again and get new signatures.
Events are delivered at most once: a socket a lost event did not close lives at most ANVIL_MAX_CONNECTION_AGE
(24 hours by default), and a session that only expires (idle or absolute lifetime) sends no event, so its
subscriptions also end with the socket’s age. Several processes need a shared PUBSUB_DRIVER for an event to reach
them all.
§Settings and limits
| Key | Default | Meaning |
|---|---|---|
ANVIL_APP_ID | smeltery | the app id |
ANVIL_APP_KEY | derived from APP_KEY (20 characters) | the public key in the socket path; letters, digits, -, _, at most 64. The derived key changes when APP_KEY changes: set it in .env when clients are built with it (a front end bundle, a mobile app) |
ANVIL_APP_SECRET | derived from APP_KEY | the secret signatures are made with; set it only when another deployment must make them; at least 32 bytes outside APP_ENV=local / testing, else the app stops at boot |
ANVIL_ALLOWED_ORIGINS | empty | origins allowed besides APP_URL’s, comma-separated; * allows any (logged as a warning outside APP_ENV=local) |
ANVIL_MAX_CONNECTIONS | 2048 | sockets in this process (below SERVER_MAX_CONNECTIONS); past it a socket is closed with 4100 |
ANVIL_MAX_CONNECTIONS_PER_IP | 100 | sockets of one client address (an IPv6 client by its /64, the address from TRUSTED_PROXIES resolution); past it 4100; below SERVER_MAX_CONNECTIONS_PER_IP when both are on, else the app stops at boot; 0 turns it off and leaves only the server’s per-address cap |
ANVIL_HANDSHAKES_PER_MINUTE | 60 | socket handshakes of one client address a minute; past it 429. Once 100,000 addresses are counted in a minute, further ones are counted with their network (an IPv4 /16, an IPv6 /48) at 16 times the budget, and once 10,000 networks are counted, further clients are limited only by the socket caps |
ANVIL_MAX_SUBSCRIPTIONS | 100 | channels per socket; past it the subscription gets status 429 |
ANVIL_MAX_MESSAGE_SIZE | 10000 | bytes of one message from a client (256 to 1048576); a larger one closes the socket with 1009 |
ANVIL_MAX_EVENT_SIZE | 32768 | bytes of one event’s data (at most 49152) |
ANVIL_MAX_PRESENCE_MEMBERS | 100 | distinct users in one presence channel (1 to 10000); the member list holds at most this many |
ANVIL_MAX_MEMBER_BYTES | 1024 | bytes of one member’s channel_data (64 to 8192) |
ANVIL_MAX_PRESENCE_CHANNELS | 10 | presence channels one socket is in (1 to 100) |
ANVIL_CLIENT_EVENTS_PER_SECOND | 500 | client events this process accepts a second from all its sockets (1 to 100000); more are dropped with 4301 |
ANVIL_CLIENT_EVENTS_PER_CLIENT | 50 | client events one client address (an IPv6 client by its /64) sends a second over all its sockets (1 to 100000); more are dropped with 4301 |
ANVIL_ACTIVITY_TIMEOUT | 30 | seconds (1 to 3600); clients ping after this much silence |
ANVIL_PING_INTERVAL | 60 | seconds of silence (1 to 3600) before the server sends pusher:ping |
ANVIL_PONG_TIMEOUT | 30 | seconds (1 to 300) to answer it; then the socket is closed with 4201 |
ANVIL_MAX_CONNECTION_AGE | 86400 | seconds (60 to 2592000) a socket lives; then it is closed with 4200 and the client reconnects |
ANVIL_IN_SERVE | true | false: serve answers the socket path with 404, because an anvil process holds the sockets (see A separate socket process) |
ANVIL_SERVER_HOST | 127.0.0.1 | the address the anvil process listens on |
ANVIL_SERVER_PORT | 8080 | the port the anvil process listens on |
A timer value outside its range in .env is replaced by the nearest bound, with a warning; outside its range in
Settings passed to anvil_with, it stops the app at boot. Every socket that joins a presence channel is sent the
whole member list in one frame, so ANVIL_MAX_PRESENCE_MEMBERS and ANVIL_MAX_MEMBER_BYTES together may allow a
list of at most 16 MiB (about 2 × member bytes + 600 bytes per member); a larger product stops the app at boot.
A socket may send 20 frames a second with bursts of 40; a frame over that is dropped with one pusher:error 4301,
and 40 more in a row close the socket with 4100. Each socket has an outbox of 256 messages; a socket that does not
read them is closed with 4100, and a write that takes longer than 10 seconds drops it. A binary frame closes it with
1003, the server’s shutdown with 1001. pusher-js reconnects after codes below 4000 and from 4100 to 4299, and stops
after 4007, 4008 (protocol version unsupported or missing) and 4009.
A socket keeps its connection’s place in SERVER_MAX_CONNECTIONS and SERVER_MAX_CONNECTIONS_PER_IP, so sockets
and HTTP requests share those limits, and the server’s idle timeout does not close it. Sockets are closed with 1001
when the app shuts down, within SHUTDOWN_TIMEOUT. Frames are never logged.
§Behind a proxy
Caddy’s reverse_proxy passes WebSocket upgrades as it is. nginx forwards Upgrade and Connection only when told
to; add this location to the server block (with the app’s key):
location = /app/ANVIL_APP_KEY_VALUE {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
# Longer than ANVIL_PING_INTERVAL + ANVIL_PONG_TIMEOUT.
proxy_read_timeout 120s;
proxy_send_timeout 120s;
}Behind a proxy every socket comes from the proxy’s address; with the proxy in TRUSTED_PROXIES, the per-client
limits count the client from X-Forwarded-For.
§A separate socket process
serve holds the sockets by default. The anvil command runs the app binary as a process that serves only the
socket endpoint (/app/<ANVIL_APP_KEY>) and /up, on ANVIL_SERVER_HOST:ANVIL_SERVER_PORT (127.0.0.1:8080;
--host and --port override them); every other path answers 404. The web processes can then restart (a deploy)
without closing a socket.
smeltery anvil # in development
/srv/myapp/myapp anvil # the release binary- The web processes run with
ANVIL_IN_SERVE=false: their socket path answers 404. They keep the auth endpoints (/broadcasting/auth,/api/broadcasting/auth), which need the session and the guards; theanvilprocess checks the signatures they make with the same secret (derived from the sameAPP_KEY, or the sameANVIL_APP_SECRET) and the sameANVIL_APP_KEY. - Events, revocations and presence reach the
anvilprocess through the PubSub. UnderPUBSUB_DRIVER=autotheanvilprocess and aservewithANVIL_IN_SERVE=falseuse the shared driver (rediswhenCACHE_STORE=redis, elsedatabase); without a usable shared driveranvilstops at start with an error. Console commands uselocalunderauto, so a deployment whose commands send events setsPUBSUB_DRIVER=databaseorredis. Thedatabasedriver needs thepubsub_messagestable, presence the presence tables (see Presence channels). - No agents, jobs or schedules run in it;
serveorworkruns them. - The server’s limits hold on its listener as on
serve’s (SERVER_MAX_CONNECTIONS,SERVER_MAX_CONNECTIONS_PER_IP,SERVER_HEADER_TIMEOUT,TRUSTED_PROXIES), with theANVIL_*limits above. On SIGTERM it closes its sockets with 1001 and exits withinSHUTDOWN_TIMEOUT; its presence members leave with them. - With
ANVIL_IN_SERVEleft attrueit logs a warning at start:serveprocesses hold sockets too.
systemd. A third unit next to the one of systemd (or next to
myapp-web and myapp-work): set ANVIL_IN_SERVE=false in .env, then
sudo cp /etc/systemd/system/myapp.service /etc/systemd/system/myapp-anvil.service
sudo nano /etc/systemd/system/myapp-anvil.serviceand change Description=myapp sockets (Smeltery) and ExecStart=/srv/myapp/myapp anvil. Each socket holds a file
descriptor: for more than about a thousand sockets add LimitNOFILE=65536 under [Service] and raise
SERVER_MAX_CONNECTIONS (4096) and ANVIL_MAX_CONNECTIONS (2048, below it) in .env.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp-anvil
sudo systemctl restart myapp
curl -s http://127.0.0.1:8080/upCaddy sends the socket path to the anvil process and everything else to the web process:
app.example.com {
handle /app/* {
reverse_proxy 127.0.0.1:8080
}
handle {
reverse_proxy 127.0.0.1:8000
}
}nginx: the location = /app/ANVIL_APP_KEY_VALUE block above with proxy_pass http://127.0.0.1:8080;.
§Testing broadcasts
use serde_json::json;
use smeltery::anvil::testing::{AnvilSpy, TestSocket, auth_of, authorize};
use smeltery::anvil::{Anvil, AnvilExt as _, Channel, ChannelCtx};
use smeltery::testing::TestApp;
let app = TestApp::new(|b| {
b.anvil(|c| {
c.public("news");
// In this test, user n owns order n.
c.private("orders.{order}", |ctx: ChannelCtx| async move {
Ok(ctx.user_id() == Some(ctx.param::<i64>("order")?))
});
})
});
let spy = AnvilSpy::of(app.app());
let mut socket = TestSocket::connect(app.app());
// A private subscription with the auth endpoint's answer.
app.acting_as(7);
let auth = auth_of(&authorize(&app, socket.socket_id(), "private-orders.7", None)).unwrap();
assert_eq!(
socket.subscribe("private-orders.7", Some(&auth))["event"],
"pusher_internal:subscription_succeeded"
);
let anvil = Anvil::of(app.app()).unwrap();
app.block_on(async {
anvil.to(Channel::private("orders.7")).event("shipped").with(&json!({ "id": 7 })).await
})?;
assert!(spy.sent_on("private-orders.7", "shipped"));
assert_eq!(socket.events()[0]["data"], r#"{"id":7}"#);AnvilSpy records every send, the last 10,000 (sent(), sent_on(channel, name), nothing_sent()); TestSocket connects to the
hub without a network (subscribe, subscribe_presence, whisper, unsubscribe, send, events, closed;
dropping it leaves its presence channels); authorize posts to the auth endpoint as the TestApp’s browser (with
TestApp::with_csrf, pass the CSRF token), and presence_of reads a presence answer’s auth and channel_data.
TestSocket keeps presence members in the process’s memory (the TestApp’s local PubSub driver).
§Watchfire: agents, jobs and the scheduler
Watchfire (smeltery::watchfire) runs the app’s background work on one runtime: agents (long-lived, supervised
tasks such as pollers, scrapers and bots), jobs (short tasks dispatched from the app, on a queue) and scheduled
tasks (started by the clock). app/agents/mod.rs registers everything; bootstrap/app.rs wires it with
.agents(app::agents::register) (the trait is smeltery::watchfire::AgentsExt). serve runs the agents next to
the HTTP server and work runs them alone; both stop them within SHUTDOWN_TIMEOUT.
use smeltery::watchfire::prelude::*;
pub fn register(w: &mut Watchfire) {
// Quick forms: closures, supervised like any agent.
w.every(30.secs(), "heartbeat", |ctx| async move {
ctx.log().info("tick");
Ok(())
});
w.run("scraper", |ctx| async move {
while ctx.sleep(5.secs()).await {
let page = ctx.http().get("https://example.com/").await?.text().await?;
ctx.counter("bytes").add(page.len() as i64);
}
Ok(())
})
.restart(Restart::OnFailure)
.backoff(1.secs()..=30.secs())
.group("scrapers");
w.on_event("post.created", "notify", |ctx, event| async move {
ctx.log().info(format!("new post: {}", event.payload));
Ok(())
});
w.group("scrapers").limit(2);
w.rate_limit("example.com", 2.per_second());
w.schedule()
.call("cleanup", |_ctx| async move { Ok(()) })
.every(5.mins())
.overlap(Overlap::Skip);
w.schedule().agent("scraper").cron("0 3 * * *");
}A full agent is a struct (smeltery make:agent PricePoller); its fields survive restarts:
use smeltery::watchfire::prelude::*;
/// Polls prices.
#[derive(Default)]
pub struct PricePoller {
last: Option<String>,
}
impl Agent for PricePoller {
fn name(&self) -> String {
"price_poller".into()
}
fn config(&self) -> AgentConfig {
AgentConfig::default()
.restart(Restart::OnFailure)
.backoff(1.secs()..=60.secs())
.heartbeat_timeout(2.mins())
}
async fn run(&mut self, ctx: AgentCtx) -> Result<(), AgentError> {
let mut ticker = ctx.interval(30.secs());
while ticker.tick().await {
// `tick` heartbeats, and returns false once the agent is asked to stop
self.last = Some("42".into());
}
Ok(())
}
}Register it with w.agent(price_poller::PricePoller::default()), or a pool of them with
w.pool(4, "fetcher", Fetcher::new) (named fetcher#0 … fetcher#3).
Supervision. States: starting (waiting for a group or global slot), running, paused, stopping,
stopped, backing_off, completed, failed, and standby (another process runs the agent; see “Several
processes”). The restart policy (Restart::Never, OnFailure (default),
Always) decides what happens when a run ends on its own; restarts wait an exponential backoff with full jitter
(a random delay up to initial × 2ⁿ, capped; a run of 60 s or more resets it). .max_restarts(n, per) marks the
agent failed after n restarts within per; .heartbeat_timeout(d) cancels a run that has not heartbeated
(ctx.heartbeat() or a ticker tick) for d (outcome stalled, restarted like a failure); .shutdown_timeout(d) (default 10 s) is how long a
cancelled run may take before it is dropped. A panic is caught and counts as a failure. Every run ends with exactly
one outcome: completed, failed, panicked, stopped, killed (did not stop in time), stalled (heartbeat
timeout) or interrupted (the process ended during the run; found on the next launch). Alerts (failed agents,
stalls) are logged at error level with the target smeltery_watchfire::alert.
Control from code. Agents (a service: app.service::<Agents>(), or a handler argument agents: Agents) has
list, status, start, stop, pause (stop and stay stopped until resume; kept in memory only, so a restart of
the process starts the agent again as autostart says), resume, restart, add,
remove, logs (the last 200 lines of ctx.log()), runs, emit and subscribe (status changes).
What a run gets (AgentCtx). name(), run_id(), cancellation (cancelled(), is_cancelled(), token()),
heartbeat(), sleep(d) and interval(d) (both return false once cancelled), http(), rate_limited(host),
app(), db(), service::<T>(), checkpoint(&state) / checkpoint_get::<T>() (JSON that survives restarts),
emit(event, payload) (to on_event agents), counter(name).inc() / .add(n) (saved in the run record),
log().info(..) (a tracing event with agent and run fields, also kept for Agents::logs),
spawn_child(name, agent) (a supervised child named <agent>.<name>, stopped when the run ends) and
dispatch(job).
HTTP. ctx.http() sends requests with a timeout (WATCHFIRE_HTTP_TIMEOUT, 30 s; 10 s to connect), retries
connect errors, timeouts, 429 and 5xx up to 3 times with jittered backoff (honouring Retry-After up to 60 s;
5xx and timeouts are retried for GET, HEAD, PUT, DELETE and OPTIONS only), waits for the host’s token
bucket from w.rate_limit(host, rate), and sends User-Agent: <APP_NAME> (smeltery-watchfire). A response body
larger than WATCHFIRE_HTTP_MAX_BODY (10 MiB) fails with HttpError::TooLarge; the body is read in chunks and the
read stops at the limit. The client follows redirects itself (301, 302, 303, 307, 308, at most 5 hops), so
each hop waits for the token bucket of its own host: only to http and https URLs, never from https to http,
and on a hop to another origin only User-Agent, Accept and Accept-Language go along (no Authorization, cookies
or key headers) and no request body (HttpError::Redirect otherwise). .redirects(Redirects::SameOrigin) stays on
one origin, .redirects(Redirects::None) returns the 3xx answer. The default follows a redirect to any http or
https host, addresses on this machine and the private network included (without the headers and body above); an
agent that fetches URLs its users or other sites supply sets .redirects(Redirects::SameOrigin) on those requests
(or HttpOptions::redirects for its client), so a redirect cannot send it to an internal address. Errors and logs
name a URL as
scheme://host:port/path, without its query string or user info. Methods: get(url),
post_json(url, &body), request(method, url) with .header, .bearer, .body, .json, .timeout,
.max_body(bytes), .redirects(policy), .send(); responses have status(), text(), json::<T>(), bytes(),
error_for_status().
Jobs. A job is a serializable struct (smeltery make:job SendWelcome), registered with w.job::<SendWelcome>():
use serde::{Deserialize, Serialize};
use smeltery::watchfire::prelude::*;
#[derive(Serialize, Deserialize)]
pub struct SendWelcome {
pub user_id: i64,
}
impl Job for SendWelcome {
const NAME: &'static str = "send_welcome";
fn max_attempts(&self) -> u32 {
3 // the default
}
async fn handle(&self, ctx: JobCtx) -> Result<(), AgentError> {
ctx.log().info(format!("welcoming user {}", self.user_id));
Ok(())
}
}
async fn register_user(app: smeltery::App) -> smeltery::Result<&'static str> {
SendWelcome { user_id: 1 }.dispatch(&app).await?;
SendWelcome { user_id: 1 }.dispatch_later(&app, 10.mins()).await?;
Ok("welcome")
}Queue workers (queue#0 … queue#n, WATCHFIRE_WORKERS, default 2) take jobs one at a time. The database driver
reserves a job with one atomic UPDATE … WHERE reserved_at IS NULL, so no two workers hold the same job;
reservations older than twice WATCHFIRE_JOB_TIMEOUT (a worker that died) are released, and the job can then run
again. A worker’s outcome (done, retry, dead letter, back to the queue) is stored only while its reservation is still
the one held: a worker whose reservation was released and taken by another one changes nothing and logs a warning.
Jobs run at least once, so a job with side effects checks whether its work is already done; give every process the
same WATCHFIRE_JOB_TIMEOUT. A failed attempt (an error,
a panic, or running longer than WATCHFIRE_JOB_TIMEOUT) is retried after Job::backoff(attempt) (5 s, doubling, at
most 10 minutes); after max_attempts the job moves to the dead letters, as does a job with an unknown name or a
payload that does not decode (the stored error names the problem and its line and column, never a value of the
payload). A payload larger than WATCHFIRE_MAX_PAYLOAD (1 MiB) is refused by dispatch; a stored one that large
goes to the dead letters without being read or run. Moving a job to the dead letters and retry moving it back are one database
transaction each, so the job is in exactly one of the two tables. A job reserved for an attempt beyond max_attempts
(its last attempt ended without its outcome being stored) goes to the dead letters without running again. A job still
running at shutdown goes back to the queue. Each job is recorded as a run of its worker, with the job name. Error
texts stored with runs, agents and dead letters keep their first 8 KiB (marked as truncated). The jobs and
dead_letters tables hold each job’s payload as plain JSON, and the API’s GET /jobs shows the dead letters’
payloads; dead letters stay until they are retried or deleted (the memory driver keeps the latest 1000).
With QUEUE_DRIVER=redis (feature redis of smeltery) the jobs and dead letters live on the Redis server of
REDIS_URL (rediss:// uses rustls), under keys that start with QUEUE_PREFIX (default
<app name in snake case>_queue_) and {default}:: a hash per job and per dead letter, and sorted sets of the
waiting, reserved and dead ones. {default} is a hash tag, so all of the queue’s keys share one hash slot. The driver
connects to one Redis server (a standalone server, or the primary of a replicated one), not to Redis Cluster. Every
queue operation is one Lua script (sent by its SHA-1 with EVALSHA), which Redis runs atomically: each job is reserved
by one worker across all processes on that server and prefix, and a job is waiting, reserved or a dead letter, never
two of them. Order, attempts, backoff, stale reservations, dead letters and the dashboard’s retry and delete work as
with the database driver. The driver connects on first use and reconnects by itself; every call has the
WATCHFIRE_STORE_TIMEOUT budget. A redis:// URL with a password to another machine logs a warning at start:
the password and the jobs travel unencrypted, so use rediss:// unless the network is private. CACHE_PREFIX is
compared with the start of the queue’s keys,
<QUEUE_PREFIX>{default}:: neither may start with the other, and QUEUE_PREFIX has no { or }; otherwise the app
refuses to boot, because cache:clear on Redis removes every key that starts with CACHE_PREFIX.
The queue’s keys have no expiry. With the maxmemory-policy noeviction (or a volatile-* policy, which only evicts
keys with an expiry) Redis keeps every queued job; when its memory is full it refuses new jobs, and dispatch returns
that error. Redis’s persistence (RDB or AOF) decides which jobs survive a restart of Redis: writes it had not saved yet
are lost, so a job can be lost or run again. New job and dead-letter ids never reuse the id of a job or dead letter
that still exists, also when the id counter itself was among the lost writes.
The scheduler. w.schedule() takes a target, .job(J) (dispatches it), .call(name, closure) or
.agent(name) (starts it when it is stopped, completed, failed or backing off), and a timing: .every(d), .every_minute(),
.hourly(), .daily(), .daily_at("03:00"), .weekly() or .cron("m h dom mon dow") (five fields with *, lists,
ranges and steps, in UTC). .overlap(Overlap::Skip) (default) skips a call that is still running,
Overlap::Queue runs it once the previous one finishes, Overlap::Allow runs both. The clock is an agent named
scheduler. schedule:run runs the tasks due this minute once, for system cron. .every(d) runs first d after
launch; with a shared lock store (see “Several processes”) it runs on multiples of d since the Unix epoch instead,
so that every process agrees on the ticks.
Persistence. With a database, Watchfire keeps the agent registry, run history, checkpoints and (with the
database queue driver) the job queue and the dead letters in watchfire_agents, watchfire_runs, watchfire_checkpoints, watchfire_jobs and
watchfire_dead_letters. A migration creates them by delegating to smeltery::watchfire::migrations::up(schema) /
down(schema); it also creates watchfire_commands (commands for agents in other processes) and gives each run the
name of the process that ran it. An app whose Watchfire migration ran before those existed adds a second migration
that calls smeltery::watchfire::migrations::up_multi_process(schema) / down_multi_process(schema) (it does nothing
when they exist). Without a database (or before the migration ran) the history and checkpoints live in memory, and
the queue too (QUEUE_DRIVER=memory). Every store call has a timeout (WATCHFIRE_STORE_TIMEOUT, 5 s); a store failure
is logged and never stops an agent.
| Variable | Default | Meaning |
|---|---|---|
WATCHFIRE_MAX_CONCURRENT | 0 | agents running at once (0: no limit; the queue workers and the scheduler do not count) |
WATCHFIRE_WORKERS | 2 | queue workers |
WATCHFIRE_JOB_TIMEOUT | 60 | seconds a job may run |
WATCHFIRE_HTTP_TIMEOUT | 30 | seconds per ctx.http() request |
WATCHFIRE_HTTP_MAX_BODY | 10485760 | the largest response body ctx.http() reads, in bytes |
WATCHFIRE_STORE_TIMEOUT | 5 | seconds per store or queue call |
WATCHFIRE_MAX_PAYLOAD | 1048576 | the largest job payload in bytes: dispatch refuses a larger one, and a larger stored one is dead-lettered without running |
QUEUE_DRIVER | database with a database, else memory | where queued jobs wait: database, redis (feature redis; the server of REDIS_URL) or memory |
QUEUE_PREFIX | <app name in snake case>_queue_ | the start of the redis queue driver’s keys |
WATCHFIRE_DASHBOARD | local | who may use the dashboard: local (signed-in users the dashboard gate admits; under APP_ENV=local also requests from this machine without signing in), auth (signed-in users the gate admits, also under APP_ENV=local), off (no dashboard) |
WATCHFIRE_API_ADDR | empty | the address work serves the API on (e.g. 127.0.0.1:8001); the agents:* commands call it (an address on this machine, or an https:// URL), else SERVER_HOST:SERVER_PORT |
WATCHFIRE_IN_SERVE | true | whether serve runs the agents, queue workers and scheduler (false: only work runs them) |
WATCHFIRE_LOCK_STORE | CACHE_STORE | the cache store whose locks coordinate several processes; off for none |
WATCHFIRE_LEASE_TTL | 30 | seconds a lease lasts without renewal (at least 3); at least 12/7 of the longest singleton agent’s shutdown timeout, and 18 with Overlap::Skip / Queue scheduled calls (see “Several processes”) |
WATCHFIRE_ALERT_WEBHOOK | empty | a URL every alert is POSTed to as JSON |
WATCHFIRE_ALERT_MAIL | empty | comma-separated addresses every alert is mailed to (needs .mail()) |
Several processes. serve runs the web server and the background work together. serve --no-agents (or
WATCHFIRE_IN_SERVE=false) serves the web only, so a deployment can run web processes next to one or more work
processes. When the processes share a cache store whose locks span processes (database, redis, memcached,
and file for the processes of one machine; WATCHFIRE_LOCK_STORE, by default CACHE_STORE), they coordinate
through its atomic locks:
- Agents run in one process at a time. Each agent holds a lease (a lock named
watchfire:agent:<name>). The other processes show it asstandbyand try to take the lease everyWATCHFIRE_LEASE_TTL / 3. A process that stops releases its leases, so another one takes over within that interval; a process that dies leaves them to expire, so another one takes over betweenWATCHFIRE_LEASE_TTLand 4/3 of it after its last renewal. The holder renews a lease every third of its cut-off,TTL - shutdown timeout - TTL / 6after the last renewal it sent. At the cut-off, whatever store call is still in flight (a renewal, or a status write of the running agent), or as soon as a renewal finds the lease taken, it stops the agent (within the agent’s shutdown timeout) and goes tostandby; a run whose lease went while its start was being recorded does not start. So it has stopped byTTL - TTL / 6after the store’s last renewal: processes whose clocks differ by less thanWATCHFIRE_LEASE_TTL / 6(5 s by default) never run an agent twice at once. A singleton whose shutdown timeout leaves a cut-off under a quarter of the TTL is refused at launch with the TTL it needs (at least 12/7 of the shutdown timeout: the default 10 s timeout needs at least 18); so is a coordinated scheduled call withOverlap::Skip/Queue(stopped within 10 s) under 18, byserve,workandschedule:runalike. The holder keeps the agent in every state: paused, stopped or completed there means the same everywhere while it runs; the next holder starts it asautostartsays.removefrees the lease, so another process takes the agent over: remove it in every process, or from the registration. Pool members are agents of their own (fetcher#0may run in one process andfetcher#1in another)..per_process()(on the builder orAgentConfig) runs an agent in every process instead. - Each scheduled tick runs once. A job or call that is due claims its tick in the store (
Cache::addofwatchfire:schedule:<name>:<tick>); the first process runs it and the others skip it. A call withOverlap::SkiporOverlap::Queuealso holds a lease while it runs, so it never runs in two processes at once: a run in another process makes it skip (Queuewaits only for a run in its own process), and when its lease is lost the call is cancelled and dropped after 10 s.schedule:runclaims the minute’s tick and takes the same leases, so system cron on several servers, or next toserve, runs a task once; it skipsevery(d)tasks whosedis not a whole number of minutes (onlyserve/workrun those then)..agent(name)targets start the agent in the process that holds it..per_process()on a scheduled task runs it in every process. - Queue workers run in every process. The
databasequeue reserves each job for one worker (above). - Live pages update from every process.
serve --no-agentsandworkuse the shared PubSub driver underPUBSUB_DRIVER=auto, so an agent’sbroadcast.to("counter").refresh()inworkreaches the pages held by the web process. - Run history keeps processes apart. Each run records its process (
RunRecord::process: host, process id and a random part). Every process holds a lease on its own name; runs leftrunningby a process whose lease is gone are markedinterrupted(checked at launch and everyWATCHFIRE_LEASE_TTL). A process that loses its own lease (its store calls fail) takes it again as soon as the store answers and puts its running runs that were markedinterruptedback torunning; a run that ended meanwhile keeps its outcome. A final run record that could not be written (the database did not answer) is written again at the next check. Processes that share the database without coordinating (lock storeoff, or the local fallback below) hold no such lease, so a coordinating process marks their running runsinterrupted.
At launch Watchfire checks the store by taking and freeing a lock. When it does not answer (or the cache_locks table
is missing), a process under APP_ENV=local or testing runs everything itself (with a warning), and any other
coordinates anyway: its agents wait in standby and its ticks are skipped until the store answers. A store named in
WATCHFIRE_LOCK_STORE that cannot be opened is an error; one that does not answer the probe is an error under
APP_ENV=local / testing and coordinated through (as above) elsewhere. The memory, array and null stores do not span
processes: each process then runs every agent and every tick itself.
One dashboard for every process. With the Watchfire tables in the database, a process that does not run
Watchfire (serve --no-agents) shows the registered agents from watchfire_agents and watchfire_runs, with the
process that holds each one (or “no process holds it”, with its last recorded state); a process where an agent is in
standby shows the holder’s row for it. A command for an agent that runs elsewhere goes into watchfire_commands.
Every coordinating process looks there once a second for the agents it holds, carries the command out (each agent’s
commands in order, those of different agents side by side) and records the outcome (or the refusal, with its
status); the dashboard (or API) waits up to 5 s for it and shows it. When the
holder took the command but has not finished within 5 s (a slow stop) it says so; when no process took it, the
command is carried out when a process holding the agent takes it, or lapses after 60 s. A command taken but never
finished is closed after 11 minutes as “outcome never recorded”; a process that shuts down while carrying a command out
closes it at once (503, outcome unknown). Command times come from the database’s clock. At
most 20 commands wait per agent.
Log lines stay in the memory of the process that runs an agent; from another process, GET /agents/{name}/logs (and
agents:logs) asks that process for them through watchfire_commands (the newest lines that fit in 60 KB; 504 when it
does not answer within 5 s). The answer’s row is deleted once read, or a minute after it was written when nobody read it. The /events stream stays with the process that runs an agent.
JSON API. Under /_watchfire/api (no sessions, no CSRF check):
| Request | Answer |
|---|---|
GET /agents | every agent’s status |
GET /agents/{name} | {"status": …, "runs": […]} (the latest 20 runs) |
POST /agents/{name}/{start|stop|pause|resume|restart} | the new status |
GET /agents/{name}/logs | the last log lines (at most 200), also from the process that runs the agent |
GET /runs?agent=&limit= | the latest runs (default 50, at most 500) |
GET /jobs | {"driver", "pending", "reserved", "dead", "dead_letters": […]} (the latest 50) |
POST /jobs/dead/{id}/retry | queues a dead letter again: {"job_id": …} |
DELETE /jobs/dead/{id} | deletes a dead letter |
GET /schedule | the scheduled tasks with their next run |
GET /events | Server-Sent Events: snapshot (every agent) first, then status per change and event per emit; the stream ends when the app shuts down |
Errors are {"error": "…"} with 401 (no or a wrong token), 404 (unknown agent, action or dead letter), 409 (the
agent is in the wrong state, e.g. stopping a stopped agent; or the process holding it refused the command), 502 (the
log lines the holding process sent could not be read), 503 (Watchfire is not running in this process and no other process
can be reached, it is shutting down, or the commands table failed) or 500. A command for an agent in another process
answers with the holder’s own status for a refusal (404, 409, 503), 202 {"message"} when the holder took it but
has not finished within 5 s, 504 when no process took it within 5 s, and 429 when 20 commands wait for the agent
already. Every request with Authorization: Bearer <token> is accepted,
where the token is the hex HMAC-SHA256 of "watchfire-api" keyed with APP_KEY
(smeltery::watchfire::web::api_token(key)). Without the token only local development gets in:
WATCHFIRE_DASHBOARD=local, APP_ENV=local, an APP_URL on this machine (localhost, *.localhost or a loopback
address), and a request from a loopback address that did not come through a proxy in TRUSTED_PROXIES and carries
no reverse-proxy or CDN header (Forwarded, X-Forwarded-For, -Host, -Proto, -Port, -Server, X-Real-IP,
X-Original-Forwarded-For, X-Client-IP, Via, CF-Connecting-IP, True-Client-IP, Fastly-Client-IP), that
names this machine as its Host (localhost, *.localhost, a loopback address or the APP_URL host, so a page on
another domain that resolves to 127.0.0.1 gets nothing) and that no other site sent (an Origin other than the
app’s own, host and port, so another dev server on localhost:3000 is another site; more than one Origin; or a
Sec-Fetch-Site other than same-origin or none, is refused; a link followed to the dashboard page opens it). Pool members are addressed with #
encoded (fetcher%230). serve answers the API on the app’s own port; work answers it only when
WATCHFIRE_API_ADDR is set, with HTTP/1.1, at most 64 connections at once, 10 s for a request’s headers (also the
idle limit between requests) and X-Content-Type-Options: nosniff; bind it to 127.0.0.1.
Dashboard. GET /_watchfire is a page (a Mold template compiled into Watchfire, the same in debug and release
builds) with summary tiles (agents running, paused, failed or backing off, in standby; queue depth, dead letters and
the next scheduled run), every agent’s state, heartbeat (on time or stalled: whether the last heartbeat arrived
within the agent’s timeout), last heartbeat, restarts, runs (job runs of a queue worker included), the process that
runs it, pending backoff and next restart, last error and recent runs with their counters (run ids count per
process, so runs of an earlier process are marked as such), the queue counts and dead letters, and the schedule.
Each agent has the buttons its state allows (start; pause or resume; restart and stop): forms with @csrf posting
to /_watchfire/agents/{name}/{action}, which redirect back with a flash message. Stop and restart ask first: they
link to /_watchfire?agent=<name>&confirm=<action>, the page with that confirmation open (its form and a Cancel
link, which has the focus), rendered without the live panels and without the 5 s reload. The page is sent with
Cache-Control: no-store, X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none', so no other
site can frame it. The page brings its own stylesheet, embedded in Watchfire and served at
/_watchfire/assets/watchfire.css?v=<version> (to anyone, as it holds no data; 404 under off; cached for a year,
and the version changes with the file), so it needs nothing from the app: no app.css, no Tailwind, no web fonts,
no JavaScript besides Sparks. It uses the forge colours of new apps, follows the system’s light or dark mode, and
shows each agent as a card on narrow screens.
The dashboard is for signed-in users that the app’s gate admits, in app/agents/mod.rs:
use smeltery::watchfire::prelude::*;
pub fn register(w: &mut Watchfire) {
// `auth` is the visitor's sign-in (`auth.id()`, `auth.user::<User>().await?`), `app` the app.
w.dashboard_gate(|auth, _app| async move { Ok(auth.id() == Some(1)) });
}Without a gate no signed-in user gets in. Guests are sent to the login route (JSON clients get 401), a signed-in
user the gate refuses gets 403, and an error from the gate is a 500. With WATCHFIRE_DASHBOARD=local (default),
APP_ENV=local and a local APP_URL, the requests the API’s local rule admits (a loopback address, no
reverse-proxy header, a Host on this machine and no other site’s Origin; see the API) get in without signing in; auth asks for the gate under APP_ENV=local too; off hides the dashboard (404). The page, its forms and its
live panels follow the same rule. The dashboard is a web route, so it is mounted only when the app has a usable
APP_KEY.
When the app installs Sparks too (.agents(…) and .sparks(…), in either order), the dashboard is live: its
panels are two Spark components registered by Watchfire, watchfire.agents (the agents table) and
watchfire.queue (queue, dead letters, schedule), both streamed (#[spark(stream)]). Watchfire pushes a refresh of
the agents panel after status changes, at most one every 500 ms however busy the supervisor is, and of the queue
panel every 5 seconds, only while a dashboard is open. The buttons call the panel’s act(name, action) action
(with JavaScript, stop and restart first call ask(name, action) instead of following their link, which opens the
confirmation in the panel’s state, so a pushed refresh keeps it open; cancel closes it) through the Sparks update endpoint, which applies the same rule to actions and refreshes (401 for a guest, 403 for a
signed-in user the gate refuses, 404 when off); its update requests show no request headers, so local development
there also needs the session of a browser the page let in from a loopback address (any dashboard request the local
rule does not admit takes that back). In a process that does not run an agent, the panels check the shared tables
every 2 seconds while a dashboard is open and refresh when they changed. The page is rendered on the
server first, so it reads without JavaScript; then the forms post as before (stop and restart lead to the
confirmation page) and a <noscript> meta tag reloads the page every 5 seconds. Without Sparks the page reloads itself every 5 seconds (<meta http-equiv="refresh">).
Console. agents:list, agents:start|stop|pause|resume|restart <name> and agents:logs <name> call the running
app’s API (at WATCHFIRE_API_ADDR, else SERVER_HOST:SERVER_PORT) with the token, with a 10 s timeout, following no
redirect; when nothing answers they say so and how to start the app. They refuse to send the token over plain
http:// to an address that is not this machine (set a loopback WATCHFIRE_API_ADDR or an https:// URL). They
print control characters from the app (terminal escape sequences in log lines) as �. agents:token prints the
token. The token is derived from APP_KEY: a new APP_KEY is the way to revoke it (it also signs every user out
and invalidates signed Spark state).
Alerts. An agent becoming failed (its run failed under Restart::Never, or it reached its restart limit), a
stalled run, and a job moved to the dead letters each raise an alert: an error-level log line (target
smeltery_watchfire::alert), every w.on_alert(|alert| async move { … }) hook (one at a time, at most 10 s each,
in a task of their own, so supervision never waits), and a POST of the alert as JSON to WATCHFIRE_ALERT_WEBHOOK
(10 s timeout, retried up to 3 times; a failed delivery is logged with the webhook’s host only), and a mail to the addresses in WATCHFIRE_ALERT_MAIL (subject
[APP_NAME] Watchfire alert: <kind> <agent>) when the app has .mail(). An Alert has kind (failed, stalled, dead_letter), app, agent,
job, message and at_ms.
LLM helpers (the llm feature: smeltery = { …, features = ["llm"] }). smeltery::watchfire::llm has the
Provider trait (complete(Request) -> Response with the system prompt, messages, tool definitions, the answer’s
content blocks, stop reason and input / output token usage), FakeProvider (scripted replies and tool calls, every
request recorded), Anthropic (the Messages API through ctx.http(), the key from ANTHROPIC_API_KEY, the model and
max_tokens set in AnthropicConfig; its calls follow no redirect, so the key and the prompt go only to the base URL,
and its Debug output hides the key) and Agent, a tool-calling loop:
use smeltery::watchfire::llm::{Agent, Anthropic, AnthropicConfig, Budget, Price};
#[derive(serde::Deserialize)]
struct Lookup { symbol: String }
let claude = Anthropic::from_env(ctx.http().clone(), AnthropicConfig::new("claude-opus-5-5", 16_000))?;
let outcome = Agent::new(claude)
.system("You answer questions about stock prices.")
.tool("price", "The latest price of a stock symbol",
serde_json::json!({"type": "object", "properties": {"symbol": {"type": "string"}}, "required": ["symbol"]}),
|input: Lookup| async move { Ok(format!("{}: 42.00", input.symbol)) })
.max_turns(8)
.budget(Budget::new().max_tokens(200_000).max_cost(1.0).price("claude-opus-5-5", Price::per_mtok(4.0, 20.0)))
.cancel_on(ctx.token().clone())
.run("What does ACME trade at?")
.await?;
ctx.log().info(outcome.text);Tool calls of one answer run in order and their results go back in one message; a tool error, an input that does
not match the tool’s type, or an unknown tool goes back to the model as an error result. The loop stops with
MaxTurns after max_turns model calls (default 10) and with BudgetExceeded once the tokens or the cost (from the
prices you give per model) pass the budget. Rate limits (429), overload (529), 5xx answers and network errors are
retried (default 3 times, backoff 1 s..=30 s with jitter, honouring retry-after); other errors are not.
Testing. TestApp leaves Watchfire off (dispatched jobs wait in the queue); TestApp::new(build).with_agents()
starts it. smeltery::watchfire::testing::Harness runs agents under the real supervisor on paused Tokio time with a
fake HTTP transport (http::FakeTransport: canned answers by method and URL, every request recorded):
use smeltery::watchfire::prelude::*;
use smeltery::watchfire::testing::Harness;
// In a #[tokio::test(start_paused = true)] function:
let mut h = Harness::new(agent_fn("flaky", |ctx: AgentCtx| async move {
ctx.sleep(1.secs()).await;
Err(AgentError::msg("boom"))
}))
.config(AgentConfig::default().backoff(1.secs()..=8.secs()));
h.start().await.unwrap();
h.advance(1.secs()).await;
assert_eq!(h.state(), AgentState::BackingOff);
assert!(h.next_backoff().unwrap() <= 1.secs());
h.advance(10.secs()).await;
assert!(h.restarts() >= 1);
assert_eq!(h.runs().await[0].outcome, RunOutcome::Failed);
h.shutdown().await;Harness also has transitions() (every state in order), runs(), logs(), stop(), agents() and
Harness::from_watchfire(w) for a whole registration; JobHarness::new().await.run(&job) runs a job’s handle
(JobHarness::for_app(app).await runs it inside a given app, e.g. a TestApp’s with its database and services)
directly.
Mail (smeltery::mail) is wired with .mail() in bootstrap/app.rs (the trait is smeltery::mail::MailExt, in
the prelude). A mail class is a Mold template struct that also implements Mailable: the template is the HTML body,
the struct’s fields are its variables, and envelope() says who gets it.
smeltery make:mail Welcome creates app/mail/welcome.rs and resources/views/mail/welcome.mold.html (an HTML mail
with inline styles) and adds the module to app/mail/mod.rs; new apps install mail and have the MAIL_* keys in
.env.
use smeltery::prelude::*;
#[derive(Mold)]
#[mold("mail/welcome")] // resources/views/mail/welcome.mold.html
pub struct Welcome {
pub name: String,
pub email: String,
}
impl Mailable for Welcome {
fn envelope(&self) -> Envelope {
Envelope::new()
.to(self.email.as_str()) // also "Ada <ada@example.com>" or ("ada@example.com", "Ada")
.subject(format!("Welcome, {}!", self.name))
}
}
async fn register(mailer: Mailer, Form(form): Form<RegisterForm>) -> Result<Redirect> {
mailer.send(Welcome { name: form.name, email: form.email }).await?;
Ok(Redirect::to("/"))
}Envelope has to, cc, bcc, reply_to, from (instead of MAIL_FROM_ADDRESS / MAIL_FROM_NAME) and
subject. Besides envelope(), a Mailable may implement text() (the plain-text part, e.g. from a second
template rendered with smeltery::mail::render; by default it is made from the HTML: tags dropped, links as
text (url)) and attachments() (Attachment::from_bytes(name, bytes), Attachment::from_path(path)). Mail
templates render like views (from the files with hot reload in debug builds, compiled in release builds);
route("name") gives absolute URLs (APP_URL + path) in mail.
Mailer is a handler argument, or Mailer::of(&app) elsewhere: send(mail) renders on a blocking thread and
hands the mail to the transport, render(mail) returns the rendered Email, and send_email(email) sends an
Email built by hand (Email::new(envelope).html(…).text(…).attach(…)). With Watchfire, mailer.queue(mail) /
queue_later(mail, delay) (the trait smeltery::watchfire::mail::QueueMail, in the prelude) render the mail now
and send it from a queue worker, retried like any job (the job smeltery-send-mail is registered when the app has
both .mail() and .agents(…)).
| Variable | Default | Meaning |
|---|---|---|
MAIL_MAILER | log | smtp, log (the mail is written to the log at info, target smeltery::mail: sender, recipients, subject and text part; outside local development (APP_ENV local or testing with an APP_URL on this machine) only sender, recipients and subject, with a note that the body was withheld because it can carry secrets such as reset links, and a warning at boot) or fake; always fake under APP_ENV=testing |
MAIL_HOST | 127.0.0.1 | the SMTP server |
MAIL_PORT | 465 for tls, 587 for starttls, 25 for none | its port |
MAIL_USERNAME, MAIL_PASSWORD | empty | the SMTP login (none when the username is empty); the password is never logged |
MAIL_ENCRYPTION | starttls | tls (TLS from the start), starttls (an upgrade the server must offer), none (plain SMTP; with a MAIL_USERNAME only for a MAIL_HOST on this machine, since the password would cross the network in clear: anywhere else the mailer refuses to start) |
MAIL_TLS_CA | empty | a PEM file (relative to the app root) of extra CA certificates to trust, for an SMTP server with a private CA |
MAIL_TIMEOUT | 10 | seconds per SMTP step; a whole send gives up after four times that |
MAIL_FROM_ADDRESS, MAIL_FROM_NAME | hello@example.com, APP_NAME | the default sender |
SMTP runs on lettre’s Tokio transport with rustls (ring) and the platform’s certificate verifier; MAIL_TLS_CA
adds certificates to the platform’s trusted roots. A server certificate that is not trusted fails the send before
any login. A failed send is an error for the caller and a warn log line.
Testing: under APP_ENV=testing mail goes to a fake mailbox: Mailer::of(app.app())?.mailbox() (or
Mailer::fake(app.app()) on an app without .mail()) returns it, with sent(), emails(),
sent_of::<Welcome>(), assert_sent::<Welcome>(|mail, email| mail.name == "Ada"), assert_sent_count::<T>(n),
assert_sent_to(address) and assert_nothing_sent().
§Bellows: AI-agent support
Bellows makes an app ready for coding agents. Each part is chosen with smeltery new … --bellows (or the question)
and can be added to an existing app with smeltery bellows:install:
| Part | Files | What it gives an agent |
|---|---|---|
| MCP server | .mcp.json | the app’s own MCP server, smeltery bellows:mcp |
| Skills | .bellows/skills/*.md | step-by-step guides: crud-resource (web apps), spark (Mold apps), alloy-page (React and Vue apps), auth-route (web apps with authentication), migration, mail, agent (apps with agents) |
| Guidelines | .bellows/guidelines.md | the app’s conventions |
Every new app also has CLAUDE.md and AGENTS.md (the same text): the layout, the conventions, the commands and
generators, and which Bellows parts are installed. In React and Vue apps they and the skills describe the kit
(Alloy pages, useForm, partial reloads, deferred props); bellows:install reads the kit from the app’s Cargo.toml.
bellows:mcp is an app command: bootstrap/app.rs calls .bellows(), and smeltery bellows:mcp runs the app
binary with it. It speaks JSON-RPC 2.0 over stdin / stdout, one message per line (MCP’s stdio transport), answers
initialize (protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05), server/discover
(2026-07-28), ping, tools/list and tools/call, and writes nothing else to stdout (logs go to stderr).
Requests run one at a time, in order; while one runs, ping is answered and notifications/cancelled stops it (a
running cargo test or generator is killed). A line longer than 1 MiB gets a parse error and is skipped. Tool results
hold the app’s data, log lines, test and compiler output and documentation files; the server’s instructions tell the
agent to treat them as data, not as instructions.
| Tool | Answers |
|---|---|
route_list | every route: methods, path, name, middleware |
models | the models in app/models/ with their table’s columns, and tables without a model |
db_schema | tables with columns (type, nullable, default, primary key) and indexes; table for one table (SQLite, PostgreSQL, MySQL) |
config_keys | the names of the keys in .env, .env.example and the framework’s settings; values are never returned |
last_errors | the latest ERROR lines of the app’s log file, LOG_FILE and its .1 backup, else storage/logs/*.log (limit, default 20; warnings: true adds WARN lines); at most 20 files, lines cut at 2,000 characters, 12,000 characters in all |
docs_search | the sections of this guide (embedded), the app’s CLAUDE.md and .bellows/ files that match the words |
run_generator | one smeltery make:* command (only the generators; SMELTERY_BIN picks the binary), stopped after 60 s; the arguments are names, fields (title:string, body:text?) and the generators’ options, nothing else |
run_tests | cargo test [filter], stopped after BELLOWS_TEST_TIMEOUT seconds (600); the result lines and failures. The filter is a test path (letters, digits, _, :, at most 200 characters). The tool compiles and runs the app’s code, its build scripts and its tests |
agents_list, agent_control | the running app’s Watchfire agents, and start / stop / pause / resume / restart, through its API with the token derived from APP_KEY (like agents:*) |
smeltery bellows:install [--mcp] [--skills] [--guidelines] [--all] writes the missing files and keeps existing
ones; when .mcp.json exists with other servers, it adds the smeltery entry to its mcpServers object.
§Errors
Return smeltery::Error from a handler: Error::not_found(), forbidden(), unauthorized(), bad_request(msg),
http(status, msg), internal(msg), validation(field, msg) (see Validation), or any error
through ? (std::io::Error, serde_json::Error, Error::other(e)). The client gets an HTML error page, or {"error": "…"} when it sent Accept: application/json.
Internal errors are logged; their details appear in the page only with APP_DEBUG=true. A panicking handler answers
500.
§The server
smeltery serve (or the app binary with serve) binds SERVER_HOST:SERVER_PORT. Every response carries an
x-request-id. Requests are traced with tracing. On Ctrl-C or SIGTERM the server stops accepting connections and
drains in-flight requests for up to SHUTDOWN_TIMEOUT seconds. Watchfire’s agents stop within the same budget, and
so do password reset mails still being sent.
Connections: a client has SERVER_HEADER_TIMEOUT seconds (30) to send a request’s headers, and a connection
with no request running for that long is closed: before its first request, between two HTTP/1 requests, and on an
HTTP/2 connection (cleartext HTTP/2 with prior knowledge is served too), which gets a GOAWAY. A request counts as
running until its response body is sent, so a long download or an event stream keeps its connection. At most
SERVER_MAX_CONNECTIONS (4096) connections are open at once; further clients wait to be accepted (each connection
is a file descriptor, so the process’s open-file limit stays above it). One client address holds at most
SERVER_MAX_CONNECTIONS_PER_IP (128) of them (an IPv6 client by its /64); a further connection from it is closed at
once. The same address runs at most SERVER_MAX_CONNECTIONS_PER_IP requests at once across its connections (HTTP/2
carries many requests on one connection); a further request gets 429 with Retry-After: 1. One HTTP/2 connection
runs at most SERVER_MAX_STREAMS (32) requests at once; further ones wait for a free stream. Peers listed in
TRUSTED_PROXIES are not counted per address, since a proxy carries many clients: list the
proxy there when the app runs behind one. REQUEST_TIMEOUT counts from when the server
takes the request, reading a form body for its _method field included, so a body that trickles in gets a 408 like
a slow handler. serve and work refuse to start under APP_ENV=testing.
Upgraded connections (WebSockets): HTTP/2 WebSockets (extended CONNECT) are not offered, so clients and proxies
upgrade over HTTP/1.1. A route that upgrades a connection itself checks the handshake’s Origin: browsers open
WebSockets to any site and send the cookies their SameSite rules allow (a page on a sibling subdomain of the same
site included), and a WebSocket handshake is a GET, which the CSRF check does not cover. Compare it with the
origin of APP_URL (scheme, host and port) and answer 403 to any other origin before the upgrade.
Anvil does this with ANVIL_ALLOWED_ORIGINS.
Request log: at LOG_LEVEL=debug every request gets a span with its method, URI, HTTP version and client IP.
The URI never shows secrets: a path segment of a route parameter whose name contains token, secret, signature,
password, hash or key (such as /reset-password/{token}), every query value and every query item without a
value appear as [redacted], so /reset-password/abc?email=a@b.test is logged as
/reset-password/[redacted]?email=[redacted]. Secret segments are found in mangled links too (repeated or trailing
slashes, other letter case, percent-encoded characters).
Compression: responses are compressed with brotli or gzip when the client sends Accept-Encoding, except
server-sent event streams (text/event-stream, such as the Sparks and Watchfire streams), images other than SVG,
formats that are compressed already (font/woff, font/woff2, zip, gzip, 7z, rar and zstd archives, PDF, video/*,
audio/*), responses under 32 bytes, range responses and responses that already have a Content-Encoding. A
compressed response’s ETag is weak (W/"…"), so it is never mistaken for the uncompressed bytes; If-None-Match
still answers 304. The CSRF token in pages is masked per response (see CSRF), so compressed HTTPS pages do
not leak it through their size (BREACH).
Security headers: every response (pages, API routes, files from public/, error pages, /up) carries
X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, X-Frame-Options: SAMEORIGIN
and Content-Security-Policy: frame-ancestors 'self', so other sites cannot show the app’s pages in a frame.
FRAME_OPTIONS=DENY sends DENY and frame-ancestors 'none' (no frames at all), FRAME_OPTIONS=off neither
header; SECURITY_HEADERS=false sends none of the four. A header the response already has, set by its handler or a
middleware, is never replaced: the Watchfire dashboard keeps its DENY. A response with its own X-Frame-Options
gets no Content-Security-Policy from the framework, and a response’s own Content-Security-Policy is kept as it is,
so a page that a partner site may frame sends Content-Security-Policy: frame-ancestors https://partner.example
(browsers follow frame-ancestors over X-Frame-Options).
HSTS_MAX_AGE (seconds, 0 by default) adds Strict-Transport-Security: max-age=… to every response when APP_URL
starts with https://, whatever SECURITY_HEADERS says; with an http:// APP_URL it is not sent and the app logs
a warning at boot. A browser that has seen the header refuses plain HTTP for the domain until max-age runs out, so
it is set once HTTPS works for the domain, and lowering it later only reaches browsers that visit again.
CORS (hybrid and cross-origin clients): a page or app on another origin (a Capacitor app is
capacitor://localhost, a Tauri app tauri://localhost or http://tauri.localhost, an Electron app the scheme it
registers, a front end on another host) may call the app’s API when its origin is listed in CORS_ALLOWED_ORIGINS:
CORS_ALLOWED_ORIGINS=capacitor://localhost,tauri://localhost,http://tauri.localhost
CORS_PATHS=/api/- Origins are compared exactly (scheme, host and port).
*, wildcards and entries with a path stop the app at boot. - A preflight (
OPTIONSwithAccess-Control-Request-Method) from a listed origin to a path underCORS_PATHSis answered204before routing, withAccess-Control-Allow-Origin(that origin), the requested method,Access-Control-Allow-Headers: Accept, Authorization, Content-Type, X-Requested-With, X-Socket-ID, X-CSRF-TOKENandAccess-Control-Max-Age: 600. Other requests from it getAccess-Control-Allow-Origin, the framework’s own answers included (the408ofREQUEST_TIMEOUT, the500of a panic, error pages). - Every answer under
CORS_PATHScarriesVary: Origin, whatever the origin, so a shared cache keeps the answers for different origins apart. - Credentials are never allowed (no
Access-Control-Allow-Credentials): a page on another origin cannot read an answer to a request made with cookies, and the browser refuses to send a preflighted one, so these clients call the API with a bearer token (see API tokens). - Requests from origins that are not listed, and paths outside
CORS_PATHS, get noAccess-Control-Allow-Origin; the browser blocks their answers. CORS_PATHSentries are prefixes compared as text: end each with/(/apiwould also cover/apiary; a prefix without the/is warned about at boot).- A front end on another origin cannot use the session through CORS (no credentials): serve it from the app’s own origin (or behind a proxy that puts both under one origin), or have it call the API with bearer tokens.
null(sent by sandboxed frames, pages opened from files, and some app shells) is allowed only when it is listed literally; then every page that sendsnullis allowed, from any site.- The listed origins may also open Anvil sockets.
Behind a reverse proxy: the client of a request is smeltery::http::ClientInfo, a handler argument:
use smeltery::http::ClientInfo;
async fn whoami(client: ClientInfo) -> String {
let ip = client.ip().map_or_else(|| "unknown".to_owned(), |ip| ip.to_string());
format!("{ip} over {} to {}", client.scheme(), client.host().unwrap_or("?"))
}By default it is the TCP peer, and X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host are ignored. List
the proxy in TRUSTED_PROXIES (TRUSTED_PROXIES=127.0.0.1 for nginx or Caddy on the same host, CIDR ranges such as
10.0.0.0/8 for a load balancer network). For a request whose TCP peer is listed:
ip()is the rightmostX-Forwarded-Foraddress that is not itself a listed proxy (the addresses left of it were written by the client and are never used). When every address in the header is a listed proxy,ip()is the rightmost one (the address the nearest proxy saw). When that walk meets a hop that is not an IP address,ip()isNone(auth.ip()isunknown), never the proxy’s own address; without the header it is the proxy’s address;scheme()/is_secure()follow the firstX-Forwarded-Protovalue (httporhttps);host()is the firstX-Forwarded-Hostvalue, else theHostheader.
host() and scheme() are only as trustworthy as the proxy’s configuration: the proxy must set (overwrite)
X-Forwarded-Host and X-Forwarded-Proto itself, otherwise the client’s own values pass through. Caddy sets both;
for nginx:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;Smeltery builds its own absolute URLs (password reset links, mail) from APP_URL, never from host(). Back (the
previous page) accepts a Referer on the client’s host or on APP_URL’s host.
TRUSTED_PROXIES=* trusts whatever peer connects, but not the addresses inside X-Forwarded-For: the client is the
address the proxy appended. Use * only when nothing but the proxy can reach the app (it listens on 127.0.0.1, a
private network or a firewalled port); a client that reaches the app directly can then send any forwarded header. An
entry that is not an IP address, a CIDR range or *, and a range of every address (0.0.0.0/0, ::/0, which would
let any client name its own address), stop the app at boot with the entry named. The login throttle,
auth.ip() and the request log use ClientInfo’s IP. The Secure flag of cookies follows APP_URL only.
§The smeltery command
| Command | Does |
|---|---|
smeltery new <name> | create an app (questions or flags, see above) |
smeltery serve | run the app (work instead of serve in a headless app, which has no routes/), restart it when Rust files change, run Tailwind in watch mode when it is installed (TAILWIND_BIN, the binary of smeltery tailwind:install, or tailwindcss on PATH); in a React or Vue app (one with vite.config.ts) run the Vite dev server instead (node node_modules/vite/bin/vite.js, SMELTERY_NODE overrides node; without node_modules/ a warning) and delete storage/framework/vite.hot when it stops |
smeltery work | run the app’s Watchfire agents, queue workers and scheduler without the HTTP server, until Ctrl-C / SIGTERM (then they stop within SHUTDOWN_TIMEOUT) |
smeltery agents:list | print the running app’s agents (through its Watchfire API, see below) |
smeltery agents:start / stop / pause / resume / restart <name> | control an agent of the running app through its API |
smeltery agents:logs <name> | print an agent’s last log lines from the running app |
smeltery agents:token | print the app’s Watchfire API token |
smeltery agents:runs <name> | print an agent’s latest runs from the database: run id, start, duration, outcome, job, error, counters (--limit N) |
smeltery schedule:list | print the scheduled tasks: name, kind, expression, next run (UTC) |
smeltery schedule:run | run the scheduled tasks due this minute once and exit |
smeltery route:list | print every route: method, path, name, middleware |
smeltery migrate | run the pending migrations (--force in production) |
smeltery migrate:rollback | revert the last batch of migrations; --step N reverts the last N |
smeltery migrate:fresh | drop every table and run every migration; --seed then seeds |
smeltery migrate:status | list the migrations with Ran / Pending and their batch |
smeltery db:seed | run the seeders; --class Name runs one (--force in production) |
smeltery cache:clear [store] | remove every entry of the default cache store, or of the named one (cache:clear redis), except Watchfire’s leases and schedule claims (--all: those too) |
smeltery key:generate | write a new APP_KEY into .env (--show prints one instead and reads no .env); with APP_ENV=production (or no APP_ENV) an existing key is kept unless --force is given, since a new key signs every user out |
smeltery storage:link | link public/storage to storage/app/public; when that link is already there it says so and exits with 0, and anything else at public/storage is an error |
smeltery test | run the app’s tests |
smeltery build | build public/assets/css/app.css from resources/css/app.css with tailwindcss --minify when Tailwind is installed (found as for serve; otherwise it prints a warning and builds on, and a failing Tailwind fails the build), then the release binary; in a React or Vue app instead of Tailwind: npm ci (or npm install without a package-lock.json) when node_modules/ is missing, then npm run build into public/build/ (SMELTERY_NPM overrides npm; without npm, or when a step fails, the build fails before cargo runs) |
smeltery tailwind:install | download the pinned Tailwind CSS standalone binary into the per-user folder (see Pages and CSS); a binary already there with the right checksum is kept |
smeltery make:model <Name> [field:type ...] | create a model in app/models/; fields are name:type with the types string, text, integer, bigint, bool, float, date, datetime, json, uuid, <name>_id:foreign, file (an upload: the forms post multipart/form-data with a file input, the controller stores the file in storage/app/public/<table>/ and the column holds its path under storage/app/public; its form rule mimes accepts jpg, jpeg, png, gif and webp when a part of the field’s name says image (image, img, photo, picture, pic, avatar, logo, thumbnail, thumb, icon, cover, banner, poster: image, cover_image), else those and pdf, txt, csv, docx, xlsx; add types to the rule in the controller as needed, never html, svg, xml or js, which a browser runs as a page of the app), and a trailing ? for nullable (body:text?). Flags: -m migration, -c controller, -r resource controller with views (in a React or Vue app: pages, see The React and Vue starter kits) and routes, -f factory, -s seeder, --all (-mrfs), --searchable (in an app with the search building block: impl Searchable, the search index migration, the registration in app/providers/search.rs, and with -r a list page that searches, see Create an app) |
smeltery make:controller <Name> | create a controller with an index view and a GET route; --resource [--model Post] creates the seven resource actions (validated with Valid<…Form>, flash messages), their views (forms with @csrf, @error and old()) and the r.resource(...) route entries: in an app with authentication index and show are public and create, store, edit, update and destroy need a signed-in user (.middleware("auth")); without authentication all seven are public, as the comment above them, the controller’s module doc and the generator’s note say; in a React or Vue app the controller returns Alloy pages and the generator writes them under resources/js/pages/. In an app without routes/web.rs (headless) it refuses and writes nothing, and make:model -c/-r makes the other parts and skips the controller |
smeltery make:migration <name> | create a migration: create_posts_table creates a table (down drops it), add_slug_to_posts_table adds a nullable slug column (down drops it with ALTER TABLE … DROP COLUMN), any other name gives empty up / down |
smeltery make:seeder <Name> | create a seeder in database/seeders/ and register it |
smeltery make:factory <Name> [--model Post] | create a factory in database/factories/ filling every field of the model with fake values |
smeltery make:command <Name> | create a console command in app/commands/ and register it (SendReport runs as smeltery send-report) |
smeltery make:mail <Name> | create a mail class in app/mail/ and its HTML template resources/views/mail/<name>.mold.html, and print how to send it |
smeltery make:middleware <Name> | create a middleware function in app/middleware/ and print how to register it |
smeltery bellows:install [--mcp] [--skills] [--guidelines] [--all] | add Bellows files to the app (.mcp.json, .bellows/skills/, .bellows/guidelines.md); existing files are kept |
smeltery pubsub:install | add the migration of the pubsub_messages table (the database driver of PubSub) to database/migrations/ and register it; refuses when the app has it already |
smeltery prospect:install | add Search to a web app: app/providers/search.rs (where make:model --searchable registers models) and its mod line; it prints the bootstrap/app.rs lines to add (use smeltery::prospect::ProspectExt as _; and .prospect(app::providers::search::register)) and PROSPECT_DRIVER=database; it refuses when bootstrap/app.rs already calls .prospect( and in a headless app |
smeltery hallmark:install | add API tokens to an app with authentication: the personal_access_tokens migration, app/controllers/api/{tokens,user}.rs, the three token routes in routes/api.rs, tests/api_tokens.rs and, with Watchfire, the daily hallmark-prune schedule, as smeltery new writes them with the hallmark block; it prints the two bootstrap/app.rs lines to add (use smeltery::hallmark::{Hallmark, HallmarkExt as _}; and .hallmark(Hallmark::new())) and the optional .env lines; it refuses in an app without authentication and when the migration or a file exists |
smeltery bellows:mcp | run the app’s MCP server on stdin / stdout (for coding agents; see Bellows) |
smeltery make:spark <Name> | create a Spark in app/sparks/ with its view resources/views/sparks/<name>.mold.html and register it in app/sparks/mod.rs; refuses in React and Vue apps. --listen <channel> --event <Event> (an app with Anvil) makes it a listener: a #[spark(stream)] component whose method #[on("anvil:<channel>", "App\\Events\\<Event>")] counts the events (--event order.shipped takes a name as sent), a field per {field} of the channel (i64 for id / *_id, else String) set from the page’s props in mount, and an event struct to fill; it refuses without .anvil( in bootstrap/app.rs and for a channel name Anvil does not accept |
smeltery make:page <Name> | in a React or Vue app: create a page (resources/js/pages/about.tsx, Vue: About.vue), its controller app/controllers/about.rs and the route GET /about; refuses in Mold and headless apps |
smeltery make:agent <Name> | create a Watchfire agent in app/agents/ (restart on failure with backoff, heartbeat timeout, a 30-second tick loop) and register it with w.agent(...); in an app without Watchfire (no app/agents/mod.rs) it refuses and writes nothing |
smeltery make:job <Name> | create a queued job in app/jobs/ and register it with w.job::<...>() in app/agents/mod.rs; in an app without Watchfire it refuses and writes nothing |
The make:* commands create new files only: they refuse when a target file exists, and they add pub mod and
registration lines above the // smeltery:… marker comments, laid out as cargo fmt lays them out. When a marker is
missing they print the line to add by hand. The Rust files they create go through rustfmt --edition 2024 (RUSTFMT
picks another binary; the app’s rustfmt.toml applies); without rustfmt the files stay as written and a note says
to run cargo fmt.
smeltery new on a terminal shows a SMELTERY banner in block letters, one section per question, a
✓ line per created folder, a spinner while migrate and db:seed build and run the app, and a summary box with
the choices, the one-line command and the next steps. Errors and warnings carry coloured ERROR / WARN labels.
Output is plain text, without colours, banner or spinner, when stdout is not a terminal, when NO_COLOR is set, or
with --no-color (accepted by every command).
Commands that need the app’s code (route:list, migrate…, db:seed, work, agents:…, schedule:…, the
app’s own commands, serve of the app binary itself) run inside the app: the smeltery command forwards them to cargo run -- <command>, and the release
binary accepts the same commands. The release binary also has key:generate (with --show and --force) and
storage:link, the same code as the smeltery commands, so a server needs no smeltery CLI: ./my-app key:generate,
./my-app storage:link, ./my-app migrate --force.
§Testing
use smeltery::testing::TestApp;
async fn home() -> &'static str { "Hello" }
// In tests/http.rs, inside a #[test] function:
let app = TestApp::new(|app| app.routes(|r| { r.get("/", home); }));
let res = app.get("/");
assert_eq!(res.status(), 200);
assert_eq!(res.text(), "Hello");TestApp::new(build) builds the whole app (all middleware, error pages and static files) with APP_ENV=testing;
get, get_json, post_form, post_json, post_multipart and request send requests without a server
(post_multipart(url, &[("title", "Sea")], &[TestFile::new("image", "sea.png", bytes)]); TestFile::with_mime
sets the content type, and testing::multipart_body builds such a body for request). A generated app’s
tests/http.rs uses it with the app’s own build. Like a browser, a TestApp keeps the cookies responses set and
sends them with later requests, so sessions and flash messages work across requests; cookie(name),
set_cookie(name, value) and clear_cookies() reach the jar. app.acting_as(user_id) signs a user in for the
following requests, and .with_csrf() turns the CSRF check on. app.with_header(name, value) sends a header with
every following request (a header given to request itself wins), app.without_header(name) stops it, and
app.with_bearer(token) sends Authorization: Bearer <token>.
Each TestApp has its own database: TEST_DATABASE_URL when it is set, otherwise (with the sqlite feature) a
fresh in-memory SQLite database, otherwise DATABASE_URL. Before TestApp::new returns it drops every table and runs
every registered migration, so each test starts with an empty, migrated database. app.db() is the handle for
creating data, and app.block_on(future) runs async calls:
let app = TestApp::new(my_app::build);
let post = app.block_on(PostFactory.create(&app.db())).unwrap();
assert_eq!(app.get(&format!("/posts/{}", post.id)).status(), 200);§Deployment
A Smeltery app runs on a server as one program: the release binary, started by systemd, behind Caddy or nginx for
HTTPS. This section walks through it on Ubuntu 24.04; the commands use the app name myapp, the folder
/srv/myapp and the domain app.example.com.
§What goes on the server
| Item | What it is |
|---|---|
myapp | the release binary (target/release/myapp) |
.env | the production settings (or the same keys in the process environment, which win over .env) |
public/ | the static files, including the built public/assets/css/app.css (in a React or Vue app: public/build/, the output of npm run build) |
storage/ | uploads, logs, file sessions and the file cache; writable, kept across deploys; its folders are created when first needed |
database/ | the SQLite file and its -wal / -shm files (SQLite apps only); writable, kept across deploys |
Everything else is compiled into the binary: the routes and controllers, the migrations and seeders, the Mold views
and mail templates (release builds render compiled templates), the Sparks components and sparks.js, and the
Watchfire dashboard. Running it needs no resources/, no Rust sources and no Cargo. The binary also runs the
setup commands, so the server needs no smeltery CLI: ./myapp key:generate, ./myapp storage:link,
./myapp migrate --force (see The smeltery command).
The app root is the working directory (or SMELTERY_ROOT): .env, public/, storage/, LOG_FILE and a relative
SQLite path are read from there.
§Build
smeltery buildIt builds public/assets/css/app.css with Tailwind (--minify) when Tailwind is installed (see
Pages and CSS; without it the committed app.css is kept) and then runs cargo build --release.
app.css is a normal file of the app, so a plain cargo build --release with the committed app.css gives the same
result. In a React or Vue app it runs npm run build instead (installing the packages first when node_modules/ is
missing), which writes the JavaScript, the CSS and manifest.json into public/build/; this needs Node.js on the
build machine, not on the server.
The binary runs on the OS it was built for: build a Linux server’s binary on Linux. Two ways:
-
On the server. Install Rust (
rustup, Rust 1.94 or newer) and a C compiler, then build in a checkout of the app:sudo apt install build-essential git curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh cargo build --release -
On another Linux machine (a CI runner, or WSL on Windows), with the same tools, then copy the binary. It links the system C library (glibc) dynamically, so build on the server’s Ubuntu release or an older one.
The C compiler builds ring (TLS) and the bundled SQLite. OpenSSL is not used: TLS is rustls, so neither the build
nor the server needs OpenSSL. For outgoing TLS (SMTP, ctx.http(), Redis over rediss://) the server needs the OS
certificate bundle (ca-certificates, installed on Ubuntu by default).
§React and Vue apps
smeltery buildrunsnpm run build, which writespublic/build/(the hashed JavaScript and CSS andmanifest.json); deploy it withpublic/. The server needs no Node.js, nonode_modules/and noresources/js/. A release binary started withoutpublic/build/manifest.jsonlogs an error when it starts serving, and its pages load without their scripts.- After a deploy with new assets, open pages notice the new asset version on their next visit and load the new
build (a
409withX-Inertia-Location). - Serve the app over HTTPS: the browser encrypts the history of pages (
encrypt_history, which the kits with authentication turn on) only in a secure context, and theXSRF-TOKENcookie getsSecurewhenAPP_URLstarts withhttps://. - Every web response sets the
XSRF-TOKENcookie, so every visitor gets a session, anonymous visitors and bots included; withSESSION_DRIVER=databasethat is one row insessionsper visitor without a cookie (expired rows are removed as with any session).
§Server layout
A system user without a login shell runs the app. It reads the app’s files and writes only storage/ and
database/:
sudo useradd --system --home-dir /srv/myapp --shell /usr/sbin/nologin myapp
sudo mkdir -p /srv/myapp/storage /srv/myapp/database
# copy the binary and public/ (see "Updating" for rsync / scp), then:
sudo chown -R root:root /srv/myapp
sudo chown -R myapp:myapp /srv/myapp/storage /srv/myapp/database
sudo chmod 750 /srv/myapp/storage /srv/myapp/database
sudo chmod 755 /srv/myapp/myapp
sudo chmod -R u=rwX,go=rX /srv/myapp/public
sudo install -o root -g myapp -m 640 /dev/null /srv/myapp/.env| Path | Owner | Mode | Why |
|---|---|---|---|
/srv/myapp/myapp | root | 755 | the app cannot replace its own binary |
/srv/myapp/.env | root:myapp | 640 | holds APP_KEY and passwords; only the app’s group reads it |
/srv/myapp/public/ | root | folders 755, files 644 | served read-only |
/srv/myapp/storage/ | myapp | 750 | uploads, logs, sessions, cache: no other local user may read them |
/srv/myapp/database/ | myapp | 750 | SQLite creates the file and its -wal / -shm files here (0600); they hold password hashes and sessions |
On Unix Smeltery creates its own files private: the SQLite database 0600, the log 0640, cache entries and
session files 0600, and the log and cache folders it creates 0750 and 0700. The systemd unit below also sets
UMask=0027 for everything else the process writes. A database.sqlite from an older setup keeps its mode:
sudo chmod 600 /srv/myapp/database/database.sqlite*.
§Production .env
Edit it with sudo nano /srv/myapp/.env:
APP_NAME="My App"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://app.example.com
APP_KEY=
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
TRUSTED_PROXIES=127.0.0.1
SHUTDOWN_TIMEOUT=30
LOG_LEVEL=info
LOG_FILE=storage/logs/smeltery.log
DATABASE_URL=sqlite://database/database.sqlite?mode=rwc
SESSION_DRIVER=database
SESSION_LIFETIME=120
CACHE_STORE=database
STATIC_CACHE_CONTROL=no-cache
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=starttls
MAIL_USERNAME=postmaster@example.com
MAIL_PASSWORD="the SMTP password"
MAIL_FROM_ADDRESS=hello@example.com
MAIL_FROM_NAME="My App"
WATCHFIRE_DASHBOARD=authThen the key: print a new one and paste it after APP_KEY=:
cd /srv/myapp && ./myapp key:generate --show--show only prints a fresh key: it reads no .env and writes nothing, so any user can run it. (sudo ./myapp key:generate without --show writes the key into .env itself and keeps the file’s owner, group and mode; with
APP_ENV=production (or without APP_ENV) it does so only while APP_KEY is empty, unless --force is given.)
| Key | Production value | Why |
|---|---|---|
APP_ENV | production | migrate, migrate:rollback, migrate:fresh and db:seed refuse to run without --force; key:generate keeps an existing key; the seeder of new apps creates no demo user; the log mailer withholds mail bodies; reset links never reach the log; the Watchfire dashboard is never open without signing in |
APP_DEBUG | false | error pages show no internal details (new apps’ .env has true) |
APP_URL | https://app.example.com | https turns on the session cookie’s Secure flag; password-reset links and mail use it |
APP_KEY | from key:generate --show | encrypts session cookies and signs Spark state and uploads; serve refuses to start without one (at least 32 bytes) |
SERVER_HOST / SERVER_PORT | 127.0.0.1 / 8000 | only the proxy on the same machine reaches the app |
TRUSTED_PROXIES | 127.0.0.1 | the client IP (login throttle, auth.ip(), the request log) is read from the proxy’s X-Forwarded-For; see The server |
SHUTDOWN_TIMEOUT | 30 | seconds a stop waits for running requests and agents; the systemd unit’s TimeoutStopSec is larger |
LOG_LEVEL | info | new apps’ .env has debug, which logs every request |
LOG_FILE | storage/logs/smeltery.log, or empty | stderr goes to the journal anyway; the file keeps one .1 backup at LOG_MAX_BYTES (10 MiB), so it needs no logrotate. Empty logs to the journal only |
DATABASE_URL | see below | |
SESSION_DRIVER | database (or file) | a logout deletes the session on the server, so a copied session cookie stops working; database uses the sessions table of new apps. cookie stores nothing on the server: a copy of the cookie stays valid until the session expires (see Authentication) |
CACHE_STORE | database (or redis) | the store must span processes for Watchfire’s coordination (“Several processes” in Watchfire); memory does not |
PUBSUB_DRIVER | auto, or database / redis with several serve processes | serve --no-agents and work share Sparks pushes through the database (with the pubsub_messages table: in new apps with Watchfire, else from smeltery pubsub:install) or Redis; several full serve processes need it set explicitly (see PubSub) |
STATIC_CACHE_CONTROL | no-cache | browsers revalidate public/ files with a cheap 304, so a deploy’s new app.css is seen at once; public, max-age=31536000, immutable for versioned file names |
HSTS_MAX_AGE | 31536000 once HTTPS works for the domain (not set at first) | browsers then use HTTPS only for the domain for a year; sent only with an https:// APP_URL |
MAIL_* | MAIL_MAILER=smtp and the server’s settings | with log, mail is not sent (see Mail) |
WATCHFIRE_DASHBOARD | auth or off | auth: signed-in users the dashboard gate admits (below); off: no dashboard (404) |
DATABASE_URL per backend (the backend’s feature must be compiled in, see Database and models):
DATABASE_URL=sqlite://database/database.sqlite?mode=rwc
DATABASE_URL=postgres://myapp:secret@127.0.0.1:5432/myapp
DATABASE_URL=mysql://myapp:secret@127.0.0.1:3306/myappThe SQLite path is relative to the app root; its directory must exist (the file is created). SQLite runs in WAL mode,
so serve, work and migrate can use the file at the same time, on a local disk.
Further keys for processes and Watchfire: QUEUE_DRIVER (database, or redis with REDIS_URL and the redis
feature), WATCHFIRE_IN_SERVE (false: serve never runs the agents),
WATCHFIRE_API_ADDR (the API address of work, e.g. 127.0.0.1:8001), WATCHFIRE_LOCK_STORE (default
CACHE_STORE) and WATCHFIRE_LEASE_TTL (30 s); see Watchfire. Every key
of the framework is in Configuration.
§First deploy
With the binary, public/, .env and the folders in place:
cd /srv/myapp
sudo -u myapp ./myapp migrate --force
sudo -u myapp install -d -m 750 storage/app storage/app/public
[ -L public/storage ] || sudo ln -s ../storage/app/public public/storagemigrate --forceruns the migrations compiled into the binary (asmyapp, so the SQLite files belong to it).- The link makes public uploads (
storage/app/public) available at/storage/…. It is made withlnas root, becausepublic/belongs to root; the folder is made asmyapp, the owner ofstorage/. Root never needs to run the app binary here. (./myapp storage:linkmakes both in one step where one user ownspublic/andstorage/. Run as root it only adds the link to apublic/that no other user controls and leavesstorage/alone; it never opens the log file.) Deploys keep the link (the deploy script below excludes it), and the[ -L … ]test makes running these lines again change nothing. sudo -u myapp ./myapp db:seed --forceruns the seeders. TheDatabaseSeederof new apps creates the demo user only underAPP_ENVlocalortesting, so in production it adds nothing; seeders of your own run as written.
§systemd: start on boot, restart on crash
/etc/systemd/system/myapp.service:
[Unit]
Description=myapp (Smeltery)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
ExecStart=/srv/myapp/myapp serve
Restart=on-failure
RestartSec=2
KillSignal=SIGTERM
TimeoutStopSec=45
UMask=0027
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/srv/myapp/storage /srv/myapp/database
PrivateTmp=true
PrivateDevices=true
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectControlGroups=true
ProtectClock=true
ProtectHostname=true
RestrictSUIDSGID=true
RestrictNamespaces=true
RestrictRealtime=true
LockPersonality=true
MemoryDenyWriteExecute=true
CapabilityBoundingSet=
AmbientCapabilities=
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallFilter=~@privileged @resources
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -f
curl -s http://127.0.0.1:8000/upenablestarts the app at every boot;--nowalso starts it now.WorkingDirectoryis the app root:.env,public/,storage/and the SQLite file are found from there.- On SIGTERM (
systemctl stop/restart) the app stops accepting connections, finishes running requests and stops its agents withinSHUTDOWN_TIMEOUT, and exits with 0.TimeoutStopSec(45) gives it that time before systemd kills it. Restart=on-failurerestarts the app after a crash and after an exit with an error (code 1: the port is taken,APP_KEYis missing, the database cannot be reached, a boot hook failed), but not after a clean stop. A handler that panics answers 500 and the app keeps running.- With a
CACHE_STOREthat spans processes (database,redis,memcached,file), after a crash the restarted process waits for the dead one’s agent leases to expire (WATCHFIRE_LEASE_TTL, 30 s) before it runs those agents again; after a clean stop orrestartthe leases are released and the agents start at once. Type=simple: the app does not usesd_notifyor socket activation.- The
ProtectSystem/ReadWritePathslines make the whole file system read-only for the app exceptstorage/anddatabase/. With PostgreSQL or MySQL on the same machine, addAfter=postgresql.service(ormysql.service) and drop/srv/myapp/database. UMask=0027: files the process creates are never readable by other users. The lines afterPrivateTmptake away what a web app does not use:/home, devices, kernel settings and modules, other address families than Unix sockets, IPv4 and IPv6, every capability, system calls outside@system-service, and memory that is both writable and executable.systemd-analyze security myapprates the unit. A Smeltery app with SQLite runs under all of them (serving pages, migrations, Watchfire agents, a clean stop on SIGTERM)./upanswers200 OKwithout a session or the database (see Routes and controllers).
One process or two. serve runs the web server and the Watchfire agents, queue workers and scheduler together:
one unit is a complete deployment. To run the background work in its own process (for example to restart the web server
without stopping long-running agents), run serve --no-agents and work as two units that replace myapp
(myapp-web listens on the same port, so stop and disable myapp first):
sudo systemctl disable --now myapp
sudo cp /etc/systemd/system/myapp.service /etc/systemd/system/myapp-web.service
sudo cp /etc/systemd/system/myapp.service /etc/systemd/system/myapp-work.serviceThen change two lines in each copy:
| File | Description= | ExecStart= |
|---|---|---|
myapp-web.service | myapp web (Smeltery) | /srv/myapp/myapp serve --no-agents |
myapp-work.service | myapp Watchfire (Smeltery) | /srv/myapp/myapp work |
sudo systemctl daemon-reload
sudo systemctl enable --now myapp-web myapp-workBack to one process: sudo systemctl disable --now myapp-web myapp-work, then sudo systemctl enable --now myapp.
Anvil’s sockets can have a process of their own as well: see A separate socket process.
With more than one serve process (serve next to work, or several behind a load balancer), set PUBSUB_DRIVER
to database or redis: under the default auto, a serve that runs its background work keeps its messages,
including the auth events that end sessions and tokens elsewhere, inside its own process (see
PubSub).
The processes coordinate through the cache store’s locks when CACHE_STORE (or WATCHFIRE_LOCK_STORE) spans
processes: database, redis, memcached, or file on one machine. Then each agent runs in one process at a time
(the others hold it in standby and take it over when its process stops or dies), each scheduled tick runs once, and
the database queue gives each job to one worker. The web process’s dashboard shows and controls the agents of the
work process. With memory, array or null every process runs every agent and every tick itself. Details:
“Several processes” in Watchfire. agents:logs <name> reads an agent’s
recent lines from the process that runs it; journalctl -u myapp-work has the full log. work exits with 1 when the app
registers no background work. A headless app (no web routes) runs only work; set WATCHFIRE_API_ADDR=127.0.0.1:8001
for its API and the agents:* commands.
§HTTPS: Caddy or nginx
The app listens on 127.0.0.1:8000; a reverse proxy on the same machine terminates HTTPS. The app compresses its
responses itself and never buffers its two event streams (/_sparks/stream for Sparks push and the live dashboard,
/_watchfire/api/events); both send a keep-alive every 15 seconds. The app also sends its own security headers
(X-Content-Type-Options, Referrer-Policy, X-Frame-Options, Content-Security-Policy: frame-ancestors, and
Strict-Transport-Security with HSTS_MAX_AGE; see The server), so the proxy needs no header
settings of its own; neither configuration below adds any, and an nginx add_header for one of them would send it a
second time.
Caddy gets and renews the certificate itself, sets X-Forwarded-For, -Proto and -Host, has no body-size
limit by default and flushes event streams at once. /etc/caddy/Caddyfile:
app.example.com {
reverse_proxy 127.0.0.1:8000
}sudo apt install caddy
sudo nano /etc/caddy/Caddyfile
sudo systemctl reload caddyA write timeout in Caddy’s global options (servers { timeouts { write 60s } }) ends each event stream at that
limit; the browser’s EventSource then reconnects. Leave write unset for the server that carries the app to keep
streams open. When a client sends no Accept-Encoding, Caddy asks the app for gzip and decompresses the answer
itself, so that client gets a weak ETag and no Content-Length; this is harmless, and
transport http { compression off } inside reverse_proxy turns it off:
app.example.com {
reverse_proxy 127.0.0.1:8000 {
transport http {
compression off
}
}
}nginx with a Let’s Encrypt certificate from certbot. /etc/nginx/sites-available/myapp:
server {
listen 80;
listen [::]:80;
server_name app.example.com;
# At least UPLOAD_MAX_BYTES (10 MiB by default); nginx's own default is 1 MiB.
client_max_body_size 10m;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}
# Server-sent events: passed on unbuffered.
location ~ ^/(_sparks/stream|_watchfire/api/events) {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_buffering off;
proxy_cache off;
}
}sudo apt install nginx certbot python3-certbot-nginx
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d app.example.comcertbot --nginx adds the listen 443 ssl lines and the redirect from HTTP to the server block, and renews the
certificate with a systemd timer. The app’s REQUEST_TIMEOUT (30 s) is below nginx’s default 60 s
proxy_read_timeout. proxy_read_timeout and send_timeout (both 60 s by default) limit the time between two
reads or writes, not a whole response, so the 15-second keep-alives keep event streams open; a value under 15 s in
the event-stream location would cut them.
Plesk. The app runs as above (binary, .env and folders in a directory of their own, the systemd unit, created
as root over SSH); Plesk’s nginx is the proxy. For the domain, turn on SSL/TLS with Let’s Encrypt, open Apache &
nginx Settings, turn off Proxy mode and put this into Additional nginx directives (Plesk’s own
configuration already has a location /, so these blocks use regular expressions, which nginx prefers over prefix
locations, in the order written):
client_max_body_size 10m;
location ~ ^/(_sparks/stream|_watchfire/api/events) {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_buffering off;
}
location ~ ^/ {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}A Smeltery app is a long-running process with its own port. Hosting that offers only PHP or CGI, with no SSH access and no way to keep a process running, cannot run it.
§The Watchfire dashboard in production
Outside APP_ENV=local, /_watchfire is open only to signed-in users that the app’s dashboard gate admits; without
a gate nobody gets in. A gate in app/agents/mod.rs that admits the users listed in an ADMIN_EMAILS key of
.env (a key of the app, read with env):
use crate::app::models::user::Model as User;
use smeltery::config::env;
use smeltery::watchfire::prelude::*;
pub fn register(w: &mut Watchfire) {
w.dashboard_gate(|auth, _app| async move {
let admins: String = env("ADMIN_EMAILS", "");
let Some(user) = auth.user::<User>().await? else {
return Ok(false);
};
Ok(admins.split(',').any(|email| email.trim() == user.email))
});
}With ADMIN_EMAILS=ops@example.com in .env, that user signs in at /login and opens /_watchfire; other users
get 403, guests are sent to /login. WATCHFIRE_DASHBOARD=off removes the dashboard (404).
The JSON API under /_watchfire/api needs Authorization: Bearer <token> outside local development. On the server,
cd /srv/myapp && sudo -u myapp ./myapp agents:list (and agents:start|stop|pause|resume|restart|logs) call it
with the token, which they derive from APP_KEY. For other clients, agents:token prints the token (the hex
HMAC-SHA256 of watchfire-api keyed with APP_KEY, smeltery::watchfire::web::api_token) to standard output:
cd /srv/myapp && sudo -u myapp ./myapp agents:tokenThe token changes only with APP_KEY; a new APP_KEY revokes it (and signs every user out).
§Updating
- Build the new binary (and
app.css). - Copy
public/and the binary next to the running one;mvit into place (a running binary cannot be overwritten in place, but it can be replaced by a rename). sudo -u myapp ./myapp migrate --forcewith the NEW binary: the migrations are compiled into it.sudo systemctl restart myapp: the old process finishes its running requests and stops its agents (withinSHUTDOWN_TIMEOUT), then the new one starts. Between the two the proxy answers 502 for a moment. Jobs that were running go back to the queue.
With two processes: migrate, then sudo systemctl restart myapp-work myapp-web. Agents stop in the old work
process and start in the new one as soon as it is up.
A deploy script, run from the app’s folder on a Linux build machine (deploy is an account on the server with sudo):
#!/usr/bin/env bash
set -euo pipefail
APP=myapp
SERVER=deploy@app.example.com
DIR=/srv/myapp
smeltery build
# A new private folder (mode 700) of the deploy account on the server: no other user can change the upload.
STAGE=$(ssh "$SERVER" mktemp -d)
rsync -a --delete --exclude /storage public/ "$SERVER:$STAGE/public/"
scp "target/release/$APP" "$SERVER:$STAGE/$APP.new"
ssh "$SERVER" "set -e
sudo rsync -a --delete --chown=root:root --chmod=D755,F644 --exclude /storage $STAGE/public/ $DIR/public/
sudo install -o root -g root -m 755 $STAGE/$APP.new $DIR/$APP.new
rm -rf $STAGE
[ -f $DIR/$APP ] && sudo cp -p $DIR/$APP $DIR/$APP.previous
sudo mv $DIR/$APP.new $DIR/$APP
cd $DIR && sudo -u $APP ./$APP migrate --force
sudo systemctl restart $APP
sleep 2 && curl -fsS http://127.0.0.1:8000/up"--chown and --chmod give public/ the owner and modes of the table under “Server layout”, whoever uploaded the
files. --exclude /storage keeps the public/storage link. The previous binary stays as myapp.previous. With two
processes, the restart line is sudo systemctl restart myapp-work myapp-web.
Rollback. When the new release added migrations, undo them with the NEW binary first (an older binary does not know them and refuses), then put the old binary back:
cd /srv/myapp
sudo -u myapp ./myapp migrate:rollback --force
sudo mv myapp.previous myapp
sudo systemctl restart myapp
# with two processes instead: sudo systemctl restart myapp-work myapp-webmigrate:rollback reverts the last batch, the migrations of the last migrate run, by running each migration’s
down; --step N reverts the last N migrations instead. A rollback undoes exactly what those down functions do,
so check them before relying on it (make:migration writes a down that drops what create_* and add_*
migrations add; other names get an empty down): a down that does nothing leaves the change in the database, and
running that migration again can then fail (for example on a column that already exists).
§Operations
-
Logs:
journalctl -u myapp(-ffollows,--since "1 hour ago"); withLOG_FILE, alsostorage/logs/smeltery.logand its.1backup. Requests are logged atdebug; secrets in URLs appear as[redacted]. -
Health checks: point an uptime monitor or load balancer at
https://app.example.com/up(200, bodyOK). -
Backups:
.env(without itsAPP_KEYevery session, signed Spark state and the API token change), the database andstorage/app/. Backups hold password hashes and sessions, so they go into a folder only root can read:sudo install -d -m 700 /var/backups/myapp # SQLite (apt install sqlite3): a consistent copy while the app runs sudo sqlite3 /srv/myapp/database/database.sqlite ".backup '/var/backups/myapp/db.sqlite'" # PostgreSQL sudo -u postgres pg_dump -Fc myapp | sudo tee /var/backups/myapp/myapp.dump > /dev/null # MySQL (root signs in through the socket on Ubuntu) sudo mysqldump --single-transaction myapp | sudo tee /var/backups/myapp/myapp.sql > /dev/nullCopying the SQLite file alone misses what is still in
database.sqlite-wal;.backupincludes it. WithQUEUE_DRIVER=redisthe queued jobs and dead letters are on the Redis server, kept by its own persistence (RDB or AOF). -
Rotating
APP_KEY(a new key fromkey:generate --showas under “Production.env”, pasted into.env, then a restart) signs every user out (session and remember-me cookies), invalidates the Spark state in open pages and pending signed uploads, and changes the Watchfire API token. Database rows stay as they are. -
Clearing the cache:
sudo -u myapp ./myapp cache:clearkeeps Watchfire’s leases and schedule claims.cache:clear --allremoves them too: the processes take their agents again withinWATCHFIRE_LEASE_TTL, and until then a singleton agent can run in two processes and a tick of the current minute can run again. -
Sharing a cache store: Watchfire’s leases and schedule claims, the cache entries and locks of the app all live under
CACHE_PREFIX(default<app name>_cache_). Two apps, or the staging and production copy of one app, on one Redis database, memcached server or database need differentCACHE_PREFIXvalues (or separate Redis databases or tables); with the same prefix they take each other’s leases and claims and read each other’s entries. Memcached cannot flush by prefix, so a shared memcached is emptied for every app bycache:clear --all. -
Sharing a Redis queue: with
QUEUE_DRIVER=redis, two apps (or the staging and production copy of one app) on one Redis database need differentQUEUE_PREFIXvalues (default<app name>_queue_) or separate Redis databases; with the same prefix their workers take each other’s jobs. -
HTTP caches: web pages are per visitor (their session, the CSRF token in their forms): a CDN or a caching proxy in front of the app caches only
public/files (STATIC_CACHE_CONTROL), never pages.
§Checklist
-
smeltery buildon Linux; binary,public/(withapp.css),storage/,database/on the server -
a
myappsystem user; onlystorage/anddatabase/writable (750);.env640root:myapp;UMask=0027in the unit -
.env:APP_ENV=production,APP_DEBUG=false,APP_URL=https://…, a newAPP_KEY,SERVER_HOST=127.0.0.1,TRUSTED_PROXIES=127.0.0.1,LOG_LEVEL=info,SESSION_DRIVER=database,MAIL_MAILER=smtpwith theMAIL_*keys,DATABASE_URL -
WATCHFIRE_DASHBOARD=authwith adashboard_gate, oroff -
migrate --force, thepublic/storagelink -
the systemd unit enabled (
enable --now),curl http://127.0.0.1:8000/upanswersOK -
Caddy or nginx with HTTPS;
client_max_body_sizeat leastUPLOAD_MAX_BYTES; the event streams unbuffered -
two processes only with a shared
CACHE_STORE(database,redis,memcached); thepubsub_messagestable (new apps with Watchfire have it, others get it fromsmeltery pubsub:install) unlessCACHE_STORE=redis -
with
QUEUE_DRIVER=redis:maxmemory-policy noeviction(orvolatile-*) on the Redis server, persistence (RDB or AOF) that fits how many jobs may be lost, and aQUEUE_PREFIXper app that does not overlapCACHE_PREFIX -
an uptime monitor on
/up; backups of.env, the database andstorage/app/
§Demo apps
Three apps in examples/, each listing the exact commands in its README (the two Smeltery apps are
built with the smeltery generators):
examples/web-demo: a Posts CRUD with validation and image uploads, authentication, a live counter fed by a scheduled job over server-sent events, and a rate-limited, checkpointed scraper agent with the live Watchfire dashboard.examples/headless-demo: agents only, run withsmeltery work: a poller and a deliberately flaky worker whose restarts and backoff show insmeltery agents:runs.examples/flutter-client: a Flutter app on a Smeltery app’s API tokens and broadcasting: sign-in, a public, a private and a presence channel, whispers, and the return to the sign-in when the token ends.
§Licence
Dual-licensed under MIT or Apache-2.0, at your option.
§Contributing
Issues and pull requests are welcome at https://github.com/smelteryworks/smeltery. Run cargo fmt --all,
cargo clippy --workspace --all-targets --all-features -- -D warnings and cargo test --workspace --all-features
before sending a change.
Re-exports§
pub use smeltery_watchfire as watchfire;pub use smeltery_bellows as bellows;pub use smeltery_alloy as alloy;pub use smeltery_anvil as anvil;pub use smeltery_hallmark as hallmark;pub use smeltery_temper as temper;pub use smeltery_prospect as prospect;pub use smeltery_sparks as sparks;pub use smeltery_mail as mail;pub use smeltery_mold as mold;
Modules§
- auth
- Authentication: password hashing, the
Authextractor, theauth,guestandverifiedmiddleware, remember-me cookies, login throttling, password resets and email verification. - cache
- The cache: typed values with a time to live, counters and atomic locks, over one of several stores.
- channels
- Broadcast channels as other crates see them: who may receive a channel’s events (
ChannelAuthorizer) and the events as they are delivered in this process (ChannelEvents). - config
- Configuration:
.envloading, theenv()reader and the frameworkSettings. - console
- The console kernel: the commands an app binary understands (
serve,route:list,migrate…) and the app’s ownCommands. - crypto
- Random tokens, hashing and constant-time comparison (the one home of these in Smeltery), and the keys derived
from
APP_KEYbehindApp::sign,App::encryptand the session cookies. - db
- The database: the
Dbhandle, models (Record), migrations, seeders and factories. - html
- HTML helpers.
- http
- HTTP types handlers use.
- middleware
- Middleware: functions that wrap request handling.
- prelude
- The items most apps use, in one import:
use smeltery::prelude::*;. - pubsub
- PubSub: messages between the processes of one app.
- routing
- Routing: the
Routerthatroutes/web.rsandroutes/api.rsfill. - session
- Sessions: per-visitor data kept between requests on web routes.
- testing
- Test helpers: drive the whole app with HTTP requests, no server or network.
- validation
- Validation (“Assay”):
#[derive(Validate)]rules on form structs, theValidextractor andValidationErrors. - view
- Views: Mold templates returned from handlers.
Macros§
- json
- Build a
serde_json::Valuewith JSON syntax, e.g.json!({"status": "ok"}). Construct aserde_json::Valuefrom a JSON literal.
Structs§
- App
- The running application: settings, services and the route table.
- AppBuilder
- Collects settings, services, routes and middleware, then
builds theApp.bootstrap/app.rsin a generated app is one function over this builder. - Built
- The result of
AppBuilder::build: the app and its HTTP service.
Enums§
- Error
- An error a handler (or the framework) returns.
Constants§
- VERSION
- The version of Smeltery the app is built with (the new app’s welcome page shows it).
Functions§
- run
- Load
.env, set up logging, build the app withbuildand run the command named by the process arguments (servewhen there is none). - serve
- Serve the app until Ctrl-C / SIGTERM or
App::shutdown, then drain within the shutdown budget.
Type Aliases§
- BoxFuture
- A boxed, sendable future, as boot hooks return.
- Response
- An HTTP response.
- Result
ResultwithErroras the error type: what handlers usually return.
Attribute Macros§
- actions
#[derive(Spark)]and#[actions]: a live component’s state, view and callable actions (seesparks). The actions of a Sparks component: everypub async fnwith a&mut selfreceiver in this impl block is callable from the page (wire:click="increment"); other methods are not.
Derive Macros§
- Alloy
#[derive(Alloy)]: a struct as an Alloy page (seealloy). Make a struct an Alloy (Inertia) page:#[alloy("posts/index")]names the React / Vue component.- Mold
#[derive(Mold)]: compilesresources/views/<name>.mold.htmlfor a struct and makes it a response. DerivesTemplatefor a struct with named fields from the template named in#[mold("…")].- Spark
#[derive(Spark)]and#[actions]: a live component’s state, view and callable actions (seesparks). Make a struct a Sparks live component: implementssmeltery::sparks::Sparkand compiles its Mold view.- Validate
#[derive(Validate)]: validation rules on a form struct (seevalidation). ImplementValidatefrom#[validate(...)]attributes.