Lines
99.57 %
Functions
33.59 %
Branches
100 %
//! consensus document builders - items that vary by consensus flavor
//!
//! **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_flavor`.
//! 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`].
ns_use_this_variety! {
use [crate::doc::netstatus::rs::build]::?::{RouterStatusBuilder};
use [crate::doc::netstatus::rs]::?::{RouterStatus};
}
#[cfg(not(doc))]
use [crate::doc::netstatus]::?::{Consensus, Preamble};
#[cfg(doc)]
pub use [crate::doc::netstatus]::?::{Consensus, Preamble};
use super::*;
/// A builder object used to construct a consensus.
///
/// Create one of these with the [`Consensus::builder`] method.
/// This facility is only enabled when the crate is built with
/// the `build_docs` feature.
#[cfg_attr(docsrs, doc(cfg(feature = "build_docs")))]
pub struct ConsensusBuilder {
/// See [`Consensus::flavor`]
flavor: ConsensusFlavor,
/// See [`Preamble::lifetime`]
lifetime: Option<Lifetime>,
/// See [`Preamble::client_versions`]
client_versions: Vec<String>,
/// See [`Preamble::server_versions`]
server_versions: Vec<String>,
/// See [`Preamble::proto_statuses`]
client_protos: ProtoStatus,
relay_protos: ProtoStatus,
/// See [`Preamble::params`]
params: NetParams<i32>,
/// See [`Preamble::voting_delay`]
voting_delay: Option<(u32, u32)>,
/// See [`Preamble::consensus_method`]
consensus_method: Option<u32>,
/// See [`SharedRandStatuses::shared_rand_previous_value`]
shared_rand_previous_value: Option<SharedRandStatus>,
/// See [`SharedRandStatuses::shared_rand_current_value`]
shared_rand_current_value: Option<SharedRandStatus>,
/// See [`Consensus::voters`]
voters: Vec<ConsensusAuthorityEntry>,
/// See [`Consensus::relays`]
relays: Vec<RouterStatus>,
/// See [`ConsensusFooterFields::bandwidth_weights`]
weights: NetParams<i32>,
impl ConsensusBuilder {
/// Construct a new ConsensusBuilder object.
pub(crate) fn new(flavor: ConsensusFlavor) -> ConsensusBuilder {
ConsensusBuilder {
flavor,
lifetime: None,
client_versions: Vec::new(),
server_versions: Vec::new(),
client_protos: ProtoStatus::default(),
relay_protos: ProtoStatus::default(),
params: NetParams::new(),
voting_delay: None,
consensus_method: None,
shared_rand_previous_value: None,
shared_rand_current_value: None,
voters: Vec::new(),
relays: Vec::new(),
weights: NetParams::new(),
/// Set the lifetime of this consensus.
/// This value is required.
pub fn lifetime(&mut self, lifetime: Lifetime) -> &mut Self {
self.lifetime = Some(lifetime);
self
/// Add a single recommended Tor client version to this consensus.
/// These values are optional for testing.
pub fn add_client_version(&mut self, ver: String) -> &mut Self {
self.client_versions.push(ver);
/// Add a single recommended Tor relay version to this consensus.
pub fn add_relay_version(&mut self, ver: String) -> &mut Self {
self.server_versions.push(ver);
/// Set the required client protocol versions for this consensus.
/// This value defaults to "no protocol versions required."
pub fn required_client_protos(&mut self, protos: Protocols) -> &mut Self {
self.client_protos.required = protos;
/// Set the recommended client protocol versions for this consensus.
/// This value defaults to "no protocol versions recommended."
pub fn recommended_client_protos(&mut self, protos: Protocols) -> &mut Self {
self.client_protos.recommended = protos;
/// Set the required relay protocol versions for this consensus.
pub fn required_relay_protos(&mut self, protos: Protocols) -> &mut Self {
self.relay_protos.required = protos;
pub fn recommended_relay_protos(&mut self, protos: Protocols) -> &mut Self {
self.relay_protos.recommended = protos;
/// Set the value for a given consensus parameter by name.
pub fn param<S>(&mut self, param: S, val: i32) -> &mut Self
where
S: Into<String>,
{
self.params.set(param.into(), val);
/// Set the voting delays (in seconds) for this consensus.
pub fn voting_delay(&mut self, vote_delay: u32, signature_delay: u32) -> &mut Self {
self.voting_delay = Some((vote_delay, signature_delay));
/// Set the declared consensus method for this consensus.
pub fn consensus_method(&mut self, consensus_method: u32) -> &mut Self {
self.consensus_method = Some(consensus_method);
/// Set the previous day's shared-random value for this consensus.
/// This value is optional.
pub fn shared_rand_prev(
&mut self,
n_reveals: u8,
value: SharedRandVal,
timestamp: Option<SystemTime>,
) -> &mut Self {
self.shared_rand_previous_value = Some(SharedRandStatus {
n_reveals,
value,
timestamp: timestamp.map(Iso8601TimeNoSp),
});
/// Set the current day's shared-random value for this consensus.
pub fn shared_rand_cur(
self.shared_rand_current_value = Some(SharedRandStatus {
/// Set a named weight parameter for this consensus.
pub fn weight<S>(&mut self, param: S, val: i32) -> &mut Self
self.weights.set(param.into(), val);
/// Replace all weight parameters for this consensus.
pub fn weights(&mut self, weights: NetParams<i32>) -> &mut Self {
self.weights = weights;
/// Create a VoterInfoBuilder to add a voter to this builder.
/// In theory these are required, but nothing asks for them.
pub fn voter(&self) -> VoterInfoBuilder {
VoterInfoBuilder::new()
/// Insert a single routerstatus into this builder.
pub(crate) fn add_rs(&mut self, rs: RouterStatus) -> &mut Self {
self.relays.push(rs);
/// Create a RouterStatusBuilder to add a RouterStatus to this builder.
/// You can make a consensus with no RouterStatus entries, but it
/// won't actually be good for anything.
pub fn rs(&self) -> RouterStatusBuilder {
RouterStatusBuilder::new()
/// Try to create a consensus object from this builder.
/// This object might not have all of the data that a valid
/// consensus would have. Therefore, it should only be used for
/// testing.
pub fn testing_consensus(&self) -> Result<Consensus> {
let lifetime = self
.lifetime
.as_ref()
.ok_or(Error::CannotBuild("Missing lifetime."))?
.clone();
let proto_statuses = Arc::new(ProtoStatuses {
client: self.client_protos.clone(),
relay: self.relay_protos.clone(),
let consensus_method = self
.consensus_method
.ok_or(Error::CannotBuild("Missing consensus method."))?;
let shared_rand = SharedRandStatuses {
shared_rand_previous_value: self.shared_rand_previous_value.clone(),
shared_rand_current_value: self.shared_rand_current_value.clone(),
__non_exhaustive: (),
};
let mk_versions = |v: &[String]| {
crate::doc::netstatus::RecommendedTorVersions::from_iter(v.iter())
.map_err(|_| crate::NetdocErrorKind::BadApiUsage.err())
let preamble = Preamble {
lifetime,
client_versions: mk_versions(&self.client_versions)?,
server_versions: mk_versions(&self.server_versions)?,
proto_statuses,
params: self.params.clone(),
voting_delay: self.voting_delay,
consensus_method: (consensus_method,),
consensus_methods: NotPresent,
published: NotPresent,
known_flags: DocRelayFlags::new_empty_unknown_discarded(),
shared_rand,
let footer = ConsensusFooterFields {
bandwidth_weights: self.weights.clone(),
let mut relays = self.relays.clone();
relays.sort_by_key(|r| *r.rsa_identity());
// TODO: check for duplicates?
Ok(Consensus {
flavor: self.flavor,
preamble,
voters: self.voters.clone(),
relays,
footer,
})
/// Builder object for constructing a [`ConsensusAuthorityEntry`]
pub struct VoterInfoBuilder {
/// See [`DirSource::nickname`]
nickname: Option<String>,
/// See [`DirSource::identity`]
identity: Option<RsaIdentity>,
/// See [`DirSource::ip`]
ip: Option<IpAddr>,
/// See [`ConsensusAuthorityEntry::contact`]
contact: Option<String>,
/// See [`ConsensusAuthorityEntry::vote_digest`]
vote_digest: Vec<u8>,
/// See [`DirSource::or_port`]
or_port: u16,
/// See [`DirSource::dir_port`]
dir_port: u16,
impl VoterInfoBuilder {
/// Construct a new VoterInfoBuilder.
pub(crate) fn new() -> Self {
VoterInfoBuilder {
nickname: None,
identity: None,
ip: None,
contact: None,
vote_digest: Vec::new(),
or_port: 0,
dir_port: 0,
/// Set a nickname.
pub fn nickname(&mut self, nickname: String) -> &mut Self {
self.nickname = Some(nickname);
/// Set an RSA identity.
pub fn identity(&mut self, identity: RsaIdentity) -> &mut Self {
self.identity = Some(identity);
/// Set a IP-valued address.
pub fn ip(&mut self, ip: IpAddr) -> &mut Self {
self.ip = Some(ip);
/// Set a contact line for this voter.
pub fn contact(&mut self, contact: String) -> &mut Self {
self.contact = Some(contact);
/// Set the declared vote digest for this voter within a consensus.
pub fn vote_digest(&mut self, vote_digest: Vec<u8>) -> &mut Self {
self.vote_digest = vote_digest;
/// Set the declared OrPort for this voter.
pub fn or_port(&mut self, or_port: u16) -> &mut Self {
self.or_port = or_port;
/// Set the declared DirPort for this voter.
pub fn dir_port(&mut self, dir_port: u16) -> &mut Self {
self.dir_port = dir_port;
/// Add the voter that we've been building into the in-progress
/// consensus of `builder`.
pub fn build(&self, builder: &mut ConsensusBuilder) -> Result<()> {
let nickname = self
.nickname
.ok_or(Error::CannotBuild("Missing nickname"))?
.parse()
.map_err(|_| Error::CannotBuild("Invalid nickname"))?;
let identity = self
.identity
.ok_or(Error::CannotBuild("Missing identity"))?
.into();
let ip = self.ip.ok_or(Error::CannotBuild("Missing IP"))?;
let contact = self
.contact
.ok_or(Error::CannotBuild("Missing contact"))?
.map_err(|_| Error::CannotBuild("Invalid contact"))?;
if self.vote_digest.is_empty() {
return Err(Error::CannotBuild("Missing vote digest"));
let dir_source = DirSource {
nickname,
identity,
hostname: "deprecated-builder.invalid".parse().expect("statically valid"),
ip,
dir_port: self.dir_port,
or_port: self.or_port,
let info = ConsensusAuthorityEntry {
dir_source,
contact,
vote_digest: self.vote_digest.clone().into(),
builder.voters.push(info);
Ok(())
#[cfg(test)]
mod test {
// @@ begin test lint list maintained by maint/add_warning @@
#![allow(clippy::bool_assert_comparison)]
#![allow(clippy::clone_on_copy)]
#![allow(clippy::dbg_macro)]
#![allow(clippy::mixed_attributes_style)]
#![allow(clippy::print_stderr)]
#![allow(clippy::print_stdout)]
#![allow(clippy::single_char_pattern)]
#![allow(clippy::unwrap_used)]
#![allow(clippy::unchecked_time_subtraction)]
#![allow(clippy::useless_vec)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::string_slice)] // See arti#2571
//! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
use crate::types::relay_flags::RelayFlag;
use std::net::SocketAddr;
use web_time_compat::{Duration, SystemTime, SystemTimeExt};
#[test]
fn consensus() {
let now = SystemTime::get();
let one_hour = Duration::new(3600, 0);
let mut builder = crate::doc::netstatus::MdConsensus::builder();
builder
.lifetime(Lifetime::new(now, now + one_hour, now + 2 * one_hour).unwrap())
.add_client_version("0.4.5.8".into())
.add_relay_version("0.4.5.9".into())
.required_client_protos("DirCache=2 LinkAuth=3".parse().unwrap())
.required_relay_protos("DirCache=1".parse().unwrap())
.recommended_client_protos("DirCache=6".parse().unwrap())
.recommended_relay_protos("DirCache=5".parse().unwrap())
.param("wombat", 7)
.param("knish", 1212)
.voting_delay(7, 8)
.consensus_method(32)
.shared_rand_prev(1, SharedRandVal([b'x'; 32]), None)
.shared_rand_cur(1, SharedRandVal([b'y'; 32]), None)
.weight("Wxy", 303)
.weight("Wow", 999);
.voter()
.nickname("Fuzzy".into())
.identity([15; 20].into())
.ip("10.0.0.200".parse().unwrap())
.contact("admin@fuzzy.example.com".into())
.vote_digest((*b"1234").into())
.or_port(9001)
.dir_port(9101)
.build(&mut builder)
.unwrap();
.rs()
.nickname("Fred".into())
.identity([155; 20].into())
.add_or_port(SocketAddr::from(([10, 0, 0, 60], 9100)))
.add_or_port("[f00f::1]:9200".parse().unwrap())
.doc_digest([99; 32])
.set_flags(RelayFlag::Fast)
.add_flags(RelayFlag::Stable | RelayFlag::V2Dir)
.version("Arti 0.0.0".into())
.protos("DirCache=7".parse().unwrap())
.build_into(&mut builder)
let _cons = builder.testing_consensus().unwrap();
// TODO: Check actual members of `cons` above.