//! 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, StreamTimeoutConfig, TorClientConfig};

use crate::status::BootstrapStatus;

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::{BoolOrAuto, 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};

use tor_persist::StateMgr;

#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]

use tor_persist::TestingStateMgr;

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_hsclient::{HsClientConnector, HsClientDescEncKeypairSpecifier, HsClientSecretKeysBuilder},

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

    tor_keymgr::CTorClientKeystore,

    tor_netdir::DirEvent,

};

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

use {tor_keymgr::CTorServiceKeystore, tor_persist::state_dir::StateDirectory};

#[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;

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, warn};

#[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]

use tor_persist::FsStateMgr as UsingStateMgr;

// TODO wasm: This is not the right choice, but at least it compiles.

#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]

use tor_persist::TestingStateMgr as UsingStateMgr;

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

///

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

/// circuits, and make connections for you.

///

/// # 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.

#[cfg_attr(

    feature = "rpc",

    derive(Deftly),

    derive_deftly(Object),

    deftly(rpc(expose_outside_of_session))

)]

pub struct TorClient<R: Runtime> {

    /// 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,

    /// Inner structure respresenting all components shared across different

    /// TorClients.

    client: Arc<ClientShared<R>>,

}

/// Shared pieces of a `TorClient`, used to implement client functionality.

///

/// In the future, we might choose to expose this along with APIs.

struct ClientShared<R: Runtime> {

    /// Asynchronous runtime object.

    runtime: R,

    /// Inner typestate object to represent the parts of the ClientShared that may be absent

    /// depending on whether we are running.

    inner: Mutex<Inner<R>>,

    /// Memory quota tracker

    memquota: Arc<MemoryQuotaTracker>,

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

    ///

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

    inert_client: InertTorClient,

    /// 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: UsingStateMgr,

    /// Directory manager persistent storage.

    dirmgr_store: DirMgrStore<R>,

    /// Client address configuration

    addrcfg: MutCfg<ClientAddrConfig>,

    /// Client DNS configuration

    timeoutcfg: MutCfg<StreamTimeoutConfig>,

    /// 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: AsyncMutex<()>,

    /// Sender used to update changes in our bootstrap settings.

    bootstrap_setting_sender: Mutex<postage::watch::Sender<BootstrapSetting>>,

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

    /// bootstrapping.

    ///

    /// If this is [`BootstrapBehavior::OnDemand`], we wait for the client to bootstrap

    /// (launching a bootstrap if necessary) before performing any operation that needs circuits.

    /// If this is [`BootstrapBehavior::Manual`], we give an error if we are told to do

    /// something that needs circuits and we have not been told to bootstrap.

    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: 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.

    path_resolver: Arc<tor_config_path::CfgPathResolver>,

}

/// A typestate object holding the parts of the client state that we may or may not have

/// depending on whether we are running.

enum Inner<R: Runtime> {

    /// The client is not constructed.

    ///

    /// In this state, the client won't try to connect to the network.

    NotConstructed(Box<NotConstructedInner<R>>),

    /// The client is either bootstrapped or trying to bootstrap.

    Running(Arc<RunningInner<R>>),

    /// The client has failed in a non-recoverable way.

    Poisoned(Box<ErrorDetail>),

}

/// Information stored by a never-bootstrapped [`TorClient`],

/// used to eventually construct a [`RunningInner`] and bootstrap.

struct NotConstructedInner<R: Runtime> {

    /// The client's configuration.

    config: TorClientConfig,

    /// A receiver to give to various tasks that want to monitor our dormant status.

    dormant_recv: postage::watch::Receiver<Option<DormantMode>>,

    /// A sender used to produce updates about our bootstrapping status.

    ///

    /// NOTE: The fact that this type is not Clone is the only reason

    /// that [`RunningInner::new`] needs to take NotConstructedInner by value.

    /// With some redesign we could simplify this, and do away with [`Inner::Poisoned`].

    status_sender: postage::watch::Sender<BootstrapStatus>,

    /// A receiver used to inform the bootstrap status processor about changes in our settings.

    bootstrap_setting_receiver: postage::watch::Receiver<BootstrapSetting>,

    /// A (possibly user-provided) builder used to construct our NetDirProvider.

    dirmgr_builder: Arc<dyn crate::builder::DirProviderBuilder<R>>,

    /// A (possibly user-provided) set of in-process extensions for our NetDirProvider.

    dirmgr_extensions: tor_dirmgr::config::DirMgrExtensions,

}

/// Data structures for a "running" client.

///

/// A running client is one that is either bootstrapped, or potentially trying to bootstrap.

///

/// All structures that potentially interact with the network belong here.

///

/// We defer the creation of this structure and its members until bootstrap time,

/// to make sure that before we are bootstrapping, nothing will try to connect to the network

/// or launch expensive background tasks.

struct RunningInner<R: Runtime> {

    /// 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 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>>,

    /// Guard manager

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

    guardmgr: GuardMgr<R>,

}

/// 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 = "onion-service-service")]

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

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

        }

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

        }

    /// 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,

}

/// A representation of whether a [`TorClient`] is allowed to bootstrap, and whether it

/// has begun to do so.

#[derive(Debug, Clone, Copy)]

pub(crate) struct BootstrapSetting {

    /// The configured [`BootstrapBehavior`] for the `TorClient`.

    behavior: BootstrapBehavior,

    /// If true, we have a [`RunningInner`] in the `TorClient`,

    /// indicating that we are trying to bootstrap it.

    running_inner_is_present: bool,

}

impl Default for BootstrapSetting {

}

impl BootstrapSetting {

    /// Return true if this [`BootstrapSetting`]

    /// indicates that the client is not trying to bootstrap,

    /// and will not try until it is told explicitly to do so.

        use BootstrapBehavior::*;

        }

}

/// 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,

    /// Whether to try to make connections to local addresses.

    ///

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

    pub(crate) connect_to_local_addrs: BoolOrAuto,

    /// Whether to accept and return local addresses in anonymously retrieved DNS answers.

    ///

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

    pub(crate) resolve_local_addrs: 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")]

    /// Indicate whether connection to a local address should be allowed

    ///

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

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

    ///

    /// If `Explicit(true)`, connections to local addresses are allowed.

    ///

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

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

    /// Indicate whether to accept and return local addresses in anonymously retrieved DNS answers.

    ///

    /// If `Explicit(false)`, we will filter out the local addresses

    /// from anonymously retrieved DNS answers.

    ///

    /// If `Explicit(true)`, we will not filter out the local addresses

    /// from anonymously retrieved DNS answers.

    ///

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

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

    /// 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`

    ///  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 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`

    /// 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.)

    /// Construct a state manager from the client configuration.

        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]

        {

            use tor_persist::FsStateMgr;

        }

        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]

        {

            unimplemented!()

        }

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

    ///

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

    /// If the client 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.client

            .bootstrap_inner()

            .await

            .map_err(ErrorDetail::into)

}

impl<R: Runtime> NotConstructedInner<R> {

    /// Replace the configuration for this unconstructed client.

    ///

    /// Since most of the client's internals are not yet constructed,

    /// we can still replace nearly all of the items.

        // We _do_ have to check the cache_dir, since we can't and won't change that

        // while we're running.

        // (We already checked the state_dir in ClientShared::reconfigure_inner.)

}

impl<R: Runtime> RunningInner<R> {

    /// Construct a new [`RunningInner`] and launch its associated tasks.

        let NotConstructedInner {

            )

        );

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

        };

            )

        );

        };

        );

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

        // TODO: We can just construct this.

        #[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.

                }

        };

        // TODO: It might be a good idea to check this earlier, in `create_impl`,

        // when we have only the DirMgrStore.

        // But if we do that we need to add a method to DirMgrStore

        // to look at the protocol recommentations.

        #[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.

                    "Shutting down because of unsupported software version.\nError was:\n{}",

                );

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

                // flush function.

            ))