Configuration
A server reads where it listens, its database and its secrets from several
places: defaults, a file in /etc, one of the user’s, the environment of a
container, an option for one run. weft/config merges them into one value
of a type the program declares, and says where each value came from.
wv add weft/configThe program
Section titled “The program”The settings are a record; #Config writes how it is read:
import weaver.io.printimport weaver.test.assertimport weaver.time.Durationimport weft.config.{Config, ConfigTag, ConfigError}import weft.config.formats.{toml, json}
/// Where the data is kept.#Configtype Database = { url: String pool: Int? password: String `config(secret)`}
/// How much the server says.#Config#Showenum Level = quiet | normal | verbose
/// The settings of a small server.#Configtype Settings = { listen: String? level: Level db: Database timeout: Duration? origins: String[]}
fn main(args: String[]) ! ConfigError { val (s, rest) = Config.loadWithRest<Settings>( name: "demo", formats: [toml(), json()], args: args )! print("listening on ${s.listen ?? ":8080"}, level ${s.level}") print("${s.db.pool ?? 10} connections to ${s.db.url}") print("arguments left: ${rest}")}
@test("each value names its source")fn explained() ! ConfigError { val env = [("DEMO_DB__URL", "postgres://db/app"), ("DEMO_DB__PASSWORD", "s3cret")] val text = Config.explain<Settings>( name: "demo", args: ["--set", "level=quiet", "--set", "db.pool=4"], env: env, dirs: String[]() )! assert(text.contains("db.password = ******** (env DEMO_DB__PASSWORD)"), "the secret is masked")}- A field is a key; a nested record, a table; an array, a list; an enum,
the name of a variant. A
Duration, a number or a boolean is read from text as well, since the environment and the command line only give strings. - An optional field may be absent, and so may an array, empty then. Any
other field is required, unless tagged
config(default), which gives it its type’s default value,0or"". config(secret)masks the value wherever the configuration is shown.formatssays which files are read: TOML and JSON here. Without a format, no file is read, only the environment and the command line.
Where the values come from
Section titled “Where the values come from”Each source overrides the one before, key by key; tables merge, lists are replaced:
- the type’s defaults;
- the files
demo.tomlordemo.json, in/etc/demo/, then in the user’s~/.config/demo/, then in the current directory; or only the file that--config pathnames; - the environment, prefixed by the program’s name:
DEMO_LISTEN,DEMO_DB__POOLfordb.pool,__between tables,_between the words of a camelCase key; - the command line,
--set db.pool=20, repeated as needed.
A file of the user’s, ~/.config/demo/demo.toml:
level = "normal"origins = ["https://a.example"]
[db]url = "postgres://localhost/app"password = "${env:DB_PASSWORD}"The password is not in the file: ${env:DB_PASSWORD} reads a variable,
${file:/run/secrets/db} a file’s content, and ${db.url} another key.
$ DB_PASSWORD=s3cret ./demolistening on :8080, level normal10 connections to postgres://localhost/apparguments left: []$ DB_PASSWORD=s3cret DEMO_DB__POOL=20 DEMO_LISTEN=:9000 ./demo --set level=verbose serve --port 1listening on :9000, level verbose20 connections to postgres://localhost/apparguments left: ["serve", "--port", "1"]loadWithRest gives back the arguments it did not take, which are the
program’s own: they can go to a command line
parsed by weft/cli. Config.load gives the settings alone.
When it goes wrong
Section titled “When it goes wrong”Every error names the key, and the source that gave the wrong value:
demo: level: missing, and the type has no defaultdemo: db.pool, from env DEMO_DB__POOL: expected an integer, found "many"demo: level, from --set level: `loud` is none of quiet, normal, verbosedemo: db.password: `env:DB_PASSWORD`: no such variableWhere each value came from
Section titled “Where each value came from”The first question about a deployed program is where a value came from.
Config.explain answers it, one line per key, secrets masked:
db.password = ******** (env DEMO_DB__PASSWORD)db.pool = 4 (--set db.pool)db.url = postgres://db/app (env DEMO_DB__URL)level = quiet (--set level)listen = (default)origins = (default)timeout = (default)load, loadWithRest and explain also take env: and dirs:, which
replace the process’s environment and the directories searched: the test
of the program above reads a configuration of its own, without touching
the machine’s.
Going further
Section titled “Going further”- Another file format, YAML or INI, is a
ConfigFormat{name, extensions, parse}:parsereads a text into aConfigValue, the neutral tree of tables, lists and values. - A configuration is read once: there is no reloading on a signal, and no watching of files. A server restarts.