Getting started
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 |
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); a further one is closed at once; peers in TRUSTED_PROXIES are not counted; 0 turns the limit off |
TRUSTED_PROXIES |
empty | proxies whose X-Forwarded-* headers are believed: IPs and CIDR ranges, comma-separated, or * (see The server); empty trusts nobody |
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 |