//!

//! A "router descriptor" is a signed statement that a relay makes

//! about itself, explaining its keys, its capabilities, its location,

//! and its status.

//!

//! Relays upload their router descriptors to authorities, which use

//! them to build consensus documents.  Old clients and relays used to

//! fetch and use router descriptors for all the relays, but nowadays they use

//! microdescriptors instead.

//!

//! Clients still use router descriptors when communicating with

//! bridges: since bridges are not passed through an authority,

//! clients accept their descriptors directly.

//!

//! For full information about the router descriptor format, see

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

//!

//! # Limitations

//!

//! TODO: This needs to get tested much more!

//!

//! TODO: This implementation can be memory-inefficient.  In practice,

//! it gets really expensive storing policy entries, family

//! descriptions, parsed keys, and things like that.  We will probably want to

//! de-duplicate those.

//!

//! TODO: There should be accessor functions for some or all of the

//! fields in RouterDesc.  I'm deferring those until I know what they

//! should be.

use crate::encode::{ItemEncoder, ItemValueEncodable};

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

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

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

use crate::parse2::{

    ArgumentError, ErrorProblem, ItemValueParseable, SignaturesData, UnparsedItem, VerifyFailed,

};

use crate::types::descriptor::*;

use crate::types::family::{RelayFamily, RelayFamilyIds};

use crate::types::policy::*;

use crate::types::version::TorVersion;

use crate::types::{EmbeddedCert, misc::*};

use crate::util::PeekableIterator;

use crate::{

    AllowAnnotations, Error, KeywordEncodable, NetdocErrorKind as EK, NormalItemArgument, Result,

};

use derive_deftly::Deftly;

use ll::pk::ed25519::Ed25519Identity;

use saturating_time::SaturatingTime;

use std::fmt::Display;

use std::sync::LazyLock;

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

use tor_basic_utils::intern::Intern;

use tor_cert::{CertType, KeyUnknownCert};

use tor_checkable::timed::{TimeRangeBound, TimeRangeBoundBuilder};

use tor_checkable::{Timebound, signed, timed};

use tor_error::{internal, into_internal};

use tor_llcrypto as ll;

use tor_llcrypto::pk::ed25519;

use tor_llcrypto::pk::keymanip::convert_curve25519_to_ed25519_public;

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

use digest::Digest;

/// Length of a router descriptor digest

pub const DOC_DIGEST_LEN: usize = 20;

/// The digest of a RouterDesc document, as reported in a NS consensus.

pub type RdDigest = [u8; DOC_DIGEST_LEN];

/// The digest of an ExtraInfo document, as reported in a RouterDesc.

pub type ExtraInfoDigest = [u8; DOC_DIGEST_LEN];

/// A router descriptor, with possible annotations.

#[non_exhaustive]

pub struct AnnotatedRouterDesc {

    /// Annotation for this router descriptor; possibly empty.

    pub ann: RouterAnnotation,

    /// Underlying router descriptor; signatures not checked yet.

    pub router: UncheckedRouterDesc,

}

/// Annotations about a router descriptor, as stored on disc.

#[derive(Default)]

#[non_exhaustive]

pub struct RouterAnnotation {

    /// Description of where we got this router descriptor

    pub source: Option<String>,

    /// When this descriptor was first downloaded.

    pub downloaded: Option<time::SystemTime>,

    /// Description of what we're willing to use this descriptor for.

    pub purpose: Option<String>,

}

/// Information about a relay, parsed from a router descriptor.

///

/// This type does not hold all the information in the router descriptor

///

/// # Limitations

///

/// See module documentation.

///

/// Additionally, some fields that from router descriptors are not yet

/// parsed: see the comments in ROUTER_BODY_RULES for information about those.

///

/// Before using this type to connect to a relay, you MUST check that

/// it is valid, using is_expired_at().

///

/// # Specification

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html>

#[derive(Clone, Debug, Deftly, PartialEq)]

#[derive_deftly(Constructor)]

#[derive_deftly(NetdocParseableUnverified, NetdocEncodable)]

#[allow(clippy::exhaustive_structs)]

pub struct RouterDesc {

    /// `router` --- Introduce a router descriptor.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:router>

    #[deftly(constructor)]

    pub router: RouterDescIntroItem,

    /// `identity-ed25519` --- Specify the router's ed25519 identity.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:identity-ed25519>

    #[deftly(constructor)]

    pub identity_ed25519: EmbeddedCert<Ed25519IdentityCert, KeyUnknownCert>,

    /// `master-key-ed25519` --- Redundantly specify the router's ed25519 identity.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:master-key-ed25519>

    #[deftly(netdoc(single_arg))]

    #[deftly(constructor)]

    pub master_key_ed25519: Ed25519Public,

    /// `bandwidth` --- Report router's network bandwidth.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:bandwidth>

    pub bandwidth: Bandwidth,

    /// `platform` --- Describe the platform on which this relay is running.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:platform>

    pub platform: Option<RelayPlatform>,

    /// `published` --- Time this descriptor (and extra-info) was generated.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:published>

    #[deftly(netdoc(single_arg))]

    #[deftly(constructor)]

    pub published: Iso8601TimeSp,

    /// `fingerprint` --- Redundant hash of ASN-1 encoding of router identity key.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:fingerprint>

    #[deftly(netdoc(single_arg))]

    pub fingerprint: Option<SpFingerprint>,

    /// `hibernating` --- Whether the relay is hibernating.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:hibernating>

    #[deftly(netdoc(single_arg, default(skip)))]

    pub hibernating: NumericBoolean,

    /// `uptime` --- How long this relay has been continously running

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:uptime>

    #[deftly(netdoc(single_arg))]

    pub uptime: Option<u64>,

    /// `ntor-onion-key` --- The circuit extension key.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:ntor-onion-key>

    #[deftly(netdoc(single_arg))]

    #[deftly(constructor)]

    pub ntor_onion_key: Curve25519Public,

    /// `ntor-onion-key-crosscert` --- Reverse cert by K_ntor on KP_relayid_ed

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:ntor-onion-key-crosscert>

    #[deftly(constructor)]

    pub ntor_onion_key_crosscert: NtorOnionKeyCrossCert,

    /// `signing-key` --- Obsolete RSA identity key.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:signing-key>

    #[deftly(constructor)]

    pub signing_key: ll::pk::rsa::PublicKey,

    /// `accept, reject` --- Exit policy.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:accept>

    // TODO: these polices can get bulky too. Perhaps we should

    // de-duplicate them too.

    // Not skipping the default here is probably desirable, as this field should

    // generally always be ended with a default policy (i.e. default accept,

    // default deny).

    #[deftly(netdoc(flatten))]

    pub ipv4_policy: AddrPolicy,

    /// `ipv6-policy` --- Exit plicy summary for IPv6

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:ipv6-policy>

    #[deftly(netdoc(default(skip)))]

    pub ipv6_policy: Intern<PortPolicy>,

    /// `overload-general` --- Relay is overloaded.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:overload-general>

    // TODO in OverloadGeneral use ConstantString (from !3985) for version

    pub overload_general: Option<OverloadGeneral>,

    /// `contact` --- Server administrator contact information.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:contact>

    pub contact: Option<ContactInfo>,

    /// `family` --- Group relays for the purpose of path selection.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:family>

    #[deftly(netdoc(default(skip)))]

    pub family: Intern<RelayFamily>,

    /// `family-cert` --- Prove membership in a relay family.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:family-cert>

    pub family_cert: RetainedOrderVec<EmbeddedCert<Ed25519FamilyCert, KeyUnknownCert>>,

    /// `caches-extra-info` --- Router provides extra-info as a dirmirror.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#caches-extra-info>

    pub caches_extra_info: Option<ItemPresent<CachesExtraInfoToken>>,

    /// `extra-info-digest` --- Hash of the extra-info document.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:extra-info-digest>

    pub extra_info_digest: Option<ExtraInfoDigests>,

    /// `hidden-service-dir` --- Declares this router to be a hidden service directory

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:hidden-service-dir>

    pub hidden_service_dir: Option<ItemPresent<HiddenServiceDirToken>>,

    /// `or-address` --- Alternative ORport address and port

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:or-address>

    #[deftly(netdoc(single_arg))]

    pub or_address: Vec<net::SocketAddr>,

    /// `tunnelled-dir-server` --- Accepts a `BEGIN_DIR` relay message.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#tunnelled-dir-server>

    pub tunnelled_dir_server: Option<ItemPresent<TunnelledDirServerToken>>,

    /// `proto` --- Subprotocol capabilities supported.

    ///

    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:proto>

    pub proto: tor_protover::Protocols,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// Signatures of a [`RouterDesc`].

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:router-sig-ed25519>

#[derive(Clone, Debug, PartialEq, Deftly)]

#[derive_deftly(NetdocParseableSignatures, NetdocEncodable)]

#[deftly(netdoc(signatures(hashes_accu = "RouterHashAccu")))]

#[non_exhaustive]

pub struct RouterDescSignatures {

    /// `router-sig-ed25519` --- Ed25519 signature

    ///

    /// Ed25519 signature by the Ed25519 signing key on the SHA-256 digest of

    /// the document prefixed by a magic up until and including the

    /// `router-sig-ed25519` keyword plus space.

    pub router_sig_ed25519: RouterSigEd25519,

    /// `router-signature` --- RSA signature

    ///

    /// * At end, exactly once.

    /// * RSA signature of the document, including `router-sig-ed25519`.

    pub router_signature: RouterSignature,

}

// TODO: Implement a .encode_sign() method.

impl RouterDescUnverified {

    /// Verifies a self-signed [`RouterDescUnverified`].

    ///

    /// This verification performs the following checks:

    /// * [`RouterDesc::identity_ed25519`] is validly signed.

    /// * [`RouterDesc::master_key_ed25519`] is as implied by [`RouterDesc::identity_ed25519`].

    /// * [`RouterDesc::fingerprint`] is as implied by [`RouterDesc::signing_key`].

    /// * [`RouterDesc::ntor_onion_key_crosscert`] is validly signed.

    /// * [`RouterDesc::signing_key`] has correct length and exponent.

    /// * All [`RouterDesc::family_cert`] elements are valid.

    /// * The inner and outer [`RouterDescSignatures`] are valid.

    ///

    /// The result will be a [`TimeRangeBound`] composed from the respective

    /// minimums and maximums found in the present certificates.  For the lower

    /// bound, [`RouterDesc::published`] will also be taken into account when

    /// determining the minimum.

    //

    // We deny the use of unused variables as a hint to use all TimeRangeBound

    // values obtained through a dangerous split.

    #[deny(unused_variables)]

            // Type annotations to make LSP happy.

            // Verify the ed25519 identity certificate.

            // This also includes a check for the master-key-ed25519.

            let Ed25519IdentityCert {

            // Keep track of the published value as lower time bound.

            // If set, ensure that the fingerprint equals to the signing key id.

            {

            // Verify the ntor-onion-key-crosscert.

            // For this, we also need to convert the X25519 ntor key to an Ed25519

            // key using convert_curve25519_to_ed25519_public().

                // Rust std turns false into 0 and true into 1.

            )

            // Verify that the signing key has the proper exponent and length.

            // TODO DIRAUTH: We want to enforce this type wise with parse2.

            // Verify all family certificates.

            }

            // Verify the actual outer document signatures.

            // VerifyFailed should be an okay error variant in case that the hashes

            // were not accumulated, as it is not possible to verify without a

            // hash.

}

/// Description of the software a relay is running.

///

/// `platform` line in a routerstatus.

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:platform>

// TODO: Move this to types/misc.rs.

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

#[non_exhaustive]

pub enum RelayPlatform {

    /// Software advertised to be some version of Tor, on some platform.

    Tor(TorVersion, Option<String>),

    /// Software not advertised to be Tor.

    Other(String),

}

/// Zero-sized token type for use in [`RouterDesc::caches_extra_info`].

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

#[non_exhaustive]

pub struct CachesExtraInfoToken;

/// Zero-sized token type for use in [`RouterDesc::hidden_service_dir`].

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

#[non_exhaustive]

pub struct HiddenServiceDirToken;

/// Zero-sized token type for use in [`RouterDesc::tunnelled_dir_server`].

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

#[non_exhaustive]

pub struct TunnelledDirServerToken;

impl std::str::FromStr for RelayPlatform {

    type Err = Error;

                }

            }

        } else {

        }

}

impl Display for RelayPlatform {

        }

}

impl ItemValueParseable for RelayPlatform {

}

impl ItemValueEncodable for RelayPlatform {

        // Adding a raw string is fine because this is effectively a free form

        // field.

}

/// Version argument found in an `overload-general` item.

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:overload-general>

#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, strum::EnumString, strum::Display)]

#[non_exhaustive]

pub enum OverloadGeneralVersion {

    /// Version 1, currently the only supported and specified one.

    #[strum(serialize = "1")]

    V1,

}

impl NormalItemArgument for OverloadGeneralVersion {}

/// The overload general type found in router descriptors.

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:overload-general>

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deftly)]

#[derive_deftly(ItemValueParseable, ItemValueEncodable)]

#[non_exhaustive]

pub struct OverloadGeneral {

    /// The version of the item.

    pub version: OverloadGeneralVersion,

    /// The timestamp since when the relay is overloaded.

    pub since: Iso8601TimeSp,

}

/// Introduction line of a router descriptor.

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:router>

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

#[derive_deftly(ItemValueParseable, ItemValueEncodable)]

#[non_exhaustive]

pub struct RouterDescIntroItem {

    /// A valid router [`Nickname`].

    pub nickname: Nickname,

    /// An IPv4 address in dotted-squad format.

    pub address: std::net::Ipv4Addr,

    /// The TCP port of the onion router.

    pub orport: u16,

    /// Legacy.

    pub socksport: u16,

    /// Legacy.

    pub dirport: u16,

}

/// Digest identifying the extra-info document.

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:extra-info-digest>

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

#[derive_deftly(ItemValueParseable, ItemValueEncodable)]

#[non_exhaustive]

pub struct ExtraInfoDigests {

    /// Mandatory SHA-1 of the signed data in base 16.

    pub sha1: FixedB16U<20>,

    /// Optional SHA-256 of the entire extra-info in base 64.

    pub sha2: Option<FixedB64<32>>,

}

/// Estimated bandwidth for a router.

///

/// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:bandwidth>

// Does not derive Ord because it only makes sense to order on a single

// field but not all.

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

#[derive_deftly(ItemValueParseable, ItemValueEncodable)]

#[non_exhaustive]

pub struct Bandwidth {

    /// The volume that the relay is willing to sustain over long periods.

    pub average: u64,

    /// The volume that the relay is willing to sustain in very short intervals.

    pub burst: u64,

    /// The estimate of the capacity this relay can handle.

    pub observed: u64,

}

/// Ntor onion key cross-certificate.

///

/// This struct contains an [`Ed25519NtorCrossCert`] alongside the `bit`

/// field required for converting the ntor X25519 key to an Ed25519 key.

///

/// # See Also

///

/// * [`Ed25519NtorCrossCert`]

/// * <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:ntor-onion-key-crosscert>

#[derive(Debug, Clone, Deftly, PartialEq)]

#[derive_deftly(ItemValueParseable, ItemValueEncodable)]

#[deftly(netdoc(no_extra_args))]

#[non_exhaustive]

pub struct NtorOnionKeyCrossCert {

    /// True if X coordinate of the ntor onion key is negative, false if

    /// positive.

    // TODO spec: This name is very unfortunate, how about we change it

    // to `is_negative`.  Also, using a boolean for storing a sign bit feels

    // wrong to me due to the zero edge case, which would not be negative,

    // but also not positive either.

    pub bit: NumericBoolean,

    /// The actual embedded ntor onion key certificate.

    #[deftly(netdoc(object))]

    pub cert: EmbeddedCert<Ed25519NtorCrossCert, KeyUnknownCert>,

}

decl_keyword! {

    /// RouterKwd is an instance of Keyword, used to denote the different

    /// Items that are recognized as appearing in a router descriptor.

    RouterKwd {

        annotation "@source" => ANN_SOURCE,

        annotation "@downloaded-at" => ANN_DOWNLOADED_AT,

        annotation "@purpose" => ANN_PURPOSE,

        "accept" | "reject" => POLICY,

        "bandwidth" => BANDWIDTH,

        "bridge-distribution-request" => BRIDGE_DISTRIBUTION_REQUEST,

        "caches-extra-info" => CACHES_EXTRA_INFO,

        "contact" => CONTACT,

        "extra-info-digest" => EXTRA_INFO_DIGEST,

        "family" => FAMILY,

        "family-cert" => FAMILY_CERT,

        "fingerprint" => FINGERPRINT,

        "hibernating" => HIBERNATING,

        "identity-ed25519" => IDENTITY_ED25519,

        "ipv6-policy" => IPV6_POLICY,

        "master-key-ed25519" => MASTER_KEY_ED25519,

        "ntor-onion-key" => NTOR_ONION_KEY,

        "ntor-onion-key-crosscert" => NTOR_ONION_KEY_CROSSCERT,

        "or-address" => OR_ADDRESS,

        "platform" => PLATFORM,

        "proto" => PROTO,

        "published" => PUBLISHED,

        "router" => ROUTER,

        "router-sig-ed25519" => ROUTER_SIG_ED25519,

        "router-signature" => ROUTER_SIGNATURE,

        "signing-key" => SIGNING_KEY,

        "tunnelled_dir_server" => TUNNELLED_DIR_SERVER,

        "uptime" => UPTIME,

        // "protocols" once existed, but is obsolete

        // "eventdns" once existed, but is obsolete

        // "allow-single-hop-exits" is also obsolete.

    }

}

/// Rules for parsing a set of router descriptor annotations.

    use RouterKwd::*;

    // Unrecognized annotations are fine; anything else is an error in this

    // context.

/// Rules for tokens that are allowed in the first part of a

/// router descriptor.

    use RouterKwd::*;

    // No other intervening tokens are permitted in the header.

/// Rules for  tokens that are allowed in the first part of a

/// router descriptor.

    use RouterKwd::*;

    );

    // TODO: these aren't parsed yet.  Only authorities use them.

    // TODO: this is ignored for now.

/// Rules for items that appear at the end of a router descriptor.

    use RouterKwd::*;

    // No intervening tokens are allowed in the footer.

impl RouterAnnotation {

    /// Extract a single RouterAnnotation (possibly empty) from a reader.

        use RouterKwd::*;

}

/// A parsed router descriptor whose signatures and/or validity times

/// may or may not be invalid.

pub type UncheckedRouterDesc = signed::SignatureGated<timed::TimeRangeBound<RouterDesc>>;

/// How long after its published time is a router descriptor officially

/// supposed to be usable?

const ROUTER_EXPIRY_SECONDS: u64 = 5 * 86400;

/// How long before its published time is a router descriptor usable?

// TODO(nickm): This valid doesn't match C tor, which only enforces this rule

// ("routers should not some from the future") at directory authorities, and

// there only enforces a 12-hour limit (`ROUTER_ALLOW_SKEW`).  Eventually we

// should probably harmonize these cutoffs.

const ROUTER_PRE_VALIDITY_SECONDS: u64 = 86400;

impl RouterDesc {

    /// Return a reference to this relay's RSA identity.

    /// Return a reference to this relay's Ed25519 identity.

    /// Return a reference to the list of subprotocol versions supported by this

    /// relay.

    /// Return a reference to this relay's Ntor onion key.

    /// Return the publication

    /// Return an iterator of every `SocketAddr` at which this descriptor says

    /// its relay can be reached.

        ))

    /// Return the declared family of this descriptor.

    /// Return the authenticated family IDs of this descriptor.

        )

    /// Helper: tokenize `s`, and divide it into three validated sections.

        use RouterKwd::*;

        // Parse everything up through the header.

        // Parse everything up to but not including the signature.

        // Parse the signature.

    /// Try to parse `s` as a router descriptor.

    ///

    /// Does not actually check liveness or signatures; you need to do that

    /// yourself before you can do the output.

    ///

    /// The following fields are not parsed with the legacy parser and their

    /// default value is used instead.

    /// * [`RouterDescIntroItem::socksport`] in [`RouterDesc::router`]

    /// * [`RouterDesc::bandwidth`]

    /// * [`RouterDesc::or_address`]

    ///     * Extracts only the first IPv6 address.

    /// * [`RouterDesc::hibernating`]

    /// * [`RouterDesc::overload_general`]

    /// * [`RouterDesc::contact`]

    /// * [`RouterDesc::extra_info_digest`]

    /// * [`RouterDesc::hidden_service_dir`]

        // We permit empty lines at the end of router descriptors, since there's

        // a known issue in Tor relays that causes them to return them this way.

    /// Helper: parse a router descriptor from `s`.

    ///

    /// This function does the same as parse(), but returns errors based on

    /// byte-wise positions.  The parse() function converts such errors

    /// into line-and-byte positions.

        // TODO: This function is too long!  The little "paragraphs" here

        // that parse one item at a time should be made into sub-functions.

        use RouterKwd::*;

        // Unwrap should be safe because inline `required` call should return

        // `Error::MissingToken` if `ROUTER` is not `Ok`

        #[allow(clippy::unwrap_used)]

        // ed25519 identity and signing key.

        //

        // Small digression: This is terrible.  We return a tuple containing

        // a KeyUnknownCert and an UncheckedCert.  This is because of a parse2

        // and legacy incongruence.  For parse2, we need the KeyUnknownCert

        // to properly include it into EmbeddedCert, whereas the legacy parser

        // will need an UncheckedCert because the verification chain is

        // performed at the end.  Because tor-cert's method all consume self,

        // we can not go backwards, meaning we have to store two separate

        // copies.  It is also not possible to do the conversion to

        // UncheckedCert later, because then we lose the error context returned

        // in EK::BadObjectVal if the signed-by extension is missing.

        //

            // Unwrap should be safe because above `required` call should

            // return `Error::MissingToken` if `IDENTITY_ED25519` is not `Ok`

            #[allow(clippy::unwrap_used)]

        };

        // master-key-ed25519: required, and should match certificate.

        #[allow(unexpected_cfgs)]

                #[cfg(not(fuzzing))] // No feature here; never omit in production.

        };

        // Legacy RSA identity

        // Unwrap should be safe because above `required` calls should return

        // an `Error::MissingToken` if `ROUTER_...` is not `Ok`

        #[allow(clippy::unwrap_used)]

        #[allow(clippy::unwrap_used)]

        // Extract ed25519 signature.

            );

        };

        // Extract legacy RSA signature.

            );

            // TODO: we need to accept prefixes here. COMPAT BLOCKER.

        };

        // router nickname ipv4addr orport socksport dirport

            (

                // Skipping socksport.

            )

        };

        // uptime

        // published time.

        // ntor key

        // ntor crosscert

            )

        };

        // List of subprotocol versions

        };

        // tunneled-dir-server

        // caches-extra-info

        // fingerprint: check for consistency with RSA identity.

        // Family

        };

        // Family ids (for "happy families")

        //

        // Unfortunately we have to store this as a tuple of KeyUnknownCert and

        // UncheckedCert due to a parse2/legacy incongruence.  parse2 requires

        // KeyUnknownCert for EmbeddedCert whereas the legacy parser needs

        // descendants of it obtained by passing it irreversibly through the

        // tor_cert verification chain.

        // or-address

        // Extract at most one ipv6 address from the list.  It's not great,

        // but it's what the legacy parser does.

            // We skip over unparsable addresses. Is that right?

        }

        // platform

        // ipv4_policy

                    _ => {

                    }

                };

            }

        };

        // ipv6 policy

            // Unwrap is safe here because str is not empty

            #[allow(clippy::unwrap_used)]

        };

        // Now we're going to collect signatures and expiration times.

        ];

        ];

        // As outlined above, we have to do this ... :/

        //

        // Composing the verified part of the EmbeddedCert by just extracting

        // the key alone is OK because it gets checked at the end anyways

        // due to the push to signatures and expirations.

                "Missing a public key that was previously there."

        }

        // Unwrap is safe here because `expirations` array is not empty

        #[allow(clippy::unwrap_used)]

}

/// An iterator that parses one or more (possibly annotated

/// router descriptors from a string.

//

// TODO: This is largely copy-pasted from MicrodescReader. Can/should they

// be merged?

pub struct RouterReader<'a> {

    /// True iff we accept annotations

    annotated: bool,

    /// Reader that we're extracting items from.

    reader: NetDocReader<'a, RouterKwd>,

}

/// Skip this reader forward until the next thing it reads looks like the

/// start of a router descriptor.

///

/// Used to recover from errors.

    use RouterKwd::*;

    loop {

            }

            None => {

            }

        }

    }

impl<'a> RouterReader<'a> {

    /// Construct a RouterReader to take router descriptors from a string.

    /// Extract an annotation from this reader.

        } else {

        }

    /// Extract an annotated router descriptor from this reader

    ///

    /// (internal helper; does not clean up on failures.)

    /// Extract an annotated router descriptor from this reader

    ///

    /// Ensure that at least one token is consumed