//! Types for building circuits, or otherwise acting as a "client".

use std::sync::Arc;

use anyhow::Context;

use tor_chanmgr::ChanMgr;

use tor_circmgr::{CircMgr, CircMgrConfig};

use tor_dirmgr::{DirMgr, DirMgrConfig, DirMgrStore, DirPlugin, DirProvider};

use tor_guardmgr::{GuardMgr, GuardMgrConfig};

use tor_persist::FsStateMgr;

use tor_rtcompat::Runtime;

use tor_rtcompat::scheduler::TaskHandle;

/// A "client" used by relays to construct circuits. For example a relay needs to build

/// bandwidth-testing circuits, reachability-testing circuits, and possibly in the future anonymous

/// circuits.

///

/// The idea here is that this [`RelayClient`] will encapsulate everything needed for building

/// circuits. So the relay itself doesn't need to worry about a channel manager, guard manager, etc.

/// Instead we provide methods here for building whatever circuits the relay may need, and with

/// whatever properties the relay needs.

pub(crate) struct RelayClient<R: Runtime> {

    /// The provided runtime.

    runtime: R,

    /// The provided state manager.

    state_mgr: FsStateMgr,

    /// Channel manager, used by circuits etc.

    #[expect(unused)] // TODO RELAY remove

    chanmgr: Arc<ChanMgr<R>>,

    /// Guard manager.

    #[expect(unused)] // TODO RELAY remove

    guardmgr: GuardMgr<R>,

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

    /// them on-demand.

    circmgr: Arc<CircMgr<R>>,

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

    dirmgr: Arc<dyn DirProvider>,

    /// A dirmgr-derived plugin for a directory mirror.

    ///

    /// TODO: This has nothing to do with the client,

    /// but we need it temporarily until the directory mirror is implemented.

    /// We should remove this later.

    dirmgr_plugin: DirPlugin,

}

impl<R: Runtime> RelayClient<R> {

    /// Create a new [`RelayClient`].

    ///

    /// You must call [`RelayClient::launch_background_tasks()`] before using.

        // TODO: We probably don't want a guard manager for relays,

        // unless we plan to build anonymous circuits.

        // See https://gitlab.torproject.org/tpo/core/arti/-/issues/1737.

        // If we do want a guard manager and anonymous circuits,

        // we should think more about whether our anonymous circuits can be differentiated from

        // other circuits, and make sure that we're not closing channels for "client reasons" as

        // these channels will also be used by the relay for relaying Tor user traffic.

        // See https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/3552#note_3313591.

        // TODO: We might not want a circuit manager for relays,

        // but we will probably want its path construction logic.

        // We need to be able to build circuits for reachability testing and bandwidth measurement.

            )

        );

        // TODO: We want to use tor-dirserver as a `NetDirProvider` in the future if possible to

        // avoid having two document downloaders, and so that we can download documents over direct

        // TCP connections rather than over circuits.

            )

        );

        // Plugin for the relay's directory mirror.

    /// Launch background tasks for any of the client's submodules.

    ///

    /// The background tasks will stop when the returned [`TaskHandle`]s are dropped.

    /// Bootstrap this client by ensuring we have directory documents downloaded.

    ///

    /// TODO: We want to use tor-dirserver as a `NetDirProvider` in the future, so hopefully we won't

    /// need this `bootstrap()` method as directory downloads will be performed elsewhere.

    /// Get the client's [`DirProvider`].

    /// Temporary. See [`RelayClient::dirmgr_plugin`].

}