Skip to main content

tor_guardmgr/
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#![allow(clippy::cognitive_complexity)] // See arti#2556
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#![warn(clippy::or_fun_call)]
28#![deny(clippy::print_stderr)]
29#![deny(clippy::print_stdout)]
30#![warn(clippy::rc_buffer)]
31#![deny(clippy::ref_option_ref)]
32#![warn(clippy::semicolon_if_nothing_returned)]
33#![warn(clippy::trait_duplication_in_bounds)]
34#![deny(clippy::unchecked_time_subtraction)]
35#![deny(clippy::unnecessary_wraps)]
36#![warn(clippy::unseparated_literal_suffix)]
37#![deny(clippy::unwrap_used)]
38#![deny(clippy::mod_module_files)]
39#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
40#![allow(clippy::uninlined_format_args)]
41#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
42#![allow(clippy::result_large_err)] // temporary workaround for arti#587
43#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
44#![allow(clippy::needless_lifetimes)] // See arti#1765
45#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060
46#![allow(clippy::collapsible_if)] // See arti#2342
47#![deny(clippy::unused_async)]
48#![deny(clippy::string_slice)] // See arti#2571
49#![allow(recursion_depth_exceeding_limit)] // arti#2715, rust/issues/159228
50//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
51
52// TODO #1645 (either remove this, or decide to have it everywhere)
53#![cfg_attr(not(all(feature = "full", feature = "experimental")), allow(unused))]
54
55// Glossary:
56//     Primary guard
57//     Sample
58//     confirmed
59//     filtered
60
61use derive_deftly::Deftly;
62use futures::channel::mpsc;
63use itertools::Either;
64use serde::{Deserialize, Serialize};
65use std::collections::HashMap;
66use std::net::SocketAddr;
67use std::sync::{Arc, Mutex, Weak};
68#[cfg(feature = "bridge-client")]
69use tor_error::internal;
70use tor_linkspec::{OwnedChanTarget, OwnedCircTarget, RelayId, RelayIdSet};
71use tor_netdir::NetDirProvider;
72use tor_proto::ClockSkew;
73use tor_rtcompat::SpawnExt;
74use tor_units::BoundedInt32;
75use tracing::{debug, info, instrument, trace, warn};
76use web_time_compat::{Duration, Instant, SystemTime};
77
78use tor_config::derive::prelude::*;
79use tor_config::{ExplicitOrAuto, impl_standard_builder};
80use tor_config::{ReconfigureError, impl_not_auto_value};
81use tor_config::{define_list_builder_accessors, define_list_builder_helper};
82use tor_netdir::{NetDir, Relay, params::NetParameters};
83use tor_persist::{DynStorageHandle, StateMgr};
84use tor_rtcompat::Runtime;
85
86#[cfg(feature = "bridge-client")]
87pub mod bridge;
88mod config;
89mod daemon;
90mod dirstatus;
91mod err;
92mod events;
93pub mod fallback;
94mod filter;
95mod guard;
96mod ids;
97mod pending;
98mod sample;
99mod skew;
100mod util;
101#[cfg(feature = "vanguards")]
102pub mod vanguards;
103
104#[cfg(not(feature = "bridge-client"))]
105#[path = "bridge_disabled.rs"]
106pub mod bridge;
107
108#[cfg(any(test, feature = "testing"))]
109pub use config::testing::TestConfig;
110
111#[cfg(test)]
112use oneshot_fused_workaround as oneshot;
113
114pub use config::GuardMgrConfig;
115pub use err::{GuardMgrConfigError, GuardMgrError, PickGuardError};
116pub use events::ClockSkewEvents;
117pub use filter::GuardFilter;
118pub use ids::FirstHopId;
119pub use pending::{GuardMonitor, GuardStatus, GuardUsable};
120pub use skew::SkewEstimate;
121
122#[cfg(feature = "vanguards")]
123pub use vanguards::VanguardMgrError;
124
125use pending::{PendingRequest, RequestId};
126use sample::{GuardSet, Universe, UniverseRef};
127
128use crate::ids::{FirstHopIdInner, GuardId};
129
130/// A "guard manager" that selects and remembers a persistent set of
131/// guard nodes.
132///
133/// This is a "handle"; clones of it share state.
134#[derive(Clone)]
135pub struct GuardMgr<R: Runtime> {
136    /// An asynchronous runtime object.
137    ///
138    /// GuardMgr uses this runtime for timing, timeouts, and spawning
139    /// tasks.
140    runtime: R,
141
142    /// Internal state for the guard manager.
143    inner: Arc<Mutex<GuardMgrInner>>,
144}
145
146/// Helper type that holds the data used by a [`GuardMgr`].
147///
148/// This would just be a [`GuardMgr`], except that it needs to sit inside
149/// a `Mutex` and get accessed by daemon tasks.
150struct GuardMgrInner {
151    /// Last time when marked all of our primary guards as retriable.
152    ///
153    /// We keep track of this time so that we can rate-limit
154    /// these attempts.
155    last_primary_retry_time: Instant,
156
157    /// Persistent guard manager state.
158    ///
159    /// This object remembers one or more persistent set of guards that we can
160    /// use, along with their relative priorities and statuses.
161    guards: GuardSets,
162
163    /// The current filter that we're using to decide which guards are
164    /// supported.
165    //
166    // TODO: This field is duplicated in the current active [`GuardSet`]; we
167    // should fix that.
168    filter: GuardFilter,
169
170    /// Configuration values derived from the consensus parameters.
171    ///
172    /// This is updated whenever the consensus parameters change.
173    params: GuardParams,
174
175    /// A mpsc channel, used to tell the task running in
176    /// [`daemon::report_status_events`] about a new event to monitor.
177    ///
178    /// This uses an `UnboundedSender` so that we don't have to await
179    /// while sending the message, which in turn allows the GuardMgr
180    /// API to be simpler.  The risk, however, is that there's no
181    /// backpressure in the event that the task running
182    /// [`daemon::report_status_events`] fails to read from this
183    /// channel.
184    ctrl: mpsc::UnboundedSender<daemon::Msg>,
185
186    /// Information about guards that we've given out, but where we have
187    /// not yet heard whether the guard was successful.
188    ///
189    /// Upon leaning whether the guard was successful, the pending
190    /// requests in this map may be either moved to `waiting`, or
191    /// discarded.
192    ///
193    /// There can be multiple pending requests corresponding to the
194    /// same guard.
195    pending: HashMap<RequestId, PendingRequest>,
196
197    /// A list of pending requests for which we have heard that the
198    /// guard was successful, but we have not yet decided whether the
199    /// circuit may be used.
200    ///
201    /// There can be multiple waiting requests corresponding to the
202    /// same guard.
203    waiting: Vec<PendingRequest>,
204
205    /// A list of fallback directories used to access the directory system
206    /// when no other directory information is yet known.
207    fallbacks: fallback::FallbackState,
208
209    /// Location in which to store persistent state.
210    storage: DynStorageHandle<GuardSets>,
211
212    /// A sender object to publish changes in our estimated clock skew.
213    send_skew: postage::watch::Sender<Option<SkewEstimate>>,
214
215    /// A receiver object to hand out to observers who want to know about
216    /// changes in our estimated clock skew.
217    recv_skew: events::ClockSkewEvents,
218
219    /// A netdir provider that we can use for adding new guards when
220    /// insufficient guards are available.
221    ///
222    /// This has to be an Option so it can be initialized from None: at the
223    /// time a GuardMgr is created, there is no NetDirProvider for it to use.
224    netdir_provider: Option<Weak<dyn NetDirProvider>>,
225
226    /// A netdir provider that we can use for discovering bridge descriptors.
227    ///
228    /// This has to be an Option so it can be initialized from None: at the time
229    /// a GuardMgr is created, there is no BridgeDescProvider for it to use.
230    #[cfg(feature = "bridge-client")]
231    bridge_desc_provider: Option<Weak<dyn bridge::BridgeDescProvider>>,
232
233    /// A list of the bridges that we are configured to use, or "None" if we are
234    /// not configured to use bridges.
235    #[cfg(feature = "bridge-client")]
236    configured_bridges: Option<Arc<[bridge::BridgeConfig]>>,
237}
238
239/// A selector that tells us which [`GuardSet`] of several is currently in use.
240#[derive(Clone, Debug, Default, Eq, PartialEq, Ord, PartialOrd, strum::EnumIter)]
241enum GuardSetSelector {
242    /// The default guard set is currently in use: that's the one that we use
243    /// when we have no filter installed, or the filter permits most of the
244    /// guards on the network.
245    #[default]
246    Default,
247    /// A "restrictive" guard set is currently in use: that's the one that we
248    /// use when we have a filter that excludes a large fraction of the guards
249    /// on the network.
250    Restricted,
251    /// The "bridges" guard set is currently in use: we are selecting our guards
252    /// from among the universe of configured bridges.
253    #[cfg(feature = "bridge-client")]
254    Bridges,
255}
256
257/// Describes the [`Universe`] that a guard sample should take its guards from.
258#[derive(Clone, Copy, Debug, Eq, PartialEq)]
259enum UniverseType {
260    /// Take information from the network directory.
261    NetDir,
262    /// Take information from the configured bridges.
263    #[cfg(feature = "bridge-client")]
264    BridgeSet,
265}
266
267impl GuardSetSelector {
268    /// Return a description of which [`Universe`] this guard sample should take
269    /// its guards from.
270    fn universe_type(&self) -> UniverseType {
271        match self {
272            GuardSetSelector::Default | GuardSetSelector::Restricted => UniverseType::NetDir,
273            #[cfg(feature = "bridge-client")]
274            GuardSetSelector::Bridges => UniverseType::BridgeSet,
275        }
276    }
277}
278
279/// Persistent state for a guard manager, as serialized to disk.
280#[derive(Debug, Clone, Default, Serialize, Deserialize)]
281struct GuardSets {
282    /// Which set of guards is currently in use?
283    #[serde(skip)]
284    active_set: GuardSetSelector,
285
286    /// The default set of guards to use.
287    ///
288    /// We use this one when there is no filter, or the filter permits most of the
289    /// guards on the network.
290    default: GuardSet,
291
292    /// A guard set to use when we have a restrictive filter.
293    #[serde(default)]
294    restricted: GuardSet,
295
296    /// A guard set sampled from our configured bridges.
297    #[serde(default)]
298    #[cfg(feature = "bridge-client")]
299    bridges: GuardSet,
300
301    /// Unrecognized fields, including (possibly) other guard sets.
302    #[serde(flatten)]
303    remaining: HashMap<String, tor_persist::JsonValue>,
304}
305
306/// The key (filename) we use for storing our persistent guard state in the
307/// `StateMgr`.
308///
309/// We used to store this in a different format in a filename called
310/// "default_guards" (before Arti 0.1.0).
311const STORAGE_KEY: &str = "guards";
312
313/// A description of which circuits to retire because of a configuration change.
314///
315/// TODO(nickm): Eventually we will want to add a "Some" here, to support
316/// removing only those circuits that correspond to no-longer-usable guards.
317#[derive(Clone, Debug, Eq, PartialEq)]
318#[must_use]
319#[non_exhaustive]
320pub enum RetireCircuits {
321    /// There's no need to retire any circuits.
322    None,
323    /// All circuits should be retired.
324    All,
325}
326
327impl<R: Runtime> GuardMgr<R> {
328    /// Create a new "empty" guard manager and launch its background tasks.
329    ///
330    /// It won't be able to hand out any guards until a [`NetDirProvider`] has
331    /// been installed.
332    #[instrument(skip_all, level = "trace")]
333    pub fn new<S>(
334        runtime: R,
335        state_mgr: S,
336        config: &impl GuardMgrConfig,
337    ) -> Result<Self, GuardMgrError>
338    where
339        S: StateMgr + Send + Sync + 'static,
340    {
341        let (ctrl, rcv) = mpsc::unbounded();
342        let storage: DynStorageHandle<GuardSets> = state_mgr.create_handle(STORAGE_KEY);
343        // TODO(nickm): We should do something about the old state in
344        // `default_guards`.  Probably it would be best to delete it.  We could
345        // try to migrate it instead, but that's beyond the stability guarantee
346        // that we're getting at this stage of our (pre-0.1) development.
347        let state = storage.load()?.unwrap_or_default();
348
349        let (send_skew, recv_skew) = postage::watch::channel();
350        let recv_skew = ClockSkewEvents { inner: recv_skew };
351
352        let inner = Arc::new(Mutex::new(GuardMgrInner {
353            guards: state,
354            filter: GuardFilter::unfiltered(),
355            last_primary_retry_time: runtime.now(),
356            params: GuardParams::default(),
357            ctrl,
358            pending: HashMap::new(),
359            waiting: Vec::new(),
360            fallbacks: config.fallbacks().into(),
361            storage,
362            send_skew,
363            recv_skew,
364            netdir_provider: None,
365            #[cfg(feature = "bridge-client")]
366            bridge_desc_provider: None,
367            #[cfg(feature = "bridge-client")]
368            configured_bridges: None,
369        }));
370        #[cfg(feature = "bridge-client")]
371        {
372            let mut inner = inner.lock().expect("lock poisoned");
373            // TODO(nickm): This calls `GuardMgrInner::update`. Will we mind doing so before any
374            // providers are configured? I think not, but we should make sure.
375            let _: RetireCircuits =
376                inner.replace_bridge_config(config, runtime.wallclock(), runtime.now())?;
377        }
378        {
379            let weak_inner = Arc::downgrade(&inner);
380            let rt_clone = runtime.clone();
381            runtime
382                .spawn(daemon::report_status_events(rt_clone, weak_inner, rcv))
383                .map_err(|e| GuardMgrError::from_spawn("guard status event reporter", e))?;
384        }
385        {
386            let rt_clone = runtime.clone();
387            let weak_inner = Arc::downgrade(&inner);
388            runtime
389                .spawn(daemon::run_periodic(rt_clone, weak_inner))
390                .map_err(|e| GuardMgrError::from_spawn("periodic guard updater", e))?;
391        }
392        Ok(GuardMgr { runtime, inner })
393    }
394
395    /// Install a [`NetDirProvider`] for use by this guard manager.
396    ///
397    /// It will be used to keep the guards up-to-date with changes from the
398    /// network directory, and to find new guards when no NetDir is provided to
399    /// select_guard().
400    ///
401    /// TODO: we should eventually return some kind of a task handle from this
402    /// task, even though it is not strictly speaking periodic.
403    ///
404    /// The guardmgr retains only a `Weak` reference to `provider`,
405    /// `install_netdir_provider` downgrades it on entry,
406    // TODO add ref to document when https://gitlab.torproject.org/tpo/core/arti/-/issues/624
407    // is fixed.  Also, maybe take an owned `Weak` to start with.
408    //
409    /// # Panics
410    ///
411    /// Panics if a [`NetDirProvider`] is already installed.
412    pub fn install_netdir_provider(
413        &self,
414        provider: &Arc<dyn NetDirProvider>,
415    ) -> Result<(), GuardMgrError> {
416        let weak_provider = Arc::downgrade(provider);
417        {
418            let mut inner = self.inner.lock().expect("Poisoned lock");
419            assert!(inner.netdir_provider.is_none());
420            inner.netdir_provider = Some(weak_provider.clone());
421        }
422        let weak_inner = Arc::downgrade(&self.inner);
423        let rt_clone = self.runtime.clone();
424        self.runtime
425            .spawn(daemon::keep_netdir_updated(
426                rt_clone,
427                weak_inner,
428                weak_provider,
429            ))
430            .map_err(|e| GuardMgrError::from_spawn("periodic guard netdir updater", e))?;
431        Ok(())
432    }
433
434    /// Configure a new [`bridge::BridgeDescProvider`] for this [`GuardMgr`].
435    ///
436    /// It will be used to learn about changes in the set of available bridge
437    /// descriptors; we'll inform it whenever our desired set of bridge
438    /// descriptors changes.
439    ///
440    /// TODO: Same todo as in `install_netdir_provider` about task handles.
441    ///
442    /// # Panics
443    ///
444    /// Panics if a [`bridge::BridgeDescProvider`] is already installed.
445    #[cfg(feature = "bridge-client")]
446    pub fn install_bridge_desc_provider(
447        &self,
448        provider: &Arc<dyn bridge::BridgeDescProvider>,
449    ) -> Result<(), GuardMgrError> {
450        let weak_provider = Arc::downgrade(provider);
451        {
452            let mut inner = self.inner.lock().expect("Poisoned lock");
453            assert!(inner.bridge_desc_provider.is_none());
454            inner.bridge_desc_provider = Some(weak_provider.clone());
455        }
456
457        let weak_inner = Arc::downgrade(&self.inner);
458        let rt_clone = self.runtime.clone();
459        self.runtime
460            .spawn(daemon::keep_bridge_descs_updated(
461                rt_clone,
462                weak_inner,
463                weak_provider,
464            ))
465            .map_err(|e| GuardMgrError::from_spawn("periodic guard netdir updater", e))?;
466
467        Ok(())
468    }
469
470    /// Flush our current guard state to the state manager, if there
471    /// is any unsaved state.
472    pub fn store_persistent_state(&self) -> Result<(), GuardMgrError> {
473        let inner = self.inner.lock().expect("Poisoned lock");
474        trace!("Flushing guard state to disk.");
475        inner.storage.store(&inner.guards)?;
476        Ok(())
477    }
478
479    /// Reload state from the state manager.
480    ///
481    /// We only call this method if we _don't_ have the lock on the state
482    /// files.  If we have the lock, we only want to save.
483    #[instrument(level = "trace", skip_all)]
484    pub fn reload_persistent_state(&self) -> Result<(), GuardMgrError> {
485        let mut inner = self.inner.lock().expect("Poisoned lock");
486        if let Some(new_guards) = inner.storage.load()? {
487            inner.replace_guards_with(new_guards, self.runtime.wallclock(), self.runtime.now());
488        }
489        Ok(())
490    }
491
492    /// Switch from having an unowned persistent state to having an owned one.
493    ///
494    /// Requires that we hold the lock on the state files.
495    #[instrument(level = "trace", skip_all)]
496    pub fn upgrade_to_owned_persistent_state(&self) -> Result<(), GuardMgrError> {
497        let mut inner = self.inner.lock().expect("Poisoned lock");
498        debug_assert!(inner.storage.can_store());
499        let new_guards = inner.storage.load()?.unwrap_or_default();
500        let wallclock = self.runtime.wallclock();
501        let now = self.runtime.now();
502        inner.replace_guards_with(new_guards, wallclock, now);
503        Ok(())
504    }
505
506    /// Return true if `netdir` has enough information to safely become our new netdir.
507    pub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool {
508        let mut inner = self.inner.lock().expect("Poisoned lock");
509        if inner.guards.active_set.universe_type() != UniverseType::NetDir {
510            // If we aren't using the netdir, this isn't something we want to look at.
511            return true;
512        }
513        inner
514            .guards
515            .active_guards_mut()
516            .n_primary_without_id_info_in(netdir)
517            == 0
518    }
519
520    /// Mark every guard as potentially retriable, regardless of how recently we
521    /// failed to connect to it.
522    pub fn mark_all_guards_retriable(&self) {
523        let mut inner = self.inner.lock().expect("Poisoned lock");
524        inner.guards.active_guards_mut().mark_all_guards_retriable();
525    }
526
527    /// Configure this guardmgr to use a fixed [`NetDir`] instead of a provider.
528    ///
529    /// This function is for testing only, and is exclusive with
530    /// `install_netdir_provider`.
531    ///
532    /// # Panics
533    ///
534    /// Panics if any [`NetDirProvider`] has already been installed.
535    #[cfg(any(test, feature = "testing"))]
536    pub fn install_test_netdir(&self, netdir: &NetDir) {
537        use tor_netdir::testprovider::TestNetDirProvider;
538        let wallclock = self.runtime.wallclock();
539        let now = self.runtime.now();
540        let netdir_provider: Arc<dyn NetDirProvider> =
541            Arc::new(TestNetDirProvider::from(netdir.clone()));
542        self.install_netdir_provider(&netdir_provider)
543            .expect("Couldn't install testing network provider");
544
545        let mut inner = self.inner.lock().expect("Poisoned lock");
546        inner.update(wallclock, now);
547    }
548
549    /// Replace the configuration in this `GuardMgr` with `config`.
550    #[instrument(level = "trace", skip_all)]
551    pub fn reconfigure(
552        &self,
553        config: &impl GuardMgrConfig,
554    ) -> Result<RetireCircuits, ReconfigureError> {
555        let mut inner = self.inner.lock().expect("Poisoned lock");
556        // Change the set of configured fallbacks.
557        {
558            let mut fallbacks: fallback::FallbackState = config.fallbacks().into();
559            std::mem::swap(&mut inner.fallbacks, &mut fallbacks);
560            inner.fallbacks.take_status_from(fallbacks);
561        }
562        // If we are built to use bridges, change the bridge configuration.
563        #[cfg(feature = "bridge-client")]
564        {
565            let wallclock = self.runtime.wallclock();
566            let now = self.runtime.now();
567            Ok(inner.replace_bridge_config(config, wallclock, now)?)
568        }
569        // If we are built to use bridges, change the bridge configuration.
570        #[cfg(not(feature = "bridge-client"))]
571        {
572            Ok(RetireCircuits::None)
573        }
574    }
575
576    /// Replace the current [`GuardFilter`] used by this `GuardMgr`.
577    // TODO should this be part of the config?
578    pub fn set_filter(&self, filter: GuardFilter) {
579        let wallclock = self.runtime.wallclock();
580        let now = self.runtime.now();
581        let mut inner = self.inner.lock().expect("Poisoned lock");
582        inner.set_filter(filter, wallclock, now);
583    }
584
585    /// Select a guard for a given [`GuardUsage`].
586    ///
587    /// On success, we return a [`FirstHop`] object to identify which
588    /// guard we have picked, a [`GuardMonitor`] object that the
589    /// caller can use to report whether its attempt to use the guard
590    /// succeeded or failed, and a [`GuardUsable`] future that the
591    /// caller can use to decide whether a circuit built through the
592    /// guard is actually safe to use.
593    ///
594    /// That last point is important: It's okay to build a circuit
595    /// through the guard returned by this function, but you can't
596    /// actually use it for traffic unless the [`GuardUsable`] future
597    /// yields "true".
598    #[instrument(skip_all, level = "trace")]
599    pub fn select_guard(
600        &self,
601        usage: GuardUsage,
602    ) -> Result<(FirstHop, GuardMonitor, GuardUsable), PickGuardError> {
603        let now = self.runtime.now();
604        let wallclock = self.runtime.wallclock();
605
606        let mut inner = self.inner.lock().expect("Poisoned lock");
607
608        // (I am not 100% sure that we need to consider_all_retries here, but
609        // it should _probably_ not hurt.)
610        inner.guards.active_guards_mut().consider_all_retries(now);
611
612        let (origin, guard) = inner.select_guard_with_expand(&usage, now, wallclock)?;
613        trace!(?guard, ?usage, "Guard selected");
614
615        let (usable, usable_sender) = if origin.usable_immediately() {
616            (GuardUsable::new_usable_immediately(), None)
617        } else {
618            let (u, snd) = GuardUsable::new_uncertain();
619            (u, Some(snd))
620        };
621        let request_id = pending::RequestId::next();
622        let ctrl = inner.ctrl.clone();
623        let monitor = GuardMonitor::new(request_id, ctrl);
624
625        // Note that the network can be down even if all the primary guards
626        // are not yet marked as unreachable.  But according to guard-spec we
627        // don't want to acknowledge the net as down before that point, since
628        // we don't mark all the primary guards as retriable unless
629        // we've been forced to non-primary guards.
630        let net_has_been_down =
631            if let Some(duration) = tor_proto::time_since_last_incoming_traffic() {
632                inner
633                    .guards
634                    .active_guards_mut()
635                    .all_primary_guards_are_unreachable()
636                    && duration >= inner.params.internet_down_timeout
637            } else {
638                // TODO: Is this the correct behavior in this case?
639                false
640            };
641
642        let pending_request = pending::PendingRequest::new(
643            guard.first_hop_id(),
644            usage,
645            usable_sender,
646            net_has_been_down,
647        );
648        inner.pending.insert(request_id, pending_request);
649
650        match &guard.sample {
651            Some(sample) => {
652                let guard_id = GuardId::from_relay_ids(&guard);
653                inner
654                    .guards
655                    .guards_mut(sample)
656                    .record_attempt(&guard_id, now);
657            }
658            None => {
659                // We don't record attempts for fallbacks; we only care when
660                // they have failed.
661            }
662        }
663
664        Ok((guard, monitor, usable))
665    }
666
667    /// Record that _after_ we built a circuit with a guard, something described
668    /// in `external_failure` went wrong with it.
669    pub fn note_external_failure<T>(&self, identity: &T, external_failure: ExternalActivity)
670    where
671        T: tor_linkspec::HasRelayIds + ?Sized,
672    {
673        let now = self.runtime.now();
674        let mut inner = self.inner.lock().expect("Poisoned lock");
675        let ids = inner.lookup_ids(identity);
676        for id in ids {
677            match &id.0 {
678                FirstHopIdInner::Guard(sample, id) => {
679                    inner
680                        .guards
681                        .guards_mut(sample)
682                        .record_failure(id, Some(external_failure), now);
683                }
684                FirstHopIdInner::Fallback(id) => {
685                    if external_failure == ExternalActivity::DirCache {
686                        inner.fallbacks.note_failure(id, now);
687                    }
688                }
689            }
690        }
691    }
692
693    /// Record that _after_ we built a circuit with a guard, some activity
694    /// described in `external_activity` was successful with it.
695    pub fn note_external_success<T>(&self, identity: &T, external_activity: ExternalActivity)
696    where
697        T: tor_linkspec::HasRelayIds + ?Sized,
698    {
699        let mut inner = self.inner.lock().expect("Poisoned lock");
700
701        inner.record_external_success(identity, external_activity, self.runtime.wallclock());
702    }
703
704    /// Return a stream of events about our estimated clock skew; these events
705    /// are `None` when we don't have enough information to make an estimate,
706    /// and `Some(`[`SkewEstimate`]`)` otherwise.
707    ///
708    /// Note that this stream can be lossy: if the estimate changes more than
709    /// one before you read from the stream, you might only get the most recent
710    /// update.
711    pub fn skew_events(&self) -> ClockSkewEvents {
712        let inner = self.inner.lock().expect("Poisoned lock");
713        inner.recv_skew.clone()
714    }
715
716    /// Ensure that the message queue is flushed before proceeding to
717    /// the next step.  Used for testing.
718    #[cfg(test)]
719    async fn flush_msg_queue(&self) {
720        let (snd, rcv) = oneshot::channel();
721        let pingmsg = daemon::Msg::Ping(snd);
722        {
723            let inner = self.inner.lock().expect("Poisoned lock");
724            inner
725                .ctrl
726                .unbounded_send(pingmsg)
727                .expect("Guard observer task exited prematurely.");
728        }
729        let _ = rcv.await;
730    }
731}
732
733/// An activity that can succeed or fail, and whose success or failure can be
734/// attributed to a guard.
735#[derive(Copy, Clone, Debug, Eq, PartialEq)]
736#[non_exhaustive]
737pub enum ExternalActivity {
738    /// The activity of using the guard as a directory cache.
739    DirCache,
740}
741
742impl GuardSets {
743    /// Return a reference to the currently active set of guards.
744    ///
745    /// (That's easy enough for now, since there is never more than one set of
746    /// guards.  But eventually that will change, as we add support for more
747    /// complex filter types, and for bridge relays. Those will use separate
748    /// `GuardSet` instances, and this accessor will choose the right one.)
749    fn active_guards(&self) -> &GuardSet {
750        self.guards(&self.active_set)
751    }
752
753    /// Return the set of guards corresponding to the provided selector.
754    fn guards(&self, selector: &GuardSetSelector) -> &GuardSet {
755        match selector {
756            GuardSetSelector::Default => &self.default,
757            GuardSetSelector::Restricted => &self.restricted,
758            #[cfg(feature = "bridge-client")]
759            GuardSetSelector::Bridges => &self.bridges,
760        }
761    }
762
763    /// Return a mutable reference to the currently active set of guards.
764    fn active_guards_mut(&mut self) -> &mut GuardSet {
765        self.guards_mut(&self.active_set.clone())
766    }
767
768    /// Return a mutable reference to the set of guards corresponding to the
769    /// provided selector.
770    fn guards_mut(&mut self, selector: &GuardSetSelector) -> &mut GuardSet {
771        match selector {
772            GuardSetSelector::Default => &mut self.default,
773            GuardSetSelector::Restricted => &mut self.restricted,
774            #[cfg(feature = "bridge-client")]
775            GuardSetSelector::Bridges => &mut self.bridges,
776        }
777    }
778
779    /// Update all non-persistent state for the guards in this object with the
780    /// state in `other`.
781    fn copy_status_from(&mut self, mut other: GuardSets) {
782        use strum::IntoEnumIterator;
783        for sample in GuardSetSelector::iter() {
784            self.guards_mut(&sample)
785                .copy_ephemeral_status_into_newly_loaded_state(std::mem::take(
786                    other.guards_mut(&sample),
787                ));
788        }
789        self.active_set = other.active_set;
790    }
791}
792
793impl GuardMgrInner {
794    /// Look up the latest [`NetDir`] (if there is one) from our
795    /// [`NetDirProvider`] (if we have one).
796    fn timely_netdir(&self) -> Option<Arc<NetDir>> {
797        self.netdir_provider
798            .as_ref()
799            .and_then(Weak::upgrade)
800            .and_then(|np| np.timely_netdir().ok())
801    }
802
803    /// Look up the latest [`BridgeDescList`](bridge::BridgeDescList) (if there
804    /// is one) from our [`BridgeDescProvider`](bridge::BridgeDescProvider) (if
805    /// we have one).
806    #[cfg(feature = "bridge-client")]
807    fn latest_bridge_desc_list(&self) -> Option<Arc<bridge::BridgeDescList>> {
808        self.bridge_desc_provider
809            .as_ref()
810            .and_then(Weak::upgrade)
811            .map(|bp| bp.bridges())
812    }
813
814    /// Run a function that takes `&mut self` and an optional NetDir.
815    ///
816    /// We try to use the netdir from our [`NetDirProvider`] (if we have one).
817    /// Therefore, although its _parameters_ are suitable for every
818    /// [`GuardSet`], its _contents_ might not be. For those, call
819    /// [`with_opt_universe`](Self::with_opt_universe) instead.
820    //
821    // This function exists to handle the lifetime mess where sometimes the
822    // resulting NetDir will borrow from `netdir`, and sometimes it will borrow
823    // from an Arc returned by `self.latest_netdir()`.
824    fn with_opt_netdir<F, T>(&mut self, func: F) -> T
825    where
826        F: FnOnce(&mut Self, Option<&NetDir>) -> T,
827    {
828        if let Some(nd) = self.timely_netdir() {
829            func(self, Some(nd.as_ref()))
830        } else {
831            func(self, None)
832        }
833    }
834
835    /// Return the latest `BridgeSet` based on our `BridgeDescProvider` and our
836    /// configured bridges.
837    ///
838    /// Returns `None` if we are not configured to use bridges.
839    #[cfg(feature = "bridge-client")]
840    fn latest_bridge_set(&self) -> Option<bridge::BridgeSet> {
841        let bridge_config = self.configured_bridges.as_ref()?.clone();
842        let bridge_descs = self.latest_bridge_desc_list();
843        Some(bridge::BridgeSet::new(bridge_config, bridge_descs))
844    }
845
846    /// Run a function that takes `&mut self` and an optional [`UniverseRef`].
847    ///
848    /// We try to get a universe from the appropriate source for the current
849    /// active guard set.
850    fn with_opt_universe<F, T>(&mut self, func: F) -> T
851    where
852        F: FnOnce(&mut Self, Option<&UniverseRef>) -> T,
853    {
854        // TODO: it might be nice to make `func` take an GuardSet and a set of
855        // parameters, so we can't get the active set wrong. Doing that will
856        // require a fair amount of refactoring so that the borrow checker is
857        // happy, however.
858        match self.guards.active_set.universe_type() {
859            UniverseType::NetDir => {
860                if let Some(nd) = self.timely_netdir() {
861                    func(self, Some(&UniverseRef::NetDir(nd)))
862                } else {
863                    func(self, None)
864                }
865            }
866            #[cfg(feature = "bridge-client")]
867            UniverseType::BridgeSet => func(
868                self,
869                self.latest_bridge_set()
870                    .map(UniverseRef::BridgeSet)
871                    .as_ref(),
872            ),
873        }
874    }
875
876    /// Update the status of all guards in the active set, based on the passage
877    /// of time, our configuration, and the relevant Universe for our active
878    /// set.
879    #[instrument(skip_all, level = "trace")]
880    fn update(&mut self, wallclock: SystemTime, now: Instant) {
881        self.with_opt_netdir(|this, netdir| {
882            // Here we update our parameters from the latest NetDir, and check
883            // whether we need to change to a (non)-restrictive GuardSet based
884            // on those parameters and our configured filter.
885            //
886            // This uses a NetDir unconditionally, since we always want to take
887            // the network parameters our parameters from the consensus even if
888            // the guards themselves are from a BridgeSet.
889            this.update_active_set_params_and_filter(netdir);
890        });
891        self.with_opt_universe(|this, univ| {
892            // Now we update the set of guards themselves based on the
893            // Universe, which is either the latest NetDir, or the latest
894            // BridgeSet—depending on what the GuardSet wants.
895            Self::update_guardset_internal(
896                &this.params,
897                wallclock,
898                this.guards.active_set.universe_type(),
899                this.guards.active_guards_mut(),
900                univ,
901            );
902            #[cfg(feature = "bridge-client")]
903            this.update_desired_descriptors(now);
904            #[cfg(not(feature = "bridge-client"))]
905            let _ = now;
906        });
907    }
908
909    /// Replace our bridge configuration with the one from `new_config`.
910    #[cfg(feature = "bridge-client")]
911    #[instrument(level = "trace", skip_all)]
912    fn replace_bridge_config(
913        &mut self,
914        new_config: &impl GuardMgrConfig,
915        wallclock: SystemTime,
916        now: Instant,
917    ) -> Result<RetireCircuits, GuardMgrConfigError> {
918        match (&self.configured_bridges, new_config.bridges_enabled()) {
919            (None, false) => {
920                assert_ne!(
921                    self.guards.active_set.universe_type(),
922                    UniverseType::BridgeSet
923                );
924                return Ok(RetireCircuits::None); // nothing to do
925            }
926            (_, true) if !self.storage.can_store() => {
927                // TODO: Ideally we would try to upgrade, obtaining an exclusive lock,
928                // but `StorageHandle` currently lacks a method for that.
929                return Err(GuardMgrConfigError::NoLock("bridges configured".into()));
930            }
931            (Some(current_bridges), true) if new_config.bridges() == current_bridges.as_ref() => {
932                assert_eq!(
933                    self.guards.active_set.universe_type(),
934                    UniverseType::BridgeSet
935                );
936                return Ok(RetireCircuits::None); // nothing to do.
937            }
938            (_, true) => {
939                self.configured_bridges = Some(new_config.bridges().into());
940                self.guards.active_set = GuardSetSelector::Bridges;
941            }
942            (_, false) => {
943                self.configured_bridges = None;
944                self.guards.active_set = GuardSetSelector::Default;
945            }
946        }
947
948        // If we have gotten here, we have changed the set of bridges, changed
949        // which set is active, or changed them both.  We need to make sure that
950        // our `GuardSet` object is up-to-date with our configuration.
951        self.update(wallclock, now);
952
953        // We also need to tell the caller that its circuits are no good any
954        // more.
955        //
956        // TODO(nickm): Someday we can do this more judiciously by retuning
957        // "Some" in the case where we're still using bridges but our new bridge
958        // set contains different elements; see comment on RetireCircuits.
959        //
960        // TODO(nickm): We could also safely return RetireCircuits::None if we
961        // are using bridges, and our new bridge list is a superset of the older
962        // one.
963        Ok(RetireCircuits::All)
964    }
965
966    /// Update our parameters, our selection (based on network parameters and
967    /// configuration), and make sure the active GuardSet has the right
968    /// configuration itself.
969    ///
970    /// We should call this whenever the NetDir's parameters change, or whenever
971    /// our filter changes.  We do not need to call it for new elements arriving
972    /// in our Universe, since those do not affect anything here.
973    ///
974    /// We should also call this whenever a new GuardSet becomes active for any
975    /// reason _other_ than just having called this function.
976    ///
977    /// (This function is only invoked from `update`, which should be called
978    /// under the above circumstances.)
979    fn update_active_set_params_and_filter(&mut self, netdir: Option<&NetDir>) {
980        // Set the parameters.  These always come from the NetDir, even if this
981        // is a bridge set.
982        if let Some(netdir) = netdir {
983            match GuardParams::try_from(netdir.params()) {
984                Ok(params) => self.params = params,
985                Err(e) => warn!("Unusable guard parameters from consensus: {}", e),
986            }
987
988            self.select_guard_set_based_on_filter(netdir);
989        }
990
991        // Change the filter, if it doesn't match what the guards have.
992        //
993        // TODO(nickm): We could use a "dirty" flag or something to decide
994        // whether we need to call set_filter, if this comparison starts to show
995        // up in profiles.
996        if self.guards.active_guards().filter() != &self.filter {
997            let restrictive = self.guards.active_set == GuardSetSelector::Restricted;
998            self.guards
999                .active_guards_mut()
1000                .set_filter(self.filter.clone(), restrictive);
1001        }
1002    }
1003
1004    /// Update the status of every guard in `active_guards`, and expand it as
1005    /// needed.
1006    ///
1007    /// This function doesn't take `&self`, to make sure that we are only
1008    /// affecting a single `GuardSet`, and to avoid confusing the borrow
1009    /// checker.
1010    ///
1011    /// We should call this whenever the contents of the universe have changed.
1012    ///
1013    /// We should also call this whenever a new GuardSet becomes active.
1014    fn update_guardset_internal<U: Universe>(
1015        params: &GuardParams,
1016        now: SystemTime,
1017        universe_type: UniverseType,
1018        active_guards: &mut GuardSet,
1019        universe: Option<&U>,
1020    ) -> ExtendedStatus {
1021        // Expire guards.  Do that early, in case doing so makes it clear that
1022        // we need to grab more guards or mark others as primary.
1023        active_guards.expire_old_guards(params, now);
1024
1025        let extended = if let Some(universe) = universe {
1026            // TODO: This check here may be completely unnecessary. I inserted
1027            // it back in 5ac0fcb7ef603e0d14 because I was originally concerned
1028            // it might be undesirable to list a primary guard as "missing dir
1029            // info" (and therefore unusable) if we were expecting to get its
1030            // microdescriptor "very soon."
1031            //
1032            // But due to the other check in `netdir_is_sufficient`, we
1033            // shouldn't be installing a netdir until it has microdescs for all
1034            // of the (non-bridge) primary guards that it lists. - nickm
1035            let n = active_guards.n_primary_without_id_info_in(universe);
1036            if n > 0 && universe_type == UniverseType::NetDir {
1037                // We are missing the information from a NetDir needed to see
1038                // whether our primary guards are listed, so we shouldn't update
1039                // our guard status.
1040                //
1041                // We don't want to do this check if we are using bridges, since
1042                // a missing bridge descriptor is not guaranteed to temporary
1043                // problem in the same way that a missing microdescriptor is.
1044                // (When a bridge desc is missing, the bridge could be down or
1045                // unreachable, and nobody else can help us. But if a microdesc
1046                // is missing, we just need to find a cache that has it.)
1047                trace!(
1048                    n_primary_without_id_info = n,
1049                    "Not extending guardset, missing information."
1050                );
1051                return ExtendedStatus::No;
1052            }
1053            active_guards.update_status_from_dir(universe);
1054            active_guards.extend_sample_as_needed(now, params, universe)
1055        } else {
1056            trace!("Not extending guardset, no universe given.");
1057            ExtendedStatus::No
1058        };
1059
1060        active_guards.select_primary_guards(params);
1061
1062        extended
1063    }
1064
1065    /// If using bridges, tell the BridgeDescProvider which descriptors we want.
1066    /// We need to check this *after* we select our primary guards.
1067    #[cfg(feature = "bridge-client")]
1068    fn update_desired_descriptors(&mut self, now: Instant) {
1069        if self.guards.active_set.universe_type() != UniverseType::BridgeSet {
1070            return;
1071        }
1072
1073        let provider = self.bridge_desc_provider.as_ref().and_then(Weak::upgrade);
1074        let bridge_set = self.latest_bridge_set();
1075        if let (Some(provider), Some(bridge_set)) = (provider, bridge_set) {
1076            let desired: Vec<_> = self
1077                .guards
1078                .active_guards()
1079                .descriptors_to_request(now, &self.params)
1080                .into_iter()
1081                .flat_map(|guard| bridge_set.bridge_by_guard(guard))
1082                .cloned()
1083                .collect();
1084
1085            provider.set_bridges(&desired);
1086        }
1087    }
1088
1089    /// Replace the active guard state with `new_state`, preserving
1090    /// non-persistent state for any guards that are retained.
1091    #[instrument(level = "trace", skip_all)]
1092    fn replace_guards_with(
1093        &mut self,
1094        mut new_guards: GuardSets,
1095        wallclock: SystemTime,
1096        now: Instant,
1097    ) {
1098        std::mem::swap(&mut self.guards, &mut new_guards);
1099        self.guards.copy_status_from(new_guards);
1100        self.update(wallclock, now);
1101    }
1102
1103    /// Update which guard set is active based on the current filter and the
1104    /// provided netdir.
1105    ///
1106    /// After calling this function, the new guard set's filter may be
1107    /// out-of-date: be sure to call `set_filter` as appropriate.
1108    fn select_guard_set_based_on_filter(&mut self, netdir: &NetDir) {
1109        // In general, we'd like to use the restricted set if we're under the
1110        // threshold, and the default set if we're over the threshold.  But if
1111        // we're sitting close to the threshold, we want to avoid flapping back
1112        // and forth, so we only change when we're more than 5% "off" from
1113        // whatever our current setting is.
1114        //
1115        // (See guard-spec section 2 for more information.)
1116        let offset = match self.guards.active_set {
1117            GuardSetSelector::Default => -0.05,
1118            GuardSetSelector::Restricted => 0.05,
1119            // If we're using bridges, then we don't switch between the other guard sets based on the filter at all.
1120            #[cfg(feature = "bridge-client")]
1121            GuardSetSelector::Bridges => return,
1122        };
1123        let frac_permitted = self.filter.frac_bw_permitted(netdir);
1124        let threshold = self.params.filter_threshold + offset;
1125        let new_choice = if frac_permitted < threshold {
1126            GuardSetSelector::Restricted
1127        } else {
1128            GuardSetSelector::Default
1129        };
1130
1131        if new_choice != self.guards.active_set {
1132            info!(
1133                "Guard selection changed; we are now using the {:?} guard set",
1134                &new_choice
1135            );
1136
1137            self.guards.active_set = new_choice;
1138
1139            if frac_permitted < self.params.extreme_threshold {
1140                warn!(
1141                    "The number of guards permitted is smaller than the recommended minimum of {:.0}%.",
1142                    self.params.extreme_threshold * 100.0,
1143                );
1144            }
1145        }
1146    }
1147
1148    /// Mark all of our primary guards as retriable, if we haven't done
1149    /// so since long enough before `now`.
1150    ///
1151    /// We want to call this function whenever a guard attempt succeeds,
1152    /// if the internet seemed to be down when the guard attempt was
1153    /// first launched.
1154    fn maybe_retry_primary_guards(&mut self, now: Instant) {
1155        // We don't actually want to mark our primary guards as
1156        // retriable more than once per internet_down_timeout: after
1157        // the first time, we would just be noticing the same "coming
1158        // back online" event more than once.
1159        let interval = self.params.internet_down_timeout;
1160        if self.last_primary_retry_time + interval <= now {
1161            debug!(
1162                "Successfully reached a guard after a while off the internet; marking all primary guards retriable."
1163            );
1164            self.guards
1165                .active_guards_mut()
1166                .mark_primary_guards_retriable();
1167            self.last_primary_retry_time = now;
1168        }
1169    }
1170
1171    /// Replace the current GuardFilter with `filter`.
1172    #[instrument(level = "trace", skip_all)]
1173    fn set_filter(&mut self, filter: GuardFilter, wallclock: SystemTime, now: Instant) {
1174        self.filter = filter;
1175        self.update(wallclock, now);
1176    }
1177
1178    /// Called when the circuit manager reports (via [`GuardMonitor`]) that
1179    /// a guard succeeded or failed.
1180    ///
1181    /// Changes the guard's status as appropriate, and updates the pending
1182    /// request as needed.
1183    pub(crate) fn handle_msg(
1184        &mut self,
1185        request_id: RequestId,
1186        status: GuardStatus,
1187        skew: Option<ClockSkew>,
1188        runtime: &impl tor_rtcompat::SleepProvider,
1189    ) {
1190        if let Some(mut pending) = self.pending.remove(&request_id) {
1191            // If there was a pending request matching this RequestId, great!
1192            let guard_id = pending.guard_id();
1193            trace!(?guard_id, ?status, "Received report of guard status");
1194
1195            // First, handle the skew report (if any)
1196            if let Some(skew) = skew {
1197                let now = runtime.now();
1198                let observation = skew::SkewObservation { skew, when: now };
1199
1200                match &guard_id.0 {
1201                    FirstHopIdInner::Guard(_, id) => {
1202                        self.guards.active_guards_mut().record_skew(id, observation);
1203                    }
1204                    FirstHopIdInner::Fallback(id) => {
1205                        self.fallbacks.note_skew(id, observation);
1206                    }
1207                }
1208                // TODO: We call this whenever we receive an observed clock
1209                // skew. That's not the perfect timing for two reasons.  First
1210                // off, it might be too frequent: it does an O(n) calculation,
1211                // which isn't ideal.  Second, it might be too infrequent: after
1212                // an hour has passed, a given observation won't be up-to-date
1213                // any more, and we might want to recalculate the skew
1214                // accordingly.
1215                self.update_skew(now);
1216            }
1217
1218            match (status, &guard_id.0) {
1219                (GuardStatus::Failure, FirstHopIdInner::Fallback(id)) => {
1220                    // We used a fallback, and we weren't able to build a circuit through it.
1221                    self.fallbacks.note_failure(id, runtime.now());
1222                }
1223                (_, FirstHopIdInner::Fallback(_)) => {
1224                    // We don't record any other kind of circuit activity if we
1225                    // took the entry from the fallback list.
1226                }
1227                (GuardStatus::Success, FirstHopIdInner::Guard(sample, id)) => {
1228                    // If we had gone too long without any net activity when we
1229                    // gave out this guard, and now we're seeing a circuit
1230                    // succeed, tell the primary guards that they might be
1231                    // retriable.
1232                    if pending.net_has_been_down() {
1233                        self.maybe_retry_primary_guards(runtime.now());
1234                    }
1235
1236                    // The guard succeeded.  Tell the GuardSet.
1237                    self.guards.guards_mut(sample).record_success(
1238                        id,
1239                        &self.params,
1240                        None,
1241                        runtime.wallclock(),
1242                    );
1243                    // Either tell the request whether the guard is
1244                    // usable, or schedule it as a "waiting" request.
1245                    if let Some(usable) = self.guard_usability_status(&pending, runtime.now()) {
1246                        trace!(?guard_id, usable, "Known usability status");
1247                        pending.reply(usable);
1248                    } else {
1249                        // This is the one case where we can't use the
1250                        // guard yet.
1251                        trace!(?guard_id, "Not able to answer right now");
1252                        pending.mark_waiting(runtime.now());
1253                        self.waiting.push(pending);
1254                    }
1255                }
1256                (GuardStatus::Failure, FirstHopIdInner::Guard(sample, id)) => {
1257                    self.guards
1258                        .guards_mut(sample)
1259                        .record_failure(id, None, runtime.now());
1260                    pending.reply(false);
1261                }
1262                (GuardStatus::AttemptAbandoned, FirstHopIdInner::Guard(sample, id)) => {
1263                    self.guards.guards_mut(sample).record_attempt_abandoned(id);
1264                    pending.reply(false);
1265                }
1266                (GuardStatus::Indeterminate, FirstHopIdInner::Guard(sample, id)) => {
1267                    self.guards
1268                        .guards_mut(sample)
1269                        .record_indeterminate_result(id);
1270                    pending.reply(false);
1271                }
1272            };
1273        } else {
1274            warn!(
1275                "Got a status {:?} for a request {:?} that wasn't pending",
1276                status, request_id
1277            );
1278        }
1279
1280        // We might need to update the primary guards based on changes in the
1281        // status of guards above.
1282        self.guards
1283            .active_guards_mut()
1284            .select_primary_guards(&self.params);
1285
1286        // Some waiting request may just have become ready (usable or
1287        // not); we need to give them the information they're waiting
1288        // for.
1289        self.expire_and_answer_pending_requests(runtime.now());
1290    }
1291
1292    /// Helper to implement `GuardMgr::note_external_success()`.
1293    ///
1294    /// (This has to be a separate function so that we can borrow params while
1295    /// we have `mut self` borrowed.)
1296    fn record_external_success<T>(
1297        &mut self,
1298        identity: &T,
1299        external_activity: ExternalActivity,
1300        now: SystemTime,
1301    ) where
1302        T: tor_linkspec::HasRelayIds + ?Sized,
1303    {
1304        for id in self.lookup_ids(identity) {
1305            match &id.0 {
1306                FirstHopIdInner::Guard(sample, id) => {
1307                    self.guards.guards_mut(sample).record_success(
1308                        id,
1309                        &self.params,
1310                        Some(external_activity),
1311                        now,
1312                    );
1313                }
1314                FirstHopIdInner::Fallback(id) => {
1315                    if external_activity == ExternalActivity::DirCache {
1316                        self.fallbacks.note_success(id);
1317                    }
1318                }
1319            }
1320        }
1321    }
1322
1323    /// Return an iterator over all of the clock skew observations we've made
1324    /// for guards or fallbacks.
1325    fn skew_observations(&self) -> impl Iterator<Item = &skew::SkewObservation> {
1326        self.fallbacks
1327            .skew_observations()
1328            .chain(self.guards.active_guards().skew_observations())
1329    }
1330
1331    /// Recalculate our estimated clock skew, and publish it to anybody who
1332    /// cares.
1333    fn update_skew(&mut self, now: Instant) {
1334        let estimate = skew::SkewEstimate::estimate_skew(self.skew_observations(), now);
1335        // TODO: we might want to do this only conditionally, when the skew
1336        // estimate changes.
1337        *self.send_skew.borrow_mut() = estimate;
1338    }
1339
1340    /// If the circuit built because of a given [`PendingRequest`] may
1341    /// now be used (or discarded), return `Some(true)` or
1342    /// `Some(false)` respectively.
1343    ///
1344    /// Return None if we can't yet give an answer about whether such
1345    /// a circuit is usable.
1346    fn guard_usability_status(&self, pending: &PendingRequest, now: Instant) -> Option<bool> {
1347        match &pending.guard_id().0 {
1348            FirstHopIdInner::Guard(sample, id) => self.guards.guards(sample).circ_usability_status(
1349                id,
1350                pending.usage(),
1351                &self.params,
1352                now,
1353            ),
1354            // Fallback circuits are usable immediately, since we don't have to wait to
1355            // see whether any _other_ circuit succeeds or fails.
1356            FirstHopIdInner::Fallback(_) => Some(true),
1357        }
1358    }
1359
1360    /// For requests that have been "waiting" for an answer for too long,
1361    /// expire them and tell the circuit manager that their circuits
1362    /// are unusable.
1363    fn expire_and_answer_pending_requests(&mut self, now: Instant) {
1364        // A bit ugly: we use a separate Vec here to avoid borrowing issues,
1365        // and put it back when we're done.
1366        let mut waiting = Vec::new();
1367        std::mem::swap(&mut waiting, &mut self.waiting);
1368
1369        waiting.retain_mut(|pending| {
1370            let expired = pending
1371                .waiting_since()
1372                .and_then(|w| now.checked_duration_since(w))
1373                .map(|d| d >= self.params.np_idle_timeout)
1374                == Some(true);
1375            if expired {
1376                trace!(?pending, "Pending request expired");
1377                pending.reply(false);
1378                return false;
1379            }
1380
1381            // TODO-SPEC: guard_usability_status isn't what the spec says.  It
1382            // says instead that we should look at _circuit_ status, saying:
1383            //  "   Definition: In the algorithm above, C2 "blocks" C1 if:
1384            // * C2 obeys all the restrictions that C1 had to obey, AND
1385            // * C2 has higher priority than C1, AND
1386            // * Either C2 is <complete>, or C2 is <waiting_for_better_guard>,
1387            // or C2 has been <usable_if_no_better_guard> for no more than
1388            // {NONPRIMARY_GUARD_CONNECT_TIMEOUT} seconds."
1389            //
1390            // See comments in sample::GuardSet::circ_usability_status.
1391
1392            if let Some(answer) = self.guard_usability_status(pending, now) {
1393                trace!(?pending, answer, "Pending request now ready");
1394                pending.reply(answer);
1395                return false;
1396            }
1397            true
1398        });
1399
1400        // Put the waiting list back.
1401        std::mem::swap(&mut waiting, &mut self.waiting);
1402    }
1403
1404    /// Return every currently extant FirstHopId for a guard or fallback
1405    /// directory matching (or possibly matching) the provided keys.
1406    ///
1407    /// An identity is _possibly matching_ if it contains some of the IDs in the
1408    /// provided identity, and it has no _contradictory_ identities, but it does
1409    /// not necessarily contain _all_ of those identities.
1410    ///
1411    /// # TODO
1412    ///
1413    /// This function should probably not exist; it's only used so that dirmgr
1414    /// can report successes or failures, since by the time it observes them it
1415    /// doesn't know whether its circuit came from a guard or a fallback.  To
1416    /// solve that, we'll need CircMgr to record and report which one it was
1417    /// using, which will take some more plumbing.
1418    ///
1419    /// TODO relay: we will have to make the change above when we implement
1420    /// relays; otherwise, it would be possible for an attacker to exploit it to
1421    /// mislead us about our guard status.
1422    fn lookup_ids<T>(&self, identity: &T) -> Vec<FirstHopId>
1423    where
1424        T: tor_linkspec::HasRelayIds + ?Sized,
1425    {
1426        use strum::IntoEnumIterator;
1427        let mut vec = Vec::with_capacity(2);
1428
1429        let id = ids::GuardId::from_relay_ids(identity);
1430        for sample in GuardSetSelector::iter() {
1431            let guard_id = match self.guards.guards(&sample).contains(&id) {
1432                Ok(true) => &id,
1433                Err(other) => other,
1434                Ok(false) => continue,
1435            };
1436            vec.push(FirstHopId(FirstHopIdInner::Guard(sample, guard_id.clone())));
1437        }
1438
1439        let id = ids::FallbackId::from_relay_ids(identity);
1440        if self.fallbacks.contains(&id) {
1441            vec.push(id.into());
1442        }
1443
1444        vec
1445    }
1446
1447    /// Run any periodic events that update guard status, and return a
1448    /// duration after which periodic events should next be run.
1449    #[instrument(skip_all, level = "trace")]
1450    pub(crate) fn run_periodic_events(&mut self, wallclock: SystemTime, now: Instant) -> Duration {
1451        self.update(wallclock, now);
1452        self.expire_and_answer_pending_requests(now);
1453        Duration::from_secs(1) // TODO: Too aggressive.
1454    }
1455
1456    /// Try to select a guard, expanding the sample if the first attempt fails.
1457    #[instrument(skip_all, level = "trace")]
1458    fn select_guard_with_expand(
1459        &mut self,
1460        usage: &GuardUsage,
1461        now: Instant,
1462        wallclock: SystemTime,
1463    ) -> Result<(sample::ListKind, FirstHop), PickGuardError> {
1464        // Try to find a guard.
1465        let first_error = match self.select_guard_once(usage, now) {
1466            Ok(res1) => return Ok(res1),
1467            Err(e) => {
1468                trace!("Couldn't select guard on first attempt: {}", e);
1469                e
1470            }
1471        };
1472
1473        // That didn't work. If we have a netdir, expand the sample and try again.
1474        let res = self.with_opt_universe(|this, univ| {
1475            let univ = univ?;
1476            trace!("No guards available, trying to extend the sample.");
1477            // Make sure that the status on all of our guards are accurate, and
1478            // expand the sample if we can.
1479            //
1480            // Our parameters and configuration did not change, so we do not
1481            // need to call update() or update_active_set_and_filter(). This
1482            // call is sufficient to  extend the sample and recompute primary
1483            // guards.
1484            let extended = Self::update_guardset_internal(
1485                &this.params,
1486                wallclock,
1487                this.guards.active_set.universe_type(),
1488                this.guards.active_guards_mut(),
1489                Some(univ),
1490            );
1491            if extended == ExtendedStatus::Yes {
1492                match this.select_guard_once(usage, now) {
1493                    Ok(res) => return Some(res),
1494                    Err(e) => {
1495                        trace!("Couldn't select guard after update: {}", e);
1496                    }
1497                }
1498            }
1499            None
1500        });
1501        if let Some(res) = res {
1502            return Ok(res);
1503        }
1504
1505        // Okay, that didn't work either.  If we were asked for a directory
1506        // guard, and we aren't using bridges, then we may be able to use a
1507        // fallback.
1508        if usage.kind == GuardUsageKind::OneHopDirectory
1509            && self.guards.active_set.universe_type() == UniverseType::NetDir
1510        {
1511            return self.select_fallback(now);
1512        }
1513
1514        // Couldn't extend the sample or use a fallback; return the original error.
1515        Err(first_error)
1516    }
1517
1518    /// Helper: try to pick a single guard, without retrying on failure.
1519    fn select_guard_once(
1520        &self,
1521        usage: &GuardUsage,
1522        now: Instant,
1523    ) -> Result<(sample::ListKind, FirstHop), PickGuardError> {
1524        let active_set = &self.guards.active_set;
1525        #[cfg_attr(not(feature = "bridge-client"), allow(unused_mut))]
1526        let (list_kind, mut first_hop) =
1527            self.guards
1528                .guards(active_set)
1529                .pick_guard(active_set, usage, &self.params, now)?;
1530        #[cfg(feature = "bridge-client")]
1531        if self.guards.active_set.universe_type() == UniverseType::BridgeSet {
1532            // See if we can promote first_hop to a viable CircTarget.
1533            let bridges = self.latest_bridge_set().ok_or_else(|| {
1534                PickGuardError::Internal(internal!(
1535                    "No bridge set available, even though this is the Bridges sample"
1536                ))
1537            })?;
1538            first_hop.lookup_bridge_circ_target(&bridges);
1539
1540            if usage.kind == GuardUsageKind::Data && !first_hop.contains_circ_target() {
1541                return Err(PickGuardError::Internal(internal!(
1542                    "Tried to return a non-circtarget guard with Data usage!"
1543                )));
1544            }
1545        }
1546        Ok((list_kind, first_hop))
1547    }
1548
1549    /// Helper: Select a fallback directory.
1550    ///
1551    /// Called when we have no guard information to use. Return values are as
1552    /// for [`GuardMgr::select_guard()`]
1553    fn select_fallback(
1554        &self,
1555        now: Instant,
1556    ) -> Result<(sample::ListKind, FirstHop), PickGuardError> {
1557        let filt = self.guards.active_guards().filter();
1558
1559        let fallback = crate::FirstHop {
1560            sample: None,
1561            inner: crate::FirstHopInner::Chan(OwnedChanTarget::from_chan_target(
1562                self.fallbacks.choose(&mut rand::rng(), now, filt)?,
1563            )),
1564        };
1565        let fallback = filt.modify_hop(fallback)?;
1566        Ok((sample::ListKind::Fallback, fallback))
1567    }
1568}
1569
1570/// A possible outcome of trying to extend a guard sample.
1571#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1572enum ExtendedStatus {
1573    /// The guard sample was extended. (At least one guard was added to it.)
1574    Yes,
1575    /// The guard sample was not extended.
1576    No,
1577}
1578
1579/// A set of parameters, derived from the consensus document, controlling
1580/// the behavior of a guard manager.
1581#[derive(Debug, Clone)]
1582#[cfg_attr(test, derive(PartialEq))]
1583struct GuardParams {
1584    /// How long should a sampled, un-confirmed guard be kept in the sample before it expires?
1585    lifetime_unconfirmed: Duration,
1586    /// How long should a confirmed guard be kept in the sample before
1587    /// it expires?
1588    lifetime_confirmed: Duration,
1589    /// How long may  a guard be unlisted before we remove it from the sample?
1590    lifetime_unlisted: Duration,
1591    /// Largest number of guards we're willing to add to the sample.
1592    max_sample_size: usize,
1593    /// Largest fraction of the network's guard bandwidth that we're
1594    /// willing to add to the sample.
1595    max_sample_bw_fraction: f64,
1596    /// Smallest number of guards that we're willing to have in the
1597    /// sample, after applying a [`GuardFilter`].
1598    min_filtered_sample_size: usize,
1599    /// How many guards are considered "Primary"?
1600    n_primary: usize,
1601    /// When making a regular circuit, how many primary guards should we
1602    /// be willing to try?
1603    data_parallelism: usize,
1604    /// When making a one-hop directory circuit, how many primary
1605    /// guards should we be willing to try?
1606    dir_parallelism: usize,
1607    /// For how long does a pending attempt to connect to a guard
1608    /// block an attempt to use a less-favored non-primary guard?
1609    np_connect_timeout: Duration,
1610    /// How long do we allow a circuit to a successful but unfavored
1611    /// non-primary guard to sit around before deciding not to use it?
1612    np_idle_timeout: Duration,
1613    /// After how much time without successful activity does a
1614    /// successful circuit indicate that we should retry our primary
1615    /// guards?
1616    internet_down_timeout: Duration,
1617    /// What fraction of the guards can be can be filtered out before we
1618    /// decide that our filter is "very restrictive"?
1619    filter_threshold: f64,
1620    /// What fraction of the guards determine that our filter is "very
1621    /// restrictive"?
1622    extreme_threshold: f64,
1623}
1624
1625impl Default for GuardParams {
1626    fn default() -> Self {
1627        let one_day = Duration::from_secs(86400);
1628        GuardParams {
1629            lifetime_unconfirmed: one_day * 120,
1630            lifetime_confirmed: one_day * 60,
1631            lifetime_unlisted: one_day * 20,
1632            max_sample_size: 60,
1633            max_sample_bw_fraction: 0.2,
1634            min_filtered_sample_size: 20,
1635            n_primary: 3,
1636            data_parallelism: 1,
1637            dir_parallelism: 3,
1638            np_connect_timeout: Duration::from_secs(15),
1639            np_idle_timeout: Duration::from_secs(600),
1640            internet_down_timeout: Duration::from_secs(600),
1641            filter_threshold: 0.2,
1642            extreme_threshold: 0.01,
1643        }
1644    }
1645}
1646
1647impl TryFrom<&NetParameters> for GuardParams {
1648    type Error = tor_units::Error;
1649    fn try_from(p: &NetParameters) -> Result<GuardParams, Self::Error> {
1650        Ok(GuardParams {
1651            lifetime_unconfirmed: p.guard_lifetime_unconfirmed.try_into()?,
1652            lifetime_confirmed: p.guard_lifetime_confirmed.try_into()?,
1653            lifetime_unlisted: p.guard_remove_unlisted_after.try_into()?,
1654            max_sample_size: p.guard_max_sample_size.try_into()?,
1655            max_sample_bw_fraction: p.guard_max_sample_threshold.as_fraction(),
1656            min_filtered_sample_size: p.guard_filtered_min_sample_size.try_into()?,
1657            n_primary: p.guard_n_primary.try_into()?,
1658            data_parallelism: p.guard_use_parallelism.try_into()?,
1659            dir_parallelism: p.guard_dir_use_parallelism.try_into()?,
1660            np_connect_timeout: p.guard_nonprimary_connect_timeout.try_into()?,
1661            np_idle_timeout: p.guard_nonprimary_idle_timeout.try_into()?,
1662            internet_down_timeout: p.guard_internet_likely_down.try_into()?,
1663            filter_threshold: p.guard_meaningful_restriction.as_fraction(),
1664            extreme_threshold: p.guard_extreme_restriction.as_fraction(),
1665        })
1666    }
1667}
1668
1669/// Representation of a guard or fallback, as returned by [`GuardMgr::select_guard()`].
1670#[derive(Debug, Clone)]
1671pub struct FirstHop {
1672    /// The sample from which this guard was taken, or `None` if this is a fallback.
1673    sample: Option<GuardSetSelector>,
1674    /// Information about connecting to (or through) this guard.
1675    inner: FirstHopInner,
1676}
1677/// The enumeration inside a FirstHop that holds information about how to
1678/// connect to (and possibly through) a guard or fallback.
1679#[derive(Debug, Clone)]
1680enum FirstHopInner {
1681    /// We have enough information to connect to a guard.
1682    Chan(OwnedChanTarget),
1683    /// We have enough information to connect to a guards _and_ to build
1684    /// multihop circuits through it.
1685    #[cfg_attr(not(feature = "bridge-client"), allow(dead_code))]
1686    Circ(OwnedCircTarget),
1687}
1688
1689impl FirstHop {
1690    /// Return a new [`FirstHopId`] for this `FirstHop`.
1691    fn first_hop_id(&self) -> FirstHopId {
1692        match &self.sample {
1693            Some(sample) => {
1694                let guard_id = GuardId::from_relay_ids(self);
1695                FirstHopId::in_sample(sample.clone(), guard_id)
1696            }
1697            None => {
1698                let fallback_id = crate::ids::FallbackId::from_relay_ids(self);
1699                FirstHopId::from(fallback_id)
1700            }
1701        }
1702    }
1703
1704    /// Look up this guard in `netdir`.
1705    pub fn get_relay<'a>(&self, netdir: &'a NetDir) -> Option<Relay<'a>> {
1706        match &self.sample {
1707            #[cfg(feature = "bridge-client")]
1708            // Always return "None" for anything that isn't in the netdir.
1709            Some(s) if s.universe_type() == UniverseType::BridgeSet => None,
1710            // Otherwise ask the netdir.
1711            _ => netdir.by_ids(self),
1712        }
1713    }
1714
1715    /// Return true if this guard is a bridge.
1716    pub fn is_bridge(&self) -> bool {
1717        match &self.sample {
1718            #[cfg(feature = "bridge-client")]
1719            Some(s) if s.universe_type() == UniverseType::BridgeSet => true,
1720            _ => false,
1721        }
1722    }
1723
1724    /// If possible, return a view of this object that can be used to build a circuit.
1725    pub fn as_circ_target(&self) -> Option<&OwnedCircTarget> {
1726        match &self.inner {
1727            FirstHopInner::Chan(_) => None,
1728            FirstHopInner::Circ(ct) => Some(ct),
1729        }
1730    }
1731
1732    /// Return a view of this as an OwnedChanTarget.
1733    fn chan_target_mut(&mut self) -> &mut OwnedChanTarget {
1734        match &mut self.inner {
1735            FirstHopInner::Chan(ct) => ct,
1736            FirstHopInner::Circ(ct) => ct.chan_target_mut(),
1737        }
1738    }
1739
1740    /// If possible and appropriate, find a circuit target in `bridges` for this
1741    /// `FirstHop`, and make this `FirstHop` a viable circuit target.
1742    ///
1743    /// (By default, any `FirstHop` that a `GuardSet` returns will have enough
1744    /// information to be a `ChanTarget`, but it will be lacking the additional
1745    /// network information in `CircTarget`[^1] necessary for us to build a
1746    /// multi-hop circuit through it.  If this FirstHop is a regular non-bridge
1747    /// `Relay`, then the `CircMgr` will later look up that circuit information
1748    /// itself from the network directory. But if this `FirstHop` *is* a bridge,
1749    /// then we need to find that information in the `BridgeSet`, since the
1750    /// CircMgr does not keep track of the `BridgeSet`.)
1751    ///
1752    /// [^1]: For example, supported protocol versions and ntor keys.
1753    #[cfg(feature = "bridge-client")]
1754    fn lookup_bridge_circ_target(&mut self, bridges: &bridge::BridgeSet) {
1755        use crate::sample::CandidateStatus::Present;
1756        if self.sample.as_ref().map(|s| s.universe_type()) == Some(UniverseType::BridgeSet)
1757            && matches!(self.inner, FirstHopInner::Chan(_))
1758        {
1759            if let Present(bridge_relay) = bridges.bridge_relay_by_guard(self) {
1760                if let Some(circ_target) = bridge_relay.as_relay_with_desc() {
1761                    self.inner =
1762                        FirstHopInner::Circ(OwnedCircTarget::from_circ_target(&circ_target));
1763                }
1764            }
1765        }
1766    }
1767
1768    /// Return true if this `FirstHop` contains circuit target information.
1769    ///
1770    /// This is true if `lookup_bridge_circ_target()` has been called, and it
1771    /// successfully found the circuit target information.
1772    #[cfg(feature = "bridge-client")]
1773    fn contains_circ_target(&self) -> bool {
1774        matches!(self.inner, FirstHopInner::Circ(_))
1775    }
1776}
1777
1778// This is somewhat redundant with the implementations in crate::guard::Guard.
1779impl tor_linkspec::HasAddrs for FirstHop {
1780    fn addrs(&self) -> impl Iterator<Item = SocketAddr> {
1781        match &self.inner {
1782            FirstHopInner::Chan(ct) => Either::Left(ct.addrs()),
1783            FirstHopInner::Circ(ct) => Either::Right(ct.addrs()),
1784        }
1785    }
1786}
1787impl tor_linkspec::HasRelayIds for FirstHop {
1788    fn identity(
1789        &self,
1790        key_type: tor_linkspec::RelayIdType,
1791    ) -> Option<tor_linkspec::RelayIdRef<'_>> {
1792        match &self.inner {
1793            FirstHopInner::Chan(ct) => ct.identity(key_type),
1794            FirstHopInner::Circ(ct) => ct.identity(key_type),
1795        }
1796    }
1797}
1798impl tor_linkspec::HasChanMethod for FirstHop {
1799    fn chan_method(&self) -> tor_linkspec::ChannelMethod {
1800        match &self.inner {
1801            FirstHopInner::Chan(ct) => ct.chan_method(),
1802            FirstHopInner::Circ(ct) => ct.chan_method(),
1803        }
1804    }
1805}
1806impl tor_linkspec::ChanTarget for FirstHop {}
1807
1808/// The purpose for which we plan to use a guard.
1809///
1810/// This can affect the guard selection algorithm.
1811#[derive(Clone, Debug, Default, Eq, PartialEq)]
1812#[non_exhaustive]
1813pub enum GuardUsageKind {
1814    /// We want to use this guard for a data circuit.
1815    ///
1816    /// (This encompasses everything except the `OneHopDirectory` case.)
1817    #[default]
1818    Data,
1819    /// We want to use this guard for a one-hop, non-anonymous
1820    /// directory request.
1821    ///
1822    /// (Our algorithm allows more parallelism for the guards that we use
1823    /// for these circuits.)
1824    OneHopDirectory,
1825}
1826
1827/// A set of parameters describing how a single guard should be selected.
1828///
1829/// Used as an argument to [`GuardMgr::select_guard`].
1830#[derive(Clone, Debug, derive_builder::Builder)]
1831#[builder(build_fn(error = "tor_config::ConfigBuildError"))]
1832pub struct GuardUsage {
1833    /// The purpose for which this guard will be used.
1834    #[builder(default)]
1835    kind: GuardUsageKind,
1836    /// A list of restrictions on which guard may be used.
1837    ///
1838    /// The default is the empty list.
1839    #[builder(sub_builder, setter(custom))]
1840    restrictions: GuardRestrictionList,
1841}
1842
1843impl_standard_builder! { GuardUsage: !Deserialize }
1844
1845/// List of socket restrictions, as configured
1846pub type GuardRestrictionList = Vec<GuardRestriction>;
1847
1848define_list_builder_helper! {
1849    pub struct GuardRestrictionListBuilder {
1850        restrictions: [GuardRestriction],
1851    }
1852    built: GuardRestrictionList = restrictions;
1853    default = vec![];
1854    item_build: |restriction| Ok(restriction.clone());
1855    item_apply_defaults: |_| Ok::<_, tor_config::ConfigBuildError>(());
1856}
1857
1858define_list_builder_accessors! {
1859    struct GuardUsageBuilder {
1860        pub restrictions: [GuardRestriction],
1861    }
1862}
1863
1864impl GuardUsageBuilder {
1865    /// Create a new empty [`GuardUsageBuilder`].
1866    pub fn new() -> Self {
1867        Self::default()
1868    }
1869}
1870
1871/// A restriction that applies to a single request for a guard.
1872///
1873/// Restrictions differ from filters (see [`GuardFilter`]) in that
1874/// they apply to single requests, not to our entire set of guards.
1875/// They're suitable for things like making sure that we don't start
1876/// and end a circuit at the same relay, or requiring a specific
1877/// subprotocol version for certain kinds of requests.
1878#[derive(Clone, Debug, Serialize, Deserialize)]
1879#[non_exhaustive]
1880pub enum GuardRestriction {
1881    /// Don't pick a guard with the provided identity.
1882    AvoidId(RelayId),
1883    /// Don't pick a guard with any of the provided Ed25519 identities.
1884    AvoidAllIds(RelayIdSet),
1885}
1886
1887/// The kind of vanguards to use.
1888#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd)] //
1889#[derive(Serialize, Deserialize)] //
1890#[derive(derive_more::Display)] //
1891#[serde(rename_all = "lowercase")]
1892#[cfg(feature = "vanguards")]
1893#[non_exhaustive]
1894pub enum VanguardMode {
1895    /// "Lite" vanguards.
1896    #[default]
1897    #[display("lite")]
1898    Lite = 1,
1899    /// "Full" vanguards.
1900    #[display("full")]
1901    Full = 2,
1902    /// Vanguards are disabled.
1903    #[display("disabled")]
1904    Disabled = 0,
1905}
1906
1907#[cfg(feature = "vanguards")]
1908impl VanguardMode {
1909    /// Build a `VanguardMode` from a [`NetParameters`] parameter.
1910    ///
1911    /// Used for converting [`vanguards_enabled`](NetParameters::vanguards_enabled)
1912    /// or [`vanguards_hs_service`](NetParameters::vanguards_hs_service)
1913    /// to the corresponding `VanguardMode`.
1914    pub(crate) fn from_net_parameter(val: BoundedInt32<0, 2>) -> Self {
1915        match val.get() {
1916            0 => VanguardMode::Disabled,
1917            1 => VanguardMode::Lite,
1918            2 => VanguardMode::Full,
1919            _ => unreachable!("BoundedInt32 was not bounded?!"),
1920        }
1921    }
1922}
1923
1924impl_not_auto_value!(VanguardMode);
1925
1926/// Vanguards configuration.
1927#[derive(Deftly, Clone, Debug, PartialEq, Eq)]
1928#[derive_deftly(TorConfig)]
1929pub struct VanguardConfig {
1930    /// The kind of vanguards to use.
1931    #[deftly(tor_config(default))]
1932    mode: ExplicitOrAuto<VanguardMode>,
1933}
1934
1935impl VanguardConfig {
1936    /// Return the configured [`VanguardMode`].
1937    ///
1938    /// Returns the [`Default`] `VanguardMode`
1939    /// if the mode is [`Auto`](ExplicitOrAuto) or unspecified.
1940    pub fn mode(&self) -> VanguardMode {
1941        match self.mode {
1942            ExplicitOrAuto::Auto => Default::default(),
1943            ExplicitOrAuto::Explicit(mode) => mode,
1944        }
1945    }
1946}
1947
1948/// The kind of vanguards to use.
1949#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd)] //
1950#[derive(Serialize, Deserialize)] //
1951#[derive(derive_more::Display)] //
1952#[serde(rename_all = "lowercase")]
1953#[cfg(not(feature = "vanguards"))]
1954#[non_exhaustive]
1955pub enum VanguardMode {
1956    /// Vanguards are disabled.
1957    #[default]
1958    #[display("disabled")]
1959    Disabled = 0,
1960}
1961
1962#[cfg(test)]
1963mod test {
1964    // @@ begin test lint list maintained by maint/add_warning @@
1965    #![allow(clippy::bool_assert_comparison)]
1966    #![allow(clippy::clone_on_copy)]
1967    #![allow(clippy::dbg_macro)]
1968    #![allow(clippy::mixed_attributes_style)]
1969    #![allow(clippy::print_stderr)]
1970    #![allow(clippy::print_stdout)]
1971    #![allow(clippy::single_char_pattern)]
1972    #![allow(clippy::unwrap_used)]
1973    #![allow(clippy::unchecked_time_subtraction)]
1974    #![allow(clippy::useless_vec)]
1975    #![allow(clippy::needless_pass_by_value)]
1976    #![allow(clippy::string_slice)] // See arti#2571
1977    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
1978    use super::*;
1979    use itertools::Itertools;
1980    use tor_linkspec::{HasAddrs, HasRelayIds};
1981    use tor_persist::TestingStateMgr;
1982    use tor_rtcompat::test_with_all_runtimes;
1983
1984    #[test]
1985    fn guard_param_defaults() {
1986        let p1 = GuardParams::default();
1987        let p2: GuardParams = (&NetParameters::default()).try_into().unwrap();
1988        assert_eq!(p1, p2);
1989    }
1990
1991    fn init<R: Runtime>(rt: R) -> (GuardMgr<R>, TestingStateMgr, NetDir) {
1992        use tor_netdir::{MdReceiver, PartialNetDir, testnet};
1993        let statemgr = TestingStateMgr::new();
1994        let have_lock = statemgr.try_lock().unwrap();
1995        assert!(have_lock.held());
1996        let guardmgr = GuardMgr::new(rt, statemgr.clone(), &TestConfig::default()).unwrap();
1997        let (con, mds) = testnet::construct_network().unwrap();
1998        let param_overrides = vec![
1999            // We make the sample size smaller than usual to compensate for the
2000            // small testing network.  (Otherwise, we'd sample the whole network,
2001            // and not be able to observe guards in the tests.)
2002            "guard-min-filtered-sample-size=5",
2003            // We choose only two primary guards, to make the tests easier to write.
2004            "guard-n-primary-guards=2",
2005            // We define any restriction that allows 75% or fewer of relays as "meaningful",
2006            // so that we can test the "restrictive" guard sample behavior, and to avoid
2007            "guard-meaningful-restriction-percent=75",
2008        ];
2009        let param_overrides: String = param_overrides.into_iter().join(" ");
2010        let override_p = param_overrides.parse().unwrap();
2011        let mut netdir = PartialNetDir::new(con, Some(&override_p));
2012        for md in mds {
2013            netdir.add_microdesc(md);
2014        }
2015        let netdir = netdir.unwrap_if_sufficient().unwrap();
2016
2017        (guardmgr, statemgr, netdir)
2018    }
2019
2020    #[test]
2021    #[allow(clippy::clone_on_copy)]
2022    fn simple_case() {
2023        test_with_all_runtimes!(|rt| async move {
2024            let (guardmgr, statemgr, netdir) = init(rt.clone());
2025            let usage = GuardUsage::default();
2026            guardmgr.install_test_netdir(&netdir);
2027
2028            let (id, mon, usable) = guardmgr.select_guard(usage).unwrap();
2029            // Report that the circuit succeeded.
2030            mon.succeeded();
2031
2032            // May we use the circuit?
2033            let usable = usable.await.unwrap();
2034            assert!(usable);
2035
2036            // Save the state...
2037            guardmgr.flush_msg_queue().await;
2038            guardmgr.store_persistent_state().unwrap();
2039            drop(guardmgr);
2040
2041            // Try reloading from the state...
2042            let guardmgr2 =
2043                GuardMgr::new(rt.clone(), statemgr.clone(), &TestConfig::default()).unwrap();
2044            guardmgr2.install_test_netdir(&netdir);
2045
2046            // Since the guard was confirmed, we should get the same one this time!
2047            let usage = GuardUsage::default();
2048            let (id2, _mon, _usable) = guardmgr2.select_guard(usage).unwrap();
2049            assert!(id2.same_relay_ids(&id));
2050        });
2051    }
2052
2053    #[test]
2054    fn simple_waiting() {
2055        // TODO(nickm): This test fails in rare cases; I suspect a
2056        // race condition somewhere.
2057        //
2058        // I've doubled up on the queue flushing in order to try to make the
2059        // race less likely, but we should investigate.
2060        test_with_all_runtimes!(|rt| async move {
2061            let (guardmgr, _statemgr, netdir) = init(rt);
2062            let u = GuardUsage::default();
2063            guardmgr.install_test_netdir(&netdir);
2064
2065            // We'll have the first two guard fail, which should make us
2066            // try a non-primary guard.
2067            let (id1, mon, _usable) = guardmgr.select_guard(u.clone()).unwrap();
2068            mon.failed();
2069            guardmgr.flush_msg_queue().await; // avoid race
2070            guardmgr.flush_msg_queue().await; // avoid race
2071            let (id2, mon, _usable) = guardmgr.select_guard(u.clone()).unwrap();
2072            mon.failed();
2073            guardmgr.flush_msg_queue().await; // avoid race
2074            guardmgr.flush_msg_queue().await; // avoid race
2075
2076            assert!(!id1.same_relay_ids(&id2));
2077
2078            // Now we should get two sampled guards. They should be different.
2079            let (id3, mon3, usable3) = guardmgr.select_guard(u.clone()).unwrap();
2080            let (id4, mon4, usable4) = guardmgr.select_guard(u.clone()).unwrap();
2081            assert!(!id3.same_relay_ids(&id4));
2082
2083            let (u3, u4) = futures::join!(
2084                async {
2085                    mon3.failed();
2086                    guardmgr.flush_msg_queue().await; // avoid race
2087                    usable3.await.unwrap()
2088                },
2089                async {
2090                    mon4.succeeded();
2091                    usable4.await.unwrap()
2092                }
2093            );
2094
2095            assert_eq!((u3, u4), (false, true));
2096        });
2097    }
2098
2099    #[test]
2100    fn filtering_basics() {
2101        test_with_all_runtimes!(|rt| async move {
2102            let (guardmgr, _statemgr, netdir) = init(rt);
2103            let u = GuardUsage::default();
2104            let filter = {
2105                let mut f = GuardFilter::default();
2106                // All the addresses in the test network are {0,1,2,3,4}.0.0.3:9001.
2107                // Limit to only 2.0.0.0/8
2108                f.push_reachable_addresses(vec!["2.0.0.0/8:9001".parse().unwrap()]);
2109                f
2110            };
2111            guardmgr.set_filter(filter);
2112            guardmgr.install_test_netdir(&netdir);
2113            let (guard, _mon, _usable) = guardmgr.select_guard(u).unwrap();
2114            // Make sure that the filter worked.
2115            let addr = guard.addrs().next().unwrap();
2116            assert_eq!(addr, "2.0.0.3:9001".parse().unwrap());
2117        });
2118    }
2119
2120    #[test]
2121    fn external_status() {
2122        test_with_all_runtimes!(|rt| async move {
2123            let (guardmgr, _statemgr, netdir) = init(rt);
2124            let data_usage = GuardUsage::default();
2125            let dir_usage = GuardUsageBuilder::new()
2126                .kind(GuardUsageKind::OneHopDirectory)
2127                .build()
2128                .unwrap();
2129            guardmgr.install_test_netdir(&netdir);
2130            {
2131                // Override this parameter, so that we can get deterministic results below.
2132                let mut inner = guardmgr.inner.lock().unwrap();
2133                inner.params.dir_parallelism = 1;
2134            }
2135
2136            let (guard, mon, _usable) = guardmgr.select_guard(data_usage.clone()).unwrap();
2137            mon.succeeded();
2138
2139            // Record that this guard gave us a bad directory object.
2140            guardmgr.note_external_failure(&guard, ExternalActivity::DirCache);
2141
2142            // We ask for another guard, for data usage.  We should get the same
2143            // one as last time, since the director failure doesn't mean this
2144            // guard is useless as a primary guard.
2145            let (g2, mon, _usable) = guardmgr.select_guard(data_usage).unwrap();
2146            assert_eq!(g2.ed_identity(), guard.ed_identity());
2147            mon.succeeded();
2148
2149            // But if we ask for a guard for directory usage, we should get a
2150            // different one, since the last guard we gave out failed.
2151            let (g3, mon, _usable) = guardmgr.select_guard(dir_usage.clone()).unwrap();
2152            assert_ne!(g3.ed_identity(), guard.ed_identity());
2153            mon.succeeded();
2154
2155            // Now record a success for directory usage.
2156            guardmgr.note_external_success(&guard, ExternalActivity::DirCache);
2157
2158            // Now that the guard is working as a cache, asking for it should get us the same guard.
2159            let (g4, _mon, _usable) = guardmgr.select_guard(dir_usage).unwrap();
2160            assert_eq!(g4.ed_identity(), guard.ed_identity());
2161        });
2162    }
2163
2164    #[cfg(feature = "vanguards")]
2165    #[test]
2166    fn vanguard_mode_ord() {
2167        assert!(VanguardMode::Disabled < VanguardMode::Lite);
2168        assert!(VanguardMode::Disabled < VanguardMode::Full);
2169        assert!(VanguardMode::Lite < VanguardMode::Full);
2170    }
2171}