Smeltery
Get started

The basics

v0.1

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:

text
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 (OPTIONS with Access-Control-Request-Method) from a listed origin to a path under CORS_PATHS is answered 204 before routing, with Access-Control-Allow-Origin (that origin), the requested method, Access-Control-Allow-Headers: Accept, Authorization, Content-Type, X-Requested-With, X-Socket-ID, X-CSRF-TOKEN and Access-Control-Max-Age: 600. Other requests from it get Access-Control-Allow-Origin, the framework's own answers included (the 408 of REQUEST_TIMEOUT, the 500 of a panic, error pages).
  • Every answer under CORS_PATHS carries Vary: 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 no Access-Control-Allow-Origin; the browser blocks their answers.
  • CORS_PATHS entries are prefixes compared as text: end each with / (/api would 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 sends null is 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:

rust
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 rightmost X-Forwarded-For address 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() is None (auth.ip() is unknown), never the proxy's own address; without the header it is the proxy's address;
  • scheme() / is_secure() follow the first X-Forwarded-Proto value (http or https);
  • host() is the first X-Forwarded-Host value, else the Host header.

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:

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.

↑↓ moveEnter openEsc close