Struct Circuit 

pub(crate) struct Circuit {

    runtime: DynTimeProvider,
    channel: Arc<Channel>,
    pub(super) chan_sender: CircuitCellSender,
    pub(super) input: Receiver<AnyChanMsg, MpscSpec>,
    crypto_in: InboundClientCrypt,
    crypto_out: OutboundClientCrypt,
    pub(super) hops: CircHopList,
    mutable: Arc<MutableState>,
    channel_id: CircId,
    unique_id: TunnelScopedCircId,
    conflux_handler: Option<ConfluxMsgHandler>,
    padding_ctrl: PaddingController,
    pub(super) padding_event_stream: PaddingEventStream,
    padding_block: Option<StartBlocking>,
    timeouts: Arc<dyn TimeoutEstimator>,
    memquota: CircuitAccount,
}

A circuit “leg” from a tunnel.

Regular (non-multipath) circuits have a single leg. Conflux (multipath) circuits have N (usually, N = 2).

Fields

runtime: DynTimeProvider

The time provider.

channel: Arc<Channel>

The channel this circuit is attached to.

chan_sender: CircuitCellSender

Sender object used to actually send cells.

NOTE: Control messages could potentially add unboundedly to this, although that’s not likely to happen (and isn’t triggereable from the network, either).

input: Receiver<AnyChanMsg, MpscSpec>

Input stream, on which we receive ChanMsg objects from this circuit’s channel.

crypto_in: InboundClientCrypt

The cryptographic state for this circuit for inbound cells. This object is divided into multiple layers, each of which is shared with one hop of the circuit.

crypto_out: OutboundClientCrypt

The cryptographic state for this circuit for outbound cells.

hops: CircHopList

List of hops state objects used by the reactor

mutable: Arc<MutableState>

Mutable information about this circuit, shared with the reactor’s ConfluxSet.

channel_id: CircId

This circuit’s identifier on the upstream channel.

unique_id: TunnelScopedCircId

An identifier for logging about this reactor’s circuit.

conflux_handler: Option<ConfluxMsgHandler>

A handler for conflux cells.

Set once the conflux handshake is initiated by the reactor using Reactor::handle_link_circuits.

padding_ctrl: PaddingController

A padding controller to which padding-related events should be reported.

padding_event_stream: PaddingEventStream

An event stream telling us about padding-related events.

padding_block: Option<StartBlocking>

Current rules for blocking traffic, according to the padding controller.

timeouts: Arc<dyn TimeoutEstimator>

The circuit timeout estimator.

Used for computing half-stream expiration.

memquota: CircuitAccount

Memory quota account

Implementations

impl Circuit

pub(super) fn new( runtime: DynTimeProvider, channel: Arc<Channel>, channel_id: CircId, unique_id: TunnelScopedCircId, input: Receiver<AnyChanMsg, MpscSpec>, memquota: CircuitAccount, mutable: Arc<MutableState>, padding_ctrl: PaddingController, padding_event_stream: PaddingEventStream, timeouts: Arc<dyn TimeoutEstimator>, ) -> Self

Create a new non-multipath circuit.

pub(super) fn unique_id(&self) -> UniqId

Return the process-unique identifier of this circuit.

pub(super) fn mutable(&self) -> &Arc<MutableState>

Return the shared mutable state of this circuit.

pub(super) fn add_to_conflux_tunnel( &mut self, tunnel_id: TunnelId, conflux_handler: ConfluxMsgHandler, )

Add this circuit to a multipath tunnel, by associating it with a new TunnelId, and installing a ConfluxMsgHandler on this circuit.

Once this is called, the circuit will be able to handle conflux cells.

pub(super) async fn begin_conflux_link( &mut self, hop: HopNum, cell: AnyRelayMsgOuter, runtime: &DynTimeProvider, ) -> Result<()>

Send a LINK cell to the specified hop.

This must be called after a ConfluxMsgHandler is installed on the circuit with add_to_conflux_tunnel.

pub(super) fn conflux_hs_timeout(&self) -> Option<SystemTime>

Get the wallclock time when the handshake on this circuit is supposed to time out.

Returns None if the handshake is not currently in progress.

fn encode_relay_cell( crypto_out: &mut OutboundClientCrypt, relay_format: RelayCellFormat, hop: HopNum, early: bool, msg: AnyRelayMsgOuter, ) -> Result<(AnyChanMsg, SendmeTag)>

Encode msg and encrypt it, returning the resulting cell and tag that should be expected for an authenticated SENDME sent in response to that cell.

pub(super) async fn send_relay_cell(&mut self, msg: SendRelayCell) -> Result<()>

Encode msg, encrypt it, and send it to the ’hop’th hop.

If there is insufficient outgoing circuit-level or stream-level SENDME window, an error is returned instead.

Does not check whether the cell is well-formed or reasonable.

NOTE: the reactor should not call this function directly, only via ConfluxSet::send_relay_cell_on_leg, which will reroute the message, if necessary to the primary leg.

async fn send_relay_cell_inner( &mut self, msg: SendRelayCell, padding_info: Option<QueuedCellPaddingInfo>, ) -> Result<()>

As send_relay_cell, but takes an optional QueuedCellPaddingInfo in padding_info.

If padding_info is None, msg must be non-padding: we report it as such to the padding controller.

pub(super) fn handle_cell( &mut self, handlers: &mut CellHandlers, leg: UniqId, cell: ClientCircChanMsg, ) -> Result<Vec<CircuitCmd>>

Helper: process a cell on a channel. Most cells get ignored or rejected; a few get delivered to circuits.

Return CellStatus::CleanShutdown if we should exit.

fn decode_relay_cell( &mut self, cell: Relay, ) -> Result<(HopNum, SendmeTag, RelayCellDecoderResult)>

Decode cell, returning its corresponding hop number, tag, and decoded body.

fn handle_relay_cell( &mut self, handlers: &mut CellHandlers, leg: UniqId, cell: Relay, ) -> Result<Vec<CircuitCmd>>

React to a Relay or RelayEarly cell.

fn handle_relay_msg( &mut self, handlers: &mut CellHandlers, hopnum: HopNum, leg: UniqId, cell_counts_toward_windows: bool, msg: UnparsedRelayMsg, ) -> Result<Option<CircuitCmd>>

Handle a single incoming relay message.

pub(super) fn handle_in_order_relay_msg( &mut self, handlers: &mut CellHandlers, hopnum: HopNum, leg: UniqId, cell_counts_toward_windows: bool, streamid: StreamId, msg: UnparsedRelayMsg, ) -> Result<Option<CircuitCmd>>

Handle a single incoming relay message that is known to be in order.

fn handle_conflux_msg( &mut self, hop: HopNum, msg: UnparsedRelayMsg, ) -> Result<Option<ConfluxCmd>>

Handle a conflux message coming from the specified hop.

Returns an error if

• this is not a conflux circuit (i.e. it doesn’t have a ConfluxMsgHandler)
• this is a client circuit and the conflux message originated an unexpected hop
• the cell was sent in violation of the handshake protocol

pub(super) fn last_seq_sent(&self) -> Result<u64>

For conflux: return the sequence number of the last cell sent on this leg.

Returns an error if this circuit is not part of a conflux set.

pub(super) fn set_last_seq_sent(&mut self, n: u64) -> Result<()>

For conflux: set the sequence number of the last cell sent on this leg.

Returns an error if this circuit is not part of a conflux set.

pub(super) fn last_seq_recv(&self) -> Result<u64>

For conflux: return the sequence number of the last cell received on this leg.

Returns an error if this circuit is not part of a conflux set.

fn handle_incoming_stream_request( &mut self, handlers: &mut CellHandlers, msg: UnparsedRelayMsg, stream_id: StreamId, hop_num: HopNum, leg: UniqId, ) -> Result<Option<CircuitCmd>>

A helper for handling incoming stream requests.

fn handle_destroy_cell(&mut self) -> Result<CircuitCmd>

Helper: process a destroy cell.

pub(super) async fn handle_create( &mut self, recv_created: Receiver<CreateResponse>, handshake: CircuitHandshake, settings: HopSettings, done: Sender<Result<()>>, ) -> StdResult<(), ReactorError>

Handle a CtrlMsg::Create message.

async fn create_impl<H, W, M>( &mut self, recvcreated: Receiver<CreateResponse>, wrap: &W, key: &H::KeyType, settings: HopSettings, msg: &M, ) -> Result<()>

where H: ClientHandshake + HandshakeAuxDataHandler, W: CreateHandshakeWrap, H::KeyGen: KeyGenerator, M: Borrow<H::ClientAuxData>,

Helper: create the first hop of a circuit.

This is parameterized not just on the RNG, but a wrapper object to build the right kind of create cell, and a handshake object to perform the cryptographic handshake.

async fn create_firsthop_fast( &mut self, recvcreated: Receiver<CreateResponse>, settings: HopSettings, ) -> Result<()>

Use the (questionable!) CREATE_FAST handshake to connect to the first hop of this circuit.

There’s no authentication in CREATE_FAST, so we don’t need to know whom we’re connecting to: we’re just connecting to whichever relay the channel is for.

async fn create_firsthop_ntor( &mut self, recvcreated: Receiver<CreateResponse>, ed_identity: Ed25519Identity, pubkey: NtorPublicKey, settings: HopSettings, ) -> Result<()>

Use the ntor handshake to connect to the first hop of this circuit.

Note that the provided keys must match the channel’s target, or the handshake will fail.

async fn create_firsthop_ntor_v3( &mut self, recvcreated: Receiver<CreateResponse>, pubkey: NtorV3PublicKey, settings: HopSettings, ) -> Result<()>

Use the ntor-v3 handshake to connect to the first hop of this circuit.

Note that the provided key must match the channel’s target, or the handshake will fail.

pub(super) fn add_hop( &mut self, peer_id: HopDetail, fwd: Box<dyn OutboundClientLayer + Send + 'static>, rev: Box<dyn InboundClientLayer + Send + 'static>, binding: Option<CircuitBinding>, settings: &HopSettings, ) -> StdResult<(), Bug>

Add a hop to the end of this circuit.

Will return an error if the circuit already has u8::MAX hops.

fn handle_meta_cell( &mut self, handlers: &mut CellHandlers, hopnum: HopNum, msg: UnparsedRelayMsg, ) -> Result<Option<CircuitCmd>>

Handle a RELAY cell on this circuit with stream ID 0.

NOTE(prop349): this is part of Arti’s “Base Circuit Hop Handler”. This function returns a CircProto error if msg is an unsupported, unexpected, or otherwise invalid message:

• unexpected messages are rejected by returning an error using unsupported_client_cell
• SENDME/TRUNCATED messages are rejected if they don’t parse
• SENDME authentication tags are validated inside Circuit::handle_sendme
• conflux cells are handled in the client ConfluxMsgHandler

The error is propagated all the way up to Circuit::handle_cell, and eventually ends up being returned from the reactor’s run_once function, causing it to shut down.

pub(super) fn handle_sendme( &mut self, hopnum: HopNum, msg: Sendme, signals: CongestionSignals, ) -> Result<Option<CircuitCmd>>

Handle a RELAY_SENDME cell on this circuit with stream ID 0.

async fn send_msg( &mut self, msg: AnyChanMsg, info: Option<QueuedCellPaddingInfo>, ) -> Result<()>

Send a message onto the circuit’s channel.

If the channel is ready to accept messages, it will be sent immediately. If not, the message will be enqueued for sending at a later iteration of the reactor loop.

info is the status returned from the padding controller when we told it we were queueing this data. It should be provided whenever possible.

Note

Making use of the enqueuing capabilities of this function is discouraged! You should first check whether the channel is ready to receive messages (self.channel.poll_ready), and ideally use this to implement backpressure (such that you do not read from other sources that would send here while you know you’re unable to forward the messages on).

pub(super) fn remove_expired_halfstreams(&mut self, now: Instant)

Remove all halfstreams that are expired at now.

pub(super) fn hop(&self, hopnum: HopNum) -> Option<&CircHop>

Return a reference to the hop corresponding to hopnum, if there is one.

pub(super) fn hop_mut(&mut self, hopnum: HopNum) -> Option<&mut CircHop>

Return a mutable reference to the hop corresponding to hopnum, if there is one.

pub(super) fn begin_stream( &mut self, hop_num: HopNum, message: AnyRelayMsg, sender: StreamQueueSender, rx: Receiver<AnyRelayMsg, MpscSpec>, rate_limit_notifier: Sender<StreamRateLimit>, drain_rate_requester: NotifySender<DrainRateRequest>, cmd_checker: Box<dyn CmdChecker + Send + 'static>, ) -> StdResult<Result<(SendRelayCell, StreamId)>, Bug>

Begin a stream with the provided hop in this circuit.

pub(super) async fn close_stream( &mut self, hop_num: HopNum, sid: StreamId, behav: CloseStreamBehavior, reason: TerminateReason, expiry: Instant, ) -> Result<()>

Close the specified stream

pub(super) fn has_streams(&self) -> bool

Returns true if there are any streams on this circuit

Important: this function locks the stream map of its each of the CircHops in this circuit, so it must not be called from any function where the stream map lock is held.

pub(super) fn num_hops(&self) -> u8

The number of hops in this circuit.

pub(super) fn has_hops(&self) -> bool

Check whether this circuit has any hops.

pub(super) fn last_hop_num(&self) -> Option<HopNum>

Get the HopNum of the last hop, if this circuit is non-empty.

Returns None if the circuit has no hops.

pub(super) fn path(&self) -> Arc<Path>

Get the path of the circuit.

Warning: Do not call while already holding the Self::mutable lock.

pub(super) 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(super) fn uses_stream_sendme(&self, hop: HopNum) -> Option<bool>

Does congestion control use stream SENDMEs for the given hop?

Returns None if hop doesn’t exist.

pub(super) fn is_conflux_pending(&self) -> bool

Returns whether this is a conflux circuit that is not linked yet.

pub(super) fn conflux_status(&self) -> Option<ConfluxStatus>

Returns the conflux status of this circuit.

Returns None if this is not a conflux circuit.

pub(super) fn init_rtt(&self) -> Option<Duration>

Returns initial RTT on this leg, measured in the conflux handshake.

pub(super) fn set_padding_at_hop( &self, hop: HopNum, padder: Option<CircuitPadder>, ) -> Result<()>

Start or stop padding at the given hop.

Replaces any previous padder at that hop.

Return an error if that hop doesn’t exist.

fn padding_disposition( &self, send_padding: &SendPadding, ) -> CircPaddingDisposition

Determine how exactly to handle a request to handle padding.

This is fairly complicated; see the maybenot documentation for more information.

Limitations

In our current padding implementation, a circuit is either blocked or not blocked: we do not keep track of which hop is actually doing the blocking.

pub(super) async fn send_padding( &mut self, send_padding: SendPadding, ) -> Result<()>

Handle a request from our padding subsystem to send a padding packet.

async fn queue_padding_cell_for_hop( &mut self, target_hop: HopNum, queue_info: Option<QueuedCellPaddingInfo>, ) -> Result<()>

Generate and encrypt a padding cell, and send it to a targeted hop.

Ignores any padding-based blocking.

pub(super) fn start_blocking_for_padding(&mut self, block: StartBlocking)

Enable padding-based blocking, or change the rule for padding-based blocking to the one in block.

pub(super) fn stop_blocking_for_padding(&mut self)

Disable padding-based blocking.

pub(super) fn estimate_cbt(&self, length: usize) -> Duration

The estimated circuit build timeout for a circuit of the specified length.

Trait Implementations

impl Drop for Circuit

fn drop(&mut self)

Executes the destructor for this type.