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 prepare(&self) -> Result<Commit, Error>

where T: Send + '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.

impl<T: DeserializeOwned + Send + '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.

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 validate(self, check: fn(&T) -> Result<(), Error>) -> 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 env_file(self, path: impl Into<String>) -> Self

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

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.

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.