Skip to main content

plexus_core/plexus/config/
settings.rs

1//! NEST-21 · plexus-core's own settings: the transport, a mount's options,
2//! the log's redactor. plexus-dyn declares its own beside them
3//! (`dyn.repin_on_valid_cert`, `dyn.containment.*`, `dyn.require_consent`).
4
5use super::{Config, Millis, Setting};
6
7/// Plain `ws://` to a host beyond loopback (DYNAUTH-8's override, a test
8/// network's). Read at every dial and mount. Critical: whoever flips it
9/// lets a hop cross a network in clear.
10pub const TRANSPORT_INSECURE_WS: Setting<bool> = crate::setting!(
11    "transport.insecure_ws",
12    default = false,
13    reload = Live,
14    sensitivity = Public,
15    scope = Service,
16    critical = true,
17    doc = "plain ws:// to a peer beyond loopback (a test network's); read at every dial"
18);
19
20/// A PEM file of certificate authorities a `wss://` peer may chain to,
21/// beside the webpki roots ([`ChildOptions::tls_roots`]). Not settable over
22/// the wire: a CA added remotely could stand in for every peer.
23///
24/// [`ChildOptions::tls_roots`]: crate::plexus::ChildOptions::tls_roots
25pub const TRANSPORT_TLS_ROOTS: Setting<Option<String>> = crate::setting!(
26    "transport.tls_roots",
27    default = None,
28    reload = Live,
29    remote = false,
30    doc = "a PEM file of extra CAs a wss:// peer may chain to; read at every dial; the host's alone"
31);
32
33/// NEST-16's one-release escape: a child declaring no `needs` may call up
34/// anything its caller could. Read at each mount. Critical: it widens what
35/// every such child may call.
36pub const CHILD_LEGACY_UPCALLS: Setting<bool> = crate::setting!(
37    "child.legacy_upcalls",
38    default = false,
39    critical = true,
40    doc = "a child declaring no needs calls up anything its caller could (NEST-11's rule); read at each mount"
41);
42
43/// A child's answer to `_info`, its schema, and each call's open.
44pub const CHILD_TIMEOUT: Setting<Millis> = crate::setting!("child.timeout", default = Millis::secs(5), doc = "a child's answer to _info and each call's open; read at each mount");
45
46/// Calls open on one child at once.
47pub const CHILD_MAX_CALLS: Setting<usize> = crate::setting!("child.max_calls", default = 1024, doc = "calls open on one child at once; read at each mount");
48
49/// Restarting (redialing) a child that died.
50pub const CHILD_BACKOFF: Setting<Backoff> = crate::setting!("child.backoff", default = Backoff::DEFAULT, doc = "restarting a child that died: initial, max, per_minute; read at each mount");
51
52/// Keys the log redacts beside the fixed credential keys (DYNAUTH-8's
53/// redactor): process-wide, live.
54pub const LOG_REDACT_KEYS: Setting<Vec<String>> = crate::setting!(
55    "log.redact.keys",
56    default = Vec::new(),
57    scope = Process,
58    doc = "keys whose values the log redacts, beside the fixed credential keys"
59);
60
61/// [`crate::plexus::Backoff`] as a setting holds it.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
63pub struct Backoff {
64    pub initial: Millis,
65    pub max: Millis,
66    pub per_minute: usize,
67}
68
69impl Backoff {
70    /// 0.5 s → 30 s, at most 5 restarts a minute.
71    pub const DEFAULT: Backoff = Backoff { initial: Millis::ms(500), max: Millis::secs(30), per_minute: 5 };
72}
73
74/// Declare plexus-core's settings in `c`, and keep the redactor's keys on
75/// `log.redact.keys`.
76pub(crate) fn declare_core(c: &Config) {
77    c.declare(&TRANSPORT_INSECURE_WS);
78    c.declare(&TRANSPORT_TLS_ROOTS);
79    c.declare(&CHILD_LEGACY_UPCALLS);
80    c.declare(&CHILD_TIMEOUT);
81    c.declare(&CHILD_MAX_CALLS);
82    c.declare(&CHILD_BACKOFF);
83    c.declare(&LOG_REDACT_KEYS);
84    // The first declaration of a process does not clear what another
85    // service's store set: only a change does.
86    let first = std::sync::atomic::AtomicBool::new(true);
87    c.on_change(&LOG_REDACT_KEYS, move |keys| {
88        if first.swap(false, std::sync::atomic::Ordering::SeqCst) && keys.is_empty() {
89            return;
90        }
91        crate::plexus::redact::set_extra_keys(&keys);
92    });
93}
94
95#[cfg(not(target_arch = "wasm32"))]
96impl crate::plexus::ChildOptions {
97    /// NEST-21: these options with every `child.*`, `transport.tls_roots`
98    /// and (KEEL-7) `transport.insecure_ws` setting `c` holds above its default (a flag, the file, a runtime
99    /// set) put over them. Read at each mount, so a change applies to the
100    /// next one.
101    pub fn configured(mut self, c: &Config) -> Self {
102        use super::Source;
103        if c.source(&CHILD_TIMEOUT) != Source::Default {
104            self.timeout = c.get(&CHILD_TIMEOUT).0;
105        }
106        if c.source(&CHILD_MAX_CALLS) != Source::Default {
107            self.max_calls = c.get(&CHILD_MAX_CALLS);
108        }
109        if c.source(&CHILD_BACKOFF) != Source::Default {
110            let b = c.get(&CHILD_BACKOFF);
111            self.backoff = crate::plexus::Backoff { initial: b.initial.0, max: b.max.0, per_minute: b.per_minute };
112        }
113        if c.source(&CHILD_LEGACY_UPCALLS) != Source::Default {
114            self.legacy_upcalls = c.get(&CHILD_LEGACY_UPCALLS);
115        }
116        if c.source(&TRANSPORT_TLS_ROOTS) != Source::Default {
117            self.tls_roots = c.get(&TRANSPORT_TLS_ROOTS).map(Into::into);
118        }
119        // KEEL-7: the override every dial reads, not plexus-dyn's alone.
120        if c.source(&TRANSPORT_INSECURE_WS) != Source::Default {
121            self.insecure_ws = c.get(&TRANSPORT_INSECURE_WS);
122        }
123        self
124    }
125
126    /// NEST-21: put what these options say above the defaults into `c` as
127    /// the flag layer (what a host read from its flags at start), so
128    /// `config.list` shows it and a runtime set goes over it.
129    pub fn seed(&self, c: &Config) {
130        use super::Source;
131        let d = Self::default();
132        if self.timeout != d.timeout {
133            c.seed(&CHILD_TIMEOUT, Source::Flag, Some(Millis(self.timeout)));
134        }
135        if self.max_calls != d.max_calls {
136            c.seed(&CHILD_MAX_CALLS, Source::Flag, Some(self.max_calls));
137        }
138        if (self.backoff.initial, self.backoff.max, self.backoff.per_minute) != (d.backoff.initial, d.backoff.max, d.backoff.per_minute) {
139            c.seed(&CHILD_BACKOFF, Source::Flag, Some(Backoff { initial: Millis(self.backoff.initial), max: Millis(self.backoff.max), per_minute: self.backoff.per_minute }));
140        }
141        if self.legacy_upcalls != d.legacy_upcalls {
142            c.seed(&CHILD_LEGACY_UPCALLS, Source::Flag, Some(self.legacy_upcalls));
143        }
144        if let Some(r) = &self.tls_roots {
145            c.seed(&TRANSPORT_TLS_ROOTS, Source::Flag, Some(Some(r.display().to_string())));
146        }
147        if self.insecure_ws != d.insecure_ws {
148            c.seed(&TRANSPORT_INSECURE_WS, Source::Flag, Some(self.insecure_ws));
149        }
150    }
151}