The basics
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. 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.
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): the browser sends no cookie cross-origin, 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 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 * stops 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.