Expand description
§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
usesConfigurationSources::from_cmdline
. -
ConfigurationSources::load
actually reads all of these sources, parses them (eg, as TOML files), and returns aConfigurationTree
. 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 concreteConfigBuilder
s for the configuration consumers within the program. (Forarti
, that’sTorClientConfigBuilder
andArtiBuilder
). This mapping is done using theDeserialize
implementations on theBuilder
s.resolve
then calls thebuild()
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 theload
module documentation. -
The resulting configuration objects (eg,
TorClientConfig
,ArtiConfig
) are provided to the code that must use them (eg, to make aTorClient
).
See the
tor_config::load
module-level documentation.
for an example.
§Facilities and approaches for particular situations
§Lists
When the configuration contains a list of items which the user is likely to want to add entries to piecemeal, modify, filter, and so on, use the list builder helper facilities in the list_builder module.
§Configuration items which are conditionally compiled
If the user requests, via the configuration, a feature which is compiled out (due to the non-selection of cargo features), it is usually right to have the code simply ignore it.
This can be achieved by applying the appropriate #[cfg]
to configuration fields and structs.
The result is that if the user does specify the relevant options,
Arti will generate an “unknown configuration item” warning.
(In the future it might be nice to
provide a message saying what feature was missing.)
§Config items which must be detected and rejected even when compiled out
For example, if Arti is compiled without bridge support, a configuration specifying use of bridges should result in failure, rather than a direct connection.
In those cases, you should unconditionally include the configuration fields which must be detected and rejected.
Then provide alternative “when-compiled-out” versions of the types for those fields.
(If the field is a list which, when enabled, uses list_builder
,
provide alternative “when-compiled-out” versions of the entry types.)
The built form of the configuration (Field
or Entry
in the case of a list),
should be a #[non_exhaustive]
empty enum.
It should implement all the same standard traits as the compiled-in version.
So everything will compile.
But, since it is an uninhabited type, no such value can ever actually appear.
The builder form (FieldBuilder
or EntryBuilder
)
should be an empty #[non_exhaustive]
struct.
It should have a trivial Deserialize
impl which always returns successfully,
and a derived Serialize
impl (and the usual traits).
This will allow configurations which attempt to specify such a value
to be recognised.
To get this to compile, naturally,
the builder will have to have a .build()
method.
This should return ConfigBuildError::Invalid
.
(it can’t return the uninhabited built type, obviously.)
The configuration resolution arrangements are set up to call this,
and will report the error.
For an example, see crates/tor-guardmgr/src/bridge_disabled.rs
.
License: MIT OR Apache-2.0
Re-exports§
pub use cmdline::CmdLine;
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 sources::ConfigurationSource;
pub use sources::ConfigurationSources;
Modules§
- cmdline
- Implement a configuration source based on command-line arguments.
- extend_
builder - Functionality for merging one config builder into another.
- file_
watcher - Code to watch configuration files for any changes.
- list_
builder - Lists in builders
- load
- Processing a
ConfigurationTree
into a validated configuration - map_
builder - Helper for defining sub-builders that map a serializable type (typically String) to a configuration type.
- mistrust
- Helpers for
fs-mistrust
configuration. - sources
ConfigurationSources
: Helper for handling configuration files- testing
testing
- Helpers for testing configuration.
Macros§
- assert_
config_ error testing
- Assert that the specified error is the specified
kind
ofConfigBuildError
. - convert_
helper_ via_ multi_ line_ list_ builder - Implement
TryFrom<MultilineListBuilder>
andInto<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
- define_
map_ builder - Define a map type, and an associated builder struct, suitable for use in a configuration object.
- derive_
deftly_ template_ Extend Builder - Provide an
ExtendBuilder
implementation for a struct’s builder. - derive_
deftly_ template_ Flattenable - Derives
Flattenable
for a struct - impl_
not_ auto_ value - A macro that implements
NotAutoValue
for your type. - impl_
standard_ builder - Defines standard impls for a struct with a
Builder
, inclDefault
Structs§
- Configuration
Tree - A set of configuration fields, represented as a set of nested K=V mappings.
- Flatten
- Helper for flattening deserialisation, compatible with
serde_ignored
- Invalid
Bool OrAuto - Boolean or
"auto"
configuration is invalid - Listen
- Specification of (possibly) something to listen on (eg, a port, or some addresses/ports)
- Listen
Unsupported Listen
configuration specified something not supported by application code- MutCfg
- A mutable configuration object.
Enums§
- Bool
OrAuto - Boolean, but with additional
"auto"
option - Config
Build Error - An error related to an option passed to Arti via a configuration builder.
- Config
Error - An error that occurs while trying to read and process our configuration.
- Explicit
OrAuto - A serializable value, or auto.
- Invalid
Listen - Listen configuration is invalid
- Padding
Level - Padding enablement - rough amount of padding requested
- Reconfigure
- Rules for reconfiguring a running Arti instance.
- Reconfigure
Error - An error caused when attempting to reconfigure an existing Arti client, or one of its modules.
Traits§
- Flattenable
- Types that can be used with
Flatten
- NotAuto
Value - A marker trait for types that do not serialize to the same value as
ExplicitOrAuto::Auto
.
Functions§
- resolve_
alternative_ specs - Helper for resolving a config item which can be specified in multiple ways
- resolve_
option - Resolves an
Option<Option<T>>
(in a builder) into anOption<T>
- resolve_
option_ general - Resolves an
Option<Option<T>>
(in a builder) into anOption<T>
, more generally