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}