Module address_lookup 

Lookup the address of an Endpoint ID.

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.

AddressLookup 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 AddressLookup trait is used to define an address lookup system. This allows multiple implementations to co-exist because there are many possible ways to implement this. Each Endpoint can use the address lookup mechanisms most suitable to the application. The Builder::address_lookup method is used to add an address lookup mechanism to an Endpoint.

Some generally useful Address Lookup implementations are provided:

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

• The address_lookup::DnsAddressLookup 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.

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

• The address_lookup::DhtAddressLookup also uses the pkarr system but can also publish and lookup records to/from the Mainline DHT. It requires enabling the address-lookup-pkarr-dht feature.

To use multiple Address Lookup’ssimultaneously you can call Builder::address_lookup. This will use ConcurrentAddressLookup under the hood, which performs lookups to all Address Lookupsystems at the same time.

Builder::address_lookup takes any type that implements IntoAddressLookup. You can implement that trait on a builder struct if your Address Lookup needs information from the endpoint it is mounted on. After endpoint construction, your Address Lookup is built by calling IntoAddressLookup::into_address_lookup, passing the finished Endpoint to your builder.

If your Address Lookupdoes not need any information from its endpoint, you can pass the Address Lookupservice directly to Builder::address_lookup: All types that implement AddressLookup also have a blanket implementation of IntoAddressLookup.

Examples

A very common setup is to enable DNS Address Lookup, which needs to be done in two parts as a PkarrPublisher and address_lookup::DnsAddressLookup:

use iroh::{
    Endpoint, SecretKey,
    address_lookup::{self, PkarrPublisher},
    endpoint::RelayMode,
};

let ep = Endpoint::empty_builder(RelayMode::Default)
    .address_lookup(PkarrPublisher::n0_dns())
    .address_lookup(address_lookup::DnsAddressLookup::n0_dns())
    .bind()
    .await?;

To also enable address_lookup::MdnsAddressLookup it can be added as another service.

#[cfg(feature = "address-lookup-mdns")]
let ep = Endpoint::empty_builder(RelayMode::Default)
    .address_lookup(PkarrPublisher::n0_dns())
    .address_lookup(address_lookup::DnsAddressLookup::n0_dns())
    .address_lookup(address_lookup::MdnsAddressLookup::builder())
    .bind()
    .await?;

Re-exports

pub use dns::*;Non-wasm_browser

pub use mdns::*;address-lookup-mdns

pub use memory::*;

pub use pkarr::dht::*;address-lookup-pkarr-dht

pub use pkarr::*;

Modules

dnsNon-wasm_browser

DNS endpoint discovery for iroh

mdnsaddress-lookup-mdns

An address lookup service that uses an mdns-like service to discover and lookup the addresses of local endpoints.

memory

An in-memory address lookup system to manually add endpoint addressing information.

pkarr

An address lookup service which publishes and resolves endpoint information using a pkarr relay.

Structs

ConcurrentAddressLookup

An Address Lookup service that combines multiple Address Lookup sources.

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.

Item

Address lookup results from AddressLookups.

UserData

Under the hood this is a UTF-8 String is no longer than UserData::MAX_LENGTH bytes.

Enums

Error

AddressLookup errors

IntoAddressLookupError

IntoAddressLookup errors

ParseError

Traits

AddressLookup

AddressLookup system for super::Endpoint.

IntoAddressLookup

Trait for structs that can be converted into AddressLookups.