commonware_p2p/
lib.rs

1//! Communicate with authenticated peers over encrypted connections.
2//!
3//! # Status
4//!
5//! `commonware-p2p` is **ALPHA** software and is not yet recommended for production use. Developers should
6//! expect breaking changes and occasional instability.
7
8#![doc(
9    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
10    html_favicon_url = "https://commonware.xyz/favicon.ico"
11)]
12
13use bytes::Bytes;
14use commonware_cryptography::PublicKey;
15use commonware_utils::set::Ordered;
16use futures::channel::mpsc;
17use std::{error::Error as StdError, fmt::Debug, future::Future};
18
19pub mod authenticated;
20pub mod simulated;
21pub mod utils;
22
23/// Tuple representing a message received from a given public key.
24///
25/// This message is guaranteed to adhere to the configuration of the channel and
26/// will already be decrypted and authenticated.
27pub type Message<P> = (P, Bytes);
28
29/// Alias for identifying communication channels.
30pub type Channel = u64;
31
32/// Enum indicating the set of recipients to send a message to.
33#[derive(Clone, Debug)]
34pub enum Recipients<P: PublicKey> {
35    All,
36    Some(Vec<P>),
37    One(P),
38}
39
40/// Interface for sending messages to a set of recipients.
41pub trait Sender: Clone + Debug + Send + 'static {
42    /// Error that can occur when sending a message.
43    type Error: Debug + StdError + Send + Sync;
44
45    /// Public key type used to identify recipients.
46    type PublicKey: PublicKey;
47
48    /// Send a message to a set of recipients.
49    fn send(
50        &mut self,
51        recipients: Recipients<Self::PublicKey>,
52        message: Bytes,
53        priority: bool,
54    ) -> impl Future<Output = Result<Vec<Self::PublicKey>, Self::Error>> + Send;
55}
56
57/// Interface for receiving messages from arbitrary recipients.
58pub trait Receiver: Debug + Send + 'static {
59    /// Error that can occur when receiving a message.
60    type Error: Debug + StdError + Send + Sync;
61
62    /// Public key type used to identify recipients.
63    type PublicKey: PublicKey;
64
65    /// Receive a message from an arbitrary recipient.
66    fn recv(
67        &mut self,
68    ) -> impl Future<Output = Result<Message<Self::PublicKey>, Self::Error>> + Send;
69}
70
71/// Interface for registering new peer sets as well as fetching an ordered list of connected peers, given a set id.
72pub trait Manager: Debug + Clone + Send + 'static {
73    /// Public key type used to identify peers.
74    type PublicKey: PublicKey;
75
76    /// The type for the peer set in registration.
77    type Peers;
78
79    /// Update the peer set.
80    ///
81    /// The peer set ID passed to this function should be strictly managed, ideally matching the epoch
82    /// of the consensus engine. It must be monotonically increasing as new peer sets are registered.
83    fn update(&mut self, id: u64, peers: Self::Peers) -> impl Future<Output = ()> + Send;
84
85    /// Fetch the ordered set of peers for a given ID.
86    fn peer_set(
87        &mut self,
88        id: u64,
89    ) -> impl Future<Output = Option<Ordered<Self::PublicKey>>> + Send;
90
91    /// Subscribe to notifications when new peer sets are added.
92    ///
93    /// Returns a receiver that will receive the peer set ID whenever a new peer set
94    /// is registered via `update`.
95    #[allow(clippy::type_complexity)]
96    fn subscribe(
97        &mut self,
98    ) -> impl Future<
99        Output = mpsc::UnboundedReceiver<(u64, Ordered<Self::PublicKey>, Ordered<Self::PublicKey>)>,
100    > + Send;
101}
102
103/// Interface for blocking other peers.
104pub trait Blocker: Clone + Send + 'static {
105    /// Public key type used to identify peers.
106    type PublicKey: PublicKey;
107
108    /// Block a peer, disconnecting them if currently connected and preventing future connections.
109    fn block(&mut self, peer: Self::PublicKey) -> impl Future<Output = ()> + Send;
110}
commonware_p2p/lib.rs

commonware_p2p/
lib.rs
