tor_config/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3// @@ begin lint list maintained by maint/add_warning @@
4#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)
5#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)
6#![warn(missing_docs)]
7#![warn(noop_method_call)]
8#![warn(unreachable_pub)]
9#![warn(clippy::all)]
10#![deny(clippy::await_holding_lock)]
11#![deny(clippy::cargo_common_metadata)]
12#![deny(clippy::cast_lossless)]
13#![deny(clippy::checked_conversions)]
14#![warn(clippy::cognitive_complexity)]
15#![deny(clippy::debug_assert_with_mut_call)]
16#![deny(clippy::exhaustive_enums)]
17#![deny(clippy::exhaustive_structs)]
18#![deny(clippy::expl_impl_clone_on_copy)]
19#![deny(clippy::fallible_impl_from)]
20#![deny(clippy::implicit_clone)]
21#![deny(clippy::large_stack_arrays)]
22#![warn(clippy::manual_ok_or)]
23#![deny(clippy::missing_docs_in_private_items)]
24#![warn(clippy::needless_borrow)]
25#![warn(clippy::needless_pass_by_value)]
26#![warn(clippy::option_option)]
27#![deny(clippy::print_stderr)]
28#![deny(clippy::print_stdout)]
29#![warn(clippy::rc_buffer)]
30#![deny(clippy::ref_option_ref)]
31#![warn(clippy::semicolon_if_nothing_returned)]
32#![warn(clippy::trait_duplication_in_bounds)]
33#![deny(clippy::unchecked_time_subtraction)]
34#![deny(clippy::unnecessary_wraps)]
35#![warn(clippy::unseparated_literal_suffix)]
36#![deny(clippy::unwrap_used)]
37#![deny(clippy::mod_module_files)]
38#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
39#![allow(clippy::uninlined_format_args)]
40#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
41#![allow(clippy::result_large_err)] // temporary workaround for arti#587
42#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
43#![allow(clippy::needless_lifetimes)] // See arti#1765
44#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060
45#![allow(clippy::collapsible_if)] // See arti#2342
46#![deny(clippy::unused_async)]
47//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
48
49pub mod cmdline;
50pub mod derive;
51mod err;
52#[macro_use]
53pub mod extend_builder;
54pub mod file_watcher;
55mod flatten;
56pub mod list_builder;
57mod listen;
58pub mod load;
59pub mod map_builder;
60pub mod metrics;
61mod misc;
62pub mod mistrust;
63mod mut_cfg;
64pub mod setter_traits;
65pub mod sources;
66#[cfg(feature = "testing")]
67pub mod testing;
68
69#[doc(hidden)]
70pub mod deps {
71 pub use educe;
72 pub use figment;
73 pub use itertools::Itertools;
74 pub use paste::paste;
75 pub use serde;
76 pub use serde_value;
77 pub use tor_basic_utils::{if_empty, macro_first_nonempty};
78}
79
80pub use cmdline::CmdLine;
81pub use err::{ConfigBuildError, ConfigError, ConfigGetValueError, ReconfigureError};
82pub use flatten::{Flatten, Flattenable};
83pub use list_builder::{MultilineListBuilder, MultilineListBuilderError};
84pub use listen::*;
85pub use load::{resolve, resolve_ignore_warnings, resolve_return_results};
86pub use metrics::*;
87pub use misc::*;
88pub use mut_cfg::MutCfg;
89use serde::de::DeserializeOwned;
90pub use sources::{ConfigurationSource, ConfigurationSources};
91use tor_error::into_internal;
92
93#[doc(hidden)]
94pub use derive_deftly;
95#[doc(hidden)]
96pub use flatten::flattenable_extract_fields;
97
98derive_deftly::template_export_semver_check! { "0.12.1" }
99
100/// A set of configuration fields, represented as a set of nested K=V
101/// mappings.
102///
103/// (This is a wrapper for an underlying type provided by the library that
104/// actually does our configuration.)
105#[derive(Clone, Debug, Default)]
106#[must_use] // to prevent errors from merge_from.
107pub struct ConfigurationTree(figment::Figment);
108
109impl ConfigurationTree {
110 #[cfg(test)]
111 pub(crate) fn get_string(&self, key: &str) -> Result<String, crate::ConfigError> {
112 use figment::value::Value as V;
113 let val = self.0.find_value(key).map_err(ConfigError::from_cfg_err)?;
114 Ok(match val {
115 V::String(_, s) => s.clone(),
116 V::Num(_, n) => n.to_i128().expect("Failed to extract i128").to_string(),
117 _ => format!("{:?}", val),
118 })
119 }
120
121 /// Return the value with a given key as some type that implements Deserialize.
122 ///
123 /// Return `None` if no such value is set in this tree.
124 pub fn get_serde_value<T: DeserializeOwned>(
125 &self,
126 key: &str,
127 ) -> Result<Option<T>, ConfigGetValueError> {
128 use figment::error::{Error as FError, Kind::MissingField};
129 match self.0.extract_inner(key) {
130 Ok(v) => Ok(Some(v)),
131 Err(FError {
132 kind: MissingField(..),
133 ..
134 }) => Ok(None),
135 Err(e) => Err(into_internal!("Unexpected error looking up config value")(e).into()),
136 }
137 }
138
139 /// Override our current tree with the settings in `config`.
140 ///
141 /// `config` must be implement [`Serialize`](serde::Serialize),
142 /// and must serialize to a map.
143 ///
144 /// This operation follows the same as are used when reading
145 /// multiple configuration files in sequence,
146 /// where option settings in later files replace earlier ones.
147 #[allow(clippy::unnecessary_wraps)]
148 pub fn merge_from<T>(&mut self, config: &T) -> Result<(), ConfigError>
149 where
150 T: serde::Serialize,
151 {
152 let provider = figment::providers::Serialized::from(config, figment::Profile::Default);
153 let mut orig = figment::Figment::new();
154 std::mem::swap(&mut orig, &mut self.0);
155 self.0 = orig.merge(provider);
156 // Figment::merge handles errors by making the type of the figment itself into an error...
157 // but we don't want our API to rely on that, so we let method returna Result.
158 Ok(())
159 }
160}
161
162/// Rules for reconfiguring a running Arti instance.
163#[derive(Debug, Clone, Copy, Eq, PartialEq)]
164#[non_exhaustive]
165pub enum Reconfigure {
166 /// Perform no reconfiguration unless we can guarantee that all changes will be successful.
167 AllOrNothing,
168 /// Try to reconfigure as much as possible; warn on fields that we cannot reconfigure.
169 WarnOnFailures,
170 /// Don't reconfigure anything: Only check whether we can guarantee that all changes will be successful.
171 CheckAllOrNothing,
172}
173
174impl Reconfigure {
175 /// Called when we see a disallowed attempt to change `field`: either give a ReconfigureError,
176 /// or warn and return `Ok(())`, depending on the value of `self`.
177 pub fn cannot_change<S: AsRef<str>>(self, field: S) -> Result<(), ReconfigureError> {
178 match self {
179 Reconfigure::AllOrNothing | Reconfigure::CheckAllOrNothing => {
180 Err(ReconfigureError::CannotChange {
181 field: field.as_ref().to_owned(),
182 })
183 }
184 Reconfigure::WarnOnFailures => {
185 tracing::warn!("Cannot change {} on a running client.", field.as_ref());
186 Ok(())
187 }
188 }
189 }
190}
191
192/// Resolves an `Option<Option<T>>` (in a builder) into an `Option<T>`
193///
194/// * If the input is `None`, this indicates that the user did not specify a value,
195/// and we therefore use `def` to obtain the default value.
196///
197/// * If the input is `Some(None)`, or `Some(Some(Default::default()))`,
198/// the user has explicitly specified that this config item should be null/none/nothing,
199/// so we return `None`.
200///
201/// * Otherwise the user provided an actual value, and we return `Some` of it.
202///
203/// See <https://gitlab.torproject.org/tpo/core/arti/-/issues/488>
204///
205/// For consistency with other APIs in Arti, when using this,
206/// do not pass `setter(strip_option)` to derive_builder.
207///
208/// # ⚠ Stability Warning ⚠
209///
210/// We may significantly change this so that it is an method in an extension trait.
211//
212// This is an annoying AOI right now because you have to write things like
213// #[builder(field(build = r#"tor_config::resolve_option(&self.dns_port, || None)"#))]
214// pub(crate) dns_port: Option<u16>,
215// which recapitulates the field name. That is very much a bug hazard (indeed, in an
216// early version of some of this code I perpetrated precisely that bug).
217// Fixing this involves a derive_builder feature.
218pub fn resolve_option<T, DF>(input: &Option<Option<T>>, def: DF) -> Option<T>
219where
220 T: Clone + Default + PartialEq,
221 DF: FnOnce() -> Option<T>,
222{
223 resolve_option_general(
224 input.as_ref().map(|ov| ov.as_ref()),
225 |v| v == &T::default(),
226 def,
227 )
228}
229
230/// Resolves an `Option<Option<&T>>` (in a builder) into an `Option<T>`, more generally
231///
232/// Like [`resolve_option`], but:
233///
234/// * Doesn't rely on `T` being `Default + PartialEq`
235/// to determine whether it's the sentinel value;
236/// instead, takes `is_sentinel`.
237///
238/// * Takes `Option<Option<&T>>` which is more general, but less like the usual call sites.
239///
240/// # Behavior
241///
242/// * If the input is `None`, this indicates that the user did not specify a value,
243/// and we therefore use `def` to obtain the default value.
244///
245/// * If the input is `Some(None)`, or `Some(Some(v))` where `is_sentinel(v)` returns true,
246/// the user has explicitly specified that this config item should be null/none/nothing,
247/// so we return `None`.
248///
249/// * Otherwise the user provided an actual value, and we return `Some` of it.
250///
251/// See <https://gitlab.torproject.org/tpo/core/arti/-/issues/488>
252///
253/// # ⚠ Stability Warning ⚠
254///
255/// We may significantly change this so that it is an method in an extension trait.
256///
257/// # Example
258/// ```
259/// use tor_config::resolve_option_general;
260///
261/// // Use 0 as a sentinel meaning "explicitly clear" in this example
262/// let is_sentinel = |v: &i32| *v == 0;
263///
264/// // No value provided: use default
265/// assert_eq!(
266/// resolve_option_general(None, is_sentinel, || Some(10)),
267/// Some(10),
268/// );
269///
270/// // Explicitly None
271/// assert_eq!(
272/// resolve_option_general(Some(None), is_sentinel, || Some(10)),
273/// None,
274/// );
275///
276/// // Sentinel value (0) -> return None
277/// assert_eq!(
278/// resolve_option_general(Some(Some(&0)), is_sentinel, || Some(10)),
279/// None,
280/// );
281///
282/// // Set to actual value -> return that value
283/// assert_eq!(
284/// resolve_option_general(Some(Some(&5)), is_sentinel, || Some(10)),
285/// Some(5),
286/// );
287/// ```
288pub fn resolve_option_general<T, ISF, DF>(
289 input: Option<Option<&T>>,
290 is_sentinel: ISF,
291 def: DF,
292) -> Option<T>
293where
294 T: Clone,
295 DF: FnOnce() -> Option<T>,
296 ISF: FnOnce(&T) -> bool,
297{
298 match input {
299 None => def(),
300 Some(None) => None,
301 Some(Some(v)) if is_sentinel(v) => None,
302 Some(Some(v)) => Some(v.clone()),
303 }
304}
305
306/// Defines standard impls for a struct with a `Builder`, incl `Default`
307///
308/// **Use this.** Do not `#[derive(Builder, Default)]`. That latter approach would produce
309/// wrong answers if builder attributes are used to specify non-`Default` default values.
310///
311/// # Input syntax
312///
313/// ```
314/// use derive_builder::Builder;
315/// use serde::{Deserialize, Serialize};
316/// use tor_config::impl_standard_builder;
317/// use tor_config::ConfigBuildError;
318///
319/// #[derive(Debug, Builder, Clone, Eq, PartialEq)]
320/// #[builder(derive(Serialize, Deserialize, Debug))]
321/// #[builder(build_fn(error = "ConfigBuildError"))]
322/// struct SomeConfigStruct { }
323/// impl_standard_builder! { SomeConfigStruct }
324///
325/// #[derive(Debug, Builder, Clone, Eq, PartialEq)]
326/// struct UnusualStruct { }
327/// impl_standard_builder! { UnusualStruct: !Deserialize + !Builder }
328/// ```
329///
330/// # Requirements
331///
332/// `$Config`'s builder must have default values for all the fields,
333/// or this macro-generated self-test will fail.
334/// This should be OK for all principal elements of our configuration.
335///
336/// `$ConfigBuilder` must have an appropriate `Deserialize` impl.
337///
338/// # Options
339///
340/// * `!Default` suppresses the `Default` implementation, and the corresponding tests.
341/// This should be done within Arti's configuration only for sub-structures which
342/// contain mandatory fields (and are themselves optional).
343///
344/// * `!Deserialize` suppresses the test case involving `Builder: Deserialize`.
345/// This should not be done for structs which are part of Arti's configuration,
346/// but can be appropriate for other types that use [`derive_builder`].
347///
348/// * `!Builder` suppresses the impl of the [`tor_config::load::Builder`](load::Builder) trait
349/// This will be necessary if the error from the builder is not [`ConfigBuildError`].
350///
351/// # Generates
352///
353/// * `impl Default for $Config`
354/// * `impl Builder for $ConfigBuilder`
355/// * a self-test that the `Default` impl actually works
356/// * a test that the `Builder` can be deserialized from an empty [`ConfigurationTree`],
357/// and then built, and that the result is the same as the ordinary default.
358//
359// The implementation munches fake "trait bounds" (`: !Deserialize + !Wombat ...`) off the RHS.
360// We're going to add at least one more option.
361//
362// When run with `!Default`, this only generates a `builder` impl and an impl of
363// the `Resolvable` trait which probably won't be used anywhere. That may seem
364// like a poor tradeoff (much fiddly macro code to generate a trivial function in
365// a handful of call sites). However, this means that `impl_standard_builder!`
366// can be used in more places. That sets a good example: always use the macro.
367//
368// That is a good example because we want `impl_standard_builder!` to be
369// used elsewhere because it generates necessary tests of properties
370// which might otherwise be violated. When adding code, people add according to the
371// patterns they see.
372//
373// (We, sadly, don't have a good way to *ensure* use of `impl_standard_builder`.)
374#[macro_export]
375macro_rules! impl_standard_builder {
376 // Convert the input into the "being processed format":
377 {
378 $Config:ty $(: $($options:tt)* )?
379 } => { $crate::impl_standard_builder!{
380 // ^Being processed format:
381 @ ( Builder )
382 ( default )
383 ( extract ) $Config : $( $( $options )* )?
384 // ~~~~~~~~~~~~~~~ ^^^^^^^ ^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
385 // present iff not !Builder, !Default
386 // present iff not !Default
387 // present iff not !Deserialize type always present options yet to be parsed
388 } };
389 // If !Deserialize is the next option, implement it by making $try_deserialize absent
390 {
391 @ ( $($Builder :ident)? )
392 ( $($default :ident)? )
393 ( $($try_deserialize:ident)? ) $Config:ty : $(+)? !Deserialize $( $options:tt )*
394 } => { $crate::impl_standard_builder!{
395 @ ( $($Builder )? )
396 ( $($default )? )
397 ( ) $Config : $( $options )*
398 } };
399 // If !Builder is the next option, implement it by making $Builder absent
400 {
401 @ ( $($Builder :ident)? )
402 ( $($default :ident)? )
403 ( $($try_deserialize:ident)? ) $Config:ty : $(+)? !Builder $( $options:tt )*
404 } => { $crate::impl_standard_builder!{
405 @ ( )
406 ( $($default )? )
407 ( $($try_deserialize )? ) $Config : $( $options )*
408 } };
409 // If !Default is the next option, implement it by making $default absent
410 {
411 @ ( $($Builder :ident)? )
412 ( $($default :ident)? )
413 ( $($try_deserialize:ident)? ) $Config:ty : $(+)? !Default $( $options:tt )*
414 } => { $crate::impl_standard_builder!{
415 @ ( $($Builder )? )
416 ( )
417 ( $($try_deserialize )? ) $Config : $( $options )*
418 } };
419 // Having parsed all options, produce output:
420 {
421 @ ( $($Builder :ident)? )
422 ( $($default :ident)? )
423 ( $($try_deserialize:ident)? ) $Config:ty : $(+)?
424 } => { $crate::deps::paste!{
425 impl $Config {
426 /// Returns a fresh, default, builder
427 pub fn builder() -> [< $Config Builder >] {
428 Default::default()
429 }
430 }
431
432 $( // expands iff there was $default, which is always default
433 impl Default for $Config {
434 fn $default() -> Self {
435 // unwrap is good because one of the test cases above checks that it works!
436 [< $Config Builder >]::default().build().unwrap()
437 }
438 }
439 )?
440
441 $( // expands iff there was $Builder, which is always Builder
442 impl $crate::load::$Builder for [< $Config Builder >] {
443 type Built = $Config;
444 fn build(&self) -> std::result::Result<$Config, $crate::ConfigBuildError> {
445 [< $Config Builder >]::build(self)
446 }
447 }
448 )?
449
450 #[test]
451 #[allow(non_snake_case)]
452 fn [< test_impl_Default_for_ $Config >] () {
453 #[allow(unused_variables)]
454 let def = None::<$Config>;
455 $( // expands iff there was $default, which is always default
456 let def = Some($Config::$default());
457 )?
458
459 if let Some(def) = def {
460 $( // expands iff there was $try_deserialize, which is always extract
461 let empty_config = $crate::deps::figment::Figment::new();
462 let builder: [< $Config Builder >] = empty_config.$try_deserialize().unwrap();
463 let from_empty = builder.build().unwrap();
464 assert_eq!(def, from_empty);
465 )*
466 }
467 }
468 } };
469}
470
471#[cfg(test)]
472mod test {
473 // @@ begin test lint list maintained by maint/add_warning @@
474 #![allow(clippy::bool_assert_comparison)]
475 #![allow(clippy::clone_on_copy)]
476 #![allow(clippy::dbg_macro)]
477 #![allow(clippy::mixed_attributes_style)]
478 #![allow(clippy::print_stderr)]
479 #![allow(clippy::print_stdout)]
480 #![allow(clippy::single_char_pattern)]
481 #![allow(clippy::unwrap_used)]
482 #![allow(clippy::unchecked_time_subtraction)]
483 #![allow(clippy::useless_vec)]
484 #![allow(clippy::needless_pass_by_value)]
485 //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
486 use super::*;
487 use crate::{self as tor_config, sources::MustRead};
488 use derive_builder::Builder;
489 use serde::{Deserialize, Serialize};
490 use serde_json::json;
491 use tracing_test::traced_test;
492
493 #[test]
494 #[traced_test]
495 fn reconfigure_helpers() {
496 let how = Reconfigure::AllOrNothing;
497 let err = how.cannot_change("the_laws_of_physics").unwrap_err();
498 assert_eq!(
499 err.to_string(),
500 "Cannot change the_laws_of_physics on a running client.".to_owned()
501 );
502
503 let how = Reconfigure::WarnOnFailures;
504 let ok = how.cannot_change("stuff");
505 assert!(ok.is_ok());
506 assert!(logs_contain("Cannot change stuff on a running client."));
507 }
508
509 #[test]
510 #[rustfmt::skip] // autoformatting obscures the regular structure
511 fn resolve_option_test() {
512 #[derive(Debug, Clone, Builder, Eq, PartialEq)]
513 #[builder(build_fn(error = "ConfigBuildError"))]
514 #[builder(derive(Debug, Serialize, Deserialize, Eq, PartialEq))]
515 struct TestConfig {
516 #[builder(field(build = r#"tor_config::resolve_option(&self.none, || None)"#))]
517 none: Option<u32>,
518
519 #[builder(field(build = r#"tor_config::resolve_option(&self.four, || Some(4))"#))]
520 four: Option<u32>,
521 }
522
523 // defaults
524 {
525 let builder_from_json: TestConfigBuilder = serde_json::from_value(
526 json!{ { } }
527 ).unwrap();
528
529 let builder_from_methods = TestConfigBuilder::default();
530
531 assert_eq!(builder_from_methods, builder_from_json);
532 assert_eq!(builder_from_methods.build().unwrap(),
533 TestConfig { none: None, four: Some(4) });
534 }
535
536 // explicit positive values
537 {
538 let builder_from_json: TestConfigBuilder = serde_json::from_value(
539 json!{ { "none": 123, "four": 456 } }
540 ).unwrap();
541
542 let mut builder_from_methods = TestConfigBuilder::default();
543 builder_from_methods.none(Some(123));
544 builder_from_methods.four(Some(456));
545
546 assert_eq!(builder_from_methods, builder_from_json);
547 assert_eq!(builder_from_methods.build().unwrap(),
548 TestConfig { none: Some(123), four: Some(456) });
549 }
550
551 // explicit "null" values
552 {
553 let builder_from_json: TestConfigBuilder = serde_json::from_value(
554 json!{ { "none": 0, "four": 0 } }
555 ).unwrap();
556
557 let mut builder_from_methods = TestConfigBuilder::default();
558 builder_from_methods.none(Some(0));
559 builder_from_methods.four(Some(0));
560
561 assert_eq!(builder_from_methods, builder_from_json);
562 assert_eq!(builder_from_methods.build().unwrap(),
563 TestConfig { none: None, four: None });
564 }
565
566 // explicit None (API only, serde can't do this for Option)
567 {
568 let mut builder_from_methods = TestConfigBuilder::default();
569 builder_from_methods.none(None);
570 builder_from_methods.four(None);
571
572 assert_eq!(builder_from_methods.build().unwrap(),
573 TestConfig { none: None, four: None });
574 }
575 }
576
577 #[test]
578 fn get_value() {
579 use serde_value::Value as V;
580 let to_value = |json_str: &str| {
581 serde_value::to_value(serde_json::from_str::<serde_json::Value>(json_str).unwrap())
582 .unwrap()
583 };
584 let mut sources = ConfigurationSources::new_empty();
585
586 let source = "
587 [foo]
588 bar.baz = 7
589 quux = [[],[],{}]
590 ";
591 let source = ConfigurationSource::from_verbatim(source.to_string());
592 sources.push_source(source, MustRead::MustRead);
593
594 let tree = sources.load().unwrap();
595
596 {
597 let v1 = tree.get_serde_value::<V>("foo.quux").unwrap().unwrap();
598 let v2 = to_value(r#"[[], [], {}]"#);
599 assert_eq!(v1, v2);
600 }
601
602 assert!(tree.get_serde_value::<V>("nonexist").unwrap().is_none());
603 assert!(tree.get_serde_value::<V>("foo.nonexist").unwrap().is_none());
604 assert!(
605 tree.get_serde_value::<V>("foo.quux.nonexist")
606 .unwrap()
607 .is_none()
608 );
609 }
610}