Struct Builder 

pub struct Builder<T> { /* private fields */ }

Runtime-chosen sources for one configuration section.

Methods take and return self, are infallible, and defer every check to load — a missing file or an unsupported extension is a load-time answer, same as everywhere else in this crate.

What the builder configures in this stage is the source side: files, the environment layer, .env files, profiles. The runtime layers (set_default, set_override) and remote stores stay on the generated type, whose statics they live in.

Implementations

impl<T: DeserializeOwned> Builder<T>

pub fn explain(&self, path: &str) -> Result<Explanation, Error>

Explains path against this builder’s sources; see crate::explain.

A builder that knows which fields are secret — every generated builder() does — hands back a path under one of them already redacted, the same as the type-level explain. A bare Builder::new knows no secrets and redacts nothing; pass the result through Explanation::redacted for a path you know to be sensitive.

Errors

The same failures as load.

pub fn source_of(&self, path: &str) -> Result<Option<Origin>, Error>

Where the value at path would come from, if anything supplies it.

Errors

The same failures as load.

pub fn is_set(&self, path: &str) -> Result<bool, Error>

Whether anything supplies path.

Errors

The same failures as load.

pub fn snapshot(&self) -> Result<Snapshot, Error>

Resolves the section without deserializing it.

Errors

The same failures as load.

pub fn check(&self) -> Result<Report, Error>

What this configuration resolves to, and whether it would load — see check. Unknown-key detection uses the field names only the generated builder() carries; a bare builder reports none.

Errors

Only if the sources cannot be read at all.

impl<T: DeserializeOwned> Builder<T>

pub fn schema(&self) -> Value

where T: JsonSchema,

Available on crate feature schema only.

A JSON Schema for the file this section lives in.

The struct’s schema wrapped under this builder’s key, with #[config(secret)] fields carrying writeOnly — which the generated builder() knows and a bare one does not. Combine several with schema::merge when more than one config type shares a file.

impl<T: DeserializeOwned> Builder<T>

pub fn load(&self) -> Result<T, Error>

Reads the sources and deserializes, installing nothing.

Errors

The same failures as any load: a file that will not parse, a missing required value, an unsupported extension.

pub fn init(&self) -> Result<(), Error>

Loads and installs as the type’s snapshot.

Errors

Whatever load reports — and, on a builder made with Builder::new rather than a generated builder(), the fact that there is no storage to install into.

pub fn init_and_current(&self) -> Result<Arc<T>, Error>

init, handing back the snapshot it installed.

The two calls always pair — install a configuration, then read it — and writing them apart means naming the type twice and reading the second line to learn that the first worked:

let config = ServerConfig::builder("server")
    .file("config.json")
    .init_and_current()?;

println!("{}", config.host);

The snapshot is the one this call installed. A reload landing between the install and the return would change what current() answers; it does not change what this returns, which is the configuration the program was started with.

Errors

Exactly init’s.

pub fn prepare(&self) -> Result<Commit, Error>

where T: Send + Sync + 'static,

The first half of a grouped reload: load and validate now, install later — what ReloadGroup drives.

Errors

The same failures as load; a builder with no installer has nothing to commit into.

pub fn reload(&self) -> Result<(), Error>

One reload: load, validate, install, rewrite the cache.

What a watch iteration and a RemoteSink’s apply both do. A failure installs nothing — the previous snapshot keeps serving.

Errors

The same failures as load; a builder with no installer has nothing to reload into.

pub fn reload_with(&self, reason: ReloadReason) -> Result<(), Error>

reload, stating why.

The reason reaches the reload hooks registered through on_reload_with and the last_reason in ConfigCell::status. Everything else is identical — this is reload with the label it would otherwise have to guess. Programs that detect their own changes (a store this crate has no adapter for, a control plane pushing over a socket) have somewhere to say so; a plain reload() is Manual.

Errors

The same failures as reload.

impl<T: DeserializeOwned + Send + Sync + 'static> Builder<T>

pub async fn load_async(&self) -> Result<T, Error>

Available on crate feature async only.

load, off the async executor.

Errors

The same failures as load.

pub async fn init_async(&self) -> Result<(), Error>

Available on crate feature async only.

init, off the async executor.

Errors

The same failures as init.

pub async fn init_and_current_async(&self) -> Result<Arc<T>, Error>

Available on crate feature async only.

init_and_current, off the async executor.

The pair is what an async main writes at startup, and it is where splitting it costs most: init_async().await? on one line and the type named again on the next.

Errors

The same failures as init.

impl<T: DeserializeOwned + Send + Sync + 'static> Builder<T>

pub fn watch(&self, debounce: Duration) -> Result<WatchHandle>

Available on crate feature watch only.

Reloads on file changes until the returned handle is dropped.

The same watcher as the attribute’s watch — same debounce, same registry: a type is watched once, whichever surface starts it, so a builder watch while start_watch() runs (or the reverse) is AlreadyExists. Each reload loads through this builder and installs into the type’s snapshot, firing on_reload hooks and waking changes() exactly as any other install does; a configured cache is rewritten after each clean reload.

Errors

As the generated start_watch(): no watchable directory, a backend that cannot start, or the type already being watched — plus a builder with no installer, which has nothing to reload into.

pub fn watch_with( &self, debounce: Duration, mode: WatchMode, ) -> Result<WatchHandle>

Available on crate feature watch only.

watch with the detection strategy chosen explicitly — polling is what network and overlay filesystems need.

Errors

As watch.

impl<T: DeserializeOwned> Builder<T>

pub fn new(key: impl Into<String>) -> Self

A builder for the section key, tied to no config type’s storage.

load works; init needs somewhere to install and is how the generated builder() differs from this.

pub fn secrets(self, secrets: &[&str]) -> Self

Which paths hold secrets, stated by hand.

#[config(secret)] is a declaration, and a configuration with no struct has nowhere to make one — so a schemaless configuration (Builder::values, or any bare Builder::new) starts with no secret list at all, and every surface that redacts one has nothing to redact. This is that list, supplied at the only place that knows it. It buys exactly what the attribute buys:

• explain returns *** for a path that is, sits under, or contains one of these — the same three-way rule #[config(secret)] gets;
• CacheMode::Redacted and Fingerprint become usable — without a list they are refused at init rather than quietly writing a cache with the secrets in it.

Paths are dotted and relative to the section, as in "credentials.password". Naming a table redacts everything below it.

What it cannot buy is a redacting Debug: there is no type here to generate one for. Value’s own Debug prints shape and keys and never values, which is why that gap is a non-event.

use dynamic_config::{Builder, CacheMode};

let builder = Builder::values("db")
    .file("config.json")
    .secrets(&["password"])
    .cache("last-known-good.json", CacheMode::Redacted);

pub fn key(&self) -> &str

The section key this builder reads.

pub fn validate( self, check: impl Fn(&T) -> Result<(), Error> + Send + Sync + 'static, ) -> Self

Application-level validation, run after deserializing and before anything installs — on init, on every watch reload, and on a recovery from the cache. The reload path keeps the previous snapshot when this refuses, exactly like a parse failure.

pub fn file(self, path: impl Into<String>) -> Self

Adds a configuration file. Merged in call order; later files win.

The format comes from the extension at load time. A missing file is skipped, which is what makes an optional secrets.json work.

pub fn encrypted_file(self, path: impl Into<String>) -> Self

Available on crate feature decrypt only.

Adds an encrypted configuration file — secrets.json.age.

The format comes from the extension under the suffix; the document decrypts through the installed Decryptor.

pub fn env(self, prefix: impl Into<String>) -> Self

The environment layer: prefix plus the key, as in env = "APP_".

pub fn nest(self, separator: impl Into<String>) -> Self

The nesting separator inside variable names; "__" unless said.

pub fn allow_empty_env(self) -> Self

Treats FOO= as set-to-empty rather than unset.

pub fn strict_env(self) -> Self

Refuses ambiguous environment spellings; see LoadSpec::with_strict_env.

pub fn whole_document(self) -> Self

Reads each document as this section’s values, with no section header.

The default is one file, several sections — every top-level key names one, and this builder’s key says which is yours. That is what lets a config.toml carry [db] and [server] for two configuration types that know nothing about each other.

Say this when the document is only this configuration:

{ "host": "0.0.0.0", "port": 8000 }

use dynamic_config::Builder;
let server: Server = Builder::new("server")
    .whole_document()
    .file("server.json")
    .env("APP_")
    .load()
    .expect("the sources read cleanly");

The key keeps every other job it has: APP_SERVER_PORT still reaches port, the cache entry and the diagnostics are still named after it, and "" is allowed for a configuration with nothing to call itself — the environment layer is then just the prefix, APP_PORT.

Everything else is unchanged: profile variants (server.production.json), defaults, flags, overrides, aliases, the secrets directory and a remote store’s document all behave exactly as they do for a sectioned load. It applies to every document this builder reads, because sources that disagreed about their own shape would be a configuration nobody could reason about.

pub fn env_file(self, path: impl Into<String>) -> Self

A .env file read as the environment layer, below the real thing.

pub fn secrets_dir(self, path: impl Into<String>) -> Self

A directory of single-value files: one file per key, the filename is the key, the contents are the value.

What Docker’s /run/secrets and a Kubernetes secret volume look like. Nesting is spelled in the filename with the same separator nest sets, so db__password is db.password; one trailing newline is removed, because every tool that writes a secret writes one. The layer sits above the files and below .env and the environment — a mounted secret is a deployment fact, and a variable exported for this run is a more specific one.

A directory that is not there is skipped, exactly like a missing file; one that cannot be read is a load-time error naming it.

pub fn profile_env(self, variable: impl Into<String>) -> Self

The environment variable naming the active profile.

pub fn discover( self, name: impl Into<String>, paths: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Discovery: look for {name}.{ext} in each of paths, below any explicitly listed files — the same rule as the attribute’s name + paths.

pub fn cache(self, path: impl Into<String>, mode: CacheMode) -> Self

A last-known-good cache: written after every clean init or watch reload, recovered from when the sources will not load.

CacheMode::Redacted and CacheMode::Fingerprint need to know which fields are secret, which only the generated builder() on a #[dynamic_config] type carries — on a bare Builder::new, those modes are refused at init rather than silently caching everything.

pub fn cache_encrypted( self, path: impl Into<String>, encryptor: impl Encryptor + 'static, ) -> Self

Available on crate feature decrypt only.

A last-known-good cache, encrypted at rest.

The fourth answer to the cache trade-off, and the one that collapses it: full fidelity — recovery needs nothing from the live environment — with nothing readable on disk. Written through encryptor after every clean init or watch reload; recovered through the installed Decryptor, the same door encrypted_file reads through, so one set_decryptor covers both. The path carries the format under the encryption suffix — last.json.age — exactly like an encrypted source file.

The recipient question that kept this out of the attribute era has the builder’s answer: the recipients live in the encryptor the caller constructs, at the call site that owns them.

impl Builder<Value>

pub fn values(key: impl Into<String>) -> Self

A configuration with no struct: the resolved section as data.

Sugar for Builder::<Value>::new(key), and the entry point that makes the schemaless shape findable — a plugin host, a feature-flag table, a tool inspecting somebody else’s configuration. Every source, layer and diagnostic on this builder behaves exactly as it does for a struct, because nothing in the engine ever needed one; what changes is the reading, which is by path.

use dynamic_config::{Builder, Dynamic};

let config = Dynamic::new(
    Builder::values("db").file("target/doctest/schemaless.json"),
);
let values = config.init_and_current()?;

// One atomic load above; a walk of the tree here. No struct, and no
// deserialize per read.
assert_eq!(values.get("host").and_then(|v| v.as_str()), Some("localhost"));
assert_eq!(values.get("pool.max_size").and_then(|v| v.as_i64()), Some(32));

What it does not get

A struct is a declaration, and four things follow from it that nothing can reconstruct without one:

	With a struct	Here
Types	checked at the load	checked at each read
Unknown keys	check names them	reported as not checked
Secrets	#[config(secret)]	secrets, by hand
Missing required values	the load fails	absent is None

Everything else — layering, profiles, discovery, .env, secrets_dir, watching, the last-known-good cache, reload hooks, source_of and explain — is unchanged. The exception is not about schemas: remote stores and the runtime layers live in a #[dynamic_config] type’s statics, so no builder made with new or values reaches them, whatever T is.

Trait Implementations

impl<T> Clone for Builder<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Builder<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.