//! Types used to parse arguments of entries in a directory document.

//!

//! There are some types that are pretty common, like "ISOTime",

//! "base64-encoded data", and so on.

//!

//! These types shouldn't be exposed outside of the netdoc crate.

pub use b16impl::*;

pub use b64impl::*;

pub use contact_info::*;

pub use curve25519impl::*;

pub use ed25519impl::*;

pub use edcert::*;

pub use fingerprint::*;

pub use hostname::*;

pub use rsa::*;

pub use timeimpl::*;

pub use nickname::{InvalidNickname, Nickname};

pub use boolean::NumericBoolean;

pub use fingerprint::{Base64Fingerprint, Fingerprint};

pub use identified_digest::{DigestName, IdentifiedDigest};

pub use ignored_impl::{

    Ignored, IgnoredItemOrObjectValue, ItemPresent, NoMoreArguments, NotPresent,

    NotPresentEachValue,

};

use crate::NormalItemArgument;

use crate::encode::{

    self,

    ItemArgument,

    ItemEncoder,

    ItemObjectEncodable,

    ItemValueEncodable,

    // `E` for "encode`; different from `parse2::MultiplicitySelector`

    MultiplicitySelector as EMultiplicitySelector,

    NetdocEncoder,

};

use crate::parse2::{

    self, ArgumentError, ArgumentStream, ItemArgumentParseable, ItemObjectParseable,

    ItemValueParseable, SignatureHashInputs, SignatureItemParseable, UnparsedItem,

    multiplicity::{

        ArgumentSetMethods,

        ItemSetMethods,

        // `P2` for "parse2`; different from `encode::MultiplicitySelector`

        MultiplicitySelector as P2MultiplicitySelector,

        ObjectSetMethods,

    },

    sig_hashes::Sha1WholeKeywordLine,

};

use derive_deftly::{Deftly, define_derive_deftly, define_derive_deftly_module};

use digest::Digest as _;

use educe::Educe;

use std::cmp::{self, Ordering, PartialOrd};

use std::fmt::{self, Display};

use std::iter;

use std::marker::PhantomData;

use std::ops::{Deref, DerefMut};

use std::result::Result as StdResult;

use std::str::FromStr;

use subtle::{Choice, ConstantTimeEq};

use tor_error::{Bug, ErrorReport as _, internal, into_internal};

use void::{ResultVoidExt as _, Void};

/// Describes a value that van be decoded from a bunch of bytes.

///

/// Used for decoding the objects between BEGIN and END tags.

pub(crate) trait FromBytes: Sized {

    /// Try to parse a value of this type from a byte slice

    fn from_bytes(b: &[u8], p: crate::Pos) -> crate::Result<Self>;

    /// Try to parse a value of this type from a vector of bytes,

    /// and consume that value

}

define_derive_deftly_module! {

    /// Implement conversion traits for a transparent newtype around bytes - shared code

    ///

    /// This is precisely `#[derive_deftly(Transparent)]`, but in the form of a deftly module,

    /// so that other derives (eg `BytesTransparent`) can re-use it.

    Transparent beta_deftly:

    // Expands to bullet points for "generated code", except omitting

    // `AsRef` & `AsMut` because some uses sites have additional impls of those,

    // which are best presented together in the docs.

  ${define TRANSPARENT_DOCS_IMPLS {

    ///  * impls of `Deref`, `DerefMut`

    ///  * impls of `From<field>` and "`Into`" (technically, `From<Self> for field`)

  }}

    // Expands to the implementations

  ${define TRANSPARENT_IMPLS {

  ${for fields {

    ${loop_exactly_1 "must be applied to a single-field struct"}

    impl<$tgens> From<$ftype> for $ttype {

            $vpat

        }

    }

    // TODO: This implementation is probably a bug, as it forbids to derive

    // Transparent on types like `struct Foo<T>(T)`, namely `T` not being

    // covered by something else, like `PhantomData<T>` or `Vec<T>`.

    impl<$tgens> From<$ttype> for $ftype {

            self_.$fname

        }

    }

    impl<$tgens> Deref for $ttype {

        type Target = $ftype;

            &self.$fname

        }

    }

    impl<$tgens> DerefMut for $ttype {

            &mut self.$fname

        }

    }

    impl<$tgens> AsRef<$ftype> for $ttype {

            &self.$fname

        }

    }

    impl<$tgens> AsMut<$ftype> for $ttype {

            &mut self.$fname

        }

    }

  }}

  }}

}

define_derive_deftly! {

    use Transparent;

    /// Implement conversion traits for an arbitrary transparent newtype

    ///

    /// # Requirements

    ///

    ///  * Self should be a single-field struct

    ///  * Self should have no runtime invariants

    ///

    /// # Generated code

    ///

    $TRANSPARENT_DOCS_IMPLS

    ///  * impls of `AsMut<field>`, `AsRef<field>`

    ///

    /// # Guidelines

    ///

    ///  * the field should be `pub`, with `#[allow(clippy::exhaustive_structs)]`

    ///  * derive `Hash`, `Debug` and (usually) `Clone`

    ///  * consider deriving `PartialEq` and `Eq`

    ///    but for types containing bytes, use [`ConstantTimeEq`],

    ///    eg with [`#[derive_deftly(BytesTransparent)]`](derive_deftly_template_BytesTransparent)

    ///    (instead of `Transparent`).

    ///  * implement `FromStr`, `Display`, `NormalItemArgument`, as required

    Transparent for struct, beta_deftly:

    $TRANSPARENT_IMPLS

}

define_derive_deftly! {

    use Transparent;

    /// Implement `ConstantTimeEq`, `.as_bytes()`, etc., for a transparent newtype around bytes

    ///

    /// # Requirements

    ///

    ///  * Self should be a single-field struct

    ///  * Self should deref to `&[u8]` (and to `&mut [u8]`).

    ///  * (so Self should have no runtime invariants)

    ///

    /// # Generated code

    ///

    ///  * impls of `ConstantTimeEq`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`

    ///  * `as_bytes()` method

    ${TRANSPARENT_DOCS_IMPLS}

    ///  * impls of `AsMut<field>`, `AsRef<field>`, `AsRef<[u8]>`, `AsMut<[u8]>`

    ///

    // We could derive Debug here but then we have to deal with the Fixed's N

    // which gets quite fiddly.

    //

    /// # Guidelines

    ///

    ///  * derive `Hash` and write `#[allow(clippy::derived_hash_with_manual_eq)]`

    ///  * impl `FromStr` and `Display` (if required, which they usually will be)

    ///  * derive `derive_more::Debug` eg with `#[debug(r#"B64("{self}")"#)]`

    ///  * `impl NormalItemArgument` if appropriate (ie the representation has no spaces)

    BytesTransparent for struct, beta_deftly:

    $TRANSPARENT_IMPLS

    impl<$tgens> ConstantTimeEq for $ttype {

          $(

          )

    }

    $/// `$tname` is `Eq` via its constant-time implementation.

    impl<$tgens> PartialEq for $ttype {

    }

    impl<$tgens> Eq for $ttype {}

    impl<$tgens> PartialOrd for $ttype {

    }

    impl<$tgens> Ord for $ttype {

          $(

          )

    }

    impl<$tgens> $ttype {

        /// Return the byte array from this object.

          $(

          )

    }

    impl<$tgens> AsRef<[u8]> for $ttype {

          $(

          )

    }

    impl<$tgens> AsMut<[u8]> for $ttype {

          $(

          )

    }

}

/// Types for decoding base64-encoded values.

mod b64impl {

    use super::*;

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

    use base64ct::{Base64, Base64Unpadded, Encoding};

    use std::ops::RangeBounds;

    /// A byte array, encoded in base64 with optional padding.

    ///

    /// On output (`Display`), output is unpadded.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B64("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B64(pub Vec<u8>);

    impl FromStr for B64 {

        type Err = Error;

            };

    }

    impl Display for B64 {

    }

    impl B64 {

        /// Return this object if its length is within the provided bounds

        /// object, or an error otherwise.

            } else {

            }

        /// Try to convert this object into an array of N bytes.

        ///

        /// Return an error if the length is wrong.

    }

    impl FromIterator<u8> for B64 {

    }

    impl NormalItemArgument for B64 {}

    /// A byte array encoded in a hexadecimal with a fixed length.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"FixedB64::<{N}>("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct FixedB64<const N: usize>(pub [u8; N]);

    impl<const N: usize> Display for FixedB64<N> {

    }

    impl<const N: usize> FromStr for FixedB64<N> {

        type Err = Error;

    }

    impl<const N: usize> NormalItemArgument for FixedB64<N> {}

}

// ============================================================

/// Types for decoding hex-encoded values.

mod b16impl {

    use super::*;

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

    /// A byte array encoded in hexadecimal; prints in lowercase

    ///

    /// Both uppercase and lowercase are tolerated when parsing.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B16("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B16(pub Vec<u8>);

    /// A byte array encoded in hexadecimal; prints in uppercase

    ///

    /// Both uppercase and lowercase are tolerated when parsing.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B16U("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B16U(pub Vec<u8>);

    /// A fixed-length version of [`B16U`].

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"FixedB16U("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct FixedB16U<const N: usize>(pub [u8; N]);

    impl FromStr for B16 {

        type Err = Error;

    }

    impl FromStr for B16U {

        type Err = Error;

    }

    impl<const N: usize> FromStr for FixedB16U<N> {

        type Err = Error;

    }

    /// Write `b` to `f` in hex uppercase

    // `hex` has `hex::encode_upper` but that allocates a `String`

        }

    impl Display for B16 {

            // `hex` has `hex::encode` but that allocates a `String`, which this approach doesn't

            }

    }

    impl Display for B16U {

    }

    impl<const N: usize> Display for FixedB16U<N> {

    }

    impl NormalItemArgument for B16 {}

    impl NormalItemArgument for B16U {}

    impl<const N: usize> NormalItemArgument for FixedB16U<N> {}

}

// ============================================================

/// Types for decoding curve25519 keys

mod curve25519impl {

    use super::*;

    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};

    use tor_llcrypto::pk::curve25519::PublicKey;

    /// A Curve25519 public key, encoded in base64 with optional padding

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Curve25519Public(pub PublicKey);

    impl FromStr for Curve25519Public {

        type Err = Error;

    }

    impl Display for Curve25519Public {

    }

    impl NormalItemArgument for Curve25519Public {}

}

// ============================================================

/// Types for decoding ed25519 keys

mod ed25519impl {

    use super::*;

    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};

    use derive_deftly::Deftly;

    use tor_llcrypto::pk::ed25519::{Ed25519Identity, Signature};

    /// An alleged ed25519 public key, encoded in base64 with optional

    /// padding.

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Ed25519Public(pub Ed25519Identity);

    impl FromStr for Ed25519Public {

        type Err = Error;

    }

    impl Display for Ed25519Public {

    }

    impl NormalItemArgument for Ed25519Public {}

    /// Helper that checks for the presence of `ed25519`.

    #[derive(Debug, Clone, PartialEq, Eq, derive_more::Display, derive_more::FromStr)]

    #[display(rename_all = "lowercase")]

    #[from_str(rename_all = "lowercase")]

    #[allow(clippy::exhaustive_enums)]

    pub enum Ed25519AlgorithmString {

        /// Ed25519 encoded as `ed25519`.

        Ed25519,

    }

    impl NormalItemArgument for Ed25519AlgorithmString {}

    /// Ed25519 public key in the form `<keyword> id <base64>`

    ///

    ///  * `id` in microdescriptors:

    ///    <https://spec.torproject.org/dir-spec/computing-microdescriptors.html>

    ///

    ///  * `identity-ed25519` in routerdescs:

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

    ///

    ///  * `id` in votes' routerstatus entries:

    ///    <https://spec.torproject.org/dir-spec/consensus-formats.html#item:id>

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

    #[derive_deftly(ItemValueEncodable, ItemValueParseable)]

    #[non_exhaustive]

    pub struct Ed25519IdentityLine {

        /// Fixed magic identifier (`ed25519`) for this line.

        pub alg: Ed25519AlgorithmString,

        /// The actual Ed25519 identity.

        pub pk: Ed25519Public,

    }

    impl From<Ed25519Public> for Ed25519IdentityLine {

    }

    impl From<Ed25519Identity> for Ed25519IdentityLine {

    }

    impl ItemArgument for Signature {

    }

}

// ============================================================

/// Dummy types like [`Ignored`]

mod ignored_impl {

    use super::*;

    use crate::parse2::ErrorProblem as EP;

    use ArgumentError as AE;

    /// Part of a network document, that isn't actually there.

    ///

    /// Used as a standin in `ns_type!` calls in various netstatus `each_variety.rs`.

    /// The effect is as if the field were omitted from the containing type.

    ///

    ///  * When used as item(s) (ie, a field type when deriving `NetdocParseable\[Fields\]`):

    ///    **ignores any number** of items with that field's keyword during parsing,

    ///    and emits none during encoding.

    ///

    ///    (To *reject* documents containing this item, use `Option<Void>`,

    ///    but note that the spec says unknown items should be ignored,

    ///    which would normally include items which are merely missing from one variety.)

    ///

    ///  * When used as an argument (ie, a field type when deriving `ItemValueParseable`,

    ///    or with `netdoc(single_arg)`  when deriving `NetdocParseable\[Fields\]`):

    ///    consumes **no arguments** during parsing, and emits none during encoding.

    ///

    ///  * When used as an object field (ie, `netdoc(object)` when deriving `ItemValueParseable`):

    ///    **rejects** an object - failing the parse if one is present.

    ///    (Functions similarly to `Option<Void>`, but prefer `NotPresent` as it's clearer.)

    ///

    ///  * When used as a sub-document (ie, `netdoc(flatten)` when deriving a document trait),

    ///    it recognises, and encodes as, no fields.

    ///

    /// There are bespoke impls of the multiplicity traits

    /// `ItemSetMethods` and `ObjectSetMethods`:

    /// don't wrap this type in `Option` or `Vec`.

    //

    // TODO we'll need to implement ItemArgument etc., for encoding, too.

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

    #[allow(clippy::exhaustive_structs)]

    #[derive(Deftly)]

    #[derive_deftly(NetdocEncodableFields, NetdocParseableFields)]

    pub struct NotPresent;

    /// An individual value that is not present - placeholder type

    ///

    /// This is the "single" item type for encoding multiplicity

    /// (for Items, Arguments or Objects), for [`NotPresent`].

    ///

    /// It should not be used directly.

    ///

    /// During parsing, each "not present" item is ignored,

    /// but the multiplicity arrangements involve parsing each value

    /// and then passing the item value to [`ItemSetMethods::accumulate`]

    /// where (for [`NotPresentEachValue`]) it is discarded.

    /// Therefore this type must be inhabited; the item parser discards the unparsed item.

    ///

    /// During parsing of arguments, parsing is driven by

    /// [our `ArgumentSetMethods::parse_with`][`P2MultiplicitySelector::<NotPresent>::parse_with)

    /// which doesn't need to call any parser.

    /// So the [`ItemArgumentParseable`] implementation always throws an error.

    ///

    /// During parsing of objects, rejection is done by

    /// [`NotPresentEachValue::check_label`] (and `from_bytes`).

    ///

    /// For encoding, there is only one multiplicity system which

    /// will never call any encoding function, so the encoding functions all throw `Bug`.

    ///

    /// This type has a similar role to `IgnoredItemOrObjectValue`,

    /// but `NotPresentEachValue` is different in detail,

    /// and (unlike `Ignored`) must support arguments, not just items and objects.

    #[derive(Debug, Clone, Deftly)]

    #[non_exhaustive]

    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]

    pub struct NotPresentEachValue;

    /// Ignored part of a network document.

    ///

    /// With `parse2`, can be used as an item, object, or even flattened-fields.

    ///

    /// When deriving `parse2` traits, and a field is absent in a particular netstatus variety,

    /// use `ns_type!` with [`NotPresent`], rather than `Ignored`.

    ///

    /// During encoding as an Items or Objects, will be entirely omitted,

    /// via the multiplicity arrangements.

    ///

    /// Cannot be encoded as an Argument: if this is not the last

    /// Argument, we need something to put into the output document to avoid generating

    /// a document with the arguments out of step.  If it *is* the last argument,

    /// it could simply be omitted, since additional arguments are in any case ignored.

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

    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Ignored;

    /// An Item or Object that would be ignored during parsing and is omitted during encoding

    ///

    /// This is the "single" item type for encoding multiplicity for Items or Objects,

    /// for [`Ignored`].

    ///

    /// It should not be used directly.

    ///

    /// This type is uninhabited.

    pub struct IgnoredItemOrObjectValue(Void);

    /// Indicates that no further arguments are allowed in a network document Item line

    ///

    /// Unlike [`NotPresent`], this fails during parsing if there are any more arguments.

    ///

    /// Should appear only at the end of the argument list.

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

    #[allow(clippy::exhaustive_structs)]

    pub struct NoMoreArguments;

    /// An item that only matters in terms of presence of absence.

    ///

    /// Useful for items such as `tunnelled-dir-server` where the mere presence

    /// implies a truthful value.

    ///

    /// This wrapper implements [`ItemValueParseable`] and [`ItemValueEncodable`]

    /// rejecting all arguments and objects and just expecting/emitting the

    /// keyword (or not).

    ///

    /// # Examples

    ///

    /// The following shows an except from a hypothetical netdoc with a

    /// [`ItemPresent`] item.

    ///

    /// ```

    /// use derive_deftly::Deftly;

    /// use tor_netdoc::types::*;

    /// use tor_netdoc::parse2::*;

    /// use tor_netdoc::*;

    ///

    /// #[derive(Debug, Default)]

    /// struct Hello;

    ///

    /// #[derive(Deftly, Debug)]

    /// #[derive_deftly(NetdocParseable)]

    /// struct TestDoc {

    ///     intro: Ignored,

    ///     hello: Option<ItemPresent<Hello>>,

    /// }

    ///

    /// // hello is not present.

    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\n", "")).unwrap();

    /// assert!(doc.hello.is_none());

    ///

    /// // hello is present.

    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello\n", "")).unwrap();

    /// assert!(doc.hello.is_some());

    ///

    /// // hello has arguments which are ignored.

    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello world\n", "")).unwrap();

    /// assert!(doc.hello.is_some());

    ///

    /// // hello is present twice which is not allowed.

    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello\nhello\n", "")).unwrap_err();

    /// ```

    //

    // We cannot derive Transparent here, because it is not possible to

    // implement `From<ItemPresent<T>> for T` due to orphan rule.

    //

    // Otherwise, a downstream crate could for example implement

    // `From<ItemPresent<U>> for U` with `U` being a locally defined type,

    // leading to a conflicting implementation.  A solution would be to cover

    // `T` behind another generic type such as `PhantomData`, as this can't be

    // a type in a downstream crate, but that level of indirection feels wrong.

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

    //

    #[derive(

        derive_more::From,

        derive_more::Deref,

        derive_more::DerefMut,

        derive_more::AsRef,

        derive_more::AsMut,

    )]

    #[allow(clippy::exhaustive_structs)]

    pub struct ItemPresent<T: Default>(pub T);

    impl ItemSetMethods for P2MultiplicitySelector<NotPresent> {

        type Each = NotPresentEachValue;

        type Field = NotPresent;

    }

    impl ItemValueEncodable for NotPresentEachValue {

    }

    impl ArgumentSetMethods for P2MultiplicitySelector<NotPresent> {

        type Each = NotPresentEachValue;

        type Field = NotPresent;

        {

    }

    impl ItemArgument for NotPresentEachValue {

    }

    impl ItemArgumentParseable for NotPresentEachValue {

            // Not quite the right error, but we don't have an ArgumentError::Internal

    }

    impl ItemObjectEncodable for NotPresentEachValue {

    }

    impl ObjectSetMethods for P2MultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = NotPresentEachValue;

    }

    impl ItemObjectParseable for NotPresentEachValue {

    }

    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = NotPresentEachValue;

    }

    impl encode::OptionalityMethods for EMultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = NotPresentEachValue;

    }

    impl FromStr for Ignored {

        type Err = Void;

    }

    impl ItemArgumentParseable for Ignored {

    }

    impl ItemObjectParseable for Ignored {

            // allow any label

    }

    impl ObjectSetMethods for P2MultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = Ignored;

    }

    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = IgnoredItemOrObjectValue;

    }

    impl encode::OptionalityMethods for EMultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = IgnoredItemOrObjectValue;

    }

    impl ItemValueEncodable for IgnoredItemOrObjectValue {

        }

    }

    impl ItemObjectEncodable for IgnoredItemOrObjectValue {

        }

        }

    }

    impl ItemArgumentParseable for NoMoreArguments {

    }

    impl ItemArgument for NoMoreArguments {

    }

    impl<T: Default> ItemValueParseable for ItemPresent<T> {

    }

    impl<T: Default> ItemValueEncodable for ItemPresent<T> {

    }

}

// ============================================================

/// Information about unknown values, which may have been retained as a `T`

///

/// Won't grow additional variants - but, `Retained` is only included conditionally.

///

/// Also used in the form `Unknown<()>` to indicate whether unknown values *should* be retained.

///

/// ### Example

///

/// ```

/// # {

/// #![cfg(feature = "retain-unknown")]

///

/// use tor_netdoc::types::Unknown;

///

/// let mut unk: Unknown<Vec<String>> = Unknown::new_retained_default();

/// unk.with_mut_unknown(|u| u.push("something-we-found".into()));

/// assert_eq!(unk.into_retained().unwrap(), ["something-we-found"]);

/// # }

/// ```

///

/// ### Equality comparison, semantics

///

/// Two `Unknown` are consider equal if both have the same record of unknown values,

/// or if neither records unknown values at all.

///

/// `Unknown` is not `Eq` or `Ord` because we won't want to relate a `Discarded`

/// to a `Retained`.  That would be a logic error.  `partial_cmp` gives `None` for this.

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

#[allow(clippy::exhaustive_enums)] // this isn't going to change

pub enum Unknown<T> {

    /// The parsing discarded unknown values and they are no longer available.

    Discarded(PhantomData<T>),

    /// The document parsing retained (or should retain) unknown values.

    #[cfg(feature = "retain-unknown")]

    Retained(T),

}

impl<T> Unknown<T> {

    /// Create an `Unknown` which specifies that values were discarded (or should be)

    /// Map the `Retained`, if there is one

    /// Map the `Retained`, fallibly

            #[cfg(feature = "retain-unknown")]

        })

    /// Obtain an `Unknown` containing (maybe) a reference

            #[cfg(feature = "retain-unknown")]

        }

    /// Return the retained unknown data, giving `None` if none was saved

    ///

    /// This is the function for disregarding the possible previously existence

    /// of now-discarded unknown (unrecognised) information.

    ///

    /// Use [`into_retained`](Self::into_retained) if it would be a bug

    /// if unrecognised information had been previously discarded.

            #[cfg(feature = "retain-unknown")]

        }

    /// Obtain the `Retained` data

    ///

    /// Treats lack of retention as an internal error.

            #[cfg(feature = "retain-unknown")]

        }

    /// Start recording unknown information, with a default value for `T`

    #[cfg(feature = "retain-unknown")]

    {

    /// Update the `Retained`, if there is one

    ///

    /// Intended for use in parsing, when we encounter an unknown value.

    ///

    /// Not provided in `try_` form.  If you think you need this, instead, unconditionally

    /// parse and verify the unknown value, and then conditionally insert it with this function.

    /// Don't parse it conditionally - that would skip some validation.

            #[cfg(feature = "retain-unknown")]

        }

}

impl<T: PartialOrd> PartialOrd for Unknown<T> {

        use Unknown::*;

            #[cfg(feature = "retain-unknown")]

            #[cfg(feature = "retain-unknown")]

        }

}

// ============================================================

/// A finite floating point number

///

/// Suitable for `stats` items in voites' routerstatus entries:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:stats>

///

/// Invariants:

///

///  * Is finite.  (So not NaN or Inf.)  Might be denormal.

///

/// String representation:

///

///  * Parses any valid C-like notation.

///

///  * Never uses exponential notation to display.

///

///  * Output can be rather large, up to 326 characters!

///    This is a spec bug.  The spec forbids us from using exponential notation.

///    <https://gitlab.torproject.org/tpo/core/torspec/-/work_items/416>

///

/// We may to change this in the future to use exponentials notation for output.

/// See <https://gitlab.torproject.org/tpo/core/torspec/-/work_items/416>

//

// TODO torspec#416 Consider replacing our F64Finite with finite f64 newtype from some crate

//

// What a palaver!

//

// This type is here rather than in rs.rs, in case similar things appears in other documents.

#[derive(Debug, Copy, Clone, PartialEq, PartialOrd)] //

#[derive(derive_more::Deref, derive_more::Into, derive_more::Display)]

pub struct F64Finite(f64);

/// Error converting an [`F64Finite`] from an `f64`: the value wasn't finite

#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error, amplify::Getters)]

#[error("FP value {} ({bits:#x}) is not finite", f64::from_bits(self.bits))]

pub struct F64FiniteError {

    /// The raw bits (as from [`f64::to_bits`])

    //

    // We store it this way rather than as `f64` so that `Eq` etc. make sense.

    bits: u64,

}

impl TryFrom<f64> for F64Finite {

    type Error = F64FiniteError;

}

/// Error parsing [`F64Finite`] from a string

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

#[non_exhaustive]

pub enum F64FiniteParseError {

    /// Syntax error

    #[error("syntax error")]

    Syntax(#[from] std::num::ParseFloatError),

    /// Value is not finite

    #[error("bad value")]

    NotFinite(#[from] F64FiniteError),

}

impl FromStr for F64Finite {

    type Err = F64FiniteParseError;

}

impl Eq for F64Finite {}

#[allow(clippy::derive_ord_xor_partial_ord)]

impl Ord for F64Finite {

}

impl NormalItemArgument for F64Finite {}

// ============================================================

/// Known keyword (enum) value, or arbitrary string

///

/// `T` should be a `Copy` enum with unit variants.

/// It should have appropriate `FromStr` and `Display`,

/// as well as [`NormalItemArgument`], impls.

///

/// Then `KeywordOrString` will implement the same traits.

///

/// Unlike [`Unknown`], unknown values are always retained as strings.

//

// `RelayFlags` has machinery for parsing flags and retaining unknown values,

// but it uses `Unknown` to maybe discard unknown flags,

// and it is generally quite a lot more complicated.

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

#[allow(clippy::exhaustive_enums)] // this isn't going to change

pub enum KeywordOrString<T: Copy> {

    /// Known and recognised `T`

    Known(T),

    /// Unknown value in arbitrary syntax

    Unknown(String),

}

impl<T: Copy + NormalItemArgument> NormalItemArgument for KeywordOrString<T> {}

impl<T: Copy + Display> Display for KeywordOrString<T> {

        }

}

impl<T: Copy + FromStr> FromStr for KeywordOrString<T> {

    type Err = Void;

        })

}

// ============================================================

/// A sequence of `T` items, with their order retained

///

/// Normally when a `Vec<T>` appears in a network document,

/// we expect the items to be sortable - they must impl [`EncodeOrd`](encode::EncodeOrd).

/// When encoding, the output is always sorted.

///

/// *This* type retains the ordering.

///

/// Implements the [`encode`] and [`parse2`] item multiplicity traits.

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

#[educe(Default)]

#[derive_deftly(Transparent)]

#[allow(clippy::exhaustive_structs)]

pub struct RetainedOrderVec<T>(pub Vec<T>);

// ============================================================

/// Types for decoding times and dates

mod timeimpl {

    use super::*;

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

    use std::time::SystemTime;

    use time::{

        OffsetDateTime, PrimitiveDateTime, format_description::FormatItem,

        macros::format_description,

    };

    /// A wall-clock time, encoded in Iso8601 format with an intervening

    /// space between the date and time.

    ///

    /// (Example: "2020-10-09 17:38:12")

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Iso8601TimeSp(pub SystemTime);

    /// Formatting object for parsing the space-separated Iso8601 format.

    const ISO_8601SP_FMT: &[FormatItem] =

        format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");

    impl FromStr for Iso8601TimeSp {

        type Err = Error;

    }

    /// Formats a SystemTime according to the given format description

    ///

    /// Also converts any time::error::format to fmt::Error

    /// so that it can be unwrapped in the Display trait impl

    impl Display for Iso8601TimeSp {

    }

    /// A wall-clock time, encoded in ISO8601 format without an intervening

    /// space.

    ///

    /// This represents a specific UTC instant (ie an instant in global civil time).

    /// But it may not be able to represent leap seconds.

    ///

    /// The timezone is not included in the string representation; `+0000` is implicit.

    ///

    /// (Example: "2020-10-09T17:38:12")

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Iso8601TimeNoSp(pub SystemTime);

    /// Formatting object for parsing the space-separated Iso8601 format.

    const ISO_8601NOSP_FMT: &[FormatItem] =

        format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");

    impl FromStr for Iso8601TimeNoSp {

        type Err = Error;

    }

    impl Display for Iso8601TimeNoSp {

    }

    impl crate::NormalItemArgument for Iso8601TimeNoSp {}

}

/// Types for decoding RSA keys

mod rsa {

    use super::*;

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