Struct tor_netdir::NetDir

pub struct NetDir { /* private fields */ }

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

Abstractly, a NetDir is a set of usable public Relays, 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.)

Implementations

impl NetDir

pub fn lifetime(&self) -> &Lifetime

Return the declared lifetime of this NetDir.

pub fn replace_overridden_parameters(&mut self, new_replacement: &NetParams<i32>)

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.

pub fn all_relays(&self) -> impl Iterator<Item = UncheckedRelay<'_>>

Return an iterator over all Relay objects, including invalid ones that we can’t use.

pub fn relays(&self) -> impl Iterator<Item = Relay<'_>>

Return an iterator over all usable Relays.

pub fn by_id(&self, id: &Ed25519Identity) -> Option<Relay<'_>>

Return a relay matching a given Ed25519 identity, if we have a usable relay with that key.

(Does not return unusable relays.)

Note that if a microdescriptor is subsequently added for a relay with this ID, the ID may become usable.

pub fn by_id_pair(
    &self,
    ed_id: &Ed25519Identity,
    rsa_id: &RsaIdentity
) -> Option<Relay<'_>>

Return a relay matching a given Ed25519 identity and RSA identity, if we have a usable relay with both keys.

(Does not return unusable relays.)

Note that if a microdescriptor is subsequently added for a relay with this ID, the ID may become usable.

pub fn by_chantarget(&self, chan_target: &impl ChanTarget) -> Option<Relay<'_>>

Return the usable relay matching a given ChanTarget’s identities, if any.

(Does not return unusable relays.)

pub fn id_pair_listed(
    &self,
    ed_id: &Ed25519Identity,
    rsa_id: &RsaIdentity
) -> Option<bool>

Return a boolean if this consensus definitely has (or does not have) a relay matching both the given Ed25519 and RSA identity.

If we can’t yet tell for sure, return None.

Once function has returned Some(b), it will always return that value for the same ed_id and rsa_id on this NetDir. A None answer may later become Some(b) if a microdescriptor arrives.

pub fn missing_descriptor_for(&self, rsa_id: &RsaIdentity) -> bool

Return true if we are currently missing a micro descriptor for the given RSA identity.

A descriptor is missing only if it is listed in the consensus, but we don’t have it downloaded.

pub fn by_rsa_id_unchecked(
    &self,
    rsa_id: &RsaIdentity
) -> Option<UncheckedRelay<'_>>

Return a (possibly unusable) relay with a given RSA identity.

pub fn by_rsa_id(&self, rsa_id: &RsaIdentity) -> Option<Relay<'_>>

Return the relay with a given RSA identity, if we have one and it is usable.

pub fn rsa_id_is_listed(&self, rsa_id: &RsaIdentity) -> bool

Return true if rsa_id is listed in this directory, even if it isn’t currently usable.

pub fn params(&self) -> &NetParameters

Return the parameters from the consensus, clamped to the correct ranges, with defaults filled in.

NOTE: that unsupported parameters aren’t returned here; only those values configured in the params module are available.

pub fn pick_relay<'a, R, P>(
    &'a self,
    rng: &mut R,
    role: WeightRole,
    usable: P
) -> Option<Relay<'a>> where
    R: Rng,
    P: FnMut(&Relay<'a>) -> bool, 

Choose a relay at random.

Each relay is chosen with probability proportional to its weight in the role role, and is only selected if the predicate usable returns true for it.

This function returns None if (and only if) there are no relays with nonzero weight where usable returned true.

pub fn pick_n_relays<'a, R, P>(
    &'a self,
    rng: &mut R,
    n: usize,
    role: WeightRole,
    usable: P
) -> Vec<Relay<'a>> where
    R: Rng,
    P: FnMut(&Relay<'a>) -> bool, 

Choose n relay at random.

Each relay is chosen with probability proportional to its weight in the role role, and is only selected if the predicate usable returns true for it.

Relays are chosen without replacement: no relay will be returned twice. Therefore, the resulting vector may be smaller than n if we happen to have fewer than n appropriate relays.

This function returns an empty vector if (and only if) there are no relays with nonzero weight where usable returned true.

pub fn relay_weight<'a>(
    &'a self,
    relay: &Relay<'a>,
    role: WeightRole
) -> RelayWeight

Compute the weight with which relay will be selected for a given role.

pub fn total_weight<P>(&self, role: WeightRole, usable: P) -> RelayWeight where
    P: Fn(&UncheckedRelay<'_>) -> bool, 

Compute the total weight with which any relay matching usable will be selected for a given role.

Note: because this function is used to assess the total properties of the consensus, the usable predicate takes a RouterStatus rather than a Relay.

pub fn weight_by_rsa_id(
    &self,
    rsa_id: &RsaIdentity,
    role: WeightRole
) -> Option<RelayWeight>

Compute the weight with which a relay with ID rsa_id would be selected for a given role.

Note that weight returned by this function assumes that the relay with that ID is actually usable; if it isn’t usable, then other weight-related functions will call its weight zero.

pub fn known_family_members<'a>(
    &'a self,
    relay: &'a Relay<'a>
) -> impl Iterator<Item = Relay<'a>>

Return all relays in this NetDir known to be in the same family as relay.

This list of members will not necessarily include relay itself.

Limitations

Two relays only belong to the same family if each relay claims to share a family with the other. But if we are missing a microdescriptor for one of the relays listed by this relay, we cannot know whether it acknowledges family membership with this relay or not. Therefore, this function can omit family members for which there is not (as yet) any Relay object.

Trait Implementations

impl Clone for NetDir

fn clone(&self) -> NetDir

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NetDir

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MdReceiver for NetDir

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

Return an iterator over the digests for all of the microdescriptors that this netdir is missing.

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

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

fn n_missing(&self) -> usize

Return the number of missing microdescriptors.