diff options
| -rw-r--r-- | crates/tor-config/README.md | 42 |
1 files changed, 41 insertions, 1 deletions
diff --git a/crates/tor-config/README.md b/crates/tor-config/README.md index 272d795ab..bd5eabc30 100644 --- a/crates/tor-config/README.md +++ b/crates/tor-config/README.md @@ -8,7 +8,47 @@ This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to implement [Tor](https://www.torproject.org/) in Rust. -It provides low-level types for handling configuration values. +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: + + 1. We use [`tor_config::ConfigurationSources`](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`]. + + 2. [`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. + + 3. We call one of the [`tor_config::resolve`](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 `Builder`s. + `resolve` then calls the `build()` method on each of these parts of the configuration + which applies defaults and validates the resulting configuation. + + 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. + + 4. 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](load). +for an example. ## ⚠ Stability Warning ⚠ |