dynamic-config 0.6.2

Hot-reloadable, lock-free application configuration with a one-attribute API, built on figment.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

<div align="center">

# dynamic-config

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

[![CI](https://github.com/dynamic-config-rs/dynamic-config/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dynamic-config-rs/dynamic-config/actions/workflows/ci.yml)
[![Security](https://github.com/dynamic-config-rs/dynamic-config/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/dynamic-config-rs/dynamic-config/actions/workflows/security.yml)
[![crates.io](https://img.shields.io/crates/v/dynamic-config.svg)](https://crates.io/crates/dynamic-config)
[![docs.rs](https://img.shields.io/docsrs/dynamic-config)](https://docs.rs/dynamic-config)
[![MSRV](https://img.shields.io/badge/MSRV-1.71-blue)](https://dynamic-config-rs.github.io/msrv-features.html)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/dynamic-config-rs/dynamic-config/badge)](https://scorecard.dev/viewer/?uri=github.com/dynamic-config-rs/dynamic-config)

[**The Book**](https://dynamic-config-rs.github.io/) · [API docs](https://docs.rs/dynamic-config) · [Examples](https://github.com/dynamic-config-rs/dynamic-config/tree/main/dynamic-config/examples) · [Changelog](CHANGELOG.md)

</div>

---

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.

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

```rust
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 and allocation-free.** `current()` acquires an
  `arc-swap` guard — **85 instructions**, ~20 ns, and zero allocations per
  100 000 reads, all three measured rather than asserted — 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 <
  secrets_dir < .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. Eight store crates ship from
  [dynamic-config-remote](https://github.com/dynamic-config-rs/dynamic-config-remote),
  each watching the way its protocol allows — seven over a network, and git.

The full story — precedence, profiles, discovery, hot reload, encryption,
schema export, units, the last-known-good cache, testing patterns — lives in
[**the book**](https://dynamic-config-rs.github.io/).

## This repository, and the family

| Crate | What | Stability |
|---|---|---|
| [`dynamic-config`](https://crates.io/crates/dynamic-config) | the engine: loading, layers, storage, watching | **Beta** |
| [`dynamic-config-macros`](https://crates.io/crates/dynamic-config-macros) | `#[dynamic_config]` | **Beta** |
| [`dynamic-config-embedded`](https://crates.io/crates/dynamic-config-embedded) | the same shape for `no_std` targets | **Beta** |
| [`dynamic-config-cli`](https://crates.io/crates/dynamic-config-cli) | `explain` and `diff` on the command line — `cargo install dynamic-config-cli` | **Beta** |

The rest of the family is released from its own repository, each naming
this engine with a caret so a patch here reaches it without a release
there:

| Repository | What it ships |
|---|---|
| [dynamic-config-remote](https://github.com/dynamic-config-rs/dynamic-config-remote) | eight store crates — etcd, Consul, NATS, Redis, Vault, S3, Firestore, git — and `dynamic-config-server` |
| [dynamic-config-python](https://github.com/dynamic-config-rs/dynamic-config-python) | `pip install dynamic-config-py`; a dataclass, Pydantic or msgspec validates |
| [dynamic-config-node](https://github.com/dynamic-config-rs/dynamic-config-node) | `npm install dynamic-config-node`; Zod, Ajv or a function of your own validates |

**Every crate is Beta**: breaking changes bump the minor pre-1.0 and are
announced in the changelog; a patch never breaks.

**Between here and 1.0, only security fixes and hotfixes land.** The
surface is what it is going to be for 0.x: no new sources, no new stores,
no new methods on the settled types. Pin the minor version and take
patches automatically. Details in
[Stability Tiers](https://dynamic-config-rs.github.io/stability-tiers.html).

## MSRV

| | floor |
|---|---|
| `dynamic-config` core | **1.71** |
| `schema` feature | 1.74 (schemars) |
| `watch` / `age` / `full` features | 1.85 (measured, not declared) |
| `dynamic-config-cli` | 1.85 |
| `dynamic-config-embedded` | 1.83 |

The store crates, the server and the bindings declare their own floors, in
their own repositories — a companion pays for what it pulls in.

MSRV changes are breaking. Every floor has a CI row against a real
toolchain; the full table with reasons is in
[MSRV & Features](https://dynamic-config-rs.github.io/msrv-features.html).

## Contributing

[CONTRIBUTING.md](https://github.com/dynamic-config-rs/dynamic-config/blob/main/CONTRIBUTING.md) is the short version;
[the onboarding tour](https://github.com/dynamic-config-rs/dynamic-config/blob/main/docs/CONTRIBUTOR-ONBOARDING.md) walks every module.
What will *not* be built, and why, is in
[Limitations & Not Planned](https://dynamic-config-rs.github.io/limitations.html);
what might be is in [ROADMAP.md](https://github.com/dynamic-config-rs/dynamic-config/blob/main/ROADMAP.md).

## Credits

What this engine is built on and whose ideas it took —
[CREDITS.md](https://github.com/dynamic-config-rs/dynamic-config/blob/main/CREDITS.md).

## License

[MIT](LICENSE).