Struct Config 

pub struct Config { /* private fields */ }

The main configuration container

Config provides lazy resolution of interpolation expressions and caches resolved values for efficiency.

Implementations

impl Config

pub fn new(value: Value) -> Self

Create a new Config from a Value

The config will use resolvers from the global registry.

pub fn with_options(value: Value, options: ConfigOptions) -> Self

Create a Config with custom options

The config will use resolvers from the global registry.

pub fn with_resolvers(value: Value, resolvers: ResolverRegistry) -> Self

Create a Config with a custom resolver registry

pub fn from_yaml(yaml: &str) -> Result<Self>

Load configuration from a YAML string

pub fn from_yaml_with_options( yaml: &str, options: ConfigOptions, ) -> Result<Self>

Load configuration from a YAML string with options

pub fn load(path: impl AsRef<Path>) -> Result<Self>

Load configuration from a YAML file (required - errors if missing)

This is the primary way to load configuration. Use Config::optional() for files that may not exist.

Supports glob patterns like config/*.yaml or config/**/*.yaml. When a glob pattern is used, matching files are sorted alphabetically and merged in order (later files override earlier ones).

Example

let config = Config::load("config.yaml")?;
let merged = Config::load("config/*.yaml")?;

pub fn load_with_options( path: impl AsRef<Path>, options: ConfigOptions, ) -> Result<Self>

Load a configuration file with custom options

This is the main entry point for loading config with HTTP/TLS/proxy options. Supports glob patterns like config/*.yaml or config/**/*.yaml. When a glob pattern is used, matching files are sorted alphabetically and merged in order.

Example

let mut options = ConfigOptions::default();
options.allow_http = true;
options.http_proxy = Some("http://proxy:8080".into());
let config = Config::load_with_options("config.yaml", options)?;

pub fn required(path: impl AsRef<Path>) -> Result<Self>

Alias for load() - load a required config file

Provided for symmetry with Config::optional().

pub fn required_with_options( path: impl AsRef<Path>, options: ConfigOptions, ) -> Result<Self>

Load a required config file with custom options

pub fn optional(path: impl AsRef<Path>) -> Result<Self>

Load an optional configuration file

Returns an empty Config if the file doesn’t exist. Use this for configuration files that may or may not be present, such as local overrides.

Supports glob patterns like config/*.yaml or config/**/*.yaml. When a glob pattern is used, matching files are sorted alphabetically and merged in order. Returns empty config if no files match.

Example

let base = Config::load("base.yaml")?;
let local = Config::optional("local.yaml")?;
let overrides = Config::optional("config/*.yaml")?;
base.merge(&local);

pub fn merge(&mut self, other: Config)

Merge another config into this one

The other config’s values override this config’s values per ADR-004 merge semantics. File roots from both configs are unioned for path traversal protection.

pub fn from_json(json: &str) -> Result<Self>

Load configuration from a JSON string

pub fn set_schema(&mut self, schema: Schema)

Set or replace the schema for default value lookup

When a schema is attached, get() will return schema defaults for missing paths instead of raising PathNotFoundError.

Note: Setting a schema clears the value cache since defaults may now affect lookups.

pub fn get_schema(&self) -> Option<&Schema>

Get a reference to the attached schema, if any

pub fn get_raw(&self, path: &str) -> Result<&Value>

Get the raw (unresolved) value at a path

pub fn get(&self, path: &str) -> Result<Value>

Get a resolved value at a path

This resolves any interpolation expressions in the value. Resolved values are cached for subsequent accesses.

If a schema is attached and the path is not found (or is null when null is not allowed), the schema default is returned instead.

pub fn get_string(&self, path: &str) -> Result<String>

Get a resolved string value, with type coercion if needed

pub fn get_i64(&self, path: &str) -> Result<i64>

Get a resolved integer value, with type coercion if needed

pub fn get_f64(&self, path: &str) -> Result<f64>

Get a resolved float value, with type coercion if needed

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

Get a resolved boolean value, with strict coercion per ADR-012

pub fn resolve_all(&self) -> Result<()>

Resolve all values in the configuration eagerly

pub fn to_value(&self, resolve: bool, redact: bool) -> Result<Value>

Export the configuration as a Value

Arguments

• resolve - If true, resolve interpolations (${…}). If false, show placeholders.
• redact - If true, replace sensitive values with “[REDACTED]”. Only applies when resolve=true.

Examples

// Show raw config with placeholders (safest, fastest)
let raw = config.to_value(false, false)?;

// Resolved with secrets redacted (safe for logs)
let safe = config.to_value(true, true)?;

// Resolved with secrets visible (use with caution)
let full = config.to_value(true, false)?;

pub fn to_yaml(&self, resolve: bool, redact: bool) -> Result<String>

Export the configuration as YAML

Arguments

• resolve - If true, resolve interpolations (${…}). If false, show placeholders.
• redact - If true, replace sensitive values with “[REDACTED]”. Only applies when resolve=true.

Examples

// Show raw config with placeholders
let yaml = config.to_yaml(false, false)?;

// Resolved with secrets redacted
let yaml = config.to_yaml(true, true)?;

pub fn to_json(&self, resolve: bool, redact: bool) -> Result<String>

Export the configuration as JSON

Arguments

• resolve - If true, resolve interpolations (${…}). If false, show placeholders.
• redact - If true, replace sensitive values with “[REDACTED]”. Only applies when resolve=true.

Examples

// Show raw config with placeholders
let json = config.to_json(false, false)?;

// Resolved with secrets redacted
let json = config.to_json(true, true)?;

pub fn clear_cache(&self)

Clear the resolution cache

pub fn get_source(&self, path: &str) -> Option<&str>

Get the source file for a config path

Returns the filename of the config file that provided this value. For merged configs, this returns the file that “won” for this path.

pub fn dump_sources(&self) -> &HashMap<String, String>

Get all source mappings

Returns a map of config paths to their source filenames. Useful for debugging which file each value came from.

pub fn register_resolver(&mut self, resolver: Arc<dyn Resolver>)

Register a custom resolver

pub fn validate_raw(&self, schema: Option<&Schema>) -> Result<()>

Validate the raw (unresolved) configuration against a schema

This performs structural validation (Phase 1 per ADR-007):

• Required keys are present
• Object/array structure matches
• Interpolations (${…}) are allowed as placeholders

If schema is None, uses the attached schema (set via set_schema()). Returns an error if no schema is provided and none is attached.

pub fn validate(&self, schema: Option<&Schema>) -> Result<()>

Validate the resolved configuration against a schema

This performs type/value validation (Phase 2 per ADR-007):

• Resolved values match expected types
• Constraints (min, max, pattern, enum) are checked

If schema is None, uses the attached schema (set via set_schema()). Returns an error if no schema is provided and none is attached.

pub fn validate_collect(&self, schema: Option<&Schema>) -> Vec<ValidationError>

Validate and collect all errors (instead of failing on first)

If schema is None, uses the attached schema (set via set_schema()). Returns a single error if no schema is provided and none is attached.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.