trippy_dns/lib.rs
1//! This crate provides a cheaply cloneable, non-blocking, caching, forward
2//! and reverse DNS resolver which support the ability to lookup Autonomous
3//! System (AS) information.
4//!
5//! Only a single reverse DNS lookup is performed (lazily) regardless of how
6//! often the lookup is performed unless:
7//! - the previous lookup failed with `DnsEntry::Timeout(_)`
8//! - the previous lookup is older than the configured time-to-live (TTL)
9//!
10//! # Example
11//!
12//! The following example perform a reverse DNS lookup and loop until it is
13//! resolved or fails. The lookup uses the Cloudflare 1.1.1.1 public DNS
14//! service.
15//!
16//! ```no_run
17//! # fn main() -> anyhow::Result<()> {
18//! # use std::net::IpAddr;
19//! # use std::str::FromStr;
20//! # use std::thread::sleep;
21//! # use std::time::Duration;
22//! use trippy_dns::{
23//! Config, DnsEntry, DnsResolver, IpAddrFamily, ResolveMethod, Resolved, Resolver, Unresolved,
24//! };
25//!
26//! let config = Config::new(
27//! ResolveMethod::Cloudflare,
28//! IpAddrFamily::Ipv4Only,
29//! Duration::from_secs(5),
30//! Duration::from_secs(300),
31//! );
32//! let resolver = DnsResolver::start(config)?;
33//! let addr = IpAddr::from_str("1.1.1.1")?;
34//! loop {
35//! let entry = resolver.lazy_reverse_lookup_with_asinfo(addr);
36//! match entry {
37//! DnsEntry::Pending(ip) => {
38//! println!("lookup of {ip} is pending, sleeping for 1 sec");
39//! sleep(Duration::from_secs(1));
40//! }
41//! DnsEntry::Resolved(Resolved::Normal(ip, addrs)) => {
42//! println!("lookup of {ip} resolved to {addrs:?}");
43//! return Ok(());
44//! }
45//! DnsEntry::Resolved(Resolved::WithAsInfo(ip, addrs, as_info)) => {
46//! println!("lookup of {ip} resolved to {addrs:?} with AS information {as_info:?}");
47//! return Ok(());
48//! }
49//! DnsEntry::NotFound(Unresolved::Normal(ip)) => {
50//! println!("lookup of {ip} did not match any records");
51//! return Ok(());
52//! }
53//! DnsEntry::NotFound(Unresolved::WithAsInfo(ip, as_info)) => {
54//! println!(
55//! "lookup of {ip} did not match any records with AS information {as_info:?}"
56//! );
57//! return Ok(());
58//! }
59//! DnsEntry::Timeout(ip) => {
60//! println!("lookup of {ip} timed out");
61//! return Ok(());
62//! }
63//! DnsEntry::Failed(ip) => {
64//! println!("lookup of {ip} failed");
65//! return Ok(());
66//! }
67//! }
68//! }
69//! # Ok(())
70//! # }
71//! ```
72#![forbid(unsafe_code)]
73
74mod config;
75mod lazy_resolver;
76mod resolver;
77
78pub use config::{Builder, Config};
79pub use lazy_resolver::{DnsResolver, IpAddrFamily, ResolveMethod};
80pub use resolver::{AsInfo, DnsEntry, Error, Resolved, Resolver, Result, Unresolved};