Struct Channel 

pub struct Channel {
    channel_type: ChannelType,
    control: UnboundedSender<CtrlMsg>,
    cell_tx: CountingSink<Sender<(AnyChanCell, Option<QueuedCellPaddingInfo>), MpscSpec>>,
    reactor_closed_rx: Receiver<Result<CloseInfo>>,
    padding_ctrl: PaddingController,
    unique_id: UniqId,
    peer_id: OwnedChanTarget,
    clock_skew: ClockSkew,
    opened_at: Instant,
    mutable: Mutex<MutableDetails>,
    details: Arc<ChannelDetails>,
}

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.

Fields

channel_type: ChannelType

The channel type.

control: UnboundedSender<CtrlMsg>

A channel used to send control messages to the Reactor.

cell_tx: CountingSink<Sender<(AnyChanCell, Option<QueuedCellPaddingInfo>), MpscSpec>>

A channel used to send cells to the Reactor.

reactor_closed_rx: Receiver<Result<CloseInfo>>

A receiver that indicates whether the channel is closed.

Awaiting will return a CancelledError event when the reactor is dropped. Read to decide if operations may succeed, and is returned by wait_for_close.

padding_ctrl: PaddingController

Padding controller, used to report when data is queued for this channel.

unique_id: UniqId

A unique identifier for this channel.

peer_id: OwnedChanTarget

Validated identity and address information for this peer.

clock_skew: ClockSkew

The declared clock skew on this channel, at the time when this channel was created.

opened_at: Instant

The time when this channel was successfully completed

mutable: Mutex<MutableDetails>

Mutable state used by the `Channel.

details: Arc<ChannelDetails>

Information shared with the reactor

Implementations

impl Channel

fn new<S>( channel_type: ChannelType, link_protocol: u16, sink: Box<dyn Sink<AnyChanCell, Error = Error> + Send + Unpin + 'static>, stream: Box<dyn Stream<Item = Result<AnyChanCell, Error>> + Send + Unpin + 'static>, streamops: Box<dyn StreamOps + Send + Unpin + 'static>, unique_id: UniqId, peer_id: OwnedChanTarget, clock_skew: ClockSkew, sleep_prov: S, memquota: ChannelAccount, ) -> Result<(Arc<Self>, Reactor<S>)>

where S: CoarseTimeProvider + SleepProvider,

Construct a channel and reactor.

Internal method, called to finalize the channel when we’ve sent our netinfo cell, received the peer’s netinfo cell, and we’re finally ready to create circuits.

Quick note on the allow clippy. This is has one call site so for now, it is fine that we bust the mighty 7 arguments.

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.

fn send_control(&self, msg: CtrlMsg) -> StdResult<(), ChannelClosed>

Send a control message

fn mutable(&self) -> MutexGuard<'_, MutableDetails>

Acquire the lock on mutable (and handle any poison error)

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(crate) fn sender(&self) -> ChannelSender

Return a new ChannelSender to transmit cells on this channel.

pub async fn new_tunnel( self: &Arc<Self>, timeouts: Arc<dyn TimeoutEstimator>, ) -> Result<(PendingClientTunnel, Reactor)>

Return a newly allocated PendingClientTunnel object with a corresponding tunnel 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::client::circuit::PendingClientTunnel 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 + use<>

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 async fn start_padding( self: &Arc<Self>, padder: CircuitPadder, ) -> Result<()>

Available on crate feature circ-padding-manual only.

Install a CircuitPadder for this channel.

Replaces any previous padder installed.

pub async fn stop_padding(self: &Arc<Self>) -> Result<()>

Available on crate feature circ-padding-manual only.

Remove any CircuitPadder installed for this channel.

Does nothing if there was not a padder installed there.

async fn set_padder_impl( self: &Arc<Self>, padder: Option<CircuitPadder>, ) -> Result<()>

Available on crate feature circ-padding-manual only.

Replace the CircuitPadder installed for this channel with padder.

pub fn new_fake( rt: impl SleepProvider + CoarseTimeProvider, channel_type: ChannelType, ) -> (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.