async_std_resolver/
lib.rs

1// Copyright 2015-2020 Benjamin Fry <benjaminfry@me.com>
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// https://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7
8// LIBRARY WARNINGS
9#![warn(
10    clippy::default_trait_access,
11    clippy::dbg_macro,
12    clippy::print_stdout,
13    clippy::unimplemented,
14    clippy::use_self,
15    missing_copy_implementations,
16    missing_docs,
17    non_snake_case,
18    non_upper_case_globals,
19    rust_2018_idioms,
20    unreachable_pub
21)]
22#![allow(clippy::needless_doctest_main)]
23
24//! The Resolver is responsible for performing recursive queries to lookup domain names.
25//!
26//! This is a 100% in process DNS resolver. It *does not* use the Host OS' resolver. If what is desired is to use the Host OS' resolver, generally in the system's libc, then the `std::net::ToSocketAddrs` variant over `&str` should be used.
27//!
28//! Unlike the `hickory-client`, this tries to provide a simpler interface to perform DNS queries. For update options, i.e. Dynamic DNS, the `hickory-client` crate must be used instead. The Resolver library is capable of searching multiple domains (this can be disabled by using an FQDN during lookup), dual-stack IPv4/IPv6 lookups, performing chained CNAME lookups, and features connection metric tracking for attempting to pick the best upstream DNS resolver.
29//!
30//! Use [`AsyncResolver`](crate::AsyncResolver) for performing DNS queries. `AsyncResolver` is a `async-std` based async resolver, and can be used inside any `asyn-std` based system.
31//!
32//! This as best as possible attempts to abide by the DNS RFCs, please file issues at <https://github.com/hickory-dns/hickory-dns>.
33//!
34//! # Usage
35//!
36//! ## Declare dependency
37//!
38//! ```toml
39//! [dependency]
40//! async-std-resolver = "*"
41//! ```
42//!
43//! ## Using the async-std Resolver
44//!
45//! For more advanced asynchronous usage, the [`AsyncResolver`] is integrated with async-std.
46//!
47//! ```rust
48//! use std::net::*;
49//! use async_std::prelude::*;
50//! use async_std_resolver::{resolver, config};
51//!
52//! #[async_std::main]
53//! async fn main() {
54//!   // Construct a new Resolver with default configuration options
55//!   let resolver = resolver(
56//!     config::ResolverConfig::default(),
57//!     config::ResolverOpts::default(),
58//!   ).await;
59//!
60//!   // Lookup the IP addresses associated with a name.
61//!   // This returns a future that will lookup the IP addresses, it must be run in the Core to
62//!   //  to get the actual result.
63//!   let mut response = resolver.lookup_ip("www.example.com.").await.unwrap();
64//!
65//!   // There can be many addresses associated with the name,
66//!   //  this can return IPv4 and/or IPv6 addresses
67//!   let _address = response.iter().next().expect("no addresses returned!");
68//! }
69//! ```
70//!
71//! ## Using the host system config
72//!
73//! On Unix systems, the `/etc/resolv.conf` can be used for configuration. Not all options specified in the host systems `resolv.conf` are applicable or compatible with this software. In addition there may be additional options supported which the host system does not. Example:
74//!
75//! ```
76//! use std::net::*;
77//! use async_std::prelude::*;
78//! # #[cfg(feature = "system-config")]
79//! use async_std_resolver::{resolver_from_system_conf, config};
80//!
81//! #[async_std::main]
82//! async fn main() {
83//! # #[cfg(feature = "system-config")]
84//! # {
85//!   // Use the host OS'es `/etc/resolv.conf`
86//!   let resolver = resolver_from_system_conf().await.unwrap();
87//!   let response = resolver.lookup_ip("www.example.com.").await.unwrap();
88//! # }
89//! }
90//! ```
91
92use hickory_resolver::AsyncResolver;
93
94use crate::runtime::AsyncStdConnectionProvider;
95
96mod net;
97mod runtime;
98#[cfg(test)]
99mod tests;
100mod time;
101
102pub use hickory_resolver::config;
103pub use hickory_resolver::error::ResolveError;
104pub use hickory_resolver::lookup;
105pub use hickory_resolver::lookup_ip;
106pub use hickory_resolver::proto;
107
108/// An AsyncResolver used with async_std
109pub type AsyncStdResolver = AsyncResolver<AsyncStdConnectionProvider>;
110
111/// Construct a new async-std based `AsyncResolver` with the provided configuration.
112///
113/// # Arguments
114///
115/// * `config` - configuration, name_servers, etc. for the Resolver
116/// * `options` - basic lookup options for the resolver
117///
118/// # Returns
119///
120/// A tuple containing the new `AsyncResolver` and a future that drives the
121/// background task that runs resolutions for the `AsyncResolver`. See the
122/// documentation for `AsyncResolver` for more information on how to use
123/// the background future.
124pub async fn resolver(
125    config: config::ResolverConfig,
126    options: config::ResolverOpts,
127) -> AsyncStdResolver {
128    AsyncStdResolver::new(config, options, AsyncStdConnectionProvider::default())
129}
130
131/// Constructs a new async-std based Resolver with the system configuration.
132///
133/// This will use `/etc/resolv.conf` on Unix OSes and the registry on Windows.
134#[cfg(any(unix, target_os = "windows"))]
135#[cfg(feature = "system-config")]
136pub async fn resolver_from_system_conf() -> Result<AsyncStdResolver, ResolveError> {
137    AsyncStdResolver::from_system_conf(AsyncStdConnectionProvider::default())
138}
async_std_resolver/lib.rs

async_std_resolver/
lib.rs
