//! Types for conveniently constructing TorClients.

#![allow(missing_docs, clippy::missing_docs_in_private_items)]

use crate::{

    err::ErrorDetail, BootstrapBehavior, InertTorClient, Result, TorClient, TorClientConfig,

};

use std::{

    result::Result as StdResult,

    sync::Arc,

    time::{Duration, Instant},

};

use tor_dirmgr::{DirMgrConfig, DirMgrStore};

use tor_error::{ErrorKind, HasKind as _};

use tor_rtcompat::Runtime;

/// An object that knows how to construct some kind of DirProvider.

///

/// Note that this type is only actually exposed when the `experimental-api`

/// feature is enabled.

#[allow(unreachable_pub)]

#[cfg_attr(docsrs, doc(cfg(feature = "experimental-api")))]

pub trait DirProviderBuilder<R: Runtime>: Send + Sync {

    fn build(

        &self,

        runtime: R,

        store: DirMgrStore<R>,

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

        config: DirMgrConfig,

    ) -> Result<Arc<dyn tor_dirmgr::DirProvider + 'static>>;

}

/// A DirProviderBuilder that constructs a regular DirMgr.

#[derive(Clone, Debug)]

struct DirMgrBuilder {}

impl<R: Runtime> DirProviderBuilder<R> for DirMgrBuilder {

}

/// An object for constructing a [`TorClient`].

///

/// Returned by [`TorClient::builder()`].

#[derive(Clone)]

#[must_use]

pub struct TorClientBuilder<R: Runtime> {

    /// The runtime for the client to use

    runtime: R,

    /// The client's configuration.

    config: TorClientConfig,

    /// How the client should behave when it is asked to do something on the Tor

    /// network before `bootstrap()` is called.

    bootstrap_behavior: BootstrapBehavior,

    /// Optional object to construct a DirProvider.

    ///

    /// Wrapped in an Arc so that we don't need to force DirProviderBuilder to

    /// implement Clone.

    dirmgr_builder: Arc<dyn DirProviderBuilder<R>>,

    /// If present, an amount of time to wait when trying to acquire the filesystem locks for our

    /// storage.

    local_resource_timeout: Option<Duration>,

    /// Optional directory filter to install for testing purposes.

    ///

    /// Only available when `arti-client` is built with the `dirfilter` and `experimental-api` features.

    #[cfg(feature = "dirfilter")]

    dirfilter: tor_dirmgr::filter::FilterConfig,

}

/// Longest allowable duration to wait for local resources to be available

/// when creating a TorClient.

///

/// This value may change in future versions of Arti.

/// It is an error to configure

/// a [`local_resource_timeout`](TorClientBuilder)

/// with a larger value than this.

///

/// (Reducing this value would count as a breaking change.)

pub const MAX_LOCAL_RESOURCE_TIMEOUT: Duration = Duration::new(5, 0);

impl<R: Runtime> TorClientBuilder<R> {

    /// Construct a new TorClientBuilder with the given runtime.

    /// Set the configuration for the `TorClient` under construction.

    ///

    /// If not called, then a compiled-in default configuration will be used.

    /// Set the bootstrap behavior for the `TorClient` under construction.

    ///

    /// If not called, then the default ([`BootstrapBehavior::OnDemand`]) will

    /// be used.

    /// Set a timeout that we should allow when trying to acquire our local resources

    /// (including lock files.)

    ///

    /// If no timeout is set, we wait for a short while (currently 500 msec) when invoked with

    /// [`create_bootstrapped`](Self::create_bootstrapped) or

    /// [`create_unbootstrapped_async`](Self::create_unbootstrapped_async),

    /// and we do not wait at all if invoked with

    /// [`create_unbootstrapped`](Self::create_unbootstrapped).

    ///

    /// (This difference in default behavior is meant to avoid unintentional blocking.

    /// If you call this method, subsequent calls to `create_bootstrapped` may block

    /// the current thread.)

    ///

    /// The provided timeout value may not be larger than [`MAX_LOCAL_RESOURCE_TIMEOUT`].

    /// Override the default function used to construct the directory provider.

    ///

    /// Only available when compiled with the `experimental-api` feature: this

    /// code is unstable.

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

    /// Install a [`DirFilter`](tor_dirmgr::filter::DirFilter) to

    ///

    /// Only available when compiled with the `dirfilter` feature: this code

    /// is unstable and not recommended for production use.

    #[cfg(feature = "dirfilter")]

    /// Create a `TorClient` from this builder, without automatically launching

    /// the bootstrap process.

    ///

    /// If you have left the default [`BootstrapBehavior`] in place, the client

    /// will bootstrap itself as soon any attempt is made to use it.  You can

    /// also bootstrap the client yourself by running its

    /// [`bootstrap()`](TorClient::bootstrap) method.

    ///

    /// If you have replaced the default behavior with [`BootstrapBehavior::Manual`],

    /// any attempts to use the client will fail with an error of kind

    /// [`ErrorKind::BootstrapRequired`],

    /// until you have called [`TorClient::bootstrap`] yourself.

    /// This option is useful if you wish to have control over the bootstrap

    /// process (for example, you might wish to avoid initiating network

    /// connections until explicit user confirmation is given).

    ///

    /// If a [local_resource_timeout](Self::local_resource_timeout) has been set, this function may

    /// block the current thread.

    /// Use [`create_unbootstrapped_async`](Self::create_unbootstrapped_async)

    /// if that is not what you want.

        loop {

            }

        }

    /// Like create_unbootstrapped, but does not block the thread while trying to acquire the lock.

    ///

    /// If no [`local_resource_timeout`](Self::local_resource_timeout) has been set, this function may

    /// delay a short while (currently 500 msec) for local resources (such as lock files) to be available.

    /// Set `local_resource_timeout` to 0 if you do not want this behavior.

        // TODO: This code is largely duplicated from create_unbootstrapped above.  It might be good

        // to have a single shared implementation to handle both the sync and async cases, but I am

        // concerned that doing so would just add a lot of complexity.

            {

                }

            }

        }

    /// Helper for create_bootstrapped and create_bootstrapped_async.

    ///

    /// Does not retry on `LocalResourceAlreadyInUse`; instead, returns a time that we should wait,

    /// and log a message if `first_attempt` is true.

                    // no time remaining; return the error that we got.

                } else {

                        );

                    // We'll retry at least once.

                    // TODO: Maybe use a smarter backoff strategy here?

                }

            }

            // We either succeeded, or failed for a reason other than LocalResourceAlreadyInUse

        }

    /// Create a TorClient from this builder, and try to bootstrap it.

    /// Return the local_resource_timeout, or `dflt` if none is defined.

    ///

    /// Give an error if the value is above MAX_LOCAL_RESOURCE_TIMEOUT

    /// Create an `InertTorClient` from this builder, without launching

    /// the bootstrap process, or connecting to the network.

    ///

    /// It is currently unspecified whether constructing an `InertTorClient`

    /// will hold any locks that prevent opening a `TorClient` with the same

    /// directories.

    //

    // TODO(#1576): reach a decision here.

    #[allow(clippy::unnecessary_wraps)]

}

#[cfg(test)]

mod test {

    use tor_rtcompat::PreferredRuntime;

    use super::*;

    fn must_be_send_and_sync<S: Send + Sync>() {}

    #[test]

    fn builder_is_send() {

        must_be_send_and_sync::<TorClientBuilder<PreferredRuntime>>();

    }

}