Struct tor_guardmgr::GuardMgr
source · [−]pub struct GuardMgr<R: Runtime> { /* private fields */ }
Expand description
A “guard manager” that selects and remembers a persistent set of guard nodes.
Implementations
sourceimpl<R: Runtime> GuardMgr<R>
impl<R: Runtime> GuardMgr<R>
sourcepub fn new<S>(
runtime: R,
state_mgr: S,
fallbacks: FallbackList
) -> Result<Self, GuardMgrError> where
S: StateMgr + Send + Sync + 'static,
pub fn new<S>(
runtime: R,
state_mgr: S,
fallbacks: FallbackList
) -> Result<Self, GuardMgrError> where
S: StateMgr + Send + Sync + 'static,
Create a new “empty” guard manager and launch its background tasks.
It won’t be able to hand out any guards until
GuardMgr::update_network
has been called.
sourcepub fn install_netdir_provider(
&self,
provider: &Arc<dyn NetDirProvider>
) -> Result<(), GuardMgrError>
pub fn install_netdir_provider(
&self,
provider: &Arc<dyn NetDirProvider>
) -> Result<(), GuardMgrError>
Install a NetDirProvider
for use by this guard manager.
It will be used to keep the guards up-to-date with changes from the network directory, and to find new guards when no NetDir is provided to select_guard().
TODO: we should eventually return some kind of a task handle from this task, even though it is not strictly speaking periodic.
sourcepub fn store_persistent_state(&self) -> Result<(), GuardMgrError>
pub fn store_persistent_state(&self) -> Result<(), GuardMgrError>
Flush our current guard state to the state manager, if there is any unsaved state.
sourcepub fn reload_persistent_state(&self) -> Result<(), GuardMgrError>
pub fn reload_persistent_state(&self) -> Result<(), GuardMgrError>
Reload state from the state manager.
We only call this method if we don’t have the lock on the state files. If we have the lock, we only want to save.
sourcepub fn upgrade_to_owned_persistent_state(&self) -> Result<(), GuardMgrError>
pub fn upgrade_to_owned_persistent_state(&self) -> Result<(), GuardMgrError>
Switch from having an unowned persistent state to having an owned one.
Requires that we hold the lock on the state files.
sourcepub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool
pub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool
Return true if netdir
has enough information to safely become our new netdir.
sourcepub fn mark_all_guards_retriable(&self)
pub fn mark_all_guards_retriable(&self)
Mark every guard as potentially retriable, regardless of how recently we failed to connect to it.
sourcepub fn update_network(&self, netdir: &NetDir)
pub fn update_network(&self, netdir: &NetDir)
Update the state of this GuardMgr
based on a new or modified
NetDir
object.
This method can add new guards, or notice that existing guards have
become unusable. It needs a NetDir
so it can identify potential
candidate guards.
Call this method whenever the NetDir
changes, unless you have used
install_netdir_provider
.
sourcepub fn replace_fallback_list(&self, list: FallbackList)
pub fn replace_fallback_list(&self, list: FallbackList)
Replace the fallback list held by this GuardMgr with new_list
.
sourcepub fn set_filter(&self, filter: GuardFilter, netdir: Option<&NetDir>)
pub fn set_filter(&self, filter: GuardFilter, netdir: Option<&NetDir>)
Replace the current GuardFilter
used by this GuardMgr
.
sourcepub fn select_guard(
&self,
usage: GuardUsage,
netdir: Option<&NetDir>
) -> Result<(FirstHop, GuardMonitor, GuardUsable), PickGuardError>
pub fn select_guard(
&self,
usage: GuardUsage,
netdir: Option<&NetDir>
) -> Result<(FirstHop, GuardMonitor, GuardUsable), PickGuardError>
Select a guard for a given GuardUsage
.
On success, we return a FirstHop
object to identify which
guard we have picked, a GuardMonitor
object that the
caller can use to report whether its attempt to use the guard
succeeded or failed, and a GuardUsable
future that the
caller can use to decide whether a circuit built through the
guard is actually safe to use.
That last point is important: It’s okay to build a circuit
through the guard returned by this function, but you can’t
actually use it for traffic unless the GuardUsable
future
yields “true”.
Limitations
This function will never return a guard that isn’t listed in
the most recent NetDir
.
That’s usually what you’d want, but when we’re trying to bootstrap we might want to use all guards as possible directory caches. That’s not implemented yet. (See ticket #220).
This function only looks at netdir when all of the known
guards are down; to force an update, use GuardMgr::update_network
.
sourcepub fn note_external_failure(
&self,
ed_identity: &Ed25519Identity,
rsa_identity: &RsaIdentity,
external_failure: ExternalActivity
)
pub fn note_external_failure(
&self,
ed_identity: &Ed25519Identity,
rsa_identity: &RsaIdentity,
external_failure: ExternalActivity
)
Record that after we built a circuit with a guard, something described
in external_failure
went wrong with it.
sourcepub fn note_external_success(
&self,
ed_identity: &Ed25519Identity,
rsa_identity: &RsaIdentity,
external_activity: ExternalActivity
)
pub fn note_external_success(
&self,
ed_identity: &Ed25519Identity,
rsa_identity: &RsaIdentity,
external_activity: ExternalActivity
)
Record that after we built a circuit with a guard, some activity
described in external_activity
was successful with it.
sourcepub fn skew_events(&self) -> ClockSkewEvents
pub fn skew_events(&self) -> ClockSkewEvents
Return a stream of events about our estimated clock skew; these events
are None
when we don’t have enough information to make an estimate,
and Some(
SkewEstimate
)
otherwise.
Note that this stream can be lossy: if the estimate changes more than one before you read from the stream, you might only get the most recent update.
Trait Implementations
Auto Trait Implementations
impl<R> RefUnwindSafe for GuardMgr<R> where
R: RefUnwindSafe,
impl<R> Send for GuardMgr<R>
impl<R> Sync for GuardMgr<R>
impl<R> Unpin for GuardMgr<R> where
R: Unpin,
impl<R> UnwindSafe for GuardMgr<R> where
R: UnwindSafe,
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>
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
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