#![cfg_attr(docsrs, feature(doc_cfg))]

#![doc = include_str!("../README.md")]

// @@ begin lint list maintained by maint/add_warning @@

#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)

#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)

#![warn(missing_docs)]

#![warn(noop_method_call)]

#![warn(unreachable_pub)]

#![warn(clippy::all)]

#![deny(clippy::await_holding_lock)]

#![deny(clippy::cargo_common_metadata)]

#![deny(clippy::cast_lossless)]

#![deny(clippy::checked_conversions)]

#![allow(clippy::cognitive_complexity)] // See arti#2556

#![deny(clippy::debug_assert_with_mut_call)]

#![deny(clippy::exhaustive_enums)]

#![deny(clippy::exhaustive_structs)]

#![deny(clippy::expl_impl_clone_on_copy)]

#![deny(clippy::fallible_impl_from)]

#![deny(clippy::implicit_clone)]

#![deny(clippy::large_stack_arrays)]

#![warn(clippy::manual_ok_or)]

#![deny(clippy::missing_docs_in_private_items)]

#![warn(clippy::needless_borrow)]

#![warn(clippy::needless_pass_by_value)]

#![warn(clippy::option_option)]

#![warn(clippy::or_fun_call)]

#![deny(clippy::print_stderr)]

#![deny(clippy::print_stdout)]

#![warn(clippy::rc_buffer)]

#![deny(clippy::ref_option_ref)]

#![warn(clippy::semicolon_if_nothing_returned)]

#![warn(clippy::trait_duplication_in_bounds)]

#![deny(clippy::unchecked_time_subtraction)]

#![deny(clippy::unnecessary_wraps)]

#![warn(clippy::unseparated_literal_suffix)]

#![deny(clippy::unwrap_used)]

#![deny(clippy::mod_module_files)]

#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness

#![allow(clippy::uninlined_format_args)]

#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945

#![allow(clippy::result_large_err)] // temporary workaround for arti#587

#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best

#![allow(clippy::needless_lifetimes)] // See arti#1765

#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060

#![allow(clippy::collapsible_if)] // See arti#2342

#![deny(clippy::unused_async)]

#![deny(clippy::string_slice)] // See arti#2571

#![allow(recursion_depth_exceeding_limit)] // arti#2715, rust/issues/159228

//! <!-- @@ end lint list maintained by maint/add_warning @@ -->

// TODO #1645 (either remove this, or decide to have it everywhere)

#![cfg_attr(not(all(feature = "full", feature = "experimental")), allow(unused))]

// Glossary:

//     Primary guard

//     Sample

//     confirmed

//     filtered

use derive_deftly::Deftly;

use futures::channel::mpsc;

use itertools::Either;

use serde::{Deserialize, Serialize};

use std::collections::HashMap;

use std::net::SocketAddr;

use std::sync::{Arc, Mutex, Weak};

#[cfg(feature = "bridge-client")]

use tor_error::internal;

use tor_linkspec::{OwnedChanTarget, OwnedCircTarget, RelayId, RelayIdSet};

use tor_netdir::NetDirProvider;

use tor_proto::ClockSkew;

use tor_rtcompat::SpawnExt;

use tor_units::BoundedInt32;

use tracing::{debug, info, instrument, trace, warn};

use web_time_compat::{Duration, Instant, SystemTime};

use tor_config::derive::prelude::*;

use tor_config::{ExplicitOrAuto, impl_standard_builder};

use tor_config::{ReconfigureError, impl_not_auto_value};

use tor_config::{define_list_builder_accessors, define_list_builder_helper};

use tor_netdir::{NetDir, Relay, params::NetParameters};

use tor_persist::{DynStorageHandle, StateMgr};

use tor_rtcompat::Runtime;

#[cfg(feature = "bridge-client")]

pub mod bridge;

mod config;

mod daemon;

mod dirstatus;

mod err;

mod events;

pub mod fallback;

mod filter;

mod guard;

mod ids;

mod pending;

mod sample;

mod skew;

mod util;

#[cfg(feature = "vanguards")]

pub mod vanguards;

#[cfg(not(feature = "bridge-client"))]

#[path = "bridge_disabled.rs"]

pub mod bridge;

#[cfg(any(test, feature = "testing"))]

pub use config::testing::TestConfig;

#[cfg(test)]

use oneshot_fused_workaround as oneshot;

pub use config::GuardMgrConfig;

pub use err::{GuardMgrConfigError, GuardMgrError, PickGuardError};

pub use events::ClockSkewEvents;

pub use filter::GuardFilter;

pub use ids::FirstHopId;

pub use pending::{GuardMonitor, GuardStatus, GuardUsable};

pub use skew::SkewEstimate;

#[cfg(feature = "vanguards")]

pub use vanguards::VanguardMgrError;

use pending::{PendingRequest, RequestId};

use sample::{GuardSet, Universe, UniverseRef};

use crate::ids::{FirstHopIdInner, GuardId};

/// A "guard manager" that selects and remembers a persistent set of

/// guard nodes.

///

/// This is a "handle"; clones of it share state.

#[derive(Clone)]

pub struct GuardMgr<R: Runtime> {

    /// An asynchronous runtime object.

    ///

    /// GuardMgr uses this runtime for timing, timeouts, and spawning

    /// tasks.

    runtime: R,

    /// Internal state for the guard manager.

    inner: Arc<Mutex<GuardMgrInner>>,

}

/// Helper type that holds the data used by a [`GuardMgr`].

///

/// This would just be a [`GuardMgr`], except that it needs to sit inside

/// a `Mutex` and get accessed by daemon tasks.

struct GuardMgrInner {

    /// Last time when marked all of our primary guards as retriable.

    ///

    /// We keep track of this time so that we can rate-limit

    /// these attempts.

    last_primary_retry_time: Instant,

    /// Persistent guard manager state.

    ///

    /// This object remembers one or more persistent set of guards that we can

    /// use, along with their relative priorities and statuses.

    guards: GuardSets,

    /// The current filter that we're using to decide which guards are

    /// supported.

    //

    // TODO: This field is duplicated in the current active [`GuardSet`]; we

    // should fix that.

    filter: GuardFilter,

    /// Configuration values derived from the consensus parameters.

    ///

    /// This is updated whenever the consensus parameters change.

    params: GuardParams,

    /// A mpsc channel, used to tell the task running in

    /// [`daemon::report_status_events`] about a new event to monitor.

    ///

    /// This uses an `UnboundedSender` so that we don't have to await

    /// while sending the message, which in turn allows the GuardMgr

    /// API to be simpler.  The risk, however, is that there's no

    /// backpressure in the event that the task running

    /// [`daemon::report_status_events`] fails to read from this

    /// channel.

    ctrl: mpsc::UnboundedSender<daemon::Msg>,

    /// Information about guards that we've given out, but where we have

    /// not yet heard whether the guard was successful.

    ///

    /// Upon leaning whether the guard was successful, the pending

    /// requests in this map may be either moved to `waiting`, or

    /// discarded.

    ///

    /// There can be multiple pending requests corresponding to the

    /// same guard.

    pending: HashMap<RequestId, PendingRequest>,

    /// A list of pending requests for which we have heard that the

    /// guard was successful, but we have not yet decided whether the

    /// circuit may be used.

    ///

    /// There can be multiple waiting requests corresponding to the

    /// same guard.

    waiting: Vec<PendingRequest>,

    /// A list of fallback directories used to access the directory system

    /// when no other directory information is yet known.

    fallbacks: fallback::FallbackState,

    /// Location in which to store persistent state.

    storage: DynStorageHandle<GuardSets>,

    /// A sender object to publish changes in our estimated clock skew.

    send_skew: postage::watch::Sender<Option<SkewEstimate>>,

    /// A receiver object to hand out to observers who want to know about

    /// changes in our estimated clock skew.

    recv_skew: events::ClockSkewEvents,

    /// A netdir provider that we can use for adding new guards when

    /// insufficient guards are available.

    ///

    /// This has to be an Option so it can be initialized from None: at the

    /// time a GuardMgr is created, there is no NetDirProvider for it to use.

    netdir_provider: Option<Weak<dyn NetDirProvider>>,

    /// A netdir provider that we can use for discovering bridge descriptors.

    ///

    /// This has to be an Option so it can be initialized from None: at the time

    /// a GuardMgr is created, there is no BridgeDescProvider for it to use.

    #[cfg(feature = "bridge-client")]

    bridge_desc_provider: Option<Weak<dyn bridge::BridgeDescProvider>>,

    /// A list of the bridges that we are configured to use, or "None" if we are

    /// not configured to use bridges.

    #[cfg(feature = "bridge-client")]

    configured_bridges: Option<Arc<[bridge::BridgeConfig]>>,

}

/// A selector that tells us which [`GuardSet`] of several is currently in use.

#[derive(Clone, Debug, Default, Eq, PartialEq, Ord, PartialOrd, strum::EnumIter)]

enum GuardSetSelector {

    /// The default guard set is currently in use: that's the one that we use

    /// when we have no filter installed, or the filter permits most of the

    /// guards on the network.

    #[default]

    Default,

    /// A "restrictive" guard set is currently in use: that's the one that we

    /// use when we have a filter that excludes a large fraction of the guards

    /// on the network.

    Restricted,

    /// The "bridges" guard set is currently in use: we are selecting our guards

    /// from among the universe of configured bridges.

    #[cfg(feature = "bridge-client")]

    Bridges,

}

/// Describes the [`Universe`] that a guard sample should take its guards from.

#[derive(Clone, Copy, Debug, Eq, PartialEq)]

enum UniverseType {

    /// Take information from the network directory.

    NetDir,

    /// Take information from the configured bridges.

    #[cfg(feature = "bridge-client")]

    BridgeSet,

}

impl GuardSetSelector {

    /// Return a description of which [`Universe`] this guard sample should take

    /// its guards from.

            #[cfg(feature = "bridge-client")]

        }

}

/// Persistent state for a guard manager, as serialized to disk.

#[derive(Debug, Clone, Default, Serialize, Deserialize)]

struct GuardSets {

    /// Which set of guards is currently in use?

    #[serde(skip)]

    active_set: GuardSetSelector,

    /// The default set of guards to use.

    ///

    /// We use this one when there is no filter, or the filter permits most of the

    /// guards on the network.

    default: GuardSet,

    /// A guard set to use when we have a restrictive filter.

    #[serde(default)]

    restricted: GuardSet,

    /// A guard set sampled from our configured bridges.

    #[serde(default)]

    #[cfg(feature = "bridge-client")]

    bridges: GuardSet,

    /// Unrecognized fields, including (possibly) other guard sets.

    #[serde(flatten)]

    remaining: HashMap<String, tor_persist::JsonValue>,

}

/// The key (filename) we use for storing our persistent guard state in the

/// `StateMgr`.

///

/// We used to store this in a different format in a filename called

/// "default_guards" (before Arti 0.1.0).

const STORAGE_KEY: &str = "guards";

/// A description of which circuits to retire because of a configuration change.

///

/// TODO(nickm): Eventually we will want to add a "Some" here, to support

/// removing only those circuits that correspond to no-longer-usable guards.

#[derive(Clone, Debug, Eq, PartialEq)]

#[must_use]

#[non_exhaustive]

pub enum RetireCircuits {

    /// There's no need to retire any circuits.

    None,

    /// All circuits should be retired.

    All,

}

impl<R: Runtime> GuardMgr<R> {

    /// Create a new "empty" guard manager and launch its background tasks.

    ///

    /// It won't be able to hand out any guards until a [`NetDirProvider`] has

    /// been installed.

    #[instrument(skip_all, level = "trace")]

    {

        // TODO(nickm): We should do something about the old state in

        // `default_guards`.  Probably it would be best to delete it.  We could

        // try to migrate it instead, but that's beyond the stability guarantee

        // that we're getting at this stage of our (pre-0.1) development.

        #[cfg(feature = "bridge-client")]

        {

            // TODO(nickm): This calls `GuardMgrInner::update`. Will we mind doing so before any

            // providers are configured? I think not, but we should make sure.

        }

        {

        }

        {

        }

    /// Install a [`NetDirProvider`] for use by this guard manager.

    ///

    /// It will be used to keep the guards up-to-date with changes from the

    /// network directory, and to find new guards when no NetDir is provided to

    /// select_guard().

    ///

    /// TODO: we should eventually return some kind of a task handle from this

    /// task, even though it is not strictly speaking periodic.

    ///

    /// The guardmgr retains only a `Weak` reference to `provider`,

    /// `install_netdir_provider` downgrades it on entry,

    // TODO add ref to document when https://gitlab.torproject.org/tpo/core/arti/-/issues/624

    // is fixed.  Also, maybe take an owned `Weak` to start with.

    //

    /// # Panics

    ///

    /// Panics if a [`NetDirProvider`] is already installed.

        {

        }

            ))

    /// Configure a new [`bridge::BridgeDescProvider`] for this [`GuardMgr`].

    ///

    /// It will be used to learn about changes in the set of available bridge

    /// descriptors; we'll inform it whenever our desired set of bridge

    /// descriptors changes.

    ///

    /// TODO: Same todo as in `install_netdir_provider` about task handles.

    ///

    /// # Panics

    ///

    /// Panics if a [`bridge::BridgeDescProvider`] is already installed.

    #[cfg(feature = "bridge-client")]

        {

        }

            ))

    /// Flush our current guard state to the state manager, if there

    /// is any unsaved state.

    /// Reload state from the state manager.

    ///

    /// We only call this method if we _don't_ have the lock on the state

    /// files.  If we have the lock, we only want to save.

    #[instrument(level = "trace", skip_all)]

    /// Switch from having an unowned persistent state to having an owned one.

    ///

    /// Requires that we hold the lock on the state files.

    #[instrument(level = "trace", skip_all)]

    /// Return true if `netdir` has enough information to safely become our new netdir.

            // If we aren't using the netdir, this isn't something we want to look at.

    /// Mark every guard as potentially retriable, regardless of how recently we

    /// failed to connect to it.

    /// Configure this guardmgr to use a fixed [`NetDir`] instead of a provider.

    ///

    /// This function is for testing only, and is exclusive with

    /// `install_netdir_provider`.

    ///

    /// # Panics

    ///

    /// Panics if any [`NetDirProvider`] has already been installed.

    #[cfg(any(test, feature = "testing"))]

        use tor_netdir::testprovider::TestNetDirProvider;

    /// Replace the configuration in this `GuardMgr` with `config`.

    #[instrument(level = "trace", skip_all)]

        // Change the set of configured fallbacks.

        // If we are built to use bridges, change the bridge configuration.

        #[cfg(feature = "bridge-client")]

        {

        }

        // If we are built to use bridges, change the bridge configuration.

        #[cfg(not(feature = "bridge-client"))]

        {

            Ok(RetireCircuits::None)

        }

    /// Replace the current [`GuardFilter`] used by this `GuardMgr`.

    // TODO should this be part of the config?

    /// Select a guard for a given [`GuardUsage`].

    ///

    /// On success, we return a [`FirstHop`] object to identify which

    /// guard we have picked, a [`GuardMonitor`] object that the

    /// caller can use to report whether its attempt to use the guard

    /// succeeded or failed, and a [`GuardUsable`] future that the

    /// caller can use to decide whether a circuit built through the

    /// guard is actually safe to use.

    ///

    /// That last point is important: It's okay to build a circuit

    /// through the guard returned by this function, but you can't

    /// actually use it for traffic unless the [`GuardUsable`] future

    /// yields "true".

    #[instrument(skip_all, level = "trace")]

        // (I am not 100% sure that we need to consider_all_retries here, but

        // it should _probably_ not hurt.)

        } else {

        };

        // Note that the network can be down even if all the primary guards

        // are not yet marked as unreachable.  But according to guard-spec we

        // don't want to acknowledge the net as down before that point, since

        // we don't mark all the primary guards as retriable unless

        // we've been forced to non-primary guards.

            } else {

                // TODO: Is this the correct behavior in this case?

            };

        );

        }

    /// Record that _after_ we built a circuit with a guard, something described

    /// in `external_failure` went wrong with it.

    {

                }

            }

        }

    /// Record that _after_ we built a circuit with a guard, some activity

    /// described in `external_activity` was successful with it.

    {

    /// Return a stream of events about our estimated clock skew; these events

    /// are `None` when we don't have enough information to make an estimate,

    /// and `Some(`[`SkewEstimate`]`)` otherwise.

    ///

    /// Note that this stream can be lossy: if the estimate changes more than

    /// one before you read from the stream, you might only get the most recent

    /// update.

    /// Ensure that the message queue is flushed before proceeding to

    /// the next step.  Used for testing.

    #[cfg(test)]

}

/// An activity that can succeed or fail, and whose success or failure can be

/// attributed to a guard.

#[derive(Copy, Clone, Debug, Eq, PartialEq)]

#[non_exhaustive]

pub enum ExternalActivity {

    /// The activity of using the guard as a directory cache.

    DirCache,

}

impl GuardSets {

    /// Return a reference to the currently active set of guards.

    ///

    /// (That's easy enough for now, since there is never more than one set of

    /// guards.  But eventually that will change, as we add support for more

    /// complex filter types, and for bridge relays. Those will use separate

    /// `GuardSet` instances, and this accessor will choose the right one.)

    /// Return the set of guards corresponding to the provided selector.

            #[cfg(feature = "bridge-client")]

        }

    /// Return a mutable reference to the currently active set of guards.

    /// Return a mutable reference to the set of guards corresponding to the

    /// provided selector.

            #[cfg(feature = "bridge-client")]

        }

    /// Update all non-persistent state for the guards in this object with the

    /// state in `other`.

        use strum::IntoEnumIterator;

}

impl GuardMgrInner {

    /// Look up the latest [`NetDir`] (if there is one) from our

    /// [`NetDirProvider`] (if we have one).

    /// Look up the latest [`BridgeDescList`](bridge::BridgeDescList) (if there

    /// is one) from our [`BridgeDescProvider`](bridge::BridgeDescProvider) (if

    /// we have one).

    #[cfg(feature = "bridge-client")]

    /// Run a function that takes `&mut self` and an optional NetDir.

    ///

    /// We try to use the netdir from our [`NetDirProvider`] (if we have one).

    /// Therefore, although its _parameters_ are suitable for every

    /// [`GuardSet`], its _contents_ might not be. For those, call

    /// [`with_opt_universe`](Self::with_opt_universe) instead.

    //

    // This function exists to handle the lifetime mess where sometimes the

    // resulting NetDir will borrow from `netdir`, and sometimes it will borrow

    // from an Arc returned by `self.latest_netdir()`.

    {

        } else {

        }

    /// Return the latest `BridgeSet` based on our `BridgeDescProvider` and our

    /// configured bridges.

    ///

    /// Returns `None` if we are not configured to use bridges.

    #[cfg(feature = "bridge-client")]

    /// Run a function that takes `&mut self` and an optional [`UniverseRef`].

    ///

    /// We try to get a universe from the appropriate source for the current

    /// active guard set.

    {

        // TODO: it might be nice to make `func` take an GuardSet and a set of

        // parameters, so we can't get the active set wrong. Doing that will

        // require a fair amount of refactoring so that the borrow checker is

        // happy, however.

            UniverseType::NetDir => {

                } else {

                }

            }

            #[cfg(feature = "bridge-client")]

        }

    /// Update the status of all guards in the active set, based on the passage

    /// of time, our configuration, and the relevant Universe for our active

    /// set.

    #[instrument(skip_all, level = "trace")]

            // Here we update our parameters from the latest NetDir, and check

            // whether we need to change to a (non)-restrictive GuardSet based

            // on those parameters and our configured filter.

            //

            // This uses a NetDir unconditionally, since we always want to take

            // the network parameters our parameters from the consensus even if

            // the guards themselves are from a BridgeSet.

            // Now we update the set of guards themselves based on the

            // Universe, which is either the latest NetDir, or the latest

            // BridgeSet—depending on what the GuardSet wants.

            );

            #[cfg(feature = "bridge-client")]

            #[cfg(not(feature = "bridge-client"))]

            let _ = now;

    /// Replace our bridge configuration with the one from `new_config`.

    #[cfg(feature = "bridge-client")]

    #[instrument(level = "trace", skip_all)]

            (None, false) => {

                    UniverseType::BridgeSet

                );

            }

                // TODO: Ideally we would try to upgrade, obtaining an exclusive lock,

                // but `StorageHandle` currently lacks a method for that.

            }

                    UniverseType::BridgeSet

                );

            }

        }

        // If we have gotten here, we have changed the set of bridges, changed

        // which set is active, or changed them both.  We need to make sure that

        // our `GuardSet` object is up-to-date with our configuration.

        // We also need to tell the caller that its circuits are no good any

        // more.

        //

        // TODO(nickm): Someday we can do this more judiciously by retuning

        // "Some" in the case where we're still using bridges but our new bridge

        // set contains different elements; see comment on RetireCircuits.

        //

        // TODO(nickm): We could also safely return RetireCircuits::None if we

        // are using bridges, and our new bridge list is a superset of the older

        // one.

    /// Update our parameters, our selection (based on network parameters and

    /// configuration), and make sure the active GuardSet has the right

    /// configuration itself.

    ///

    /// We should call this whenever the NetDir's parameters change, or whenever

    /// our filter changes.  We do not need to call it for new elements arriving

    /// in our Universe, since those do not affect anything here.

    ///

    /// We should also call this whenever a new GuardSet becomes active for any

    /// reason _other_ than just having called this function.

    ///

    /// (This function is only invoked from `update`, which should be called

    /// under the above circumstances.)

        // Set the parameters.  These always come from the NetDir, even if this

        // is a bridge set.

            }

        // Change the filter, if it doesn't match what the guards have.

        //

        // TODO(nickm): We could use a "dirty" flag or something to decide

        // whether we need to call set_filter, if this comparison starts to show

        // up in profiles.

    /// Update the status of every guard in `active_guards`, and expand it as

    /// needed.

    ///

    /// This function doesn't take `&self`, to make sure that we are only

    /// affecting a single `GuardSet`, and to avoid confusing the borrow

    /// checker.

    ///

    /// We should call this whenever the contents of the universe have changed.

    ///

    /// We should also call this whenever a new GuardSet becomes active.

        // Expire guards.  Do that early, in case doing so makes it clear that

        // we need to grab more guards or mark others as primary.

            // TODO: This check here may be completely unnecessary. I inserted

            // it back in 5ac0fcb7ef603e0d14 because I was originally concerned

            // it might be undesirable to list a primary guard as "missing dir

            // info" (and therefore unusable) if we were expecting to get its

            // microdescriptor "very soon."

            //

            // But due to the other check in `netdir_is_sufficient`, we

            // shouldn't be installing a netdir until it has microdescs for all

            // of the (non-bridge) primary guards that it lists. - nickm

                // We are missing the information from a NetDir needed to see

                // whether our primary guards are listed, so we shouldn't update

                // our guard status.

                //

                // We don't want to do this check if we are using bridges, since

                // a missing bridge descriptor is not guaranteed to temporary

                // problem in the same way that a missing microdescriptor is.

                // (When a bridge desc is missing, the bridge could be down or

                // unreachable, and nobody else can help us. But if a microdesc

                // is missing, we just need to find a cache that has it.)

                    n_primary_without_id_info = n,

                    "Not extending guardset, missing information."

                );

        } else {

        };

    /// If using bridges, tell the BridgeDescProvider which descriptors we want.

    /// We need to check this *after* we select our primary guards.

    #[cfg(feature = "bridge-client")]

    /// Replace the active guard state with `new_state`, preserving

    /// non-persistent state for any guards that are retained.

    #[instrument(level = "trace", skip_all)]

    /// Update which guard set is active based on the current filter and the

    /// provided netdir.

    ///

    /// After calling this function, the new guard set's filter may be

    /// out-of-date: be sure to call `set_filter` as appropriate.

        // In general, we'd like to use the restricted set if we're under the

        // threshold, and the default set if we're over the threshold.  But if

        // we're sitting close to the threshold, we want to avoid flapping back

        // and forth, so we only change when we're more than 5% "off" from

        // whatever our current setting is.

        //

        // (See guard-spec section 2 for more information.)

            // If we're using bridges, then we don't switch between the other guard sets based on the filter at all.

            #[cfg(feature = "bridge-client")]

        };

        } else {

        };

                "Guard selection changed; we are now using the {:?} guard set",

            );

                    "The number of guards permitted is smaller than the recommended minimum of {:.0}%.",

                );

    /// Mark all of our primary guards as retriable, if we haven't done

    /// so since long enough before `now`.

    ///

    /// We want to call this function whenever a guard attempt succeeds,

    /// if the internet seemed to be down when the guard attempt was

    /// first launched.

        // We don't actually want to mark our primary guards as

        // retriable more than once per internet_down_timeout: after

        // the first time, we would just be noticing the same "coming

        // back online" event more than once.

                "Successfully reached a guard after a while off the internet; marking all primary guards retriable."

            );

    /// Replace the current GuardFilter with `filter`.

    #[instrument(level = "trace", skip_all)]

    /// Called when the circuit manager reports (via [`GuardMonitor`]) that

    /// a guard succeeded or failed.

    ///

    /// Changes the guard's status as appropriate, and updates the pending

    /// request as needed.

            // If there was a pending request matching this RequestId, great!

            // First, handle the skew report (if any)

                }

                // TODO: We call this whenever we receive an observed clock

                // skew. That's not the perfect timing for two reasons.  First

                // off, it might be too frequent: it does an O(n) calculation,

                // which isn't ideal.  Second, it might be too infrequent: after

                // an hour has passed, a given observation won't be up-to-date

                // any more, and we might want to recalculate the skew

                // accordingly.

                    // If we had gone too long without any net activity when we

                    // gave out this guard, and now we're seeing a circuit

                    // succeed, tell the primary guards that they might be

                    // retriable.

                    // The guard succeeded.  Tell the GuardSet.

                    );

                    // Either tell the request whether the guard is

                    // usable, or schedule it as a "waiting" request.

                    } else {

                        // This is the one case where we can't use the

                        // guard yet.

                    }

                }

            };

        } else {

                "Got a status {:?} for a request {:?} that wasn't pending",

                status, request_id

            );

        }

        // We might need to update the primary guards based on changes in the

        // status of guards above.

        // Some waiting request may just have become ready (usable or

        // not); we need to give them the information they're waiting

        // for.

    /// Helper to implement `GuardMgr::note_external_success()`.

    ///

    /// (This has to be a separate function so that we can borrow params while

    /// we have `mut self` borrowed.)

    {

                }

            }

        }

    /// Return an iterator over all of the clock skew observations we've made

    /// for guards or fallbacks.

    /// Recalculate our estimated clock skew, and publish it to anybody who

    /// cares.