Smeltery
Get started

Getting started

v0.1

Configuration

Config lives in typed structs under config/, read from .env with env(key, default):

rust
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

↑↓ moveEnter openEsc close