//! Abstract code to manage a set of tunnels which has underlying circuit(s).

//!

//! This module implements the real logic for deciding when and how to

//! launch tunnels, and for which tunnels to hand out in response to

//! which requests.

//!

//! For testing and abstraction purposes, this module _does not_

//! actually know anything about tunnels _per se_.  Instead,

//! everything is handled using a set of traits that are internal to this

//! crate:

//!

//!  * [`AbstractTunnel`] is a view of a tunnel.

//!  * [`AbstractTunnelBuilder`] knows how to build an `AbstractCirc`.

//!

//! Using these traits, the [`AbstractTunnelMgr`] object manages a set of

//! tunnels , launching them as necessary, and keeping track of the

//! restrictions on their use.

// TODO:

// - Testing

//    - Error from prepare_action()

//    - Error reported by restrict_mut?

use crate::config::CircuitTiming;

use crate::usage::{SupportedTunnelUsage, TargetTunnelUsage};

use crate::{DirInfo, Error, PathConfig, Result, timeouts};

use retry_error::RetryError;

use tor_async_utils::mpsc_channel_no_memquota;

use tor_basic_utils::retry::RetryDelay;

use tor_config::MutCfg;

use tor_error::{AbsRetryTime, HasRetryTime, debug_report, info_report, internal, warn_report};

#[cfg(feature = "vanguards")]

use tor_guardmgr::vanguards::VanguardMgr;

use tor_linkspec::CircTarget;

use tor_proto::circuit::UniqId;

use tor_proto::client::circuit::{CircParameters, Path};

use tor_rtcompat::{Runtime, SleepProviderExt};

use async_trait::async_trait;

use futures::channel::mpsc;

use futures::future::{FutureExt, Shared};

use futures::stream::{FuturesUnordered, StreamExt};

use futures::task::SpawnExt;

use oneshot_fused_workaround as oneshot;

use std::collections::HashMap;

use std::fmt::Debug;

use std::hash::Hash;

use std::panic::AssertUnwindSafe;

use std::sync::{self, Arc, Weak};

use std::time::{Duration, Instant};

use tracing::{debug, warn};

use weak_table::PtrWeakHashSet;

mod streams;

/// Description of how we got a tunnel.

#[non_exhaustive]

#[derive(Debug, Copy, Clone, Eq, PartialEq)]

pub(crate) enum TunnelProvenance {

    /// This channel was newly launched, or was in progress and finished while

    /// we were waiting.

    NewlyCreated,

    /// This channel already existed when we asked for it.

    Preexisting,

}

#[derive(Clone, Debug, thiserror::Error)]

#[non_exhaustive]

pub enum RestrictionFailed {

    /// Tried to restrict a specification, but the tunnel didn't support the

    /// requested usage.

    #[error("Specification did not support desired usage")]

    NotSupported,

}

/// Minimal abstract view of a tunnel.

///

/// From this module's point of view, tunnels are simply objects

/// with unique identities, and a possible closed-state.

#[async_trait]

pub(crate) trait AbstractTunnel: Debug {

    /// Type for a unique identifier for tunnels.

    type Id: Clone + Debug + Hash + Eq + Send + Sync;

    /// Return the unique identifier for this tunnel.

    ///

    /// # Requirements

    ///

    /// The values returned by this function are unique for distinct

    /// tunnels.

    fn id(&self) -> Self::Id;

    /// Return true if this tunnel is usable for some purpose.

    ///

    /// Reasons a tunnel might be unusable include being closed.

    fn usable(&self) -> bool;

    /// Return a list of [`Path`] objects describing the only circuit in this tunnel.

    ///

    /// Returns an error if the tunnel has more than one tunnel.

    fn single_path(&self) -> tor_proto::Result<Arc<Path>>;

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

    ///

    /// Returns an error if the circuit is closed.

    ///

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

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

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

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

    fn n_hops(&self) -> tor_proto::Result<usize>;

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

    fn is_closing(&self) -> bool;

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

    fn unique_id(&self) -> UniqId;

    /// Extend the tunnel via the most appropriate handshake to a new `target` hop.

    async fn extend<T: CircTarget + Sync>(

        &self,

        target: &T,

        params: CircParameters,

    ) -> tor_proto::Result<()>;

}

/// A plan for an `AbstractCircBuilder` that can maybe be mutated by tests.

///

/// You should implement this trait using all default methods for all code that isn't test code.

pub(crate) trait MockablePlan {

    /// Add a reason string that was passed to `SleepProvider::block_advance()` to this object

    /// so that it knows what to pass to `::release_advance()`.

}

/// An object that knows how to build tunnels.

///

/// This creates tunnels in two phases. First, a plan is

/// made for how to build the tunnel. This planning phase should be

/// relatively fast, and must not suspend or block.  Its purpose is to

/// get an early estimate of which operations the tunnel will be able

/// to support when it's done.

///

/// Second, the tunnel is actually built, using the plan as input.

#[async_trait]

pub(crate) trait AbstractTunnelBuilder<R: Runtime>: Send + Sync {

    /// The tunnel type that this builder knows how to build.

    type Tunnel: AbstractTunnel + Send + Sync;

    /// An opaque type describing how a given tunnel will be built.

    /// It may represent some or all of a path-or it may not.

    //

    // TODO: It would be nice to have this parameterized on a lifetime,

    // and have that lifetime depend on the lifetime of the directory.

    // But I don't think that rust can do that.

    //

    // HACK(eta): I don't like the fact that `MockablePlan` is necessary here.

    type Plan: Send + Debug + MockablePlan;

    // TODO: I'd like to have a Dir type here to represent

    // create::DirInfo, but that would need to be parameterized too,

    // and would make everything complicated.

    /// Form a plan for how to build a new tunnel that supports `usage`.

    ///

    /// Return an opaque Plan object, and a new spec describing what

    /// the tunnel will actually support when it's built.  (For

    /// example, if the input spec requests a tunnel that connect to

    /// port 80, then "planning" the tunnel might involve picking an

    /// exit that supports port 80, and the resulting spec might be

    /// the exit's complete list of supported ports.)

    ///

    /// # Requirements

    ///

    /// The resulting Spec must support `usage`.

    fn plan_tunnel(

        &self,

        usage: &TargetTunnelUsage,

        dir: DirInfo<'_>,

    ) -> Result<(Self::Plan, SupportedTunnelUsage)>;

    /// Construct a tunnel according to a given plan.

    ///

    /// On success, return a spec describing what the tunnel can be used for,

    /// and the tunnel that was just constructed.

    ///

    /// This function should implement some kind of a timeout for

    /// tunnel that are taking too long.

    ///

    /// # Requirements

    ///

    /// The spec that this function returns _must_ support the usage

    /// that was originally passed to `plan_tunnel`.  It _must_ also

    /// contain the spec that was originally returned by

    /// `plan_tunnel`.

    async fn build_tunnel(&self, plan: Self::Plan) -> Result<(SupportedTunnelUsage, Self::Tunnel)>;

    /// Return a "parallelism factor" with which tunnels should be

    /// constructed for a given purpose.

    ///

    /// If this function returns N, then whenever we launch tunnels

    /// for this purpose, then we launch N in parallel.

    ///

    /// The default implementation returns 1.  The value of 0 is

    /// treated as if it were 1.

    /// Return a "parallelism factor" for which tunnels should be

    /// used for a given purpose.

    ///

    /// If this function returns N, then whenever we select among

    /// open tunnels for this purpose, we choose at random from the

    /// best N.

    ///

    /// The default implementation returns 1.  The value of 0 is

    /// treated as if it were 1.

    // TODO: Possibly this doesn't belong in this trait.

    /// Return true if we are currently attempting to learn tunnel

    /// timeouts by building testing tunnels.

    fn learning_timeouts(&self) -> bool;

    /// Flush state to the state manager if we own the lock.

    ///

    /// Return `Ok(true)` if we saved, and `Ok(false)` if we didn't hold the lock.

    fn save_state(&self) -> Result<bool>;

    /// Return this builder's [`PathConfig`].

    fn path_config(&self) -> Arc<PathConfig>;

    /// Replace this builder's [`PathConfig`].

    // TODO: This is dead_code because we only call this for the CircuitBuilder specialization of

    // CircMgr, not from the generic version, because this trait doesn't provide guardmgr, which is

    // needed by the [`CircMgr::reconfigure`] function that would be the only caller of this. We

    // should add `guardmgr` to this trait, make [`CircMgr::reconfigure`] generic, and remove this

    // dead_code marking.

    #[allow(dead_code)]

    fn set_path_config(&self, new_config: PathConfig);

    /// Return a reference to this builder's timeout estimator.

    fn estimator(&self) -> &timeouts::Estimator;

    /// Return a reference to this builder's `VanguardMgr`.

    #[cfg(feature = "vanguards")]

    fn vanguardmgr(&self) -> &Arc<VanguardMgr<R>>;

    /// Replace our state with a new owning state, assuming we have

    /// storage permission.

    fn upgrade_to_owned_state(&self) -> Result<()>;

    /// Reload persistent state from disk, if we don't have storage permission.

    fn reload_state(&self) -> Result<()>;

    /// Return a reference to this builder's `GuardMgr`.

    fn guardmgr(&self) -> &tor_guardmgr::GuardMgr<R>;

    /// Reconfigure this builder using the latest set of network parameters.

    ///

    /// (NOTE: for now, this only affects tunnel timeout estimation.)

    fn update_network_parameters(&self, p: &tor_netdir::params::NetParameters);

}

/// Enumeration to track the expiration state of a tunnel.

///

/// A tunnel an either be unused (at which point it should expire if it is

/// _still unused_ by a certain time, or dirty (at which point it should

/// expire after a certain duration).

///

/// All tunnels start out "unused" and become "dirty" when their spec

/// is first restricted -- that is, when they are first handed out to be

/// used for a request.

#[derive(Debug, Clone, PartialEq, Eq)]

enum ExpirationInfo {

    /// The tunnel has never been used.

    Unused {

        /// A time when the tunnel should expire.

        use_before: Instant,

    },

    /// The tunnel has been used (or at least, restricted for use with a

    /// request) at least once.

    Dirty {

        /// The time at which this tunnel's spec was first restricted.

        dirty_since: Instant,

    },

}

impl ExpirationInfo {

    /// Return an ExpirationInfo for a newly created tunnel.

    /// Mark this ExpirationInfo as dirty, if it is not already dirty.

}

/// An entry for an open tunnel held by an `AbstractTunnelMgr`.

#[derive(Debug, Clone)]

pub(crate) struct OpenEntry<T> {

    /// The supported usage for this tunnel.

    spec: SupportedTunnelUsage,

    /// The tunnel under management.

    tunnel: Arc<T>,

    /// When does this tunnel expire?

    ///

    /// (Note that expired tunnels are removed from the manager,

    /// which does not actually close them until there are no more

    /// references to them.)

    expiration: ExpirationInfo,

}

impl<T: AbstractTunnel> OpenEntry<T> {

    /// Make a new OpenEntry for a given tunnel and spec.

    /// Return true if the underlying tunnel can be used for `usage`.

    /// Change the underlying tunnel's permissible usage, based on its having

    /// been used for `usage` at time `now`.

    ///

    /// Return an error if the tunnel may not be used for `usage`.

    /// Find the "best" entry from a slice of OpenEntry for supporting

    /// a given `usage`.

    ///

    /// If `parallelism` is some N greater than 1, we pick randomly

    /// from the best `N` tunnels.

    ///

    /// # Requirements

    ///

    /// Requires that `ents` is nonempty, and that every element of `ents`

    /// supports `spec`.

        use rand::seq::IndexedMutRandom as _;

        // TODO: Actually look over the whole list to see which is better.

    /// Return true if this tunnel has been marked as dirty before

    /// `dirty_cutoff`, or if it is an unused tunnel set to expire before

    /// `unused_cutoff`.

        }

}

/// A result type whose "Ok" value is the Id for a tunnel from B.

type PendResult<B, R> = Result<<<B as AbstractTunnelBuilder<R>>::Tunnel as AbstractTunnel>::Id>;

/// An in-progress tunnel request tracked by an `AbstractTunnelMgr`.

///

/// (In addition to tracking tunnels, `AbstractTunnelMgr` tracks

/// _requests_ for tunnels.  The manager uses these entries if it

/// finds that some tunnel created _after_ a request first launched

/// might meet the request's requirements.)

struct PendingRequest<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// Usage for the operation requested by this request

    usage: TargetTunnelUsage,

    /// A channel to use for telling this request about tunnels that it

    /// might like.

    notify: mpsc::Sender<PendResult<B, R>>,

}

impl<B: AbstractTunnelBuilder<R>, R: Runtime> PendingRequest<B, R> {

    /// Return true if this request would be supported by `spec`.

}

/// An entry for an under-construction in-progress tunnel tracked by

/// an `AbstractTunnelMgr`.

#[derive(Debug)]

struct PendingEntry<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// Specification that this tunnel will support, if every pending

    /// request that is waiting for it is attached to it.

    ///

    /// This spec becomes more and more restricted as more pending

    /// requests are waiting for this tunnel.

    ///

    /// This spec is contained by circ_spec, and must support the usage

    /// of every pending request that's waiting for this tunnel.

    tentative_assignment: sync::Mutex<SupportedTunnelUsage>,

    /// A shared future for requests to use when waiting for

    /// notification of this tunnel's success.

    receiver: Shared<oneshot::Receiver<PendResult<B, R>>>,

}

impl<B: AbstractTunnelBuilder<R>, R: Runtime> PendingEntry<B, R> {

    /// Make a new PendingEntry that starts out supporting a given

    /// spec.  Return that PendingEntry, along with a Sender to use to

    /// report the result of building this tunnel.

    /// Return true if this tunnel's current tentative assignment

    /// supports `usage`.

    /// Try to change the tentative assignment of this tunnel by

    /// restricting it for use with `usage`.

    ///

    /// Return an error if the current tentative assignment didn't

    /// support `usage` in the first place.

    /// Find the best PendingEntry values from a slice for use with

    /// `usage`.

    ///

    /// # Requirements

    ///

    /// The `ents` slice must not be empty.  Every element of `ents`

    /// must support the given spec.

        // TODO: Actually look over the whole list to see which is better.

}

/// Wrapper type to represent the state between planning to build a

/// tunnel and constructing it.

#[derive(Debug)]

struct TunnelBuildPlan<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// The Plan object returned by [`AbstractTunnelBuilder::plan_tunnel`].

    plan: B::Plan,

    /// A sender to notify any pending requests when this tunnel is done.

    sender: oneshot::Sender<PendResult<B, R>>,

    /// A strong entry to the PendingEntry for this tunnel build attempt.

    pending: Arc<PendingEntry<B, R>>,

}

/// The inner state of an [`AbstractTunnelMgr`].

struct TunnelList<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// A map from tunnel ID to [`OpenEntry`] values for all managed

    /// open tunnels.

    ///

    /// A tunnel is added here from [`AbstractTunnelMgr::do_launch`] when we find

    /// that it completes successfully, and has not been cancelled.

    /// When we decide that such a tunnel should no longer be handed out for

    /// any new requests, we "retire" the tunnel by removing it from this map.

    #[allow(clippy::type_complexity)]

    open_tunnels: HashMap<<B::Tunnel as AbstractTunnel>::Id, OpenEntry<B::Tunnel>>,

    /// Weak-set of PendingEntry for tunnels that are being built.

    ///

    /// Because this set only holds weak references, and the only strong

    /// reference to the PendingEntry is held by the task building the tunnel,

    /// this set's members are lazily removed after the tunnel is either built

    /// or fails to build.

    ///

    /// This set is used for two purposes:

    ///

    /// 1. When a tunnel request finds that there is no open tunnel for its

    ///    purposes, it checks here to see if there is a pending tunnel that it

    ///    could wait for.

    /// 2. When a pending tunnel finishes building, it checks here to make sure

    ///    that it has not been cancelled. (Removing an entry from this set marks

    ///    it as cancelled.)

    ///

    /// An entry is added here in [`AbstractTunnelMgr::prepare_action`] when we

    /// decide that a tunnel needs to be launched.

    ///

    /// Later, in [`AbstractTunnelMgr::do_launch`], once the tunnel has finished

    /// (or failed), we remove the entry (by pointer identity).

    /// If we cannot find the entry, we conclude that the request has been

    /// _cancelled_, and so we discard any tunnel that was created.

    pending_tunnels: PtrWeakHashSet<Weak<PendingEntry<B, R>>>,

    /// Weak-set of PendingRequest for requests that are waiting for a

    /// tunnel to be built.

    ///

    /// Because this set only holds weak references, and the only

    /// strong reference to the PendingRequest is held by the task

    /// waiting for the tunnel to be built, this set's members are

    /// lazily removed after the request succeeds or fails.

    pending_requests: PtrWeakHashSet<Weak<PendingRequest<B, R>>>,

}

impl<B: AbstractTunnelBuilder<R>, R: Runtime> TunnelList<B, R> {

    /// Make a new empty `CircList`

    /// Add `e` to the list of open tunnels.

    /// Find all the usable open tunnels that support `usage`.

    ///

    /// Return None if there are no such tunnels.

    /// Find an open tunnel by ID.

    ///

    /// Return None if no such tunnels exists in this list.

    /// Extract an open tunnel by ID, removing it from this list.

    ///

    /// Return None if no such tunnel exists in this list.

    /// Remove tunnels based on expiration times.

    ///

    /// We remove every unused tunnel that is set to expire by

    /// `unused_cutoff`, and every dirty tunnel that has been dirty

    /// since before `dirty_cutoff`.

    /// Remove the tunnel with given `id`, if it is scheduled to

    /// expire now, according to the provided expiration times.

    /// Add `pending` to the set of in-progress tunnels.

    /// Find all pending tunnels that support `usage`.

    ///

    /// If no such tunnels are currently being built, return None.

        } else {

        }

    /// Return true if `circ` is still pending.

    ///

    /// A tunnel will become non-pending when finishes (successfully or not), or when it's

    /// removed from this list via `clear_all_tunnels()`.

    /// Construct and add a new entry to the set of request waiting

    /// for a tunnel.

    ///

    /// Return the request, and a new receiver stream that it should

    /// use for notification of possible tunnels to use.

    /// Return all pending requests that would be satisfied by a tunnel

    /// that supports `circ_spec`.

    /// Clear all pending and open tunnels.

    ///

    /// Calling `clear_all_tunnels` ensures that any request that is answered _after

    /// this method runs_ will receive a tunnels that was launched _after this

    /// method runs_.

        // Note that removing entries from pending_circs will also cause the

        // tunnel tasks to realize that they are cancelled when they

        // go to tell anybody about their results.

}

/// Timing information for tunnels that have been built but never used.

///

/// Currently taken from the network parameters.

struct UnusedTimings {

    /// Minimum lifetime of a tunnel created while learning

    /// tunnel timeouts.

    learning: Duration,

    /// Minimum lifetime of a tunnel created while not learning

    /// tunnel timeouts.

    not_learning: Duration,

}

// This isn't really fallible, given the definitions of the underlying

// types.

#[allow(clippy::fallible_impl_from)]

impl From<&tor_netdir::params::NetParameters> for UnusedTimings {

        // These try_into() calls can't fail, so unwrap() can't panic.

        #[allow(clippy::unwrap_used)]

}

/// Abstract implementation for tunnel management.

///

/// The algorithm provided here is fairly simple. In its simplest form:

///

/// When somebody asks for a tunnel for a given operation: if we find

/// one open already, we return it.  If we find in-progress tunnels

/// that would meet our needs, we wait for one to finish (or for all

/// to fail).  And otherwise, we launch one or more tunnels to meet the

/// request's needs.

///

/// If this process fails, then we retry it, up to a timeout or a

/// numerical limit.

///

/// If a tunnel not previously considered for a given request

/// finishes before the request is satisfied, and if the tunnel would

/// satisfy the request, we try to give that tunnel as an answer to

/// that request even if it was not one of the tunnels that request

/// was waiting for.

pub(crate) struct AbstractTunnelMgr<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// Builder used to construct tunnels.

    builder: B,

    /// An asynchronous runtime to use for launching tasks and

    /// checking timeouts.

    runtime: R,

    /// A CircList to manage our list of tunnels, requests, and

    /// pending tunnels.

    tunnels: sync::Mutex<TunnelList<B, R>>,

    /// Configured information about when to expire tunnels and requests.

    circuit_timing: MutCfg<CircuitTiming>,

    /// Minimum lifetime of an unused tunnel.

    ///

    /// Derived from the network parameters.

    unused_timing: sync::Mutex<UnusedTimings>,

}

/// An action to take in order to satisfy a request for a tunnel.

enum Action<B: AbstractTunnelBuilder<R>, R: Runtime> {

    /// We found an open tunnel: return immediately.

    Open(Arc<B::Tunnel>),

    /// We found one or more pending tunnels: wait until one succeeds,

    /// or all fail.

    Wait(FuturesUnordered<Shared<oneshot::Receiver<PendResult<B, R>>>>),

    /// We should launch tunnels: here are the instructions for how

    /// to do so.

    Build(Vec<TunnelBuildPlan<B, R>>),

}

impl<B: AbstractTunnelBuilder<R> + 'static, R: Runtime> AbstractTunnelMgr<B, R> {

    /// Construct a new AbstractTunnelMgr.

    /// Reconfigure this manager using the latest set of network parameters.

    /// Return this manager's [`CircuitTiming`].

    /// Return this manager's [`CircuitTiming`].

    /// Return a circuit suitable for use with a given `usage`,

    /// creating that circuit if necessary, and restricting it

    /// under the assumption that it will be used for that spec.

    ///

    /// This is the primary entry point for AbstractTunnelMgr.

    #[allow(clippy::cognitive_complexity)] // TODO #2010: Refactor?

        /// Largest number of "resets" that we will accept in this attempt.

        ///

        /// A "reset" is an internally generated error that does not represent a

        /// real problem; only a "whoops, got to try again" kind of a situation.

        /// For example, if we reconfigure in the middle of an attempt and need

        /// to re-launch the circuit, that counts as a "reset", since there was

        /// nothing actually _wrong_ with the circuit we were building.

        ///

        /// We accept more resets than we do real failures. However,

        /// we don't accept an unlimited number: we don't want to inadvertently

        /// permit infinite loops here. If we ever bump against this limit, we

        /// should not automatically increase it: we should instead figure out

        /// why it is happening and try to make it not happen.

        const MAX_RESETS: usize = 8;

        // We compute the maximum number of failures by dividing the maximum

        // number of circuits to attempt by the number that will be launched in

        // parallel for each iteration.

        );

            // How much time is remaining?

                None => {

                }

            };

                    // We successfully found an action: Take that action.

                        }

                        Err(_) => {

                            // We ran out of "remaining" time; there is nothing

                            // more to be done.

                        }

                    }

                }

                    // We couldn't pick the action!

                        attempt_num,

                    );

                }

            };

            // There's been an error.  See how long we wait before we retry.

            } else {

            };

            // Record the error, flattening it if needed.

            }

            // If we have reached our limit of this kind of problem, we're done.

            // Wait, or not, as appropriate.

                }

            }

        }

    /// Make sure a circuit exists, without actually asking for it.

    ///

    /// Make sure that there is a circuit (built or in-progress) that could be

    /// used for `usage`, and launch one or more circuits in a background task

    /// if there is not.

    // TODO: This should probably take some kind of parallelism parameter.

    #[cfg(test)]

    /// Choose which action we should take in order to provide a tunnel

    /// for a given `usage`.

    ///

    /// If `restrict_circ` is true, we restrict the spec of any

    /// circ we decide to use to mark that it _is_ being used for

    /// `usage`.

            // We have open tunnels that meet the spec: return the best one.

            // TODO: If we have fewer tunnels here than our select

            // parallelism, perhaps we should launch more?

            // There are pending tunnels that could meet the spec.

            // Restrict them under the assumption that they could all

            // be used for this, and then wait until one is ready (or

            // all have failed)

                    // TODO: Do we want to tentatively restrict _all_ of these?

                    // not clear to me.

                }

            // TODO: if we have fewer tunnels here than our launch

            // parallelism, we might want to launch more.

        // Okay, we need to launch tunnels here.

                }

            }

        }

        } else {

            // we didn't even try to plan anything!

        }

    /// Execute an action returned by pick-action, and return the

    /// resulting tunnel or error.

    #[allow(clippy::cognitive_complexity)] // TODO #2010: Refactor

        /// Store the error `err` into `retry_err`, as appropriate.

                // We don't care about this error, since it is from neither a tunnel we launched

                // nor one that we're waiting on.

        /// Return a string describing what it means, within the context of this

        /// function, to have gotten an answer from `source`.

            }

        // Get or make a stream of futures to wait on.

                // There's already a perfectly good open tunnel; we can return

                // it now.

            }

                // There is one or more pending tunnel that we're waiting for.

                // If any succeeds, we try to use it.  If they all fail, we

                // fail.

            }

                // We're going to launch one or more tunnels in parallel.  We

                // report success if any succeeds, and failure of they all fail.

            }

        };

        // Insert ourself into the list of pending requests, and make a

        // stream for us to listen on for notification from pending tunnels

        // other than those we are pending on.

        // We use our "select_biased" stream combiner here to ensure that:

        //   1) Circuits from wait_on_stream (the ones we're pending on) are

        //      preferred.

        //   2) We exit this function when those tunnels are exhausted.

        //   3) We still get notified about other tunnels that might meet our

        //      interests.

        //

        // The events from Left stream are the oes that we explicitly asked for,

        // so we'll treat errors there as real problems.  The events from the

        // Right stream are ones that we got opportunistically told about; it's

        // not a big deal if those fail.

                    // Great, we have a tunnel . See if we can use it!

                            Ok(()) => {

                                // Great, this will work.  We drop the

                                // pending request now explicitly to remove

                                // it from the list.

                            }

                                // In this case, a `UsageMismatched` error just means that we lost the race

                                // to restrict this tunnel.

                                };

                                        id,

                                    );

                                } else {

                                        id,

                                    );

                                }

                            }

                        }

                }

                }

                Err(oneshot::Canceled) => {

                    );

                }

            }

                id,

            );

        }

        // Nothing worked.  We drop the pending request now explicitly

        // to remove it from the list.  (We could just let it get dropped

        // implicitly, but that's a bit confusing.)

    /// Given a directory and usage, compute the necessary objects to

    /// build a tunnel: A [`PendingEntry`] to keep track of the in-process

    /// tunnel, and a [`TunnelBuildPlan`] that we'll give to the thread

    /// that will build the tunnel.

    ///

    /// The caller should probably add the resulting `PendingEntry` to

    /// `self.circs`.

    ///

    /// This is an internal function that we call when we're pretty sure

    /// we want to build a tunnel.

    #[allow(clippy::type_complexity)]

    /// Launch a managed tunnel for a target usage, without checking

    /// whether one already exists or is pending.

    ///

    /// Return a listener that will be informed when the tunnel is done.

    /// Spawn a background task to launch a tunnel, and report its status.

    ///

    /// The `usage` argument is the usage from the original request that made

    /// us build this tunnel.

        let TunnelBuildPlan {

        // We release this block when the tunnel builder task terminates.

        // During tests, the `FakeBuilder` will need to release the block in order to fake a timeout

        // correctly.

                        // Okay, this is a panic.  We have to tell the calling

                        // thread about it, then exit this tunnel builder task.

                    }

                };

                // Tell anybody who was listening about it that this

                // tunnel is now usable or failed.

                //

                // (We ignore any errors from `send`: That just means that nobody

                // was waiting for this tunnel.)

                    // Wait briefly before we notify opportunistically.  This

                    // delay will give the tunnels that were originally

                    // specifically intended for a request a little more time

                    // to finish, before we offer it this tunnel instead.

                    };

    /// Run in the background to launch a tunnel. Return a 2-tuple of the new

    /// tunnel spec and the outcome that should be sent to the initiator.

                // I used to call restrict_mut here, but now I'm not so

                // sure. Doing restrict_mut makes sure that this

                // tunnel will be suitable for the request that asked

                // for us in the first place, but that should be

                // ensured anyway by our tracking its tentative

                // assignment.

                //