//! Multi-hop paths over the Tor network.

//!

//! Right now, we only implement "client circuits" -- also sometimes

//! called "origin circuits".  A client circuit is one that is

//! constructed by this Tor instance, and used in its own behalf to

//! send data over the Tor network.

//!

//! Each circuit has multiple hops over the Tor network: each hop

//! knows only the hop before and the hop after.  The client shares a

//! separate set of keys with each hop.

//!

//! To build a circuit, first create a [crate::channel::Channel], then

//! call its [crate::channel::Channel::new_circ] method.  This yields

//! a [PendingClientCirc] object that won't become live until you call

//! one of the methods

//! (typically [`PendingClientCirc::create_firsthop`])

//! that extends it to its first hop.  After you've

//! done that, you can call [`ClientCirc::extend`] on the circuit to

//! build it into a multi-hop circuit.  Finally, you can use

//! [ClientCirc::begin_stream] to get a Stream object that can be used

//! for anonymized data.

//!

//! # Implementation

//!

//! Each open circuit has a corresponding Reactor object that runs in

//! an asynchronous task, and manages incoming cells from the

//! circuit's upstream channel.  These cells are either RELAY cells or

//! DESTROY cells.  DESTROY cells are handled immediately.

//! RELAY cells are either for a particular stream, in which case they

//! get forwarded to a RawCellStream object, or for no particular stream,

//! in which case they are considered "meta" cells (like EXTENDED2)

//! that should only get accepted if something is waiting for them.

//!

//! # Limitations

//!

//! This is client-only.

pub(crate) mod celltypes;

pub(crate) mod halfcirc;

#[cfg(feature = "hs-common")]

pub mod handshake;

#[cfg(not(feature = "hs-common"))]

pub(crate) mod handshake;

pub(super) mod path;

pub(crate) mod unique_id;

use crate::channel::Channel;

use crate::congestion::params::CongestionControlParams;

use crate::crypto::cell::HopNum;

use crate::crypto::handshake::ntor_v3::NtorV3PublicKey;

use crate::memquota::{CircuitAccount, SpecificAccount as _};

use crate::stream::queue::stream_queue;

use crate::stream::xon_xoff::XonXoffReaderCtrl;

use crate::stream::{

    AnyCmdChecker, DataCmdChecker, DataStream, ResolveCmdChecker, ResolveStream, StreamParameters,

    StreamRateLimit, StreamReceiver,

};

use crate::tunnel::circuit::celltypes::*;

use crate::tunnel::reactor::CtrlCmd;

use crate::tunnel::reactor::{

    CircuitHandshake, CtrlMsg, Reactor, RECV_WINDOW_INIT, STREAM_READER_BUFFER,

};

use crate::tunnel::{StreamTarget, TargetHop};

use crate::util::notify::NotifySender;

use crate::util::skew::ClockSkew;

use crate::{Error, ResolveError, Result};

use educe::Educe;

use path::HopDetail;

use postage::watch;

use tor_cell::{

    chancell::CircId,

    relaycell::msg::{AnyRelayMsg, Begin, Resolve, Resolved, ResolvedVal},

};

use tor_error::{bad_api_usage, internal, into_internal};

use tor_linkspec::{CircTarget, LinkSpecType, OwnedChanTarget, RelayIdType};

use tor_protover::named;

pub use crate::crypto::binding::CircuitBinding;

pub use crate::memquota::StreamAccount;

pub use crate::tunnel::circuit::unique_id::UniqId;

#[cfg(feature = "hs-service")]

use {

    crate::stream::{IncomingCmdChecker, IncomingStream},

    crate::tunnel::reactor::StreamReqInfo,

};

use futures::channel::mpsc;

use oneshot_fused_workaround as oneshot;

use crate::congestion::sendme::StreamRecvWindow;

use crate::DynTimeProvider;

use futures::FutureExt as _;

use std::collections::HashMap;

use std::net::IpAddr;

use std::sync::{Arc, Mutex};

use tor_memquota::mq_queue::{self, ChannelSpec as _, MpscSpec};

use crate::crypto::handshake::ntor::NtorPublicKey;

pub use path::{Path, PathEntry};

/// The size of the buffer for communication between `ClientCirc` and its reactor.

pub const CIRCUIT_BUFFER_SIZE: usize = 128;

#[cfg(feature = "send-control-msg")]

use {crate::tunnel::msghandler::UserMsgHandler, crate::tunnel::reactor::MetaCellHandler};

pub use crate::tunnel::reactor::syncview::ClientCircSyncView;

#[cfg(feature = "send-control-msg")]

#[cfg_attr(docsrs, doc(cfg(feature = "send-control-msg")))]

pub use {crate::tunnel::msghandler::MsgHandler, crate::tunnel::reactor::MetaCellDisposition};

/// MPSC queue relating to a stream (either inbound or outbound), sender

pub(crate) type StreamMpscSender<T> = mq_queue::Sender<T, MpscSpec>;

/// MPSC queue relating to a stream (either inbound or outbound), receiver

pub(crate) type StreamMpscReceiver<T> = mq_queue::Receiver<T, MpscSpec>;

/// MPSC queue for inbound data on its way from channel to circuit, sender

pub(crate) type CircuitRxSender = mq_queue::Sender<ClientCircChanMsg, MpscSpec>;

/// MPSC queue for inbound data on its way from channel to circuit, receiver

pub(crate) type CircuitRxReceiver = mq_queue::Receiver<ClientCircChanMsg, MpscSpec>;

#[derive(Debug)]

/// A circuit that we have constructed over the Tor network.

///

/// # Circuit life cycle

///

/// `ClientCirc`s are created in an initially unusable state using [`Channel::new_circ`],

/// which returns a [`PendingClientCirc`].  To get a real (one-hop) circuit from

/// one of these, you invoke one of its `create_firsthop` methods (typically

/// [`create_firsthop_fast()`](PendingClientCirc::create_firsthop_fast) or

/// [`create_firsthop()`](PendingClientCirc::create_firsthop)).

/// Then, to add more hops to the circuit, you can call

/// [`extend()`](ClientCirc::extend) on it.

///

/// For higher-level APIs, see the `tor-circmgr` crate: the ones here in

/// `tor-proto` are probably not what you need.

///

/// After a circuit is created, it will persist until it is closed in one of

/// five ways:

///    1. A remote error occurs.

///    2. Some hop on the circuit sends a `DESTROY` message to tear down the

///       circuit.

///    3. The circuit's channel is closed.

///    4. Someone calls [`ClientCirc::terminate`] on the circuit.

///    5. The last reference to the `ClientCirc` is dropped. (Note that every stream

///       on a `ClientCirc` keeps a reference to it, which will in turn keep the

///       circuit from closing until all those streams have gone away.)

///

/// Note that in cases 1-4 the [`ClientCirc`] object itself will still exist: it

/// will just be unusable for most purposes.  Most operations on it will fail

/// with an error.

//

// Effectively, this struct contains two Arcs: one for `path` and one for

// `control` (which surely has something Arc-like in it).  We cannot unify

// these by putting a single Arc around the whole struct, and passing

// an Arc strong reference to the `Reactor`, because then `control` would

// not be dropped when the last user of the circuit goes away.  We could

// make the reactor have a weak reference but weak references are more

// expensive to dereference.

//

// Because of the above, cloning this struct is always going to involve

// two atomic refcount changes/checks.  Wrapping it in another Arc would

// be overkill.

//

pub struct ClientCirc {

    /// Mutable state shared with the `Reactor`.

    mutable: Arc<TunnelMutableState>,

    /// A unique identifier for this circuit.

    unique_id: UniqId,

    /// Channel to send control messages to the reactor.

    pub(super) control: mpsc::UnboundedSender<CtrlMsg>,

    /// Channel to send commands to the reactor.

    pub(super) command: mpsc::UnboundedSender<CtrlCmd>,

    /// A future that resolves to Cancelled once the reactor is shut down,

    /// meaning that the circuit is closed.

    #[cfg_attr(not(feature = "experimental-api"), allow(dead_code))]

    reactor_closed_rx: futures::future::Shared<oneshot::Receiver<void::Void>>,

    /// For testing purposes: the CircId, for use in peek_circid().

    #[cfg(test)]

    circid: CircId,

    /// Memory quota account

    memquota: CircuitAccount,

    /// Time provider

    time_provider: DynTimeProvider,

}

/// The mutable state of a tunnel, shared between [`ClientCirc`] and [`Reactor`].

///

/// NOTE(gabi): this mutex-inside-a-mutex might look suspicious,

/// but it is currently the best option we have for sharing

/// the circuit state with `ClientCirc` (and soon, with `ClientTunnel`).

/// In practice, these mutexes won't be accessed very often

/// (they're accessed for writing when a circuit is extended,

/// and for reading by the various `ClientCirc` APIs),

/// so they shouldn't really impact performance.

///

/// Alternatively, the circuit state information could be shared

/// outside the reactor through a channel (passed to the reactor via a `CtrlCmd`),

/// but in #1840 @opara notes that involves making the `ClientCirc` accessors

/// (`ClientCirc::path`, `ClientCirc::binding_key`, etc.)

/// asynchronous, which will significantly complicate their callsites,

/// which would in turn need to be made async too.

///

/// We should revisit this decision at some point, and decide whether an async API

/// would be preferable.

#[derive(Debug, Default)]

pub(super) struct TunnelMutableState(Mutex<HashMap<UniqId, Arc<MutableState>>>);

impl TunnelMutableState {

    /// Add the [`MutableState`] of a circuit.

    /// Remove the [`MutableState`] of a circuit.

    /// Return a [`Path`] object describing all the hops in the specified circuit.

    ///

    /// See [`MutableState::path`].

    /// Return a description of the first hop of this circuit.

    ///

    /// Returns an error if a circuit with the specified [`UniqId`] doesn't exist.

    /// Returns `Ok(None)` if the specified circuit doesn't have any hops.

            #[cfg(feature = "hs-common")]

            path::HopDetail::Virtual => {

            }

    /// Return the [`HopNum`] of the last hop of the specified circuit.

    ///

    /// Returns an error if a circuit with the specified [`UniqId`] doesn't exist.

    ///

    /// See [`MutableState::last_hop_num`].

    /// Return the number of hops in the specified circuit.

    ///

    /// See [`MutableState::n_hops`].

    /// Return the number of legs in this tunnel.

    ///

    /// TODO(conflux-fork): this can be removed once we modify `path_ref`

    /// to return *all* the Paths in the tunnel.

}

/// The mutable state of a circuit.

#[educe(Debug)]

pub(super) struct MutableState(Mutex<CircuitState>);

impl MutableState {

    /// Add a hop to the path of this circuit.

    /// Get a copy of the circuit's current [`path::Path`].

    /// Return the cryptographic material used to prove knowledge of a shared

    /// secret with with `hop`.

    /// Return a description of the first hop of this circuit.

    /// Return the [`HopNum`] of the last hop of this circuit.

    ///

    /// NOTE: This function will return the [`HopNum`] of the hop

    /// that is _currently_ the last. If there is an extend operation in progress,

    /// the currently pending hop may or may not be counted, depending on whether

    /// the extend operation finishes before this call is done.

    /// Return the number of hops in this circuit.

    ///

    /// NOTE: This function will currently return only the number of hops

    /// _currently_ in the circuit. If there is an extend operation in progress,

    /// the currently pending hop may or may not be counted, depending on whether

    /// the extend operation finishes before this call is done.

}

/// The shared state of a circuit.

#[educe(Debug)]

pub(super) struct CircuitState {

    /// Information about this circuit's path.

    ///

    /// This is stored in an Arc so that we can cheaply give a copy of it to

    /// client code; when we need to add a hop (which is less frequent) we use

    /// [`Arc::make_mut()`].

    path: Arc<path::Path>,

    /// Circuit binding keys [q.v.][`CircuitBinding`] information for each hop

    /// in the circuit's path.

    ///

    /// NOTE: Right now, there is a `CircuitBinding` for every hop.  There's a

    /// fair chance that this will change in the future, and I don't want other

    /// code to assume that a `CircuitBinding` _must_ exist, so I'm making this

    /// an `Option`.

    #[educe(Debug(ignore))]

    binding: Vec<Option<CircuitBinding>>,

}

/// A ClientCirc that needs to send a create cell and receive a created* cell.

///

/// To use one of these, call `create_firsthop_fast()` or `create_firsthop()`

/// to negotiate the cryptographic handshake with the first hop.

pub struct PendingClientCirc {

    /// A oneshot receiver on which we'll receive a CREATED* cell,

    /// or a DESTROY cell.

    recvcreated: oneshot::Receiver<CreateResponse>,

    /// The ClientCirc object that we can expose on success.

    circ: Arc<ClientCirc>,

}

/// Description of the network's current rules for building circuits.

///

/// This type describes rules derived from the consensus,

/// and possibly amended by our own configuration.

///

/// Typically, this type created once for an entire circuit,

/// and any special per-hop information is derived

/// from each hop as a CircTarget.

/// Note however that callers _may_ provide different `CircParameters`

/// for different hops within a circuit if they have some reason to do so,

/// so we do not enforce that every hop in a circuit has the same `CircParameters`.

#[non_exhaustive]

#[derive(Clone, Debug)]

pub struct CircParameters {

    /// Whether we should include ed25519 identities when we send

    /// EXTEND2 cells.

    pub extend_by_ed25519_id: bool,

    /// Congestion control parameters for this circuit.

    pub ccontrol: CongestionControlParams,

    /// Maximum number of permitted incoming relay cells for each hop.

    ///

    /// If we would receive more relay cells than this from a single hop,

    /// we close the circuit with [`ExcessInboundCells`](Error::ExcessInboundCells).

    ///

    /// If this value is None, then there is no limit to the number of inbound cells.

    ///

    /// Known limitation: If this value if `u32::MAX`,

    /// then a limit of `u32::MAX - 1` is enforced.

    pub n_incoming_cells_permitted: Option<u32>,

    /// Maximum number of permitted outgoing relay cells for each hop.

    ///

    /// If we would try to send more relay cells than this from a single hop,

    /// we close the circuit with [`ExcessOutboundCells`](Error::ExcessOutboundCells).

    /// It is the circuit-user's responsibility to make sure that this does not happen.

    ///

    /// This setting is used to ensure that we do not violate a limit

    /// imposed by `n_incoming_cells_permitted`

    /// on the other side of a circuit.

    ///

    /// If this value is None, then there is no limit to the number of outbound cells.

    ///

    /// Known limitation: If this value if `u32::MAX`,

    /// then a limit of `u32::MAX - 1` is enforced.

    pub n_outgoing_cells_permitted: Option<u32>,

}

/// The settings we use for single hop of a circuit.

///

/// Unlike [`CircParameters`], this type is crate-internal.

/// We construct it based on our settings from the circuit,

/// and from the hop's actual capabilities.

/// Then, we negotiate with the hop as part of circuit

/// creation/extension to determine the actual settings that will be in use.

/// Finally, we use those settings to construct the negotiated circuit hop.

//

// TODO: Relays should probably derive an instance of this type too, as

// part of the circuit creation handshake.

#[derive(Clone, Debug)]

pub(super) struct HopSettings {

    /// The negotiated congestion control settings for this circuit.

    pub(super) ccontrol: CongestionControlParams,

    /// Maximum number of permitted incoming relay cells for this hop.

    pub(super) n_incoming_cells_permitted: Option<u32>,

    /// Maximum number of permitted outgoing relay cells for this hop.

    pub(super) n_outgoing_cells_permitted: Option<u32>,

}

impl HopSettings {

    /// Construct a new `HopSettings` based on `params` (a set of circuit parameters)

    /// and `caps` (a set of protocol capabilities for a circuit target).

    ///

    /// The resulting settings will represent what the client would prefer to negotiate

    /// (determined by `params`),

    /// as modified by what the target relay is believed to support (represented by `caps`).

    ///

    /// This represents the `HopSettings` in a pre-negotiation state:

    /// the circuit negotiation process will modify it.

    #[allow(clippy::unnecessary_wraps)] // likely to become fallible in the future.

            crate::ccparams::Algorithm::Vegas(_) => {

                // If the target doesn't support FLOWCTRL_CC, we can't use Vegas.

            }

        }

    /// Return a new `HopSettings` based on this one,

    /// representing the settings that we should use

    /// if circuit negotiation will be impossible.

    ///

    /// (Circuit negotiation is impossible when using the legacy ntor protocol,

    /// and when using CRATE_FAST.  It is currently unsupported with virtual hops.)

}

#[cfg(test)]

impl std::default::Default for CircParameters {

}

impl CircParameters {

    /// Constructor

}

impl ClientCirc {

    /// Return a description of the first hop of this circuit.

    ///

    /// # Panics

    ///

    /// Panics if there is no first hop.  (This should be impossible outside of

    /// the tor-proto crate, but within the crate it's possible to have a

    /// circuit with no hops.)

    /// Return a description of the last hop of the circuit.

    ///

    /// Return None if the last hop is virtual.

    ///

    /// See caveats on [`ClientCirc::last_hop_num()`].

    ///

    /// # Panics

    ///

    /// Panics if there is no last hop.  (This should be impossible outside of

    /// the tor-proto crate, but within the crate it's possible to have a

    /// circuit with no hops.)

    /// Return the [`HopNum`] of the last hop of this circuit.

    ///

    /// Returns an error if there is no last hop.  (This should be impossible outside of the

    /// tor-proto crate, but within the crate it's possible to have a circuit with no hops.)

    ///

    /// NOTE: This function will return the [`HopNum`] of the hop

    /// that is _currently_ the last. If there is an extend operation in progress,

    /// the currently pending hop may or may not be counted, depending on whether

    /// the extend operation finishes before this call is done.

    /// Return a [`TargetHop`] representing precisely the last hop of the circuit as in set as a

    /// HopLocation with its id and hop number.

    ///

    /// Return an error if there is no last hop.

    /// Return a [`Path`] object describing all the hops in this circuit.

    ///

    /// Note that this `Path` is not automatically updated if the circuit is

    /// extended.

    /// Get the clock skew claimed by the first hop of the circuit.

    ///

    /// See [`Channel::clock_skew()`].

    /// Return a reference to this circuit's memory quota account

    /// Return the cryptographic material used to prove knowledge of a shared

    /// secret with with `hop`.

    ///

    /// See [`CircuitBinding`] for more information on how this is used.

    ///

    /// Return None if we have no circuit binding information for the hop, or if

    /// the hop does not exist.

    #[cfg(feature = "hs-service")]

    /// Start an ad-hoc protocol exchange to the specified hop on this circuit

    ///

    /// To use this:

    ///

    ///  0. Create an inter-task channel you'll use to receive

    ///     the outcome of your conversation,

    ///     and bundle it into a [`MsgHandler`].

    ///

    ///  1. Call `start_conversation`.

    ///     This will install a your handler, for incoming messages,

    ///     and send the outgoing message (if you provided one).

    ///     After that, each message on the circuit

    ///     that isn't handled by the core machinery

    ///     is passed to your provided `reply_handler`.

    ///

    ///  2. Possibly call `send_msg` on the [`Conversation`],

    ///     from the call site of `start_conversation`,

    ///     possibly multiple times, from time to time,

    ///     to send further desired messages to the peer.

    ///

    ///  3. In your [`MsgHandler`], process the incoming messages.

    ///     You may respond by

    ///     sending additional messages

    ///     When the protocol exchange is finished,

    ///     `MsgHandler::handle_msg` should return

    ///     [`ConversationFinished`](MetaCellDisposition::ConversationFinished).

    ///

    /// If you don't need the `Conversation` to send followup messages,

    /// you may simply drop it,

    /// and rely on the responses you get from your handler,

    /// on the channel from step 0 above.

    /// Your handler will remain installed and able to process incoming messages

    /// until it returns `ConversationFinished`.

    ///

    /// (If you don't want to accept any replies at all, it may be

    /// simpler to use [`ClientCirc::send_raw_msg`].)

    ///

    /// Note that it is quite possible to use this function to violate the tor

    /// protocol; most users of this API will not need to call it.  It is used

    /// to implement most of the onion service handshake.

    ///

    /// # Limitations

    ///

    /// Only one conversation may be active at any one time,

    /// for any one circuit.

    /// This generally means that this function should not be called

    /// on a circuit which might be shared with anyone else.

    ///

    /// Likewise, it is forbidden to try to extend the circuit,

    /// while the conversation is in progress.

    ///

    /// After the conversation has finished, the circuit may be extended.

    /// Or, `start_conversation` may be called again;

    /// but, in that case there will be a gap between the two conversations,

    /// during which no `MsgHandler` is installed,

    /// and unexpected incoming messages would close the circuit.

    ///

    /// If these restrictions are violated, the circuit will be closed with an error.

    ///

    /// ## Precise definition of the lifetime of a conversation

    ///

    /// A conversation is in progress from entry to `start_conversation`,

    /// until entry to the body of the [`MsgHandler::handle_msg`]

    /// call which returns [`ConversationFinished`](MetaCellDisposition::ConversationFinished).

    /// (*Entry* since `handle_msg` is synchronously embedded

    /// into the incoming message processing.)

    /// So you may start a new conversation as soon as you have the final response

    /// via your inter-task channel from (0) above.

    ///

    /// The lifetime relationship of the [`Conversation`],

    /// vs the handler returning `ConversationFinished`

    /// is not enforced by the type system.

    // Doing so without still leaving plenty of scope for runtime errors doesn't seem possible,

    // at least while allowing sending followup messages from outside the handler.

    //

    // TODO hs: it might be nice to avoid exposing tor-cell APIs in the

    //   tor-proto interface.

    #[cfg(feature = "send-control-msg")]

    /// Send an ad-hoc message to a given hop on the circuit, without expecting

    /// a reply.

    ///

    /// (If you want to handle one or more possible replies, see

    /// [`ClientCirc::start_conversation`].)

    #[cfg(feature = "send-control-msg")]

    /// Tell this circuit to begin allowing the final hop of the circuit to try

    /// to create new Tor streams, and to return those pending requests in an

    /// asynchronous stream.

    ///

    /// Ordinarily, these requests are rejected.

    ///

    /// There can only be one [`Stream`](futures::Stream) of this type created on a given circuit.

    /// If a such a [`Stream`](futures::Stream) already exists, this method will return

    /// an error.

    ///

    /// After this method has been called on a circuit, the circuit is expected

    /// to receive requests of this type indefinitely, until it is finally closed.

    /// If the `Stream` is dropped, the next request on this circuit will cause it to close.

    ///

    /// Only onion services (and eventually) exit relays should call this

    /// method.

    //

    // TODO: Someday, we might want to allow a stream request handler to be

    // un-registered.  However, nothing in the Tor protocol requires it.

    #[cfg(feature = "hs-service")]

        use futures::stream::StreamExt;

        /// The size of the channel receiving IncomingStreamRequestContexts.

        const INCOMING_BUFFER: usize = STREAM_READER_BUFFER;

        // TODO(#2002): support onion service conflux

        // Check whether the AwaitStreamRequest was processed successfully.

        }

            // TODO(#2002): figure out what this is going to look like

            // for onion services (perhaps we should forbid this function

            // from being called on a multipath circuit?)

            //

            // See also:

            // https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/3002#note_3200937

    /// Extend the circuit, via the most appropriate circuit extension handshake,

    /// to the chosen `target` hop.

        {

        } else {

        }

    /// Extend the circuit via the ntor handshake to a new target last

    /// hop.

        };

    /// Extend the circuit via the ntor handshake to a new target last

    /// hop.

        };

    /// Extend this circuit by a single, "virtual" hop.

    ///

    /// A virtual hop is one for which we do not add an actual network connection

    /// between separate hosts (such as Relays).  We only add a layer of

    /// cryptography.

    ///

    /// This is used to implement onion services: the client and the service

    /// both build a circuit to a single rendezvous point, and tell the

    /// rendezvous point to relay traffic between their two circuits.  Having

    /// completed a [`handshake`] out of band[^1], the parties each extend their

    /// circuits by a single "virtual" encryption hop that represents their

    /// shared cryptographic context.

    ///

    /// Once a circuit has been extended in this way, it is an error to try to

    /// extend it in any other way.

    ///

    /// [^1]: Technically, the handshake is only _mostly_ out of band: the

    ///     client sends their half of the handshake in an ` message, and the

    ///     service's response is inline in its `RENDEZVOUS2` message.

    //

    // TODO hs: let's try to enforce the "you can't extend a circuit again once

    // it has been extended this way" property.  We could do that with internal

    // state, or some kind of a type state pattern.

    #[cfg(feature = "hs-common")]

        use self::handshake::BoxedClientLayer;

            // TODO #2037: We _should_ support negotiation here; see #2037.

    /// Helper, used to begin a stream.

    ///

    /// This function allocates a stream ID, and sends the message

    /// (like a BEGIN or RESOLVE), but doesn't wait for a response.

    ///

    /// The caller will typically want to see the first cell in response,

    /// to see whether it is e.g. an END or a CONNECTED.

    /// Start a DataStream (anonymized connection) to the given

    /// address and port, using a BEGIN cell.

        let StreamComponents {

    /// Start a stream to the given address and port, using a BEGIN

    /// cell.

    ///

    /// The use of a string for the address is intentional: you should let

    /// the remote Tor relay do the hostname lookup for you.

        } else {

        };

    /// Start a new stream to the last relay in the circuit, using

    /// a BEGIN_DIR cell.

    /// Perform a DNS lookup, using a RESOLVE cell with the last relay

    /// in this circuit.

    ///

    /// Note that this function does not check for timeouts; that's

    /// the caller's responsibility.

    /// Perform a reverse DNS lookup, by sending a RESOLVE cell with

    /// the last relay on this circuit.

    ///

    /// Note that this function does not check for timeouts; that's

    /// the caller's responsibility.

    /// Helper: Send the resolve message, and read resolved message from

    /// resolve stream.

        let StreamComponents {

    /// Shut down this circuit, along with all streams that are using it.

    /// Happens asynchronously (i.e. the circuit won't necessarily be done shutting down

    /// immediately after this function returns!).

    ///

    /// Note that other references to this circuit 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 circuit: the circuit should close on its own once nothing

    /// is using it any more.

    /// Called when a circuit-level protocol error has occurred and the

    /// circuit needs to shut down.

    ///

    /// This is a separate function because we may eventually want to have

    /// it do more than just shut down.

    ///

    /// As with `terminate`, this function is asynchronous.

    /// Return true if this circuit is closed and therefore unusable.

    /// Return a process-unique identifier for this circuit.

    /// Return the number of hops in this circuit.

    ///

    /// NOTE: This function will currently return only the number of hops

    /// _currently_ in the circuit. If there is an extend operation in progress,

    /// the currently pending hop may or may not be counted, depending on whether

    /// the extend operation finishes before this call is done.

    /// Return a future that will resolve once this circuit has closed.

    ///

    /// Note that this method does not itself cause the circuit to shut down.

    ///

    /// TODO: Perhaps this should return some kind of status indication instead

    /// of just ()

    #[cfg(feature = "experimental-api")]

}

/// Handle to use during an ongoing protocol exchange with a circuit's last hop

///

/// This is obtained from [`ClientCirc::start_conversation`],

/// and used to send messages to the last hop relay.

//

// TODO(conflux): this should use ClientTunnel, and it should be moved into

// the tunnel module.

#[cfg(feature = "send-control-msg")]

#[cfg_attr(docsrs, doc(cfg(feature = "send-control-msg")))]

pub struct Conversation<'r>(&'r ClientCirc);

#[cfg(feature = "send-control-msg")]

#[cfg_attr(docsrs, doc(cfg(feature = "send-control-msg")))]

impl Conversation<'_> {

    /// Send a protocol message as part of an ad-hoc exchange

    ///

    /// Responses are handled by the `MsgHandler` set up

    /// when the `Conversation` was created.