iroh

Module discovery

Source
Expand description

Node address discovery.

To connect to an iroh node a NodeAddr is needed, which may contain a RelayUrl or one or more direct addresses in addition to the NodeId.

Since there is a conversion from NodeId to NodeAddr, you can also use connect directly with a NodeId.

For this to work however, the endpoint has to get the addressing information by other means. This can be done by manually calling Endpoint::add_node_addr, but that still requires knowing the other addressing information.

Node discovery is an automated system for an Endpoint to retrieve this addressing information. Each iroh node will automatically publish their own addressing information. Usually this means publishing which RelayUrl to use for their NodeId, but they could also publish their direct addresses.

The Discovery trait is used to define node discovery. This allows multiple implementations to co-exist because there are many possible ways to implement this. Each Endpoint can use the discovery mechanisms most suitable to the application. The Builder::discovery method is used to add a discovery mechanism to an Endpoint.

Some generally useful discovery implementations are provided:

  • The DnsDiscovery which performs lookups via the standard DNS systems. To publish to this DNS server a PkarrPublisher is needed. Number 0 runs a public instance of a PkarrPublisher with attached DNS server which is globally available and a reliable default choice.

  • The PkarrResolver which can perform lookups from designated pkarr relay servers using HTTP.

  • very similar to mDNS.

  • The DhtDiscovery also uses the pkarr system but can also publish and lookup records to/from the Mainline DHT.

To use multiple discovery systems simultaneously use ConcurrentDiscovery which will perform lookups to all discovery systems at the same time.

§Examples

A very common setup is to enable DNS discovery, which needs to be done in two parts as a PkarrPublisher and DnsDiscovery:

use iroh::{
    discovery::{dns::DnsDiscovery, pkarr::PkarrPublisher, ConcurrentDiscovery},
    Endpoint, SecretKey,
};

let secret_key = SecretKey::generate(rand::rngs::OsRng);
let discovery = ConcurrentDiscovery::from_services(vec![
    Box::new(PkarrPublisher::n0_dns(secret_key.clone())),
    Box::new(DnsDiscovery::n0_dns()),
]);
let ep = Endpoint::builder()
    .secret_key(secret_key)
    .discovery(Box::new(discovery))
    .bind()
    .await?;

To also enable LocalSwarmDiscovery it can be added as another service in the ConcurrentDiscovery:

let discovery = ConcurrentDiscovery::from_services(vec![
    Box::new(PkarrPublisher::n0_dns(secret_key.clone())),
    Box::new(DnsDiscovery::n0_dns()),
    Box::new(LocalSwarmDiscovery::new(secret_key.public())?),
]);

Modules§

  • dns
    DNS node discovery for iroh
  • local_swarm_discoverydiscovery-local-network
    A discovery service that uses an mdns-like service to discover local nodes.
  • pkarr
    A discovery service which publishes and resolves node information using a pkarr relay.
  • static_provider
    A static discovery implementation that allows adding info for nodes manually.

Structs§

Traits§