#![cfg_attr(docsrs, feature(doc_auto_cfg, 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)]

#![warn(clippy::cognitive_complexity)]

#![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)]

#![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_duration_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

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

pub mod details;

mod err;

#[cfg(feature = "hs-common")]

mod hsdir_params;

#[cfg(feature = "hs-common")]

mod hsdir_ring;

pub mod params;

mod weight;

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

pub mod testnet;

#[cfg(feature = "testing")]

pub mod testprovider;

use async_trait::async_trait;

#[cfg(feature = "hs-service")]

use itertools::chain;

use static_assertions::const_assert;

use tor_error::warn_report;

use tor_linkspec::{

    ChanTarget, DirectChanMethodsHelper, HasAddrs, HasRelayIds, RelayIdRef, RelayIdType,

};

use tor_llcrypto as ll;

use tor_llcrypto::pk::{ed25519::Ed25519Identity, rsa::RsaIdentity};

use tor_netdoc::doc::microdesc::{MdDigest, Microdesc};

use tor_netdoc::doc::netstatus::{self, MdConsensus, MdConsensusRouterStatus, RouterStatus};

#[cfg(feature = "hs-common")]

use {hsdir_ring::HsDirRing, std::iter};

use derive_more::{From, Into};

use futures::{StreamExt, stream::BoxStream};

use num_enum::{IntoPrimitive, TryFromPrimitive};

use rand::seq::{IndexedRandom as _, SliceRandom as _, WeightError};

use serde::Deserialize;

use std::collections::HashMap;

use std::net::IpAddr;

use std::ops::Deref;

use std::sync::Arc;

use std::time::SystemTime;

use strum::{EnumCount, EnumIter};

use tracing::warn;

use typed_index_collections::{TiSlice, TiVec};

#[cfg(feature = "hs-common")]

use {

    itertools::Itertools,

    std::collections::HashSet,

    tor_error::{Bug, internal},

    tor_hscrypto::{pk::HsBlindId, time::TimePeriod},

};

pub use err::Error;

pub use weight::WeightRole;

/// A Result using the Error type from the tor-netdir crate

pub type Result<T> = std::result::Result<T, Error>;

#[cfg(feature = "hs-common")]

pub use err::OnionDirLookupError;

use params::NetParameters;

#[cfg(feature = "geoip")]

use tor_geoip::{CountryCode, GeoipDb, HasCountryCode};

#[cfg(feature = "hs-common")]

#[cfg_attr(docsrs, doc(cfg(feature = "hs-common")))]

pub use hsdir_params::HsDirParams;

/// Index into the consensus relays

///

/// This is an index into the list of relays returned by

/// [`.c_relays()`](ConsensusRelays::c_relays)

/// (on the corresponding consensus or netdir).

///

/// This is just a `usize` inside, but using a newtype prevents getting a relay index

/// confused with other kinds of slice indices or counts.

///

/// If you are in a part of the code which needs to work with multiple consensuses,

/// the typechecking cannot tell if you try to index into the wrong consensus.

#[derive(Debug, From, Into, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]

pub(crate) struct RouterStatusIdx(usize);

/// Extension trait to provide index-type-safe `.c_relays()` method

//

// TODO: Really it would be better to have MdConsensns::relays() return TiSlice,

// but that would be an API break there.

pub(crate) trait ConsensusRelays {

    /// Obtain the list of relays in the consensus

    //

    fn c_relays(&self) -> &TiSlice<RouterStatusIdx, MdConsensusRouterStatus>;

}

impl ConsensusRelays for MdConsensus {

}

impl ConsensusRelays for NetDir {

}

/// Configuration for determining when two relays have addresses "too close" in

/// the network.

///

/// Used by `Relay::low_level_details().in_same_subnet()`.

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

#[serde(deny_unknown_fields)]

pub struct SubnetConfig {

    /// Consider IPv4 nodes in the same /x to be the same family.

    ///

    /// If this value is 0, all nodes with IPv4 addresses will be in the

    /// same family.  If this value is above 32, then no nodes will be

    /// placed im the same family based on their IPv4 addresses.

    subnets_family_v4: u8,

    /// Consider IPv6 nodes in the same /x to be the same family.

    ///

    /// If this value is 0, all nodes with IPv6 addresses will be in the

    /// same family.  If this value is above 128, then no nodes will be

    /// placed im the same family based on their IPv6 addresses.

    subnets_family_v6: u8,

}

impl Default for SubnetConfig {

}

impl SubnetConfig {

    /// Construct a new SubnetConfig from a pair of bit prefix lengths.

    ///

    /// The values are clamped to the appropriate ranges if they are

    /// out-of-bounds.

    /// Construct a new SubnetConfig such that addresses are not in the same

    /// family with anything--not even with themselves.

    /// Return true if the two addresses in the same subnet, according to this

    /// configuration.

            }

            }

        }

    /// Return true if any of the addresses in `a` shares a subnet with any of

    /// the addresses in `b`, according to this configuration.

    /// Return a new subnet configuration that is the union of `self` and

    /// `other`.

    ///

    /// That is, return a subnet configuration that puts all addresses in the

    /// same subnet if and only if at least one of `self` and `other` would put

    /// them in the same subnet.

        use std::cmp::min;

}

/// Configuration for which listed family information to use when deciding

/// whether relays belong to the same family.

///

/// Derived from network parameters.

#[derive(Clone, Copy, Debug)]

pub struct FamilyRules {

    /// If true, we use family information from lists of family members.

    use_family_lists: bool,

    /// If true, we use family information from lists of family IDs and from family certs.

    use_family_ids: bool,

}

impl<'a> From<&'a NetParameters> for FamilyRules {

}

impl FamilyRules {

    /// Return a `FamilyRules` that will use all recognized kinds of family information.

    /// Return a `FamilyRules` that will ignore all family information declared by relays.

    /// Configure this `FamilyRules` to use (or not use) family information from

    /// lists of family members.

    /// Configure this `FamilyRules` to use (or not use) family information from

    /// family IDs and family certs.

    /// Return a `FamilyRules` that will look at every source of information

    /// requested by `self` or by `other`.

        }

}

/// An opaque type representing the weight with which a relay or set of

/// relays will be selected for a given role.

///

/// Most users should ignore this type, and just use pick_relay instead.

#[derive(

    Copy,

    Clone,

    Debug,

    derive_more::Add,

    derive_more::Sum,

    derive_more::AddAssign,

    Eq,

    PartialEq,

    Ord,

    PartialOrd,

)]

pub struct RelayWeight(u64);

impl RelayWeight {

    /// Try to divide this weight by `rhs`.

    ///

    /// Return a ratio on success, or None on division-by-zero.

        } else {

        }

    /// Compute a ratio `frac` of this weight.

    ///

    /// Return None if frac is less than zero, since negative weights

    /// are impossible.

        } else {

        }

}

impl From<u64> for RelayWeight {

}

/// An operation for which we might be requesting a hidden service directory.

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

// TODO: make this pub(crate) once NetDir::hs_dirs is removed

#[non_exhaustive]

pub enum HsDirOp {

    /// Uploading an onion service descriptor.

    #[cfg(feature = "hs-service")]

    Upload,

    /// Downloading an onion service descriptor.

    Download,

}

/// A view of the Tor directory, suitable for use in building circuits.

///

/// Abstractly, a [`NetDir`] is a set of usable public [`Relay`]s, each of which

/// has its own properties, identity, and correct weighted probability for use

/// under different circumstances.

///

/// A [`NetDir`] is constructed by making a [`PartialNetDir`] from a consensus

/// document, and then adding enough microdescriptors to that `PartialNetDir` so

/// that it can be used to build paths. (Thus, if you have a NetDir, it is

/// definitely adequate to build paths.)

///

/// # "Usable" relays

///

/// Many methods on NetDir are defined in terms of <a name="usable">"Usable"</a> relays.  Unless

/// otherwise stated, a relay is "usable" if it is listed in the consensus,

/// if we have full directory information for that relay (including a

/// microdescriptor), and if that relay does not have any flags indicating that

/// we should never use it. (Currently, `NoEdConsensus` is the only such flag.)

///

/// # Limitations

///

/// The current NetDir implementation assumes fairly strongly that every relay

/// has an Ed25519 identity and an RSA identity, that the consensus is indexed

/// by RSA identities, and that the Ed25519 identities are stored in

/// microdescriptors.

///

/// If these assumptions someday change, then we'll have to revise the

/// implementation.

#[derive(Debug, Clone)]

pub struct NetDir {

    /// A microdescriptor consensus that lists the members of the network,

    /// and maps each one to a 'microdescriptor' that has more information

    /// about it

    consensus: Arc<MdConsensus>,

    /// A map from keys to integer values, distributed in the consensus,

    /// and clamped to certain defaults.

    params: NetParameters,

    /// Map from routerstatus index, to that routerstatus's microdescriptor (if we have one.)

    mds: TiVec<RouterStatusIdx, Option<Arc<Microdesc>>>,

    /// Map from SHA256 of _missing_ microdescriptors to the index of their

    /// corresponding routerstatus.

    rsidx_by_missing: HashMap<MdDigest, RouterStatusIdx>,

    /// Map from ed25519 identity to index of the routerstatus.

    ///

    /// Note that we don't know the ed25519 identity of a relay until

    /// we get the microdescriptor for it, so this won't be filled in

    /// until we get the microdescriptors.

    ///

    /// # Implementation note

    ///

    /// For this field, and for `rsidx_by_rsa`,

    /// it might be cool to have references instead.

    /// But that would make this into a self-referential structure,

    /// which isn't possible in safe rust.

    rsidx_by_ed: HashMap<Ed25519Identity, RouterStatusIdx>,

    /// Map from RSA identity to index of the routerstatus.

    ///

    /// This is constructed at the same time as the NetDir object, so it

    /// can be immutable.

    rsidx_by_rsa: Arc<HashMap<RsaIdentity, RouterStatusIdx>>,

    /// Hash ring(s) describing the onion service directory.

    ///

    /// This is empty in a PartialNetDir, and is filled in before the NetDir is

    /// built.

    //

    // TODO hs: It is ugly to have this exist in a partially constructed state

    // in a PartialNetDir.

    // Ideally, a PartialNetDir would contain only an HsDirs<HsDirParams>,

    // or perhaps nothing at all, here.

    #[cfg(feature = "hs-common")]

    hsdir_rings: Arc<HsDirs<HsDirRing>>,

    /// Weight values to apply to a given relay when deciding how frequently

    /// to choose it for a given role.

    weights: weight::WeightSet,

    #[cfg(feature = "geoip")]

    /// Country codes for each router in our consensus.

    ///

    /// This is indexed by the `RouterStatusIdx` (i.e. a router idx of zero has

    /// the country code at position zero in this array).

    country_codes: Vec<Option<CountryCode>>,

}

/// Collection of hidden service directories (or parameters for them)

///

/// In [`NetDir`] this is used to store the actual hash rings.

/// (But, in a NetDir in a [`PartialNetDir`], it contains [`HsDirRing`]s

/// where only the `params` are populated, and the `ring` is empty.)

///

/// This same generic type is used as the return type from

/// [`HsDirParams::compute`](HsDirParams::compute),

/// where it contains the *parameters* for the primary and secondary rings.

#[derive(Debug, Clone)]

#[cfg(feature = "hs-common")]

pub(crate) struct HsDirs<D> {

    /// The current ring

    ///

    /// It corresponds to the time period containing the `valid-after` time in

    /// the consensus. Its SRV is whatever SRV was most current at the time when

    /// that time period began.

    ///

    /// This is the hash ring that we should use whenever we are fetching an

    /// onion service descriptor.

    current: D,

    /// Secondary rings (based on the parameters for the previous and next time periods)

    ///

    /// Onion services upload to positions on these ring as well, based on how

    /// far into the current time period this directory is, so that

    /// not-synchronized clients can still find their descriptor.

    ///

    /// Note that with the current (2023) network parameters, with

    /// `hsdir_interval = SRV lifetime = 24 hours` at most one of these

    /// secondary rings will be active at a time.  We have two here in order

    /// to conform with a more flexible regime in proposal 342.

    //

    // TODO: hs clients never need this; so I've made it not-present for them.

    // But does that risk too much with respect to side channels?

    //

    // TODO: Perhaps we should refactor this so that it is clear that these

    // are immutable?  On the other hand, the documentation for this type

    // declares that it is immutable, so we are likely okay.

    //

    // TODO: this `Vec` is only ever 0,1,2 elements.

    // Maybe it should be an ArrayVec or something.

    #[cfg(feature = "hs-service")]

    secondary: Vec<D>,

}

#[cfg(feature = "hs-common")]

impl<D> HsDirs<D> {

    /// Convert an `HsDirs<D>` to `HsDirs<D2>` by mapping each contained `D`

    /// Iterate over some of the contained hsdirs, according to `secondary`

    ///

    /// The current ring is always included.

    /// Secondary rings are included iff `secondary` and the `hs-service` feature is enabled.

    /// Iterate over all the contained hsdirs

    /// Iterate over the hsdirs relevant for `op`

            #[cfg(feature = "hs-service")]

        })

}

/// An event that a [`NetDirProvider`] can broadcast to indicate that a change in

/// the status of its directory.

#[derive(

)]

#[non_exhaustive]

#[repr(u16)]

pub enum DirEvent {

    /// A new consensus has been received, and has enough information to be

    /// used.

    ///

    /// This event is also broadcast when a new set of consensus parameters is

    /// available, even if that set of parameters comes from a configuration

    /// change rather than from the latest consensus.

    NewConsensus,

    /// New descriptors have been received for the current consensus.

    ///

    /// (This event is _not_ broadcast when receiving new descriptors for a

    /// consensus which is not yet ready to replace the current consensus.)

    NewDescriptors,

    /// We have received updated recommendations and requirements

    /// for which subprotocols we should have to use the network.

    NewProtocolRecommendation,

}

/// The network directory provider is shutting down without giving us the

/// netdir we asked for.

#[derive(Clone, Copy, Debug, thiserror::Error)]

#[error("Network directory provider is shutting down")]

#[non_exhaustive]

pub struct NetdirProviderShutdown;

impl tor_error::HasKind for NetdirProviderShutdown {

}

/// How "timely" must a network directory be?

///

/// This enum is used as an argument when requesting a [`NetDir`] object from

/// [`NetDirProvider`] and other APIs, to specify how recent the information

/// must be in order to be useful.

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

#[allow(clippy::exhaustive_enums)]

pub enum Timeliness {

    /// The network directory must be strictly timely.

    ///

    /// That is, it must be based on a consensus that valid right now, with no

    /// tolerance for skew or consensus problems.

    ///

    /// Avoid using this option if you could use [`Timeliness::Timely`] instead.

    Strict,

    /// The network directory must be roughly timely.

    ///

    /// This is, it must be be based on a consensus that is not _too_ far in the

    /// future, and not _too_ far in the past.

    ///

    /// (The tolerances for "too far" will depend on configuration.)

    ///

    /// This is almost always the option that you want to use.

    Timely,

    /// Any network directory is permissible, regardless of how untimely.

    ///

    /// Avoid using this option if you could use [`Timeliness::Timely`] instead.

    Unchecked,

}

/// An object that can provide [`NetDir`]s, as well as inform consumers when

/// they might have changed.

///

/// It is the responsibility of the implementor of `NetDirProvider`

/// to try to obtain an up-to-date `NetDir`,

/// and continuously to maintain and update it.

///

/// In usual configurations, Arti uses `tor_dirmgr::DirMgr`

/// as its `NetDirProvider`.

#[async_trait]

pub trait NetDirProvider: UpcastArcNetDirProvider + Send + Sync {

    /// Return a network directory that's live according to the provided

    /// `timeliness`.

    fn netdir(&self, timeliness: Timeliness) -> Result<Arc<NetDir>>;

    /// Return a reasonable netdir for general usage.

    ///

    /// This is an alias for

    /// [`NetDirProvider::netdir`]`(`[`Timeliness::Timely`]`)`.

    /// Return a new asynchronous stream that will receive notification

    /// whenever the consensus has changed.

    ///

    /// Multiple events may be batched up into a single item: each time

    /// this stream yields an event, all you can assume is that the event has

    /// occurred at least once.

    fn events(&self) -> BoxStream<'static, DirEvent>;

    /// Return the latest network parameters.

    ///

    /// If we have no directory, return a reasonable set of defaults.

    fn params(&self) -> Arc<dyn AsRef<NetParameters>>;

    /// Get a NetDir from `provider`, waiting until one exists.

    async fn wait_for_netdir(

        &self,

        timeliness: Timeliness,

        loop {

            // We need to retry `self.netdir()` before waiting for any stream events, to

            // avoid deadlock.

            //

            // We ignore all errors here: they can all potentially be fixed by

            // getting a fresh consensus, and they will all get warned about

            // by the NetDirProvider itself.

                None => {

                }

            }

        }

    /// Wait until `provider` lists `target`.

    ///

    /// NOTE: This might potentially wait indefinitely, if `target` is never actually

    /// becomes listed in the directory.  It will exit if the `NetDirProvider` shuts down.

    async fn wait_for_netdir_to_list(

        &self,

        target: &tor_linkspec::RelayIds,

        timeliness: Timeliness,

        loop {

            // See if the desired relay is in the netdir.

            //

            // We do this before waiting for any events, to avoid race conditions.

            {

                // The event stream is closed; the provider has shut down.

        }

    /// Return the latest set of recommended and required protocols, if there is one.

    ///

    /// This may be more recent (or more available) than this provider's associated NetDir.

    fn protocol_statuses(&self) -> Option<(SystemTime, Arc<netstatus::ProtoStatuses>)>;

}

impl<T> NetDirProvider for Arc<T>

where

    T: NetDirProvider,

{

}

/// Helper trait: allows any `Arc<X>` to be upcast to a `Arc<dyn

/// NetDirProvider>` if X is an implementation or supertrait of NetDirProvider.

///

/// This trait exists to work around a limitation in rust: when trait upcasting

/// coercion is stable, this will be unnecessary.

///

/// The Rust tracking issue is <https://github.com/rust-lang/rust/issues/65991>.

pub trait UpcastArcNetDirProvider {

    /// Return a view of this object as an `Arc<dyn NetDirProvider>`

    fn upcast_arc<'a>(self: Arc<Self>) -> Arc<dyn NetDirProvider + 'a>

    where

        Self: 'a;

}

impl<T> UpcastArcNetDirProvider for T

where

    T: NetDirProvider + Sized,

{

}

impl AsRef<NetParameters> for NetDir {

}

/// A partially build NetDir -- it can't be unwrapped until it has

/// enough information to build safe paths.

#[derive(Debug, Clone)]

pub struct PartialNetDir {

    /// The netdir that's under construction.

    netdir: NetDir,

    /// The previous netdir, if we had one

    ///

    /// Used as a cache, so we can reuse information

    #[cfg(feature = "hs-common")]

    prev_netdir: Option<Arc<NetDir>>,

}

/// A view of a relay on the Tor network, suitable for building circuits.

// TODO: This should probably be a more specific struct, with a trait

// that implements it.

#[derive(Clone)]

pub struct Relay<'a> {

    /// A router descriptor for this relay.

    rs: &'a netstatus::MdConsensusRouterStatus,

    /// A microdescriptor for this relay.

    md: &'a Microdesc,

    /// The country code this relay is in, if we know one.

    #[cfg(feature = "geoip")]

    cc: Option<CountryCode>,

}

/// A relay that we haven't checked for validity or usability in

/// routing.

#[derive(Debug)]

pub struct UncheckedRelay<'a> {

    /// A router descriptor for this relay.

    rs: &'a netstatus::MdConsensusRouterStatus,

    /// A microdescriptor for this relay, if there is one.

    md: Option<&'a Microdesc>,

    /// The country code this relay is in, if we know one.

    #[cfg(feature = "geoip")]

    cc: Option<CountryCode>,

}

/// A partial or full network directory that we can download

/// microdescriptors for.

pub trait MdReceiver {

    /// Return an iterator over the digests for all of the microdescriptors

    /// that this netdir is missing.

    fn missing_microdescs(&self) -> Box<dyn Iterator<Item = &MdDigest> + '_>;

    /// Add a microdescriptor to this netdir, if it was wanted.

    ///

    /// Return true if it was indeed wanted.

    fn add_microdesc(&mut self, md: Microdesc) -> bool;

    /// Return the number of missing microdescriptors.

    fn n_missing(&self) -> usize;

}

impl PartialNetDir {

    /// Create a new PartialNetDir with a given consensus, and no

    /// microdescriptors loaded.

    ///

    /// If `replacement_params` is provided, override network parameters from

    /// the consensus with those from `replacement_params`.

    /// Create a new PartialNetDir with GeoIP support.

    ///

    /// This does the same thing as `new()`, except the provided GeoIP database is used to add

    /// country codes to relays.

    #[cfg(feature = "geoip")]

    #[cfg_attr(docsrs, doc(cfg(feature = "geoip")))]

    /// Implementation of the `new()` functions.

        // Now see if the user has any parameters to override.

        // (We have to do this now, or else changes won't be reflected in our

        // weights.)

            }

        // Compute the weights we'll want to use for these relays.

        #[cfg(feature = "geoip")]

        } else {

        };

        #[cfg(feature = "hs-common")]

    /// Return the declared lifetime of this PartialNetDir.

    /// Record a previous netdir, which can be used for reusing cached information

    //

    // Fills in as many missing microdescriptors as possible in this

    // netdir, using the microdescriptors from the previous netdir.

    //

    // With HS enabled, stores the netdir for reuse of relay hash ring index values.

    #[allow(clippy::needless_pass_by_value)] // prev might, or might not, be stored

        #[cfg(feature = "hs-common")]

    /// Compute the hash ring(s) for this NetDir

    #[cfg(feature = "hs-common")]

    /// Return true if this are enough information in this directory

    /// to build multihop paths.

    /// If this directory has enough information to build multihop

    /// circuits, return it.

            #[cfg(feature = "hs-common")]

        } else {

        }

}

impl MdReceiver for PartialNetDir {

}

impl NetDir {

    /// Return the declared lifetime of this NetDir.

    /// Add `md` to this NetDir.

    ///

    /// Return true if we wanted it, and false otherwise.

            // There should never be two approved MDs in the same

            // consensus listing the same ID... but if there is,

            // we'll let the most recent one win.

    /// Construct a (possibly invalid) Relay object from a routerstatus and its

    /// index within the consensus.

    /// Return the value of the hsdir_n_replicas param.

    #[cfg(feature = "hs-common")]

    /// Return the spread parameter for the specified `op`.

    #[cfg(feature = "hs-common")]

            #[cfg(feature = "hs-service")]

        };

    /// Select `spread` hsdir relays for the specified `hsid` from a given `ring`.

    ///

    /// Algorithm:

    ///

    /// for idx in 1..=n_replicas:

    ///       - let H = hsdir_ring::onion_service_index(id, replica, rand,

    ///         period).

    ///       - Find the position of H within hsdir_ring.

    ///       - Take elements from hsdir_ring starting at that position,

    ///         adding them to Dirs until we have added `spread` new elements

    ///         that were not there before.

    #[cfg(feature = "hs-common")]

    /// Replace the overridden parameters in this netdir with `new_replacement`.

    ///

    /// After this function is done, the netdir's parameters will be those in

    /// the consensus, overridden by settings from `new_replacement`.  Any

    /// settings in the old replacement parameters will be discarded.

        }

    /// Return an iterator over all Relay objects, including invalid ones

    /// that we can't use.

    /// Return an iterator over all [usable](NetDir#usable) Relays.

    /// Look up a relay's [`Microdesc`] by its [`RouterStatusIdx`]

    #[cfg_attr(not(feature = "hs-common"), allow(dead_code))]

    /// Return a relay matching a given identity, if we have a

    /// _usable_ relay with that key.

    ///

    /// (Does not return [unusable](NetDir#usable) relays.)

    ///

    ///

    /// Note that a `None` answer is not always permanent: if a microdescriptor

    /// is subsequently added for a relay with this ID, the ID may become usable

    /// even if it was not usable before.

            }

        };

    /// Obtain a `Relay` given a `RouterStatusIdx`

    ///

    /// Differs from `relay_from_rs_and_rsi` as follows:

    ///  * That function expects the caller to already have an `MdConsensusRouterStatus`;

    ///    it checks with `debug_assert` that the relay in the netdir matches.

    ///  * That function panics if the `RouterStatusIdx` is invalid; this one returns `None`.

    ///  * That function returns an `UncheckedRelay`; this one a `Relay`.

    ///

    /// `None` could be returned here, even with a valid `rsi`,

    /// if `rsi` refers to an [unusable](NetDir#usable) relay.

    #[cfg_attr(not(feature = "hs-common"), allow(dead_code))]

    /// Return a relay with the same identities as those in `target`, if one

    /// exists.

    ///

    /// Does not return [unusable](NetDir#usable) relays.

    ///

    /// Note that a negative result from this method is not necessarily permanent:

    /// it may be the case that a relay exists,

    /// but we don't yet have enough information about it to know all of its IDs.

    /// To test whether a relay is *definitely* absent,

    /// use [`by_ids_detailed`](Self::by_ids_detailed)

    /// or [`ids_listed`](Self::ids_listed).

    ///

    /// # Limitations

    ///

    /// This will be very slow if `target` does not have an Ed25519 or RSA

    /// identity.

        // Don't try if there are no identities.

        // Since there is at most one relay with each given ID type,

        // we only need to check the first relay we find.

        } else {

        }

    /// Check whether there is a relay that has at least one identity from

    /// `target`, and which _could_ have every identity from `target`.

    /// If so, return such a relay.

    ///

    /// Return `Ok(None)` if we did not find a relay with any identity from `target`.

    ///

    /// Return `RelayLookupError::Impossible` if we found a relay with at least

    /// one identity from `target`, but that relay's other identities contradict

    /// what we learned from `target`.

    ///

    /// Does not return [unusable](NetDir#usable) relays.

    ///

    /// (This function is only useful if you need to distinguish the

    /// "impossible" case from the "no such relay known" case.)

    ///

    /// # Limitations

    ///

    /// This will be very slow if `target` does not have an Ed25519 or RSA

    /// identity.

    //

    // TODO HS: This function could use a better name.

    //

    // TODO: We could remove the feature restriction here once we think this API is

    // stable.

    #[cfg(feature = "hs-common")]

        // If we have no candidate, return None early.

        };

        // Now we know we have a single candidate.  Make sure that it does not have any

        // identity that does not match the target.

        {

        } else {