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/// The preamble of a network status document, except for the intro and `vote-status` items.
20///
21/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:preable>
22///
23/// **Does not include `network-status-version` and `vote-status`**.
24/// In the old parser this is not represented directly;
25/// instead, in `Consensus.flavor`, there's just the `ConsensusFlavor`.
26/// `parse2` doesn't (currently) support subdocuments which contain the parent's intro item
27/// (ie, `#[deftly(netdoc(flatten))]` is not supported on the first field.)
28//
29// TODO DIRAUTH the *contents* of this struct is still wrong for votes,
30// and is missing some consensus fields that need to be manipulated by dirauths;
31// there are individual TODO comments about each such defect.
32#[derive(Clone, Debug, Deftly)]
33#[derive_deftly(Constructor, NetdocEncodableFields, NetdocParseableFields)]
34#[allow(clippy::exhaustive_structs)]
35pub struct Preamble {
36    /// Consensus methods supported by this voter.
37    #[deftly(constructor)]
38    pub consensus_methods: ns_type!( NotPresent, NotPresent, ConsensusMethods ),
39
40    /// What "method" was used to produce this consensus?  (A
41    /// consensus method is a version number used by authorities to
42    /// upgrade the consensus algorithm.)
43    #[deftly(constructor)]
44    // Not #[deftly(netdoc(single_arg))] because that would mean a consensuses
45    // had an always-present singleton `consensus_method` item with no arguments.
46    pub consensus_method: ns_type!( (u32,), (u32,), NotPresent ),
47
48    /// Publication time (of a vote)
49    #[deftly(constructor)]
50    // Not #[deftly(netdoc(single_arg))] because that would mean a consensuses
51    // had an always-present singleton `published` item with no arguments.
52    pub published: ns_type!( NotPresent, NotPresent, (Iso8601TimeSp,) ),
53
54    /// Over what time is this consensus valid?  (For votes, this is
55    /// the time over which the voted-upon consensus should be valid.)
56    #[deftly(constructor)]
57    #[deftly(netdoc(flatten))]
58    pub lifetime: Lifetime,
59
60    /// How long in seconds should voters wait for votes and
61    /// signatures (respectively) to propagate?
62    pub voting_delay: Option<(u32, u32)>,
63
64    /// List of recommended Tor client versions.
65    #[deftly(constructor)]
66    #[deftly(netdoc(single_arg))]
67    pub client_versions: Vec<String>,
68
69    /// List of recommended Tor relay versions.
70    #[deftly(constructor)]
71    #[deftly(netdoc(single_arg))]
72    pub server_versions: Vec<String>,
73
74    /// Router flags which could be determined
75    #[deftly(constructor)]
76    #[deftly(netdoc(with = "relay_flags::ParserEncoder::<relay_flags::NoImplicitRepr>"))]
77    pub known_flags: DocRelayFlags,
78
79    // TODO DIRAUTH missing field: flag-thresholds (in votes)
80
81    /// Lists of recommended and required subprotocols.
82    ///
83    /// **`{recommended,required}-{client,relay}-protocols`**
84    #[deftly(constructor)]
85    #[deftly(netdoc(flatten))]
86    pub proto_statuses: Arc<ProtoStatuses>,
87
88    /// Declared parameters for tunable settings about how to the
89    /// network should operator. Some of these adjust timeouts and
90    /// whatnot; some features things on and off.
91    #[deftly(constructor)]
92    pub params: NetParams<i32>,
93
94    /// Global shared-random value for the previous shared-random period.
95    // TODO DIRAUTH in votes, is in the authority section
96    pub shared_rand_previous_value: Option<SharedRandStatus>,
97
98    /// Global shared-random value for the current shared-random period.
99    // TODO DIRAUTH in votes, is in the authority section
100    pub shared_rand_current_value: Option<SharedRandStatus>,
101
102    // TODO DIRAUTH missing field: bandwidth-file-headers (in votes)
103    // TODO DIRAUTH missing field: bandwidth-file-digest (in votes)
104
105    #[doc(hidden)]
106    #[deftly(netdoc(skip))]
107    pub __non_exhaustive: (),
108}
tor_netdoc/doc/netstatus/each_variety.rs

tor_netdoc/doc/netstatus/
each_variety.rs
