Struct swarm_discovery::Discoverer

pub struct Discoverer { /* private fields */ }

Builder for a swarm discovery service.

Example

use if_addrs::get_if_addrs;
use swarm_discovery::Discoverer;
use tokio::runtime::Builder;

// create Tokio runtime
let rt = Builder::new_multi_thread()
    .enable_all()
    .build()
    .expect("build runtime");

// make up some peer ID
let peer_id = "peer_id42".to_owned();

// get local addresses and make up some port
let addrs = get_if_addrs().unwrap().into_iter().map(|i| i.addr.ip()).collect::<Vec<_>>();
let port = 1234;

// start announcing and discovering
let _guard = Discoverer::new("swarm".to_owned(), peer_id)
    .with_addrs(port, addrs)
    .with_callback(|peer_id, peer| {
        println!("discovered {}: {:?}", peer_id, peer);
    })
    .spawn(rt.handle())
    .expect("discoverer spawn");

Implementations

impl Discoverer

pub fn new(name: String, peer_id: String) -> Self

Creates a new builder for a swarm discovery service.

The name is the name of the mDNS service, meaning that it will be discoverable under the name _name._udp.local.. The peer_id is the unique identifier of this peer, which will be discoverable under the name peer_id._name._udp.local..

pub fn new_interactive(name: String, peer_id: String) -> Self

Creates a new builder with default cadence and response rate for human interactive applications.

This sets τ=0.7sec and φ=2.5, see Discoverer::new for the name and peer_id arguments.

pub fn with_protocol(self, protocol: Protocol) -> Self

Set the protocol suffix to use for the service name.

Note that this does not change the protocol used for discovery, which is always UDP-based mDNS. Default is Protocol::Udp.

pub fn with_addrs( self, port: u16, addrs: impl IntoIterator<Item = IpAddr>, ) -> Self

Register the local peer’s port and IP addresses, may be called multiple times with additive effect.

If this method is not called, the local peer will not advertise itself. It can still discover others.

pub fn with_callback( self, callback: impl FnMut(&str, &Peer) + Send + 'static, ) -> Self

Register a callback to be called when a peer is discovered or its addresses change.

When a peer is removed, the callback will be called with an empty list of addresses. This happens after not receiving any responses for a time period greater than three times the estimated swarm size divided by the response frequency.

pub fn with_cadence(self, tau: Duration) -> Self

Set the discovery time target.

After roughly this time a new peer should have discovered some parts of the swarm. The worst-case latency is 1.2•τ.

Note that the product τ•φ must be greater than 1 for the rate limiting to work correctly. For human interactive applications it is recommended to set τ=0.7s and φ=2.5 (see Discoverer::new_interactive).

The default is 10 seconds.

pub fn with_response_rate(self, phi: f32) -> Self

Set the response frequency target in Hz.

While query-response cycles follow the configured cadence (see Discoverer::with_cadence), the response rate determines the (soft) maximum of how many responses should be received per second.

With cadence 10sec, setting this to 1.0Hz means that at most 10 responses will be received per cycle. Setting it to 0.5Hz means that up to roughly 5 responses will be received per cycle.

Note that the product τ•φ must be greater than 1 for the rate limiting to work correctly. For human interactive applications it is recommended to set τ=0.7s and φ=2.5 (see Discoverer::new_interactive).

The default is 1.0Hz.

pub fn with_ip_class(self, class: IpClass) -> Self

Set which IP classes to use.

The default is to use both IPv4 and IPv6, where IPv4 is preferred for sending queries. Responses will be sent using that class which the query used.

pub fn spawn(self, handle: &Handle) -> Result<DropGuard>

Start the discovery service.

This will spawn asynchronous tasks and return a guard which will stop the discovery when dropped. Changing the configuration is done by stopping the discovery and starting a new one.