#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]

#![doc = include_str!("../README.md")]

// @@ begin lint list maintained by maint/add_warning @@

#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)

#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)

#![warn(missing_docs)]

#![warn(noop_method_call)]

#![warn(unreachable_pub)]

#![warn(clippy::all)]

#![deny(clippy::await_holding_lock)]

#![deny(clippy::cargo_common_metadata)]

#![deny(clippy::cast_lossless)]

#![deny(clippy::checked_conversions)]

#![warn(clippy::cognitive_complexity)]

#![deny(clippy::debug_assert_with_mut_call)]

#![deny(clippy::exhaustive_enums)]

#![deny(clippy::exhaustive_structs)]

#![deny(clippy::expl_impl_clone_on_copy)]

#![deny(clippy::fallible_impl_from)]

#![deny(clippy::implicit_clone)]

#![deny(clippy::large_stack_arrays)]

#![warn(clippy::manual_ok_or)]

#![deny(clippy::missing_docs_in_private_items)]

#![warn(clippy::needless_borrow)]

#![warn(clippy::needless_pass_by_value)]

#![warn(clippy::option_option)]

#![deny(clippy::print_stderr)]

#![deny(clippy::print_stdout)]

#![warn(clippy::rc_buffer)]

#![deny(clippy::ref_option_ref)]

#![warn(clippy::semicolon_if_nothing_returned)]

#![warn(clippy::trait_duplication_in_bounds)]

#![deny(clippy::unchecked_duration_subtraction)]

#![deny(clippy::unnecessary_wraps)]

#![warn(clippy::unseparated_literal_suffix)]

#![deny(clippy::unwrap_used)]

#![deny(clippy::mod_module_files)]

#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness

#![allow(clippy::uninlined_format_args)]

#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945

#![allow(clippy::result_large_err)] // temporary workaround for arti#587

#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best

#![allow(clippy::needless_lifetimes)] // See arti#1765

#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060

//! <!-- @@ end lint list maintained by maint/add_warning @@ -->

// This clippy lint produces a false positive on `use strum`, below.

// Attempting to apply the lint to just the use statement fails to suppress

// this lint and instead produces another lint about a useless clippy attribute.

#![allow(clippy::single_component_path_imports)]

pub mod authority;

mod bootstrap;

pub mod config;

mod docid;

mod docmeta;

mod err;

mod event;

mod retry;

mod shared_ref;

mod state;

mod storage;

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

pub mod bridgedesc;

#[cfg(feature = "dirfilter")]

pub mod filter;

use crate::docid::{CacheUsage, ClientRequest, DocQuery};

use crate::err::BootstrapAction;

#[cfg(not(feature = "experimental-api"))]

use crate::shared_ref::SharedMutArc;

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

pub use crate::shared_ref::SharedMutArc;

use crate::storage::{DynStore, Store};

use bootstrap::AttemptId;

use event::DirProgress;

use postage::watch;

pub use retry::{DownloadSchedule, DownloadScheduleBuilder};

use scopeguard::ScopeGuard;

use tor_circmgr::CircMgr;

use tor_dirclient::SourceInfo;

use tor_error::{info_report, into_internal, warn_report};

use tor_netdir::params::NetParameters;

use tor_netdir::{DirEvent, MdReceiver, NetDir, NetDirProvider};

use async_trait::async_trait;

use futures::{stream::BoxStream, task::SpawnExt};

use oneshot_fused_workaround as oneshot;

use tor_netdoc::doc::netstatus::ProtoStatuses;

use tor_rtcompat::scheduler::{TaskHandle, TaskSchedule};

use tor_rtcompat::Runtime;

use tracing::{debug, info, trace, warn};

use std::marker::PhantomData;

use std::sync::atomic::{AtomicBool, Ordering};

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

use std::time::Duration;

use std::{collections::HashMap, sync::Weak};

use std::{fmt::Debug, time::SystemTime};

use crate::state::{DirState, NetDirChange};

pub use authority::{Authority, AuthorityBuilder};

pub use config::{

    DirMgrConfig, DirTolerance, DirToleranceBuilder, DownloadScheduleConfig,

    DownloadScheduleConfigBuilder, NetworkConfig, NetworkConfigBuilder,

};

pub use docid::DocId;

pub use err::Error;

pub use event::{DirBlockage, DirBootstrapEvents, DirBootstrapStatus};

pub use storage::DocumentText;

pub use tor_guardmgr::fallback::{FallbackDir, FallbackDirBuilder};

pub use tor_netdir::Timeliness;

/// Re-export of `strum` crate for use by an internal macro

use strum;

/// A Result as returned by this crate.

pub type Result<T> = std::result::Result<T, Error>;

/// Storage manager used by [`DirMgr`] and

/// [`BridgeDescMgr`](bridgedesc::BridgeDescMgr)

///

/// Internally, this wraps up a sqlite database.

///

/// This is a handle, which is cheap to clone; clones share state.

#[derive(Clone)]

pub struct DirMgrStore<R: Runtime> {

    /// The actual store

    pub(crate) store: Arc<Mutex<crate::DynStore>>,

    /// Be parameterized by Runtime even though we don't use it right now

    pub(crate) runtime: PhantomData<R>,

}

impl<R: Runtime> DirMgrStore<R> {

    /// Open the storage, according to the specified configuration

}

/// Trait for DirMgr implementations

#[async_trait]

pub trait DirProvider: NetDirProvider {

    /// Try to change our configuration to `new_config`.

    ///

    /// Actual behavior will depend on the value of `how`.

    fn reconfigure(

        &self,

        new_config: &DirMgrConfig,

        how: tor_config::Reconfigure,

    ) -> std::result::Result<(), tor_config::ReconfigureError>;

    /// Bootstrap a `DirProvider` that hasn't been bootstrapped yet.

    async fn bootstrap(&self) -> Result<()>;

    /// Return a stream of [`DirBootstrapStatus`] events to tell us about changes

    /// in the latest directory's bootstrap status.

    ///

    /// Note that this stream can be lossy: the caller will not necessarily

    /// observe every event on the stream

    fn bootstrap_events(&self) -> BoxStream<'static, DirBootstrapStatus>;

    /// Return a [`TaskHandle`] that can be used to manage the download process.

}

// NOTE(eta): We can't implement this for Arc<DirMgr<R>> due to trait coherence rules, so instead

//            there's a blanket impl for Arc<T> in tor-netdir.

impl<R: Runtime> NetDirProvider for DirMgr<R> {

        use tor_netdir::Error as NetDirError;

        };

        } else {

        }

            // We have a directory, so we'd like to give it out for its

            // parameters.

            //

            // We do this even if the directory is expired, since parameters

            // don't really expire on any plausible timescale.

        } else {

            // We have no directory, so we'll give out the default parameters as

            // modified by the provided override_net_params configuration.

            //

        }

        // TODO(nickm): If we felt extremely clever, we could add a third case

        // where, if we have a pending directory with a validated consensus, we

        // give out that consensus's network parameters even if we _don't_ yet

        // have a full directory.  That's significant refactoring, though, for

        // an unclear amount of benefit.

}

#[async_trait]

impl<R: Runtime> DirProvider for Arc<DirMgr<R>> {

}

/// A directory manager to download, fetch, and cache a Tor directory.

///

/// A DirMgr can operate in three modes:

///   * In **offline** mode, it only reads from the cache, and can

///     only read once.

///   * In **read-only** mode, it reads from the cache, but checks

///     whether it can acquire an associated lock file.  If it can, then

///     it enters read-write mode.  If not, it checks the cache

///     periodically for new information.

///   * In **read-write** mode, it knows that no other process will be

///     writing to the cache, and it takes responsibility for fetching

///     data from the network and updating the directory with new

///     directory information.

pub struct DirMgr<R: Runtime> {

    /// Configuration information: where to find directories, how to

    /// validate them, and so on.

    config: tor_config::MutCfg<DirMgrConfig>,

    /// Handle to our sqlite cache.

    // TODO(nickm): I'd like to use an rwlock, but that's not feasible, since

    // rusqlite::Connection isn't Sync.

    // TODO is needed?

    store: Arc<Mutex<DynStore>>,

    /// Our latest sufficiently bootstrapped directory, if we have one.

    ///

    /// We use the RwLock so that we can give this out to a bunch of other

    /// users, and replace it once a new directory is bootstrapped.

    // TODO(eta): Eurgh! This is so many Arcs! (especially considering this

    //            gets wrapped in an Arc)

    netdir: Arc<SharedMutArc<NetDir>>,

    /// Our latest set of recommended protocols.

    protocols: Mutex<Option<(SystemTime, Arc<ProtoStatuses>)>>,

    /// A set of network parameters to hand out when we have no directory.

    default_parameters: Mutex<Arc<NetParameters>>,

    /// A publisher handle that we notify whenever the consensus changes.

    events: event::FlagPublisher<DirEvent>,

    /// A publisher handle that we notify whenever our bootstrapping status

    /// changes.

    send_status: Mutex<watch::Sender<event::DirBootstrapStatus>>,

    /// A receiver handle that gets notified whenever our bootstrapping status

    /// changes.

    ///

    /// We don't need to keep this drained, since `postage::watch` already knows

    /// to discard unread events.

    receive_status: DirBootstrapEvents,

    /// A circuit manager, if this DirMgr supports downloading.

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

    /// Our asynchronous runtime.

    runtime: R,

    /// Whether or not we're operating in offline mode.

    offline: bool,

    /// If we're not in offline mode, stores whether or not the `DirMgr` has attempted

    /// to bootstrap yet or not.

    ///

    /// This exists in order to prevent starting two concurrent bootstrap tasks.

    ///

    /// (In offline mode, this does nothing.)

    bootstrap_started: AtomicBool,

    /// A filter that gets applied to directory objects before we use them.

    #[cfg(feature = "dirfilter")]

    filter: crate::filter::FilterConfig,

    /// A task schedule that can be used if we're bootstrapping.  If this is

    /// None, then there's currently a scheduled task in progress.

    task_schedule: Mutex<Option<TaskSchedule<R>>>,

    /// A task handle that we return to anybody who needs to manage our download process.

    task_handle: TaskHandle,

}

/// The possible origins of a document.

///

/// Used (for example) to report where we got a document from if it fails to

/// parse.

#[derive(Debug, Clone)]

#[non_exhaustive]

pub enum DocSource {

    /// We loaded the document from our cache.

    LocalCache,

    /// We fetched the document from a server.

    DirServer {

        /// Information about the server we fetched the document from.

        source: Option<SourceInfo>,

    },

}

impl std::fmt::Display for DocSource {

        }

}

impl<R: Runtime> DirMgr<R> {

    /// Try to load the directory from disk, without launching any

    /// kind of update process.

    ///

    /// This function runs in **offline** mode: it will give an error

    /// if the result is not up-to-date, or not fully downloaded.

    ///

    /// In general, you shouldn't use this function in a long-running

    /// program; it's only suitable for command-line or batch tools.

    // TODO: I wish this function didn't have to be async or take a runtime.

        // TODO: add some way to return a directory that isn't up-to-date

    /// Return a current netdir, either loading it or bootstrapping it

    /// as needed.

    ///

    /// Like load_once, but will try to bootstrap (or wait for another

    /// process to bootstrap) if we don't have an up-to-date

    /// bootstrapped directory.

    ///

    /// In general, you shouldn't use this function in a long-running

    /// program; it's only suitable for command-line or batch tools.

    /// Create a new `DirMgr` in online mode, but don't bootstrap it yet.

    ///

    /// The `DirMgr` can be bootstrapped later with `bootstrap`.

    /// Bootstrap a `DirMgr` created in online mode that hasn't been bootstrapped yet.

    ///

    /// This function will not return until the directory is bootstrapped enough to build circuits.

    /// It will also launch a background task that fetches any missing information, and that

    /// replaces the directory when a new one is available.

    ///

    /// This function is intended to be used together with `create_unbootstrapped`. There is no

    /// need to call this function otherwise.

    ///

    /// If bootstrapping has already successfully taken place, returns early with success.

    ///

    /// # Errors

    ///

    /// Returns an error if bootstrapping fails. If the error is [`Error::CantAdvanceState`],

    /// it may be possible to successfully bootstrap later on by calling this function again.

    ///

    /// # Panics

    ///

    /// Panics if the `DirMgr` passed to this function was not created in online mode, such as

    /// via `load_once`.

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

        {

                None => {

                }

            }

        };

        // Try to load from the cache.

        } else {

        };

        // Whether we loaded or not, we now start downloading.

                // Don't warn when these are Error::ManagerDropped: that

                // means that the DirMgr has been shut down.

                {

                    }

                {

                    }

                Ok(()) => {

                    // Disarm the RAII guard, since we succeeded.  Now bootstrap_started will remain true.

                }

                Err(_) => {

                }

            }

    /// Returns `true` if a bootstrap attempt is in progress, or successfully completed.

    /// Return a new directory manager from a given configuration,

    /// bootstrapping from the network as necessary.

    /// Try forever to either lock the storage (and thereby become the

    /// owner), or to reload the database.

    ///

    /// If we have begin to have a bootstrapped directory, send a

    /// message using `on_complete`.

    ///

    /// If we eventually become the owner, return Ok().

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

        let mut bootstrapped;

        {

        }

        loop {

            {

                    // We now own the lock!  (Maybe we owned it before; the

                    // upgrade_to_readwrite() function is idempotent.)  We can

                    // do our own bootstrapping.

                } else {

                }

            // We don't own the lock.  Somebody else owns the cache.  They

            // should be updating it.  Wait a bit, then try again.

            } else {

            };

            // TODO: instead of loading the whole thing we should have a

            // database entry that says when the last update was, or use

            // our state functions.

            {

                    // Successfully loaded a bootstrapped directory.

            }

        }

    /// Try to fetch our directory info and keep it updated, indefinitely.

    ///

    /// If we have begin to have a bootstrapped directory, send a

    /// message using `on_complete`.

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

        loop {

                // TODO(nickm): instead of getting this every time we loop, it

                // might be a good idea to refresh it with each attempt, at

                // least at the point of checking the number of attempts.

                        BootstrapAction::Nonfatal => {

                        }

                    }

                    );

                    {

                } else {

                }

            }

                // we ran out of attempts.

                );

            } else {

                // Report success, if appropriate.

            }

                }

            }

        }

    /// Get a reference to the circuit manager, if we have one.

    /// Try to change our configuration to `new_config`.

    ///

    /// Actual behavior will depend on the value of `how`.

    /// Return a stream of [`DirBootstrapStatus`] events to tell us about changes

    /// in the latest directory's bootstrap status.

    ///

    /// Note that this stream can be lossy: the caller will not necessarily

    /// observe every event on the stream

    /// Replace the latest status with `progress` and broadcast to anybody

    /// watching via a [`DirBootstrapEvents`] stream.

    /// Update our status tracker to note that some number of errors has

    /// occurred.

    /// Update our status tracker to note that we've needed to reset our download attempt.

    /// Try to make this a directory manager with read-write access to its

    /// storage.

    ///

    /// Return true if we got the lock, or if we already had it.

    ///

    /// Return false if another process has the lock

    /// Return a reference to the store, if it is currently read-write.

    #[cfg(test)]

        } else {

        }

    /// Construct a DirMgr from a DirMgrConfig.

    ///

    /// If `offline` is set, opens the SQLite store read-only and sets the offline flag in the

    /// returned manager.

    #[allow(clippy::unnecessary_wraps)] // API compat and future-proofing

        // We load the cached protocol recommendations unconditionally: the caller needs them even

        // if it does not try to load the reset of the cache.

    /// Load the latest non-pending non-expired directory from the

    /// cache, if it is newer than the one we have.

    ///

    /// Return false if there is no such consensus.

    /// Return a new asynchronous stream that will receive notification

    /// whenever the consensus has changed.

    ///

    /// Multiple events may be batched up into a single item: each time

    /// this stream yields an event, all you can assume is that the event has

    /// occurred at least once.

    /// Try to load the text of a single document described by `doc` from

    /// storage.

        use itertools::Itertools;

        } else {

        }

    /// Load the text for a collection of documents.

    ///

    /// If many of the documents have the same type, this can be more

    /// efficient than calling [`text`](Self::text).

        }

    /// Given a request we sent and the response we got from a

    /// directory server, see whether we should expand that response

    /// into "something larger".

    ///

    /// Currently, this handles expanding consensus diffs, and nothing

    /// else.  We do it at this stage of our downloading operation

    /// because it requires access to the store.

                    };

    /// If `state` has netdir changes to apply, apply them to our netdir.

    #[allow(clippy::cognitive_complexity)]

                NetDirChange::AttemptReplace {

                } => {

                    // Check the new netdir is sufficient, if we have a circmgr.

                    // (Unwraps are fine because the `Option` is `Some` until we take it.)

                        {

                        // Now that a consensus is usable, older consensuses may

                        // need to expire.

                }

                }

                }

            }

        } else {

        }

}

/// A degree of readiness for a given directory state object.

#[derive(Debug, Copy, Clone)]

enum Readiness {

    /// There is no more information to download.

    Complete,

    /// There is more information to download, but we don't need to

    Usable,

}

/// Try to upgrade a weak reference to a DirMgr, and give an error on

/// failure.

/// Given a time `now`, and an amount of tolerated clock skew `tolerance`,

/// return the age of the oldest consensus that we should request at that time.

    /// We _always_ allow at least this much age in our consensuses, to account

    /// for the fact that consensuses have some lifetime.

    const MIN_AGE_TO_ALLOW: Duration = Duration::from_secs(3 * 3600);

    );

/// Return a list of the protocols [supported](tor_protover::doc_supported) by this crate

/// when running as a client.

    use tor_protover::named::*;

    // WARNING: REMOVING ELEMENTS FROM THIS LIST CAN BE DANGEROUS!

    // SEE [`tor_protover::doc_changing`]

#[cfg(test)]

mod test {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_duration_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use crate::docmeta::{AuthCertMeta, ConsensusMeta};

    use std::time::Duration;

    use tempfile::TempDir;

    use tor_basic_utils::test_rng::testing_rng;

    use tor_netdoc::doc::netstatus::ConsensusFlavor;

    use tor_netdoc::doc::{authcert::AuthCertKeyIds, netstatus::Lifetime};

    use tor_rtcompat::SleepProvider;

    #[test]

    fn protocols() {

        let pr = supported_client_protocols();

        let expected = "DirCache=2".parse().unwrap();

        assert_eq!(pr, expected);

    }

    pub(crate) fn new_mgr<R: Runtime>(runtime: R) -> (TempDir, DirMgr<R>) {

        let dir = TempDir::new().unwrap();

        let config = DirMgrConfig {

            cache_dir: dir.path().into(),

            ..Default::default()

        };

        let store = DirMgrStore::new(&config, runtime.clone(), false).unwrap();

        let dirmgr = DirMgr::from_config(config, runtime, store, None, false).unwrap();

        (dir, dirmgr)

    }

    #[test]

    fn failing_accessors() {

        tor_rtcompat::test_with_one_runtime!(|rt| async {

            let (_tempdir, mgr) = new_mgr(rt);

            assert!(mgr.circmgr().is_err());

            assert!(mgr.netdir(Timeliness::Unchecked).is_err());

        });

    }

    #[test]

    fn load_and_store_internals() {

        tor_rtcompat::test_with_one_runtime!(|rt| async {

            let now = rt.wallclock();

            let tomorrow = now + Duration::from_secs(86400);

            let later = tomorrow + Duration::from_secs(86400);

            let (_tempdir, mgr) = new_mgr(rt);

            // Seed the storage with a bunch of junk.

            let d1 = [5_u8; 32];

            let d2 = [7; 32];

            let d3 = [42; 32];

            let d4 = [99; 20];

            let d5 = [12; 20];

            let certid1 = AuthCertKeyIds {

                id_fingerprint: d4.into(),

                sk_fingerprint: d5.into(),

            };

            let certid2 = AuthCertKeyIds {

                id_fingerprint: d5.into(),

                sk_fingerprint: d4.into(),

            };

            {

                let mut store = mgr.store.lock().unwrap();

                store

                    .store_microdescs(

                        &[

                            ("Fake micro 1", &d1),

                            ("Fake micro 2", &d2),

                            ("Fake micro 3", &d3),

                        ],

                        now,

                    )

                    .unwrap();

                #[cfg(feature = "routerdesc")]

                store

                    .store_routerdescs(&[("Fake rd1", now, &d4), ("Fake rd2", now, &d5)])

                    .unwrap();

                store

                    .store_authcerts(&[

                        (

                            AuthCertMeta::new(certid1, now, tomorrow),

                            "Fake certificate one",

                        ),

                        (

                            AuthCertMeta::new(certid2, now, tomorrow),

                            "Fake certificate two",

                        ),

                    ])

                    .unwrap();

                let cmeta = ConsensusMeta::new(

                    Lifetime::new(now, tomorrow, later).unwrap(),

                    [102; 32],

                    [103; 32],

                );

                store

                    .store_consensus(&cmeta, ConsensusFlavor::Microdesc, false, "Fake consensus!")

                    .unwrap();

            }

            // Try to get it with text().

            let t1 = mgr.text(&DocId::Microdesc(d1)).unwrap().unwrap();

            assert_eq!(t1.as_str(), Ok("Fake micro 1"));

            let t2 = mgr

                .text(&DocId::LatestConsensus {

                    flavor: ConsensusFlavor::Microdesc,

                    cache_usage: CacheUsage::CacheOkay,

                })

                .unwrap()

                .unwrap();

            assert_eq!(t2.as_str(), Ok("Fake consensus!"));

            let t3 = mgr.text(&DocId::Microdesc([255; 32])).unwrap();

            assert!(t3.is_none());

            // Now try texts()

            let d_bogus = DocId::Microdesc([255; 32]);

            let res = mgr

                .texts(vec![

                    DocId::Microdesc(d2),

                    DocId::Microdesc(d3),

                    d_bogus,

                    DocId::AuthCert(certid2),

                    #[cfg(feature = "routerdesc")]

                    DocId::RouterDesc(d5),

                ])

                .unwrap();

            assert_eq!(