rename hints to roots in source and docs

crates/recursor/src/recursor.rs

@@ -32,34 +32,36 @@ use crate::{recursor_pool::RecursorPool, Error, ErrorKind};
 /// Set of nameservers by the zone name
 type NameServerCache<C, P> = LruCache<Name, RecursorPool<C, P>>;
 
-/// A top down recursive resolver which operates off a list of "hints", this is often the root nodes.
+/// A top down recursive resolver which operates off a list of roots for initial recursive requests.
+///
+/// This is the well known root nodes, refered to as hints in RFCs. See the IANA [Root Servers](https://www.iana.org/domains/root/servers) list.
 pub struct Recursor {
-    hints: RecursorPool<TokioConnection, TokioConnectionProvider>,
+    roots: RecursorPool<TokioConnection, TokioConnectionProvider>,
     name_server_cache: Mutex<NameServerCache<TokioConnection, TokioConnectionProvider>>,
     record_cache: DnsLru,
 }
 
 impl Recursor {
-    /// Construct a new recursor using the list of NameServerConfigs for the hint list
+    /// Construct a new recursor using the list of NameServerConfigs for the root node list
     ///
     /// # Panics
     ///
-    /// This will panic if the hints are empty.
-    pub fn new(hints: impl Into<NameServerConfigGroup>) -> Result<Self, ResolveError> {
+    /// This will panic if the roots are empty.
+    pub fn new(roots: impl Into<NameServerConfigGroup>) -> Result<Self, ResolveError> {
         // configure the trust-dns-resolver
-        let hints: NameServerConfigGroup = hints.into();
+        let roots: NameServerConfigGroup = roots.into();
 
-        assert!(!hints.is_empty(), "hints must not be empty");
+        assert!(!roots.is_empty(), "roots must not be empty");
 
         let opts = recursor_opts();
-        let hints =
-            NameServerPool::from_config(hints, &opts, TokioConnectionProvider::new(TokioHandle));
-        let hints = RecursorPool::from(Name::root(), hints);
+        let roots =
+            NameServerPool::from_config(roots, &opts, TokioConnectionProvider::new(TokioHandle));
+        let roots = RecursorPool::from(Name::root(), roots);
         let name_server_cache = Mutex::new(NameServerCache::new(100)); // TODO: make this configurable
         let record_cache = DnsLru::new(100, TtlConfig::default());
 
         Ok(Self {
-            hints,
+            roots,
             name_server_cache,
             record_cache,
         })
@@ -323,8 +325,8 @@ impl Recursor {
         let parent_zone = zone.base_name();
 
         let nameserver_pool = if parent_zone.is_root() {
-            debug!("using hints for {} nameservers", zone);
-            self.hints.clone()
+            debug!("using roots for {} nameservers", zone);
+            self.roots.clone()
         } else {
             self.get_ns_pool_for_zone(parent_zone, request_time).await?
         };

crates/server/src/error/config_error.rs

@@ -29,7 +29,7 @@ pub enum ErrorKind {
     TomlDecode(#[from] toml::de::Error),
 
     /// An error occurred while parsing a zone file
-    #[error("failed to parse hints zone file: {0}")]
+    #[error("failed to parse the zone file: {0}")]
     ZoneParse(#[from] trust_dns_client::error::ParseError),
 }
 

crates/server/src/store/recursor/authority.rs

@@ -44,15 +44,15 @@ impl RecursiveAuthority {
     ) -> Result<Self, String> {
         info!("loading recursor config: {}", origin);
 
-        // read the hints
-        let hint_addrs = config
-            .read_hints(root_dir)
-            .map_err(|e| format!("failed to read hints {}: {}", config.hints.display(), e))?;
+        // read the roots
+        let root_addrs = config
+            .read_roots(root_dir)
+            .map_err(|e| format!("failed to read roots {}: {}", config.roots.display(), e))?;
 
         // Configure all the name servers
-        let mut hints = NameServerConfigGroup::new();
-        for socket_addr in hint_addrs {
-            hints.push(NameServerConfig {
+        let mut roots = NameServerConfigGroup::new();
+        for socket_addr in root_addrs {
+            roots.push(NameServerConfig {
                 socket_addr,
                 protocol: Protocol::Tcp,
                 tls_dns_name: None,
@@ -62,7 +62,7 @@ impl RecursiveAuthority {
                 bind_addr: None, // TODO: need to support bind addresses
             });
 
-            hints.push(NameServerConfig {
+            roots.push(NameServerConfig {
                 socket_addr,
                 protocol: Protocol::Udp,
                 tls_dns_name: None,
@@ -74,7 +74,7 @@ impl RecursiveAuthority {
         }
 
         let recursor =
-            Recursor::new(hints).map_err(|e| format!("failed to initialize recursor: {}", e))?;
+            Recursor::new(roots).map_err(|e| format!("failed to initialize recursor: {}", e))?;
 
         Ok(Self {
             origin: origin.into(),

crates/server/src/store/recursor/config.rs

@@ -25,37 +25,37 @@ use crate::error::ConfigError;
 /// Configuration for file based zones
 #[derive(Clone, Deserialize, PartialEq, Debug)]
 pub struct RecursiveConfig {
-    /// File with hints
-    pub hints: PathBuf,
+    /// File with roots, aka hints
+    pub roots: PathBuf,
 }
 
 impl RecursiveConfig {
-    pub(crate) fn read_hints(
+    pub(crate) fn read_roots(
         &self,
         root_dir: Option<&Path>,
     ) -> Result<Vec<SocketAddr>, ConfigError> {
         let path = if let Some(root_dir) = root_dir {
-            Cow::Owned(root_dir.join(&self.hints))
+            Cow::Owned(root_dir.join(&self.roots))
         } else {
-            Cow::Borrowed(&self.hints)
+            Cow::Borrowed(&self.roots)
         };
 
-        let mut hints = File::open(path.as_ref())?;
-        let mut hints_str = String::new();
-        hints.read_to_string(&mut hints_str)?;
+        let mut roots = File::open(path.as_ref())?;
+        let mut roots_str = String::new();
+        roots.read_to_string(&mut roots_str)?;
 
-        let lexer = Lexer::new(&hints_str);
+        let lexer = Lexer::new(&roots_str);
         let mut parser = Parser::new();
 
-        let (_zone, hints_zone) = parser.parse(lexer, Some(Name::root()), Some(DNSClass::IN))?;
+        let (_zone, roots_zone) = parser.parse(lexer, Some(Name::root()), Some(DNSClass::IN))?;
 
         // TODO: we may want to deny some of the root nameservers, for reasons...
-        Ok(hints_zone
+        Ok(roots_zone
             .values()
             .flat_map(RecordSet::records_without_rrsigs)
             .filter_map(Record::data)
             .filter_map(RData::to_ip_addr) // we only want IPs
-            .map(|ip| SocketAddr::from((ip, 53))) // all the hints only have tradition DNS ports
+            .map(|ip| SocketAddr::from((ip, 53))) // all the roots only have tradition DNS ports
             .collect())
     }
 }

tests/integration-tests/src/lib.rs

@@ -38,7 +38,6 @@ use trust_dns_server::{
 
 pub mod example_authority;
 pub mod mock_client;
-pub mod test_authority;
 #[cfg(feature = "dns-over-rustls")]
 pub mod tls_client_connection;
 

tests/integration-tests/tests/recursor_tests.rs

@@ -8,10 +8,11 @@
 //! Integration tests for the recursor. These integration tests setup scenarios to verify that the recursor is able
 //!  to recursively resolve various real world scenarios. As new scenarios are discovered, they should be added here.
 
-
-
 /// Tests a basic recursive resolution `a.recursive.test.` , `.` -> `test.` -> `recursive.test.` -> `a.recursive.test.`
 ///
 /// There are three authorities needed for this test `.` which contains the `test` nameserver, `recursive.test` which is
 ///  target zone containing `a.recursive.test.`.
-fn test_basic_recursion() {}
+#[test]
+fn test_basic_recursion() {
+    // TBD
+}

tests/test-data/named_test_configs/example_recursor.toml

@@ -37,4 +37,4 @@ zone_type = "Hint"
 
 ## remember the port, defaults: 53 for Udp & Tcp, 853 for Tls and 443 for Https.
 ##   Tls and/or Https require features dns-over-tls and/or dns-over-https
-stores = { type = "recursor", hints = "default/root.zone" }
+stores = { type = "recursor", roots = "default/root.zone" }

util/src/recurse.rs

@@ -40,7 +40,7 @@ use trust_dns_resolver::{
 /// A CLI interface for the trust-dns-recursor.
 ///
 /// This utility directly uses the trust-dns-recursor to perform a recursive lookup
-///   starting with a sent of hints or root dns servers.
+///   starting with a set of root dns servers, aka hints.
 #[derive(Debug, Parser)]
 #[clap(name = "recurse")]
 struct Opts {
@@ -96,9 +96,9 @@ struct Opts {
     #[clap(long)]
     error: bool,
 
-    /// Path to a hints file
-    #[clap(short = 'f', long)]
-    hints: Option<PathBuf>,
+    /// Path to a roots file
+    #[clap(short = 'r', long)]
+    roots: Option<PathBuf>,
 }
 
 /// Run the resolve programf
@@ -122,10 +122,10 @@ pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
     trust_dns_util::logger(env!("CARGO_BIN_NAME"), log_level);
 
     // Configure all the name servers
-    let mut hints = NameServerConfigGroup::new();
+    let mut roots = NameServerConfigGroup::new();
 
     for socket_addr in &opts.nameserver {
-        hints.push(NameServerConfig {
+        roots.push(NameServerConfig {
             socket_addr: *socket_addr,
             protocol: Protocol::Tcp,
             tls_dns_name: None,
@@ -135,7 +135,7 @@ pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
             bind_addr: opts.bind.map(|ip| SocketAddr::new(ip, 0)),
         });
 
-        hints.push(NameServerConfig {
+        roots.push(NameServerConfig {
             socket_addr: *socket_addr,
             protocol: Protocol::Udp,
             tls_dns_name: None,
@@ -152,20 +152,20 @@ pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let udp = opts.udp || !opts.tcp;
     let tcp = opts.tcp || !opts.udp;
 
-    hints.retain(|ns| (ipv4 && ns.socket_addr.is_ipv4()) || (ipv6 && ns.socket_addr.is_ipv6()));
-    hints.retain(|ns| {
+    roots.retain(|ns| (ipv4 && ns.socket_addr.is_ipv4()) || (ipv6 && ns.socket_addr.is_ipv6()));
+    roots.retain(|ns| {
         (udp && ns.protocol == Protocol::Udp) || (tcp && ns.protocol == Protocol::Tcp)
     });
 
     // query parameters
     let name = opts.domainname;
     let ty = opts.ty;
 
-    let recursor = Recursor::new(hints)?;
+    let recursor = Recursor::new(roots)?;
 
     // execute query
     println!(
-        "Recursing for {name} {ty} from hints",
+        "Recursing for {name} {ty} from roots",
         name = style(&name).yellow(),
         ty = style(ty).yellow(),
     );