Struct ChanMgr 

pub struct ChanMgr<R: Runtime> {
    pub(crate) mgr: AbstractChanMgr<CompoundFactory<ChanBuilder<R, DefaultTransport<R>>>>,
    pub(crate) bootstrap_status: ConnStatusEvents,
    pub(crate) runtime: R,
}

An object that remembers a set of live channels, and launches new ones on request.

Use the ChanMgr::get_or_launch function to create a new Channel, or get one if it exists. (For a slightly lower-level API that does no caching, see ChannelFactory and its implementors.

Each channel is kept open as long as there is a reference to it, or something else (such as the relay or a network error) kills the channel.

After a ChanMgr launches a channel, it keeps a reference to it until that channel has been unused (that is, had no circuits attached to it) for a certain amount of time. (Currently this interval is chosen randomly from between 180-270 seconds, but this is an implementation detail that may change in the future.)

Fields

mgr: AbstractChanMgr<CompoundFactory<ChanBuilder<R, DefaultTransport<R>>>>

Internal channel manager object that does the actual work.

How this is built

This internal manager is parameterized over an mgr::AbstractChannelFactory, which here is instantiated with a factory::CompoundFactory. The CompoundFactory itself holds:

• A dyn factory::AbstractPtMgr that can provide a dyn factory::ChannelFactory for each supported pluggable transport. This starts out as None, but can be replaced with ChanMgr::set_pt_mgr. The TorClient code currently sets this using tor_ptmgr::PtMgr. PtMgr currently returns ChannelFactory implementations that are built using transport::proxied::ExternalProxyPlugin, which implements transport::TransportImplHelper, which in turn is wrapped into a ChanBuilder to implement ChannelFactory.
• A generic factory::ChannelFactory that it uses for everything else We instantiate this with a builder::ChanBuilder using a transport::default::DefaultTransport.

bootstrap_status: ConnStatusEvents

Stream of ConnStatus events.

runtime: R

The runtime. Needed to possibly spawn tasks.

Implementations

impl<R: Runtime> ChanMgr<R>

pub fn new( runtime: R, config: ChanMgrConfig, dormancy: Dormancy, netparams: &NetParameters, memquota: ToplevelAccount, ) -> Result<Self>

where R: 'static,

Construct a new channel manager.

A new ChannelAccount will be made from memquota, for each Channel.

The ChannelAccount is used for data associated with this channel.

This does not (currently) include downstream outbound data (ie, data processed by the channel implementation here, awaiting TLS processing and actual transmission). In any case we try to keep those buffers small.

The ChannelAccount does track upstream outbound data (ie, data processed by a circuit, but not yet by the channel), even though that data relates to a specific circuit. TODO #1652 use CircuitAccount for circuit->channel queue.

Usage note

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

The keymgr is only needed for a relay which is used for authenticating its channel to other relays. Pass None for a client.

pub fn launch_background_tasks( self: &Arc<Self>, runtime: &R, netdir: Arc<dyn NetDirProvider>, ) -> Result<Vec<TaskHandle>>

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

Returns a TaskHandle that can be used to manage those daemon tasks that poll periodically.

pub async fn handle_incoming( &self, src: Sensitive<SocketAddr>, stream: <R as NetStreamProvider>::Stream, ) -> Result<Arc<Channel>>

Build a channel for an incoming stream.

The my_addrs are the IP address(es) that are advertised by the relay in the consensus. We need to pass them so they can be sent in the NETINFO cell.

The channel may or may not be authenticated. This method will wait until the channel is usable, and may return an error if we already have an existing channel to this peer, or if there are already too many open connections with this peer or subnet (as a dos defence).

pub async fn get_or_launch<T: ChanTarget + ?Sized>( &self, target: &T, usage: ChannelUsage, ) -> Result<(Arc<Channel>, ChanProvenance)>

Try to get a suitable channel to the provided target, launching one if one does not exist.

This function does not guarantee that the returned channel satisfies all of the properties of target. For example if an existing channel is returned, it might not be connected to any of the addresses specified in target.

If there is already a channel launch attempt in progress, this function will wait until that launch is complete, and succeed or fail depending on its outcome.

pub fn bootstrap_events(&self) -> ConnStatusEvents

Return a stream of ConnStatus events to tell us about changes in our ability to connect to the internet.

Note that this stream can be lossy: the caller will not necessarily observe every event on the stream

pub fn expire_channels(&self) -> Duration

Expire all channels that have been unused for too long.

Return the duration from now until next channel expires.

pub fn set_dormancy( &self, dormancy: Dormancy, netparams: Arc<dyn AsRef<NetParameters>>, ) -> StdResult<(), Bug>

Notifies the chanmgr to be dormant like dormancy

pub fn reconfigure( &self, config: &ChannelConfig, how: Reconfigure, netparams: Arc<dyn AsRef<NetParameters>>, ) -> StdResult<(), ReconfigureError>

Reconfigure all channels

pub fn set_pt_mgr(&self, ptmgr: Arc<dyn AbstractPtMgr + 'static>)

Replace the transport registry with one that may know about more transports.

Note that the ChannelFactory instances returned by ptmgr are required to time-out channels that take too long to build. You’ll get this behavior by default if the factories implement ChannelFactory using transport::proxied::ExternalProxyPlugin, which tor-ptmgr does.

pub fn set_relay_auth_material( &self, auth_material: Arc<RelayChannelAuthMaterial>, ) -> Result<()>

Replace the relay auth material used for building new channels.

This rebuilds the internal channel builder with the provided auth_material, which includes a new TLS cert and key. Existing channels are not affected, only newly created channels will use the new keys.

pub fn set_create_request_handler( &self, handler: Arc<CreateRequestHandler>, ) -> Result<()>

This will be used to handle CREATE* requests on channels.

This handler will only be used for new channels, not existing channels.

This will not be updated in any way by the channel manager, for example by a netdir update or when any keys change. The caller must handle this. The idea is that the channel manager shouldn’t need to deal with circuit-specific stuff.

It’s expected to only ever call this once. Ideally it would be an Option in the constructor, but we don’t want conditionally-compiled constructor arguments, and the CreateRequestHandler requires a [dyn ChannelProvider] which is typically this ChanMgr itself.

pub async fn build_unmanaged_channel( &self, target: impl IntoOwnedChanTarget, memquota: ChannelAccount, ) -> Result<Arc<Channel>>

Try to create a new, unmanaged channel to target.

Unlike get_or_launch, this function always creates a new channel, never retries transient failure, and does not register this channel with the ChanMgr.

Generally you should not use this function; get_or_launch is usually a better choice. This function is the right choice if, for whatever reason, you need to manage the lifetime of the channel you create, and make sure that no other code with access to this ChanMgr will be able to use the channel.

pub(crate) async fn continually_update_channels_config( self_: Weak<Self>, netdir: Arc<dyn NetDirProvider>, )

Watch for things that ought to change the configuration of all channels in the client

Currently this handles enabling and disabling channel padding.

This is a daemon task that runs indefinitely in the background, and exits when we find that chanmgr is dropped.

pub(crate) async fn continually_expire_channels( sched: TaskSchedule<R>, chanmgr: Weak<Self>, )

Periodically expire any channels that have been unused beyond the maximum duration allowed.

Exist when we find that chanmgr is dropped

This is a daemon task that runs indefinitely in the background

Trait Implementations

impl<R: Runtime> ChannelProvider for ChanMgr<R>

type BuildSpec = OwnedChanTarget

Type that explains how to build an outgoing channel.

fn get_or_launch( self: Arc<Self>, reactor_id: UniqId, target: Self::BuildSpec, tx: OutboundChanSender, ) -> Result<()>

Get a channel corresponding to the identities of target, for the circuit reactor with the specified reactor_id which should only be used for logging purposes.