Struct tor_netdir::NetDir
source · [−]pub struct NetDir { /* private fields */ }
Expand description
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.)
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.
Implementations
sourceimpl NetDir
impl NetDir
sourcepub fn replace_overridden_parameters(&mut self, new_replacement: &NetParams<i32>)
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.
sourcepub fn all_relays(&self) -> impl Iterator<Item = UncheckedRelay<'_>>
pub fn all_relays(&self) -> impl Iterator<Item = UncheckedRelay<'_>>
Return an iterator over all Relay objects, including invalid ones that we can’t use.
sourcepub fn relays(&self) -> impl Iterator<Item = Relay<'_>>
pub fn relays(&self) -> impl Iterator<Item = Relay<'_>>
Return an iterator over all usable Relays.
sourcepub fn by_id<'a, T>(&self, id: T) -> Option<Relay<'_>> where
T: Into<RelayIdRef<'a>> + ?Sized,
pub fn by_id<'a, T>(&self, id: T) -> Option<Relay<'_>> where
T: Into<RelayIdRef<'a>> + ?Sized,
Return a relay matching a given identity, if we have a usable relay with that key.
(Does not return unusable 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.
sourcepub fn by_ids<T>(&self, target: &T) -> Option<Relay<'_>> where
T: HasRelayIds + ?Sized,
pub fn by_ids<T>(&self, target: &T) -> Option<Relay<'_>> where
T: HasRelayIds + ?Sized,
Return a relay with the same identities as those in target
, if one
exists.
Does not return unusable relays.
Limitations
This will be very slow if target
does not have an Ed25519 or RSA
identity.
sourcepub fn ids_listed<T>(&self, target: &T) -> Option<bool> where
T: HasRelayIds + ?Sized,
pub fn ids_listed<T>(&self, target: &T) -> Option<bool> where
T: HasRelayIds + ?Sized,
As id_pair_listed
, but check whether a relay exists (or may exist)
with the same identities as those in target
.
Limitations
This can be inefficient if the target does not have both an ed25519 and an rsa identity key.
sourcepub fn params(&self) -> &NetParameters
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.
sourcepub 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,
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.
sourcepub fn pick_n_relays<'a, R, P>(
&'a self,
rng: &mut R,
n: usize,
role: WeightRole,
usable: P
) -> Vec<Relay<'a>>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
where
R: Rng,
P: FnMut(&Relay<'a>) -> bool,
pub fn pick_n_relays<'a, R, P>(
&'a self,
rng: &mut R,
n: usize,
role: WeightRole,
usable: P
) -> Vec<Relay<'a>>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
where
R: Rng,
P: FnMut(&Relay<'a>) -> bool,
A: Allocator,
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.
sourcepub fn relay_weight<'a>(
&'a self,
relay: &Relay<'a>,
role: WeightRole
) -> RelayWeight
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
.
sourcepub fn total_weight<P>(&self, role: WeightRole, usable: P) -> RelayWeight where
P: Fn(&UncheckedRelay<'_>) -> bool,
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
.
sourcepub fn weight_by_rsa_id(
&self,
rsa_id: &RsaIdentity,
role: WeightRole
) -> Option<RelayWeight>
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.
sourcepub fn known_family_members<'a>(
&'a self,
relay: &'a Relay<'a>
) -> impl Iterator<Item = Relay<'a>>
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.
sourcepub fn onion_service_time_period(&self) -> TimePeriod
Available on crate feature hs-common
only.
pub fn onion_service_time_period(&self) -> TimePeriod
hs-common
only.Return the current onion service directory “time period”.
Specifically, this returns the time period that contains the beginning
of the validity period of this NetDir
’s consensus. That time period
is the one we use when acting as an onion service client.
sourcepub fn onion_service_secondary_time_periods(&self) -> Vec<TimePeriod>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
Available on crate feature hs-service
only.
pub fn onion_service_secondary_time_periods(&self) -> Vec<TimePeriod>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
hs-service
only.Return the secondary onion service directory “time periods”.
These are additional time periods that we publish descriptors for when we are acting as an onion service.
sourcepub fn onion_service_dirs(
&self,
id: HsBlindId,
op: OnionServiceDirOp,
when: TimePeriod
) -> Result<Vec<Relay<'_>>, OnionDirLookupError>
Available on crate feature hs-common
only.
pub fn onion_service_dirs(
&self,
id: HsBlindId,
op: OnionServiceDirOp,
when: TimePeriod
) -> Result<Vec<Relay<'_>>, OnionDirLookupError>
hs-common
only.Return the relays in this network directory that will be used to store a given onion service’s descriptor at a given time period.
Return an error if the time period is not one returned by
onion_service_time_period
or onion_service_secondary_time_periods
.
Trait Implementations
sourceimpl AsRef<NetParameters> for NetDir
impl AsRef<NetParameters> for NetDir
sourcefn as_ref(&self) -> &NetParameters
fn as_ref(&self) -> &NetParameters
Converts this type into a shared reference of the (usually inferred) input type.
sourceimpl From<NetDir> for TestNetDirProvider
impl From<NetDir> for TestNetDirProvider
sourceimpl MdReceiver for NetDir
impl MdReceiver for NetDir
sourcefn missing_microdescs(&self) -> Box<dyn Iterator<Item = &MdDigest> + '_>
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. Read more
sourcefn add_microdesc(&mut self, md: Microdesc) -> bool
fn add_microdesc(&mut self, md: Microdesc) -> bool
Add a microdescriptor to this netdir, if it was wanted. Read more
Auto Trait Implementations
impl RefUnwindSafe for NetDir
impl Send for NetDir
impl Sync for NetDir
impl Unpin for NetDir
impl UnwindSafe for NetDir
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more