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.

Structs

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

Enums

Traits

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

Functions

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