Skip to content

Commit 89a75aa

Browse files
jpraynaudjpraynaud
committed
Add doc comments
1 parent 9ef5fc9 commit 89a75aa

File tree

8 files changed

+141
-89
lines changed

8 files changed

+141
-89
lines changed

‎mithril-relay/src/commands/relay.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ use mithril_common::StdResult;
44

55
use super::{AggregatorCommand, PassiveCommand, SignerCommand};
66

7+
/// The available sub-commands of the relay
78
#[derive(Subcommand, Debug, Clone)]
89
pub enum RelayCommands {
910
/// Run a relay for a Mithril aggregator
@@ -20,6 +21,7 @@ pub enum RelayCommands {
2021
}
2122

2223
impl RelayCommands {
24+
/// Execute the command
2325
pub async fn execute(&self, config_builder: ConfigBuilder<DefaultState>) -> StdResult<()> {
2426
match self {
2527
Self::Aggregator(cmd) => cmd.execute(config_builder).await,

‎mithril-relay/src/lib.rs‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1-
pub mod commands;
2-
pub mod p2p;
3-
pub mod relay;
1+
#![warn(missing_docs)]
2+
3+
//! Mithril relay modules
4+
5+
mod commands;
6+
mod p2p;
7+
mod relay;
48

59
pub use commands::RelayCommands;
610
pub use p2p::*;
7-
pub use relay::passive;
811
pub use relay::AggregatorRelay;
912
pub use relay::PassiveRelay;
1013
pub use relay::SignerRelay;
1114

15+
/// The topic name where signatures are published
1216
pub const MITHRIL_SIGNATURES_TOPIC_NAME: &str = "mithril/signatures";

‎mithril-relay/src/p2p/peer.rs‎

Lines changed: 84 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1+
#![allow(missing_docs)]
12
use anyhow::Context;
23
use libp2p::{
34
core::upgrade::Version,
45
futures::StreamExt,
56
gossipsub::{self, ValidationMode},
67
noise, ping,
7-
swarm::{self, DialError},
8+
swarm::{self, DialError, NetworkBehaviour},
89
tcp, yamux, Multiaddr, PeerId, Swarm, Transport,
910
};
1011
use mithril_common::{messages::RegisterSignatureMessage, StdResult};
@@ -13,40 +14,54 @@ use std::{collections::HashMap, time::Duration};
1314

1415
use crate::{PeerError, MITHRIL_SIGNATURES_TOPIC_NAME};
1516

16-
// We create a custom network behaviour that combines gossipsub and ping.
17-
#[derive(swarm::NetworkBehaviour)]
17+
/// Custom network behaviour
18+
#[derive(NetworkBehaviour)]
1819
pub struct PeerBehaviour {
1920
gossipsub: gossipsub::Behaviour,
2021
ping: ping::Behaviour,
2122
}
2223

24+
/// Peer event that is polled from the swarm
2325
#[derive(Debug)]
2426
pub enum PeerEvent {
27+
/// The peer is listening on an address
2528
ListeningOnAddr {
29+
/// Listening multi address
2630
address: Multiaddr,
2731
},
32+
/// The peer established a connection with another peer
2833
ConnectionEstablished {
34+
/// Remote peer id
2935
peer_id: PeerId,
3036
},
37+
/// The peer can not connect to another peer
3138
OutgoingConnectionError {
39+
/// Remote peer id
3240
peer_id: Option<PeerId>,
41+
/// Error that occurred when dialing the remote peer
3342
error: DialError,
3443
},
44+
/// The peer received a behaviour related event
3545
Behaviour {
46+
/// The behaviour event the peer received
3647
event: PeerBehaviourEvent,
3748
},
3849
}
3950

51+
/// The topic name of a P2P pubsub
4052
pub type TopicName = String;
4153

54+
/// A peer in the P2P network
4255
pub struct Peer {
43-
pub topics: HashMap<TopicName, gossipsub::IdentTopic>,
44-
pub swarm: Option<Swarm<PeerBehaviour>>,
45-
pub addr: Multiaddr,
56+
topics: HashMap<TopicName, gossipsub::IdentTopic>,
57+
swarm: Option<Swarm<PeerBehaviour>>,
58+
addr: Multiaddr,
59+
/// Multi address on which the peer is listening
4660
pub addr_peer: Option<Multiaddr>,
4761
}
4862

4963
impl Peer {
64+
/// Peer factory
5065
pub fn new(addr: &Multiaddr) -> Self {
5166
Self {
5267
topics: Self::build_topics(),
@@ -63,64 +78,7 @@ impl Peer {
6378
)])
6479
}
6580

66-
pub fn publish_signature(
67-
&mut self,
68-
message: &RegisterSignatureMessage,
69-
) -> StdResult<gossipsub::MessageId> {
70-
let topic = self
71-
.topics
72-
.get(MITHRIL_SIGNATURES_TOPIC_NAME)
73-
.ok_or(PeerError::MissingTopic())
74-
.with_context(|| "Can not publish signature on invalid topic")?
75-
.to_owned();
76-
let data = serde_json::to_vec(message)
77-
.with_context(|| "Can not publish signature with invalid format")?;
78-
79-
let message_id = self
80-
.swarm
81-
.as_mut()
82-
.map(|swarm| swarm.behaviour_mut().gossipsub.publish(topic, data))
83-
.transpose()
84-
.with_context(|| "Can not publish signature on P2P pubsub")?
85-
.ok_or(PeerError::UnavailableSwarm())
86-
.with_context(|| "Can not publish signature without swarm")?;
87-
Ok(message_id.to_owned())
88-
}
89-
90-
pub async fn tick_swarm(&mut self) -> StdResult<Option<PeerEvent>> {
91-
debug!("Peer: reading next event"; "local_peer_id" => format!("{:?}", self.local_peer_id()));
92-
match self
93-
.swarm
94-
.as_mut()
95-
.ok_or(PeerError::UnavailableSwarm())
96-
.with_context(|| "Can not publish signature without swarm")?
97-
.next()
98-
.await
99-
{
100-
Some(swarm::SwarmEvent::NewListenAddr { address, .. }) => {
101-
debug!("Peer: received listening address event"; "address" => format!("{address:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
102-
Ok(Some(PeerEvent::ListeningOnAddr { address }))
103-
}
104-
Some(swarm::SwarmEvent::OutgoingConnectionError { peer_id, error, .. }) => {
105-
debug!("Peer: received outgoing connection error event"; "error" => format!("{error:#?}"), "remote_peer_id" => format!("{peer_id:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
106-
Ok(Some(PeerEvent::OutgoingConnectionError { peer_id, error }))
107-
}
108-
Some(swarm::SwarmEvent::ConnectionEstablished { peer_id, .. }) => {
109-
debug!("Peer: received connection established event"; "remote_peer_id" => format!("{peer_id:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
110-
Ok(Some(PeerEvent::ConnectionEstablished { peer_id }))
111-
}
112-
Some(swarm::SwarmEvent::Behaviour(event)) => {
113-
debug!("Peer: received behaviour event"; "event" => format!("{event:#?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
114-
Ok(Some(PeerEvent::Behaviour { event }))
115-
}
116-
Some(event) => {
117-
debug!("Peer: received other event"; "event" => format!("{event:#?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
118-
Ok(None)
119-
}
120-
_ => Ok(None),
121-
}
122-
}
123-
81+
/// Start the peer
12482
pub async fn start(mut self) -> StdResult<Self> {
12583
debug!("Peer: starting...");
12684
let mut swarm = libp2p::SwarmBuilder::with_new_identity()
@@ -175,13 +133,75 @@ impl Peer {
175133
Ok(self)
176134
}
177135

136+
/// Tick the peer swarm to receive the next event
137+
pub async fn tick_swarm(&mut self) -> StdResult<Option<PeerEvent>> {
138+
debug!("Peer: reading next event"; "local_peer_id" => format!("{:?}", self.local_peer_id()));
139+
match self
140+
.swarm
141+
.as_mut()
142+
.ok_or(PeerError::UnavailableSwarm())
143+
.with_context(|| "Can not publish signature without swarm")?
144+
.next()
145+
.await
146+
{
147+
Some(swarm::SwarmEvent::NewListenAddr { address, .. }) => {
148+
debug!("Peer: received listening address event"; "address" => format!("{address:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
149+
Ok(Some(PeerEvent::ListeningOnAddr { address }))
150+
}
151+
Some(swarm::SwarmEvent::OutgoingConnectionError { peer_id, error, .. }) => {
152+
debug!("Peer: received outgoing connection error event"; "error" => format!("{error:#?}"), "remote_peer_id" => format!("{peer_id:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
153+
Ok(Some(PeerEvent::OutgoingConnectionError { peer_id, error }))
154+
}
155+
Some(swarm::SwarmEvent::ConnectionEstablished { peer_id, .. }) => {
156+
debug!("Peer: received connection established event"; "remote_peer_id" => format!("{peer_id:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
157+
Ok(Some(PeerEvent::ConnectionEstablished { peer_id }))
158+
}
159+
Some(swarm::SwarmEvent::Behaviour(event)) => {
160+
debug!("Peer: received behaviour event"; "event" => format!("{event:#?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
161+
Ok(Some(PeerEvent::Behaviour { event }))
162+
}
163+
Some(event) => {
164+
debug!("Peer: received other event"; "event" => format!("{event:#?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
165+
Ok(None)
166+
}
167+
_ => Ok(None),
168+
}
169+
}
170+
171+
/// Publish a signature on the P2P pubsub
172+
pub fn publish_signature(
173+
&mut self,
174+
message: &RegisterSignatureMessage,
175+
) -> StdResult<gossipsub::MessageId> {
176+
let topic = self
177+
.topics
178+
.get(MITHRIL_SIGNATURES_TOPIC_NAME)
179+
.ok_or(PeerError::MissingTopic())
180+
.with_context(|| "Can not publish signature on invalid topic")?
181+
.to_owned();
182+
let data = serde_json::to_vec(message)
183+
.with_context(|| "Can not publish signature with invalid format")?;
184+
185+
let message_id = self
186+
.swarm
187+
.as_mut()
188+
.map(|swarm| swarm.behaviour_mut().gossipsub.publish(topic, data))
189+
.transpose()
190+
.with_context(|| "Can not publish signature on P2P pubsub")?
191+
.ok_or(PeerError::UnavailableSwarm())
192+
.with_context(|| "Can not publish signature without swarm")?;
193+
Ok(message_id.to_owned())
194+
}
195+
196+
/// Connect to a remote peer
178197
pub fn dial(&mut self, addr: Multiaddr) -> StdResult<()> {
179198
debug!("Peer: dialing to"; "address" => format!("{addr:?}"), "local_peer_id" => format!("{:?}", self.local_peer_id()));
180199
self.swarm.as_mut().unwrap().dial(addr)?;
181200

182201
Ok(())
183202
}
184203

204+
/// Get the local peer id (if any)
185205
pub fn local_peer_id(&self) -> Option<PeerId> {
186206
self.swarm.as_ref().map(|s| s.local_peer_id().to_owned())
187207
}

‎mithril-relay/src/relay/aggregator.rs‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,22 @@ use mithril_common::{messages::RegisterSignatureMessage, StdResult};
55
use reqwest::StatusCode;
66
use slog_scope::{error, info};
77

8+
/// A relay for a Mithril aggregator
89
pub struct AggregatorRelay {
910
aggregator_endpoint: String,
10-
pub peer: Peer,
11+
peer: Peer,
1112
}
1213

1314
impl AggregatorRelay {
15+
/// Start a relay for a Mithril aggregator
1416
pub async fn start(addr: &Multiaddr, aggregator_endpoint: &str) -> StdResult<Self> {
1517
Ok(Self {
1618
aggregator_endpoint: aggregator_endpoint.to_owned(),
1719
peer: Peer::new(addr).start().await?,
1820
})
1921
}
2022

21-
pub fn convert_peer_event_to_signature_message(
23+
fn convert_peer_event_to_signature_message(
2224
&mut self,
2325
event: PeerEvent,
2426
) -> StdResult<Option<RegisterSignatureMessage>> {
@@ -30,7 +32,7 @@ impl AggregatorRelay {
3032
}
3133
}
3234

33-
pub async fn notify_signature_to_aggregator(
35+
async fn notify_signature_to_aggregator(
3436
&self,
3537
signature_message: &RegisterSignatureMessage,
3638
) -> StdResult<()> {
@@ -58,6 +60,7 @@ impl AggregatorRelay {
5860
}
5961
}
6062

63+
/// Tick the aggregator relay
6164
pub async fn tick(&mut self) -> StdResult<()> {
6265
if let Some(peer_event) = self.peer.tick_swarm().await? {
6366
if let Ok(Some(signature_message_received)) =
@@ -71,14 +74,18 @@ impl AggregatorRelay {
7174
Ok(())
7275
}
7376

74-
pub async fn tick_peer(&mut self) -> StdResult<Option<PeerEvent>> {
77+
/// Tick the peer of the aggregator relay
78+
#[allow(dead_code)]
79+
pub(crate) async fn tick_peer(&mut self) -> StdResult<Option<PeerEvent>> {
7580
self.peer.tick_swarm().await
7681
}
7782

83+
/// Connect to a remote peer
7884
pub fn dial_peer(&mut self, addr: Multiaddr) -> StdResult<()> {
7985
self.peer.dial(addr)
8086
}
8187

88+
/// Retrieve address on which the peer is listening
8289
pub fn peer_address(&self) -> Option<Multiaddr> {
8390
self.peer.addr_peer.to_owned()
8491
}

‎mithril-relay/src/relay/mod.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
pub mod aggregator;
2-
pub mod passive;
3-
pub mod signer;
1+
mod aggregator;
2+
mod passive;
3+
mod signer;
44

55
pub use aggregator::AggregatorRelay;
66
pub use passive::PassiveRelay;

‎mithril-relay/src/relay/passive.rs‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,32 @@ use libp2p::{gossipsub, Multiaddr};
33
use mithril_common::{messages::RegisterSignatureMessage, StdResult};
44
use slog_scope::debug;
55

6+
/// A passive relay
67
pub struct PassiveRelay {
8+
/// Relay peer
9+
// TODO: should be private
710
pub peer: Peer,
811
}
912

1013
impl PassiveRelay {
14+
/// Create a passive relay
15+
/// TODO: should be replaced by Self::start(...)
1116
pub fn new(addr: &Multiaddr) -> Self {
1217
Self {
1318
peer: Peer::new(addr),
1419
}
1520
}
1621

22+
/// Start a passive relay
23+
pub async fn start(self) -> StdResult<Self> {
24+
debug!("PassiveRelay: starting...");
25+
Ok(Self {
26+
peer: self.peer.start().await?,
27+
})
28+
}
29+
30+
/// Convert event to signature message
31+
/// TODO: should be removed
1732
pub fn convert_event(
1833
&mut self,
1934
event: PeerEvent,
@@ -26,28 +41,25 @@ impl PassiveRelay {
2641
}
2742
}
2843

44+
/// Tick the passive relay
2945
pub async fn tick(&mut self) -> StdResult<()> {
3046
self.tick_peer().await?;
3147

3248
Ok(())
3349
}
3450

51+
/// Tick the peer of the passive relay
3552
pub async fn tick_peer(&mut self) -> StdResult<Option<PeerEvent>> {
3653
self.peer.tick_swarm().await
3754
}
3855

56+
/// Connect to a remote peer
3957
pub fn dial_peer(&mut self, addr: Multiaddr) -> StdResult<()> {
4058
self.peer.dial(addr)
4159
}
4260

43-
pub async fn start(self) -> StdResult<Self> {
44-
debug!("PassiveRelay: starting...");
45-
Ok(Self {
46-
peer: self.peer.start().await?,
47-
})
48-
}
49-
50-
pub fn address(&self) -> Option<Multiaddr> {
61+
/// Retrieve address on which the peer is listening
62+
pub fn peer_address(&self) -> Option<Multiaddr> {
5163
self.peer.addr_peer.to_owned()
5264
}
5365
}

0 commit comments

Comments
 (0)