Struct ConfigurationLoader 

pub struct ConfigurationLoader { /* private fields */ }

A configuration loader that can pull from various sources.

This loader provides a wrapper around a lower-level library, figment, to expose a simpler and focused API for both loading configuration data from various sources, as well as querying it.

A variety of configuration sources can be configured (see below), with an implicit priority based on the order in which sources are added: sources added later take precedence over sources prior. Additionally, either a typed value can be extracted from the configuration (into_typed), or the raw configuration data can be accessed via a generic API (into_generic).

Supported sources

• YAML file
• JSON file
• environment variables (must be prefixed; see from_environment)

Implementations

impl ConfigurationLoader

pub fn with_key_aliases( self, aliases: &'static [(&'static str, &'static str)], ) -> Self

Sets key aliases to apply when loading file-based configuration sources.

Each entry is (nested_path, flat_key). When a YAML or JSON file contains a value at nested_path (dot-separated), that value is also emitted under flat_key at the top level — but only if flat_key is not already explicitly set at the top level. This ensures that both YAML nested format and flat env var format produce the same Figment key, so source precedence (env vars > file) works correctly.

Must be called before any file-loading methods (from_yaml, etc.) to take effect.

pub fn add_providers<P, I>(self, providers: I) -> Self

where P: Provider + Send + Sync + 'static, I: IntoIterator<Item = P>,

Appends one or more providers to the configuration chain.

Sources are merged in the order they are added: later sources take precedence over earlier ones. Call this method after any file-loading methods and before from_environment to place the added providers at the correct intermediate precedence level:

file providers  <  add_providers(...)  <  from_environment(...)

pub fn from_yaml<P>(self, path: P) -> Result<Self, ConfigurationError>

where P: AsRef<Path>,

Loads the given YAML configuration file.

Errors

If the file could not be read, or if the file is not valid YAML, an error will be returned.

pub fn try_from_yaml<P>(self, path: P) -> Self

where P: AsRef<Path>,

Attempts to load the given YAML configuration file, ignoring any errors.

Errors include the file not existing, not being readable/accessible, and not being valid YAML.

pub fn from_json<P>(self, path: P) -> Result<Self, ConfigurationError>

where P: AsRef<Path>,

Loads the given JSON configuration file.

Errors

If the file could not be read, or if the file is not valid JSON, an error will be returned.

pub fn try_from_json<P>(self, path: P) -> Self

where P: AsRef<Path>,

Attempts to load the given JSON configuration file, ignoring any errors.

Errors include the file not existing, not being readable/accessible, and not being valid JSON.

pub fn from_environment( self, prefix: &'static str, ) -> Result<Self, ConfigurationError>

Loads configuration from environment variables.

The prefix given will have an underscore appended to it if it does not already end with one. For example, with a prefix of app, any environment variable starting with app_ would be matched. The prefix is case-insensitive.

Sources are merged in the order they are added, with later sources taking precedence over earlier ones. Sources added after this call will have higher precedence than environment variables.

Errors

If the prefix is empty, an error will be returned.

pub async fn with_default_secrets_resolution( self, ) -> Result<Self, ConfigurationError>

Resolves secrets in the configuration based on available secret backend configuration.

This will attempt to resolve any secret references (format shown below) in the configuration by using a “secrets backend”, which is a user-provided command that utilizes a simple JSON-based protocol to accept secrets to resolve, and return those resolved secrets, or the errors that occurred during resolving.

Configuration

This method uses the existing configuration (see Caveats) to determine the secrets backend configuration. The following configuration settings are used:

• secret_backend_command: The executable to resolve secrets. (required)
• secret_backend_timeout: The timeout for the secrets backend command, in seconds. (optional, default: 30)

Usage

For any value which should be resolved as a secret, the value should be a string in the format of ENC[secret_reference]. The secret_reference portion is the value that will be sent to the backend command during resolution. There is no limitation on the format of the secret_reference value, so long as it can be expressed through the existing configuration sources (YAML, environment variables, etc).

The entire configuration value must match this pattern, and cannot be used to replace only part of a value, so values such as db-ENC[secret_reference] would not be detected as secrets and thus would not be resolved.

Protocol

The executable is expected to accept a JSON object on stdin, with the following format:

{
  "version": "1.0",
  "secrets": ["key1", "key2"]
}

The executable is expected return a JSON object on stdout, with the following format:

{
  "key1": {
    "value": "my_secret_password",
    "error": null
  },
  "key2": {
    "value": null,
    "error": "could not fetch the secret"
  }
}

If any entry in the response has an error value that is anything but null, the overall resolution will be considered failed.

Caveats

Time of resolution

Secrets resolution happens at the time this method is called, and only resolves configuration values that are already present in the configuration, which means all calls to load configuration (try_from_yaml, from_environment, etc) must be made before calling this method.

Sensitive data in error output

Care should be taken to not return sensitive information in either the error output (standard error) of the backend command or the error field in the JSON response, as these values are logged in order to aid debugging.

pub fn with_dynamic_configuration( self, receiver: Receiver<ConfigUpdate>, ) -> Self

Enables dynamic configuration.

The receiver is used in run_dynamic_config_updater to handle retrieving the initial snapshot and subsequent updates.

pub fn into_typed<'a, T>(self) -> Result<T, ConfigurationError>

where T: Deserialize<'a>,

Consumes the configuration loader, deserializing it as T.

Errors

If the configuration could not be deserialized into T, an error will be returned.

pub fn bootstrap_generic(&self) -> GenericConfiguration

Creates a bootstrap GenericConfiguration without consuming the loader.

This creates a static snapshot of the configuration loaded so far. As this is intended for bootstrapping before dynamic configuration is active, the dynamic provider is ignored.

pub async fn into_generic( self, ) -> Result<GenericConfiguration, ConfigurationError>

Consumes the configuration loader and wraps it in a generic wrapper.

pub async fn for_tests( file_values: Option<Value>, env_vars: Option<&[(String, String)]>, enable_dynamic_configuration: bool, ) -> (GenericConfiguration, Option<Sender<ConfigUpdate>>)

Configures a GenericConfiguration that is suitable for tests.

This configures the loader with the following defaults:

• configuration from a JSON file
• configuration from environment variables

If enable_dynamic_configuration is true, a dynamic configuration sender is returned.

This is generally only useful for testing purposes, and is exposed publicly in order to be used in cross-crate testing scenarios.

pub async fn for_tests_with_provider_factory<P, F>( file_values: Option<Value>, env_vars: Option<&[(String, String)]>, enable_dynamic_configuration: bool, key_aliases: &'static [(&'static str, &'static str)], provider_factory: F, ) -> (GenericConfiguration, Option<Sender<ConfigUpdate>>)

where P: Provider + Send + Sync + 'static, F: FnOnce() -> P,

Like for_tests, but applies key_aliases during file loading and calls provider_factory to build an additional provider inserted between the file provider and the environment provider.

The factory is called after test environment variables have been set, so any env var reads it performs (e.g. in DatadogRemapper) are consistent with the test’s env setup.

This is generally only useful for testing purposes, and is exposed publicly in order to be used in cross-crate testing scenarios.

Trait Implementations

impl Clone for ConfigurationLoader

fn clone(&self) -> ConfigurationLoader

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for ConfigurationLoader

fn default() -> ConfigurationLoader

Returns the “default value” for a type.