Struct tor_circmgr::CircMgr

pub struct CircMgr<R: Runtime> { /* private fields */ }

A Circuit Manager (CircMgr) manages a set of circuits, returning them when they’re suitable, and launching them if they don’t already exist.

Right now, its notion of “suitable” is quite rudimentary: it just believes in two kinds of circuits: Exit circuits, and directory circuits. Exit circuits are ones that were created to connect to a set of ports; directory circuits were made to talk to directory caches.

This is a “handle”; clones of it share state.

Implementations

impl<R: Runtime> CircMgr<R>

pub fn new<SM, CFG: CircMgrConfig>( config: &CFG, storage: SM, runtime: &R, chanmgr: Arc<ChanMgr<R>>, guardmgr: GuardMgr<R> ) -> Result<Arc<Self>>where SM: StateMgr + Send + Sync + 'static,

Construct a new circuit manager.

Usage note

For the manager to work properly, you will need to call CircMgr::launch_background_tasks.

pub fn install_onion_service_connector( &self, connector: &Arc<dyn OnionServiceConnector> ) -> Result<()>

Available on crate feature hs-client only.

Install a given OnionServiceConnector object to be used when making connections to an onion service.

(This cannot be done at construction time, since the OnionServiceConnector will have to keep a reference to this CircMgr.)

pub fn launch_background_tasks<D>( self: &Arc<Self>, runtime: &R, dir_provider: &Arc<D>, state_mgr: FsStateMgr ) -> Result<Vec<TaskHandle>>where D: NetDirProvider + 'static + ?Sized,

Launch the periodic daemon tasks required by the manager to function properly.

Returns a set of TaskHandles that can be used to manage the daemon tasks.

pub fn reconfigure<CFG: CircMgrConfig>( &self, new_config: &CFG, how: Reconfigure ) -> Result<(), ReconfigureError>

Try to change our configuration settings to new_config.

The actual behavior here will depend on the value of how.

pub fn reload_persistent_state(&self) -> Result<()>

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.

pub fn upgrade_to_owned_persistent_state(&self) -> Result<()>

Switch from having an unowned persistent state to having an owned one.

Requires that we hold the lock on the state files.

pub fn store_persistent_state(&self) -> Result<bool>

Flush state to the state manager, if there is any unsaved state and we have the lock.

Return true if we saved something; false if we didn’t have the lock.

pub fn update_network_parameters(&self, p: &NetParameters)

👎Deprecated: There is no need to call this function if you have used launch_background_tasks

Reconfigure this circuit manager using the latest set of network parameters.

This is deprecated as a public function: launch_background_tasks now ensures that this happens as needed.

pub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool

Return true if netdir has enough information to be used for this circuit manager.

(This will check whether the netdir is missing any primary guard microdescriptors)

pub async fn get_or_launch_dir(&self, netdir: DirInfo<'_>) -> Result<ClientCirc>

Return a circuit suitable for sending one-hop BEGINDIR streams, launching it if necessary.

pub async fn get_or_launch_exit( &self, netdir: DirInfo<'_>, ports: &[TargetPort], isolation: StreamIsolation ) -> Result<ClientCirc>

Return a circuit suitable for exiting to all of the provided ports, launching it if necessary.

If the list of ports is empty, then the chosen circuit will still end at some exit.

pub async fn get_or_launch_onion_client( &self, service_id: HsId, using_keys: Option<ClientSecretKeys>, isolation: StreamIsolation ) -> Result<ClientCirc>

Available on crate feature hs-client only.

Try to connect to an onion service via this circuit manager.

If using_keys is provided, then we will use those keys, in addition to any configured in our OnionServiceConnector, to connect to the service.

If we already have an existing circuit with the appropriate isolation, we will return that circuit regardless of the content of using_keys.

Requires that an OnionServiceConnector has been installed. If it hasn’t, then we return an error.

pub async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>( &self, target: T ) -> Result<ClientCirc>

Available on crate feature specific-relay only.

Return a circuit to a specific relay, suitable for using for direct (one-hop) directory downloads.

This could be used, for example, to download a descriptor for a bridge.

pub async fn launch_specific_isolated( &self, target: OwnedCircTarget, preferences: () ) -> Result<ClientCirc>

Available on crate feature hs-common only.

Create and return a new (typically anonymous) circuit whose last hop is target.

This circuit is guaranteed not to have been used for any traffic previously, and it will not be given out for any other requests in the future unless explicitly re-registered with a circuit manager.

Used to implement onion service clients and services.

pub fn builder(&self) -> &CircuitBuilder<R>

Available on crate feature experimental-api only.

Return a reference to the associated CircuitBuilder that this CircMgr will use to create its circuits.

pub fn retire_circ(&self, circ_id: &UniqId)

If circ_id is the unique identifier for a circuit that we’re keeping track of, don’t give it out for any future requests.

pub fn note_external_failure( &self, target: &impl ChanTarget, external_failure: ExternalActivity )

Record that a failure occurred on a circuit with a given guard, in a way that makes us unwilling to use that guard for future circuits.

pub fn note_external_success( &self, target: &impl ChanTarget, external_activity: ExternalActivity )

Record that a success occurred on a circuit with a given guard, in a way that makes us possibly willing to use that guard for future circuits.

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

impl<R: Clone + Runtime> Clone for CircMgr<R>

fn clone(&self) -> CircMgr<R>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R: Runtime> Drop for CircMgr<R>

fn drop(&mut self)

Executes the destructor for this type.