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 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.)

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

Return the declared lifetime of this NetDir.

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 Relays.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

Available on crate feature 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.

Available on crate feature 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.

Available on crate feature 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

Converts this type into a shared reference of the (usually inferred) input type.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Converts to this type from the input type.

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

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

Return the number of missing microdescriptors.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more