cdns-rs 2.0.0-next.0

/*-
 * cdns-rs - a simple sync/async DNS query library
 * 
 * Copyright (C) 2021  Aleksandr Morozov
 * Copyright (C) 2025  Aleksandr Morozov
 * Copyright (C) 2026  Aleksandr Morozov, 4neko.org
 * 
 * The syslog-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *
 *   2. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

use std::
{
    collections::BTreeMap, io::{self, ErrorKind}, net::{IpAddr, SocketAddr, TcpStream, UdpSocket}, rc::Rc, sync::Arc, time::Instant, vec
};

use instance_copy_on_write::{ICoWWeak, ICoWWeakRead};

use crate::{CDnsError, common::{CDdnsGlobals, DnsRequestAnswerParser, QDnsName}};

#[cfg(feature = "use_sync_tls")]
use crate::network::with_tls::{TcpHttpsConnection, TcpTlsConnection};

use crate::network::{NetworkTap, SocketTap};
use crate::parsers::cfg_resolv_parser::{ConfigEntryTls, ResolveConfEntry};
use crate::
{
    CDnsErrorDnsResponse, 
    CDnsErrorType, 
    CDnsIOError, 
    DnsResponsePayload, 
    ErrorReport, 
    GLOBAL_CONFIG, 
    HostConfig, 
    QDnsQuery, 
    ResolveConfig, 
    ResolverStdErr, 
    internal_error_map,
    CDnsResult, 
    QDnsQueryResult, 
    QType, 
    QuerySetup, 
    common::DnsRequest, 
    configuration::{ConfigGetter, DnsConfigReader}, 
    query::QDnsRequests
};

#[allow(async_fn_in_trait)]
pub trait ToSocketAddrs 
{
    /// Returned iterator over socket addresses which this type may correspond
    /// to.
    type Iter: Iterator<Item = SocketAddr>;

    /// Converts this object to an iterator of resolved [`SocketAddr`]s.
    ///
    /// The returned iterator might not actually yield any values depending on the
    /// outcome of any resolution performed.
    ///
    /// Note that this function may block the current thread while resolution is
    /// performed.
    async fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
}

/// A struct which implements the [ToSocketAddrs] to resolve A and AAAA
/// directly to functions which argumnets are implementing [ToSocketAddrs]
/// Available only for the `sync` version. Tokio has ToSocketAddrs `sealed`.
#[derive(Clone, Debug)]
pub enum QDnsSockerAddr
{
    Ip(SocketAddr),
    Host(String, u16)
}

impl ToSocketAddrs for QDnsSockerAddr
{
    type Iter = vec::IntoIter<SocketAddr>;

    async 
    fn to_socket_addrs(&self) -> std::io::Result<Self::Iter> 
    {
        match self
        {
            QDnsSockerAddr::Ip(socket_addr) => 
                return Ok(vec![socket_addr.clone()].into_iter()),
            QDnsSockerAddr::Host(host, port) => 
            {
                let cfg = 
                    GLOBAL_CONFIG
                        .get()
                        .ok_or(
                            std::io::Error::new(
                                ErrorKind::NotSeekable, 
                                CDnsIOError::from(
                                    internal_error_map!(CDnsErrorType::ConfigError, 
                                        "global config is not available")
                                )
                            )
                        )?;

                let req0 = 
                    QDnsRequests
                        ::resolve_fqdn(&cfg.get_resolv_l(), 1, 2, host, 
                            QuerySetup::default())
                            .map_err(|e|
                                    std::io::Error::new(ErrorKind::InvalidData, 
                                        CDnsIOError::from(e))
                            )?;

                let mut resolver_res = 
                    Resolver::<ResolverStdErr>::new(cfg, ResolverStdErr);
                
                
                let res = 
                    resolver_res
                        .query(&req0)
                        .await
                        .map_err(|e| 
                            std::io::Error::new(ErrorKind::Other, CDnsIOError::from(e)))?
                        .collect_ok()
                        .into_iter()
                        .map(|resp|
                            resp
                                .get_responses()
                                .iter()
                                .map(|r| 
                                    r.get_rdata().get_ip().map(|f| SocketAddr::new(f, *port))
                                )
                                .collect::<Vec<Option<SocketAddr>>>()
                        )
                        .flatten()
                        .filter(|p| p.is_some())
                        .map(|v| v.unwrap())
                        .collect::<Vec<SocketAddr>>();

                return Ok( res.into_iter() );
            }
        }
    }
}


impl QDnsSockerAddr
{
    /// Creates instance for A and AAAA records resolution from configured
    /// in `/etc/resolv.conf` DNS servers. The instance performs the DNS resolve
    /// when passed to functions which arguments implements [ToSocketAddrs]. 
    /// 
    /// # Arguments 
    /// 
    /// * `host` - `domain`:`port` i.e example.com:443. The `ip``port` is also
    ///     possible and no DNS resolution will be performed.
    pub 
    fn resolve<D>(host: D) -> std::io::Result<Self> 
    where D: AsRef<str>
    {
        if let Ok(addr) = host.as_ref().parse::<SocketAddr>() 
        {
            return Ok(Self::Ip(addr));
        }
        else
        {
            let ref_host = host.as_ref();

            let (domain, port) = 
                match ref_host.split_once(":")
                {
                    Some((h, portno)) => 
                    {
                        let port: u16 = 
                            portno
                                .parse()
                                .map_err(|e| 
                                    std::io::Error::new(ErrorKind::InvalidData, format!("{}", e))
                                )?;

                        (h, port)
                    },
                    None => 
                        return Err(std::io::Error::new(ErrorKind::InvalidData, "missing prot number"))
                };
            
            return Ok(Self::Host(domain.to_string(), port));
        }
    }

    /// Same as `resolve` but port is provided separatly.
    ///     
    /// # Arguments 
    /// 
    /// * `host` - `domain` name i.e example.com. The `ip`` is also
    ///     possible and no DNS resolution will be performed.
    /// 
    /// * `port` - a port number to be added to the result.
    pub 
    fn resolve_port<D>(host: D, port: u16) -> std::io::Result<Self> 
    where D: AsRef<str>
    {
        if let Ok(addr) = host.as_ref().parse::<IpAddr>() 
        {
            return Ok(Self::Ip(SocketAddr::new(addr, port)));
        }
        else
        {   
            return Ok(Self::Host(host.as_ref().to_string(), port));
        }
    }
}

#[derive(Debug)]
struct PersistantConnections
{
    persistant_sockets: Vec<Rc<Box<dyn SocketTap>>>,
}

impl PersistantConnections
{
    fn new() -> Self
    {
        return Self{ persistant_sockets: Vec::new() };
    }

    fn invalidate(&mut self)
    {
        self.persistant_sockets.clear();
    }

    fn get(&self, rce: &ResolveConfEntry, force_reopen: bool) -> Option<Rc<Box<dyn SocketTap>>>
    {
        for item in self.persistant_sockets.iter()
        {
            if item.as_ref().as_ref() == rce
            {
                if force_reopen == true
                {
                    if let Err(_) = item.reconnect()
                    {
                        return None;
                    }
                }

                return Some(item.clone());
            }
        }

        return None;
    }

    fn add(&mut self, sock_tap: Box<dyn SocketTap>) -> Rc<Box<dyn SocketTap>>
    {
        let st = Rc::new(sock_tap);

        self.persistant_sockets.push(st.clone());

        return st;
    }
}

/// After constructing this instance, it can be used as a resolver. It cannot
/// be sent because it is not [Send] and not [Sync]. It is purely thread local.
/// 
/// ## System config
/// 
/// ```ignore
/// DnsConfigs::<DnsConfigGlobal>::init_global_config(None).unwrap();
/// 
/// let qse = QuerySetup::default().measure_time(true);
/// 
/// let mut res0 = 
///     Resolver::<ResolverStdErr>::new(GLOBAL_CONFIG.get().unwrap(), ResolverStdErr);
/// 
/// let req0 = 
///     QDnsRequests::resolve_a_aaaa_request(1, 2, ResolveConfigFamily::INET4, "4neko.org", qse)
///         .unwrap();
/// ```
/// 
/// ## Custom config
/// 
/// ```ignore
/// let cfg = 
///    "nameserver 1.1.1.1#@853#cloudflare-dns.com \n \
///    search .";
/// 
/// let hosts = 
///     DnsConfigs::<DnsConfigUser>::load_host(Path::new("/etc/hosts")).unwrap();
/// 
/// let cfg = 
///     DnsConfigs
///         ::<DnsConfigUser>
///         ::new_custom(
///             DnsConfigSource::SourceInstance(hosts), 
///             DnsConfigSource::SourceText(cfg)
///         )
///         .unwrap();
/// 
/// let mut res0 = 
///     Resolver::<ResolverStdErr>::new(&cfg, ResolverStdErr);
/// ```
/// 
/// # Generics
/// 
/// * `ERR` - an instance which implements [ErrorReport]. Used to report fatal 
///     errors.
#[derive(Debug)]
pub struct Resolver<ERR: ErrorReport>
{
    /// A `weak` reference to the [ResolveConfig] instance. In case if instance becomes invalid,
    /// all cached persistent connections should be stopped.
    resolv_cfg: ICoWWeak<ResolveConfig>,

    /// A `weak` reference to hosts config.
    hosts_cfg: ICoWWeak<HostConfig>,

    /// A storage for the connections which are reused.
    persistant_sockets: PersistantConnections,

    /// Error reporting.
    err: ERR,
}

impl<ERR: ErrorReport> Resolver<ERR>
{
    #[inline]
    fn create_socket(
        &mut self, 
        opts: &QuerySetup,
        force_tcp: bool, 
        resolver: &Arc<ResolveConfEntry>,
        resolv_cfg: &ResolveConfig
    ) -> CDnsResult<Rc<Box<dyn SocketTap>>>
    {
        let is_tls = resolver.get_tls_type();

        if is_tls == ConfigEntryTls::Tls
        {
            #[cfg(feature = "use_sync_tls")]
            {
                // check the cache if there is alive connection
                let Some(socket) = 
                    self.persistant_sockets.get(resolver.as_ref(), resolv_cfg.option_flags.is_reopen_socket())
                else
                {
                    let socket = 
                        NetworkTap
                            ::<TcpTlsConnection>
                            ::new_tls(resolver.clone(), opts.get_timeout(resolv_cfg), CDdnsGlobals::get_tcp_conn_timeout())?;

                        
                    return Ok(self.persistant_sockets.add(socket));
                };

                return Ok(socket);
            }

            #[cfg(not(feature = "use_sync_tls"))]
            internal_error!(CDnsErrorType::SocketNotSupported, 
                "socket not supported: '{}'", resolver.get_tls_type());
        }
        else if is_tls == ConfigEntryTls::Https
        {
            #[cfg(feature = "use_sync_tls")]
            {
                 // check the cache if there is alive connection
                let Some(socket) = 
                    self.persistant_sockets.get(resolver.as_ref(), resolv_cfg.option_flags.is_reopen_socket())
                else
                {
                    let socket = 
                        NetworkTap
                            ::<TcpHttpsConnection>
                            ::new_https(resolver.clone(), opts.get_timeout(resolv_cfg), CDdnsGlobals::get_tcp_conn_timeout())?;

                        
                    return Ok(self.persistant_sockets.add(socket));
                };

                return Ok(socket);
            }

            #[cfg(not(feature = "use_sync_tls"))]
            internal_error!(CDnsErrorType::SocketNotSupported, 
                "socket not supported: '{}'", resolver.get_tls_type());
        }
        else if resolv_cfg.option_flags.is_force_tcp() == true || force_tcp == true
        {
            // check the cache if there is alive connection
            let Some(socket) = 
                self.persistant_sockets.get(resolver.as_ref(), resolv_cfg.option_flags.is_reopen_socket())
            else
            {
                let socket = 
                    NetworkTap
                        ::<TcpStream>
                        ::new_tcp(resolver.clone(), opts.get_timeout(resolv_cfg), 
                    CDdnsGlobals::get_tcp_conn_timeout())?;

                    
                return Ok(self.persistant_sockets.add(socket));
            };

            return Ok(socket);
        }
        else
        {
            /*
            // check the cache if there is alive connection
            let Some(socket) = 
                self.persistant_sockets.get(resolver.as_ref(), resolv_cfg.option_flags.is_reopen_socket())
            else
            {
                let socket = 
                    NetworkTap
                        ::<UdpSocket>
                        ::new_udp(resolver.clone(), opts.get_timeout(resolv_cfg))?;

                return Ok(self.persistant_sockets.add(socket));
            };*/
            // don't store UDP sockets
            let socket = 
                    NetworkTap
                        ::<UdpSocket>
                        ::new_udp(resolver.clone(), opts.get_timeout(resolv_cfg))
                            .map(|s| Rc::new(s));

            return socket;
        }
    }

    fn lookup_hosts_internal(&self, hlist: &HostConfig, qname: &QDnsName, qtype: QType, opts: &QuerySetup) -> CDnsResult<Option<QDnsQuery>>
    {
        if qtype.is_hosts() == false
        {
            return Ok(None);
        }

        // check if we need to measure time
        let now = 
            if opts.get_measure_time() == true
            {
                Some(Instant::now())
            }
            else
            {
                None
            };

        if let Some(ip) = <&QDnsName as Into<Option<IpAddr>>>::into(qname)
        {
             let Some(host_name_ent) = hlist.search_by_ip(&ip)
                else { return Ok(None) };

            let drp = DnsResponsePayload::new_local(qtype, host_name_ent).unwrap();  

            return Ok(Some(QDnsQuery::from_local(drp, now.as_ref())));
            //dnsquries.push(req.get_assigned_id(), Ok(QDnsQuery::from_local(drp, now))); 
        }
        else
        {
            let req_name = qname.get_query();

            let Some(host_name_ent) = hlist.search_by_fqdn(qtype, req_name)
                else { return Ok(None) };
            
            let drp = DnsResponsePayload::new_local(qtype, host_name_ent).unwrap();
            
            return Ok(Some(QDnsQuery::from_local(drp, now.as_ref())));
            // store to list
            //dnsquries.push(req.get_assigned_id(), Ok(QDnsQuery::from_local(drp, now)));
        }
    }

    async 
    fn process_hosts(&self, reqs: &mut Vec<&DnsRequest>, opts: &QuerySetup) -> CDnsResult<QDnsQueryResult>
    {
        let mut qqr = QDnsQueryResult::default();

        if opts.get_ignore_hosts() == false
        {   
            let hlist = 
                self.hosts_cfg.aquire()
                    .ok_or(
                        internal_error_map!(CDnsErrorType::ConfigError, "resolver's config has gone!")
                    )?;

            reqs.retain(
                |r|
                {
                    if r.payload.qtype.is_hosts() == false
                    {
                        return true;
                    }

                    match self.lookup_hosts_internal(&hlist, &r.get_name(), r.get_type(), opts)
                    {
                        Ok(Some(resp)) => 
                        {
                            qqr.push(r.get_assigned_id(), Ok(resp));
                            return false;
                        },
                        Ok(None) =>
                        {
                            return true;
                        },
                        Err(e) =>
                        {
                            self.err.report(e);

                            return true;
                        }
                    }
                }
            );
        }

        return Ok(qqr);
    }

    fn process_request(
        &mut self, 
        resolv_cfg: &ICoWWeakRead<'_, ResolveConfig>, 
        reqs: &mut Vec<&DnsRequest>, 
        opts: &QuerySetup, 
    ) -> QDnsQueryResult
    {
        let mut responses: QDnsQueryResult = QDnsQueryResult::new();

        // check if config was reloaded before the read was aquired
        if resolv_cfg.item_updated() == true
        {
            // remove all previosuly created sockets
            self.persistant_sockets.invalidate();
        }

        for _ in 0..resolv_cfg.get_attempts()
        {
            for resolver in resolv_cfg.get_resolvers_iter()
            {
                let res = 
                    if resolv_cfg.option_flags.is_no_parallel() == true
                    {
                        self.query_exec_seq(opts, reqs, resolver, &resolv_cfg, false)
                    }
                    else
                    {
                        self.query_exec_pipelined(opts, reqs, resolver, &resolv_cfg, false)
                    };

                match res
                {
                    Ok(resp) =>
                    {
                        responses.extend(resp, opts);
                    },
                    Err(e) =>
                    {
                        self.err.report(e);
                    }
                }

                // if not requests have left, quit
                if reqs.is_empty() == true
                {
                    break;
                }            
            }
        }
        
        return responses;
    }

    fn query_exec_pipelined(
        &mut self, 
        opts: &QuerySetup,
        reqs: &mut Vec<&DnsRequest>,
        resolver: &Arc<ResolveConfEntry>,
        resolv_cfg: &ICoWWeakRead<'_, ResolveConfig>,
        requery: bool,
    ) -> CDnsResult<QDnsQueryResult>
    {
        let force_tcp = resolv_cfg.option_flags.is_force_tcp() | requery;

        // create socket and connect
        let tap = 
            self.create_socket(opts, force_tcp, &resolver, resolv_cfg)?;

        let mut req_pkt_map: BTreeMap<u16, (&DnsRequest, Option<Instant>)> = BTreeMap::new();


        // send request mapping pkt
        while let Some(req) = reqs.pop()
        {
            let rand_id = 
                loop
                {
                    let rand_id = rand::random();

                    if req_pkt_map.contains_key(&rand_id) == false
                    {
                        break rand_id;
                    }
                };

            // convert to byte packet (the error returned is global error i.e OOM)
            let pkt = req.to_bytes(tap.should_append_len(), rand_id)?;

            // check if we need to measure time
            let now = 
                if opts.get_measure_time() == true
                {
                    Some(Instant::now())
                }
                else
                {
                    None
                };

            // send to DNS server, if error happens, then stop processing this server
            tap.send(pkt.as_slice())?;

            req_pkt_map.insert(rand_id, (req, now));
        }

        // a responses collection
        let mut responses = QDnsQueryResult::default();

        // a responses which should be made to next ns if any
        let mut tcp_requery: Vec<&DnsRequest> = Vec::new();

        // wait for responses
        while req_pkt_map.is_empty() == false
        {
            let Some(ans_pkt) = tap.recv()?
            else
            {
                // report error
                self.err.report(
                    internal_error_map!(CDnsErrorType::RequestTimeout, 
                        "timeout waiting for responses count: '{}'", req_pkt_map.len())
                );

                // fill the responses with timeout error, maybe it will be resolved at other
                // DNS server
                for (_, (req, _)) in req_pkt_map
                {
                    responses.push(
                        req.get_assigned_id(), 
                        Err(
                                internal_error_map!(CDnsErrorType::RequestTimeout, 
                                    "request timeout for {}", req)
                            )
                    );

                    // return back to the list
                    reqs.push(req);
                }

                // timeout loop to return result
                break;
            };

            let req_ans_par = DnsRequestAnswerParser::try_from(ans_pkt.as_slice())?;
            let req_ans_id = req_ans_par.get_pkt_id();

            // remove the record from the request mapping
            let Some((mapped_req, inst_time)) = req_pkt_map.remove(&req_ans_id)
            else
            {
                // report error
                self.err.report(
                    internal_error_map!(CDnsErrorType::DnsResponse(CDnsErrorDnsResponse::DnsUnknownReqID), 
                        "received pkt with unknown req id: {}", req_ans_id)
                );

                continue;
            };

            // convert into answer
            let mut ans = req_ans_par.into_answer(mapped_req.get_assigned_id())?;                

            // verify the response
            ans.1.verify(None, &ans.0, mapped_req)?;

            // verified
            let res_query = 
                QDnsQuery::from_response(tap.get_remote_addr(), ans.0, ans.1, inst_time);

            if let Ok(ref qdns) = res_query
            {
                if qdns.get_status().should_try_tcp() == true && force_tcp == false
                {
                    tcp_requery.push(mapped_req);
                }
                else if qdns.should_check_next_ns(opts.get_next_ns_ok()) == true
                {
                    // store the result and overwrite it later
                    responses.push(mapped_req.get_assigned_id(), res_query);

                    // requery
                    reqs.push(mapped_req);
                }
                else
                {
                    // just store the result
                    responses.push(mapped_req.get_assigned_id(), res_query);
                }
            }
            else
            {
                // just store error
                responses.push(mapped_req.get_assigned_id(), res_query);
            }
            
        }

        // check if there is something for TCP
        if tcp_requery.is_empty() == false
        {
            let res = 
                self.query_exec_pipelined(opts, &mut tcp_requery, resolver, resolv_cfg, true)?;

            // merge lists
            responses.extend(res, opts);

            // merge back reqs which are for next ns
            if tcp_requery.is_empty() == false
            {
                reqs.extend(tcp_requery);
            }
        }

        return Ok(responses);
    }

    /// Runs sequentually
    fn query_exec_seq(
        &mut self, 
        opts: &QuerySetup,
        reqs: &mut Vec<&DnsRequest>,
        resolver: &Arc<ResolveConfEntry>,
        resolv_cfg: &ICoWWeakRead<'_, ResolveConfig>,
        requery: bool,
    ) -> CDnsResult<QDnsQueryResult>
    {
        let mut responses = QDnsQueryResult::default();

        let force_tcp = resolv_cfg.option_flags.is_force_tcp() || requery;

        let mut tcp_requery: Vec<&DnsRequest> = Vec::new();
        let mut next_ns_req: Vec<&DnsRequest> = Vec::new();

        // create socket and connect
        let tap = 
            self
                .create_socket(opts, force_tcp, &resolver, resolv_cfg)?;

        while let Some(req) = reqs.pop()
        {
            let pkt_ran_id = rand::random();

            // convert to byte packet (the error returned is global error i.e OOM)
            let pkt = req.to_bytes(tap.should_append_len(), pkt_ran_id)?;
            
            // check if we need to measure time
            let now = 
                if opts.get_measure_time() == true
                {
                    Some(Instant::now())
                }
                else
                {
                    None
                };

            // send to DNS server, if error happens, then stop processing this server
            tap.send(pkt.as_slice())?;

            let Some(ans_pkt) = tap.recv()?
            else
            {
                // report error
                self.err.report(
                    internal_error_map!(CDnsErrorType::RequestTimeout, 
                        "timeout waiting for request: '{}'", req)
                );

                return Err(
                    internal_error_map!(CDnsErrorType::RequestTimeout, "request timeout {}", req)
                );
            };

            let mut ans = 
                DnsRequestAnswerParser::try_from(ans_pkt.as_slice())?
                    .into_answer(req.get_assigned_id())?;                

            // verify the response
            ans.1.verify(Some(pkt_ran_id), &ans.0, req)?;

            // verified
            let res_query = QDnsQuery::from_response(tap.get_remote_addr(), ans.0, ans.1, now);

            if let Ok(ref qdns) = res_query
            {
                if qdns.get_status().should_try_tcp() == true && force_tcp == false
                {
                    tcp_requery.push(req);
                }
                else if qdns.should_check_next_ns(opts.get_next_ns_ok()) == true
                {
                    // store the result and overwrite it later
                    responses.push_req(req, res_query);

                    // requery
                    next_ns_req.push(req);
                }
                else
                {
                    // just store the result
                    responses.push_req(req, res_query);
                }
            }
            else
            {
                // just store error
                responses.push_req(req, res_query);
            }
        }
        
        
        // check if there is something for TCP
        if tcp_requery.is_empty() == false
        {
            let res = 
                self.query_exec_seq(opts, &mut tcp_requery, resolver, resolv_cfg, true)?;

            // merge lists
            responses.extend(res, opts);

            // merge back reqs which are for next ns
            if tcp_requery.is_empty() == false
            {
                reqs.extend(tcp_requery);
            }
        }

        // return all which should be req  at other NS
        reqs.extend(next_ns_req);

        return Ok(responses);
    }
}

impl<ERR: ErrorReport> Resolver<ERR>
{
    /// Creates new instance. A resolve and hosts configurations should be 
    /// provided and a error reporting.
    pub 
    fn new<CFG: ConfigGetter>(config: CFG, err: ERR) -> Self
    {
        return 
            Self
            {
                resolv_cfg: 
                    config.get_resolv().get_reader(),
                hosts_cfg:
                    config.get_hosts().get_reader(),
                persistant_sockets: 
                    PersistantConnections::new(),
                err: 
                    err,
            };
    }

    /// Performs lookup only in the `hosts` file. 
    /// 
    /// # Generics
    /// 
    /// * `R` - a type should implement [TryInto] [QDnsName]
    /// 
    /// # Arguments
    /// 
    /// * `req` - a name or IP to lookup
    /// 
    /// * `qtype` - a type of the request. Only [QType::A], [QType::AAAA], [QType::PTR]
    ///     are allowed.
    /// 
    /// * `opts` - a query override
    /// 
    /// # Returns
    /// 
    /// A [Result] as alias [CDnsResult] is returned.
    /// 
    /// A [Option::None] is returned if the record was not found, including the condition
    ///     when the `qtype` is not one of the allowed types.
    pub 
    fn lookup_hosts<R>(&self, req: R, qtype: QType, opts: &QuerySetup) -> CDnsResult<Option<QDnsQuery>>
    where 
        R: TryInto<QDnsName, Error = CDnsError>
    {
        let hlist = 
            self.hosts_cfg.aquire()
                .ok_or(
                    internal_error_map!(CDnsErrorType::ConfigError, "resolver's config has gone!")
                )?;

        return self.lookup_hosts_internal(&hlist, &req.try_into()?, qtype, opts);
    }

    
    /// Attempts to resolve the requests.
    pub async 
    fn query(&mut self, reqs: &QDnsRequests) -> CDnsResult<QDnsQueryResult>
    {
        let resolv_cfg = 
            self.resolv_cfg.aquire()
                .ok_or(
                    internal_error_map!(CDnsErrorType::ConfigError, "resolver's config has gone!")
                )?;

        let mut mirrowed_reqs = reqs.mirror();

        // determine where to look firstly i.e file -> bind, bind -> file
        // or bind only, or file only
        let qqr = 
            if resolv_cfg.lookup.is_file_first() == true
            {
                let mut qqr = self.process_hosts(&mut mirrowed_reqs, &reqs.opts)?;

                if mirrowed_reqs.is_empty() == false
                {
                    let pr = self.process_request(&resolv_cfg, &mut mirrowed_reqs, &reqs.opts);

                    qqr.extend(pr, &reqs.opts);
                }

                qqr
            }
            else
            {
                let mut qqr = self.process_request(&resolv_cfg, &mut mirrowed_reqs, &reqs.opts);

                if resolv_cfg.lookup.is_file_first() == false && mirrowed_reqs.is_empty() == false
                {
                    let res = self.process_hosts(&mut mirrowed_reqs, &reqs.opts)?;

                    qqr.extend(res, &reqs.opts);
                }

                qqr
            };

        

        return Ok(qqr);
    }

}