tor_netdoc/doc/netstatus/
each_variety.rs

1//! network status documents - items for all varieties, that vary
2//!
3//! **This file is reincluded multiple times**,
4//! by the macros in [`crate::doc::ns_variety_definition_macros`],
5//! once for votes, and once for each consensus flavour.
6//! It is *not* a module `crate::doc::netstatus::rs::each_variety`.
7//!
8//! Each time this file is included by one of the macros mentioned above,
9//! the `ns_***` macros (such as `ns_const_name!`) may expand to different values.
10//!
11//! See [`crate::doc::ns_variety_definition_macros`].
12
13use super::*;
14
15ns_use_this_variety! {
16    pub use [crate::doc::netstatus::rs]::?::{RouterStatus};
17}
18
19/// `network-status-version` intro item in a consensus
20///
21/// This is hard to parse because it's so irregular (even, ambiguous).
22///
23/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:network-status-version>
24///
25/// <https://spec.torproject.org/dir-spec/computing-consensus.html#flavor:microdesc>
26///
27/// <https://gitlab.torproject.org/tpo/core/torspec/-/work_items/359>
28#[derive(Clone, Debug, Deftly, Default)]
29#[derive_deftly(Constructor, ItemValueEncodable, ItemValueParseable)]
30#[allow(clippy::exhaustive_structs)]
31pub struct NetworkStatusVersionItem {
32    /// The version number, always `3`
33    pub version: NetworkStatusVersion,
34
35    /// The `flavor` argument
36    ///
37    ///  * In a plain consensus, this is an optional `ns`.
38    ///  * In an md consensus, this is always `microdesc`.
39    ///  * In a vote, there is no variety, but to avoid ambiguity, we reject.
40    pub variety: VarietyKeyword,
41
42    #[doc(hidden)]
43    #[deftly(netdoc(skip))]
44    pub __non_exhaustive: (),
45}
46
47/// The preamble of a network status document, except for the intro and `vote-status` items.
48///
49/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:preable>
50///
51/// **Does not include `network-status-version` and `vote-status`**.
52/// In the old parser this is not represented directly;
53/// instead, in `Consensus.flavor`, there's just the `ConsensusFlavor`.
54/// `parse2` doesn't (currently) support subdocuments which contain the parent's intro item
55/// (ie, `#[deftly(netdoc(flatten))]` is not supported on the first field.)
56//
57// TODO DIRAUTH this is missing some fields that need to be included in votes,
58// by dirauths, when voting.  They are not needed for calculating a consensus from votes.
59// there are individual TODO comments about each such defect.
60#[derive(Clone, Debug, Deftly)]
61#[derive_deftly(Constructor, NetdocEncodableFields, NetdocParseableFields)]
62#[allow(clippy::exhaustive_structs)]
63pub struct Preamble {
64    /// Consensus methods supported by this voter.
65    #[deftly(constructor)]
66    pub consensus_methods: ns_type!( NotPresent, NotPresent, ConsensusMethods ),
67
68    /// What "method" was used to produce this consensus?  (A
69    /// consensus method is a version number used by authorities to
70    /// upgrade the consensus algorithm.)
71    #[deftly(constructor)]
72    // Not #[deftly(netdoc(single_arg))] because that would mean a consensuses
73    // had an always-present singleton `consensus_method` item with no arguments.
74    pub consensus_method: ns_type!( (u32,), (u32,), NotPresent ),
75
76    /// Publication time (of a vote)
77    #[deftly(constructor)]
78    // Not #[deftly(netdoc(single_arg))] because that would mean a consensuses
79    // had an always-present singleton `published` item with no arguments.
80    pub published: ns_type!( NotPresent, NotPresent, (Iso8601TimeSp,) ),
81
82    /// Over what time is this consensus valid?  (For votes, this is
83    /// the time over which the voted-upon consensus should be valid.)
84    #[deftly(constructor)]
85    #[deftly(netdoc(flatten))]
86    pub lifetime: Lifetime,
87
88    /// How long in seconds should voters wait for votes and
89    /// signatures (respectively) to propagate?
90    pub voting_delay: Option<(u32, u32)>,
91
92    /// List of recommended Tor client versions.
93    #[deftly(constructor)]
94    #[deftly(netdoc(single_arg))]
95    pub client_versions: Vec<String>,
96
97    /// List of recommended Tor relay versions.
98    #[deftly(constructor)]
99    #[deftly(netdoc(single_arg))]
100    pub server_versions: Vec<String>,
101
102    /// Router flags which could be determined
103    #[deftly(constructor)]
104    #[deftly(netdoc(with = "relay_flags::ParserEncoder::<relay_flags::NoImplicitRepr>"))]
105    pub known_flags: DocRelayFlags,
106
107    // TODO DIRAUTH torspec#404 missing field: flag-thresholds (in votes)
108
109    /// Lists of recommended and required subprotocols.
110    ///
111    /// **`{recommended,required}-{client,relay}-protocols`**
112    #[deftly(constructor)]
113    #[deftly(netdoc(flatten))]
114    pub proto_statuses: Arc<ProtoStatuses>,
115
116    /// Declared parameters for tunable settings about how to the
117    /// network should operator. Some of these adjust timeouts and
118    /// whatnot; some features things on and off.
119    #[deftly(constructor)]
120    pub params: NetParams<i32>,
121
122    /// Global shared-random values
123    #[deftly(netdoc(flatten))]
124    pub shared_rand: ns_type!( SharedRandStatuses, SharedRandStatuses, NotPresent ),
125
126    // TODO DIRAUTH missing field: bandwidth-file-headers (in votes)
127    // TODO DIRAUTH missing field: bandwidth-file-digest (in votes)
128
129    #[doc(hidden)]
130    #[deftly(netdoc(skip))]
131    pub __non_exhaustive: (),
132}
133
134/// The footer of a network status document.
135///
136/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:footer>>
137#[derive(Clone, Debug, Deftly)]
138#[derive_deftly(Constructor, NetdocEncodable, NetdocParseable)]
139#[allow(clippy::exhaustive_structs)]
140pub struct Footer {
141    /// Intro item
142    ///
143    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:directory-footer>
144    pub directory_footer: (),
145
146    /// Fields that appear in consensuses (only)
147    #[deftly(constructor, netdoc(flatten))]
148    pub consensus: ns_type!(ConsensusFooterFields, ConsensusFooterFields, NotPresent),
149
150    #[doc(hidden)]
151    #[deftly(netdoc(skip))]
152    pub __non_exhaustive: (),
153}
154
155/// Signatures on a network status document
156#[derive(Deftly, Clone, Debug)]
157#[derive_deftly(NetdocParseableSignatures)]
158#[deftly(netdoc(signatures(hashes_accu = "DirectorySignaturesHashesAccu")))]
159#[non_exhaustive]
160pub struct NetworkStatusSignatures {
161    /// `directory-signature`s
162    pub directory_signature: ns_type!(Vec<Signature>, Vec<Signature>, Signature),
163}
tor_netdoc/doc/netstatus/each_variety.rs

tor_netdoc/doc/netstatus/
each_variety.rs
