Module load

Processing a ConfigurationTree into a validated configuration

This module, and particularly resolve, takes care of:

• Deserializing a ConfigurationTree 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 ConfigurationTree, 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 ConfigurationTree.
• 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.

Macros

define_for_tuples 🔒

impl Resolvable for (A,B..) where A: Resolvable, B: Resolvable ...

Structs

Des 🔒

Wrapper around T that collects ignored keys as we deserialize it.

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)

PathEntry 🔒

Element of an DisfavouredKey

UnrecognizedKeys 🔒

Keys we have not recognized so far

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

copy_path 🔒

Turns a serde_ignored::Path (which is borrowed) into an owned DisfavouredKey

intersect_unrecognized_lists 🔒

Computes the intersection, resolving ignorances at different depths

ok_unquoted 🔒

Would s be OK to use unquoted as a key in a TOML file?

resolve

Deserialize and build overall configuration from config sources

resolve_ignore_warnings

Deserialize and build overall configuration, silently ignoring unrecognized config keys

resolve_inner 🔒

Deserialize and build overall configuration from config sources

resolve_return_results

Deserialize and build overall configuration, reporting unrecognized keys in the return value