//! Parsing implementation for networkstatus documents.

//!

//! In Tor, a networkstatus documents describes a complete view of the

//! relays in the network: how many there are, how to contact them,

//! and so forth.

//!

//! A networkstatus document can either be a "votes" -- an authority's

//! view of the network, used as input to the voting process -- or a

//! "consensus" -- a combined view of the network based on multiple

//! authorities' votes, and signed by multiple authorities.

//!

//! A consensus document can itself come in two different flavors: a

//! "ns"-flavored consensus has references to router descriptors, and

//! a "microdesc"-flavored consensus has references to

//! microdescriptors.

//!

//! To keep an up-to-date view of the network, clients download

//! microdescriptor-flavored consensuses periodically, and then

//! download whatever microdescriptors the consensus lists that the

//! client doesn't already have.

//!

//! For full information about the network status format, see

//! [dir-spec.txt](https://spec.torproject.org/dir-spec).

//!

//! # Limitations

//!

//! NOTE: The consensus format has changes time, using a

//! "consensus-method" mechanism.  This module is does not yet handle all

//! all historical consensus-methods.

//!

//! NOTE: This module _does_ parse some fields that are not in current

//! use, like relay nicknames, and the "published" times on

//! microdescriptors. We should probably decide whether we actually

//! want to do this.

//!

//! TODO: This module doesn't implement vote parsing at all yet.

//!

//! TODO: This module doesn't implement ns-flavored consensuses.

//!

//! TODO: More testing is needed!

//!

//! TODO: There should be accessor functions for most of the fields here.

//! As with the other tor-netdoc types, I'm deferring those till I know what

//! they should be.

mod rs;

#[cfg(feature = "build_docs")]

mod build;

use crate::doc::authcert::{AuthCert, AuthCertKeyIds};

use crate::parse::keyword::Keyword;

use crate::parse::parser::{Section, SectionRules, SectionRulesBuilder};

use crate::parse::tokenize::{Item, ItemResult, NetDocReader};

use crate::types::misc::*;

use crate::util::private::Sealed;

use crate::util::PeekableIterator;

use crate::{Error, NetdocErrorKind as EK, Pos, Result};

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

use std::result::Result as StdResult;

use std::sync::Arc;

use std::{net, result, time};

use tor_error::{internal, HasKind};

use tor_protover::Protocols;

use bitflags::bitflags;

use digest::Digest;

use std::sync::LazyLock;

use tor_checkable::{timed::TimerangeBound, ExternallySigned};

use tor_llcrypto as ll;

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

use serde::{Deserialize, Deserializer};

#[cfg(feature = "build_docs")]

pub use build::ConsensusBuilder;

#[cfg(feature = "build_docs")]

pub use rs::build::RouterStatusBuilder;

pub use rs::MdConsensusRouterStatus;

#[cfg(feature = "ns_consensus")]

pub use rs::NsConsensusRouterStatus;

use void::ResultVoidExt as _;

/// The lifetime of a networkstatus document.

///

/// In a consensus, this type describes when the consensus may safely

/// be used.  In a vote, this type describes the proposed lifetime for a

/// consensus.

#[derive(Clone, Debug)]

pub struct Lifetime {

    /// Time at which the document becomes valid

    valid_after: time::SystemTime,

    /// Time after which there is expected to be a better version

    /// of this consensus

    fresh_until: time::SystemTime,

    /// Time after which this consensus is expired.

    ///

    /// (In practice, Tor clients will keep using documents for a while

    /// after this expiration time, if no better one can be found.)

    valid_until: time::SystemTime,

}

impl Lifetime {

    /// Construct a new Lifetime.

        } else {

        }

    /// Return time when this consensus first becomes valid.

    ///

    /// (You might see a consensus a little while before this time,

    /// since voting tries to finish up before the.)

    /// Return time when this consensus is no longer fresh.

    ///

    /// You can use the consensus after this time, but there is (or is

    /// supposed to be) a better one by this point.

    /// Return the time when this consensus is no longer valid.

    ///

    /// You should try to get a better consensus after this time,

    /// though it's okay to keep using this one if no more recent one

    /// can be found.

    /// Return true if this consensus is officially valid at the provided time.

    /// Return the voting period implied by this lifetime.

    ///

    /// (The "voting period" is the amount of time in between when a consensus first

    /// becomes valid, and when the next consensus is expected to become valid)

}

/// A set of named network parameters.

///

/// These are used to describe current settings for the Tor network,

/// current weighting parameters for path selection, and so on.  They're

/// encoded with a space-separated K=V format.

///

/// A `NetParams<i32>` is part of the validated directory manager configuration,

/// where it is built (in the builder-pattern sense) from a transparent HashMap.

#[derive(Debug, Clone, Default, Eq, PartialEq)]

pub struct NetParams<T> {

    /// Map from keys to values.

    params: HashMap<String, T>,

}

impl<T> NetParams<T> {

    /// Create a new empty list of NetParams.

    #[allow(unused)]

    /// Retrieve a given network parameter, if it is present.

    /// Return an iterator over all key value pairs in an arbitrary order.

    /// Set or replace the value of a network parameter.

}

impl<K: Into<String>, T> FromIterator<(K, T)> for NetParams<T> {

}

impl<T> std::iter::Extend<(String, T)> for NetParams<T> {

}

impl<'de, T> Deserialize<'de> for NetParams<T>

where

    T: Deserialize<'de>,

{

}

/// A list of subprotocol versions that implementors should/must provide.

///

/// Each consensus has two of these: one for relays, and one for clients.

#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]

pub struct ProtoStatus {

    /// Set of protocols that are recommended; if we're missing a protocol

    /// in this list we should warn the user.

    recommended: Protocols,

    /// Set of protocols that are required; if we're missing a protocol

    /// in this list we should refuse to start.

    required: Protocols,

}

impl ProtoStatus {

    /// Check whether the list of supported protocols

    /// is sufficient to satisfy this list of recommendations and requirements.

    ///

    /// If any required protocol is missing, returns [`ProtocolSupportError::MissingRequired`].

    ///

    /// Otherwise, if no required protocol is missing, but some recommended protocol is missing,

    /// returns [`ProtocolSupportError::MissingRecommended`].

    ///

    /// Otherwise, if no recommended or required protocol is missing, returns `Ok(())`.

}

/// A subprotocol that is recommended or required in the consensus was not present.

#[derive(Clone, Debug, thiserror::Error)]

#[cfg_attr(test, derive(PartialEq))]

#[non_exhaustive]

pub enum ProtocolSupportError {

    /// At least one required protocol was not in our list of supported protocols.

    #[error("Required protocols are not implemented: {0}")]

    MissingRequired(Protocols),

    /// At least one recommended protocol was not in our list of supported protocols.

    ///

    /// Also implies that no _required_ protocols were missing.

    #[error("Recommended protocols are not implemented: {0}")]

    MissingRecommended(Protocols),

}

impl ProtocolSupportError {

    /// Return true if the suggested behavior for this error is a shutdown.

}

impl HasKind for ProtocolSupportError {

}

/// A set of recommended and required protocols when running

/// in various scenarios.

#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]

pub struct ProtoStatuses {

    /// Lists of recommended and required subprotocol versions for clients

    client: ProtoStatus,

    /// Lists of recommended and required subprotocol versions for relays

    relay: ProtoStatus,

}

impl ProtoStatuses {

    /// Return the list of recommended and required protocols for running as a client.

    /// Return the list of recommended and required protocols for running as a relay.

}

/// A recognized 'flavor' of consensus document.

#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]

#[non_exhaustive]

pub enum ConsensusFlavor {

    /// A "microdesc"-flavored consensus.  This is the one that

    /// clients and relays use today.

    Microdesc,

    /// A "networkstatus"-flavored consensus.  It's used for

    /// historical and network-health purposes.  Instead of listing

    /// microdescriptor digests, it lists digests of full relay

    /// descriptors.

    Ns,

}

impl ConsensusFlavor {

    /// Return the name of this consensus flavor.

        }

    /// Try to find the flavor whose name is `name`.

    ///

    /// For historical reasons, an unnamed flavor indicates an "Ns"

    /// document.

            }

        }

}

/// The signature of a single directory authority on a networkstatus document.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

pub struct Signature {

    /// The name of the digest algorithm used to make the signature.

    ///

    /// Currently sha1 and sh256 are recognized.  Here we only support

    /// sha256.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    digestname: String,

    /// Fingerprints of the keys for the authority that made

    /// this signature.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    key_ids: AuthCertKeyIds,

    /// The signature itself.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    signature: Vec<u8>,

}

/// A collection of signatures that can be checked on a networkstatus document

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

pub struct SignatureGroup {

    /// The sha256 of the document itself

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    sha256: Option<[u8; 32]>,

    /// The sha1 of the document itself

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    sha1: Option<[u8; 20]>,

    /// The signatures listed on the document.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    signatures: Vec<Signature>,

}

/// A shared random value produced by the directory authorities.

#[derive(

    Debug, Clone, Copy, Eq, PartialEq, derive_more::From, derive_more::Into, derive_more::AsRef,

)]

// (This doesn't need to use CtByteArray; we don't really need to compare these.)

pub struct SharedRandVal([u8; 32]);

/// A shared-random value produced by the directory authorities,

/// along with meta-information about that value.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

pub struct SharedRandStatus {

    /// How many authorities revealed shares that contributed to this value.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    n_reveals: u8,

    /// The current random value.

    ///

    /// The properties of the secure shared-random system guarantee

    /// that this value isn't predictable before it first becomes

    /// live, and that a hostile party could not have forced it to

    /// have any more than a small number of possible random values.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    value: SharedRandVal,

    /// The time when this SharedRandVal becomes (or became) the latest.

    ///

    /// (This is added per proposal 342, assuming that gets accepted.)

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    timestamp: Option<time::SystemTime>,

}

/// Parts of the networkstatus header that are present in every networkstatus.

///

/// NOTE: this type is separate from the header parts that are only in

/// votes or only in consensuses, even though we don't implement votes yet.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

struct CommonHeader {

    /// What kind of consensus document is this?  Absent in votes and

    /// in ns-flavored consensuses.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    flavor: ConsensusFlavor,

    /// Over what time is this consensus valid?  (For votes, this is

    /// the time over which the voted-upon consensus should be valid.)

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    lifetime: Lifetime,

    /// List of recommended Tor client versions.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    client_versions: Vec<String>,

    /// List of recommended Tor relay versions.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    relay_versions: Vec<String>,

    /// Lists of recommended and required subprotocols.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    proto_statuses: Arc<ProtoStatuses>,

    /// Declared parameters for tunable settings about how to the

    /// network should operator. Some of these adjust timeouts and

    /// whatnot; some features things on and off.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    params: NetParams<i32>,

    /// How long in seconds should voters wait for votes and

    /// signatures (respectively) to propagate?

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    voting_delay: Option<(u32, u32)>,

}

/// The header of a consensus networkstatus.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

struct ConsensusHeader {

    /// Header fields common to votes and consensuses

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    hdr: CommonHeader,

    /// What "method" was used to produce this consensus?  (A

    /// consensus method is a version number used by authorities to

    /// upgrade the consensus algorithm.)

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    consensus_method: u32,

    /// Global shared-random value for the previous shared-random period.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    shared_rand_prev: Option<SharedRandStatus>,

    /// Global shared-random value for the current shared-random period.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    shared_rand_cur: Option<SharedRandStatus>,

}

/// Description of an authority's identity and address.

///

/// (Corresponds to a dir-source line.)

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

struct DirSource {

    /// human-readable nickname for this authority.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    nickname: String,

    /// Fingerprint for the _authority_ identity key of this

    /// authority.

    ///

    /// This is the same key as the one that signs the authority's

    /// certificates.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    identity: RsaIdentity,

    /// IP address for the authority

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    ip: net::IpAddr,

    /// HTTP directory port for this authority

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    dir_port: u16,

    /// OR port for this authority.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    or_port: u16,

}

bitflags! {

    /// A set of recognized directory flags on a single relay.

    ///

    /// These flags come from a consensus directory document, and are

    /// used to describe what the authorities believe about the relay.

    /// If the document contained any flags that we _didn't_ recognize,

    /// they are not listed in this type.

    ///

    /// The bit values used to represent the flags have no meaning;

    /// they may change between releases of this crate.  Relying on their

    /// values may void your semver guarantees.

    #[derive(Clone, Copy, Debug)]

    pub struct RelayFlags: u16 {

        /// Is this a directory authority?

        const AUTHORITY = (1<<0);

        /// Is this relay marked as a bad exit?

        ///

        /// Bad exits can be used as intermediate relays, but not to

        /// deliver traffic.

        const BAD_EXIT = (1<<1);

        /// Is this relay marked as an exit for weighting purposes?

        const EXIT = (1<<2);

        /// Is this relay considered "fast" above a certain threshold?

        const FAST = (1<<3);

        /// Is this relay suitable for use as a guard relay?

        ///

        /// Clients choose their their initial relays from among the set

        /// of Guard relays.

        const GUARD = (1<<4);

        /// Does this relay participate on the onion service directory

        /// ring?

        const HSDIR = (1<<5);

        /// Set if this relay is considered "middle only", not suitable to run

        /// as an exit or guard relay.

        ///

        /// Note that this flag is only used by authorities as part of

        /// the voting process; clients do not and should not act

        /// based on whether it is set.

        const MIDDLE_ONLY = (1<<6);

        /// If set, there is no consensus for the ed25519 key for this relay.

        const NO_ED_CONSENSUS = (1<<7);

        /// Is this relay considered "stable" enough for long-lived circuits?

        const STABLE = (1<<8);

        /// Set if the authorities are requesting a fresh descriptor for

        /// this relay.

        const STALE_DESC = (1<<9);

        /// Set if this relay is currently running.

        ///

        /// This flag can appear in votes, but in consensuses, every relay

        /// is assumed to be running.

        const RUNNING = (1<<10);

        /// Set if this relay is considered "valid" -- allowed to be on

        /// the network.

        ///

        /// This flag can appear in votes, but in consensuses, every relay

        /// is assumed to be valid.

        const VALID = (1<<11);

        /// Set if this relay supports a currently recognized version of the

        /// directory protocol.

        const V2DIR = (1<<12);

    }

}

/// Recognized weight fields on a single relay in a consensus

#[non_exhaustive]

#[derive(Debug, Clone, Copy)]

pub enum RelayWeight {

    /// An unmeasured weight for a relay.

    Unmeasured(u32),

    /// An measured weight for a relay.

    Measured(u32),

}

impl RelayWeight {

    /// Return true if this weight is the result of a successful measurement

    /// Return true if this weight is nonzero

}

/// All information about a single authority, as represented in a consensus

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

struct ConsensusVoterInfo {

    /// Contents of the dirsource line about an authority

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    dir_source: DirSource,

    /// Human-readable contact information about the authority

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    contact: String,

    /// Digest of the vote that the authority cast to contribute to

    /// this consensus.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    vote_digest: Vec<u8>,

}

/// The signed footer of a consensus netstatus.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    visibility::make(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

struct Footer {

    /// Weights to be applied to certain classes of relays when choosing

    /// for different roles.

    ///

    /// For example, we want to avoid choosing exits for non-exit

    /// roles when overall the proportion of exits is small.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    weights: NetParams<i32>,

}

/// Trait to parse a single relay as listed in a consensus document.

///

/// TODO(nickm): I'd rather not have this trait be public, but I haven't yet

/// figured out how to make it private.

pub trait ParseRouterStatus: Sized + Sealed {

    /// Parse this object from a `Section` object containing its

    /// elements.

    fn from_section(sec: &Section<'_, NetstatusKwd>) -> Result<Self>;

    /// Return the networkstatus consensus flavor in which this

    /// routerstatus appears.

    fn flavor() -> ConsensusFlavor;

}

/// Represents a single relay as listed in a consensus document.

///

/// Not implementable outside of the `tor-netdoc` crate.

pub trait RouterStatus: Sealed {

    /// A digest of the document that's identified by this RouterStatus.

    type DocumentDigest: Clone;

    /// Return RSA identity for the relay described by this RouterStatus

    fn rsa_identity(&self) -> &RsaIdentity;

    /// Return the digest of the document identified by this

    /// routerstatus.

    fn doc_digest(&self) -> &Self::DocumentDigest;

}

/// A single microdescriptor consensus netstatus

///

/// TODO: This should possibly turn into a parameterized type, to represent

/// votes and ns consensuses.

#[allow(dead_code)]

#[cfg_attr(

    feature = "dangerous-expose-struct-fields",

    visible::StructFields(pub),

    non_exhaustive

)]

#[derive(Debug, Clone)]

pub struct Consensus<RS> {

    /// Part of the header shared by all consensus types.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    header: ConsensusHeader,

    /// List of voters whose votes contributed to this consensus.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    voters: Vec<ConsensusVoterInfo>,

    /// A list of routerstatus entries for the relays on the network,

    /// with one entry per relay.

    ///

    /// These are currently ordered by the router's RSA identity, but this is not

    /// to be relied on, since we may want to even abolish RSA at some point!

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    relays: Vec<RS>,

    /// Footer for the consensus object.

    #[cfg_attr(docsrs, doc(cfg(feature = "dangerous-expose-struct-fields")))]

    footer: Footer,

}

/// A consensus document that lists relays along with their

/// microdescriptor documents.

pub type MdConsensus = Consensus<MdConsensusRouterStatus>;

/// An MdConsensus that has been parsed and checked for timeliness,

/// but not for signatures.

pub type UnvalidatedMdConsensus = UnvalidatedConsensus<MdConsensusRouterStatus>;

/// An MdConsensus that has been parsed but not checked for signatures

/// and timeliness.

pub type UncheckedMdConsensus = UncheckedConsensus<MdConsensusRouterStatus>;

#[cfg(feature = "ns_consensus")]

/// A consensus document that lists relays along with their

/// router descriptor documents.

pub type NsConsensus = Consensus<NsConsensusRouterStatus>;

#[cfg(feature = "ns_consensus")]

/// An NsConsensus that has been parsed and checked for timeliness,

/// but not for signatures.

pub type UnvalidatedNsConsensus = UnvalidatedConsensus<NsConsensusRouterStatus>;

#[cfg(feature = "ns_consensus")]

/// An NsConsensus that has been parsed but not checked for signatures

/// and timeliness.

pub type UncheckedNsConsensus = UncheckedConsensus<NsConsensusRouterStatus>;

impl<RS> Consensus<RS> {

    /// Return the Lifetime for this consensus.

    /// Return a slice of all the routerstatus entries in this consensus.

    /// Return a mapping from keywords to integers representing how

    /// to weight different kinds of relays in different path positions.

    /// Return the map of network parameters that this consensus advertises.

    /// Return the latest shared random value, if the consensus

    /// contains one.

    /// Return the previous shared random value, if the consensus

    /// contains one.

    /// Return a [`ProtoStatus`] that lists the network's current requirements and

    /// recommendations for the list of protocols that every relay must implement.  

    /// Return a [`ProtoStatus`] that lists the network's current requirements and

    /// recommendations for the list of protocols that every client must implement.

    /// Return a set of all known [`ProtoStatus`] values.

}

decl_keyword! {

    /// Keywords that can be used in votes and consensuses.

    // TODO: This is public because otherwise we can't use it in the

    // ParseRouterStatus crate.  But I'd rather find a way to make it

    // private.

    #[non_exhaustive]

    #[allow(missing_docs)]

    pub NetstatusKwd {

        // Header

        "network-status-version" => NETWORK_STATUS_VERSION,

        "vote-status" => VOTE_STATUS,

        "consensus-methods" => CONSENSUS_METHODS,

        "consensus-method" => CONSENSUS_METHOD,

        "published" => PUBLISHED,

        "valid-after" => VALID_AFTER,

        "fresh-until" => FRESH_UNTIL,

        "valid-until" => VALID_UNTIL,

        "voting-delay" => VOTING_DELAY,

        "client-versions" => CLIENT_VERSIONS,

        "server-versions" => SERVER_VERSIONS,

        "known-flags" => KNOWN_FLAGS,

        "flag-thresholds" => FLAG_THRESHOLDS,

        "recommended-client-protocols" => RECOMMENDED_CLIENT_PROTOCOLS,

        "required-client-protocols" => REQUIRED_CLIENT_PROTOCOLS,

        "recommended-relay-protocols" => RECOMMENDED_RELAY_PROTOCOLS,

        "required-relay-protocols" => REQUIRED_RELAY_PROTOCOLS,

        "params" => PARAMS,

        "bandwidth-file-headers" => BANDWIDTH_FILE_HEADERS,

        "bandwidth-file-digest" => BANDWIDTH_FILE_DIGEST,

        // "package" is now ignored.

        // header in consensus, voter section in vote?

        "shared-rand-previous-value" => SHARED_RAND_PREVIOUS_VALUE,

        "shared-rand-current-value" => SHARED_RAND_CURRENT_VALUE,

        // Voter section (both)

        "dir-source" => DIR_SOURCE,

        "contact" => CONTACT,

        // voter section (vote, but not consensus)

        "legacy-dir-key" => LEGACY_DIR_KEY,

        "shared-rand-participate" => SHARED_RAND_PARTICIPATE,

        "shared-rand-commit" => SHARED_RAND_COMMIT,

        // voter section (consensus, but not vote)

        "vote-digest" => VOTE_DIGEST,

        // voter cert beginning (but only the beginning)

        "dir-key-certificate-version" => DIR_KEY_CERTIFICATE_VERSION,

        // routerstatus

        "r" => RS_R,

        "a" => RS_A,

        "s" => RS_S,

        "v" => RS_V,

        "pr" => RS_PR,

        "w" => RS_W,

        "p" => RS_P,

        "m" => RS_M,

        "id" => RS_ID,

        // footer

        "directory-footer" => DIRECTORY_FOOTER,

        "bandwidth-weights" => BANDWIDTH_WEIGHTS,

        "directory-signature" => DIRECTORY_SIGNATURE,

    }

}

/// Shared parts of rules for all kinds of netstatus headers

    use NetstatusKwd::*;

/// Rules for parsing the header of a consensus.

    use NetstatusKwd::*;

/*

/// Rules for parsing the header of a vote.

static NS_HEADER_RULES_VOTE: SectionRules<NetstatusKwd> = {

    use NetstatusKwd::*;

    let mut rules = NS_HEADER_RULES_COMMON_.clone();

    rules.add(CONSENSUS_METHODS.rule().args(1..));

    rules.add(FLAG_THRESHOLDS.rule());

    rules.add(BANDWIDTH_FILE_HEADERS.rule());

    rules.add(BANDWIDTH_FILE_DIGEST.rule().args(1..));

    rules.add(UNRECOGNIZED.rule().may_repeat().obj_optional());

    rules

};

/// Rules for parsing a single voter's information in a vote.

static NS_VOTERINFO_RULES_VOTE: SectionRules<NetstatusKwd> = {

    use NetstatusKwd::*;

    let mut rules = SectionRules::new();

    rules.add(DIR_SOURCE.rule().required().args(6..));

    rules.add(CONTACT.rule().required());

    rules.add(LEGACY_DIR_KEY.rule().args(1..));

    rules.add(SHARED_RAND_PARTICIPATE.rule().no_args());

    rules.add(SHARED_RAND_COMMIT.rule().may_repeat().args(4..));

    rules.add(SHARED_RAND_PREVIOUS_VALUE.rule().args(2..));

    rules.add(SHARED_RAND_CURRENT_VALUE.rule().args(2..));

    // then comes an entire cert: When we implement vote parsing,

    // we should use the authcert code for handling that.

    rules.add(UNRECOGNIZED.rule().may_repeat().obj_optional());

    rules

};

 */

/// Rules for parsing a single voter's information in a consensus

    use NetstatusKwd::*;

/// Shared rules for parsing a single routerstatus

static NS_ROUTERSTATUS_RULES_COMMON_: LazyLock<SectionRulesBuilder<NetstatusKwd>> =

        use NetstatusKwd::*;

/// Rules for parsing a single routerstatus in an NS consensus

    use NetstatusKwd::*;

/*

/// Rules for parsing a single routerstatus in a vote

static NS_ROUTERSTATUS_RULES_VOTE: SectionRules<NetstatusKwd> = {

    use NetstatusKwd::*;

        let mut rules = NS_ROUTERSTATUS_RULES_COMMON_.clone();

        rules.add(RS_R.rule().required().args(8..));

        rules.add(RS_M.rule().may_repeat().args(2..));

        rules.add(RS_ID.rule().may_repeat().args(2..)); // may-repeat?

        rules

    };

*/

/// Rules for parsing a single routerstatus in a microdesc consensus

    use NetstatusKwd::*;

/// Rules for parsing consensus fields from a footer.

    use NetstatusKwd::*;

impl ProtoStatus {

    /// Construct a ProtoStatus from two chosen keywords in a section.

        /// Helper: extract a Protocols entry from an item's arguments.

            } else {

            }

    /// Return the protocols that are listed as "required" in this `ProtoStatus`.

    ///

    /// Implementations may assume that relays on the network implement all the

    /// protocols in the relays' required-protocols list.  Implementations should

    /// refuse to start if they do not implement all the protocols on their own

    /// (client or relay) required-protocols list.

    /// Return the protocols that are listed as "recommended" in this `ProtoStatus`.

    ///

    /// Implementations should warn if they do not implement all the protocols

    /// on their own (client or relay) recommended-protocols list.

}

impl<T> std::str::FromStr for NetParams<T>

where

    T: std::str::FromStr,

    T::Err: std::error::Error,

{

    type Err = Error;

        /// Helper: parse a single K=V pair.

}

impl CommonHeader {

    /// Extract the CommonHeader members from a single header section.

        use NetstatusKwd::*;

        {

            // this unwrap is safe because if there is not at least one

            // token in the section, the section is unparsable.

            #[allow(clippy::unwrap_used)]

        }

        };

        } else {

        };

}

impl SharedRandStatus {

    /// Parse a current or previous shared rand value from a given

    /// SharedRandPreviousValue or SharedRandCurrentValue.

            _ => {

            }

        }

        // Added in proposal 342

    /// Return the actual shared random value.

    /// Return the timestamp (if any) associated with this `SharedRandValue`.

}

impl ConsensusHeader {

    /// Parse the ConsensusHeader members from a provided section.

        use NetstatusKwd::*;

        // We're ignoring KNOWN_FLAGS in the consensus.

}

impl DirSource {

    /// Parse a "dir-source" item

}

impl ConsensusVoterInfo {

    /// Parse a single ConsensusVoterInfo from a voter info section.

        use NetstatusKwd::*;

        // this unwrap should be safe because if there is not at least one

        // token in the section, the section is unparsable.

        #[allow(clippy::unwrap_used)]

}

impl std::str::FromStr for RelayFlags {

    type Err = void::Void;

        })

}

impl RelayFlags {

    /// Parse a relay-flags entry from an "s" line.

                    // Arguments out of order.