Skip to main content

tor_proto/client/
circuit.rs

1//! Multi-hop paths over the Tor network.
2//!
3//! Right now, we only implement "client circuits" -- also sometimes
4//! called "origin circuits".  A client circuit is one that is
5//! constructed by this Tor instance, and used in its own behalf to
6//! send data over the Tor network.
7//!
8//! Each circuit has multiple hops over the Tor network: each hop
9//! knows only the hop before and the hop after.  The client shares a
10//! separate set of keys with each hop.
11//!
12//! To build a circuit, first create a [crate::channel::Channel], then
13//! call its [crate::channel::Channel::new_tunnel] method.  This yields
14//! a [PendingClientTunnel] object that won't become live until you call
15//! one of the methods
16//! (typically [`PendingClientTunnel::create_firsthop`])
17//! that extends it to its first hop.  After you've
18//! done that, you can call [`ClientCirc::extend`] on the tunnel to
19//! build it into a multi-hop tunnel.  Finally, you can use
20//! [ClientTunnel::begin_stream] to get a Stream object that can be used
21//! for anonymized data.
22//!
23//! # Implementation
24//!
25//! Each open circuit has a corresponding Reactor object that runs in
26//! an asynchronous task, and manages incoming cells from the
27//! circuit's upstream channel.  These cells are either RELAY cells or
28//! DESTROY cells.  DESTROY cells are handled immediately.
29//! RELAY cells are either for a particular stream, in which case they
30//! get forwarded to a StreamReceiver object, or for no particular stream,
31//! in which case they are considered "meta" cells (like EXTENDED2)
32//! that should only get accepted if something is waiting for them.
33//!
34//! # Limitations
35//!
36//! This is client-only.
37
38pub(crate) mod halfcirc;
39
40#[cfg(feature = "hs-common")]
41pub mod handshake;
42#[cfg(not(feature = "hs-common"))]
43pub(crate) mod handshake;
44
45pub(crate) mod padding;
46
47pub(super) mod path;
48
49use crate::channel::Channel;
50use crate::circuit::circhop::{HopNegotiationType, HopSettings};
51use crate::circuit::{CircuitRxReceiver, celltypes::*};
52#[cfg(feature = "circ-padding-manual")]
53use crate::client::CircuitPadder;
54use crate::client::circuit::padding::{PaddingController, PaddingEventStream};
55use crate::client::reactor::{CircuitHandshake, CtrlCmd, CtrlMsg, Reactor};
56use crate::crypto::cell::HopNum;
57use crate::crypto::handshake::ntor_v3::NtorV3PublicKey;
58use crate::memquota::CircuitAccount;
59use crate::util::skew::ClockSkew;
60use crate::{Error, Result};
61use derive_deftly::Deftly;
62use educe::Educe;
63use path::HopDetail;
64use tor_cell::chancell::{
65    CircId,
66    msg::{self as chanmsg},
67};
68use tor_error::{bad_api_usage, internal, into_internal};
69use tor_linkspec::{CircTarget, LinkSpecType, OwnedChanTarget, RelayIdType};
70use tor_protover::named;
71use tor_rtcompat::DynTimeProvider;
72use web_time_compat::Instant;
73
74use crate::circuit::UniqId;
75
76use super::{ClientTunnel, TargetHop};
77
78use futures::channel::mpsc;
79use oneshot_fused_workaround as oneshot;
80
81use futures::FutureExt as _;
82use std::collections::HashMap;
83use std::sync::{Arc, Mutex};
84use tor_memquota::derive_deftly_template_HasMemoryCost;
85
86use crate::crypto::handshake::ntor::NtorPublicKey;
87
88pub use crate::crypto::binding::CircuitBinding;
89pub use path::{Path, PathEntry};
90
91// TODO: export this from the top-level instead (it's not client-specific).
92pub use crate::circuit::CircParameters;
93
94// TODO(relay): reexport this from somewhere else (it's not client-specific)
95pub use crate::util::timeout::TimeoutEstimator;
96
97/// A subclass of ChanMsg that can correctly arrive on a live client
98/// circuit (one where a CREATED* has been received).
99#[derive(Debug, Deftly)]
100#[allow(unreachable_pub)] // Only `pub` with feature `testing`; otherwise, visible in crate
101#[derive_deftly(HasMemoryCost)]
102#[derive_deftly(RestrictedChanMsgSet)]
103#[deftly(usage = "on an open client circuit")]
104pub(super) enum ClientCircChanMsg {
105    /// A relay cell telling us some kind of remote command from some
106    /// party on the circuit.
107    Relay(chanmsg::Relay),
108    /// A cell telling us to destroy the circuit.
109    Destroy(chanmsg::Destroy),
110    // Note: RelayEarly is not valid for clients!
111}
112
113#[derive(Debug)]
114/// A circuit that we have constructed over the Tor network.
115///
116/// # Circuit life cycle
117///
118/// `ClientCirc`s are created in an initially unusable state using [`Channel::new_tunnel`],
119/// which returns a [`PendingClientTunnel`].  To get a real (one-hop) tunnel from
120/// one of these, you invoke one of its `create_firsthop` methods (typically
121/// [`create_firsthop_fast()`](PendingClientTunnel::create_firsthop_fast) or
122/// [`create_firsthop()`](PendingClientTunnel::create_firsthop)).
123/// Then, to add more hops to the circuit, you can call
124/// [`extend()`](ClientCirc::extend) on it.
125///
126/// For higher-level APIs, see the `tor-circmgr` crate: the ones here in
127/// `tor-proto` are probably not what you need.
128///
129/// After a circuit is created, it will persist until it is closed in one of
130/// five ways:
131///    1. A remote error occurs.
132///    2. Some hop on the circuit sends a `DESTROY` message to tear down the
133///       circuit.
134///    3. The circuit's channel is closed.
135///    4. Someone calls [`ClientTunnel::terminate`] on the tunnel owning the circuit.
136///    5. The last reference to the `ClientCirc` is dropped. (Note that every stream
137///       on a `ClientCirc` keeps a reference to it, which will in turn keep the
138///       circuit from closing until all those streams have gone away.)
139///
140/// Note that in cases 1-4 the [`ClientCirc`] object itself will still exist: it
141/// will just be unusable for most purposes.  Most operations on it will fail
142/// with an error.
143//
144// Effectively, this struct contains two Arcs: one for `path` and one for
145// `control` (which surely has something Arc-like in it).  We cannot unify
146// these by putting a single Arc around the whole struct, and passing
147// an Arc strong reference to the `Reactor`, because then `control` would
148// not be dropped when the last user of the circuit goes away.  We could
149// make the reactor have a weak reference but weak references are more
150// expensive to dereference.
151//
152// Because of the above, cloning this struct is always going to involve
153// two atomic refcount changes/checks.  Wrapping it in another Arc would
154// be overkill.
155//
156pub struct ClientCirc {
157    /// Mutable state shared with the `Reactor`.
158    pub(super) mutable: Arc<TunnelMutableState>,
159    /// A unique identifier for this circuit.
160    unique_id: UniqId,
161    /// Channel to send control messages to the reactor.
162    pub(super) control: mpsc::UnboundedSender<CtrlMsg>,
163    /// Channel to send commands to the reactor.
164    pub(super) command: mpsc::UnboundedSender<CtrlCmd>,
165    /// A future that resolves to Cancelled once the reactor is shut down,
166    /// meaning that the circuit is closed.
167    #[cfg_attr(not(feature = "experimental-api"), allow(dead_code))]
168    reactor_closed_rx: futures::future::Shared<oneshot::Receiver<void::Void>>,
169    /// For testing purposes: the CircId, for use in peek_circid().
170    #[cfg(test)]
171    circid: CircId,
172    /// Memory quota account
173    pub(super) memquota: CircuitAccount,
174    /// Time provider
175    pub(super) time_provider: DynTimeProvider,
176    /// Indicate if this reactor is a multi path or not. This is flagged at the very first
177    /// LinkCircuit seen and never changed after.
178    ///
179    /// We can't just look at the number of legs because a multi path tunnel could have 1 leg only
180    /// because the other(s) have collapsed.
181    ///
182    /// This is very important because it allows to make a quick efficient safety check by the
183    /// circmgr higher level tunnel type without locking the mutable state or using the command
184    /// channel.
185    pub(super) is_multi_path: bool,
186}
187
188/// The mutable state of a tunnel, shared between [`ClientCirc`] and [`Reactor`].
189///
190/// NOTE(gabi): this mutex-inside-a-mutex might look suspicious,
191/// but it is currently the best option we have for sharing
192/// the circuit state with `ClientCirc` (and soon, with `ClientTunnel`).
193/// In practice, these mutexes won't be accessed very often
194/// (they're accessed for writing when a circuit is extended,
195/// and for reading by the various `ClientCirc` APIs),
196/// so they shouldn't really impact performance.
197///
198/// Alternatively, the circuit state information could be shared
199/// outside the reactor through a channel (passed to the reactor via a `CtrlCmd`),
200/// but in #1840 @opara notes that involves making the `ClientCirc` accessors
201/// (`ClientCirc::path`, `ClientCirc::binding_key`, etc.)
202/// asynchronous, which will significantly complicate their callsites,
203/// which would in turn need to be made async too.
204///
205/// We should revisit this decision at some point, and decide whether an async API
206/// would be preferable.
207#[derive(Debug, Default)]
208pub(super) struct TunnelMutableState(Mutex<HashMap<UniqId, Arc<MutableState>>>);
209
210impl TunnelMutableState {
211    /// Add the [`MutableState`] of a circuit.
212    pub(super) fn insert(&self, unique_id: UniqId, mutable: Arc<MutableState>) {
213        #[allow(unused)] // unused in non-debug builds
214        let state = self
215            .0
216            .lock()
217            .expect("lock poisoned")
218            .insert(unique_id, mutable);
219
220        debug_assert!(state.is_none());
221    }
222
223    /// Remove the [`MutableState`] of a circuit.
224    pub(super) fn remove(&self, unique_id: UniqId) {
225        #[allow(unused)] // unused in non-debug builds
226        let state = self.0.lock().expect("lock poisoned").remove(&unique_id);
227
228        debug_assert!(state.is_some());
229    }
230
231    /// Return a [`Path`] object describing all the circuits in this tunnel.
232    fn all_paths(&self) -> Vec<Arc<Path>> {
233        let lock = self.0.lock().expect("lock poisoned");
234        lock.values().map(|mutable| mutable.path()).collect()
235    }
236
237    /// Return a representation of the Paths for all the circuits in this tunnel,
238    /// as a map from each circuits' UniqId to its path.
239    ///
240    /// This is only exposed for the RPC subsystem, where it is documented that the
241    /// format of `UniqId` is not stable.
242    #[cfg(feature = "rpc")]
243    pub(super) fn tagged_paths(&self) -> HashMap<UniqId, Arc<Path>> {
244        let lock = self.0.lock().expect("lock poisoned");
245        lock.iter()
246            .map(|(id, mutable)| (*id, mutable.path()))
247            .collect()
248    }
249
250    /// Return a list of [`Path`] objects describing the only circuit in this tunnel.
251    ///
252    /// Returns an error if the tunnel has more than one tunnel.
253    //
254    // TODO: replace Itertools::exactly_one() with a stdlib equivalent when there is one.
255    //
256    // See issue #48919 <https://github.com/rust-lang/rust/issues/48919>
257    #[allow(unstable_name_collisions)]
258    fn single_path(&self) -> Result<Arc<Path>> {
259        use itertools::Itertools as _;
260
261        self.all_paths().into_iter().exactly_one().map_err(|_| {
262            bad_api_usage!("requested the single path of a multi-path tunnel?!").into()
263        })
264    }
265
266    /// Return a description of the first hop of this circuit.
267    ///
268    /// Returns an error if a circuit with the specified [`UniqId`] doesn't exist.
269    /// Returns `Ok(None)` if the specified circuit doesn't have any hops.
270    fn first_hop(&self, unique_id: UniqId) -> Result<Option<OwnedChanTarget>> {
271        let lock = self.0.lock().expect("lock poisoned");
272        let mutable = lock
273            .get(&unique_id)
274            .ok_or_else(|| bad_api_usage!("no circuit with unique ID {unique_id}"))?;
275
276        let first_hop = mutable.first_hop().map(|first_hop| match first_hop {
277            path::HopDetail::Relay(r) => r,
278            #[cfg(feature = "hs-common")]
279            path::HopDetail::Virtual => {
280                panic!("somehow made a circuit with a virtual first hop.")
281            }
282        });
283
284        Ok(first_hop)
285    }
286
287    /// Return the [`HopNum`] of the last hop of the specified circuit.
288    ///
289    /// Returns an error if a circuit with the specified [`UniqId`] doesn't exist.
290    ///
291    /// See [`MutableState::last_hop_num`].
292    pub(super) fn last_hop_num(&self, unique_id: UniqId) -> Result<Option<HopNum>> {
293        let lock = self.0.lock().expect("lock poisoned");
294        let mutable = lock
295            .get(&unique_id)
296            .ok_or_else(|| bad_api_usage!("no circuit with unique ID {unique_id}"))?;
297
298        Ok(mutable.last_hop_num())
299    }
300
301    /// Return the number of hops in the specified circuit.
302    ///
303    /// See [`MutableState::n_hops`].
304    fn n_hops(&self, unique_id: UniqId) -> Result<usize> {
305        let lock = self.0.lock().expect("lock poisoned");
306        let mutable = lock
307            .get(&unique_id)
308            .ok_or_else(|| bad_api_usage!("no circuit with unique ID {unique_id}"))?;
309
310        Ok(mutable.n_hops())
311    }
312}
313
314/// The mutable state of a circuit.
315#[derive(Educe, Default)]
316#[educe(Debug)]
317pub(super) struct MutableState(Mutex<CircuitState>);
318
319impl MutableState {
320    /// Add a hop to the path of this circuit.
321    pub(super) fn add_hop(&self, peer_id: HopDetail, binding: Option<CircuitBinding>) {
322        let mut mutable = self.0.lock().expect("poisoned lock");
323        Arc::make_mut(&mut mutable.path).push_hop(peer_id);
324        mutable.binding.push(binding);
325    }
326
327    /// Get a copy of the circuit's current [`path::Path`].
328    pub(super) fn path(&self) -> Arc<path::Path> {
329        let mutable = self.0.lock().expect("poisoned lock");
330        Arc::clone(&mutable.path)
331    }
332
333    /// Return the cryptographic material used to prove knowledge of a shared
334    /// secret with with `hop`.
335    pub(super) fn binding_key(&self, hop: HopNum) -> Option<CircuitBinding> {
336        let mutable = self.0.lock().expect("poisoned lock");
337
338        mutable.binding.get::<usize>(hop.into()).cloned().flatten()
339        // NOTE: I'm not thrilled to have to copy this information, but we use
340        // it very rarely, so it's not _that_ bad IMO.
341    }
342
343    /// Return a description of the first hop of this circuit.
344    fn first_hop(&self) -> Option<HopDetail> {
345        let mutable = self.0.lock().expect("poisoned lock");
346        mutable.path.first_hop()
347    }
348
349    /// Return the [`HopNum`] of the last hop of this circuit.
350    ///
351    /// NOTE: This function will return the [`HopNum`] of the hop
352    /// that is _currently_ the last. If there is an extend operation in progress,
353    /// the currently pending hop may or may not be counted, depending on whether
354    /// the extend operation finishes before this call is done.
355    fn last_hop_num(&self) -> Option<HopNum> {
356        let mutable = self.0.lock().expect("poisoned lock");
357        mutable.path.last_hop_num()
358    }
359
360    /// Return the number of hops in this circuit.
361    ///
362    /// NOTE: This function will currently return only the number of hops
363    /// _currently_ in the circuit. If there is an extend operation in progress,
364    /// the currently pending hop may or may not be counted, depending on whether
365    /// the extend operation finishes before this call is done.
366    fn n_hops(&self) -> usize {
367        let mutable = self.0.lock().expect("poisoned lock");
368        mutable.path.n_hops()
369    }
370}
371
372/// The shared state of a circuit.
373#[derive(Educe, Default)]
374#[educe(Debug)]
375pub(super) struct CircuitState {
376    /// Information about this circuit's path.
377    ///
378    /// This is stored in an Arc so that we can cheaply give a copy of it to
379    /// client code; when we need to add a hop (which is less frequent) we use
380    /// [`Arc::make_mut()`].
381    path: Arc<path::Path>,
382
383    /// Circuit binding keys [q.v.][`CircuitBinding`] information for each hop
384    /// in the circuit's path.
385    ///
386    /// NOTE: Right now, there is a `CircuitBinding` for every hop.  There's a
387    /// fair chance that this will change in the future, and I don't want other
388    /// code to assume that a `CircuitBinding` _must_ exist, so I'm making this
389    /// an `Option`.
390    #[educe(Debug(ignore))]
391    binding: Vec<Option<CircuitBinding>>,
392}
393
394/// A ClientCirc that needs to send a create cell and receive a created* cell.
395///
396/// To use one of these, call `create_firsthop_fast()` or `create_firsthop()`
397/// to negotiate the cryptographic handshake with the first hop.
398pub struct PendingClientTunnel {
399    /// A oneshot receiver on which we'll receive a CREATED* cell,
400    /// or a DESTROY cell.
401    recvcreated: oneshot::Receiver<CreateResponse>,
402    /// The ClientCirc object that we can expose on success.
403    circ: ClientCirc,
404}
405
406impl ClientCirc {
407    /// Convert this `ClientCirc` into a single circuit [`ClientTunnel`].
408    pub fn into_tunnel(self) -> Result<ClientTunnel> {
409        self.try_into()
410    }
411
412    /// Return a description of the first hop of this circuit.
413    ///
414    /// # Panics
415    ///
416    /// Panics if there is no first hop.  (This should be impossible outside of
417    /// the tor-proto crate, but within the crate it's possible to have a
418    /// circuit with no hops.)
419    pub fn first_hop(&self) -> Result<OwnedChanTarget> {
420        Ok(self
421            .mutable
422            .first_hop(self.unique_id)
423            .map_err(|_| Error::CircuitClosed)?
424            .expect("called first_hop on an un-constructed circuit"))
425    }
426
427    /// Return a description of the last hop of the tunnel.
428    ///
429    /// Return None if the last hop is virtual.
430    ///
431    /// # Panics
432    ///
433    /// Panics if there is no last hop.  (This should be impossible outside of
434    /// the tor-proto crate, but within the crate it's possible to have a
435    /// circuit with no hops.)
436    pub fn last_hop_info(&self) -> Result<Option<OwnedChanTarget>> {
437        let all_paths = self.all_paths();
438        let path = all_paths.first().ok_or_else(|| {
439            tor_error::bad_api_usage!("Called last_hop_info on an un-constructed tunnel")
440        })?;
441        Ok(path
442            .hops()
443            .last()
444            .expect("Called last_hop on an un-constructed circuit")
445            .as_chan_target()
446            .map(OwnedChanTarget::from_chan_target))
447    }
448
449    /// Return the [`HopNum`] of the last hop of this circuit.
450    ///
451    /// Returns an error if there is no last hop.  (This should be impossible outside of the
452    /// tor-proto crate, but within the crate it's possible to have a circuit with no hops.)
453    ///
454    /// NOTE: This function will return the [`HopNum`] of the hop
455    /// that is _currently_ the last. If there is an extend operation in progress,
456    /// the currently pending hop may or may not be counted, depending on whether
457    /// the extend operation finishes before this call is done.
458    pub fn last_hop_num(&self) -> Result<HopNum> {
459        Ok(self
460            .mutable
461            .last_hop_num(self.unique_id)?
462            .ok_or_else(|| internal!("no last hop index"))?)
463    }
464
465    /// Return a [`TargetHop`] representing precisely the last hop of the circuit as in set as a
466    /// HopLocation with its id and hop number.
467    ///
468    /// Return an error if there is no last hop.
469    pub fn last_hop(&self) -> Result<TargetHop> {
470        let hop_num = self
471            .mutable
472            .last_hop_num(self.unique_id)?
473            .ok_or_else(|| bad_api_usage!("no last hop"))?;
474        Ok((self.unique_id, hop_num).into())
475    }
476
477    /// Return a list of [`Path`] objects describing all the circuits in this tunnel.
478    ///
479    /// Note that these `Path`s are not automatically updated if the underlying
480    /// circuits are extended.
481    pub fn all_paths(&self) -> Vec<Arc<Path>> {
482        self.mutable.all_paths()
483    }
484
485    /// Return a list of [`Path`] objects describing the only circuit in this tunnel.
486    ///
487    /// Returns an error if the tunnel has more than one tunnel.
488    pub fn single_path(&self) -> Result<Arc<Path>> {
489        self.mutable.single_path()
490    }
491
492    /// Return the time at which this circuit last had any open streams.
493    ///
494    /// Returns `None` if this circuit has never had any open streams,
495    /// or if it currently has open streams.
496    ///
497    /// NOTE that the Instant returned by this method is not affected by
498    /// any runtime mocking; it is the output of an ordinary call to
499    /// `Instant::get()`.
500    pub async fn disused_since(&self) -> Result<Option<Instant>> {
501        let (tx, rx) = oneshot::channel();
502        self.command
503            .unbounded_send(CtrlCmd::GetTunnelActivity { sender: tx })
504            .map_err(|_| Error::CircuitClosed)?;
505
506        Ok(rx.await.map_err(|_| Error::CircuitClosed)?.disused_since())
507    }
508
509    /// Get the clock skew claimed by the first hop of the circuit.
510    ///
511    /// See [`Channel::clock_skew()`].
512    pub async fn first_hop_clock_skew(&self) -> Result<ClockSkew> {
513        let (tx, rx) = oneshot::channel();
514
515        self.control
516            .unbounded_send(CtrlMsg::FirstHopClockSkew { answer: tx })
517            .map_err(|_| Error::CircuitClosed)?;
518
519        Ok(rx.await.map_err(|_| Error::CircuitClosed)??)
520    }
521
522    /// Return a reference to this circuit's memory quota account
523    pub fn mq_account(&self) -> &CircuitAccount {
524        &self.memquota
525    }
526
527    /// Return the cryptographic material used to prove knowledge of a shared
528    /// secret with with `hop`.
529    ///
530    /// See [`CircuitBinding`] for more information on how this is used.
531    ///
532    /// Return None if we have no circuit binding information for the hop, or if
533    /// the hop does not exist.
534    #[cfg(feature = "hs-service")]
535    pub async fn binding_key(&self, hop: TargetHop) -> Result<Option<CircuitBinding>> {
536        let (sender, receiver) = oneshot::channel();
537        let msg = CtrlCmd::GetBindingKey { hop, done: sender };
538        self.command
539            .unbounded_send(msg)
540            .map_err(|_| Error::CircuitClosed)?;
541
542        receiver.await.map_err(|_| Error::CircuitClosed)?
543    }
544
545    /// Extend the circuit, via the most appropriate circuit extension handshake,
546    /// to the chosen `target` hop.
547    pub async fn extend<Tg>(&self, target: &Tg, params: CircParameters) -> Result<()>
548    where
549        Tg: CircTarget,
550    {
551        #![allow(deprecated)]
552
553        // For now we use the simplest decision-making mechanism:
554        // we use ntor_v3 whenever it is present; and otherwise we use ntor.
555        //
556        // This behavior is slightly different from C tor, which uses ntor v3
557        // only whenever it want to send any extension in the circuit message.
558        // But thanks to congestion control (named::FLOWCTRL_CC), we'll _always_
559        // want to use an extension if we can, and so it doesn't make too much
560        // sense to detect the case where we have no extensions.
561        //
562        // (As of April 2025, RELAY_NTORV3 is not yet listed as Required for relays
563        // on the tor network, and so we cannot simply assume that everybody has it.)
564        if target
565            .protovers()
566            .supports_named_subver(named::RELAY_NTORV3)
567        {
568            self.extend_ntor_v3(target, params).await
569        } else {
570            self.extend_ntor(target, params).await
571        }
572    }
573
574    /// Extend the circuit via the ntor handshake to a new target last
575    /// hop.
576    #[deprecated(since = "1.6.1", note = "Use extend instead.")]
577    pub async fn extend_ntor<Tg>(&self, target: &Tg, params: CircParameters) -> Result<()>
578    where
579        Tg: CircTarget,
580    {
581        let key = NtorPublicKey {
582            id: *target
583                .rsa_identity()
584                .ok_or(Error::MissingId(RelayIdType::Rsa))?,
585            pk: *target.ntor_onion_key(),
586        };
587        let mut linkspecs = target
588            .linkspecs()
589            .map_err(into_internal!("Could not encode linkspecs for extend_ntor"))?;
590        if !params.extend_by_ed25519_id {
591            linkspecs.retain(|ls| ls.lstype() != LinkSpecType::ED25519ID);
592        }
593
594        let (tx, rx) = oneshot::channel();
595
596        let peer_id = OwnedChanTarget::from_chan_target(target);
597        let settings = HopSettings::from_params_and_caps(
598            HopNegotiationType::None,
599            &params,
600            target.protovers(),
601        )?;
602        self.control
603            .unbounded_send(CtrlMsg::ExtendNtor {
604                peer_id,
605                public_key: key,
606                linkspecs,
607                settings,
608                done: tx,
609            })
610            .map_err(|_| Error::CircuitClosed)?;
611
612        rx.await.map_err(|_| Error::CircuitClosed)??;
613
614        Ok(())
615    }
616
617    /// Extend the circuit via the ntor handshake to a new target last
618    /// hop.
619    #[deprecated(since = "1.6.1", note = "Use extend instead.")]
620    pub async fn extend_ntor_v3<Tg>(&self, target: &Tg, params: CircParameters) -> Result<()>
621    where
622        Tg: CircTarget,
623    {
624        let key = NtorV3PublicKey {
625            id: *target
626                .ed_identity()
627                .ok_or(Error::MissingId(RelayIdType::Ed25519))?,
628            pk: *target.ntor_onion_key(),
629        };
630        let mut linkspecs = target
631            .linkspecs()
632            .map_err(into_internal!("Could not encode linkspecs for extend_ntor"))?;
633        if !params.extend_by_ed25519_id {
634            linkspecs.retain(|ls| ls.lstype() != LinkSpecType::ED25519ID);
635        }
636
637        let (tx, rx) = oneshot::channel();
638
639        let peer_id = OwnedChanTarget::from_chan_target(target);
640        let settings = HopSettings::from_params_and_caps(
641            HopNegotiationType::Full,
642            &params,
643            target.protovers(),
644        )?;
645        self.control
646            .unbounded_send(CtrlMsg::ExtendNtorV3 {
647                peer_id,
648                public_key: key,
649                linkspecs,
650                settings,
651                done: tx,
652            })
653            .map_err(|_| Error::CircuitClosed)?;
654
655        rx.await.map_err(|_| Error::CircuitClosed)??;
656
657        Ok(())
658    }
659
660    /// Extend this circuit by a single, "virtual" hop.
661    ///
662    /// A virtual hop is one for which we do not add an actual network connection
663    /// between separate hosts (such as Relays).  We only add a layer of
664    /// cryptography.
665    ///
666    /// This is used to implement onion services: the client and the service
667    /// both build a circuit to a single rendezvous point, and tell the
668    /// rendezvous point to relay traffic between their two circuits.  Having
669    /// completed a [`handshake`] out of band[^1], the parties each extend their
670    /// circuits by a single "virtual" encryption hop that represents their
671    /// shared cryptographic context.
672    ///
673    /// Protocol settings, capabilities, and parameters
674    /// are based on the `params` and `capabilities` arguments.
675    /// The `capabilities` argument should contains a set of capabilities that both
676    /// parties have agreed to use.  Only explicitly negotiable capabilities[^2] need
677    /// to be listed.
678    ///
679    /// Once a circuit has been extended in this way, it is an error to try to
680    /// extend it in any other way.
681    ///
682    /// [^1]: Technically, the handshake is only _mostly_ out of band: the
683    ///     client sends their half of the handshake in an ` message, and the
684    ///     service's response is inline in its `RENDEZVOUS2` message.
685    /// [^2]: That is to say, if a capability is always-on, then there is no need to list
686    ///     it.
687    //
688    // TODO hs: let's try to enforce the "you can't extend a circuit again once
689    // it has been extended this way" property.  We could do that with internal
690    // state, or some kind of a type state pattern.
691    #[cfg(feature = "hs-common")]
692    pub async fn extend_virtual(
693        &self,
694        protocol: handshake::RelayProtocol,
695        role: handshake::HandshakeRole,
696        seed: impl handshake::KeyGenerator,
697        params: &CircParameters,
698        capabilities: &tor_protover::Protocols,
699    ) -> Result<()> {
700        use self::handshake::BoxedClientLayer;
701
702        // TODO CGO: Possibly refactor this match into a separate method when we revisit this.
703        let negotiation_type = match protocol {
704            handshake::RelayProtocol::HsV3 => HopNegotiationType::HsV3,
705        };
706        let protocol = handshake::RelayCryptLayerProtocol::from(protocol);
707
708        let BoxedClientLayer { fwd, back, binding } =
709            protocol.construct_client_layers(role, seed)?;
710
711        let settings = HopSettings::from_params_and_caps(negotiation_type, params, capabilities)?;
712        let (tx, rx) = oneshot::channel();
713        let message = CtrlCmd::ExtendVirtual {
714            cell_crypto: (fwd, back, binding),
715            settings,
716            done: tx,
717        };
718
719        self.command
720            .unbounded_send(message)
721            .map_err(|_| Error::CircuitClosed)?;
722
723        rx.await.map_err(|_| Error::CircuitClosed)?
724    }
725
726    /// Install a [`CircuitPadder`] at the listed `hop`.
727    ///
728    /// Replaces any previous padder installed at that hop.
729    #[cfg(feature = "circ-padding-manual")]
730    pub async fn start_padding_at_hop(&self, hop: HopNum, padder: CircuitPadder) -> Result<()> {
731        self.set_padder_impl(crate::HopLocation::Hop((self.unique_id, hop)), Some(padder))
732            .await
733    }
734
735    /// Remove any [`CircuitPadder`] at the listed `hop`.
736    ///
737    /// Does nothing if there was not a padder installed there.
738    #[cfg(feature = "circ-padding-manual")]
739    pub async fn stop_padding_at_hop(&self, hop: HopNum) -> Result<()> {
740        self.set_padder_impl(crate::HopLocation::Hop((self.unique_id, hop)), None)
741            .await
742    }
743
744    /// Helper: replace the padder at `hop` with the provided `padder`, or with `None`.
745    #[cfg(feature = "circ-padding-manual")]
746    pub(super) async fn set_padder_impl(
747        &self,
748        hop: crate::HopLocation,
749        padder: Option<CircuitPadder>,
750    ) -> Result<()> {
751        let (tx, rx) = oneshot::channel();
752        let msg = CtrlCmd::SetPadder {
753            hop,
754            padder,
755            sender: tx,
756        };
757        self.command
758            .unbounded_send(msg)
759            .map_err(|_| Error::CircuitClosed)?;
760        rx.await.map_err(|_| Error::CircuitClosed)?
761    }
762
763    /// Return true if this circuit is closed and therefore unusable.
764    pub fn is_closing(&self) -> bool {
765        self.control.is_closed()
766    }
767
768    /// Return a process-unique identifier for this circuit.
769    pub fn unique_id(&self) -> UniqId {
770        self.unique_id
771    }
772
773    /// Return the number of hops in this circuit.
774    ///
775    /// NOTE: This function will currently return only the number of hops
776    /// _currently_ in the circuit. If there is an extend operation in progress,
777    /// the currently pending hop may or may not be counted, depending on whether
778    /// the extend operation finishes before this call is done.
779    pub fn n_hops(&self) -> Result<usize> {
780        self.mutable
781            .n_hops(self.unique_id)
782            .map_err(|_| Error::CircuitClosed)
783    }
784
785    /// Return a future that will resolve once this circuit has closed.
786    ///
787    /// Note that this method does not itself cause the circuit to shut down.
788    ///
789    /// TODO: Perhaps this should return some kind of status indication instead
790    /// of just ()
791    pub fn wait_for_close(
792        &self,
793    ) -> impl futures::Future<Output = ()> + Send + Sync + 'static + use<> {
794        self.reactor_closed_rx.clone().map(|_| ())
795    }
796}
797
798impl PendingClientTunnel {
799    /// Instantiate a new circuit object: used from Channel::new_tunnel().
800    ///
801    /// Does not send a CREATE* cell on its own.
802    #[allow(clippy::too_many_arguments)]
803    pub(crate) fn new(
804        circ_id: CircId,
805        channel: Arc<Channel>,
806        createdreceiver: oneshot::Receiver<CreateResponse>,
807        input: CircuitRxReceiver,
808        unique_id: UniqId,
809        runtime: DynTimeProvider,
810        memquota: CircuitAccount,
811        padding_ctrl: PaddingController,
812        padding_stream: PaddingEventStream,
813        timeouts: Arc<dyn TimeoutEstimator>,
814    ) -> (PendingClientTunnel, crate::client::reactor::Reactor) {
815        let time_provider = channel.time_provider().clone();
816        let (reactor, control_tx, command_tx, reactor_closed_rx, mutable) = Reactor::new(
817            channel,
818            circ_id,
819            unique_id,
820            input,
821            runtime,
822            memquota.clone(),
823            padding_ctrl,
824            padding_stream,
825            timeouts,
826        );
827
828        let circuit = ClientCirc {
829            mutable,
830            unique_id,
831            control: control_tx,
832            command: command_tx,
833            reactor_closed_rx: reactor_closed_rx.shared(),
834            #[cfg(test)]
835            circid: circ_id,
836            memquota,
837            time_provider,
838            is_multi_path: false,
839        };
840
841        let pending = PendingClientTunnel {
842            recvcreated: createdreceiver,
843            circ: circuit,
844        };
845        (pending, reactor)
846    }
847
848    /// Extract the process-unique identifier for this pending circuit.
849    pub fn peek_unique_id(&self) -> UniqId {
850        self.circ.unique_id
851    }
852
853    /// Use the (questionable!) CREATE_FAST handshake to connect to the
854    /// first hop of this circuit.
855    ///
856    /// There's no authentication in CRATE_FAST,
857    /// so we don't need to know whom we're connecting to: we're just
858    /// connecting to whichever relay the channel is for.
859    pub async fn create_firsthop_fast(self, params: CircParameters) -> Result<ClientTunnel> {
860        // We know nothing about this relay, so we assume it supports no protocol capabilities at all.
861        //
862        // TODO: If we had a consensus, we could assume it supported all required-relay-protocols.
863        // TODO prop364: When we implement CreateOneHop, we will want a Protocols argument here.
864        let protocols = tor_protover::Protocols::new();
865        let settings =
866            HopSettings::from_params_and_caps(HopNegotiationType::None, &params, &protocols)?;
867        let (tx, rx) = oneshot::channel();
868        self.circ
869            .control
870            .unbounded_send(CtrlMsg::Create {
871                recv_created: self.recvcreated,
872                handshake: CircuitHandshake::CreateFast,
873                settings,
874                done: tx,
875            })
876            .map_err(|_| Error::CircuitClosed)?;
877
878        rx.await.map_err(|_| Error::CircuitClosed)??;
879
880        self.circ.into_tunnel()
881    }
882
883    /// Use the most appropriate handshake to connect to the first hop of this circuit.
884    ///
885    /// Note that the provided 'target' must match the channel's target,
886    /// or the handshake will fail.
887    pub async fn create_firsthop<Tg>(
888        self,
889        target: &Tg,
890        params: CircParameters,
891    ) -> Result<ClientTunnel>
892    where
893        Tg: tor_linkspec::CircTarget,
894    {
895        #![allow(deprecated)]
896        // (See note in ClientCirc::extend.)
897        if target
898            .protovers()
899            .supports_named_subver(named::RELAY_NTORV3)
900        {
901            self.create_firsthop_ntor_v3(target, params).await
902        } else {
903            self.create_firsthop_ntor(target, params).await
904        }
905    }
906
907    /// Use the ntor handshake to connect to the first hop of this circuit.
908    ///
909    /// Note that the provided 'target' must match the channel's target,
910    /// or the handshake will fail.
911    #[deprecated(since = "1.6.1", note = "Use create_firsthop instead.")]
912    pub async fn create_firsthop_ntor<Tg>(
913        self,
914        target: &Tg,
915        params: CircParameters,
916    ) -> Result<ClientTunnel>
917    where
918        Tg: tor_linkspec::CircTarget,
919    {
920        let (tx, rx) = oneshot::channel();
921        let settings = HopSettings::from_params_and_caps(
922            HopNegotiationType::None,
923            &params,
924            target.protovers(),
925        )?;
926
927        self.circ
928            .control
929            .unbounded_send(CtrlMsg::Create {
930                recv_created: self.recvcreated,
931                handshake: CircuitHandshake::Ntor {
932                    public_key: NtorPublicKey {
933                        id: *target
934                            .rsa_identity()
935                            .ok_or(Error::MissingId(RelayIdType::Rsa))?,
936                        pk: *target.ntor_onion_key(),
937                    },
938                    ed_identity: *target
939                        .ed_identity()
940                        .ok_or(Error::MissingId(RelayIdType::Ed25519))?,
941                },
942                settings,
943                done: tx,
944            })
945            .map_err(|_| Error::CircuitClosed)?;
946
947        rx.await.map_err(|_| Error::CircuitClosed)??;
948
949        self.circ.into_tunnel()
950    }
951
952    /// Use the ntor_v3 handshake to connect to the first hop of this circuit.
953    ///
954    /// Assumes that the target supports ntor_v3. The caller should verify
955    /// this before calling this function, e.g. by validating that the target
956    /// has advertised ["Relay=4"](https://spec.torproject.org/tor-spec/subprotocol-versioning.html#relay).
957    ///
958    /// Note that the provided 'target' must match the channel's target,
959    /// or the handshake will fail.
960    #[deprecated(since = "1.6.1", note = "Use create_firsthop instead.")]
961    pub async fn create_firsthop_ntor_v3<Tg>(
962        self,
963        target: &Tg,
964        params: CircParameters,
965    ) -> Result<ClientTunnel>
966    where
967        Tg: tor_linkspec::CircTarget,
968    {
969        let settings = HopSettings::from_params_and_caps(
970            HopNegotiationType::Full,
971            &params,
972            target.protovers(),
973        )?;
974        let (tx, rx) = oneshot::channel();
975
976        self.circ
977            .control
978            .unbounded_send(CtrlMsg::Create {
979                recv_created: self.recvcreated,
980                handshake: CircuitHandshake::NtorV3 {
981                    public_key: NtorV3PublicKey {
982                        id: *target
983                            .ed_identity()
984                            .ok_or(Error::MissingId(RelayIdType::Ed25519))?,
985                        pk: *target.ntor_onion_key(),
986                    },
987                },
988                settings,
989                done: tx,
990            })
991            .map_err(|_| Error::CircuitClosed)?;
992
993        rx.await.map_err(|_| Error::CircuitClosed)??;
994
995        self.circ.into_tunnel()
996    }
997}
998
999#[cfg(test)]
1000pub(crate) mod test {
1001    // @@ begin test lint list maintained by maint/add_warning @@
1002    #![allow(clippy::bool_assert_comparison)]
1003    #![allow(clippy::clone_on_copy)]
1004    #![allow(clippy::dbg_macro)]
1005    #![allow(clippy::mixed_attributes_style)]
1006    #![allow(clippy::print_stderr)]
1007    #![allow(clippy::print_stdout)]
1008    #![allow(clippy::single_char_pattern)]
1009    #![allow(clippy::unwrap_used)]
1010    #![allow(clippy::unchecked_time_subtraction)]
1011    #![allow(clippy::useless_vec)]
1012    #![allow(clippy::needless_pass_by_value)]
1013    #![allow(clippy::string_slice)] // See arti#2571
1014    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
1015
1016    use super::*;
1017    use crate::channel::ChannelMode;
1018    use crate::channel::test_utils::{CodecResult, DummyChan};
1019    use crate::circuit::CircuitRxSender;
1020    use crate::circuit::reactor::test::rmsg_to_ccmsg;
1021    use crate::circuit::test::fake_mpsc;
1022    use crate::client::circuit::padding::new_padding;
1023    use crate::client::stream::DataStream;
1024    use crate::congestion::params::CongestionControlParams;
1025    use crate::congestion::test_utils::params::build_cc_vegas_params;
1026    use crate::crypto::cell::RelayCellBody;
1027    use crate::crypto::handshake::ntor::tests::NtorSecretKey;
1028    use crate::crypto::handshake::ntor_v3::NtorV3Server;
1029    use crate::crypto::handshake::ntor_v3::test::NtorV3SecretKey;
1030    use crate::memquota::SpecificAccount as _;
1031    use crate::stream::flow_ctrl::params::FlowCtrlParameters;
1032    use crate::util::DummyTimeoutEstimator;
1033    use assert_matches::assert_matches;
1034    use chanmsg::{AnyChanMsg, Created2, CreatedFast};
1035    use futures::channel::mpsc::{Receiver, Sender};
1036    use futures::io::{AsyncReadExt, AsyncWriteExt};
1037    use futures::sink::SinkExt;
1038    use futures::stream::StreamExt;
1039    use hex_literal::hex;
1040    use std::collections::{HashMap, VecDeque};
1041    use std::fmt::Debug;
1042    use std::time::Duration;
1043    use tor_basic_utils::test_rng::testing_rng;
1044    use tor_cell::chancell::{AnyChanCell, BoxedCellBody, ChanCell, ChanCmd, msg as chanmsg};
1045    use tor_cell::relaycell::extend::{self as extend_ext, CircRequestExt, CircResponseExt};
1046    use tor_cell::relaycell::msg::SendmeTag;
1047    use tor_cell::relaycell::{
1048        AnyRelayMsgOuter, RelayCellFormat, RelayCmd, StreamId, msg as relaymsg, msg::AnyRelayMsg,
1049    };
1050    use tor_cell::relaycell::{RelayMsg, UnparsedRelayMsg};
1051    use tor_linkspec::OwnedCircTarget;
1052    use tor_rtcompat::Runtime;
1053    use tor_rtcompat::SpawnExt;
1054    use tracing::trace;
1055    use tracing_test::traced_test;
1056
1057    #[cfg(feature = "conflux")]
1058    use {
1059        crate::client::reactor::ConfluxHandshakeResult,
1060        crate::util::err::ConfluxHandshakeError,
1061        futures::future::FusedFuture,
1062        futures::lock::Mutex as AsyncMutex,
1063        std::pin::Pin,
1064        std::result::Result as StdResult,
1065        tor_cell::relaycell::conflux::{V1DesiredUx, V1LinkPayload, V1Nonce},
1066        tor_cell::relaycell::msg::ConfluxLink,
1067        tor_rtmock::MockRuntime,
1068    };
1069
1070    #[cfg(feature = "hs-service")]
1071    use crate::circuit::reactor::test::AllowAllStreamsFilter;
1072
1073    impl PendingClientTunnel {
1074        /// Testing only: Extract the circuit ID for this pending circuit.
1075        pub(crate) fn peek_circid(&self) -> CircId {
1076            self.circ.circid
1077        }
1078    }
1079
1080    impl ClientCirc {
1081        /// Testing only: Extract the circuit ID of this circuit.
1082        pub(crate) fn peek_circid(&self) -> CircId {
1083            self.circid
1084        }
1085    }
1086
1087    impl ClientTunnel {
1088        pub(crate) async fn resolve_last_hop(&self) -> TargetHop {
1089            let (sender, receiver) = oneshot::channel();
1090            let _ =
1091                self.as_single_circ()
1092                    .unwrap()
1093                    .command
1094                    .unbounded_send(CtrlCmd::ResolveTargetHop {
1095                        hop: TargetHop::LastHop,
1096                        done: sender,
1097                    });
1098            TargetHop::Hop(receiver.await.unwrap().unwrap())
1099        }
1100    }
1101
1102    // Example relay IDs and keys
1103    const EXAMPLE_SK: [u8; 32] =
1104        hex!("7789d92a89711a7e2874c61ea495452cfd48627b3ca2ea9546aafa5bf7b55803");
1105    const EXAMPLE_PK: [u8; 32] =
1106        hex!("395cb26b83b3cd4b91dba9913e562ae87d21ecdd56843da7ca939a6a69001253");
1107    const EXAMPLE_ED_ID: [u8; 32] = [6; 32];
1108    const EXAMPLE_RSA_ID: [u8; 20] = [10; 20];
1109
1110    /// return an example OwnedCircTarget that can get used for an ntor handshake.
1111    fn example_target() -> OwnedCircTarget {
1112        let mut builder = OwnedCircTarget::builder();
1113        builder
1114            .chan_target()
1115            .ed_identity(EXAMPLE_ED_ID.into())
1116            .rsa_identity(EXAMPLE_RSA_ID.into());
1117        builder
1118            .ntor_onion_key(EXAMPLE_PK.into())
1119            .protocols("FlowCtrl=1-2".parse().unwrap())
1120            .build()
1121            .unwrap()
1122    }
1123    fn example_ntor_key() -> NtorSecretKey {
1124        NtorSecretKey::new(EXAMPLE_SK.into(), EXAMPLE_PK.into(), EXAMPLE_RSA_ID.into())
1125    }
1126    fn example_ntor_v3_key() -> NtorV3SecretKey {
1127        NtorV3SecretKey::new(EXAMPLE_SK.into(), EXAMPLE_PK.into(), EXAMPLE_ED_ID.into())
1128    }
1129
1130    /// Which handshake type to use.
1131    #[derive(Copy, Clone)]
1132    enum HandshakeType {
1133        Fast,
1134        Ntor,
1135        NtorV3,
1136    }
1137
1138    #[allow(deprecated)]
1139    async fn test_create<R: Runtime>(rt: &R, handshake_type: HandshakeType, with_cc: bool) {
1140        // We want to try progressing from a pending circuit to a circuit
1141        // via a crate_fast handshake.
1142
1143        use crate::crypto::handshake::{ServerHandshake, fast::CreateFastServer, ntor::NtorServer};
1144
1145        let DummyChan {
1146            channel,
1147            mut rx,
1148            tx: _sink,
1149        } = DummyChan::run(rt, ChannelMode::Client);
1150        let circid = CircId::new(128).unwrap();
1151        let (created_send, created_recv) = oneshot::channel();
1152        let (_circmsg_send, circmsg_recv) = fake_mpsc(64);
1153        let unique_id = UniqId::new(23, 17);
1154        let (padding_ctrl, padding_stream) = new_padding(DynTimeProvider::new(rt.clone()));
1155
1156        let (pending, reactor) = PendingClientTunnel::new(
1157            circid,
1158            channel,
1159            created_recv,
1160            circmsg_recv,
1161            unique_id,
1162            DynTimeProvider::new(rt.clone()),
1163            CircuitAccount::new_noop(),
1164            padding_ctrl,
1165            padding_stream,
1166            Arc::new(DummyTimeoutEstimator),
1167        );
1168
1169        rt.spawn(async {
1170            let _ignore = reactor.run().await;
1171        })
1172        .unwrap();
1173
1174        // Future to pretend to be a relay on the other end of the circuit.
1175        let simulate_relay_fut = async move {
1176            let mut rng = testing_rng();
1177            let create_cell = rx.next().await.unwrap();
1178            assert_eq!(create_cell.circid(), Some(circid));
1179            let reply = match handshake_type {
1180                HandshakeType::Fast => {
1181                    let cf = match create_cell.msg() {
1182                        AnyChanMsg::CreateFast(cf) => cf,
1183                        other => panic!("{:?}", other),
1184                    };
1185                    let (_, rep) = CreateFastServer::server(
1186                        &mut rng,
1187                        &mut |_: &()| Some(()),
1188                        &[],
1189                        cf.handshake(),
1190                    )
1191                    .unwrap();
1192                    CreateResponse::CreatedFast(CreatedFast::new(rep))
1193                }
1194                HandshakeType::Ntor => {
1195                    let c2 = match create_cell.msg() {
1196                        AnyChanMsg::Create2(c2) => c2,
1197                        other => panic!("{:?}", other),
1198                    };
1199                    let (_, rep) = NtorServer::server(
1200                        &mut rng,
1201                        &mut |_: &()| Some(()),
1202                        &[example_ntor_key()],
1203                        c2.body(),
1204                    )
1205                    .unwrap();
1206                    CreateResponse::Created2(Created2::new(rep))
1207                }
1208                HandshakeType::NtorV3 => {
1209                    let c2 = match create_cell.msg() {
1210                        AnyChanMsg::Create2(c2) => c2,
1211                        other => panic!("{:?}", other),
1212                    };
1213                    let mut reply_fn = if with_cc {
1214                        |client_exts: &[CircRequestExt]| {
1215                            let _ = client_exts
1216                                .iter()
1217                                .find(|e| matches!(e, CircRequestExt::CcRequest(_)))
1218                                .expect("Client failed to request CC");
1219                            // This needs to be aligned to test_utils params
1220                            // value due to validation that needs it in range.
1221                            Some(vec![CircResponseExt::CcResponse(
1222                                extend_ext::CcResponse::new(31),
1223                            )])
1224                        }
1225                    } else {
1226                        |_: &_| Some(vec![])
1227                    };
1228                    let (_, rep) = NtorV3Server::server(
1229                        &mut rng,
1230                        &mut reply_fn,
1231                        &[example_ntor_v3_key()],
1232                        c2.body(),
1233                    )
1234                    .unwrap();
1235                    CreateResponse::Created2(Created2::new(rep))
1236                }
1237            };
1238            created_send.send(reply).unwrap();
1239        };
1240        // Future to pretend to be a client.
1241        let client_fut = async move {
1242            let target = example_target();
1243            let params = CircParameters::default();
1244            let ret = match handshake_type {
1245                HandshakeType::Fast => {
1246                    trace!("doing fast create");
1247                    pending.create_firsthop_fast(params).await
1248                }
1249                HandshakeType::Ntor => {
1250                    trace!("doing ntor create");
1251                    pending.create_firsthop_ntor(&target, params).await
1252                }
1253                HandshakeType::NtorV3 => {
1254                    let params = if with_cc {
1255                        // Setup CC vegas parameters.
1256                        CircParameters::new(
1257                            true,
1258                            build_cc_vegas_params(),
1259                            FlowCtrlParameters::defaults_for_tests(),
1260                        )
1261                    } else {
1262                        params
1263                    };
1264                    trace!("doing ntor_v3 create");
1265                    pending.create_firsthop_ntor_v3(&target, params).await
1266                }
1267            };
1268            trace!("create done: result {:?}", ret);
1269            ret
1270        };
1271
1272        let (circ, _) = futures::join!(client_fut, simulate_relay_fut);
1273
1274        let _circ = circ.unwrap();
1275
1276        // pfew!  We've build a circuit!  Let's make sure it has one hop.
1277        assert_eq!(_circ.n_hops().unwrap(), 1);
1278    }
1279
1280    #[traced_test]
1281    #[test]
1282    fn test_create_fast() {
1283        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1284            test_create(&rt, HandshakeType::Fast, false).await;
1285        });
1286    }
1287    #[traced_test]
1288    #[test]
1289    fn test_create_ntor() {
1290        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1291            test_create(&rt, HandshakeType::Ntor, false).await;
1292        });
1293    }
1294    #[traced_test]
1295    #[test]
1296    fn test_create_ntor_v3() {
1297        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1298            test_create(&rt, HandshakeType::NtorV3, false).await;
1299        });
1300    }
1301    #[traced_test]
1302    #[test]
1303    fn test_create_ntor_v3_with_cc() {
1304        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1305            test_create(&rt, HandshakeType::NtorV3, true).await;
1306        });
1307    }
1308
1309    // An encryption layer that doesn't do any crypto.   Can be used
1310    // as inbound or outbound, but not both at once.
1311    pub(crate) struct DummyCrypto {
1312        counter_tag: [u8; 20],
1313        counter: u32,
1314        lasthop: bool,
1315    }
1316    impl DummyCrypto {
1317        fn next_tag(&mut self) -> SendmeTag {
1318            #![allow(clippy::identity_op)]
1319            self.counter_tag[0] = ((self.counter >> 0) & 255) as u8;
1320            self.counter_tag[1] = ((self.counter >> 8) & 255) as u8;
1321            self.counter_tag[2] = ((self.counter >> 16) & 255) as u8;
1322            self.counter_tag[3] = ((self.counter >> 24) & 255) as u8;
1323            self.counter += 1;
1324            self.counter_tag.into()
1325        }
1326    }
1327
1328    impl crate::crypto::cell::OutboundClientLayer for DummyCrypto {
1329        fn originate_for(&mut self, _cmd: ChanCmd, _cell: &mut RelayCellBody) -> SendmeTag {
1330            self.next_tag()
1331        }
1332        fn encrypt_outbound(&mut self, _cmd: ChanCmd, _cell: &mut RelayCellBody) {}
1333    }
1334    impl crate::crypto::cell::InboundClientLayer for DummyCrypto {
1335        fn decrypt_inbound(
1336            &mut self,
1337            _cmd: ChanCmd,
1338            _cell: &mut RelayCellBody,
1339        ) -> Option<SendmeTag> {
1340            if self.lasthop {
1341                Some(self.next_tag())
1342            } else {
1343                None
1344            }
1345        }
1346    }
1347    impl DummyCrypto {
1348        pub(crate) fn new(lasthop: bool) -> Self {
1349            DummyCrypto {
1350                counter_tag: [0; 20],
1351                counter: 0,
1352                lasthop,
1353            }
1354        }
1355    }
1356
1357    // Helper: set up a 3-hop circuit with no encryption, where the
1358    // next inbound message seems to come from hop next_msg_from
1359    async fn newtunnel_ext<R: Runtime>(
1360        rt: &R,
1361        unique_id: UniqId,
1362        chan: Arc<Channel>,
1363        hops: Vec<path::HopDetail>,
1364        next_msg_from: HopNum,
1365        params: CircParameters,
1366    ) -> (ClientTunnel, CircuitRxSender) {
1367        let circid = CircId::new(128).unwrap();
1368        let (_created_send, created_recv) = oneshot::channel();
1369        let (circmsg_send, circmsg_recv) = fake_mpsc(64);
1370        let (padding_ctrl, padding_stream) = new_padding(DynTimeProvider::new(rt.clone()));
1371
1372        let (pending, reactor) = PendingClientTunnel::new(
1373            circid,
1374            chan,
1375            created_recv,
1376            circmsg_recv,
1377            unique_id,
1378            DynTimeProvider::new(rt.clone()),
1379            CircuitAccount::new_noop(),
1380            padding_ctrl,
1381            padding_stream,
1382            Arc::new(DummyTimeoutEstimator),
1383        );
1384
1385        rt.spawn(async {
1386            let _ignore = reactor.run().await;
1387        })
1388        .unwrap();
1389        let PendingClientTunnel {
1390            circ,
1391            recvcreated: _,
1392        } = pending;
1393
1394        // TODO #1067: Support other formats
1395        let relay_cell_format = RelayCellFormat::V0;
1396
1397        let last_hop_num = u8::try_from(hops.len() - 1).unwrap();
1398        for (idx, peer_id) in hops.into_iter().enumerate() {
1399            let (tx, rx) = oneshot::channel();
1400            let idx = idx as u8;
1401
1402            circ.command
1403                .unbounded_send(CtrlCmd::AddFakeHop {
1404                    relay_cell_format,
1405                    fwd_lasthop: idx == last_hop_num,
1406                    rev_lasthop: idx == u8::from(next_msg_from),
1407                    peer_id,
1408                    params: Box::new(params.clone()),
1409                    done: tx,
1410                })
1411                .unwrap();
1412            rx.await.unwrap().unwrap();
1413        }
1414        (circ.into_tunnel().unwrap(), circmsg_send)
1415    }
1416
1417    // Helper: set up a 3-hop circuit with no encryption, where the
1418    // next inbound message seems to come from hop next_msg_from
1419    async fn newtunnel<R: Runtime>(
1420        rt: &R,
1421        chan: Arc<Channel>,
1422    ) -> (Arc<ClientTunnel>, CircuitRxSender) {
1423        let hops = std::iter::repeat_with(|| {
1424            let peer_id = tor_linkspec::OwnedChanTarget::builder()
1425                .ed_identity([4; 32].into())
1426                .rsa_identity([5; 20].into())
1427                .build()
1428                .expect("Could not construct fake hop");
1429
1430            path::HopDetail::Relay(peer_id)
1431        })
1432        .take(3)
1433        .collect();
1434
1435        let unique_id = UniqId::new(23, 17);
1436        let (tunnel, circmsg_send) = newtunnel_ext(
1437            rt,
1438            unique_id,
1439            chan,
1440            hops,
1441            2.into(),
1442            CircParameters::default(),
1443        )
1444        .await;
1445
1446        (Arc::new(tunnel), circmsg_send)
1447    }
1448
1449    /// Create `n` distinct [`path::HopDetail`]s,
1450    /// with the specified `start_idx` for the dummy identities.
1451    fn hop_details(n: u8, start_idx: u8) -> Vec<path::HopDetail> {
1452        (0..n)
1453            .map(|idx| {
1454                let peer_id = tor_linkspec::OwnedChanTarget::builder()
1455                    .ed_identity([idx + start_idx; 32].into())
1456                    .rsa_identity([idx + start_idx + 1; 20].into())
1457                    .build()
1458                    .expect("Could not construct fake hop");
1459
1460                path::HopDetail::Relay(peer_id)
1461            })
1462            .collect()
1463    }
1464
1465    #[allow(deprecated)]
1466    async fn test_extend<R: Runtime>(rt: &R, handshake_type: HandshakeType) {
1467        use crate::crypto::handshake::{ServerHandshake, ntor::NtorServer};
1468
1469        let DummyChan {
1470            channel,
1471            mut rx,
1472            tx: _sink,
1473        } = DummyChan::run(rt, ChannelMode::Client);
1474        let (tunnel, mut sink) = newtunnel(rt, channel).await;
1475        let circ = Arc::new(tunnel.as_single_circ().unwrap());
1476        let circid = circ.peek_circid();
1477        let params = CircParameters::default();
1478
1479        let extend_fut = async move {
1480            let target = example_target();
1481            match handshake_type {
1482                HandshakeType::Fast => panic!("Can't extend with Fast handshake"),
1483                HandshakeType::Ntor => circ.extend_ntor(&target, params).await.unwrap(),
1484                HandshakeType::NtorV3 => circ.extend_ntor_v3(&target, params).await.unwrap(),
1485            };
1486            circ // gotta keep the circ alive, or the reactor would exit.
1487        };
1488        let reply_fut = async move {
1489            // We've disabled encryption on this circuit, so we can just
1490            // read the extend2 cell.
1491            let (id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
1492            assert_eq!(id, Some(circid));
1493            let rmsg = match chmsg {
1494                AnyChanMsg::RelayEarly(r) => {
1495                    AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1496                        .unwrap()
1497                }
1498                other => panic!("{:?}", other),
1499            };
1500            let e2 = match rmsg.msg() {
1501                AnyRelayMsg::Extend2(e2) => e2,
1502                other => panic!("{:?}", other),
1503            };
1504            let mut rng = testing_rng();
1505            let reply = match handshake_type {
1506                HandshakeType::Fast => panic!("Can't extend with Fast handshake"),
1507                HandshakeType::Ntor => {
1508                    let (_keygen, reply) = NtorServer::server(
1509                        &mut rng,
1510                        &mut |_: &()| Some(()),
1511                        &[example_ntor_key()],
1512                        e2.handshake(),
1513                    )
1514                    .unwrap();
1515                    reply
1516                }
1517                HandshakeType::NtorV3 => {
1518                    let (_keygen, reply) = NtorV3Server::server(
1519                        &mut rng,
1520                        &mut |_: &[CircRequestExt]| Some(vec![]),
1521                        &[example_ntor_v3_key()],
1522                        e2.handshake(),
1523                    )
1524                    .unwrap();
1525                    reply
1526                }
1527            };
1528
1529            let extended2 = relaymsg::Extended2::new(reply).into();
1530            sink.send(rmsg_to_ccmsg(None, extended2, false))
1531                .await
1532                .unwrap();
1533            (sink, rx) // gotta keep the sink and receiver alive, or the reactor will exit.
1534        };
1535
1536        let (circ, (_sink, _rx)) = futures::join!(extend_fut, reply_fut);
1537
1538        // Did we really add another hop?
1539        assert_eq!(circ.n_hops().unwrap(), 4);
1540
1541        // Do the path accessors report a reasonable outcome?
1542        {
1543            let path = circ.single_path().unwrap();
1544            // Without the 'hs-common' feature, clippy would prefer a `map()`.
1545            #[allow(clippy::unnecessary_filter_map)]
1546            let path = path
1547                .all_hops()
1548                .filter_map(|hop| match hop {
1549                    path::HopDetail::Relay(r) => Some(r),
1550                    #[cfg(feature = "hs-common")]
1551                    path::HopDetail::Virtual => None,
1552                })
1553                .collect::<Vec<_>>();
1554
1555            assert_eq!(path.len(), 4);
1556            use tor_linkspec::HasRelayIds;
1557            assert_eq!(path[3].ed_identity(), example_target().ed_identity());
1558            assert_ne!(path[0].ed_identity(), example_target().ed_identity());
1559        }
1560        {
1561            let path = circ.single_path().unwrap();
1562            assert_eq!(path.n_hops(), 4);
1563            use tor_linkspec::HasRelayIds;
1564            assert_eq!(
1565                path.hops()[3].as_chan_target().unwrap().ed_identity(),
1566                example_target().ed_identity()
1567            );
1568            assert_ne!(
1569                path.hops()[0].as_chan_target().unwrap().ed_identity(),
1570                example_target().ed_identity()
1571            );
1572        }
1573    }
1574
1575    #[traced_test]
1576    #[test]
1577    fn test_extend_ntor() {
1578        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1579            test_extend(&rt, HandshakeType::Ntor).await;
1580        });
1581    }
1582
1583    #[traced_test]
1584    #[test]
1585    fn test_extend_ntor_v3() {
1586        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1587            test_extend(&rt, HandshakeType::NtorV3).await;
1588        });
1589    }
1590
1591    #[allow(deprecated)]
1592    async fn bad_extend_test_impl<R: Runtime>(
1593        rt: &R,
1594        reply_hop: HopNum,
1595        bad_reply: AnyChanMsg,
1596    ) -> Error {
1597        let DummyChan {
1598            channel,
1599            mut rx,
1600            tx: _sink,
1601        } = DummyChan::run(rt, ChannelMode::Client);
1602        let hops = std::iter::repeat_with(|| {
1603            let peer_id = tor_linkspec::OwnedChanTarget::builder()
1604                .ed_identity([4; 32].into())
1605                .rsa_identity([5; 20].into())
1606                .build()
1607                .expect("Could not construct fake hop");
1608
1609            path::HopDetail::Relay(peer_id)
1610        })
1611        .take(3)
1612        .collect();
1613
1614        let unique_id = UniqId::new(23, 17);
1615        let (tunnel, mut sink) = newtunnel_ext(
1616            rt,
1617            unique_id,
1618            channel,
1619            hops,
1620            reply_hop,
1621            CircParameters::default(),
1622        )
1623        .await;
1624        let params = CircParameters::default();
1625
1626        let target = example_target();
1627        let reply_task_handle = rt
1628            .spawn_with_handle(async move {
1629                // Wait for a cell, and make sure it's EXTEND2.
1630                let (_circid, chanmsg) = rx.next().await.unwrap().into_circid_and_msg();
1631                let AnyChanMsg::RelayEarly(relay_early) = chanmsg else {
1632                    panic!("unexpected message {chanmsg:?}");
1633                };
1634                let relaymsg = UnparsedRelayMsg::from_singleton_body(
1635                    RelayCellFormat::V0,
1636                    relay_early.into_relay_body(),
1637                )
1638                .unwrap();
1639                assert_eq!(relaymsg.cmd(), RelayCmd::EXTEND2);
1640
1641                // Send back the "bad_reply."
1642                sink.send(bad_reply).await.unwrap();
1643                sink
1644            })
1645            .unwrap();
1646        let outcome = tunnel
1647            .as_single_circ()
1648            .unwrap()
1649            .extend_ntor(&target, params)
1650            .await;
1651        let _sink = reply_task_handle.await;
1652
1653        assert_eq!(tunnel.n_hops().unwrap(), 3);
1654        assert!(outcome.is_err());
1655        outcome.unwrap_err()
1656    }
1657
1658    #[traced_test]
1659    #[test]
1660    fn bad_extend_wronghop() {
1661        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1662            let extended2 = relaymsg::Extended2::new(vec![]).into();
1663            let cc = rmsg_to_ccmsg(None, extended2, false);
1664
1665            let error = bad_extend_test_impl(&rt, 1.into(), cc).await;
1666            // This case shows up as a CircDestroy, since a message sent
1667            // from the wrong hop won't even be delivered to the extend
1668            // code's meta-handler.  Instead the unexpected message will cause
1669            // the circuit to get torn down.
1670            match error {
1671                Error::CircuitClosed => {}
1672                x => panic!("got other error: {}", x),
1673            }
1674        });
1675    }
1676
1677    #[traced_test]
1678    #[test]
1679    fn bad_extend_wrongtype() {
1680        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1681            let extended = relaymsg::Extended::new(vec![7; 200]).into();
1682            let cc = rmsg_to_ccmsg(None, extended, false);
1683
1684            let error = bad_extend_test_impl(&rt, 2.into(), cc).await;
1685            match error {
1686                Error::BytesErr {
1687                    err: tor_bytes::Error::InvalidMessage(_),
1688                    object: "extended2 message",
1689                } => {}
1690                other => panic!("{:?}", other),
1691            }
1692        });
1693    }
1694
1695    #[traced_test]
1696    #[test]
1697    fn bad_extend_destroy() {
1698        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1699            let cc = AnyChanMsg::Destroy(chanmsg::Destroy::new(4.into()));
1700            let error = bad_extend_test_impl(&rt, 2.into(), cc).await;
1701            match error {
1702                Error::CircuitClosed => {}
1703                other => panic!("{:?}", other),
1704            }
1705        });
1706    }
1707
1708    #[traced_test]
1709    #[test]
1710    fn bad_extend_crypto() {
1711        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1712            let extended2 = relaymsg::Extended2::new(vec![99; 256]).into();
1713            let cc = rmsg_to_ccmsg(None, extended2, false);
1714            let error = bad_extend_test_impl(&rt, 2.into(), cc).await;
1715            assert_matches!(error, Error::BadCircHandshakeAuth);
1716        });
1717    }
1718
1719    #[traced_test]
1720    #[test]
1721    fn begindir() {
1722        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1723            let DummyChan {
1724                channel,
1725                mut rx,
1726                tx: _sink,
1727            } = DummyChan::run(&rt, ChannelMode::Client);
1728            let (tunnel, mut sink) = newtunnel(&rt, channel).await;
1729            let circ = tunnel.as_single_circ().unwrap();
1730            let circid = circ.peek_circid();
1731
1732            let begin_and_send_fut = async move {
1733                // Here we'll say we've got a circuit, and we want to
1734                // make a simple BEGINDIR request with it.
1735                let mut stream = tunnel.begin_dir_stream().await.unwrap();
1736                stream.write_all(b"HTTP/1.0 GET /\r\n").await.unwrap();
1737                stream.flush().await.unwrap();
1738                let mut buf = [0_u8; 1024];
1739                let n = stream.read(&mut buf).await.unwrap();
1740                assert_eq!(&buf[..n], b"HTTP/1.0 404 Not found\r\n");
1741                let n = stream.read(&mut buf).await.unwrap();
1742                assert_eq!(n, 0);
1743                stream
1744            };
1745            let reply_fut = async move {
1746                // We've disabled encryption on this circuit, so we can just
1747                // read the begindir cell.
1748                let (id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
1749                assert_eq!(id, Some(circid));
1750                let rmsg = match chmsg {
1751                    AnyChanMsg::Relay(r) => {
1752                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1753                            .unwrap()
1754                    }
1755                    other => panic!("{:?}", other),
1756                };
1757                let (streamid, rmsg) = rmsg.into_streamid_and_msg();
1758                assert_matches!(rmsg, AnyRelayMsg::BeginDir(_));
1759
1760                // Reply with a Connected cell to indicate success.
1761                let connected = relaymsg::Connected::new_empty().into();
1762                sink.send(rmsg_to_ccmsg(streamid, connected, false))
1763                    .await
1764                    .unwrap();
1765
1766                // Now read a DATA cell...
1767                let (id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
1768                assert_eq!(id, Some(circid));
1769                let rmsg = match chmsg {
1770                    AnyChanMsg::Relay(r) => {
1771                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1772                            .unwrap()
1773                    }
1774                    other => panic!("{:?}", other),
1775                };
1776                let (streamid_2, rmsg) = rmsg.into_streamid_and_msg();
1777                assert_eq!(streamid_2, streamid);
1778                if let AnyRelayMsg::Data(d) = rmsg {
1779                    assert_eq!(d.as_ref(), &b"HTTP/1.0 GET /\r\n"[..]);
1780                } else {
1781                    panic!();
1782                }
1783
1784                // Write another data cell in reply!
1785                let data = relaymsg::Data::new(b"HTTP/1.0 404 Not found\r\n")
1786                    .unwrap()
1787                    .into();
1788                sink.send(rmsg_to_ccmsg(streamid, data, false))
1789                    .await
1790                    .unwrap();
1791
1792                // Send an END cell to say that the conversation is over.
1793                let end = relaymsg::End::new_with_reason(relaymsg::EndReason::DONE).into();
1794                sink.send(rmsg_to_ccmsg(streamid, end, false))
1795                    .await
1796                    .unwrap();
1797
1798                (rx, sink) // gotta keep these alive, or the reactor will exit.
1799            };
1800
1801            let (_stream, (_rx, _sink)) = futures::join!(begin_and_send_fut, reply_fut);
1802        });
1803    }
1804
1805    // Test: close a stream, either by dropping it or by calling AsyncWriteExt::close.
1806    fn close_stream_helper(by_drop: bool) {
1807        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
1808            let DummyChan {
1809                channel,
1810                mut rx,
1811                tx: _sink,
1812            } = DummyChan::run(&rt, ChannelMode::Client);
1813            let (tunnel, mut sink) = newtunnel(&rt, channel).await;
1814
1815            let stream_fut = async move {
1816                let stream = tunnel
1817                    .begin_stream("www.example.com", 80, None)
1818                    .await
1819                    .unwrap();
1820
1821                let (r, mut w) = stream.split();
1822                if by_drop {
1823                    // Drop the writer and the reader, which should close the stream.
1824                    drop(r);
1825                    drop(w);
1826                    (None, tunnel) // make sure to keep the circuit alive
1827                } else {
1828                    // Call close on the writer, while keeping the reader alive.
1829                    w.close().await.unwrap();
1830                    (Some(r), tunnel)
1831                }
1832            };
1833            let handler_fut = async {
1834                // Read the BEGIN message.
1835                let (_, msg) = rx.next().await.unwrap().into_circid_and_msg();
1836                let rmsg = match msg {
1837                    AnyChanMsg::Relay(r) => {
1838                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1839                            .unwrap()
1840                    }
1841                    other => panic!("{:?}", other),
1842                };
1843                let (streamid, rmsg) = rmsg.into_streamid_and_msg();
1844                assert_eq!(rmsg.cmd(), RelayCmd::BEGIN);
1845
1846                // Reply with a CONNECTED.
1847                let connected =
1848                    relaymsg::Connected::new_with_addr("10.0.0.1".parse().unwrap(), 1234).into();
1849                sink.send(rmsg_to_ccmsg(streamid, connected, false))
1850                    .await
1851                    .unwrap();
1852
1853                // Expect an END.
1854                let (_, msg) = rx.next().await.unwrap().into_circid_and_msg();
1855                let rmsg = match msg {
1856                    AnyChanMsg::Relay(r) => {
1857                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1858                            .unwrap()
1859                    }
1860                    other => panic!("{:?}", other),
1861                };
1862                let (_, rmsg) = rmsg.into_streamid_and_msg();
1863                assert_eq!(rmsg.cmd(), RelayCmd::END);
1864
1865                (rx, sink) // keep these alive or the reactor will exit.
1866            };
1867
1868            let ((_opt_reader, _circ), (_rx, _sink)) = futures::join!(stream_fut, handler_fut);
1869        });
1870    }
1871
1872    #[traced_test]
1873    #[test]
1874    fn drop_stream() {
1875        close_stream_helper(true);
1876    }
1877
1878    #[traced_test]
1879    #[test]
1880    fn close_stream() {
1881        close_stream_helper(false);
1882    }
1883
1884    #[traced_test]
1885    #[test]
1886    fn expire_halfstreams() {
1887        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
1888            let DummyChan {
1889                channel,
1890                mut rx,
1891                tx: _sink,
1892            } = DummyChan::run(&rt, ChannelMode::Client);
1893            let (tunnel, mut sink) = newtunnel(&rt, channel).await;
1894
1895            let client_fut = async move {
1896                let stream = tunnel
1897                    .begin_stream("www.example.com", 80, None)
1898                    .await
1899                    .unwrap();
1900
1901                let (r, mut w) = stream.split();
1902                // Close the stream
1903                w.close().await.unwrap();
1904                (Some(r), tunnel)
1905            };
1906            let exit_fut = async {
1907                // Read the BEGIN message.
1908                let (_, msg) = rx.next().await.unwrap().into_circid_and_msg();
1909                let rmsg = match msg {
1910                    AnyChanMsg::Relay(r) => {
1911                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
1912                            .unwrap()
1913                    }
1914                    other => panic!("{:?}", other),
1915                };
1916                let (streamid, rmsg) = rmsg.into_streamid_and_msg();
1917                assert_eq!(rmsg.cmd(), RelayCmd::BEGIN);
1918
1919                // Reply with a CONNECTED.
1920                let connected =
1921                    relaymsg::Connected::new_with_addr("10.0.0.1".parse().unwrap(), 1234).into();
1922                sink.send(rmsg_to_ccmsg(streamid, connected, false))
1923                    .await
1924                    .unwrap();
1925
1926                (rx, streamid, sink) // keep these alive or the reactor will exit.
1927            };
1928
1929            let ((_opt_reader, tunnel), (_rx, streamid, mut sink)) =
1930                futures::join!(client_fut, exit_fut);
1931
1932            // Progress all futures to ensure the reactor has a chance to notice
1933            // we closed the stream.
1934            rt.progress_until_stalled().await;
1935
1936            // The tunnel should remain open
1937            assert!(!tunnel.is_closed());
1938
1939            // Write some more data on the half-stream.
1940            // The half-stream hasn't expired yet, so it will simply be ignored.
1941            let data = relaymsg::Data::new(b"hello").unwrap();
1942            sink.send(rmsg_to_ccmsg(streamid, AnyRelayMsg::Data(data), false))
1943                .await
1944                .unwrap();
1945            rt.progress_until_stalled().await;
1946
1947            // This was not a protocol violation, so the tunnel is still alive.
1948            assert!(!tunnel.is_closed());
1949
1950            // Advance the time to cause the half-streams to get garbage collected.
1951            //
1952            // Advancing it by 2 * CBT ought to be enough, because the RTT estimator
1953            // won't yet have an estimate for the max_rtt.
1954            let stream_timeout = DummyTimeoutEstimator.circuit_build_timeout(3);
1955            rt.advance_by(2 * stream_timeout).await;
1956
1957            // Sending this cell is a protocol violation now
1958            // that the half-stream expired.
1959            let data = relaymsg::Data::new(b"hello").unwrap();
1960            sink.send(rmsg_to_ccmsg(streamid, AnyRelayMsg::Data(data), false))
1961                .await
1962                .unwrap();
1963            rt.progress_until_stalled().await;
1964
1965            // The tunnel shut down because of the proto violation.
1966            assert!(tunnel.is_closed());
1967        });
1968    }
1969
1970    // Set up a circuit and stream that expects some incoming SENDMEs.
1971    async fn setup_incoming_sendme_case<R: Runtime>(
1972        rt: &R,
1973        n_to_send: usize,
1974    ) -> (
1975        Arc<ClientTunnel>,
1976        DataStream,
1977        CircuitRxSender,
1978        Option<StreamId>,
1979        usize,
1980        Receiver<AnyChanCell>,
1981        Sender<CodecResult>,
1982    ) {
1983        let DummyChan {
1984            channel,
1985            mut rx,
1986            tx: sink2,
1987        } = DummyChan::run(rt, ChannelMode::Client);
1988        let (tunnel, mut sink) = newtunnel(rt, channel).await;
1989        let circid = tunnel.as_single_circ().unwrap().peek_circid();
1990
1991        let begin_and_send_fut = {
1992            let tunnel = tunnel.clone();
1993            async move {
1994                // Take our circuit and make a stream on it.
1995                let mut stream = tunnel
1996                    .begin_stream("www.example.com", 443, None)
1997                    .await
1998                    .unwrap();
1999                let junk = [0_u8; 1024];
2000                let mut remaining = n_to_send;
2001                while remaining > 0 {
2002                    let n = std::cmp::min(remaining, junk.len());
2003                    stream.write_all(&junk[..n]).await.unwrap();
2004                    remaining -= n;
2005                }
2006                stream.flush().await.unwrap();
2007                stream
2008            }
2009        };
2010
2011        let receive_fut = async move {
2012            // Read the begin cell.
2013            let (_id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
2014            let rmsg = match chmsg {
2015                AnyChanMsg::Relay(r) => {
2016                    AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
2017                        .unwrap()
2018                }
2019                other => panic!("{:?}", other),
2020            };
2021            let (streamid, rmsg) = rmsg.into_streamid_and_msg();
2022            assert_matches!(rmsg, AnyRelayMsg::Begin(_));
2023            // Reply with a connected cell...
2024            let connected = relaymsg::Connected::new_empty().into();
2025            sink.send(rmsg_to_ccmsg(streamid, connected, false))
2026                .await
2027                .unwrap();
2028            // Now read bytes from the stream until we have them all.
2029            let mut bytes_received = 0_usize;
2030            let mut cells_received = 0_usize;
2031            while bytes_received < n_to_send {
2032                // Read a data cell, and remember how much we got.
2033                let (id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
2034                assert_eq!(id, Some(circid));
2035
2036                let rmsg = match chmsg {
2037                    AnyChanMsg::Relay(r) => {
2038                        AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
2039                            .unwrap()
2040                    }
2041                    other => panic!("{:?}", other),
2042                };
2043                let (streamid2, rmsg) = rmsg.into_streamid_and_msg();
2044                assert_eq!(streamid2, streamid);
2045                if let AnyRelayMsg::Data(dat) = rmsg {
2046                    cells_received += 1;
2047                    bytes_received += dat.as_ref().len();
2048                } else {
2049                    panic!();
2050                }
2051            }
2052
2053            (sink, streamid, cells_received, rx)
2054        };
2055
2056        let (stream, (sink, streamid, cells_received, rx)) =
2057            futures::join!(begin_and_send_fut, receive_fut);
2058
2059        (tunnel, stream, sink, streamid, cells_received, rx, sink2)
2060    }
2061
2062    #[traced_test]
2063    #[test]
2064    fn accept_valid_sendme() {
2065        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2066            let (tunnel, _stream, mut sink, streamid, cells_received, _rx, _sink2) =
2067                setup_incoming_sendme_case(&rt, 300 * 498 + 3).await;
2068            let circ = tunnel.as_single_circ().unwrap();
2069
2070            assert_eq!(cells_received, 301);
2071
2072            // Make sure that the circuit is indeed expecting the right sendmes
2073            {
2074                let (tx, rx) = oneshot::channel();
2075                circ.command
2076                    .unbounded_send(CtrlCmd::QuerySendWindow {
2077                        hop: 2.into(),
2078                        leg: tunnel.unique_id(),
2079                        done: tx,
2080                    })
2081                    .unwrap();
2082                let (window, tags) = rx.await.unwrap().unwrap();
2083                assert_eq!(window, 1000 - 301);
2084                assert_eq!(tags.len(), 3);
2085                // 100
2086                assert_eq!(
2087                    tags[0],
2088                    SendmeTag::from(hex!("6400000000000000000000000000000000000000"))
2089                );
2090                // 200
2091                assert_eq!(
2092                    tags[1],
2093                    SendmeTag::from(hex!("c800000000000000000000000000000000000000"))
2094                );
2095                // 300
2096                assert_eq!(
2097                    tags[2],
2098                    SendmeTag::from(hex!("2c01000000000000000000000000000000000000"))
2099                );
2100            }
2101
2102            let reply_with_sendme_fut = async move {
2103                // make and send a circuit-level sendme.
2104                let c_sendme =
2105                    relaymsg::Sendme::new_tag(hex!("6400000000000000000000000000000000000000"))
2106                        .into();
2107                sink.send(rmsg_to_ccmsg(None, c_sendme, false))
2108                    .await
2109                    .unwrap();
2110
2111                // Make and send a stream-level sendme.
2112                let s_sendme = relaymsg::Sendme::new_empty().into();
2113                sink.send(rmsg_to_ccmsg(streamid, s_sendme, false))
2114                    .await
2115                    .unwrap();
2116
2117                sink
2118            };
2119
2120            let _sink = reply_with_sendme_fut.await;
2121
2122            rt.advance_until_stalled().await;
2123
2124            // Now make sure that the circuit is still happy, and its
2125            // window is updated.
2126            {
2127                let (tx, rx) = oneshot::channel();
2128                circ.command
2129                    .unbounded_send(CtrlCmd::QuerySendWindow {
2130                        hop: 2.into(),
2131                        leg: tunnel.unique_id(),
2132                        done: tx,
2133                    })
2134                    .unwrap();
2135                let (window, _tags) = rx.await.unwrap().unwrap();
2136                assert_eq!(window, 1000 - 201);
2137            }
2138        });
2139    }
2140
2141    #[traced_test]
2142    #[test]
2143    fn invalid_circ_sendme() {
2144        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2145            // Same setup as accept_valid_sendme() test above but try giving
2146            // a sendme with the wrong tag.
2147
2148            let (tunnel, _stream, mut sink, _streamid, _cells_received, _rx, _sink2) =
2149                setup_incoming_sendme_case(&rt, 300 * 498 + 3).await;
2150
2151            let reply_with_sendme_fut = async move {
2152                // make and send a circuit-level sendme with a bad tag.
2153                let c_sendme =
2154                    relaymsg::Sendme::new_tag(hex!("FFFF0000000000000000000000000000000000FF"))
2155                        .into();
2156                sink.send(rmsg_to_ccmsg(None, c_sendme, false))
2157                    .await
2158                    .unwrap();
2159                sink
2160            };
2161
2162            let _sink = reply_with_sendme_fut.await;
2163
2164            // Check whether the reactor dies as a result of receiving invalid data.
2165            rt.advance_until_stalled().await;
2166            assert!(tunnel.is_closed());
2167        });
2168    }
2169
2170    #[traced_test]
2171    #[test]
2172    fn test_busy_stream_fairness() {
2173        // Number of streams to use.
2174        const N_STREAMS: usize = 3;
2175        // Number of cells (roughly) for each stream to send.
2176        const N_CELLS: usize = 20;
2177        // Number of bytes that *each* stream will send, and that we'll read
2178        // from the channel.
2179        const N_BYTES: usize = relaymsg::Data::MAXLEN_V0 * N_CELLS;
2180        // Ignoring cell granularity, with perfect fairness we'd expect
2181        // `N_BYTES/N_STREAMS` bytes from each stream.
2182        //
2183        // We currently allow for up to a full cell less than that.  This is
2184        // somewhat arbitrary and can be changed as needed, since we don't
2185        // provide any specific fairness guarantees.
2186        const MIN_EXPECTED_BYTES_PER_STREAM: usize =
2187            N_BYTES / N_STREAMS - relaymsg::Data::MAXLEN_V0;
2188
2189        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
2190            let DummyChan {
2191                channel,
2192                mut rx,
2193                tx: _sink,
2194            } = DummyChan::run(&rt, ChannelMode::Client);
2195            let (tunnel, mut sink) = newtunnel(&rt, channel).await;
2196
2197            // Run clients in a single task, doing our own round-robin
2198            // scheduling of writes to the reactor. Conversely, if we were to
2199            // put each client in its own task, we would be at the mercy of
2200            // how fairly the runtime schedules the client tasks, which is outside
2201            // the scope of this test.
2202            rt.spawn({
2203                // Clone the circuit to keep it alive after writers have
2204                // finished with it.
2205                let tunnel = tunnel.clone();
2206                async move {
2207                    let mut clients = VecDeque::new();
2208                    struct Client {
2209                        stream: DataStream,
2210                        to_write: &'static [u8],
2211                    }
2212                    for _ in 0..N_STREAMS {
2213                        clients.push_back(Client {
2214                            stream: tunnel
2215                                .begin_stream("www.example.com", 80, None)
2216                                .await
2217                                .unwrap(),
2218                            to_write: &[0_u8; N_BYTES][..],
2219                        });
2220                    }
2221                    while let Some(mut client) = clients.pop_front() {
2222                        if client.to_write.is_empty() {
2223                            // Client is done. Don't put back in queue.
2224                            continue;
2225                        }
2226                        let written = client.stream.write(client.to_write).await.unwrap();
2227                        client.to_write = &client.to_write[written..];
2228                        clients.push_back(client);
2229                    }
2230                }
2231            })
2232            .unwrap();
2233
2234            let channel_handler_fut = async {
2235                let mut stream_bytes_received = HashMap::<StreamId, usize>::new();
2236                let mut total_bytes_received = 0;
2237
2238                loop {
2239                    let (_, msg) = rx.next().await.unwrap().into_circid_and_msg();
2240                    let rmsg = match msg {
2241                        AnyChanMsg::Relay(r) => AnyRelayMsgOuter::decode_singleton(
2242                            RelayCellFormat::V0,
2243                            r.into_relay_body(),
2244                        )
2245                        .unwrap(),
2246                        other => panic!("Unexpected chanmsg: {other:?}"),
2247                    };
2248                    let (streamid, rmsg) = rmsg.into_streamid_and_msg();
2249                    match rmsg.cmd() {
2250                        RelayCmd::BEGIN => {
2251                            // Add an entry for this stream.
2252                            let prev = stream_bytes_received.insert(streamid.unwrap(), 0);
2253                            assert_eq!(prev, None);
2254                            // Reply with a CONNECTED.
2255                            let connected = relaymsg::Connected::new_with_addr(
2256                                "10.0.0.1".parse().unwrap(),
2257                                1234,
2258                            )
2259                            .into();
2260                            sink.send(rmsg_to_ccmsg(streamid, connected, false))
2261                                .await
2262                                .unwrap();
2263                        }
2264                        RelayCmd::DATA => {
2265                            let data_msg = relaymsg::Data::try_from(rmsg).unwrap();
2266                            let nbytes = data_msg.as_ref().len();
2267                            total_bytes_received += nbytes;
2268                            let streamid = streamid.unwrap();
2269                            let stream_bytes = stream_bytes_received.get_mut(&streamid).unwrap();
2270                            *stream_bytes += nbytes;
2271                            if total_bytes_received >= N_BYTES {
2272                                break;
2273                            }
2274                        }
2275                        RelayCmd::END => {
2276                            // Stream is done. If fair scheduling is working as
2277                            // expected we *probably* shouldn't get here, but we
2278                            // can ignore it and save the failure until we
2279                            // actually have the final stats.
2280                            continue;
2281                        }
2282                        other => {
2283                            panic!("Unexpected command {other:?}");
2284                        }
2285                    }
2286                }
2287
2288                // Return our stats, along with the `rx` and `sink` to keep the
2289                // reactor alive (since clients could still be writing).
2290                (total_bytes_received, stream_bytes_received, rx, sink)
2291            };
2292
2293            let (total_bytes_received, stream_bytes_received, _rx, _sink) =
2294                channel_handler_fut.await;
2295            assert_eq!(stream_bytes_received.len(), N_STREAMS);
2296            for (sid, stream_bytes) in stream_bytes_received {
2297                assert!(
2298                    stream_bytes >= MIN_EXPECTED_BYTES_PER_STREAM,
2299                    "Only {stream_bytes} of {total_bytes_received} bytes received from {N_STREAMS} came from {sid:?}; expected at least {MIN_EXPECTED_BYTES_PER_STREAM}"
2300                );
2301            }
2302        });
2303    }
2304
2305    #[test]
2306    fn basic_params() {
2307        use super::CircParameters;
2308        let mut p = CircParameters::default();
2309        assert!(p.extend_by_ed25519_id);
2310
2311        p.extend_by_ed25519_id = false;
2312        assert!(!p.extend_by_ed25519_id);
2313    }
2314
2315    #[traced_test]
2316    #[test]
2317    #[cfg(feature = "hs-service")]
2318    fn allow_stream_requests_twice() {
2319        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
2320            let DummyChan {
2321                channel,
2322                rx: _rx,
2323                tx: _sink,
2324            } = DummyChan::run(&rt, ChannelMode::Client);
2325            let (tunnel, _send) = newtunnel(&rt, channel).await;
2326
2327            let _incoming = tunnel
2328                .allow_stream_requests(
2329                    &[tor_cell::relaycell::RelayCmd::BEGIN],
2330                    tunnel.resolve_last_hop().await,
2331                    AllowAllStreamsFilter,
2332                )
2333                .await
2334                .unwrap();
2335
2336            let incoming = tunnel
2337                .allow_stream_requests(
2338                    &[tor_cell::relaycell::RelayCmd::BEGIN],
2339                    tunnel.resolve_last_hop().await,
2340                    AllowAllStreamsFilter,
2341                )
2342                .await;
2343
2344            // There can only be one IncomingStream at a time on any given circuit.
2345            assert!(incoming.is_err());
2346        });
2347    }
2348
2349    #[traced_test]
2350    #[test]
2351    #[cfg(feature = "hs-service")]
2352    fn allow_stream_requests() {
2353        use tor_cell::relaycell::msg::BeginFlags;
2354
2355        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
2356            const TEST_DATA: &[u8] = b"ping";
2357
2358            let DummyChan {
2359                channel,
2360                rx: _rx,
2361                tx: _sink,
2362            } = DummyChan::run(&rt, ChannelMode::Client);
2363            let (tunnel, mut send) = newtunnel(&rt, channel).await;
2364
2365            let rfmt = RelayCellFormat::V0;
2366
2367            // A helper channel for coordinating the "client"/"service" interaction
2368            let (tx, rx) = oneshot::channel();
2369            let mut incoming = tunnel
2370                .allow_stream_requests(
2371                    &[tor_cell::relaycell::RelayCmd::BEGIN],
2372                    tunnel.resolve_last_hop().await,
2373                    AllowAllStreamsFilter,
2374                )
2375                .await
2376                .unwrap();
2377
2378            let simulate_service = async move {
2379                let stream = incoming.next().await.unwrap();
2380                let mut data_stream = stream
2381                    .accept_data(relaymsg::Connected::new_empty())
2382                    .await
2383                    .unwrap();
2384                // Notify the client task we're ready to accept DATA cells
2385                tx.send(()).unwrap();
2386
2387                // Read the data the client sent us
2388                let mut buf = [0_u8; TEST_DATA.len()];
2389                data_stream.read_exact(&mut buf).await.unwrap();
2390                assert_eq!(&buf, TEST_DATA);
2391
2392                tunnel
2393            };
2394
2395            let simulate_client = async move {
2396                let begin = relaymsg::Begin::new("localhost", 80, BeginFlags::IPV6_OKAY).unwrap();
2397                let body: BoxedCellBody =
2398                    AnyRelayMsgOuter::new(StreamId::new(12), AnyRelayMsg::Begin(begin))
2399                        .encode(rfmt, &mut testing_rng())
2400                        .unwrap();
2401                let begin_msg = chanmsg::Relay::from(body);
2402
2403                // Pretend to be a client at the other end of the circuit sending a begin cell
2404                send.send(AnyChanMsg::Relay(begin_msg)).await.unwrap();
2405
2406                // Wait until the service is ready to accept data
2407                // TODO: we shouldn't need to wait! This is needed because the service will reject
2408                // any DATA cells that aren't associated with a known stream. We need to wait until
2409                // the service receives our BEGIN cell (and the reactor updates hop.map with the
2410                // new stream).
2411                rx.await.unwrap();
2412                // Now send some data along the newly established circuit..
2413                let data = relaymsg::Data::new(TEST_DATA).unwrap();
2414                let body: BoxedCellBody =
2415                    AnyRelayMsgOuter::new(StreamId::new(12), AnyRelayMsg::Data(data))
2416                        .encode(rfmt, &mut testing_rng())
2417                        .unwrap();
2418                let data_msg = chanmsg::Relay::from(body);
2419
2420                send.send(AnyChanMsg::Relay(data_msg)).await.unwrap();
2421                send
2422            };
2423
2424            let (_circ, _send) = futures::join!(simulate_service, simulate_client);
2425        });
2426    }
2427
2428    #[traced_test]
2429    #[test]
2430    #[cfg(feature = "hs-service")]
2431    fn accept_stream_after_reject() {
2432        use tor_cell::relaycell::msg::AnyRelayMsg;
2433        use tor_cell::relaycell::msg::BeginFlags;
2434        use tor_cell::relaycell::msg::EndReason;
2435
2436        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
2437            const TEST_DATA: &[u8] = b"ping";
2438            const STREAM_COUNT: usize = 2;
2439            let rfmt = RelayCellFormat::V0;
2440
2441            let DummyChan {
2442                channel,
2443                rx: _rx,
2444                tx: _sink,
2445            } = DummyChan::run(&rt, ChannelMode::Client);
2446            let (tunnel, mut send) = newtunnel(&rt, channel).await;
2447
2448            // A helper channel for coordinating the "client"/"service" interaction
2449            let (mut tx, mut rx) = mpsc::channel(STREAM_COUNT);
2450
2451            let mut incoming = tunnel
2452                .allow_stream_requests(
2453                    &[tor_cell::relaycell::RelayCmd::BEGIN],
2454                    tunnel.resolve_last_hop().await,
2455                    AllowAllStreamsFilter,
2456                )
2457                .await
2458                .unwrap();
2459
2460            let simulate_service = async move {
2461                // Process 2 incoming streams
2462                for i in 0..STREAM_COUNT {
2463                    let stream = incoming.next().await.unwrap();
2464
2465                    // Reject the first one
2466                    if i == 0 {
2467                        stream
2468                            .reject(relaymsg::End::new_with_reason(EndReason::INTERNAL))
2469                            .await
2470                            .unwrap();
2471                        // Notify the client
2472                        tx.send(()).await.unwrap();
2473                        continue;
2474                    }
2475
2476                    let mut data_stream = stream
2477                        .accept_data(relaymsg::Connected::new_empty())
2478                        .await
2479                        .unwrap();
2480                    // Notify the client task we're ready to accept DATA cells
2481                    tx.send(()).await.unwrap();
2482
2483                    // Read the data the client sent us
2484                    let mut buf = [0_u8; TEST_DATA.len()];
2485                    data_stream.read_exact(&mut buf).await.unwrap();
2486                    assert_eq!(&buf, TEST_DATA);
2487                }
2488
2489                tunnel
2490            };
2491
2492            let simulate_client = async move {
2493                let begin = relaymsg::Begin::new("localhost", 80, BeginFlags::IPV6_OKAY).unwrap();
2494                let body: BoxedCellBody =
2495                    AnyRelayMsgOuter::new(StreamId::new(12), AnyRelayMsg::Begin(begin))
2496                        .encode(rfmt, &mut testing_rng())
2497                        .unwrap();
2498                let begin_msg = chanmsg::Relay::from(body);
2499
2500                // Pretend to be a client at the other end of the circuit sending 2 identical begin
2501                // cells (the first one will be rejected by the test service).
2502                for _ in 0..STREAM_COUNT {
2503                    send.send(AnyChanMsg::Relay(begin_msg.clone()))
2504                        .await
2505                        .unwrap();
2506
2507                    // Wait until the service rejects our request
2508                    rx.next().await.unwrap();
2509                }
2510
2511                // Now send some data along the newly established circuit..
2512                let data = relaymsg::Data::new(TEST_DATA).unwrap();
2513                let body: BoxedCellBody =
2514                    AnyRelayMsgOuter::new(StreamId::new(12), AnyRelayMsg::Data(data))
2515                        .encode(rfmt, &mut testing_rng())
2516                        .unwrap();
2517                let data_msg = chanmsg::Relay::from(body);
2518
2519                send.send(AnyChanMsg::Relay(data_msg)).await.unwrap();
2520                send
2521            };
2522
2523            let (_circ, _send) = futures::join!(simulate_service, simulate_client);
2524        });
2525    }
2526
2527    #[traced_test]
2528    #[test]
2529    #[cfg(feature = "hs-service")]
2530    fn incoming_stream_bad_hop() {
2531        use tor_cell::relaycell::msg::BeginFlags;
2532
2533        tor_rtcompat::test_with_all_runtimes!(|rt| async move {
2534            /// Expect the originator of the BEGIN cell to be hop 1.
2535            const EXPECTED_HOP: u8 = 1;
2536            let rfmt = RelayCellFormat::V0;
2537
2538            let DummyChan {
2539                channel,
2540                rx: _rx,
2541                tx: _sink,
2542            } = DummyChan::run(&rt, ChannelMode::Client);
2543            let (tunnel, mut send) = newtunnel(&rt, channel).await;
2544
2545            // Expect to receive incoming streams from hop EXPECTED_HOP
2546            let mut incoming = tunnel
2547                .allow_stream_requests(
2548                    &[tor_cell::relaycell::RelayCmd::BEGIN],
2549                    // Build the precise HopLocation with the underlying circuit.
2550                    (
2551                        tunnel.as_single_circ().unwrap().unique_id(),
2552                        EXPECTED_HOP.into(),
2553                    )
2554                        .into(),
2555                    AllowAllStreamsFilter,
2556                )
2557                .await
2558                .unwrap();
2559
2560            let simulate_service = async move {
2561                // The originator of the cell is actually the last hop on the circuit, not hop 1,
2562                // so we expect the reactor to shut down.
2563                assert!(incoming.next().await.is_none());
2564                tunnel
2565            };
2566
2567            let simulate_client = async move {
2568                let begin = relaymsg::Begin::new("localhost", 80, BeginFlags::IPV6_OKAY).unwrap();
2569                let body: BoxedCellBody =
2570                    AnyRelayMsgOuter::new(StreamId::new(12), AnyRelayMsg::Begin(begin))
2571                        .encode(rfmt, &mut testing_rng())
2572                        .unwrap();
2573                let begin_msg = chanmsg::Relay::from(body);
2574
2575                // Pretend to be a client at the other end of the circuit sending a begin cell
2576                send.send(AnyChanMsg::Relay(begin_msg)).await.unwrap();
2577
2578                send
2579            };
2580
2581            let (_circ, _send) = futures::join!(simulate_service, simulate_client);
2582        });
2583    }
2584
2585    #[traced_test]
2586    #[test]
2587    #[cfg(feature = "conflux")]
2588    fn multipath_circ_validation() {
2589        use std::error::Error as _;
2590
2591        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2592            let params = CircParameters::default();
2593            let invalid_tunnels = [
2594                setup_bad_conflux_tunnel(&rt).await,
2595                setup_conflux_tunnel(&rt, true, params).await,
2596            ];
2597
2598            for tunnel in invalid_tunnels {
2599                let TestTunnelCtx {
2600                    tunnel: _tunnel,
2601                    circs: _circs,
2602                    conflux_link_rx,
2603                } = tunnel;
2604
2605                let conflux_hs_err = conflux_link_rx.await.unwrap().unwrap_err();
2606                let err_src = conflux_hs_err.source().unwrap();
2607
2608                // The two circuits don't end in the same hop (no join point),
2609                // so the reactor will refuse to link them
2610                assert!(
2611                    err_src
2612                        .to_string()
2613                        .contains("one more conflux circuits are invalid")
2614                );
2615            }
2616        });
2617    }
2618
2619    // TODO: this structure could be reused for the other tests,
2620    // to address nickm's comment:
2621    // https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/3005#note_3202362
2622    #[derive(Debug)]
2623    #[allow(unused)]
2624    #[cfg(feature = "conflux")]
2625    struct TestCircuitCtx {
2626        chan_rx: Receiver<AnyChanCell>,
2627        chan_tx: Sender<std::result::Result<AnyChanCell, Error>>,
2628        circ_tx: CircuitRxSender,
2629        unique_id: UniqId,
2630    }
2631
2632    #[derive(Debug)]
2633    #[cfg(feature = "conflux")]
2634    struct TestTunnelCtx {
2635        tunnel: Arc<ClientTunnel>,
2636        circs: Vec<TestCircuitCtx>,
2637        conflux_link_rx: oneshot::Receiver<Result<ConfluxHandshakeResult>>,
2638    }
2639
2640    /// Wait for a LINK cell to arrive on the specified channel and return its payload.
2641    #[cfg(feature = "conflux")]
2642    async fn await_link_payload(rx: &mut Receiver<AnyChanCell>) -> ConfluxLink {
2643        // Wait for the LINK cell...
2644        let (_id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
2645        let rmsg = match chmsg {
2646            AnyChanMsg::Relay(r) => {
2647                AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
2648                    .unwrap()
2649            }
2650            other => panic!("{:?}", other),
2651        };
2652        let (streamid, rmsg) = rmsg.into_streamid_and_msg();
2653
2654        let link = match rmsg {
2655            AnyRelayMsg::ConfluxLink(link) => link,
2656            _ => panic!("unexpected relay message {rmsg:?}"),
2657        };
2658
2659        assert!(streamid.is_none());
2660
2661        link
2662    }
2663
2664    #[cfg(feature = "conflux")]
2665    async fn setup_conflux_tunnel(
2666        rt: &MockRuntime,
2667        same_hops: bool,
2668        params: CircParameters,
2669    ) -> TestTunnelCtx {
2670        let hops1 = hop_details(3, 0);
2671        let hops2 = if same_hops {
2672            hops1.clone()
2673        } else {
2674            hop_details(3, 10)
2675        };
2676
2677        let DummyChan {
2678            channel: chan1,
2679            rx: rx1,
2680            tx: chan_sink1,
2681        } = DummyChan::run(rt, ChannelMode::Client);
2682        let (mut tunnel1, sink1) = newtunnel_ext(
2683            rt,
2684            UniqId::new(1, 3),
2685            chan1,
2686            hops1,
2687            2.into(),
2688            params.clone(),
2689        )
2690        .await;
2691
2692        let DummyChan {
2693            channel: chan2,
2694            rx: rx2,
2695            tx: chan_sink2,
2696        } = DummyChan::run(rt, ChannelMode::Client);
2697
2698        let (tunnel2, sink2) =
2699            newtunnel_ext(rt, UniqId::new(2, 4), chan2, hops2, 2.into(), params).await;
2700
2701        let (answer_tx, answer_rx) = oneshot::channel();
2702        tunnel2
2703            .as_single_circ()
2704            .unwrap()
2705            .command
2706            .unbounded_send(CtrlCmd::ShutdownAndReturnCircuit { answer: answer_tx })
2707            .unwrap();
2708
2709        let circuit = answer_rx.await.unwrap().unwrap();
2710        // The circuit should be shutting down its reactor
2711        rt.advance_until_stalled().await;
2712        assert!(tunnel2.is_closed());
2713
2714        let (conflux_link_tx, conflux_link_rx) = oneshot::channel();
2715        // Tell the first circuit to link with the second and form a multipath tunnel
2716        tunnel1
2717            .as_single_circ()
2718            .unwrap()
2719            .control
2720            .unbounded_send(CtrlMsg::LinkCircuits {
2721                circuits: vec![circuit],
2722                answer: conflux_link_tx,
2723            })
2724            .unwrap();
2725
2726        let circ_ctx1 = TestCircuitCtx {
2727            chan_rx: rx1,
2728            chan_tx: chan_sink1,
2729            circ_tx: sink1,
2730            unique_id: tunnel1.unique_id(),
2731        };
2732
2733        let circ_ctx2 = TestCircuitCtx {
2734            chan_rx: rx2,
2735            chan_tx: chan_sink2,
2736            circ_tx: sink2,
2737            unique_id: tunnel2.unique_id(),
2738        };
2739
2740        // TODO(conflux): nothing currently sets this,
2741        // so we need to manually set it.
2742        //
2743        // Instead of doing this, we should have a ClientCirc
2744        // API that sends CtrlMsg::Link circuits and sets this to true
2745        tunnel1.circ.is_multi_path = true;
2746        TestTunnelCtx {
2747            tunnel: Arc::new(tunnel1),
2748            circs: vec![circ_ctx1, circ_ctx2],
2749            conflux_link_rx,
2750        }
2751    }
2752
2753    #[cfg(feature = "conflux")]
2754    async fn setup_good_conflux_tunnel(
2755        rt: &MockRuntime,
2756        cc_params: CongestionControlParams,
2757    ) -> TestTunnelCtx {
2758        // Our 2 test circuits are identical, so they both have the same guards,
2759        // which technically violates the conflux set rule mentioned in prop354.
2760        // For testing purposes this is fine, but in production we'll need to ensure
2761        // the calling code prevents guard reuse (except in the case where
2762        // one of the guards happens to be Guard + Exit)
2763        let same_hops = true;
2764        let flow_ctrl_params = FlowCtrlParameters::defaults_for_tests();
2765        let params = CircParameters::new(true, cc_params, flow_ctrl_params);
2766        setup_conflux_tunnel(rt, same_hops, params).await
2767    }
2768
2769    #[cfg(feature = "conflux")]
2770    async fn setup_bad_conflux_tunnel(rt: &MockRuntime) -> TestTunnelCtx {
2771        // The two circuits don't share any hops,
2772        // so they won't end in the same hop (no join point),
2773        // causing the reactor to refuse to link them.
2774        let same_hops = false;
2775        let flow_ctrl_params = FlowCtrlParameters::defaults_for_tests();
2776        let params = CircParameters::new(true, build_cc_vegas_params(), flow_ctrl_params);
2777        setup_conflux_tunnel(rt, same_hops, params).await
2778    }
2779
2780    #[traced_test]
2781    #[test]
2782    #[cfg(feature = "conflux")]
2783    fn reject_conflux_linked_before_hs() {
2784        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2785            let DummyChan {
2786                channel,
2787                rx: _,
2788                tx: _sink,
2789            } = DummyChan::run(&rt, ChannelMode::Client);
2790            let (tunnel, mut sink) = newtunnel(&rt, channel).await;
2791
2792            let nonce = V1Nonce::new(&mut testing_rng());
2793            let payload = V1LinkPayload::new(nonce, V1DesiredUx::NO_OPINION);
2794            // Send a LINKED cell
2795            let linked = relaymsg::ConfluxLinked::new(payload).into();
2796            sink.send(rmsg_to_ccmsg(None, linked, false)).await.unwrap();
2797
2798            rt.advance_until_stalled().await;
2799            assert!(tunnel.is_closed());
2800        });
2801    }
2802
2803    #[traced_test]
2804    #[test]
2805    #[cfg(feature = "conflux")]
2806    fn conflux_hs_timeout() {
2807        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2808            let TestTunnelCtx {
2809                tunnel: _tunnel,
2810                circs,
2811                conflux_link_rx,
2812            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
2813
2814            let [mut circ1, _circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
2815
2816            // Wait for the LINK cell
2817            let link = await_link_payload(&mut circ1.chan_rx).await;
2818
2819            // Send a LINK cell on the first leg...
2820            let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
2821            circ1
2822                .circ_tx
2823                .send(rmsg_to_ccmsg(None, linked, false))
2824                .await
2825                .unwrap();
2826
2827            // Do nothing, and wait for the handshake to timeout on the second leg
2828            rt.advance_by(Duration::from_secs(60)).await;
2829
2830            let conflux_hs_res = conflux_link_rx.await.unwrap().unwrap();
2831
2832            // Get the handshake results of each circuit
2833            let [res1, res2]: [StdResult<(), ConfluxHandshakeError>; 2] =
2834                conflux_hs_res.try_into().unwrap();
2835
2836            assert!(res1.is_ok());
2837
2838            let err = res2.unwrap_err();
2839            assert_matches!(err, ConfluxHandshakeError::Timeout);
2840        });
2841    }
2842
2843    #[traced_test]
2844    #[test]
2845    #[cfg(feature = "conflux")]
2846    fn conflux_bad_hs() {
2847        use crate::util::err::ConfluxHandshakeError;
2848
2849        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2850            let nonce = V1Nonce::new(&mut testing_rng());
2851            let bad_link_payload = V1LinkPayload::new(nonce, V1DesiredUx::NO_OPINION);
2852            //let extended2 = relaymsg::Extended2::new(vec![]).into();
2853            let bad_hs_responses = [
2854                (
2855                    rmsg_to_ccmsg(
2856                        None,
2857                        relaymsg::ConfluxLinked::new(bad_link_payload.clone()).into(),
2858                        false,
2859                    ),
2860                    "Received CONFLUX_LINKED cell with mismatched nonce",
2861                ),
2862                (
2863                    rmsg_to_ccmsg(
2864                        None,
2865                        relaymsg::ConfluxLink::new(bad_link_payload).into(),
2866                        false,
2867                    ),
2868                    "Unexpected CONFLUX_LINK cell from hop #3 on client circuit",
2869                ),
2870                (
2871                    rmsg_to_ccmsg(None, relaymsg::ConfluxSwitch::new(0).into(), false),
2872                    "Received CONFLUX_SWITCH on unlinked circuit?!",
2873                ),
2874                // TODO: this currently causes the reactor to shut down immediately,
2875                // without sending a response on the handshake channel
2876                /*
2877                (
2878                    rmsg_to_ccmsg(None, extended2, false),
2879                    "Received CONFLUX_LINKED cell with mismatched nonce",
2880                ),
2881                */
2882            ];
2883
2884            for (bad_cell, expected_err) in bad_hs_responses {
2885                let TestTunnelCtx {
2886                    tunnel,
2887                    circs,
2888                    conflux_link_rx,
2889                } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
2890
2891                let [mut _circ1, mut circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
2892
2893                // Respond with a bogus cell on one of the legs
2894                circ2.circ_tx.send(bad_cell).await.unwrap();
2895
2896                let conflux_hs_res = conflux_link_rx.await.unwrap().unwrap();
2897                // Get the handshake results (the handshake results are reported early,
2898                // without waiting for the second circuit leg's handshake to timeout,
2899                // because this is a protocol violation causing the entire tunnel to shut down)
2900                let [res2]: [StdResult<(), ConfluxHandshakeError>; 1] =
2901                    conflux_hs_res.try_into().unwrap();
2902
2903                match res2.unwrap_err() {
2904                    ConfluxHandshakeError::Link(Error::CircProto(e)) => {
2905                        assert_eq!(e, expected_err);
2906                    }
2907                    e => panic!("unexpected error: {e:?}"),
2908                }
2909
2910                assert!(tunnel.is_closed());
2911            }
2912        });
2913    }
2914
2915    #[traced_test]
2916    #[test]
2917    #[cfg(feature = "conflux")]
2918    fn unexpected_conflux_cell() {
2919        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2920            let nonce = V1Nonce::new(&mut testing_rng());
2921            let link_payload = V1LinkPayload::new(nonce, V1DesiredUx::NO_OPINION);
2922            let bad_cells = [
2923                rmsg_to_ccmsg(
2924                    None,
2925                    relaymsg::ConfluxLinked::new(link_payload.clone()).into(),
2926                    false,
2927                ),
2928                rmsg_to_ccmsg(
2929                    None,
2930                    relaymsg::ConfluxLink::new(link_payload.clone()).into(),
2931                    false,
2932                ),
2933                rmsg_to_ccmsg(None, relaymsg::ConfluxSwitch::new(0).into(), false),
2934            ];
2935
2936            for bad_cell in bad_cells {
2937                let DummyChan {
2938                    channel,
2939                    rx: _rx,
2940                    tx: _sink,
2941                } = DummyChan::run(&rt, ChannelMode::Client);
2942                let (tunnel, mut sink) = newtunnel(&rt, channel).await;
2943
2944                sink.send(bad_cell).await.unwrap();
2945                rt.advance_until_stalled().await;
2946
2947                // Note: unfortunately we can't assert the circuit is
2948                // closing for the reason, because the reactor just logs
2949                // the error and then exits.
2950                assert!(tunnel.is_closed());
2951            }
2952        });
2953    }
2954
2955    #[traced_test]
2956    #[test]
2957    #[cfg(feature = "conflux")]
2958    fn conflux_bad_linked() {
2959        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
2960            let TestTunnelCtx {
2961                tunnel,
2962                circs,
2963                conflux_link_rx: _,
2964            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
2965
2966            let [mut circ1, mut circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
2967
2968            let link = await_link_payload(&mut circ1.chan_rx).await;
2969
2970            // Send a LINK cell on the first leg...
2971            let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
2972            circ1
2973                .circ_tx
2974                .send(rmsg_to_ccmsg(None, linked, false))
2975                .await
2976                .unwrap();
2977
2978            // ...and two LINKED cells on the second
2979            let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
2980            circ2
2981                .circ_tx
2982                .send(rmsg_to_ccmsg(None, linked, false))
2983                .await
2984                .unwrap();
2985            let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
2986            circ2
2987                .circ_tx
2988                .send(rmsg_to_ccmsg(None, linked, false))
2989                .await
2990                .unwrap();
2991
2992            rt.advance_until_stalled().await;
2993
2994            // Receiving a LINKED cell on an already linked leg causes
2995            // the tunnel to be torn down
2996            assert!(tunnel.is_closed());
2997        });
2998    }
2999
3000    #[traced_test]
3001    #[test]
3002    #[cfg(feature = "conflux")]
3003    fn conflux_bad_switch() {
3004        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
3005            let cc_vegas_params = build_cc_vegas_params();
3006            let cwnd_init = cc_vegas_params.cwnd_params().cwnd_init();
3007            let bad_switch = [
3008                // SWITCH cells with seqno = 0 are not allowed
3009                relaymsg::ConfluxSwitch::new(0),
3010                // SWITCH cells with seqno > cc_init_cwnd are not allowed
3011                // on tunnels that have not received any data
3012                relaymsg::ConfluxSwitch::new(cwnd_init + 1),
3013            ];
3014
3015            for bad_cell in bad_switch {
3016                let TestTunnelCtx {
3017                    tunnel,
3018                    circs,
3019                    conflux_link_rx,
3020                } = setup_good_conflux_tunnel(&rt, cc_vegas_params.clone()).await;
3021
3022                let [mut circ1, mut circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
3023
3024                let link = await_link_payload(&mut circ1.chan_rx).await;
3025
3026                // Send a LINKED cell on both legs
3027                for circ in [&mut circ1, &mut circ2] {
3028                    let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
3029                    circ.circ_tx
3030                        .send(rmsg_to_ccmsg(None, linked, false))
3031                        .await
3032                        .unwrap();
3033                }
3034
3035                let conflux_hs_res = conflux_link_rx.await.unwrap().unwrap();
3036                assert!(conflux_hs_res.iter().all(|res| res.is_ok()));
3037
3038                // Now send a bad SWITCH cell on the first leg.
3039                // This will cause the tunnel reactor to shut down.
3040                let msg = rmsg_to_ccmsg(None, bad_cell.clone().into(), false);
3041                circ1.circ_tx.send(msg).await.unwrap();
3042
3043                // The tunnel should be shutting down
3044                rt.advance_until_stalled().await;
3045                assert!(tunnel.is_closed());
3046            }
3047        });
3048    }
3049
3050    #[traced_test]
3051    #[test]
3052    #[cfg(feature = "conflux")]
3053    fn conflux_consecutive_switch() {
3054        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
3055            let TestTunnelCtx {
3056                tunnel,
3057                circs,
3058                conflux_link_rx,
3059            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
3060
3061            let [mut circ1, mut circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
3062
3063            let link = await_link_payload(&mut circ1.chan_rx).await;
3064
3065            // Send a LINKED cell on both legs
3066            for circ in [&mut circ1, &mut circ2] {
3067                let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
3068                circ.circ_tx
3069                    .send(rmsg_to_ccmsg(None, linked, false))
3070                    .await
3071                    .unwrap();
3072            }
3073
3074            let conflux_hs_res = conflux_link_rx.await.unwrap().unwrap();
3075            assert!(conflux_hs_res.iter().all(|res| res.is_ok()));
3076
3077            // Send a valid SWITCH cell on the first leg.
3078            let switch1 = relaymsg::ConfluxSwitch::new(10);
3079            let msg = rmsg_to_ccmsg(None, switch1.into(), false);
3080            circ1.circ_tx.send(msg).await.unwrap();
3081
3082            // The tunnel should not be shutting down
3083            rt.advance_until_stalled().await;
3084            assert!(!tunnel.is_closed());
3085
3086            // Send another valid SWITCH cell on the same leg.
3087            let switch2 = relaymsg::ConfluxSwitch::new(12);
3088            let msg = rmsg_to_ccmsg(None, switch2.into(), false);
3089            circ1.circ_tx.send(msg).await.unwrap();
3090
3091            // The tunnel should now be shutting down
3092            // (consecutive switches are not allowed)
3093            rt.advance_until_stalled().await;
3094            assert!(tunnel.is_closed());
3095        });
3096    }
3097
3098    // This test ensures CtrlMsg::ShutdownAndReturnCircuit returns an
3099    // error when called on a multi-path tunnel
3100    #[traced_test]
3101    #[test]
3102    #[cfg(feature = "conflux")]
3103    fn shutdown_and_return_circ_multipath() {
3104        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
3105            let TestTunnelCtx {
3106                tunnel,
3107                circs,
3108                conflux_link_rx: _,
3109            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
3110
3111            rt.progress_until_stalled().await;
3112
3113            let (answer_tx, answer_rx) = oneshot::channel();
3114            tunnel
3115                .circ
3116                .command
3117                .unbounded_send(CtrlCmd::ShutdownAndReturnCircuit { answer: answer_tx })
3118                .unwrap();
3119
3120            // map explicitly returns () for clarity
3121            #[allow(clippy::unused_unit, clippy::semicolon_if_nothing_returned)]
3122            let err = answer_rx
3123                .await
3124                .unwrap()
3125                .map(|_| {
3126                    // Map to () so we can call unwrap
3127                    // (Circuit doesn't impl debug)
3128                    ()
3129                })
3130                .unwrap_err();
3131
3132            const MSG: &str = "not a single leg conflux set (got at least 2 elements when exactly one was expected)";
3133            assert!(err.to_string().contains(MSG), "{err}");
3134
3135            // The tunnel reactor should be shutting down,
3136            // regardless of the error
3137            rt.progress_until_stalled().await;
3138            assert!(tunnel.is_closed());
3139
3140            // Keep circs alive, to prevent the reactor
3141            // from shutting down prematurely
3142            drop(circs);
3143        });
3144    }
3145
3146    /// Run a conflux test endpoint.
3147    #[cfg(feature = "conflux")]
3148    #[derive(Debug)]
3149    enum ConfluxTestEndpoint<I: Iterator<Item = Option<Duration>>> {
3150        /// Pretend to be an exit relay.
3151        Relay(ConfluxExitState<I>),
3152        /// Client task.
3153        Client {
3154            /// Channel for receiving the outcome of the conflux handshakes.
3155            conflux_link_rx: oneshot::Receiver<Result<ConfluxHandshakeResult>>,
3156            /// The tunnel reactor handle
3157            tunnel: Arc<ClientTunnel>,
3158            /// Data to send on a stream.
3159            send_data: Vec<u8>,
3160            /// Data we expect to receive on a stream.
3161            recv_data: Vec<u8>,
3162        },
3163    }
3164
3165    /// Structure for returning the sinks, channels, etc. that must stay
3166    /// alive until the test is complete.
3167    #[allow(unused, clippy::large_enum_variant)]
3168    #[derive(Debug)]
3169    #[cfg(feature = "conflux")]
3170    enum ConfluxEndpointResult {
3171        Circuit {
3172            tunnel: Arc<ClientTunnel>,
3173            stream: DataStream,
3174        },
3175        Relay {
3176            circ: TestCircuitCtx,
3177        },
3178    }
3179
3180    /// Stream data, shared by all the mock exit endpoints.
3181    #[derive(Debug)]
3182    #[cfg(feature = "conflux")]
3183    struct ConfluxStreamState {
3184        /// The data received so far on this stream (at the exit).
3185        data_recvd: Vec<u8>,
3186        /// The total amount of data we expect to receive on this stream.
3187        expected_data_len: usize,
3188        /// Whether we have seen a BEGIN cell yet.
3189        begin_recvd: bool,
3190        /// Whether we have seen an END cell yet.
3191        end_recvd: bool,
3192        /// Whether we have sent an END cell yet.
3193        end_sent: bool,
3194    }
3195
3196    #[cfg(feature = "conflux")]
3197    impl ConfluxStreamState {
3198        fn new(expected_data_len: usize) -> Self {
3199            Self {
3200                data_recvd: vec![],
3201                expected_data_len,
3202                begin_recvd: false,
3203                end_recvd: false,
3204                end_sent: false,
3205            }
3206        }
3207    }
3208
3209    /// An object describing a SWITCH cell that we expect to receive
3210    /// in the mock exit
3211    #[derive(Debug)]
3212    #[cfg(feature = "conflux")]
3213    struct ExpectedSwitch {
3214        /// The number of cells we've seen on this leg so far,
3215        /// up to and including the SWITCH.
3216        cells_so_far: usize,
3217        /// The expected seqno in SWITCH cell,
3218        seqno: u32,
3219    }
3220
3221    /// Object dispatching cells for delivery on the appropriate
3222    /// leg in a multipath tunnel.
3223    ///
3224    /// Used to send out-of-order cells from the mock exit
3225    /// to the client under test.
3226    #[cfg(feature = "conflux")]
3227    struct CellDispatcher {
3228        /// Channels on which to send the [`CellToSend`] commands on.
3229        leg_tx: HashMap<UniqId, mpsc::Sender<CellToSend>>,
3230        /// The list of cells to send,
3231        cells_to_send: Vec<(UniqId, AnyRelayMsg)>,
3232    }
3233
3234    #[cfg(feature = "conflux")]
3235    impl CellDispatcher {
3236        async fn run(mut self) {
3237            while !self.cells_to_send.is_empty() {
3238                let (circ_id, cell) = self.cells_to_send.remove(0);
3239                let cell_tx = self.leg_tx.get_mut(&circ_id).unwrap();
3240                let (done_tx, done_rx) = oneshot::channel();
3241                cell_tx.send(CellToSend { done_tx, cell }).await.unwrap();
3242                // Wait for the cell to be sent before sending the next one.
3243                let () = done_rx.await.unwrap();
3244            }
3245        }
3246    }
3247
3248    /// A cell for the mock exit to send on one of its legs.
3249    #[cfg(feature = "conflux")]
3250    #[derive(Debug)]
3251    struct CellToSend {
3252        /// Channel for notifying the control task that the cell was sent.
3253        done_tx: oneshot::Sender<()>,
3254        /// The cell to send.
3255        cell: AnyRelayMsg,
3256    }
3257
3258    /// The state of a mock exit.
3259    #[derive(Debug)]
3260    #[cfg(feature = "conflux")]
3261    struct ConfluxExitState<I: Iterator<Item = Option<Duration>>> {
3262        /// The runtime, shared by the test client and mock exit tasks.
3263        ///
3264        /// The mutex prevents the client and mock exit tasks from calling
3265        /// functions like [`MockRuntime::advance_until_stalled`]
3266        /// or [`MockRuntime::progress_until_stalled]` concurrently,
3267        /// as this is not supported by the mock runtime.
3268        runtime: Arc<AsyncMutex<MockRuntime>>,
3269        /// The client view of the tunnel.
3270        tunnel: Arc<ClientTunnel>,
3271        /// The circuit test context.
3272        circ: TestCircuitCtx,
3273        /// The RTT delay to introduce just before each SENDME.
3274        ///
3275        /// Used to trigger the client to send a SWITCH.
3276        rtt_delays: I,
3277        /// State of the (only) expected stream on this tunnel,
3278        /// shared by all the mock exit endpoints.
3279        stream_state: Arc<Mutex<ConfluxStreamState>>,
3280        /// The number of cells after which to expect a SWITCH
3281        /// cell from the client.
3282        expect_switch: Vec<ExpectedSwitch>,
3283        /// Channel for receiving notifications from the other leg.
3284        event_rx: mpsc::Receiver<MockExitEvent>,
3285        /// Channel for sending notifications to the other leg.
3286        event_tx: mpsc::Sender<MockExitEvent>,
3287        /// Whether this circuit leg should act as the primary (sending) leg.
3288        is_sending_leg: bool,
3289        /// A channel for receiving cells to send on this stream.
3290        cells_rx: mpsc::Receiver<CellToSend>,
3291    }
3292
3293    #[cfg(feature = "conflux")]
3294    async fn good_exit_handshake(
3295        runtime: &Arc<AsyncMutex<MockRuntime>>,
3296        init_rtt_delay: Option<Duration>,
3297        rx: &mut Receiver<ChanCell<AnyChanMsg>>,
3298        sink: &mut CircuitRxSender,
3299    ) {
3300        // Wait for the LINK cell
3301        let link = await_link_payload(rx).await;
3302
3303        // Introduce an artificial delay, to make one circ have a better initial RTT
3304        // than the other
3305        if let Some(init_rtt_delay) = init_rtt_delay {
3306            runtime.lock().await.advance_by(init_rtt_delay).await;
3307        }
3308
3309        // Reply with a LINKED cell...
3310        let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
3311        sink.send(rmsg_to_ccmsg(None, linked, false)).await.unwrap();
3312
3313        // Wait for the client to respond with LINKED_ACK...
3314        let (_id, chmsg) = rx.next().await.unwrap().into_circid_and_msg();
3315        let rmsg = match chmsg {
3316            AnyChanMsg::Relay(r) => {
3317                AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
3318                    .unwrap()
3319            }
3320            other => panic!("{other:?}"),
3321        };
3322        let (_streamid, rmsg) = rmsg.into_streamid_and_msg();
3323
3324        assert_matches!(rmsg, AnyRelayMsg::ConfluxLinkedAck(_));
3325    }
3326
3327    /// An event sent by one mock conflux leg to another.
3328    #[derive(Copy, Clone, Debug)]
3329    enum MockExitEvent {
3330        /// Inform the other leg we are done.
3331        Done,
3332        /// Inform the other leg a stream was opened.
3333        BeginRecvd(StreamId),
3334    }
3335
3336    #[cfg(feature = "conflux")]
3337    async fn run_mock_conflux_exit<I: Iterator<Item = Option<Duration>>>(
3338        state: ConfluxExitState<I>,
3339    ) -> ConfluxEndpointResult {
3340        let ConfluxExitState {
3341            runtime,
3342            tunnel,
3343            mut circ,
3344            rtt_delays,
3345            stream_state,
3346            mut expect_switch,
3347            mut event_tx,
3348            mut event_rx,
3349            is_sending_leg,
3350            mut cells_rx,
3351        } = state;
3352
3353        let mut rtt_delays = rtt_delays.into_iter();
3354
3355        // Expect the client to open a stream, and de-multiplex the received stream data
3356        let stream_len = stream_state.lock().unwrap().expected_data_len;
3357        let mut data_cells_received = 0_usize;
3358        let mut cell_count = 0_usize;
3359        let mut tags = vec![];
3360        let mut streamid = None;
3361        let mut done_writing = false;
3362
3363        loop {
3364            let should_exit = {
3365                let stream_state = stream_state.lock().unwrap();
3366                let done_reading = stream_state.data_recvd.len() >= stream_len;
3367
3368                (stream_state.begin_recvd || stream_state.end_recvd) && done_reading && done_writing
3369            };
3370
3371            if should_exit {
3372                break;
3373            }
3374
3375            use futures::select;
3376
3377            // Only start reading from the dispatcher channel after the stream is open
3378            // and we're ready to start sending cells.
3379            let mut next_cell = if streamid.is_some() && !done_writing {
3380                Box::pin(cells_rx.next().fuse())
3381                    as Pin<Box<dyn FusedFuture<Output = Option<CellToSend>> + Send>>
3382            } else {
3383                Box::pin(std::future::pending().fuse())
3384            };
3385
3386            // Wait for the BEGIN cell to arrive, or for the transfer to complete
3387            // (we need to bail if the other leg already completed);
3388            let res = select! {
3389                res = circ.chan_rx.next() => {
3390                    res.unwrap()
3391                },
3392                res = event_rx.next() => {
3393                    let Some(event) = res else {
3394                        break;
3395                    };
3396
3397                    match event {
3398                        MockExitEvent::Done => {
3399                            break;
3400                        },
3401                        MockExitEvent::BeginRecvd(id) => {
3402                            // The stream is now open (the other leg received the BEGIN),
3403                            // so we're reading to start reading cells from the cell dispatcher.
3404                            streamid = Some(id);
3405                            continue;
3406                        },
3407                    }
3408                }
3409                res = next_cell => {
3410                    if let Some(cell_to_send) = res {
3411                        let CellToSend { cell, done_tx } = cell_to_send;
3412
3413                        // SWITCH cells don't have a stream ID
3414                        let streamid = if matches!(cell, AnyRelayMsg::ConfluxSwitch(_)) {
3415                            None
3416                        } else {
3417                            streamid
3418                        };
3419
3420                        circ.circ_tx
3421                            .send(rmsg_to_ccmsg(streamid, cell, false))
3422                            .await
3423                            .unwrap();
3424
3425                        runtime.lock().await.advance_until_stalled().await;
3426                        done_tx.send(()).unwrap();
3427                    } else {
3428                        done_writing = true;
3429                    }
3430
3431                    continue;
3432                }
3433            };
3434
3435            let (_id, chmsg) = res.into_circid_and_msg();
3436            cell_count += 1;
3437            let rmsg = match chmsg {
3438                AnyChanMsg::Relay(r) => {
3439                    AnyRelayMsgOuter::decode_singleton(RelayCellFormat::V0, r.into_relay_body())
3440                        .unwrap()
3441                }
3442                other => panic!("{:?}", other),
3443            };
3444            let (new_streamid, rmsg) = rmsg.into_streamid_and_msg();
3445            if streamid.is_none() {
3446                streamid = new_streamid;
3447            }
3448
3449            let begin_recvd = stream_state.lock().unwrap().begin_recvd;
3450            let end_recvd = stream_state.lock().unwrap().end_recvd;
3451            match rmsg {
3452                AnyRelayMsg::Begin(_) if begin_recvd => {
3453                    panic!("client tried to open two streams?!");
3454                }
3455                AnyRelayMsg::Begin(_) if !begin_recvd => {
3456                    stream_state.lock().unwrap().begin_recvd = true;
3457                    // Reply with a connected cell...
3458                    let connected = relaymsg::Connected::new_empty().into();
3459                    circ.circ_tx
3460                        .send(rmsg_to_ccmsg(streamid, connected, false))
3461                        .await
3462                        .unwrap();
3463                    // Tell the other leg we received a BEGIN cell
3464                    event_tx
3465                        .send(MockExitEvent::BeginRecvd(streamid.unwrap()))
3466                        .await
3467                        .unwrap();
3468                }
3469                AnyRelayMsg::End(_) if !end_recvd => {
3470                    stream_state.lock().unwrap().end_recvd = true;
3471                    break;
3472                }
3473                AnyRelayMsg::End(_) if end_recvd => {
3474                    panic!("received two END cells for the same stream?!");
3475                }
3476                AnyRelayMsg::ConfluxSwitch(cell) => {
3477                    // Ensure we got the SWITCH after the expected number of cells
3478                    let expected = expect_switch.remove(0);
3479
3480                    assert_eq!(expected.cells_so_far, cell_count);
3481                    assert_eq!(expected.seqno, cell.seqno());
3482
3483                    // To keep the tests simple, we don't handle out of order cells,
3484                    // and simply sort the received data at the end.
3485                    // This ensures all the data was actually received,
3486                    // but it doesn't actually test that the SWITCH cells
3487                    // contain the appropriate seqnos.
3488                    continue;
3489                }
3490                AnyRelayMsg::Data(dat) => {
3491                    data_cells_received += 1;
3492                    stream_state
3493                        .lock()
3494                        .unwrap()
3495                        .data_recvd
3496                        .extend_from_slice(dat.as_ref());
3497
3498                    let is_next_cell_sendme = data_cells_received.is_multiple_of(31);
3499                    if is_next_cell_sendme {
3500                        if tags.is_empty() {
3501                            // Important: we need to make sure all the SENDMEs
3502                            // we sent so far have been processed by the reactor
3503                            // (otherwise the next QuerySendWindow call
3504                            // might return an outdated list of tags!)
3505                            runtime.lock().await.advance_until_stalled().await;
3506                            let (tx, rx) = oneshot::channel();
3507                            tunnel
3508                                .circ
3509                                .command
3510                                .unbounded_send(CtrlCmd::QuerySendWindow {
3511                                    hop: 2.into(),
3512                                    leg: circ.unique_id,
3513                                    done: tx,
3514                                })
3515                                .unwrap();
3516
3517                            // Get a fresh batch of tags.
3518                            let (_window, new_tags) = rx.await.unwrap().unwrap();
3519                            tags = new_tags;
3520                        }
3521
3522                        let tag = tags.remove(0);
3523
3524                        // Introduce an artificial delay, to make one circ have worse RTT
3525                        // than the other, and thus trigger a SWITCH
3526                        if let Some(rtt_delay) = rtt_delays.next().flatten() {
3527                            runtime.lock().await.advance_by(rtt_delay).await;
3528                        }
3529                        // Make and send a circuit-level SENDME
3530                        let sendme = relaymsg::Sendme::from(tag).into();
3531
3532                        circ.circ_tx
3533                            .send(rmsg_to_ccmsg(None, sendme, false))
3534                            .await
3535                            .unwrap();
3536                    }
3537                }
3538                _ => panic!("unexpected message {rmsg:?} on leg {}", circ.unique_id),
3539            }
3540        }
3541
3542        let end_recvd = stream_state.lock().unwrap().end_recvd;
3543
3544        // Close the stream if the other endpoint hasn't already done so
3545        if is_sending_leg && !end_recvd {
3546            let end = relaymsg::End::new_with_reason(relaymsg::EndReason::DONE).into();
3547            circ.circ_tx
3548                .send(rmsg_to_ccmsg(streamid, end, false))
3549                .await
3550                .unwrap();
3551            stream_state.lock().unwrap().end_sent = true;
3552        }
3553
3554        // This is allowed to fail, because the other leg might have exited first.
3555        let _ = event_tx.send(MockExitEvent::Done).await;
3556
3557        // Ensure we received all the switch cells we were expecting
3558        assert!(
3559            expect_switch.is_empty(),
3560            "expect_switch = {expect_switch:?}"
3561        );
3562
3563        ConfluxEndpointResult::Relay { circ }
3564    }
3565
3566    #[cfg(feature = "conflux")]
3567    async fn run_conflux_client(
3568        tunnel: Arc<ClientTunnel>,
3569        conflux_link_rx: oneshot::Receiver<Result<ConfluxHandshakeResult>>,
3570        send_data: Vec<u8>,
3571        recv_data: Vec<u8>,
3572    ) -> ConfluxEndpointResult {
3573        let res = conflux_link_rx.await;
3574
3575        let res = res.unwrap().unwrap();
3576        assert_eq!(res.len(), 2);
3577
3578        // All circuit legs have completed the conflux handshake,
3579        // so we now have a multipath tunnel
3580
3581        // Now we're ready to open a stream
3582        let mut stream = tunnel
3583            .begin_stream("www.example.com", 443, None)
3584            .await
3585            .unwrap();
3586
3587        stream.write_all(&send_data).await.unwrap();
3588        stream.flush().await.unwrap();
3589
3590        let mut recv: Vec<u8> = Vec::new();
3591        let recv_len = stream.read_to_end(&mut recv).await.unwrap();
3592        assert_eq!(recv_len, recv_data.len());
3593        assert_eq!(recv_data, recv);
3594
3595        ConfluxEndpointResult::Circuit { tunnel, stream }
3596    }
3597
3598    #[cfg(feature = "conflux")]
3599    async fn run_conflux_endpoint<I: Iterator<Item = Option<Duration>>>(
3600        endpoint: ConfluxTestEndpoint<I>,
3601    ) -> ConfluxEndpointResult {
3602        match endpoint {
3603            ConfluxTestEndpoint::Relay(state) => run_mock_conflux_exit(state).await,
3604            ConfluxTestEndpoint::Client {
3605                tunnel,
3606                conflux_link_rx,
3607                send_data,
3608                recv_data,
3609            } => run_conflux_client(tunnel, conflux_link_rx, send_data, recv_data).await,
3610        }
3611    }
3612
3613    // In this test, a `ConfluxTestEndpoint::Client` task creates a multipath tunnel
3614    // with 2 legs, opens a stream and sends 300 DATA cells on it.
3615    //
3616    // The test spawns two `ConfluxTestEndpoint::Relay` tasks (one for each leg),
3617    // which mock the behavior of an exit. The two relay tasks introduce
3618    // artificial delays before each SENDME sent to the client,
3619    // in order to trigger it to switch its sending leg predictably.
3620    //
3621    // The mock exit does not send any data on the stream.
3622    //
3623    // This test checks that the client sends SWITCH cells at the right time,
3624    // and that all the data it sent over the stream arrived at the exit.
3625    //
3626    // Note, however, that it doesn't check that the client sends the data in
3627    // the right order. For simplicity, the test concatenates the data received
3628    // on both legs, sorts it, and then compares it against the of the data sent
3629    // by the client (TODO: improve this)
3630    #[traced_test]
3631    #[test]
3632    #[cfg(feature = "conflux")]
3633    fn multipath_client_to_exit() {
3634        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
3635            /// The number of data cells to send.
3636            const NUM_CELLS: usize = 300;
3637            /// 498 bytes per DATA cell.
3638            const CELL_SIZE: usize = 498;
3639
3640            let TestTunnelCtx {
3641                tunnel,
3642                circs,
3643                conflux_link_rx,
3644            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
3645            let [circ1, circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
3646
3647            // The stream data we're going to send over the conflux tunnel
3648            let mut send_data = (0..255_u8)
3649                .cycle()
3650                .take(NUM_CELLS * CELL_SIZE)
3651                .collect::<Vec<_>>();
3652            let stream_state = Arc::new(Mutex::new(ConfluxStreamState::new(send_data.len())));
3653
3654            let mut tasks = vec![];
3655
3656            // Channels used by the mock relays to notify each other
3657            // of various events.
3658            let (tx1, rx1) = mpsc::channel(1);
3659            let (tx2, rx2) = mpsc::channel(1);
3660
3661            // The 9 RTT delays to insert before each of the 9 SENDMEs
3662            // the exit will end up sending.
3663            //
3664            // Note: the first delay is the init_rtt delay (measured during the conflux HS).
3665            let circ1_rtt_delays = [
3666                // Initially, circ1 has better RTT, so we will start on this leg.
3667                Some(Duration::from_millis(100)),
3668                // But then its RTT takes a turn for the worse,
3669                // triggering a switch after the first SENDME is processed
3670                // (this happens after sending 123 DATA cells).
3671                Some(Duration::from_millis(500)),
3672                Some(Duration::from_millis(700)),
3673                Some(Duration::from_millis(900)),
3674                Some(Duration::from_millis(1100)),
3675                Some(Duration::from_millis(1300)),
3676                Some(Duration::from_millis(1500)),
3677                Some(Duration::from_millis(1700)),
3678                Some(Duration::from_millis(1900)),
3679                Some(Duration::from_millis(2100)),
3680            ]
3681            .into_iter();
3682
3683            let circ2_rtt_delays = [
3684                Some(Duration::from_millis(200)),
3685                Some(Duration::from_millis(400)),
3686                Some(Duration::from_millis(600)),
3687                Some(Duration::from_millis(800)),
3688                Some(Duration::from_millis(1000)),
3689                Some(Duration::from_millis(1200)),
3690                Some(Duration::from_millis(1400)),
3691                Some(Duration::from_millis(1600)),
3692                Some(Duration::from_millis(1800)),
3693                Some(Duration::from_millis(2000)),
3694            ]
3695            .into_iter();
3696
3697            let expected_switches1 = vec![ExpectedSwitch {
3698                // We start on this leg, and receive a BEGIN cell,
3699                // followed by (4 * 31 - 1) = 123 DATA cells.
3700                // Then it becomes blocked on CC, then finally the reactor
3701                // realizes it has some SENDMEs to process, and
3702                // then as a result of the new RTT measurement, we switch to circ1,
3703                // and then finally we switch back here, and get another SWITCH
3704                // as the 126th cell.
3705                cells_so_far: 126,
3706                // Leg 2 switches back to this leg after the 249th cell
3707                // (just before sending the 250th one):
3708                // seqno = 125 carried over from leg 1 (see the seqno of the
3709                // SWITCH expected on leg 2 below), plus 1 SWITCH, plus
3710                // 4 * 31 = 124 DATA cells after which the RTT of the first leg
3711                // is deemed favorable again.
3712                //
3713                // 249 - 125 (last_seq_sent of leg 1) = 124
3714                seqno: 124,
3715            }];
3716
3717            let expected_switches2 = vec![ExpectedSwitch {
3718                // The SWITCH is the first cell we received after the conflux HS
3719                // on this leg.
3720                cells_so_far: 1,
3721                // See explanation on the ExpectedSwitch from circ1 above.
3722                seqno: 125,
3723            }];
3724
3725            let relay_runtime = Arc::new(AsyncMutex::new(rt.clone()));
3726
3727            // Drop the senders and close the channels,
3728            // we have nothing to send in this test.
3729            let (_, cells_rx1) = mpsc::channel(1);
3730            let (_, cells_rx2) = mpsc::channel(1);
3731
3732            let relay1 = ConfluxExitState {
3733                runtime: Arc::clone(&relay_runtime),
3734                tunnel: Arc::clone(&tunnel),
3735                circ: circ1,
3736                rtt_delays: circ1_rtt_delays,
3737                stream_state: Arc::clone(&stream_state),
3738                expect_switch: expected_switches1,
3739                event_tx: tx1,
3740                event_rx: rx2,
3741                is_sending_leg: true,
3742                cells_rx: cells_rx1,
3743            };
3744
3745            let relay2 = ConfluxExitState {
3746                runtime: Arc::clone(&relay_runtime),
3747                tunnel: Arc::clone(&tunnel),
3748                circ: circ2,
3749                rtt_delays: circ2_rtt_delays,
3750                stream_state: Arc::clone(&stream_state),
3751                expect_switch: expected_switches2,
3752                event_tx: tx2,
3753                event_rx: rx1,
3754                is_sending_leg: false,
3755                cells_rx: cells_rx2,
3756            };
3757
3758            for mut mock_relay in [relay1, relay2] {
3759                let leg = mock_relay.circ.unique_id;
3760
3761                // Do the conflux handshake
3762                //
3763                // We do this outside of run_conflux_endpoint,
3764                // toa void running both handshakes at concurrently
3765                // (this gives more predictable RTT delays:
3766                // if both handshake tasks run at once, they race
3767                // to advance the mock runtime's clock)
3768                good_exit_handshake(
3769                    &relay_runtime,
3770                    mock_relay.rtt_delays.next().flatten(),
3771                    &mut mock_relay.circ.chan_rx,
3772                    &mut mock_relay.circ.circ_tx,
3773                )
3774                .await;
3775
3776                let relay = ConfluxTestEndpoint::Relay(mock_relay);
3777
3778                tasks.push(rt.spawn_join(format!("relay task {leg}"), run_conflux_endpoint(relay)));
3779            }
3780
3781            tasks.push(rt.spawn_join(
3782                "client task".to_string(),
3783                run_conflux_endpoint(ConfluxTestEndpoint::Client {
3784                    tunnel,
3785                    conflux_link_rx,
3786                    send_data: send_data.clone(),
3787                    recv_data: vec![],
3788                }),
3789            ));
3790            let _sinks = futures::future::join_all(tasks).await;
3791            let mut stream_state = stream_state.lock().unwrap();
3792            assert!(stream_state.begin_recvd);
3793
3794            stream_state.data_recvd.sort();
3795            send_data.sort();
3796            assert_eq!(stream_state.data_recvd, send_data);
3797        });
3798    }
3799
3800    // In this test, a `ConfluxTestEndpoint::Client` task creates a multipath tunnel
3801    // with 2 legs, opens a stream and reads from the stream until the stream is closed.
3802    //
3803    // The test spawns two `ConfluxTestEndpoint::Relay` tasks (one for each leg),
3804    // which mock the behavior of an exit. The two tasks send DATA and SWITCH
3805    // cells on the two circuit "legs" such that some cells arrive out of order.
3806    // This forces the client to buffer some cells, and then reorder them when
3807    // the missing cells finally arrive.
3808    //
3809    // The client does not send any data on the stream.
3810    #[cfg(feature = "conflux")]
3811    async fn run_multipath_exit_to_client_test(
3812        rt: MockRuntime,
3813        tunnel: TestTunnelCtx,
3814        cells_to_send: Vec<(UniqId, AnyRelayMsg)>,
3815        send_data: Vec<u8>,
3816        recv_data: Vec<u8>,
3817    ) -> Arc<Mutex<ConfluxStreamState>> {
3818        let TestTunnelCtx {
3819            tunnel,
3820            circs,
3821            conflux_link_rx,
3822        } = tunnel;
3823        let [circ1, circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
3824
3825        let stream_state = Arc::new(Mutex::new(ConfluxStreamState::new(send_data.len())));
3826
3827        let mut tasks = vec![];
3828        let relay_runtime = Arc::new(AsyncMutex::new(rt.clone()));
3829        let (cells_tx1, cells_rx1) = mpsc::channel(1);
3830        let (cells_tx2, cells_rx2) = mpsc::channel(1);
3831
3832        let dispatcher = CellDispatcher {
3833            leg_tx: [(circ1.unique_id, cells_tx1), (circ2.unique_id, cells_tx2)]
3834                .into_iter()
3835                .collect(),
3836            cells_to_send,
3837        };
3838
3839        // Channels used by the mock relays to notify each other
3840        // of various events.
3841        let (tx1, rx1) = mpsc::channel(1);
3842        let (tx2, rx2) = mpsc::channel(1);
3843
3844        let relay1 = ConfluxExitState {
3845            runtime: Arc::clone(&relay_runtime),
3846            tunnel: Arc::clone(&tunnel),
3847            circ: circ1,
3848            rtt_delays: [].into_iter(),
3849            stream_state: Arc::clone(&stream_state),
3850            // Expect no SWITCH cells from the client
3851            expect_switch: vec![],
3852            event_tx: tx1,
3853            event_rx: rx2,
3854            is_sending_leg: false,
3855            cells_rx: cells_rx1,
3856        };
3857
3858        let relay2 = ConfluxExitState {
3859            runtime: Arc::clone(&relay_runtime),
3860            tunnel: Arc::clone(&tunnel),
3861            circ: circ2,
3862            rtt_delays: [].into_iter(),
3863            stream_state: Arc::clone(&stream_state),
3864            // Expect no SWITCH cells from the client
3865            expect_switch: vec![],
3866            event_tx: tx2,
3867            event_rx: rx1,
3868            is_sending_leg: true,
3869            cells_rx: cells_rx2,
3870        };
3871
3872        // Run the cell dispatcher, which tells each exit leg task
3873        // what cells to write.
3874        //
3875        // This enables us to write out-of-order cells deterministically.
3876        rt.spawn(dispatcher.run()).unwrap();
3877
3878        for mut mock_relay in [relay1, relay2] {
3879            let leg = mock_relay.circ.unique_id;
3880
3881            good_exit_handshake(
3882                &relay_runtime,
3883                mock_relay.rtt_delays.next().flatten(),
3884                &mut mock_relay.circ.chan_rx,
3885                &mut mock_relay.circ.circ_tx,
3886            )
3887            .await;
3888
3889            let relay = ConfluxTestEndpoint::Relay(mock_relay);
3890
3891            tasks.push(rt.spawn_join(format!("relay task {leg}"), run_conflux_endpoint(relay)));
3892        }
3893
3894        tasks.push(rt.spawn_join(
3895            "client task".to_string(),
3896            run_conflux_endpoint(ConfluxTestEndpoint::Client {
3897                tunnel,
3898                conflux_link_rx,
3899                send_data: send_data.clone(),
3900                recv_data,
3901            }),
3902        ));
3903
3904        // Wait for all the tasks to complete
3905        let _sinks = futures::future::join_all(tasks).await;
3906
3907        stream_state
3908    }
3909
3910    #[traced_test]
3911    #[test]
3912    #[cfg(feature = "conflux")]
3913    fn multipath_exit_to_client() {
3914        // The data we expect the client to read from the stream
3915        const TO_SEND: &[u8] =
3916            b"But something about Buster Friendly irritated John Isidore, one specific thing";
3917
3918        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
3919            // The indices of the tunnel legs.
3920            const CIRC1: usize = 0;
3921            const CIRC2: usize = 1;
3922
3923            // The client receives the following cells, in the order indicated
3924            // by the t0-t8 "timestamps" (where C = CONNECTED, D = DATA, E = END,
3925            // S = SWITCH):
3926            //
3927            //  Leg 1 (CIRC1):   -----------D--------------------- D -- D -- C
3928            //                              |                      |    |    | \
3929            //                              |                      |    |    |  v
3930            //                              |                      |    |    | client
3931            //                              |                      |    |    |  ^
3932            //                              |                      |    |    |/
3933            //  Leg 2 (CIRC2): E - D -- D --\--- D* -- S (seqno=4)-/----/----/
3934            //                 |   |    |   |    |       |         |    |    |
3935            //                 |   |    |   |    |       |         |    |    |
3936            //                 |   |    |   |    |       |         |    |    |
3937            //  Time:          t8  t7   t6  t5   t4      t3        t2   t1  t0
3938            //
3939            //
3940            //  The cells marked with * are out of order.
3941            //
3942            // Note: t0 is the time when the client receives the first cell,
3943            // and t8 is the time when it receives the last one.
3944            // In other words, this test simulates a mock exit that "sent" the cells
3945            // in the order t0, t1, t2, t5, t4, t6, t7, t8
3946            let simple_switch = vec![
3947                (CIRC1, relaymsg::Data::new(&TO_SEND[0..5]).unwrap().into()),
3948                (CIRC1, relaymsg::Data::new(&TO_SEND[5..10]).unwrap().into()),
3949                // Switch to sending on the second leg
3950                (CIRC2, relaymsg::ConfluxSwitch::new(4).into()),
3951                // An out of order cell!
3952                (CIRC2, relaymsg::Data::new(&TO_SEND[20..30]).unwrap().into()),
3953                // The missing cell (as indicated by seqno = 4 from the switch cell above)
3954                // is finally arriving on leg1
3955                (CIRC1, relaymsg::Data::new(&TO_SEND[10..20]).unwrap().into()),
3956                (CIRC2, relaymsg::Data::new(&TO_SEND[30..40]).unwrap().into()),
3957                (CIRC2, relaymsg::Data::new(&TO_SEND[40..]).unwrap().into()),
3958            ];
3959
3960            //  Leg 1 (CIRC1): ---------------- D  ------D* --- S(seqno = 3) -- D - D ---------------------------- C
3961            //                                  |        |          |           |   |                              | \
3962            //                                  |        |          |           |   |                              |  v
3963            //                                  |        |          |           |   |                              |  client
3964            //                                  |        |          |           |   |                              |  ^
3965            //                                  |        |          |           |   |                              | /
3966            //  Leg 2 (CIRC2): E - S(seqno = 2) \ -- D --\----------\---------- \ --\--- D* -- D* - S(seqno = 3) --/
3967            //                 |        |       |    |   |          |           |   |    |     |         |         |
3968            //                 |        |       |    |   |          |           |   |    |     |         |         |
3969            //                 |        |       |    |   |          |           |   |    |     |         |         |
3970            //  Time:          t11      t10     t9   t8  t7         t6          t5  t4   t3    t2        t1        t0
3971            //  =====================================================================================================
3972            //  Leg 1 LSR:      8        8      8 7  7   7          6           3   2    1      1        1         1
3973            //  Leg 2 LSR:      9        8      6 6  6   5          5           5   5    5      4        3         0
3974            //  LSD:            9        8      8 7  6   5          5       5   3   2    1      1        1         1
3975            //                                    ^ OOO cell is delivered   ^ the OOO cells are delivered to the stream
3976            //
3977            //
3978            //  (LSR = last seq received, LSD = last seq delivered, both from the client's POV)
3979            //
3980            //
3981            // The client keeps track of the `last_seqno_received` (LSR) on each leg.
3982            // This is incremented for each cell that counts towards the seqnos (BEGIN, DATA, etc.)
3983            // that is received on the leg. The client also tracks the `last_seqno_delivered` (LSD),
3984            // which is the seqno of the last cell delivered to a stream
3985            // (this is global for the whole tunnel, whereas the LSR is different for each leg).
3986            //
3987            // When switching to leg `N`, the seqno in the switch is, from the POV of the sender,
3988            // the delta between the absolute seqno (i.e. the total number of cells[^1] sent)
3989            // and the value of this absolute seqno when leg `N` was last used.
3990            //
3991            // At the time of the first SWITCH from `t1`, the exit "sent" 3 cells:
3992            // a `CONNECTED` cell, which was received by the client at `t0`, and 2 `DATA` cells that
3993            // haven't been received yet. At this point, the exit decides to switch to leg 2,
3994            // on which it hasn't sent any cells yet, so the seqno is set to `3 - 0 = 3`.
3995            //
3996            // At `t6` when the exit sends the second switch (leg 2 -> leg 1), has "sent" 6 cells
3997            // (`C` plus the data cells that are received at `t1 - 5` and `t8`.
3998            // The seqno is `6 - 3 = 3`, because when it last sent on leg 1,
3999            // the absolute seqno was `3`.
4000            //
4001            // At `t10`, the absolute seqno is 8 (8 qualifying cells have been sent so far).
4002            // When the exit last sent on leg 2 (which we are switching to),
4003            // the absolute seqno was `6`, so the `SWITCH` cell will have `8 - 6 = 2` as the seqno.
4004            //
4005            // [^1]: only counting the cells that count towards sequence numbers
4006            let multiple_switches = vec![
4007                // Immediately switch to sending on the second leg
4008                // (indicating that we've already sent 3 cells (including the CONNECTED)
4009                (CIRC2, relaymsg::ConfluxSwitch::new(3).into()),
4010                // Two out of order cells!
4011                (CIRC2, relaymsg::Data::new(&TO_SEND[15..20]).unwrap().into()),
4012                (CIRC2, relaymsg::Data::new(&TO_SEND[20..30]).unwrap().into()),
4013                // The missing cells finally arrive on the first leg
4014                (CIRC1, relaymsg::Data::new(&TO_SEND[0..10]).unwrap().into()),
4015                (CIRC1, relaymsg::Data::new(&TO_SEND[10..15]).unwrap().into()),
4016                // Switch back to the first leg
4017                (CIRC1, relaymsg::ConfluxSwitch::new(3).into()),
4018                // OOO cell
4019                (CIRC1, relaymsg::Data::new(&TO_SEND[31..40]).unwrap().into()),
4020                // Missing cell is received
4021                (CIRC2, relaymsg::Data::new(&TO_SEND[30..31]).unwrap().into()),
4022                // The remaining cells are in-order
4023                (CIRC1, relaymsg::Data::new(&TO_SEND[40..]).unwrap().into()),
4024                // Switch right after we've sent all the data we had to send
4025                (CIRC2, relaymsg::ConfluxSwitch::new(2).into()),
4026            ];
4027
4028            // TODO: give these tests the ability to control when END cells are sent
4029            // (currently we have ensure the is_sending_leg is set to true
4030            // on the leg that ends up sending the last data cell).
4031            //
4032            // TODO: test the edge cases
4033            let tests = [simple_switch, multiple_switches];
4034
4035            for cells_to_send in tests {
4036                let tunnel = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
4037                assert_eq!(tunnel.circs.len(), 2);
4038                let circ_ids = [tunnel.circs[0].unique_id, tunnel.circs[1].unique_id];
4039                let cells_to_send = cells_to_send
4040                    .into_iter()
4041                    .map(|(i, cell)| (circ_ids[i], cell))
4042                    .collect();
4043
4044                // The client won't be sending any DATA cells on this stream
4045                let send_data = vec![];
4046                let stream_state = run_multipath_exit_to_client_test(
4047                    rt.clone(),
4048                    tunnel,
4049                    cells_to_send,
4050                    send_data.clone(),
4051                    TO_SEND.into(),
4052                )
4053                .await;
4054                let stream_state = stream_state.lock().unwrap();
4055                assert!(stream_state.begin_recvd);
4056                // We don't expect the client to have sent anything
4057                assert!(stream_state.data_recvd.is_empty());
4058            }
4059        });
4060    }
4061
4062    #[traced_test]
4063    #[test]
4064    #[cfg(all(feature = "conflux", feature = "hs-service"))]
4065    fn conflux_incoming_stream() {
4066        tor_rtmock::MockRuntime::test_with_various(|rt| async move {
4067            use std::error::Error as _;
4068
4069            const EXPECTED_HOP: u8 = 1;
4070
4071            let TestTunnelCtx {
4072                tunnel,
4073                circs,
4074                conflux_link_rx,
4075            } = setup_good_conflux_tunnel(&rt, build_cc_vegas_params()).await;
4076
4077            let [mut circ1, mut circ2]: [TestCircuitCtx; 2] = circs.try_into().unwrap();
4078
4079            let link = await_link_payload(&mut circ1.chan_rx).await;
4080            for circ in [&mut circ1, &mut circ2] {
4081                let linked = relaymsg::ConfluxLinked::new(link.payload().clone()).into();
4082                circ.circ_tx
4083                    .send(rmsg_to_ccmsg(None, linked, false))
4084                    .await
4085                    .unwrap();
4086            }
4087
4088            let conflux_hs_res = conflux_link_rx.await.unwrap().unwrap();
4089            assert!(conflux_hs_res.iter().all(|res| res.is_ok()));
4090
4091            // TODO(#2002): we don't currently support conflux for onion services
4092            let err = tunnel
4093                .allow_stream_requests(
4094                    &[tor_cell::relaycell::RelayCmd::BEGIN],
4095                    (tunnel.circ.unique_id(), EXPECTED_HOP.into()).into(),
4096                    AllowAllStreamsFilter,
4097                )
4098                .await
4099                // IncomingStream doesn't impl Debug, so we need to map to a different type
4100                .map(|_| ())
4101                .unwrap_err();
4102
4103            let err_src = err.source().unwrap().to_string();
4104            assert!(
4105                err_src.contains("Cannot allow stream requests on a multi-path tunnel"),
4106                "{err_src}"
4107            );
4108        });
4109    }
4110
4111    #[test]
4112    fn client_circ_chan_msg() {
4113        use tor_cell::chancell::msg::{self, AnyChanMsg};
4114        fn good(m: AnyChanMsg) {
4115            assert!(ClientCircChanMsg::try_from(m).is_ok());
4116        }
4117        fn bad(m: AnyChanMsg) {
4118            assert!(ClientCircChanMsg::try_from(m).is_err());
4119        }
4120
4121        good(msg::Destroy::new(2.into()).into());
4122        bad(msg::CreatedFast::new(&b"guaranteed in this world"[..]).into());
4123        bad(msg::Created2::new(&b"and the next"[..]).into());
4124        good(msg::Relay::new(&b"guaranteed guaranteed"[..]).into());
4125        bad(msg::AnyChanMsg::RelayEarly(
4126            msg::Relay::new(&b"for the world and its mother"[..]).into(),
4127        ));
4128        bad(msg::Versions::new([1, 2, 3]).unwrap().into());
4129    }
4130}