Server configuration is a strict server.toml with environment overrides

Status: Accepted (2026-11-06)

Context

A host needs a file for the server's launch parameters (name, slots, password, ports, the resources to start), and a container deployment needs to set the same parameters through the environment without editing the file. A config that silently replaces a broken value with its default, ignores an unknown key or quietly clamps an out-of-range number lets a typo start the server with parameters the host never meant.

Decision

• server.toml next to resources/, like the ban list. TOML is already the format of resource manifests and bans. The file in the repository is a template with a comment on every key, and its values equal the built-in defaults (a test checks this). Without a file the defaults apply.
• Precedence: ports given on the command line, then environment variables, then the file, then the defaults. Environment names are fixed per key: DARQLINEMP_<KEY> for top-level keys and DARQLINEMP_<TABLE>_<KEY> for keys of a table (DARQLINEMP_NETWORK_GAME_PORT); a list is comma-separated. Structured values ([[auth.providers]]) come only from the file.
• Strict and fail-closed: an unknown key, a wrong type, a value out of range, a contradiction between keys (an auth resource that is not in the startup list, auth providers without an auth resource) or an environment variable that does not parse or is not UTF-8 prevents the server from starting, and the error names its source. Nothing silently falls back to a default.
• Launch parameters of the host only, read once at start. The server never writes the file back, and resources do not read it. Gameplay parameters (time, weather, nametags, sync rates) belong to the game mode and the protocol. The password is the one launch value with a runtime counterpart: the operator (password set / password clear) and resources (dlmp.set_server_password) can change it while the server runs, without touching the file.
• A key appears with a consumer. The current keys are name, max_players, password, [network] game_port, [network] client_files_port (defaults to the game port number), [resources] startup and [auth] resource, timeout_seconds and providers (ADR 0052, ADR 0055).

Consequences

• A new key means a field in src/config.rs, its check, its environment name, a line of the template and a test; the template and the defaults cannot drift apart.
• max_players is a soft limit below the hard maximum of 1000 slots: player ids are handed out below it, and lowering it does not disconnect players in higher slots.
• Bind and public addresses and a download mirror are not configurable yet; each gets its key when something needs it.

Alternatives considered

• JSON or XML. JSON has no comments, XML is verbose, and the rest of the server already uses TOML.
• ${VAR} substitution inside the file. Flexible names, but substitution before parsing breaks quoting and escaping, and an error points at a line of the substituted text the host never wrote. Fixed environment names are used instead.
• Silent fallback to defaults, or clamping. A typo in a key or value starts the server with the wrong parameters unnoticed.
• Changing the config at runtime and saving it back. The file would become mutable server state; nothing needs it.
• Generating the file with a command-line flag. An extra launch mode; the template in the repository, checked by a test, does the same.