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.

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::add_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 you can call Builder::add_discovery. This will use ConcurrentDiscovery under the hood, which performs lookups to all discovery systems at the same time.

Builder::add_discovery takes any type that implements IntoDiscovery. You can implement that trait on a builder struct if your discovery service needs information from the endpoint it is mounted on. During endpoint construction, your discovery service is built by calling IntoDiscovery::into_discovery, passing a DiscoveryContext to your builder. The DiscoveryContext gives access to the endpoint’s secret key and DNS resolver.

If your discovery service does not need any information from its endpoint, you can pass the discovery service directly to Builder::add_discovery: All types that implement Discovery also have a blanket implementation of IntoDiscovery.

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::{
    Endpoint, SecretKey,
    discovery::{dns::DnsDiscovery, pkarr::PkarrPublisher},
};

let ep = Endpoint::builder()
    .add_discovery(PkarrPublisher::n0_dns())
    .add_discovery(DnsDiscovery::n0_dns())
    .bind()
    .await?;

To also enable MdnsDiscovery it can be added as another service.

#[cfg(feature = "discovery-local-network")]
let ep = Endpoint::builder()
    .add_discovery(PkarrPublisher::n0_dns())
    .add_discovery(DnsDiscovery::n0_dns())
    .add_discovery(MdnsDiscovery::builder())
    .bind()
    .await?;

Modules

dns

DNS node discovery for iroh

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.

DiscoveryContext

Context about the Endpoint for discovery services.

DiscoveryItem

Node discovery results from Discovery services.

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.

Enums

DiscoveryError

Discovery errors

IntoDiscoveryError

IntoDiscovery errors

ParseError

Traits

Discovery

Node discovery for super::Endpoint.

IntoDiscovery

Trait for structs that can be converted into Discovery.