tor-netdoc 0.41.0

Network document formats used with the Tor protocols.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

//! network status documents - items for all varieties, that vary
//!
//! **This file is reincluded multiple times**,
//! by the macros in [`crate::doc::ns_variety_definition_macros`],
//! once for votes, and once for each consensus flavour.
//! It is *not* a module `crate::doc::netstatus::rs::each_variety`.
//!
//! Each time this file is included by one of the macros mentioned above,
//! the `ns_***` macros (such as `ns_const_name!`) may expand to different values.
//!
//! See [`crate::doc::ns_variety_definition_macros`].

use super::*;

ns_use_this_variety! {
    pub use [crate::doc::netstatus::rs]::?::{RouterStatus};
}

/// The preamble of a network status document, except for the intro and `vote-status` items.
///
/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:preable>
///
/// **Does not include `network-status-version` and `vote-status`**.
/// In the old parser this is not represented directly;
/// instead, in `Consensus.flavor`, there's just the `ConsensusFlavor`.
/// `parse2` doesn't (currently) support subdocuments which contain the parent's intro item
/// (ie, `#[deftly(netdoc(flatten))]` is not supported on the first field.)
//
// TODO DIRAUTH the *contents* of this struct is still wrong for votes,
// and is missing some consensus fields that need to be manipulated by dirauths;
// there are individual TODO comments about each such defect.
#[cfg_attr(
    feature = "parse2",
    derive(Deftly),
    derive_deftly(NetdocParseableFields),
)]
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct Preamble {
    /// Consensus methods supported by this voter.
    pub consensus_methods: ns_type!( NotPresent, NotPresent, ConsensusMethods ),

    /// 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(feature = "parse2", deftly(netdoc(single_arg)))]
    pub consensus_method: ns_type!( u32, u32, NotPresent ),

    /// Publication time (of a vote)
    #[cfg_attr(feature = "parse2", deftly(netdoc(single_arg)))]
    pub published: ns_type!( NotPresent, NotPresent, Iso8601TimeSp ),

    /// Over what time is this consensus valid?  (For votes, this is
    /// the time over which the voted-upon consensus should be valid.)
    #[cfg_attr(feature = "parse2", deftly(netdoc(flatten)))]
    pub lifetime: Lifetime,

    /// How long in seconds should voters wait for votes and
    /// signatures (respectively) to propagate?
    pub voting_delay: Option<(u32, u32)>,

    /// List of recommended Tor client versions.
    #[cfg_attr(feature = "parse2", deftly(netdoc(single_arg)))]
    pub client_versions: Vec<String>,

    /// List of recommended Tor relay versions.
    #[cfg_attr(feature = "parse2", deftly(netdoc(single_arg)))]
    pub server_versions: Vec<String>,

    // TODO DIRAUTH missing field: known-flags (in consensuses too, not just votes)
    // TODO DIRAUTH missing field: flag-thresholds (in votes)

    /// Lists of recommended and required subprotocols.
    ///
    /// **`{recommended,required}-{client,relay}-protocols`**
    #[cfg_attr(feature = "parse2", deftly(netdoc(flatten)))]
    pub 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.
    pub params: NetParams<i32>,

    /// Global shared-random value for the previous shared-random period.
    // TODO DIRAUTH in votes, is in the authority section
    pub shared_rand_previous_value: Option<SharedRandStatus>,

    /// Global shared-random value for the current shared-random period.
    // TODO DIRAUTH in votes, is in the authority section
    pub shared_rand_current_value: Option<SharedRandStatus>,

    // TODO DIRAUTH missing field: bandwidth-file-headers (in votes)
    // TODO DIRAUTH missing field: bandwidth-file-digest (in votes)
}