dynamic-config

Hot-reloadable, layered configuration for Rust — one attribute, lock-free reads.

The Book · API docs · Examples · Changelog

Configuration that stays live after startup: files, environment, remote stores and command-line flags merged into one typed struct, re-read when they change, served to every thread as one atomic load.

[dependencies]
dynamic-config = { version = "0.2.0", features = ["toml", "watch"] }

use dynamic_config::dynamic_config;
use serde::Deserialize;
use std::time::Duration;

#[dynamic_config]
#[derive(Debug, Deserialize)]
pub struct DatabaseConfig {
    pub host: String,
    pub port: u16,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let builder = DatabaseConfig::builder("db")
        .file("config.toml")
        .file("secrets.json")
        .env("APP_");

    builder.init()?;                                     // load once, fail fast on a bad config
    builder.watch(Duration::from_millis(250))?.detach(); // reload in the background from now on

    let config = DatabaseConfig::current();              // one atomic load, on any thread
    println!("{}:{}", config.host, config.port);

    Ok(())
}

The attribute declares — this type is a configuration — and generates its storage and accessors. The builder configures: where the sources are is runtime data, and it lives in runtime code.

Why this one

• Reads are lock-free. current() is an atomic pointer load — ~17 ns — so configuration can be read per request without a second thought.
• A bad edit cannot take the process down. A file that no longer parses or validates degrades to "no change"; the previous snapshot keeps serving, and the error is reported.
• Layers with provenance. defaults < discovered < files < remote < .env < environment < bindings < flags < overrides — and source_of("key") names the file, variable or store a value actually came from.
• Secrets stay out of diagnostics. Errors, diffs, reports and {:?} print paths and types, never values — enforced by its own test suite.
• Any runtime, or none. The async surface is a Future and a thread; tokio, smol and Embassy all drive it. Blocking work never lands on your executor.
• Remote stores are explicit. refresh_remote() does the network round trip; load() never does. Seven store crates ship, each watching the way its protocol allows.

The full story — precedence, profiles, discovery, hot reload, encryption, schema export, units, the last-known-good cache, testing patterns — lives in the book.

The workspace

Beta: breaking changes bump the minor pre-1.0 and are announced in the changelog. Experimental: may change shape without ceremony — pin an exact version. Details in Stability Tiers.

Every store follows the same contract — the current value is not announced at startup, a deleted key is not a change, transport failures retry, a panicking callback ends the watch with an error — and each documents its stop latency and change-detection rule side by side in Store Crates at a Glance.

MSRV

MSRV changes are breaking. Every floor has a CI row against a real toolchain; the full table with reasons is in MSRV & Features.

Contributing

CONTRIBUTING.md is the short version; the onboarding tour walks every module. What will not be built, and why, is in Limitations & Not Planned; what might be is in ROADMAP.md.

License

MIT.