Module blockz::configuration

This is supported on crate feature configuration only.

Support for common configuration behaviour and loading them from various sources.

Direct configuration example

This example shows how to use the direct configuration. Please note that the direct configuration is usually useful in testing scenarios. Production usage is discouraged.

#[derive(Configuration)]
#[configuration(direct)]
struct ServerConfig {
    address: String,
    port: u16,
}

let config = <ServerConfig as Configuration>::load(ServerConfig {
    address: "127.0.0.1".to_string(),
    port: 58732,
}).await;
println!("Server binding to {}:{}.", config.address, config.port);
// Server binding to 127.0.0.1:58732.

If the configuration type implements Default, you can use EasyConfiguration to load the default value, like so:

#[derive(Configuration)]
#[configuration(direct)]
struct ServerConfig {
    address: String,
    port: u16,
}

impl Default for ServerConfig {
    fn default() -> ServerConfig {
        ServerConfig {
            address: "0.0.0.0".to_string(),
            port: 9999,
        }
    }
}

let config = <ServerConfig as EasyConfiguration>::load().await;
println!("Server binding to {}:{}.", config.address, config.port);
// Server binding to 0.0.0.0:9999.

Env configuration examples

NOTE: These examples require the env_configuration feature.

The first example shows how to use the env configuration with a prefix.

#[derive(Configuration, Deserialize)]
#[configuration(env(prefix = "COOL_APP_"))]
struct ServerConfig {
    #[serde(rename = "bind_addr")]
    address: String,
    #[serde(rename = "bind_port")]
    port: u16,
}

let config = <ServerConfig as EasyConfiguration>::load()
    .await
    .expect("Failed to load configuration from the environment!");
println!("Server binding to {}:{}.", config.address, config.port);
// Server binding to aaa.bbb.ccc.ddd:ppppp.

The second example shows how to use the env configuration with a prefix source in the form of a constant.

/// This is our prefix.
const PREFIX: &str = "COOL_APP_";

#[derive(Configuration, Deserialize)]
#[configuration(env(prefix_source = "PREFIX.to_string()"))]
struct ServerConfig {
    #[serde(rename = "bind_addr")]
    address: String,
    #[serde(rename = "bind_port")]
    port: u16,
}

let config = <ServerConfig as EasyConfiguration>::load()
    .await
    .expect("Failed to load configuration from the environment!");
println!("Server binding to {}:{}.", config.address, config.port);
// Server binding to aaa.bbb.ccc.ddd:ppppp.

The third example shows how to use the env configuration with a prefix source in the form of a function that can return an error. The error must be mapped to an envy::Error.

/// This function sources our prefix.
fn source_prefix() -> Result<String, envy::Error> {
    std::env::var("COOL_APP_PREFIX")
        .map_err(|err| envy::Error::Custom(format!("failed to source the prefix: {}", err)))
}

#[derive(Configuration, Deserialize)]
#[configuration(env(prefix_source = "source_prefix()?"))]
struct ServerConfig {
    #[serde(rename = "bind_addr")]
    address: String,
    #[serde(rename = "bind_port")]
    port: u16,
}

let config = <ServerConfig as EasyConfiguration>::load()
    .await
    .expect("Failed to load configuration from the environment!");
println!("Server binding to {}:{}.", config.address, config.port);
// Server binding to aaa.bbb.ccc.ddd:ppppp.

Structs

DirectConfiguration	Direct configuration that just returns the passed value.
EnvConfiguration	env_configuration Configuration that can be sourced from environment variables.

Traits

Configuration	Common behaviour of configurations.
EasyConfiguration	An easy configuration is a configuration that can be loaded without other parameters.