Module tor_config::load

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.

Structs

• DisfavouredKey
  Key in config file(s) which is disfavoured (unrecognized or deprecated)
• ResolutionResults
  Results of a successful resolve_return_disfavoured
• ResolveContext
  Config resolution context, not used outside tor_config::load

Enums

• ConfigResolveError
  Error resolving a configuration (during deserialize, or build)

Traits

• Builder
  A type that can be built from a builder via a build method
• Resolvable
  Collection of configuration settings that can be deserialized and then built
• TopLevel
  Top-level configuration struct, made from a deserializable builder

Functions

• resolve
  Deserialize and build overall configuration from config sources
• resolve_ignore_warnings
  Deserialize and build overall configuration, silently ignoring unrecognized config keys
• resolve_return_results
  Deserialize and build overall configuration, reporting unrecognized keys in the return value