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 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.

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.

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.