Module tor_config::load

source · [−]

Expand description

Processing a config::Config into a validated configuration

This module, and particularly resolve, takes care of:

Deserializing a config::Config into various FooConfigBuilder
Calling the build() methods to get various FooConfig.
Reporting unrecognised configuration keys (eg to help the user detect misspellings).

This is step 3 of the overall config processing, as described in the crate-level documentation.

Starting points

To use this, you will need to:

#[derive(Builder)] and use impl_standard_builder! for all of your configuration structures, using #[sub_builder] etc. sa appropriate, and making your builders Deserialize.
impl TopLevel for your top level structures (only).
Call resolve (or one of its variants) with a config::Config, to obtain your top-level configuration(s).

Example

In this example the developers are embedding arti, arti_client, etc., into a program of their own. The example code shown:

Defines a configuration structure EmbedderConfig, for additional configuration settings for the added features.
Establishes some configuration sources (the trivial empty ConfigSources, to avoid clutter in the example)
Reads those sources into a single configuration taxonomy config::Config.
Processes that configuration into a 3-tuple of configuration structs for the three components, namely:
- TorClientConfig, the configuration for the arti_client crate’s TorClient
- ArtiConfig, for behaviours in the arti command line utility
- EmbedderConfig.
Will report a warning to the user about config settings found in the config files, but not recognized by any of the three config consumers,

use derive_builder::Builder;
use tor_config::{impl_standard_builder, resolve, ConfigBuildError, ConfigurationSources};
use tor_config::load::TopLevel;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Builder, Eq, PartialEq)]
#[builder(build_fn(error = "ConfigBuildError"))]
#[builder(derive(Debug, Serialize, Deserialize))]
struct EmbedderConfig {
    // ....
}
impl_standard_builder! { EmbedderConfig }
impl TopLevel for EmbedderConfig {
    type Builder = EmbedderConfigBuilder;
}

let cfg_sources = ConfigurationSources::new_empty(); // In real program, use from_cmdline
let cfg = cfg_sources.load()?;

let (tcc, arti_config, embedder_config) =
     tor_config::resolve::<(TorClientConfig, ArtiConfig, EmbedderConfig)>(cfg)?;

let _: EmbedderConfig = embedder_config; // etc.