Struct NetworkBuilder

pub struct NetworkBuilder<T> { /* private fields */ }

Builds an overlay network for peers grouped under the same network identifier.

All peers can subscribe to multiple topics in this overlay and hook into a data stream per topic where they’ll send and receive data.

Implementations

impl<T> NetworkBuilder<T>

where T: TopicQuery,

pub fn new(network_id: NetworkId) -> Self

Returns a new instance of NetworkBuilder using the given network identifier.

Networks must use the same identifier if they wish to successfully connect and share data.

pub fn from_config(config: Config) -> Self

Returns a new instance of NetworkBuilder using the given configuration.

pub fn bind_ip_v4(self, ip: Ipv4Addr) -> Self

Sets or overwrites the local IP for IPv4 sockets.

Default is 0.0.0.0 (UNSPECIFIED).

pub fn bind_port_v4(self, port: u16) -> Self

Sets or overwrites the local bind port for IPv4 sockets.

Default is 2022.

pub fn bind_ip_v6(self, ip: Ipv6Addr) -> Self

Sets or overwrites the local IP for IPv6 sockets.

Default is :: (UNSPECIFIED).

pub fn bind_port_v6(self, port: u16) -> Self

Sets or overwrites the local bind port for IPv6 sockets.

Default is 2023.

pub fn private_key(self, private_key: PrivateKey) -> Self

Sets or overwrites the private key.

If this value is not set, the NetworkBuilder will generate a new, random key when building the network.

pub fn relay(self, url: RelayUrl, stun_only: bool, stun_port: u16) -> Self

Sets the relay used by the local network to facilitate the establishment of direct connections.

Relay nodes are STUN servers which help in establishing a peer-to-peer connection if one or both of the peers are behind a NAT. The relay node might offer proxy functionality on top (via the Tailscale DERP protocol which is very similar to TURN) if the connection attempt fails, which will serve to relay the data in that case.

pub fn direct_address( self, node_id: PublicKey, addresses: Vec<SocketAddr>, relay_addr: Option<RelayUrl>, ) -> Self

Sets the direct address of a peer, identified by their public key (node id).

The direct address should be reachable without the aid of a STUN or TURN-based relay node. However, if the direct connection attempt might fail (for example, because of a NAT or Firewall), the relay node of that peer can be supplied to allow connecting to it via a fallback connection.

If no relay address is given but turns out to be required, we optimistically try to use our own relay node instead (if specified). This might still fail, as we can’t know if the peer is using the same relay node.

pub fn discovery(self, handler: impl Discovery + 'static) -> Self

Adds one or more discovery strategy, such as mDNS.

pub fn sync(self, config: SyncConfiguration<T>) -> Self

Sets the sync protocol and configuration.

Sync sessions will be automatically initiated with any known peers with whom we share topics of interest.

pub fn gossip(self, config: GossipConfig) -> Self

Sets the gossip configuration.

Configuration parameters define the behavior of the swarm membership (HyParView) and gossip broadcast (Plumtree) layers, as well as the maximum message size.

pub fn protocol( self, protocol_name: &'static [u8], handler: impl ProtocolHandler + 'static, ) -> Self

Adds additional, custom protocols for communication between two peers.

pub async fn build(self) -> Result<Network<T>>

where T: TopicQuery + TopicId + 'static,

Returns a handle to a newly-spawned instance of Network.

A peer-to-peer endpoint is created and bound to a QUIC socket, after which the gossip, engine and connection handlers are instantiated. A sync handler is also instantiated if a sync protocol is provided. Direct addresses for network peers are added to the engine from the address book and core protocols are registered.

After configuration and registration processes are complete, the network is spawned and an attempt is made to retrieve a direct address for a network peer so that a connection may be made. If no address is retrieved within the timeout limit, the network is shut down and an error is returned.

Trait Implementations

impl<T: Debug> Debug for NetworkBuilder<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.