Struct DnsResolver 

pub struct DnsResolver { /* private fields */ }

The DNS resolver used throughout iroh.

By default, we use a built-in resolver that reads the system’s DNS configuration. The nameservers can be customized by constructing the resolver with Self::builder. Alternatively, you can create a fully custom DNS resolver by implementing the Resolver trait and creating the resolver with Self::custom.

Usage on Android

The system-defaults reader uses JNI through ndk_context, which must be initialized with a JavaVM and Application context before the resolver is constructed. Glue crates like ndk-glue and android-activity do this before main. Apps that don’t use either should call install_android_jni_context once at startup, see docs there for details.

If ndk_context is not initialized, fetching the system config on Android will fail and the resolver will use the fallback nameservers instead, subject to the configured FallbackMode. Due to how things are implemented in ndk_context, detecting the failure relies on unwinding a panic. If your app uses panic = "abort" in its compilation profile, this doesn’t work, so in that case your app will panic if no JNI context is initialized. Therefore, either make sure that the JNI context is installed, or don’t use panic = "abort".

Implementations

impl DnsResolver

pub fn new() -> Self

Creates a new DNS resolver with sensible cross-platform defaults.

Reads the host system’s DNS configuration, with the default public resolvers behind it as a fallback tier. Those are queried only when the system configuration cannot be read, which happens on some Android versions, or when its nameservers do not answer.

pub fn with_nameserver(nameserver: SocketAddr) -> Self

Creates a new DNS resolver configured with a single UDP DNS nameserver.

pub fn builder() -> Builder

Creates a builder to construct a DNS resolver with custom options.

pub fn custom(resolver: impl Resolver) -> Self

Creates a new DnsResolver from a struct that implements Resolver.

If you need more customization for DNS resolving than the Builder allows, you can implement the Resolver trait on a struct and implement DNS resolution however you see fit.

pub fn clear_cache(&self)

Removes all entries from the cache.

pub fn reset(&self)

Replaces the inner resolver with a freshly-built one.

Call this on a major host network change to pick up the new system DNS configuration and rebind sockets. The swap is atomic and non-blocking; in-flight lookups retry against the new resolver. See Resolver::reset.

pub async fn lookup_txt<T: ToString>( &self, host: T, timeout: Duration, ) -> Result<impl Iterator<Item = TxtRecordData>, DnsError>

Looks up a TXT record.

pub async fn lookup_ipv4<T: ToString>( &self, host: T, timeout: Duration, ) -> Result<impl Iterator<Item = IpAddr> + use<T>, DnsError>

Performs an IPv4 lookup with a timeout.

pub async fn lookup_ipv6<T: ToString>( &self, host: T, timeout: Duration, ) -> Result<impl Iterator<Item = IpAddr> + use<T>, DnsError>

Performs an IPv6 lookup with a timeout.

pub async fn lookup_ipv4_ipv6<T: ToString>( &self, host: T, timeout: Duration, ) -> Result<impl Iterator<Item = IpAddr> + use<T>, DnsError>

Resolves IPv4 and IPv6 in parallel with a timeout.

LookupIpStrategy::Ipv4AndIpv6 will wait for ipv6 resolution timeout, even if it is not usable on the stack, so we manually query both lookups concurrently and time them out individually.

pub async fn resolve_host( &self, url: &Url, prefer_ipv6: bool, timeout: Duration, ) -> Result<IpAddr, DnsError>

Resolves a hostname from a URL to an IP address.

pub fn resolve_host_all<'a>( &'a self, url: &Url, timeout: Duration, ) -> impl Stream<Item = Result<IpAddr, DnsError>> + Send + 'a

Resolves a hostname from a URL to its IP addresses, streamed as they resolve.

IPv4 and IPv6 are looked up concurrently and each address is yielded as soon as its lookup completes, so a caller can start dialing without waiting for both families.

A lookup failure is swallowed as long as the other family yields an address. Only if both lookups fail does the stream yield a single DnsError.

The stream ends once both lookups have finished and every address or the error have been yielded.

pub async fn lookup_ipv4_staggered( &self, host: impl ToString, timeout: Duration, delays_ms: &[u64], ) -> Result<impl Iterator<Item = IpAddr>, StaggeredError<DnsError>>

Performs an IPv4 lookup with a timeout in a staggered fashion.

From the moment this function is called, each lookup is scheduled after the delays in delays_ms with the first call being done immediately. [200ms, 300ms] results in calls at T+0ms, T+200ms and T+300ms. The timeout is applied to each call individually. The result of the first successful call is returned, or a summary of all errors otherwise.

pub async fn lookup_ipv6_staggered( &self, host: impl ToString, timeout: Duration, delays_ms: &[u64], ) -> Result<impl Iterator<Item = IpAddr>, StaggeredError<DnsError>>

Performs an IPv6 lookup with a timeout in a staggered fashion.

From the moment this function is called, each lookup is scheduled after the delays in delays_ms with the first call being done immediately. [200ms, 300ms] results in calls at T+0ms, T+200ms and T+300ms. The timeout is applied to each call individually. The result of the first successful call is returned, or a summary of all errors otherwise.

pub async fn lookup_ipv4_ipv6_staggered( &self, host: impl ToString, timeout: Duration, delays_ms: &[u64], ) -> Result<impl Iterator<Item = IpAddr>, StaggeredError<DnsError>>

Races an IPv4 and IPv6 lookup with a timeout in a staggered fashion.

From the moment this function is called, each lookup is scheduled after the delays in delays_ms with the first call being done immediately. [200ms, 300ms] results in calls at T+0ms, T+200ms and T+300ms. The timeout is applied as stated in Self::lookup_ipv4_ipv6. The result of the first successful call is returned, or a summary of all errors otherwise.

pub async fn lookup_endpoint_by_id( &self, endpoint_id: &EndpointId, origin: &str, ) -> Result<EndpointInfo, LookupError>

Looks up endpoint info by EndpointId and origin domain name.

To lookup endpoints that published their endpoint info to the DNS servers run by n0, pass N0_DNS_ENDPOINT_ORIGIN_PROD as origin.

pub async fn lookup_endpoint_by_domain_name( &self, name: &str, ) -> Result<EndpointInfo, LookupError>

Looks up endpoint info by DNS name.

pub async fn lookup_endpoint_by_domain_name_staggered( &self, name: &str, delays_ms: &[u64], ) -> Result<EndpointInfo, StaggeredError<LookupError>>

Looks up endpoint info by DNS name in a staggered fashion.

From the moment this function is called, each lookup is scheduled after the delays in delays_ms with the first call being done immediately. [200ms, 300ms] results in calls at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a summary of all errors otherwise.

pub async fn lookup_endpoint_by_id_staggered( &self, endpoint_id: &EndpointId, origin: &str, delays_ms: &[u64], ) -> Result<EndpointInfo, StaggeredError<LookupError>>

Looks up endpoint info by EndpointId and origin domain name.

From the moment this function is called, each lookup is scheduled after the delays in delays_ms with the first call being done immediately. [200ms, 300ms] results in calls at T+0ms, T+200ms and T+300ms. The result of the first successful call is returned, or a summary of all errors otherwise.

Trait Implementations

impl Clone for DnsResolver

fn clone(&self) -> DnsResolver

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DnsResolver

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DnsResolver

fn default() -> Self

Returns the “default value” for a type.