hopr-api 1.6.0

Common high-level external and internal API traits used by hopr-lib to implement the HOPR protocol
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

use std::collections::HashSet;

use futures::{AsyncRead, AsyncWrite, Stream, future::BoxFuture};
use hopr_types::crypto::keypairs::OffchainKeypair;

use super::Health;
use crate::{Multiaddr, PeerId};

/// Type alias for a boxed function returning a boxed future.
pub type BoxedProcessFn = Box<dyn FnOnce() -> BoxFuture<'static, ()> + Send>;

/// Trait representing a read-only view of the network state.
pub trait NetworkView {
    /// Multiaddresses used for listening by the local node.
    fn listening_as(&self) -> HashSet<Multiaddr>;

    /// Translation of the peer into its known multiaddresses.
    fn multiaddress_of(&self, peer: &PeerId) -> Option<HashSet<Multiaddr>>;

    /// Peers collected by the network discovery mechanism.
    fn discovered_peers(&self) -> HashSet<PeerId>;

    /// Peers currently connected and tracked by the network.
    fn connected_peers(&self) -> HashSet<PeerId>;

    /// Peers currently connected and tracked by the network.
    fn is_connected(&self, peer: &PeerId) -> bool;

    /// Represents perceived health of the network.
    fn health(&self) -> Health;
}

/// Control object for the opening and receiving of network connections in the
/// form of network streams.
#[async_trait::async_trait]
pub trait NetworkStreamControl: std::fmt::Debug {
    fn accept(
        self,
    ) -> Result<impl Stream<Item = (PeerId, impl AsyncRead + AsyncWrite + Send)> + Send, impl std::error::Error>;

    async fn open(self, peer: PeerId) -> Result<impl AsyncRead + AsyncWrite + Send, impl std::error::Error>;
}

/// Builder for a network object that returns the network specified in
/// the `NetworkBuilder::Network` associated type.
#[async_trait::async_trait]
pub trait NetworkBuilder {
    type Network: NetworkView + NetworkStreamControl + Send + Sync + Clone + 'static;

    /// Build and return an instance of a network viewer along with a process to start
    /// and run the network component.
    async fn build(
        self,
        identity: &OffchainKeypair,
        my_multiaddresses: Vec<Multiaddr>,
        protocol: &'static str,
        allow_private_addresses: bool,
    ) -> Result<(Self::Network, BoxedProcessFn), impl std::error::Error>;
}