Crate tor_config

Expand description

tor-config

tor-config: Tools for configuration management in Arti

Overview

This crate is part of Arti, a project to implement Tor in Rust.

It provides types for handling configuration values, and general machinery for configuration management.

Configuration in Arti

The configuration for the arti command line program, and other programs which embed Arti reusing the configuration machinery, works as follows:

We use tor_config::ConfigurationSources to enumerate the various places where configuration information needs to come from, and configure how they are to be read. arti uses ConfigurationSources::from_cmdline.
ConfigurationSources::load actually reads all of these sources, parses them (eg, as TOML files), and returns a config::Config. This is a tree-structured dynamically typed data structure, mirroring the input configuration structure, largely unvalidated, and containing everything in the input config sources.
We call one of the tor_config::resolve family. This maps the input configuration data to concrete ConfigBuilder s for the configuration consumers within the program. (For arti, that’s TorClientConfigBuilder and ArtiBuilder). This mapping is done using the Deserialize implementations on the Builders. resolve then calls the build() method on each of these parts of the configuration which applies defaults and validates the resulting configuration.

It is important to call resolve once for all the configuration consumers, so that it sees a unified view of which config settings in the input were unrecognized, and therefore may need to be reported to the user. See the example in the load module documentation.
The resulting configuration objects (eg, TorClientConfig, ArtiConfig) are provided to the code that must use them (eg, to make a TorClient).

See the tor_config::load module-level documentation. for an example.

License: MIT OR Apache-2.0

Re-exports

pub use cmdline::CmdLine;

pub use config as config_crate;

pub use educe;

pub use list_builder::MultilineListBuilder;

pub use list_builder::MultilineListBuilderError;

pub use load::resolve;

pub use load::resolve_ignore_warnings;

pub use load::resolve_return_results;

pub use serde;

pub use sources::ConfigurationSource;

pub use sources::ConfigurationSources;

Modules

Implement a configuration source based on command-line arguments.

Lists in builders

Processing a config::Config into a validated configuration

ConfigurationSources: Helper for handling configuration files

Macros

convert_helper_via_multi_line_list_builder

Implement TryFrom<MultilineListBuilder> and Into<MultilineListBuilder> for $Builder.

define_list_builder_accessors

Define accessor methods for a configuration item which is a list

define_list_builder_helper

Define a list builder struct for use with define_list_builder_accessors

impl_standard_builder

Defines standard impls for a struct with a Builder, incl Default

macro_first_nonempty

Helper for assisting with macro “argument” defaulting

Structs

A path in a configuration file: tilde expansion is performed, along with expansion of certain variables.

Wrapper for config::ConfigError with a more helpful error message.

InvalidBoolOrAuto

Boolean or "auto" configuration is invalid

Specification of (possibly) something to listen on (eg, a port, or some addresses/ports)

ListenUnsupported

Listen configuration specified something not supported by application code

A mutable configuration object.

Enums

Boolean, but with additional "auto" option

An error that has occurred while expanding a path.

ConfigBuildError

An error related to an option passed to Arti via a configuration builder.

Listen configuration is invalid

Padding enablement - rough amount of padding requested

Rules for reconfiguring a running Arti instance.

ReconfigureError

An error caused when attempting to reconfigure an existing Arti client, or one of its modules.

Traits

An Iterator blanket implementation that provides extra adaptors and methods.

Functions

resolve_alternative_specs

Helper for resolving a config item which can be specified in multiple ways

Resolves an Option<Option<T>> (in a builder) into an Option<T>

resolve_option_general

Resolves an Option<Option<T>> (in a builder) into an Option<T>, more generally