domain/resolv/
resolver.rs

1//! The trait defining an abstract resolver.
2
3use crate::base::message::Message;
4use crate::base::name::ToName;
5use crate::base::question::Question;
6use std::future::Future;
7use std::io;
8
9//----------- Resolver -------------------------------------------------------
10
11/// A type that acts as a DNS resolver.
12///
13/// A resolver is anything that tries to answer questions using the DNS. The
14/// [`query`] method takes a single question and returns a future that will
15/// eventually resolve into either an answer or an IO error.
16///
17/// [`query`]: Resolver::query
18pub trait Resolver {
19    type Octets: AsRef<[u8]>;
20
21    /// The answer returned by a query.
22    ///
23    /// This isn’t [`Message`] directly as it may be useful for the resolver
24    /// to provide additional information. For instance, a validating
25    /// resolver (a resolver that checks whether DNSSEC signatures are
26    /// correct) can supply more information as to why validation failed.
27    type Answer: AsRef<Message<Self::Octets>>;
28
29    /// The future resolving into an answer.
30    type Query: Future<Output = Result<Self::Answer, io::Error>> + Send;
31
32    /// Returns a future answering a question.
33    ///
34    /// The method takes anything that can be converted into a question and
35    /// produces a future trying to answer the question.
36    fn query<N, Q>(&self, question: Q) -> Self::Query
37    where
38        N: ToName,
39        Q: Into<Question<N>>;
40}
41
42//------------ SearchNames ---------------------------------------------------
43
44/// A type that can produce a list of name suffixes.
45///
46/// Legacy systems have the ability to interpret relative domain names as
47/// within the local system. They provide a list of suffixes that can be
48/// attached to the name to make it absolute.
49///
50/// A search resolver is a resolver that provides such a list. This is
51/// implemented via an iterator over domain names.
52pub trait SearchNames {
53    type Name: ToName;
54    type Iter: Iterator<Item = Self::Name>;
55
56    /// Returns an iterator over the search suffixes.
57    fn search_iter(&self) -> Self::Iter;
58}