Struct GuardMgrInner

pub(crate) struct GuardMgrInner {

    pub(crate) last_primary_retry_time: Instant,
    pub(crate) guards: GuardSets,
    pub(crate) filter: GuardFilter,
    pub(crate) params: GuardParams,
    pub(crate) ctrl: UnboundedSender<Msg>,
    pub(crate) pending: HashMap<RequestId, PendingRequest>,
    pub(crate) waiting: Vec<PendingRequest>,
    pub(crate) fallbacks: FallbackState,
    pub(crate) storage: DynStorageHandle<GuardSets>,
    pub(crate) send_skew: Sender<Option<SkewEstimate>>,
    pub(crate) recv_skew: ClockSkewEvents,
    pub(crate) netdir_provider: Option<Weak<dyn NetDirProvider>>,
    pub(crate) bridge_desc_provider: Option<Weak<dyn BridgeDescProvider>>,
    pub(crate) configured_bridges: Option<Arc<[BridgeConfig]>>,
}

Helper type that holds the data used by a GuardMgr.

This would just be a GuardMgr, except that it needs to sit inside a Mutex and get accessed by daemon tasks.

Fields

last_primary_retry_time: Instant

Last time when marked all of our primary guards as retriable.

We keep track of this time so that we can rate-limit these attempts.

guards: GuardSets

Persistent guard manager state.

This object remembers one or more persistent set of guards that we can use, along with their relative priorities and statuses.

filter: GuardFilter

The current filter that we’re using to decide which guards are supported.

params: GuardParams

Configuration values derived from the consensus parameters.

This is updated whenever the consensus parameters change.

ctrl: UnboundedSender<Msg>

A mpsc channel, used to tell the task running in daemon::report_status_events about a new event to monitor.

This uses an UnboundedSender so that we don’t have to await while sending the message, which in turn allows the GuardMgr API to be simpler. The risk, however, is that there’s no backpressure in the event that the task running daemon::report_status_events fails to read from this channel.

pending: HashMap<RequestId, PendingRequest>

Information about guards that we’ve given out, but where we have not yet heard whether the guard was successful.

Upon leaning whether the guard was successful, the pending requests in this map may be either moved to waiting, or discarded.

There can be multiple pending requests corresponding to the same guard.

waiting: Vec<PendingRequest>

A list of pending requests for which we have heard that the guard was successful, but we have not yet decided whether the circuit may be used.

There can be multiple waiting requests corresponding to the same guard.

fallbacks: FallbackState

A list of fallback directories used to access the directory system when no other directory information is yet known.

storage: DynStorageHandle<GuardSets>

Location in which to store persistent state.

send_skew: Sender<Option<SkewEstimate>>

A sender object to publish changes in our estimated clock skew.

recv_skew: ClockSkewEvents

A receiver object to hand out to observers who want to know about changes in our estimated clock skew.

netdir_provider: Option<Weak<dyn NetDirProvider>>

A netdir provider that we can use for adding new guards when insufficient guards are available.

This has to be an Option so it can be initialized from None: at the time a GuardMgr is created, there is no NetDirProvider for it to use.

bridge_desc_provider: Option<Weak<dyn BridgeDescProvider>>

Available on crate feature bridge-client only.

A netdir provider that we can use for discovering bridge descriptors.

This has to be an Option so it can be initialized from None: at the time a GuardMgr is created, there is no BridgeDescProvider for it to use.

configured_bridges: Option<Arc<[BridgeConfig]>>

Available on crate feature bridge-client only.

A list of the bridges that we are configured to use, or “None” if we are not configured to use bridges.

Implementations

impl GuardMgrInner

pub(crate) fn timely_netdir(&self) -> Option<Arc<NetDir>>

Look up the latest NetDir (if there is one) from our NetDirProvider (if we have one).

pub(crate) fn latest_bridge_desc_list(&self) -> Option<Arc<BridgeDescList>>

Available on crate feature bridge-client only.

Look up the latest BridgeDescList (if there is one) from our BridgeDescProvider (if we have one).

pub(crate) fn with_opt_netdir<F, T>(&mut self, func: F) -> T

where F: FnOnce(&mut Self, Option<&NetDir>) -> T,

Run a function that takes &mut self and an optional NetDir.

We try to use the netdir from our NetDirProvider (if we have one). Therefore, although its parameters are suitable for every GuardSet, its contents might not be. For those, call with_opt_universe instead.

pub(crate) fn latest_bridge_set(&self) -> Option<BridgeSet>

Available on crate feature bridge-client only.

Return the latest BridgeSet based on our BridgeDescProvider and our configured bridges.

Returns None if we are not configured to use bridges.

pub(crate) fn with_opt_universe<F, T>(&mut self, func: F) -> T

where F: FnOnce(&mut Self, Option<&UniverseRef>) -> T,

Run a function that takes &mut self and an optional UniverseRef.

We try to get a universe from the appropriate source for the current active guard set.

pub(crate) fn update(&mut self, wallclock: SystemTime, now: Instant)

Update the status of all guards in the active set, based on the passage of time, our configuration, and the relevant Universe for our active set.

pub(crate) fn replace_bridge_config( &mut self, new_config: &impl GuardMgrConfig, wallclock: SystemTime, now: Instant, ) -> Result<RetireCircuits, GuardMgrConfigError>

Available on crate feature bridge-client only.

Replace our bridge configuration with the one from new_config.

pub(crate) fn update_active_set_params_and_filter( &mut self, netdir: Option<&NetDir>, )

Update our parameters, our selection (based on network parameters and configuration), and make sure the active GuardSet has the right configuration itself.

We should call this whenever the NetDir’s parameters change, or whenever our filter changes. We do not need to call it for new elements arriving in our Universe, since those do not affect anything here.

We should also call this whenever a new GuardSet becomes active for any reason other than just having called this function.

(This function is only invoked from update, which should be called under the above circumstances.)

pub(crate) fn update_guardset_internal<U: Universe>( params: &GuardParams, now: SystemTime, universe_type: UniverseType, active_guards: &mut GuardSet, universe: Option<&U>, ) -> ExtendedStatus

Update the status of every guard in active_guards, and expand it as needed.

This function doesn’t take &self, to make sure that we are only affecting a single GuardSet, and to avoid confusing the borrow checker.

We should call this whenever the contents of the universe have changed.

We should also call this whenever a new GuardSet becomes active.

pub(crate) fn update_desired_descriptors(&mut self, now: Instant)

Available on crate feature bridge-client only.

If using bridges, tell the BridgeDescProvider which descriptors we want. We need to check this after we select our primary guards.

pub(crate) fn replace_guards_with( &mut self, new_guards: GuardSets, wallclock: SystemTime, now: Instant, )

Replace the active guard state with new_state, preserving non-persistent state for any guards that are retained.

pub(crate) fn select_guard_set_based_on_filter(&mut self, netdir: &NetDir)

Update which guard set is active based on the current filter and the provided netdir.

After calling this function, the new guard set’s filter may be out-of-date: be sure to call set_filter as appropriate.

pub(crate) fn maybe_retry_primary_guards(&mut self, now: Instant)

Mark all of our primary guards as retriable, if we haven’t done so since long enough before now.

We want to call this function whenever a guard attempt succeeds, if the internet seemed to be down when the guard attempt was first launched.

pub(crate) fn set_filter( &mut self, filter: GuardFilter, wallclock: SystemTime, now: Instant, )

Replace the current GuardFilter with filter.

pub(crate) fn handle_msg( &mut self, request_id: RequestId, status: GuardStatus, skew: Option<ClockSkew>, runtime: &impl SleepProvider, )

Called when the circuit manager reports (via GuardMonitor) that a guard succeeded or failed.

Changes the guard’s status as appropriate, and updates the pending request as needed.

pub(crate) fn record_external_success<T>( &mut self, identity: &T, external_activity: ExternalActivity, now: SystemTime, )

where T: HasRelayIds + ?Sized,

Helper to implement GuardMgr::note_external_success().

(This has to be a separate function so that we can borrow params while we have mut self borrowed.)

pub(crate) fn skew_observations(&self) -> impl Iterator<Item = &SkewObservation>

Return an iterator over all of the clock skew observations we’ve made for guards or fallbacks.

pub(crate) fn update_skew(&mut self, now: Instant)

Recalculate our estimated clock skew, and publish it to anybody who cares.

pub(crate) fn guard_usability_status( &self, pending: &PendingRequest, now: Instant, ) -> Option<bool>

If the circuit built because of a given PendingRequest may now be used (or discarded), return Some(true) or Some(false) respectively.

Return None if we can’t yet give an answer about whether such a circuit is usable.

pub(crate) fn expire_and_answer_pending_requests(&mut self, now: Instant)

For requests that have been “waiting” for an answer for too long, expire them and tell the circuit manager that their circuits are unusable.

pub(crate) fn lookup_ids<T>(&self, identity: &T) -> Vec<FirstHopId>

where T: HasRelayIds + ?Sized,

Return every currently extant FirstHopId for a guard or fallback directory matching (or possibly matching) the provided keys.

An identity is possibly matching if it contains some of the IDs in the provided identity, and it has no contradictory identities, but it does not necessarily contain all of those identities.

TODO

This function should probably not exist; it’s only used so that dirmgr can report successes or failures, since by the time it observes them it doesn’t know whether its circuit came from a guard or a fallback. To solve that, we’ll need CircMgr to record and report which one it was using, which will take some more plumbing.

TODO relay: we will have to make the change above when we implement relays; otherwise, it would be possible for an attacker to exploit it to mislead us about our guard status.

pub(crate) fn run_periodic_events( &mut self, wallclock: SystemTime, now: Instant, ) -> Duration

Run any periodic events that update guard status, and return a duration after which periodic events should next be run.

pub(crate) fn select_guard_with_expand( &mut self, usage: &GuardUsage, now: Instant, wallclock: SystemTime, ) -> Result<(ListKind, FirstHop), PickGuardError>

Try to select a guard, expanding the sample if the first attempt fails.

pub(crate) fn select_guard_once( &self, usage: &GuardUsage, now: Instant, ) -> Result<(ListKind, FirstHop), PickGuardError>

Helper: try to pick a single guard, without retrying on failure.

pub(crate) fn select_fallback( &self, now: Instant, ) -> Result<(ListKind, FirstHop), PickGuardError>

Helper: Select a fallback directory.

Called when we have no guard information to use. Return values are as for GuardMgr::select_guard()