Module discovery 

Endpoint address discovery.

To connect to an iroh endpoint a EndpointAddr is needed, which may contain a RelayUrl or one or more direct addresses in addition to the EndpointId.

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

For this to work however, the endpoint has to get the addressing information by other means.

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

The Discovery trait is used to define endpoint 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 endpoints 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::discovery. This will use ConcurrentDiscovery under the hood, which performs lookups to all discovery systems at the same time.

Builder::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. After endpoint construction, your discovery service is built by calling IntoDiscovery::into_discovery, passing the finished Endpoint to your builder.

If your discovery service does not need any information from its endpoint, you can pass the discovery service directly to Builder::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},
    endpoint::RelayMode,
};

let ep = Endpoint::empty_builder(RelayMode::Default)
    .discovery(PkarrPublisher::n0_dns())
    .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::empty_builder(RelayMode::Default)
    .discovery(PkarrPublisher::n0_dns())
    .discovery(DnsDiscovery::n0_dns())
    .discovery(MdnsDiscovery::builder())
    .bind()
    .await?;

Modules

dnsNon-wasm_browser

DNS endpoint discovery for iroh

mdnsdiscovery-local-network

A discovery service that uses an mdns-like service to discover local endpoints.

pkarr

A discovery service which publishes and resolves endpoint information using a pkarr relay.

static_provider

A static endpoint discovery to manually add endpoint addressing information.

Structs

ConcurrentDiscovery

A discovery service that combines multiple discovery sources.

DiscoveryItem

Endpoint discovery results from Discovery services.

EndpointData

Data about an endpoint that may be published to and resolved from discovery services.

EndpointInfo

Information about an endpoint 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

Endpoint discovery for super::Endpoint.

IntoDiscovery

Trait for structs that can be converted into Discovery.