Struct Channel

pub struct Channel { /* private fields */ }

An open client channel, ready to send and receive Tor cells.

A channel is a direct connection to a Tor relay, implemented using TLS.

This struct is a frontend that can be used to send cells and otherwise control the channel. The main state is in the Reactor object.

(Users need a mutable reference because of the types in Sink, and ultimately because cell_tx: mpsc::Sender doesn’t work without mut.

Channel life cycle

Channels can be created directly here through the ChannelBuilder API. For a higher-level API (with better support for TLS, pluggable transports, and channel reuse) see the tor-chanmgr crate.

After a channel is created, it will persist until it is closed in one of four ways:

1. A remote error occurs.
2. The other side of the channel closes the channel.
3. Someone calls Channel::terminate on the channel.
4. The last reference to the Channel is dropped. (Note that every circuit on a Channel keeps a reference to it, which will in turn keep the channel from closing until all those circuits have gone away.)

Note that in cases 1-3, the Channel object itself will still exist: it will just be unusable for most purposes. Most operations on it will fail with an error.

Implementations

impl Channel

pub fn unique_id(&self) -> UniqId

Return a process-unique identifier for this channel.

pub fn mq_account(&self) -> &ChannelAccount

Return a reference to the memory tracking account for this Channel

pub fn time_provider(&self) -> &DynTimeProvider

Obtain a reference to the Channel’s DynTimeProvider

(This can sometimes be used to avoid having to keep a separate clone of the time provider.)

pub fn target(&self) -> &OwnedChanTarget

Return an OwnedChanTarget representing the actual handshake used to create this channel.

pub fn age(&self) -> Duration

Return the amount of time that has passed since this channel became open.

pub fn clock_skew(&self) -> ClockSkew

Return a ClockSkew declaring how much clock skew the other side of this channel claimed that we had when we negotiated the connection.

pub fn engage_padding_activities(&self)

Specify that this channel should do activities related to channel padding

Initially, the channel does nothing related to channel padding: it neither sends any padding, nor sends any PADDING_NEGOTIATE cells.

After this function has been called, it will do both, according to the parameters specified through reparameterize. Note that this might include disabling padding (for example, by sending a PADDING_NEGOTIATE).

Idempotent.

There is no way to undo the effect of this call.

pub fn reparameterize( &self, params: Arc<ChannelPaddingInstructionsUpdates>, ) -> Result<()>

Reparameterise (update parameters; reconfigure)

Returns Err if the channel was closed earlier

pub fn reparameterize_kist(&self, kist_params: KistParams) -> Result<()>

Update the KIST parameters.

Returns Err if the channel is closed.

pub fn check_match<T: HasRelayIds + ?Sized>(&self, target: &T) -> Result<()>

Return an error if this channel is somehow mismatched with the given target.

pub fn is_closing(&self) -> bool

Return true if this channel is closed and therefore unusable.

pub fn duration_unused(&self) -> Option<Duration>

If the channel is not in use, return the amount of time it has had with no circuits.

Return None if the channel is currently in use.

pub async fn new_circ(self: &Arc<Self>) -> Result<(PendingClientCirc, Reactor)>

Return a newly allocated PendingClientCirc object with a corresponding circuit reactor. A circuit ID is allocated, but no messages are sent, and no cryptography is done.

To use the results of this method, call Reactor::run() in a new task, then use the methods of crate::circuit::PendingClientCirc to build the circuit.

pub fn terminate(&self)

Shut down this channel immediately, along with all circuits that are using it.

Note that other references to this channel may exist. If they do, they will stop working after you call this function.

It’s not necessary to call this method if you’re just done with a channel: the channel should close on its own once nothing is using it any more.

pub fn close_circuit(&self, circid: CircId) -> Result<()>

Tell the reactor that the circuit with the given ID has gone away.

pub fn wait_for_close( &self, ) -> impl Future<Output = StdResult<CloseInfo, ClosedUnexpectedly>> + Send + Sync + 'static

Return a future that will resolve once this channel has closed.

Note that this method does not cause the channel to shut down on its own.

pub fn new_fake() -> (Channel, UnboundedReceiver<CtrlMsg>)

Available on crate feature testing only.

Make a new fake reactor-less channel. For testing only, obviously.

Returns the receiver end of the control message mpsc.

Suitable for external callers who want to test behaviour of layers including the logic in the channel frontend (Channel object methods).

Trait Implementations

impl Debug for Channel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasRelayIds for Channel

fn identity(&self, key_type: RelayIdType) -> Option<RelayIdRef<'_>>

Return the identity of this relay whose type is key_type, or None if the relay has no such identity.

fn identities(&self) -> RelayIdIter<'_, Self>

Return an iterator over all of the identities held by this object.

fn ed_identity(&self) -> Option<&Ed25519Identity>

Return the ed25519 identity for this relay if it has one.

fn rsa_identity(&self) -> Option<&RsaIdentity>

Return the RSA identity for this relay if it has one.

fn has_identity(&self, id: RelayIdRef<'_>) -> bool

Check whether the provided Id is a known identity of this relay.

fn has_any_identity(&self) -> bool

Return true if this object has any known identity.

fn same_relay_ids<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has exactly the same relay IDs as other.

fn has_all_relay_ids_from<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has every relay ID that other does.

fn has_any_relay_id_from<T>(&self, other: &T) -> bool

where T: HasRelayIds + ?Sized,

Return true if this object has any relay ID that other has.

fn cmp_by_relay_ids<T>(&self, other: &T) -> Ordering

where T: HasRelayIds + ?Sized,

Compare this object to another HasRelayIds.

fn display_relay_ids(&self) -> DisplayRelayIds<'_, Self>

Return a reference to this object suitable for formatting its HasRelayIds members.