From f3fa77be6f2a9d6248ff06f385f69d4983263d05 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 6 Dec 2022 15:48:53 +0000 Subject: [PATCH 1/2] tor-config: Add "particular situations" sections and mention list_builder --- crates/tor-config/README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/crates/tor-config/README.md b/crates/tor-config/README.md index db0250326..345b7fd63 100644 --- a/crates/tor-config/README.md +++ b/crates/tor-config/README.md @@ -50,4 +50,15 @@ See the [`tor_config::load` module-level documentation](load). 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. + +--- License: MIT OR Apache-2.0 From dc3c7651ca584c8b3e2ee05e41a870f16eb7a08d Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 6 Dec 2022 15:51:27 +0000 Subject: [PATCH 2/2] tor-config: Document how to reject compiled-out features Fixes #654 --- crates/tor-config/README.md | 49 +++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/crates/tor-config/README.md b/crates/tor-config/README.md index 345b7fd63..0b818abbf 100644 --- a/crates/tor-config/README.md +++ b/crates/tor-config/README.md @@ -60,5 +60,54 @@ 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