Skip to content
Weaverv0.5.0

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.

Terminal window
wv add weft/config

The settings are a record; #Config writes how it is read:

import weaver.io.print
import weaver.test.assert
import weaver.time.Duration
import weft.config.{Config, ConfigTag, ConfigError}
import weft.config.formats.{toml, json}
/// Where the data is kept.
#Config
type Database = {
url: String
pool: Int?
password: String `config(secret)`
}
/// How much the server says.
#Config
#Show
enum Level = quiet | normal | verbose
/// The settings of a small server.
#Config
type 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, 0 or "".
  • config(secret) masks the value wherever the configuration is shown.
  • formats says which files are read: TOML and JSON here. Without a format, no file is read, only the environment and the command line.

Each source overrides the one before, key by key; tables merge, lists are replaced:

  1. the type’s defaults;
  2. the files demo.toml or demo.json, in /etc/demo/, then in the user’s ~/.config/demo/, then in the current directory; or only the file that --config path names;
  3. the environment, prefixed by the program’s name: DEMO_LISTEN, DEMO_DB__POOL for db.pool, __ between tables, _ between the words of a camelCase key;
  4. 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 ./demo
listening on :8080, level normal
10 connections to postgres://localhost/app
arguments left: []
$ DB_PASSWORD=s3cret DEMO_DB__POOL=20 DEMO_LISTEN=:9000 ./demo --set level=verbose serve --port 1
listening on :9000, level verbose
20 connections to postgres://localhost/app
arguments 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.

Every error names the key, and the source that gave the wrong value:

demo: level: missing, and the type has no default
demo: db.pool, from env DEMO_DB__POOL: expected an integer, found "many"
demo: level, from --set level: `loud` is none of quiet, normal, verbose
demo: db.password: `env:DB_PASSWORD`: no such variable

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.

  • Another file format, YAML or INI, is a ConfigFormat{name, extensions, parse}: parse reads a text into a ConfigValue, 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.