Module discovery

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:

• StaticProvider which allows application to add and remove out-of-band addressing information.

• 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.

• MdnsDiscovery: mdns::MdnsDiscovery which uses the crate swarm-discovery, an opinionated mDNS implementation, to discover nodes on the local network.

• 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 MdnsDiscovery 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(MdnsDiscovery::new(secret_key.public())?),
]);

Modules

• dnsNon-wasm_browser
  DNS node discovery for iroh
• mdnsdiscovery-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 node discovery to manually add node addressing information.

Structs

• ConcurrentDiscovery
  A discovery service that combines multiple discovery sources.
• DiscoveryItem
  Node discovery results from Discovery services.
• Lagged
  Error returned when a discovery watch stream lagged too far behind.
• NodeData
  Data about a node that may be published to and resolved from discovery services.
• NodeInfo
  Information about a node that may be published to and resolved from discovery services.
• UserData
  Under the hood this is a UTF-8 String is no longer than UserData::MAX_LENGTH bytes.

Traits

• Discovery
  Node discovery for super::Endpoint.