//! Implementation for the primary directory state machine.

//!

//! There are three (active) states that a download can be in: looking

//! for a consensus ([`GetConsensusState`]), looking for certificates

//! to validate that consensus ([`GetCertsState`]), and looking for

//! microdescriptors ([`GetMicrodescsState`]).

//!

//! These states have no contact with the network, and are purely

//! reactive to other code that drives them.  See the

//! [`bootstrap`](crate::bootstrap) module for functions that actually

//! load or download directory information.

use std::collections::{HashMap, HashSet};

use std::fmt::Debug;

use std::mem;

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

use std::time::{Duration, SystemTime};

use time::OffsetDateTime;

use tor_basic_utils::RngExt as _;

use tor_dircommon::retry::DownloadSchedule;

use tor_error::{internal, warn_report};

use tor_netdir::{MdReceiver, NetDir, PartialNetDir};

use tor_netdoc::doc::authcert::UncheckedAuthCert;

use tor_netdoc::doc::netstatus::{Lifetime, ProtoStatuses};

use tracing::{debug, warn};

use crate::event::DirProgress;

use crate::storage::DynStore;

use crate::{

    CacheUsage, ClientRequest, DirMgrConfig, DocId, DocumentText, Error, Readiness, Result,

    docmeta::{AuthCertMeta, ConsensusMeta},

    event,

};

use crate::{DocSource, SharedMutArc};

use tor_checkable::{ExternallySigned, SelfSigned, Timebound};

#[cfg(feature = "geoip")]

use tor_geoip::GeoipDb;

use tor_llcrypto::pk::rsa::RsaIdentity;

use tor_netdoc::doc::{

    microdesc::{MdDigest, Microdesc},

    netstatus::MdConsensus,

};

use tor_netdoc::{

    AllowAnnotations,

    doc::{

        authcert::{AuthCert, AuthCertKeyIds},

        microdesc::MicrodescReader,

        netstatus::{ConsensusFlavor, UnvalidatedMdConsensus},

    },

};

use tor_rtcompat::Runtime;

/// A change to the currently running `NetDir`, returned by the state machines in this module.

#[derive(Debug)]

pub(crate) enum NetDirChange<'a> {

    /// If the provided `NetDir` is suitable for use (i.e. the caller determines it can build

    /// circuits with it), replace the current `NetDir` with it.

    ///

    /// The caller must call `DirState::on_netdir_replaced` if the replace was successful.

    AttemptReplace {

        /// The netdir to replace the current one with, if it's usable.

        ///

        /// The `Option` is always `Some` when returned from the state machine; it's there

        /// so that the caller can call `.take()` to avoid cloning the netdir.

        netdir: &'a mut Option<NetDir>,

        /// The consensus metadata for this netdir.

        consensus_meta: &'a ConsensusMeta,

    },

    /// Add the provided microdescriptors to the current `NetDir`.

    AddMicrodescs(&'a mut Vec<Microdesc>),

    /// Replace the recommended set of subprotocols.

    SetRequiredProtocol {

        /// The time at which the protocol statuses were recommended

        timestamp: SystemTime,

        /// The recommended set of protocols.

        protos: Arc<ProtoStatuses>,

    },

}

/// A "state" object used to represent our progress in downloading a

/// directory.

///

/// These state objects are not meant to know about the network, or

/// how to fetch documents at all.  Instead, they keep track of what

/// information they are missing, and what to do when they get that

/// information.

///

/// Every state object has two possible transitions: "resetting", and

/// "advancing".  Advancing happens when a state has no more work to

/// do, and needs to transform into a different kind of object.

/// Resetting happens when this state needs to go back to an initial

/// state in order to start over -- either because of an error or

/// because the information it has downloaded is no longer timely.

pub(crate) trait DirState: Send {

    /// Return a human-readable description of this state.

    fn describe(&self) -> String;

    /// Return a list of the documents we're missing.

    ///

    /// If every document on this list were to be loaded or downloaded, then

    /// the state should either become "ready to advance", or "complete."

    ///

    /// This list should never _grow_ on a given state; only advancing

    /// or resetting the state should add new DocIds that weren't

    /// there before.

    fn missing_docs(&self) -> Vec<DocId>;

    /// Describe whether this state has reached `ready` status.

    fn is_ready(&self, ready: Readiness) -> bool;

    /// If the state object wants to make changes to the currently running `NetDir`,

    /// return the proposed changes.

    /// Return true if this state can advance to another state via its

    /// `advance` method.

    fn can_advance(&self) -> bool;

    /// Add one or more documents from our cache; returns 'true' if there

    /// was any change in this state.

    ///

    /// Set `changed` to true if any semantic changes in this state were made.

    ///

    /// An error return does not necessarily mean that no data was added;

    /// partial successes are possible.

    fn add_from_cache(

        &mut self,

        docs: HashMap<DocId, DocumentText>,

        changed: &mut bool,

    ) -> Result<()>;

    /// Add information that we have just downloaded to this state.

    ///

    /// This method receives a copy of the original request, and should reject

    /// any documents that do not pertain to it.

    ///

    /// If `storage` is provided, then we should write any accepted documents

    /// into `storage` so they can be saved in a cache.

    ///

    /// Set `changed` to true if any semantic changes in this state were made.

    ///

    /// An error return does not necessarily mean that no data was added;

    /// partial successes are possible.

    fn add_from_download(

        &mut self,

        text: &str,

        request: &ClientRequest,

        source: DocSource,

        storage: Option<&Mutex<DynStore>>,

        changed: &mut bool,

    ) -> Result<()>;

    /// Return a summary of this state as a [`DirProgress`].

    fn bootstrap_progress(&self) -> event::DirProgress;

    /// Return a configuration for attempting downloads.

    fn dl_config(&self) -> DownloadSchedule;

    /// If possible, advance to the next state.

    fn advance(self: Box<Self>) -> Box<dyn DirState>;

    /// Return a time (if any) when downloaders should stop attempting to

    /// advance this state, and should instead reset it and start over.

    fn reset_time(&self) -> Option<SystemTime>;

    /// Reset this state and start over.

    fn reset(self: Box<Self>) -> Box<dyn DirState>;

}

/// An object that can provide a previous netdir for the bootstrapping state machines to use.

pub(crate) trait PreviousNetDir: Send + Sync + 'static + Debug {

    /// Get the previous netdir, if there still is one.

    fn get_netdir(&self) -> Option<Arc<NetDir>>;

}

impl PreviousNetDir for SharedMutArc<NetDir> {

}

/// Initial state: fetching or loading a consensus directory.

#[derive(Clone, Debug)]

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

    /// How should we get the consensus from the cache, if at all?

    cache_usage: CacheUsage,

    /// If present, a time after which we want our consensus to have

    /// been published.

    //

    // TODO: This is not yet used everywhere it could be.  In the future maybe

    // it should be inserted into the DocId::LatestConsensus  alternative rather

    // than being recalculated in make_consensus_request,

    after: Option<SystemTime>,

    /// If present, our next state.

    ///

    /// (This is present once we have a consensus.)

    next: Option<GetCertsState<R>>,

    /// A list of RsaIdentity for the authorities that we believe in.

    ///

    /// No consensus can be valid unless it purports to be signed by

    /// more than half of these authorities.

    authority_ids: Vec<RsaIdentity>,

    /// A `Runtime` implementation.

    rt: R,

    /// The configuration of the directory manager. Used for download configuration

    /// purposes.

    config: Arc<DirMgrConfig>,

    /// If one exists, the netdir we're trying to update.

    prev_netdir: Option<Arc<dyn PreviousNetDir>>,

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

    #[cfg(feature = "dirfilter")]

    filter: Arc<dyn crate::filter::DirFilter>,

}

impl<R: Runtime> GetConsensusState<R> {

    /// Create a new `GetConsensusState`, using the cache as per `cache_usage` and downloading as

    /// per the relevant sections of `config`. If `prev_netdir` is supplied, information from that

    /// directory may be used to complete the next one.

}

impl<R: Runtime> DirState for GetConsensusState<R> {

        } else {

            }

        }

        } else {

        }

            Some((

                DocId::LatestConsensus {

                    flavor: ConsensusFlavor::Microdesc,

                    ..

                },

        };

        };

        }

}

impl<R: Runtime> GetConsensusState<R> {

    /// Helper: try to set the current consensus text from an input string

    /// `text`.  Refuse it if the authorities could never be correct, or if it

    /// is ill-formed.

    ///

    /// If `cutoff` is provided, treat any consensus older than `cutoff` as

    /// older-than-requested.

    ///

    /// Errors from this method are not fatal to the download process.

        // Try to parse it and get its metadata.

            #[cfg(feature = "dirfilter")]

        };

        // Check out what authorities we believe in, and see if enough

        // of them are purported to have signed this consensus.

        // Yes, we've added the consensus.  That's a change.

        // Make a set of all the certificates we want -- the subset of

        // those listed on the consensus that we would indeed accept as

        // authoritative.

        // Unwrap should be safe because `next` was just assigned

        #[allow(clippy::unwrap_used)]

    /// Return true if `id` is an authority identity we recognize

}

/// One of two possible internal states for the consensus in a GetCertsState.

///

/// This inner object is advanced by `try_checking_sigs`.

#[derive(Clone, Debug)]

enum GetCertsConsensus {

    /// We have an unvalidated consensus; we haven't checked its signatures.

    Unvalidated(UnvalidatedMdConsensus),

    /// A validated consensus: the signatures are fine and we can advance.

    Validated(MdConsensus),

    /// We failed to validate the consensus, even after getting enough certificates.

    Failed,

}

/// Second state: fetching or loading authority certificates.

///

/// TODO: we should probably do what C tor does, and try to use the

/// same directory that gave us the consensus.

///

/// TODO SECURITY: This needs better handling for the DOS attack where

/// we are given a bad consensus signed with fictional certificates

/// that we can never find.

#[derive(Clone, Debug)]

struct GetCertsState<R: Runtime> {

    /// The cache usage we had in mind when we began.  Used to reset.

    cache_usage: CacheUsage,

    /// Where did we get our consensus?

    consensus_source: DocSource,

    /// The consensus that we are trying to validate, or an error if we've given

    /// up on validating it.

    consensus: GetCertsConsensus,

    /// Metadata for the consensus.

    consensus_meta: ConsensusMeta,

    /// A set of the certificate keypairs for the certificates we don't

    /// have yet.

    missing_certs: HashSet<AuthCertKeyIds>,

    /// A list of the certificates we've been able to load or download.

    certs: Vec<AuthCert>,

    /// A `Runtime` implementation.

    rt: R,

    /// The configuration of the directory manager. Used for download configuration

    /// purposes.

    config: Arc<DirMgrConfig>,

    /// If one exists, the netdir we're trying to update.

    prev_netdir: Option<Arc<dyn PreviousNetDir>>,

    /// If present a set of protocols to install as our latest recommended set.

    protocol_statuses: Option<(SystemTime, Arc<ProtoStatuses>)>,

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

    #[cfg(feature = "dirfilter")]

    filter: Arc<dyn crate::filter::DirFilter>,

}

impl<R: Runtime> GetCertsState<R> {

    /// Handle a certificate result returned by `tor_netdoc`: checking it for timeliness

    /// and well-signedness.

    ///

    /// On success return the `AuthCert` and the string that represents it within the string `within`.

    /// On failure, return an error.

    /// If we have enough certificates, and we have not yet checked the

    /// signatures on the consensus, try checking them.

    ///

    /// If the consensus is valid, remove the unvalidated consensus from `self`

    /// and put the validated consensus there instead.

    ///

    /// If the consensus is invalid, throw it out set a blocking error.

        use GetCertsConsensus as C;

        // Temporary value; we'll replace the consensus field with something

        // better before the method returns.

            _ => {

                // nothing to check at this point.  Either we already checked the consensus, or we don't yet have enough certificates.

            }

        };

        };

        // Update our protocol recommendations if we have a validated consensus,

        // and if we haven't already updated our recommendations.

}

impl<R: Runtime> DirState for GetCertsState<R> {

        use GetCertsConsensus as C;

            C::Unvalidated(_) => {

                    total

                )

            }

        }

        // Here we iterate over the documents we want, taking them from

        // our input and remembering them.

                }

        }

        };

        {

                }

            }

        }

        // Now discard any certs we didn't ask for.

                source

            );

        // We want to exit early if we aren't saving any certificates.

            // Write the certificates to the store.

        // Remember the certificates in this state, and remove them

        // from our list of missing certs.

        }

        use GetCertsConsensus::*;

        }

            // Cache only means we can't ever download.

        } else {

            // If we reset in this state, we should always go to "must

            // download": Either we've failed to get the certs we needed, or we

            // have found that the consensus wasn't valid.  Either case calls

            // for a fresh consensus download attempt.

        };

}

/// Final state: we're fetching or loading microdescriptors

#[derive(Debug, Clone)]

struct GetMicrodescsState<R: Runtime> {

    /// How should we get the consensus from the cache, if at all?

    cache_usage: CacheUsage,

    /// Total number of microdescriptors listed in the consensus.

    n_microdescs: usize,

    /// The current status of our netdir.

    partial: PendingNetDir,

    /// Metadata for the current consensus.

    meta: ConsensusMeta,

    /// A pending list of microdescriptor digests whose

    /// "last-listed-at" times we should update.

    newly_listed: Vec<MdDigest>,

    /// A time after which we should try to replace this directory and

    /// find a new one.  Since this is randomized, we only compute it

    /// once.

    reset_time: SystemTime,

    /// A `Runtime` implementation.

    rt: R,

    /// The configuration of the directory manager. Used for download configuration

    /// purposes.

    config: Arc<DirMgrConfig>,

    /// If one exists, the netdir we're trying to update.

    prev_netdir: Option<Arc<dyn PreviousNetDir>>,

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

    #[cfg(feature = "dirfilter")]

    filter: Arc<dyn crate::filter::DirFilter>,

}

/// Information about a network directory that might not be ready to become _the_ current network

/// directory.

#[derive(Debug, Clone)]

enum PendingNetDir {

    /// A NetDir for which we have a consensus, but not enough microdescriptors.

    Partial(PartialNetDir),

    /// A NetDir we're either trying to get our caller to replace, or that the caller

    /// has already taken from us.

    ///

    /// After the netdir gets taken, the `collected_microdescs` and `missing_microdescs`

    /// fields get used. Before then, we just do operations on the netdir.

    Yielding {

        /// The actual netdir. This starts out as `Some`, but our caller can `take()` it

        /// from us.

        netdir: Option<NetDir>,

        /// Microdescs we have collected in order to yield to our caller.

        collected_microdescs: Vec<Microdesc>,

        /// Which microdescs we need for the netdir that either is or used to be in `netdir`.

        ///

        /// NOTE(eta): This MUST always match the netdir's own idea of which microdescs we need.

        ///            We do this by copying the netdir's missing microdescs into here when we

        ///            instantiate it.

        ///            (This code assumes that it doesn't add more needed microdescriptors later!)

        missing_microdescs: HashSet<MdDigest>,

        /// The time at which we should renew this netdir, assuming we have

        /// driven it to a "usable" state.

        replace_dir_time: SystemTime,

    },

    /// A dummy value, so we can use `mem::replace`.

    Dummy,

}

impl MdReceiver for PendingNetDir {

            PendingNetDir::Yielding {

                ..

            } => {

                } else {

                }

            }

        }

            PendingNetDir::Yielding {

                ..

            } => {

                    // This shouldn't ever happen; if it does, our invariants are violated.

                } else {

                }

            }

        }

            PendingNetDir::Yielding {

                ..

            } => {

                    // This shouldn't ever happen; if it does, our invariants are violated.

                } else {

                }

            }

        }

}

impl PendingNetDir {

    /// If this PendingNetDir is Partial and could not be partial, upgrade it.

                        );

                    }

                },

            }

}

impl<R: Runtime> GetMicrodescsState<R> {

    /// Create a new [`GetMicrodescsState`] from a provided

    /// microdescriptor consensus.

        #[cfg(not(feature = "geoip"))]

        let mut partial_dir = PartialNetDir::new(consensus, Some(params));

        // TODO(eta): Make this embedded database configurable using the `DirMgrConfig`.

        #[cfg(feature = "geoip")]

        // Always upgrade at least once: otherwise, we won't notice we're ready unless we

        // add a microdescriptor.

    /// Add a bunch of microdescriptors to the in-progress netdir.

    {

        #[cfg(feature = "dirfilter")]

        }

}

impl<R: Runtime> DirState for GetMicrodescsState<R> {

        )

            PendingNetDir::Yielding {

                ..

            } => {

                } else {

                }

            }

        }

            Readiness::Usable => {

                // We're "usable" if the calling code thought our netdir was usable enough to

                // steal it.

            }

        }

        }

        } else {

        };

        {

                }

            };

                    source,

                );

        }

                //.get_mut()

        // TODO(nickm): The reset logic is a little wonky here: we don't truly

        // want to _reset_ this state at `replace_dir_time`.  In fact, we ought

        // to be able to have multiple states running in parallel: one filling

        // in the mds for an old consensus, and one trying to fetch a better

        // one.  That's likely to require some amount of refactoring of the

        // bootstrap code.

            // If the client has taken a completed netdir, the netdir is now

            // usable: We can reset our download attempt when we choose to try

            // to replace this directory.

            PendingNetDir::Yielding {

                netdir: None,

                ..

            // We don't have a completed netdir: Keep trying to fill this one in

            // until it is _definitely_ unusable.  (Our clock might be skewed;

            // there might be no up-to-date consensus.)

        })

            // Cache only means we can't ever download.

            // If we managed to bootstrap a usable consensus, then we won't

            // accept our next consensus from the cache.

        } else {

            // If we didn't manage to bootstrap a usable consensus, then we can

            // indeed try again with the one in the cache.

            // TODO(nickm) is this right?

        };

}

/// Choose a random download time to replace a consensus whose lifetime

/// is `lifetime`.

/// Based on the lifetime for a consensus, return the time range during which

/// clients should fetch the next one.

    // From dir-spec:

    // "This time is chosen uniformly at random from the interval

    // between the time 3/4 into the first interval after the

    // consensus is no longer fresh, and 7/8 of the time remaining

    // after that before the consensus is invalid."

/// If `err` is some, return `Err(err)`.  Otherwise return Ok(()).

    }

/// A dummy state implementation, used when we need to temporarily write a

/// placeholder into a box.

///

/// Calling any method on this state will panic.

#[derive(Clone, Debug)]

pub(crate) struct PoisonedState;

impl DirState for PoisonedState {

    }

    }

    }

    }

    }

    }

    }

    }

    }

    }

    }

}

#[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_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

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

    #![allow(clippy::cognitive_complexity)]

    use super::*;

    use std::convert::TryInto;

    use std::sync::Arc;

    use tempfile::TempDir;

    use time::macros::datetime;

    use tor_dircommon::{

        authority::{AuthorityContacts, AuthorityContactsBuilder},

        config::{DownloadScheduleConfig, NetworkConfig},

    };

    use tor_netdoc::doc::authcert::AuthCertKeyIds;

    use tor_rtcompat::RuntimeSubstExt as _;

    use tor_rtmock::simple_time::SimpleMockTimeProvider;

    #[test]

    fn download_schedule() {

        let va = datetime!(2008-08-02 20:00 UTC).into();

        let fu = datetime!(2008-08-02 21:00 UTC).into();

        let vu = datetime!(2008-08-02 23:00 UTC).into();

        let lifetime = Lifetime::new(va, fu, vu).unwrap();

        let expected_start: SystemTime = datetime!(2008-08-02 21:45 UTC).into();

        let expected_range = Duration::from_millis((75 * 60 * 1000) * 7 / 8);

        let (start, range) = client_download_range(&lifetime);

        assert_eq!(start, expected_start);

        assert_eq!(range, expected_range);

        for _ in 0..100 {

            let when = pick_download_time(&lifetime);

            assert!(when > va);

            assert!(when >= expected_start);

            assert!(when < vu);

            assert!(when <= expected_start + range);

        }