//! Code to represent its single guard node and track its status.

use tor_basic_utils::retry::RetryDelay;

use itertools::Itertools;

use serde::{Deserialize, Serialize};

use std::collections::HashMap;

use std::net::SocketAddr;

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

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

use crate::dirstatus::DirStatus;

use crate::sample::Candidate;

use crate::skew::SkewObservation;

use crate::util::randomize_time;

use crate::{ExternalActivity, GuardSetSelector, GuardUsageKind, sample};

use crate::{GuardParams, GuardRestriction, GuardUsage, ids::GuardId};

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

use safelog::Redactable as _;

use tor_basic_utils::onionperf_types::{OnionperfEvent, OnionperfGuardStatus};

use tor_linkspec::{

    ChanTarget, ChannelMethod, HasAddrs, HasChanMethod, HasRelayIds, PtTarget, RelayIds,

};

use tor_persist::{Futureproof, JsonValue};

/// Tri-state to represent whether a guard is believed to be reachable or not.

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

#[allow(clippy::enum_variant_names)]

pub(crate) enum Reachable {

    /// A guard is believed to be reachable, since we have successfully

    /// used it more recently than we've failed.

    Reachable,

    /// A guard is believed to be unreachable, since recent attempts

    /// to use it have failed, and not enough time has elapsed since then.

    Unreachable,

    /// We have never (during the lifetime of the current guard manager)

    /// tried to connect to this guard.

    #[default]

    Untried,

    /// The last time that we tried to connect to this guard, it failed,

    /// but enough time has elapsed that we think it is worth trying again.

    Retriable,

}

/// The name and version of the crate that first picked a potential

/// guard.

///

/// The C Tor implementation has found it useful to keep this information

/// about guards, to better work around any bugs discovered in the guard

/// implementation.

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

struct CrateId {

    /// The name of the crate that added this guard.

    #[serde(rename = "crate")]

    crate_name: String,

    /// The version of the crate that added this guard.

    version: String,

}

impl CrateId {

    /// Return a new CrateId representing this crate.

}

/// What rule do we use when we're displaying information about a guard?

#[derive(Clone, Default, Debug)]

pub(crate) enum DisplayRule {

    /// The guard is Sensitive; we should display it as "\[scrubbed\]".

    ///

    /// We use this for public relays on the network, since displaying even the

    /// redacted info about them can enough to identify them uniquely within the

    /// NetDir.

    ///

    /// This should not be too much of a hit for UX (we hope), since the user is

    /// not typically expected to work around issues with these guards themself.

    #[default]

    Sensitive,

    /// The guard should be Redacted; we display it as something like "192.x.x.x

    /// $ab...".

    ///

    /// We use this for bridges.

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

    Redacted,

}

/// A single guard node, as held by the guard manager.

///

/// A Guard is a Tor relay that clients use for the first hop of their circuits.

/// It doesn't need to be a relay that's currently on the network (that is, one

/// that we could represent as a [`Relay`](tor_netdir::Relay)): guards might be

/// temporarily unlisted.

///

/// Some fields in guards are persistent; others are reset with every process.

///

/// # Identity

///

/// Every guard has at least one `RelayId`.  A guard may _gain_ identities over

/// time, as we learn more about it, but it should never _lose_ or _change_ its

/// identities of a given type.

///

/// # TODO

///

/// This structure uses [`Instant`] to represent non-persistent points in time,

/// and [`SystemTime`] to represent points in time that need to be persistent.

/// That's possibly undesirable; maybe we should come up with a better solution.

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

pub(crate) struct Guard {

    /// The identity keys for this guard.

    id: GuardId,

    /// The most recently seen addresses for this guard.  If `pt_targets` is

    /// empty, these are the addresses we use for making OR connections to this

    /// guard directly.  If `pt_targets` is nonempty, these are addresses at

    /// which the server is "located" (q.v. [`HasAddrs`]), but not ways to

    /// connect to it.

    orports: Vec<SocketAddr>,

    /// Any `PtTarget` instances that we know about for connecting to this guard

    /// over a pluggable transport.

    ///

    /// If this is empty, then this guard only supports direct connections, at

    /// the locations in `orports`.

    ///

    /// (Currently, this is always empty, or a singleton.  If we find more than

    /// one, we only look at the first. It is a vector only for forward

    /// compatibility.)

    //

    // TODO: We may want to replace pt_targets and orports with a new structure;

    // maybe a PtAddress and a list of SocketAddr.  But we'll keep them like

    // this for now to keep backward compatibility.

    #[serde(default, skip_serializing_if = "Vec::is_empty")]

    pt_targets: Vec<PtTarget>,

    /// When, approximately, did we first add this guard to our sample?

    #[serde(with = "humantime_serde")]

    added_at: SystemTime,

    /// What version of this crate added this guard to our sample?

    added_by: Option<CrateId>,

    /// If present, this guard is permanently disabled, and this

    /// object tells us why.

    #[serde(default)]

    disabled: Option<Futureproof<GuardDisabled>>,

    /// When, approximately, did we first successfully use this guard?

    ///

    /// (We call a guard "confirmed" if we have successfully used it at

    /// least once.)

    #[serde(with = "humantime_serde")]

    confirmed_at: Option<SystemTime>,

    /// If this guard is not listed in the current-consensus, this is the

    /// `valid_after` date of the oldest consensus in which it was not listed.

    ///

    /// A guard counts as "unlisted" if it is absent, unusable, or

    /// doesn't have the Guard flag.

    #[serde(with = "humantime_serde")]

    unlisted_since: Option<SystemTime>,

    /// True if this guard is listed in the latest consensus, but we don't

    /// have a microdescriptor for it.

    #[serde(skip)]

    dir_info_missing: bool,

    /// When did we last give out this guard in response to a request?

    #[serde(skip)]

    last_tried_to_connect_at: Option<Instant>,

    /// If this guard is currently Unreachable, when should we next

    /// retry it?

    ///

    /// (Retrying a guard involves clearing this field, and setting

    /// `reachable`)

    #[serde(skip)]

    retry_at: Option<Instant>, // derived from retry_schedule.

    /// Schedule use to determine when we can next attempt to connect to this

    /// guard.

    #[serde(skip)]

    retry_schedule: Option<RetryDelay>,

    /// Current reachability status for this guard.

    #[serde(skip)]

    reachable: Reachable,

    /// If true, then the last time we saw a relay entry for this

    /// guard, it seemed like a valid directory cache.

    #[serde(skip)]

    is_dir_cache: bool,

    /// Status for this guard, when used as a directory cache.

    ///

    /// (This is separate from `Reachable` and `retry_schedule`, since being

    /// usable for circuit construction does not necessarily mean that the guard

    /// will have good, timely cache information.  If it were not separate, then

    /// circuit success would clear directory failures.)

    #[serde(skip, default = "guard_dirstatus")]

    dir_status: DirStatus,

    /// If true, we have given this guard out for an exploratory circuit,

    /// and that exploratory circuit is still pending.

    ///

    /// A circuit is "exploratory" if we launched it on a non-primary guard.

    // TODO: Maybe this should be an integer that counts a number of such

    // circuits?

    #[serde(skip)]

    exploratory_circ_pending: bool,

    /// A count of all the circuit statuses we've seen on this guard.

    ///

    /// Used to implement a lightweight version of path-bias detection.

    #[serde(skip)]

    circ_history: CircHistory,

    /// True if we have warned about this guard behaving suspiciously.

    #[serde(skip)]

    suspicious_behavior_warned: bool,

    /// Latest clock skew (if any) we have observed from this guard.

    #[serde(skip)]

    clock_skew: Option<SkewObservation>,

    /// How should we display information about this guard?

    #[serde(skip)]

    sensitivity: DisplayRule,

    /// Fields from the state file that was used to make this `Guard` that

    /// this version of Arti doesn't understand.

    #[serde(flatten)]

    unknown_fields: HashMap<String, JsonValue>,

}

/// Lower bound for delay after get a failure using a guard as a directory

/// cache.

const GUARD_DIR_RETRY_FLOOR: Duration = Duration::from_secs(60);

/// Return a DirStatus entry for a guard.

/// Wrapper to declare whether a given successful use of a guard is the

/// _first_ successful use of the guard.

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

pub(crate) enum NewlyConfirmed {

    /// This was the first successful use of a guard.

    Yes,

    /// This guard has been used successfully before.

    No,

}

impl Guard {

    /// Create a new unused [`Guard`] from a [`Candidate`].

        let Candidate {

            ..

    /// Create a new unused [`Guard`] from a [`ChanTarget`].

    ///

    /// This function doesn't check whether the provided relay is a

    /// suitable guard node or not: that's up to the caller to decide.

    {

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

        };

        )

    /// Return a new, manually constructed [`Guard`].

    /// Return the identity of this Guard.

    /// Return the reachability status for this guard.

    /// Return the next time at which this guard will be retriable for a given

    /// usage.

    ///

    /// (Return None if we think this guard might be reachable right now.)

        }

    /// Return true if this guard is usable and working according to our latest

    /// configuration and directory information, and hasn't been turned off for

    /// some other reason.

    /// Return true if this guard is ready (with respect to any timeouts) for

    /// the given `usage` at `now`.

        }

    /// Copy all _non-persistent_ status from `other` to self.

    ///

    /// We do this when we were not the owner of our persistent state, and we

    /// have just reloaded it (as `self`), but we have some ephemeral knowledge

    /// about this guard (as `other`).

    ///

    /// You should not invent new uses for this function; instead we should come

    /// up with alternatives.

    ///

    /// # Panics

    ///

    /// Panics if the identities in `self` are not exactly the same as the

    /// identities in `other`.

        // It is not safe to copy failure information unless these identities

        // are a superset of those in `other`; but it is not safe to copy success

        // information unless these identities are a subset of those in `other`.

        //

        // To simplify matters, we just insist that the identities have to be the same.

    /// Change the reachability status for this guard.

        use Reachable as R;

            // High-level logs, if change is interesting to user.

                        "Could not connect to guard {}. Retrying in {}.",

                        self,

                    ),

                        "Could not connect to guard {}. Next retry time unknown.",

                        self

                    ),

                },

            }

            //

    /// Return true if at least one exploratory circuit is pending to this

    /// guard.

    ///

    /// A circuit is "exploratory" if launched on a non-primary guard.

    ///

    /// # TODO

    ///

    /// The "exploratory" definition doesn't quite match up with the behavior

    /// in the spec, but it is what Tor does.

    /// Note that an exploratory circuit is pending (if `pending` is true),

    /// or not pending (if `pending` is false.

    /// Possibly mark this guard as retriable, if it has been down for

    /// long enough.

    ///

    /// Specifically, if the guard is to be Unreachable, and our last attempt

    /// to connect to it is far enough in the past from `now`, we change its

    /// status to Unknown.

    /// If this guard is marked Unreachable, clear its unreachability status

    /// and mark it as Retriable.

    /// Return true if this guard obeys all of the given restrictions.

    /// Return true if this guard obeys a single restriction.

            }

        }

    /// Return true if this guard is suitable to use for the provided `usage`.

            GuardUsageKind::OneHopDirectory => {

            }

            GuardUsageKind::Data => {

                // We need a "definitely listed" guard to build a multihop

                // circuit.

            }

        }

    /// Check whether this guard is listed in the provided [`sample::Universe`].

    ///

    /// Returns `Some(true)` if it is definitely listed, and `Some(false)` if it

    /// is definitely not listed.  A `None` return indicates that we need to

    /// download more directory information about this guard before we can be

    /// certain whether this guard is listed or not.

    /// Change this guard's status based on a newly received or newly updated

    /// [`sample::Universe`].

    ///

    /// A guard may become "listed" or "unlisted": a listed guard is one that

    /// appears in the consensus with the Guard flag.

    ///

    /// A guard may acquire additional identities if we learned them from the

    /// guard, either directly or via an authenticated directory document.

    ///

    /// Additionally, a guard's `orports` or `pt_targets` may change, if the

    /// `universe` lists a new address for the relay.

        // This is a tricky check, since if we're missing directory information

        // for the guard, we won't know its full set of identities.

        use sample::CandidateStatus::*;

            Present(Candidate {

            }) => {

                // Update address information.

                // Update Pt information.

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

                };

                // Check whether we can currently use it as a directory cache.

                // Update our IDs: the Relay will have strictly more.

            }

            Uncertain => {

                // We can't tell if this is listed without more directory information.

            }

        };

    /// Mark this guard as currently listed in the directory.

    /// Mark this guard as having been unlisted since `now`, if it is not

    /// already so marked.

    /// Return true if we should remove this guard from the current guard

    /// sample.

    ///

    /// Guards may be ready for removal because they have been

    /// confirmed too long ago, if they have been sampled too long ago

    /// (if they are not confirmed), or if they have been unlisted for

    /// too long.

        /// Helper: Return true if `t2` is after `t1` by at least `d`.

            } else {

            }

            // We never forget a guard that we've disabled: we've disabled

            // it for a reason.

    /// Record that a failure has happened for this guard.

    ///

    /// If `is_primary` is true, this is a primary guard (q.v.).

        // TODO-SPEC: Document this behavior in guard-spec.

    /// Note that we have launch an attempted use of this guard.

    ///

    /// We use this time to decide when to retry failing guards, and

    /// to see if the guard has been "pending" for a long time.

    /// Return true if this guard has an exploratory circuit pending and

    /// if the most recent attempt to connect to it is after `when`.

    ///

    /// See [`Self::exploratory_circ_pending`].

    /// Note that a guard has been used successfully.

    ///

    /// Updates that guard's status to reachable, clears any failing status

    /// information for it, and decides whether the guard is newly confirmed.

    ///

    /// If the guard is newly confirmed, the caller must add it to the

    /// list of confirmed guards.

    #[must_use = "You need to check whether a succeeding guard is confirmed."]

            // TODO-SPEC: The "max" above isn't specified by guard-spec,

            // but I think it's wise.

        } else {

        }

    /// Record that an external operation has succeeded on this guard.

        }

    /// Record that an external operation has failed on this guard.

        }

    /// Note that a circuit through this guard died in a way that we couldn't

    /// necessarily attribute to the guard.

            // TODO: These should not be hardwired.

            /// If this fraction of circs are suspicious, we should disable

            /// the guard.

            ///

            /// (We may lower this in the future, but see discussion in arti#2752

            /// and analysis in proposal 344.  It's currently set to 2.0 while we

            /// wait to get more network simulation and testing; 2.0 is impossible,

            /// since the ratio will be in range `0.0..=1.0`.)

            ///

            /// (Choosing `DISABLE_THRESHOLD = 1.0` would have the same effect,

            /// since we compare `ratio > DISABLE_THRESHOLD`, but using 2.0 makes it more

            /// clear that we will never disable a guard.)

            const DISABLE_THRESHOLD: f64 = 2.0;

            /// If this fraction of circuits are suspicious, we should

            /// warn.

            ///

            /// (This value is deliberately _lower_ than recommended on arti#2752,

            /// under the theory that warnings don't hurt anybody.  If we start to see

            /// excessive warnings, we should investigate.)

            ///

            /// Generally speaking, we would expect an adversary who controls fraction

            /// X of the network to succeed in a path bias attack with probability X^2.

            /// Therefore, if we set this value to 1.0-X^2, we should catch about half

            /// of the attempts by such an attacker to mount a path-bias attack.)

            const WARN_THRESHOLD: f64 = 0.91;

    /// Return a [`FirstHop`](crate::FirstHop) object to represent this guard.

    /// Record that a given fallback has told us about clock skew.

    /// Return the most recent clock skew observation for this guard, if we have

    /// made one.

    /// Testing only: Return true if this guard was ever contacted successfully.

    #[cfg(test)]

}

impl tor_linkspec::HasAddrs for Guard {

}

impl tor_linkspec::HasRelayIds for Guard {

}

impl tor_linkspec::HasChanMethod for Guard {

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

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

            [_first, ..] => ChannelMethod::Direct(vec![]), // can't connect to this; no pt support.

        }

}

impl tor_linkspec::ChanTarget for Guard {}

impl std::fmt::Display for Guard {

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

        }

}

/// A reason for permanently disabling a guard.

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

#[serde(tag = "type")]

enum GuardDisabled {

    /// Too many attempts to use this guard failed for indeterminate reasons.

    TooManyIndeterminateFailures {

        /// Observed count of status reports about this guard.

        history: CircHistory,

        /// Observed fraction of indeterminate status reports.

        failure_ratio: f64,

        /// Threshold that was exceeded.

        threshold_ratio: f64,

    },

}

/// Return a new RetryDelay tracker for a guard.

///

/// `is_primary should be true if the guard is primary.

    } else {

    };

/// The recent history of circuit activity on this guard.

///

/// We keep this information so that we can tell if too many circuits are

/// winding up in "indeterminate" status.

///

/// # What's this for?

///

/// Recall that an "indeterminate" circuit failure is one that might

/// or might not be the guard's fault.  For example, if the second hop

/// of the circuit fails, we can't tell whether to blame the guard,

/// the second hop, or the internet between them.

///

/// But we don't want to allow an unbounded number of indeterminate

/// failures: if we did, it would allow a malicious guard to simply

/// reject any circuit whose second hop it didn't like, and thereby

/// filter the client's paths down to a hostile subset.

///

/// So as a workaround, and to discourage this kind of behavior, we

/// track the fraction of indeterminate circuits, and disable any guard

/// where the fraction is too high.

//

// TODO: We may eventually want to make this structure persistent.  If we

// do, however, we'll need a way to make ancient history expire.  We might

// want that anyway, to make attacks harder.

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

pub(crate) struct CircHistory {

    /// How many times have we seen this guard succeed?

    n_successes: u32,

    /// How many times have we seen this guard fail?

    #[allow(dead_code)] // not actually used yet.

    n_failures: u32,

    /// How many times has this guard given us indeterminate results?

    n_indeterminate: u32,

}

impl CircHistory {

    /// If we have seen enough, return the fraction of circuits that have

    /// "died under mysterious circumstances".

        // TODO: This should probably not be hardwired

        /// Don't try to give a ratio unless we've seen this many observations.

        const MIN_OBSERVATIONS: u32 = 100;

}

#[cfg(test)]

mod test {

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

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

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

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

    use super::*;

    use crate::ids::FirstHopId;

    use tor_linkspec::{HasRelayIds, RelayId};

    use tor_llcrypto::pk::ed25519::Ed25519Identity;

    use web_time_compat::SystemTimeExt;

    #[test]

    fn crate_id() {

        let id = CrateId::this_crate().unwrap();

        assert_eq!(&id.crate_name, "tor-guardmgr");

        assert_eq!(Some(id.version.as_ref()), option_env!("CARGO_PKG_VERSION"));

    }

    fn basic_id() -> GuardId {

        GuardId::new([13; 32].into(), [37; 20].into())

    }

    fn basic_guard() -> Guard {

        let id = basic_id();

        let ports = vec!["127.0.0.7:7777".parse().unwrap()];

        let added = SystemTime::get();

        Guard::new(id, ports, None, added)

    }

    #[test]

    fn simple_accessors() {

        fn ed(id: [u8; 32]) -> RelayId {

            RelayId::Ed25519(id.into())

        }

        let id = basic_id();

        let g = basic_guard();

        assert_eq!(g.guard_id(), &id);

        assert!(g.same_relay_ids(&FirstHopId::in_sample(GuardSetSelector::Default, id)));

        assert_eq!(

            g.addrs().collect_vec(),

            &["127.0.0.7:7777".parse().unwrap()]

        );

        assert_eq!(g.reachable(), Reachable::Untried);

        assert_eq!(g.reachable(), Reachable::default());

        use crate::GuardUsageBuilder;

        let mut usage1 = GuardUsageBuilder::new();

        usage1

            .restrictions()

            .push(GuardRestriction::AvoidId(ed([22; 32])));

        let usage1 = usage1.build().unwrap();

        let mut usage2 = GuardUsageBuilder::new();

        usage2

            .restrictions()

            .push(GuardRestriction::AvoidId(ed([13; 32])));

        let usage2 = usage2.build().unwrap();

        let usage3 = GuardUsage::default();

        let mut usage4 = GuardUsageBuilder::new();

        usage4

            .restrictions()

            .push(GuardRestriction::AvoidId(ed([22; 32])));

        usage4

            .restrictions()

            .push(GuardRestriction::AvoidId(ed([13; 32])));

        let usage4 = usage4.build().unwrap();

        let mut usage5 = GuardUsageBuilder::new();

        usage5.restrictions().push(GuardRestriction::AvoidAllIds(

            vec![ed([22; 32]), ed([13; 32])].into_iter().collect(),

        ));

        let usage5 = usage5.build().unwrap();

        let mut usage6 = GuardUsageBuilder::new();

        usage6.restrictions().push(GuardRestriction::AvoidAllIds(

            vec![ed([99; 32]), ed([100; 32])].into_iter().collect(),

        ));

        let usage6 = usage6.build().unwrap();

        assert!(g.conforms_to_usage(&usage1));

        assert!(!g.conforms_to_usage(&usage2));

        assert!(g.conforms_to_usage(&usage3));

        assert!(!g.conforms_to_usage(&usage4));

        assert!(!g.conforms_to_usage(&usage5));

        assert!(g.conforms_to_usage(&usage6));

    }

    #[allow(clippy::redundant_clone)]

    #[test]

    fn trickier_usages() {

        let g = basic_guard();

        use crate::{GuardUsageBuilder, GuardUsageKind};

        let data_usage = GuardUsageBuilder::new()

            .kind(GuardUsageKind::Data)

            .build()

            .unwrap();

        let dir_usage = GuardUsageBuilder::new()

            .kind(GuardUsageKind::OneHopDirectory)

            .build()

            .unwrap();

        assert!(g.conforms_to_usage(&data_usage));

        assert!(g.conforms_to_usage(&dir_usage));

        let mut g2 = g.clone();

        g2.dir_info_missing = true;

        assert!(!g2.conforms_to_usage(&data_usage));

        assert!(g2.conforms_to_usage(&dir_usage));

        let mut g3 = g.clone();

        g3.is_dir_cache = false;

        assert!(g3.conforms_to_usage(&data_usage));

        assert!(!g3.conforms_to_usage(&dir_usage));

    }

    #[test]

    fn record_attempt() {

        let t1 = Instant::get() - Duration::from_secs(10);

        let t2 = Instant::get() - Duration::from_secs(5);

        let t3 = Instant::get();

        let mut g = basic_guard();

        assert!(g.last_tried_to_connect_at.is_none());

        g.record_attempt(t1);

        assert_eq!(g.last_tried_to_connect_at, Some(t1));

        g.record_attempt(t3);

        assert_eq!(g.last_tried_to_connect_at, Some(t3));

        g.record_attempt(t2);

        assert_eq!(g.last_tried_to_connect_at, Some(t3));

    }

    #[test]

    fn record_failure() {

        let t1 = Instant::get() - Duration::from_secs(10);

        let t2 = Instant::get();

        let mut g = basic_guard();

        g.record_failure(t1, true);

        assert!(g.retry_schedule.is_some());

        assert_eq!(g.reachable(), Reachable::Unreachable);

        let retry1 = g.retry_at.unwrap();

        assert_eq!(retry1, t1 + Duration::from_secs(30));

        g.record_failure(t2, true);

        let retry2 = g.retry_at.unwrap();

        assert!(retry2 >= t2 + Duration::from_secs(30));

        assert!(retry2 <= t2 + Duration::from_secs(200));

    }

    #[test]

    fn record_success() {

        let t1 = Instant::get() - Duration::from_secs(10);

        // has to be in the future, since the guard's "added_at" time is based on now.

        let now = SystemTime::get();

        let t2 = now + Duration::from_secs(300 * 86400);

        let t3 = Instant::get() + Duration::from_secs(310 * 86400);

        let t4 = now + Duration::from_secs(320 * 86400);

        let mut g = basic_guard();

        g.record_failure(t1, true);

        assert_eq!(g.reachable(), Reachable::Unreachable);

        let conf = g.record_success(t2, &GuardParams::default());

        assert_eq!(g.reachable(), Reachable::Reachable);

        assert_eq!(conf, NewlyConfirmed::Yes);

        assert!(g.retry_at.is_none());

        assert!(g.confirmed_at.unwrap() <= t2);

        assert!(g.confirmed_at.unwrap() >= t2 - Duration::from_secs(12 * 86400));

        let confirmed_at_orig = g.confirmed_at;

        g.record_failure(t3, true);

        assert_eq!(g.reachable(), Reachable::Unreachable);

        let conf = g.record_success(t4, &GuardParams::default());

        assert_eq!(conf, NewlyConfirmed::No);

        assert_eq!(g.reachable(), Reachable::Reachable);

        assert!(g.retry_at.is_none());

        assert_eq!(g.confirmed_at, confirmed_at_orig);

    }

    #[test]

    fn retry() {

        let t1 = Instant::get();

        let mut g = basic_guard();

        g.record_failure(t1, true);

        assert!(g.retry_at.is_some());

        assert_eq!(g.reachable(), Reachable::Unreachable);

        // Not yet retriable.

        g.consider_retry(t1);

        assert!(g.retry_at.is_some());

        assert_eq!(g.reachable(), Reachable::Unreachable);

        // Not retriable right before the retry time.

        g.consider_retry(g.retry_at.unwrap() - Duration::from_secs(1));

        assert!(g.retry_at.is_some());

        assert_eq!(g.reachable(), Reachable::Unreachable);

        // Retriable right after the retry time.

        g.consider_retry(g.retry_at.unwrap() + Duration::from_secs(1));

        assert!(g.retry_at.is_none());

        assert_eq!(g.reachable(), Reachable::Retriable);

    }

    #[test]

    fn expiration() {

        const DAY: Duration = Duration::from_secs(24 * 60 * 60);

        let params = GuardParams::default();

        let now = SystemTime::get();

        let g = basic_guard();

        assert!(!g.is_expired(&params, now));

        assert!(!g.is_expired(&params, now + 10 * DAY));

        assert!(!g.is_expired(&params, now + 25 * DAY));

        assert!(!g.is_expired(&params, now + 70 * DAY));

        assert!(g.is_expired(&params, now + 200 * DAY)); // lifetime_unconfirmed.

        let mut g = basic_guard();

        let _ = g.record_success(now, &params);

        assert!(!g.is_expired(&params, now));

        assert!(!g.is_expired(&params, now + 10 * DAY));

        assert!(!g.is_expired(&params, now + 25 * DAY));

        assert!(g.is_expired(&params, now + 70 * DAY)); // lifetime_confirmed.

        let mut g = basic_guard();

        g.mark_unlisted(now);

        assert!(!g.is_expired(&params, now));

        assert!(!g.is_expired(&params, now + 10 * DAY));

        assert!(g.is_expired(&params, now + 25 * DAY)); // lifetime_unlisted

    }

    #[test]

    fn netdir_integration() {

        use tor_netdir::testnet;

        let netdir = testnet::construct_netdir().unwrap_if_sufficient().unwrap();

        let params = GuardParams::default();

        let now = SystemTime::get();

        // Construct a guard from a relay from the netdir.

        let relay22 = netdir.by_id(&Ed25519Identity::from([22; 32])).unwrap();

        let guard22 = Guard::from_chan_target(&relay22, now, &params);

        assert!(guard22.same_relay_ids(&relay22));

        assert!(Some(guard22.added_at) <= Some(now));

        // Can we still get the relay back?

        let id = FirstHopId::in_sample(GuardSetSelector::Default, guard22.id);

        let r = id.get_relay(&netdir).unwrap();

        assert!(r.same_relay_ids(&relay22));

        // Now try a guard that isn't in the netdir.

        let guard255 = Guard::new(

            GuardId::new([255; 32].into(), [255; 20].into()),

            vec![],

            None,

            now,

        );

        let id = FirstHopId::in_sample(GuardSetSelector::Default, guard255.id);

        assert!(id.get_relay(&netdir).is_none());

    }

    #[test]

    fn update_from_netdir() {

        use tor_netdir::testnet;

        let netdir = testnet::construct_netdir().unwrap_if_sufficient().unwrap();

        // Same as above but omit [22]

        let netdir2 = testnet::construct_custom_netdir(|idx, node, _| {

            if idx == 22 {

                node.omit_rs = true;

            }

        })

        .unwrap()

        .unwrap_if_sufficient()

        .unwrap();

        // Same as above but omit [22] as well as MD for [23].

        let netdir3 = testnet::construct_custom_netdir(|idx, node, _| {

            if idx == 22 {

                node.omit_rs = true;

            } else if idx == 23 {

                node.omit_md = true;

            }

        })

        .unwrap()

        .unwrap_if_sufficient()

        .unwrap();

        //let params = GuardParams::default();

        let now = SystemTime::get();

        // Try a guard that isn't in the netdir at all.

        let mut guard255 = Guard::new(

            GuardId::new([255; 32].into(), [255; 20].into()),

            vec!["8.8.8.8:53".parse().unwrap()],

            None,

            now,

        );

        assert_eq!(guard255.unlisted_since, None);

        assert_eq!(guard255.listed_in(&netdir), Some(false));

        guard255.update_from_universe(&netdir);

        assert_eq!(

            guard255.unlisted_since,

            Some(netdir.lifetime().valid_after())

        );

        assert!(!guard255.orports.is_empty());

        // Try a guard that is in netdir, but not netdir2.

        let mut guard22 = Guard::new(

            GuardId::new([22; 32].into(), [22; 20].into()),

            vec![],

            None,

            now,

        );

        let id22: FirstHopId = FirstHopId::in_sample(GuardSetSelector::Default, guard22.id.clone());

        let relay22 = id22.get_relay(&netdir).unwrap();

        assert_eq!(guard22.listed_in(&netdir), Some(true));

        guard22.update_from_universe(&netdir);

        assert_eq!(guard22.unlisted_since, None); // It's listed.

        assert_eq!(guard22.orports, relay22.addrs().collect_vec()); // Addrs are set.

        assert_eq!(guard22.listed_in(&netdir2), Some(false));

        guard22.update_from_universe(&netdir2);

        assert_eq!(

            guard22.unlisted_since,

            Some(netdir2.lifetime().valid_after())

        );

        assert_eq!(guard22.orports, relay22.addrs().collect_vec()); // Addrs still set.

        assert!(!guard22.dir_info_missing);

        // Now see what happens for a guard that's in the consensus, but missing an MD.

        let mut guard23 = Guard::new(

            GuardId::new([23; 32].into(), [23; 20].into()),

            vec![],

            None,

            now,

        );

        assert_eq!(guard23.listed_in(&netdir2), Some(true));

        assert_eq!(guard23.listed_in(&netdir3), None);

        guard23.update_from_universe(&netdir3);

        assert!(guard23.dir_info_missing);

        assert!(guard23.is_dir_cache);

    }

    #[test]

    fn pending() {

        let mut g = basic_guard();

        let t1 = Instant::get();

        let t2 = t1 + Duration::from_secs(100);

        let t3 = t1 + Duration::from_secs(200);

        assert!(!g.exploratory_attempt_after(t1));

        assert!(!g.exploratory_circ_pending());

        g.note_exploratory_circ(true);

        g.record_attempt(t2);

        assert!(g.exploratory_circ_pending());

        assert!(g.exploratory_attempt_after(t1));

        assert!(!g.exploratory_attempt_after(t3));

        g.note_exploratory_circ(false);

        assert!(!g.exploratory_circ_pending());

        assert!(!g.exploratory_attempt_after(t1));

        assert!(!g.exploratory_attempt_after(t3));

    }

    #[test]

    fn circ_history() {

        let mut h = CircHistory {

            n_successes: 3,

            n_failures: 4,

            n_indeterminate: 3,