//! A general interface for Tor client usage.

//!

//! To construct a client, run the [`TorClient::create_bootstrapped`] method.

//! Once the client is bootstrapped, you can make anonymous

//! connections ("streams") over the Tor network using

//! [`TorClient::connect`].

#[cfg(feature = "rpc")]

use {derive_deftly::Deftly, tor_rpcbase::templates::*};

use crate::address::{IntoTorAddr, ResolveInstructions, StreamInstructions};

use crate::config::{

    ClientAddrConfig, SoftwareStatusOverrideConfig, StreamTimeoutConfig, TorClientConfig,

};

use safelog::{Sensitive, sensitive};

use tor_async_utils::{DropNotifyWatchSender, PostageWatchSenderExt};

use tor_chanmgr::ChanMgrConfig;

use tor_circmgr::ClientDataTunnel;

use tor_circmgr::isolation::{Isolation, StreamIsolation};

use tor_circmgr::{IsolationToken, TargetPort, isolation::StreamIsolationBuilder};

use tor_config::MutCfg;

#[cfg(feature = "bridge-client")]

use tor_dirmgr::bridgedesc::BridgeDescMgr;

use tor_dirmgr::{DirMgrStore, Timeliness};

use tor_error::{Bug, error_report, internal};

use tor_guardmgr::{GuardMgr, RetireCircuits};

use tor_keymgr::Keystore;

use tor_memquota::MemoryQuotaTracker;

use tor_netdir::{NetDirProvider, params::NetParameters};

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

use tor_persist::state_dir::StateDirectory;

use tor_persist::{FsStateMgr, StateMgr};

use tor_proto::client::stream::{DataStream, IpVersionPreference, StreamParameters};

#[cfg(all(

    any(feature = "native-tls", feature = "rustls"),

    any(feature = "async-std", feature = "tokio"),

))]

use tor_rtcompat::PreferredRuntime;

use tor_rtcompat::{Runtime, SleepProviderExt};

#[cfg(feature = "onion-service-client")]

use {

    tor_config::BoolOrAuto,

    tor_hsclient::{HsClientConnector, HsClientDescEncKeypairSpecifier, HsClientSecretKeysBuilder},

    tor_hscrypto::pk::{HsClientDescEncKey, HsClientDescEncKeypair, HsClientDescEncSecretKey},

    tor_netdir::DirEvent,

};

#[cfg(all(feature = "onion-service-service", feature = "experimental-api"))]

use tor_hsservice::HsIdKeypairSpecifier;

#[cfg(all(feature = "onion-service-client", feature = "experimental-api"))]

use {tor_hscrypto::pk::HsId, tor_hscrypto::pk::HsIdKeypair, tor_keymgr::KeystoreSelector};

use tor_keymgr::{ArtiNativeKeystore, KeyMgr, KeyMgrBuilder, config::ArtiKeystoreKind};

#[cfg(feature = "ephemeral-keystore")]

use tor_keymgr::ArtiEphemeralKeystore;

#[cfg(feature = "ctor-keystore")]

use tor_keymgr::{CTorClientKeystore, CTorServiceKeystore};

use futures::StreamExt as _;

use futures::lock::Mutex as AsyncMutex;

use std::net::IpAddr;

use std::result::Result as StdResult;

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

use tor_rtcompat::SpawnExt;

use crate::err::ErrorDetail;

use crate::{TorClientBuilder, status, util};

#[cfg(feature = "geoip")]

use tor_geoip::CountryCode;

use tor_rtcompat::scheduler::TaskHandle;

use tracing::{debug, info, instrument};

/// An active client session on the Tor network.

///

/// While it's running, it will fetch directory information, build

/// circuits, and make connections for you.

///

/// Cloning this object makes a new reference to the same underlying

/// handles: it's usually better to clone the `TorClient` than it is to

/// create a new one.

///

/// # In the Arti RPC System

///

/// An open client on the Tor network.

///

/// A `TorClient` can be used to open anonymous connections,

/// and (eventually) perform other activities.

///

/// You can use an `RpcSession` as a `TorClient`, or use the `isolated_client` method

/// to create a new `TorClient` whose stream will not share circuits with any other Tor client.

///

/// This ObjectID for this object can be used as the target of a SOCKS stream.

// TODO(nickm): This type now has 5 Arcs inside it, and 2 types that have

// implicit Arcs inside them! maybe it's time to replace much of the insides of

// this with an Arc<TorClientInner>?

#[derive(Clone)]

#[cfg_attr(

    feature = "rpc",

    derive(Deftly),

    derive_deftly(Object),

    deftly(rpc(expose_outside_of_session))

)]

pub struct TorClient<R: Runtime> {

    /// Asynchronous runtime object.

    runtime: R,

    /// Default isolation token for streams through this client.

    ///

    /// This is eventually used for `owner_token` in `tor-circmgr/src/usage.rs`, and is orthogonal

    /// to the `stream_isolation` which comes from `connect_prefs` (or a passed-in `StreamPrefs`).

    /// (ie, both must be the same to share a circuit).

    client_isolation: IsolationToken,

    /// Connection preferences.  Starts out as `Default`,  Inherited by our clones.

    connect_prefs: StreamPrefs,

    /// Memory quota tracker

    memquota: Arc<MemoryQuotaTracker>,

    /// Channel manager, used by circuits etc.,

    ///

    /// Used directly by client only for reconfiguration.

    chanmgr: Arc<tor_chanmgr::ChanMgr<R>>,

    /// Circuit manager for keeping our circuits up to date and building

    /// them on-demand.

    circmgr: Arc<tor_circmgr::CircMgr<R>>,

    /// Directory manager persistent storage.

    #[cfg_attr(not(feature = "bridge-client"), allow(dead_code))]

    dirmgr_store: DirMgrStore<R>,

    /// Directory manager for keeping our directory material up to date.

    dirmgr: Arc<dyn tor_dirmgr::DirProvider>,

    /// Bridge descriptor manager

    ///

    /// None until we have bootstrapped.

    ///

    /// Lock hierarchy: don't acquire this before dormant

    //

    // TODO: after or as part of https://gitlab.torproject.org/tpo/core/arti/-/issues/634

    // this can be   bridge_desc_mgr: BridgeDescMgr<R>>

    // since BridgeDescMgr is Clone and all its methods take `&self` (it has a lock inside)

    // Or maybe BridgeDescMgr should not be Clone, since we want to make Weaks of it,

    // which we can't do when the Arc is inside.

    #[cfg(feature = "bridge-client")]

    bridge_desc_mgr: Arc<Mutex<Option<Arc<BridgeDescMgr<R>>>>>,

    /// Pluggable transport manager.

    #[cfg(feature = "pt-client")]

    pt_mgr: Arc<tor_ptmgr::PtMgr<R>>,

    /// HS client connector

    #[cfg(feature = "onion-service-client")]

    hsclient: HsClientConnector<R>,

    /// Circuit pool for providing onion services with circuits.

    #[cfg(any(feature = "onion-service-client", feature = "onion-service-service"))]

    hs_circ_pool: Arc<tor_circmgr::hspool::HsCircPool<R>>,

    /// A handle to this client's [`InertTorClient`].

    ///

    /// Used for accessing the key manager and other persistent state.

    inert_client: InertTorClient,

    /// Guard manager

    #[cfg_attr(not(feature = "bridge-client"), allow(dead_code))]

    guardmgr: GuardMgr<R>,

    /// Location on disk where we store persistent data containing both location and Mistrust information.

    ///

    ///

    /// This path is configured via `[storage]` in the config but is not used directly as a

    /// StateDirectory in most places. Instead, its path and Mistrust information are copied

    /// to subsystems like `dirmgr`, `keymgr`, and `statemgr` during `TorClient` creation.

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

    state_directory: StateDirectory,

    /// Location on disk where we store persistent data (cooked state manager).

    statemgr: FsStateMgr,

    /// Client address configuration

    addrcfg: Arc<MutCfg<ClientAddrConfig>>,

    /// Client DNS configuration

    timeoutcfg: Arc<MutCfg<StreamTimeoutConfig>>,

    /// Software status configuration.

    software_status_cfg: Arc<MutCfg<SoftwareStatusOverrideConfig>>,

    /// Mutex used to serialize concurrent attempts to reconfigure a TorClient.

    ///

    /// See [`TorClient::reconfigure`] for more information on its use.

    reconfigure_lock: Arc<Mutex<()>>,

    /// A stream of bootstrap messages that we can clone when a client asks for

    /// it.

    ///

    /// (We don't need to observe this stream ourselves, since it drops each

    /// unobserved status change when the next status change occurs.)

    status_receiver: status::BootstrapEvents,

    /// mutex used to prevent two tasks from trying to bootstrap at once.

    bootstrap_in_progress: Arc<AsyncMutex<()>>,

    /// Whether or not we should call `bootstrap` before doing things that require

    /// bootstrapping. If this is `false`, we will just call `wait_for_bootstrap`

    /// instead.

    should_bootstrap: BootstrapBehavior,

    /// Shared boolean for whether we're currently in "dormant mode" or not.

    //

    // The sent value is `Option`, so that `None` is sent when the sender, here,

    // is dropped,.  That shuts down the monitoring task.

    dormant: Arc<Mutex<DropNotifyWatchSender<Option<DormantMode>>>>,

    /// The path resolver given to us by a [`TorClientConfig`].

    ///

    /// We must not add our own variables to it since `TorClientConfig` uses it to perform its own

    /// path expansions. If we added our own variables, it would introduce an inconsistency where

    /// paths expanded by the `TorClientConfig` would expand differently than when expanded by us.

    // This is an Arc so that we can make cheap clones of it.

    path_resolver: Arc<tor_config_path::CfgPathResolver>,

}

/// A Tor client that is not runnable.

///

/// Can be used to access the state that would be used by a running [`TorClient`].

///

/// An `InertTorClient` never connects to the network.

#[derive(Clone)]

pub struct InertTorClient {

    /// The key manager.

    ///

    /// This is used for retrieving private keys, certificates, and other sensitive data (for

    /// example, for retrieving the keys necessary for connecting to hidden services that are

    /// running in restricted discovery mode).

    ///

    /// If this crate is compiled _with_ the `keymgr` feature, [`TorClient`] will use a functional

    /// key manager implementation.

    ///

    /// If this crate is compiled _without_ the `keymgr` feature, then [`TorClient`] will use a

    /// no-op key manager implementation instead.

    ///

    /// See the [`KeyMgr`] documentation for more details.

    keymgr: Option<Arc<KeyMgr>>,

}

impl InertTorClient {

    /// Create an `InertTorClient` from a `TorClientConfig`.

    /// Create a [`KeyMgr`] using the specified configuration.

    ///

    /// Returns `Ok(None)` if keystore use is disabled.

            Some(ArtiKeystoreKind::Native) => {

                // Should only log fs paths at debug level or lower,

                // unless they're part of a diagnostic message.

            }

            #[cfg(feature = "ephemeral-keystore")]

            Some(ArtiKeystoreKind::Ephemeral) => {

                // TODO: make the keystore ID somehow configurable

            }

            None => {

            }

        };

        #[cfg(feature = "ctor-keystore")]

                // TODO: these nicknames should be cross-checked with configured

                // svc nicknames as part of config validation!!!

        }

        #[cfg(feature = "ctor-keystore")]

        }

    /// Generate a service discovery keypair for connecting to a hidden service running in

    /// "restricted discovery" mode.

    ///

    /// See [`TorClient::generate_service_discovery_key`].

    //

    // TODO: decide whether this should use get_or_generate before making it

    // non-experimental

    #[cfg(all(

        feature = "onion-service-client",

        feature = "experimental-api",

        feature = "keymgr"

    ))]

    #[cfg_attr(

        docsrs,

        doc(cfg(all(

            feature = "onion-service-client",

            feature = "experimental-api",

            feature = "keymgr"

        )))

    )]

    /// Rotate the service discovery keypair for connecting to a hidden service running in

    /// "restricted discovery" mode.

    ///

    /// See [`TorClient::rotate_service_discovery_key`].

    #[cfg(all(

        feature = "onion-service-client",

        feature = "experimental-api",

        feature = "keymgr"

    ))]

    /// Insert a service discovery secret key for connecting to a hidden service running in

    /// "restricted discovery" mode

    ///

    /// See [`TorClient::insert_service_discovery_key`].

    #[cfg(all(

        feature = "onion-service-client",

        feature = "experimental-api",

        feature = "keymgr"

    ))]

    #[cfg_attr(

        docsrs,

        doc(cfg(all(

            feature = "onion-service-client",

            feature = "experimental-api",

            feature = "keymgr"

        )))

    )]

    /// Return the service discovery public key for the service with the specified `hsid`.

    ///

    /// See [`TorClient::get_service_discovery_key`].

    #[cfg(all(feature = "onion-service-client", feature = "experimental-api"))]

    #[cfg_attr(

        docsrs,

        doc(cfg(all(feature = "onion-service-client", feature = "experimental-api")))

    )]

    /// Removes the service discovery keypair for the service with the specified `hsid`.

    ///

    /// See [`TorClient::remove_service_discovery_key`].

    #[cfg(all(

        feature = "onion-service-client",

        feature = "experimental-api",

        feature = "keymgr"

    ))]

    #[cfg_attr(

        docsrs,

        doc(cfg(all(

            feature = "onion-service-client",

            feature = "experimental-api",

            feature = "keymgr"

        )))

    )]

        }

    /// Getter for keymgr.

    #[cfg(feature = "onion-service-cli-extra")]

    /// Create (but do not launch) a new

    /// [`OnionService`](tor_hsservice::OnionService)

    /// using the given configuration.

    ///

    /// See [`TorClient::create_onion_service`].

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

    #[instrument(skip_all, level = "trace")]

}

/// Preferences for whether a [`TorClient`] should bootstrap on its own or not.

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

#[non_exhaustive]

pub enum BootstrapBehavior {

    /// Bootstrap the client automatically when requests are made that require the client to be

    /// bootstrapped.

    #[default]

    OnDemand,

    /// Make no attempts to automatically bootstrap. [`TorClient::bootstrap`] must be manually

    /// invoked in order for the [`TorClient`] to become useful.

    ///

    /// Attempts to use the client (e.g. by creating connections or resolving hosts over the Tor

    /// network) before calling [`bootstrap`](TorClient::bootstrap) will fail, and

    /// return an error that has kind [`ErrorKind::BootstrapRequired`](crate::ErrorKind::BootstrapRequired).

    Manual,

}

/// What level of sleep to put a Tor client into.

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

#[non_exhaustive]

pub enum DormantMode {

    /// The client functions as normal, and background tasks run periodically.

    #[default]

    Normal,

    /// Background tasks are suspended, conserving CPU usage. Attempts to use the client will

    /// wake it back up again.

    Soft,

}

/// Preferences for how to route a stream over the Tor network.

#[derive(Debug, Default, Clone)]

pub struct StreamPrefs {

    /// What kind of IPv6/IPv4 we'd prefer, and how strongly.

    ip_ver_pref: IpVersionPreference,

    /// How should we isolate connection(s)?

    isolation: StreamIsolationPreference,

    /// Whether to return the stream optimistically.

    optimistic_stream: bool,

    // TODO GEOIP Ideally this would be unconditional, with CountryCode maybe being Void

    // This probably applies in many other places, so probably:   git grep 'cfg.*geoip'

    // and consider each one with a view to making it unconditional.  Background:

    //   https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/1537#note_2935256

    //   https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/1537#note_2942214

    #[cfg(feature = "geoip")]

    /// A country to restrict the exit relay's location to.

    country_code: Option<CountryCode>,

    /// Whether to try to make connections to onion services.

    ///

    /// `Auto` means to use the client configuration.

    #[cfg(feature = "onion-service-client")]

    pub(crate) connect_to_onion_services: BoolOrAuto,

}

/// Record of how we are isolating connections

#[derive(Debug, Default, Clone)]

enum StreamIsolationPreference {

    /// No additional isolation

    #[default]

    None,

    /// Isolation parameter to use for connections

    Explicit(Box<dyn Isolation>),

    /// Isolate every connection!

    EveryStream,

}

impl From<DormantMode> for tor_chanmgr::Dormancy {

        }

}

#[cfg(feature = "bridge-client")]

impl From<DormantMode> for tor_dirmgr::bridgedesc::Dormancy {

        }

}

impl StreamPrefs {

    /// Construct a new StreamPrefs.

    /// Indicate that a stream may be made over IPv4 or IPv6, but that

    /// we'd prefer IPv6.

    /// Indicate that a stream may only be made over IPv6.

    ///

    /// When this option is set, we will only pick exit relays that

    /// support IPv6, and we will tell them to only give us IPv6

    /// connections.

    /// Indicate that a stream may be made over IPv4 or IPv6, but that

    /// we'd prefer IPv4.

    ///

    /// This is the default.

    /// Indicate that a stream may only be made over IPv4.

    ///

    /// When this option is set, we will only pick exit relays that

    /// support IPv4, and we will tell them to only give us IPv4

    /// connections.

    /// Indicate that a stream should appear to come from the given country.

    ///

    /// When this option is set, we will only pick exit relays that

    /// have an IP address that matches the country in our GeoIP database.

    #[cfg(feature = "geoip")]

    /// Indicate that we don't care which country a stream appears to come from.

    ///

    /// This is available even in the case where GeoIP support is compiled out,

    /// to make things easier.

        #[cfg(feature = "geoip")]

    /// Indicate that the stream should be opened "optimistically".

    ///

    /// By default, streams are not "optimistic". When you call

    /// [`TorClient::connect()`], it won't give you a stream until the

    /// exit node has confirmed that it has successfully opened a

    /// connection to your target address.  It's safer to wait in this

    /// way, but it is slower: it takes an entire round trip to get

    /// your confirmation.

    ///

    /// If a stream _is_ configured to be "optimistic", on the other

    /// hand, then `TorClient::connect()` will return the stream

    /// immediately, without waiting for an answer from the exit.  You

    /// can start sending data on the stream right away, though of

    /// course this data will be lost if the connection is not

    /// actually successful.

    /// Return true if this stream has been configured as "optimistic".

    ///

    /// See [`StreamPrefs::optimistic`] for more info.

    /// Indicate whether connection to a hidden service (`.onion` service) should be allowed

    ///

    /// If `Explicit(false)`, attempts to connect to Onion Services will be forced to fail with

    /// an error of kind [`InvalidStreamTarget`](crate::ErrorKind::InvalidStreamTarget).

    ///

    /// If `Explicit(true)`, Onion Service connections are enabled.

    ///

    /// If `Auto`, the behaviour depends on the `address_filter.allow_onion_addrs`

    /// configuration option, which is in turn enabled by default.

    #[cfg(feature = "onion-service-client")]

    /// Return a TargetPort to describe what kind of exit policy our

    /// target circuit needs to support.

        }

    /// Return a new StreamParameters based on this configuration.

    /// Indicate that connections with these preferences should have their own isolation group

    ///

    /// This is a convenience method which creates a fresh [`IsolationToken`]

    /// and sets it for these preferences.

    ///

    /// This connection preference is orthogonal to isolation established by

    /// [`TorClient::isolated_client`].  Connections made with an `isolated_client` (and its

    /// clones) will not share circuits with the original client, even if the same

    /// `isolation` is specified via the `ConnectionPrefs` in force.

    /// Indicate which other connections might use the same circuit

    /// as this one.

    ///

    /// By default all connections made on all clones of a `TorClient` may share connections.

    /// Connections made with a particular `isolation` may share circuits with each other.

    ///

    /// This connection preference is orthogonal to isolation established by

    /// [`TorClient::isolated_client`].  Connections made with an `isolated_client` (and its

    /// clones) will not share circuits with the original client, even if the same

    /// `isolation` is specified via the `ConnectionPrefs` in force.

    {

    /// Indicate that no connection should share a circuit with any other.

    ///

    /// **Use with care:** This is likely to have poor performance, and imposes a much greater load

    /// on the Tor network.  Use this option only to make small numbers of connections each of

    /// which needs to be isolated from all other connections.

    ///

    /// (Don't just use this as a "get more privacy!!" method: the circuits

    /// that it put connections on will have no more privacy than any other

    /// circuits.  The only benefit is that these circuits will not be shared

    /// by multiple streams.)

    ///

    /// This can be undone by calling `set_isolation` or `new_isolation_group` on these

    /// preferences.

    /// Return an [`Isolation`] which separates according to these `StreamPrefs` (only)

    ///

    /// This describes which connections or operations might use

    /// the same circuit(s) as this one.

    ///

    /// Since this doesn't have access to the `TorClient`,

    /// it doesn't separate streams which ought to be separated because of

    /// the way their `TorClient`s are isolated.

    /// For that, use [`TorClient::isolation`].

        use StreamIsolationPreference as SIP;

        }

    // TODO: Add some way to be IPFlexible, and require exit to support both.

}

#[cfg(all(

    any(feature = "native-tls", feature = "rustls"),

    any(feature = "async-std", feature = "tokio")

))]

impl TorClient<PreferredRuntime> {

    /// Bootstrap a connection to the Tor network, using the provided `config`.

    ///

    /// Returns a client once there is enough directory material to

    /// connect safely over the Tor network.

    ///

    /// Consider using [`TorClient::builder`] for more fine-grained control.

    ///

    /// # Panics

    ///

    /// If Tokio is being used (the default), panics if created outside the context of a currently

    /// running Tokio runtime. See the documentation for [`PreferredRuntime::current`] for

    /// more information.

    ///

    /// If using `async-std`, either take care to ensure Arti is not compiled with Tokio support,

    /// or manually create an `async-std` runtime using [`tor_rtcompat`] and use it with

    /// [`TorClient::with_runtime`].

    ///

    /// # Do not fork

    ///

    /// The process [**may not fork**](tor_rtcompat#do-not-fork)

    /// (except, very carefully, before exec)

    /// after calling this function, because it creates a [`PreferredRuntime`].

    /// Return a new builder for creating TorClient objects.

    ///

    /// If you want to make a [`TorClient`] synchronously, this is what you want; call

    /// `TorClientBuilder::create_unbootstrapped` on the returned builder.

    ///

    /// # Panics

    ///

    /// If Tokio is being used (the default), panics if created outside the context of a currently

    /// running Tokio runtime. See the documentation for `tokio::runtime::Handle::current` for

    /// more information.

    ///

    /// If using `async-std`, either take care to ensure Arti is not compiled with Tokio support,

    /// or manually create an `async-std` runtime using [`tor_rtcompat`] and use it with

    /// [`TorClient::with_runtime`].

    ///

    /// # Do not fork

    ///

    /// The process [**may not fork**](tor_rtcompat#do-not-fork)

    /// (except, very carefully, before exec)

    /// after calling this function, because it creates a [`PreferredRuntime`].

}

impl<R: Runtime> TorClient<R> {

    /// Return a new builder for creating TorClient objects, with a custom provided [`Runtime`].

    ///

    /// See the [`tor_rtcompat`] crate for more information on custom runtimes.

    /// Implementation of `create_unbootstrapped`, split out in order to avoid manually specifying

    /// double error conversions.

    #[instrument(skip_all, level = "trace")]

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

        };

        // Try to take state ownership early, so we'll know if we have it.

        // Note that this `try_lock()` may return `Ok` even if we can't acquire the lock.

        // (At this point we don't yet care if we have it.)

        ));

        #[cfg(feature = "pt-client")]

        };

            )

        );

            )

        #[allow(clippy::print_stderr)]

            // TODO #1932: It would be nice to have a cleaner shutdown mechanism here,

            // but that will take some work.

                use tor_error::ErrorReport as _;

                // We already logged this error, but let's tell stderr too.

                );

                // Give the tracing module a while to flush everything, since it has no built-in

                // flush function.

        );

        #[cfg(feature = "bridge-client")]

        #[cfg(any(feature = "onion-service-client", feature = "onion-service-service"))]

        };

        #[cfg(feature = "onion-service-client")]

            // Prompt the hs connector to do its data housekeeping when we get a new consensus.

            // That's a time we're doing a bunch of thinking anyway, and it's not very frequent.

                }

        };

                #[cfg(feature = "bridge-client")]

            ))

            ))

    /// Bootstrap a connection to the Tor network, with a client created by `create_unbootstrapped`.

    ///

    /// Since cloned copies of a `TorClient` share internal state, you can bootstrap a client by

    /// cloning it and running this function in a background task (or similar). This function

    /// only needs to be called on one client in order to bootstrap all of its clones.

    ///

    /// Returns once there is enough directory material to connect safely over the Tor network.

    /// If the client or one of its clones has already been bootstrapped, returns immediately with

    /// success. If a bootstrap is in progress, waits for it to finish, then retries it if it

    /// failed (returning success if it succeeded).

    ///

    /// Bootstrap progress can be tracked by listening to the event receiver returned by

    /// [`bootstrap_events`](TorClient::bootstrap_events).

    ///

    /// # Failures

    ///

    /// If the bootstrapping process fails, returns an error. This function can safely be called

    /// again later to attempt to bootstrap another time.

    #[instrument(skip_all, level = "trace")]

        self.bootstrap_inner().await.map_err(ErrorDetail::into)

    /// Implementation of `bootstrap`, split out in order to avoid manually specifying

    /// double error conversions.

        // Make sure we have a bridge descriptor manager, which is active iff required

        #[cfg(feature = "bridge-client")]

        {

                // If ^ that fails, we drop the BridgeDescMgr again.  It may do some

                // work but will hopefully eventually quit.

        }

        // Wait for an existing bootstrap attempt to finish first.

        //

        // This is a futures::lock::Mutex, so it's okay to await while we hold it.

        {

        } else {

            );

        }

        // If we fail to bootstrap (i.e. we return before the disarm() point below), attempt to

        // unlock the state files.

        // Since we succeeded, disarm the unlock guard.

    /// ## For `BootstrapBehavior::OnDemand` clients

    ///

    /// Initiate a bootstrap by calling `bootstrap` (which is idempotent, so attempts to

    /// bootstrap twice will just do nothing).

    ///

    /// ## For `BootstrapBehavior::Manual` clients

    ///

    /// Check whether a bootstrap is in progress; if one is, wait until it finishes

    /// and then return. (Otherwise, return immediately.)

    #[instrument(skip_all, level = "trace")]

            BootstrapBehavior::OnDemand => {

                self.bootstrap_inner().await?;

            }

            BootstrapBehavior::Manual => {

                // Grab the lock, and immediately release it.  That will ensure that nobody else is trying to bootstrap.

                self.bootstrap_in_progress.lock().await;

            }

        }

        self.dormant

            .lock()

                Ok::<_, Bug>(Some({

                    }

                }))

        Ok(())

    /// Change the configuration of this TorClient to `new_config`.

    ///

    /// The `how` describes whether to perform an all-or-nothing

    /// reconfiguration: either all of the configuration changes will be

    /// applied, or none will. If you have disabled all-or-nothing changes, then

    /// only fatal errors will be reported in this function's return value.

    ///

    /// This function applies its changes to **all** TorClient instances derived

    /// from the same call to `TorClient::create_*`: even ones whose circuits

    /// are isolated from this handle.

    ///

    /// # Limitations

    ///

    /// Although most options are reconfigurable, there are some whose values

    /// can't be changed on an a running TorClient.  Those options (or their

    /// sections) are explicitly documented not to be changeable.

    /// NOTE: Currently, not all of these non-reconfigurable options are

    /// documented. See [arti#1721][arti-1721].

    ///

    /// [arti-1721]: https://gitlab.torproject.org/tpo/core/arti/-/issues/1721

    ///

    /// Changing some options do not take effect immediately on all open streams

    /// and circuits, but rather affect only future streams and circuits.  Those

    /// are also explicitly documented.

    #[instrument(skip_all, level = "trace")]

        // We need to hold this lock while we're reconfiguring the client: even

        // though the individual fields have their own synchronization, we can't

        // safely let two threads change them at once.  If we did, then we'd

        // introduce time-of-check/time-of-use bugs in checking our configuration,

        // deciding how to change it, then applying the changes.

            tor_config::Reconfigure::AllOrNothing => {

                // We have to check before we make any changes.

            }

        }

        // Actually reconfigure

    /// This is split out from `reconfigure` so we can do the all-or-nothing

    /// check without recursion. the caller to this method must hold the

    /// `reconfigure_lock`.

    #[instrument(level = "trace", skip_all)]

        // We ignore 'new_config.path_resolver' here since CfgPathResolver does not impl PartialEq

        // and we have no way to compare them, but this field is explicitly documented as being

        // non-reconfigurable anyways.

        #[cfg(any(feature = "onion-service-client", feature = "onion-service-service"))]

        #[cfg(feature = "pt-client")]

    /// Return a new isolated `TorClient` handle.

    ///

    /// The two `TorClient`s will share internal state and configuration, but

    /// their streams will never share circuits with one another.

    ///