From e038f87c6062ec0353816c3cdd026032e8e6c67d Mon Sep 17 00:00:00 2001 From: Oliver Wangler Date: Wed, 30 Jun 2021 21:02:20 +0200 Subject: [PATCH] transports/dns: Document caveats of using the `trust-dns-resolver` crate (#2114) Ref https://github.com/libp2p/rust-libp2p/issues/2064 --- transports/dns/src/lib.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/transports/dns/src/lib.rs b/transports/dns/src/lib.rs index d10f5d74cce..0d2e2212211 100644 --- a/transports/dns/src/lib.rs +++ b/transports/dns/src/lib.rs @@ -36,6 +36,22 @@ //! features. For more information about these features, please //! refer to the documentation of [trust-dns-resolver]. //! +//! On Unix systems, if no custom configuration is given, [trust-dns-resolver] +//! will try to parse the `/etc/resolv.conf` file. This approach comes with a +//! few caveats to be aware of: +//! 1) This fails (panics even!) if `/etc/resolv.conf` does not exist. This is +//! the case on all versions of Android. +//! 2) DNS configuration is only evaluated during startup. Runtime changes are +//! thus ignored. +//! 3) DNS resolution is obviously done in process and consequently not using +//! any system APIs (like libc's `gethostbyname`). Again this is +//! problematic on platforms like Android, where there's a lot of +//! complexity hidden behind the system APIs. +//! If the implementation requires different characteristics, one should +//! consider providing their own implementation of [`GenDnsConfig`] or use +//! platform specific APIs to extract the host's DNS configuration (if possible) +//! and provide a custom [`ResolverConfig`]. +//! //![trust-dns-resolver]: https://docs.rs/trust-dns-resolver/latest/trust_dns_resolver/#dns-over-tls-and-dns-over-https use futures::{prelude::*, future::BoxFuture};