cdns_rs/

lib.rs

/*-
 * cdns-rs - a simple sync/async DNS query library
 * 
 * Copyright (C) 2020  Aleksandr Morozov
 * 
 * Copyright 2025 Aleksandr Morozov
 * 
 * Licensed under the EUPL, Version 1.2 or - as soon they will be approved by
 * the European Commission - subsequent versions of the EUPL (the "Licence").
 * 
 * You may not use this work except in compliance with the Licence.
 * 
 * You may obtain a copy of the Licence at:
 * 
 *    https://joinup.ec.europa.eu/software/page/eupl
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * Licence for the specific language governing permissions and limitations
 * under the Licence.
 */

/*! cdns-rs
    # CDns-rs

    v 1.0.0 

    An implementation of client side DNS query library which also is able to look for host name in `/etc/hosts`.  
    Also it is able to `/etc/resolv.conf` and uses options from this file to configure itself. So it acts like libc's `gethostbyname(3)` or `gethostbyaddr(3)`. The configuration can be overriden.

    This library supports both async and sync code. At the moment async part is not available because:
    - it is based on the sync realization because async code is based on sync code and sync code is unstable at the moment
    - it requires proper porting from sync, because sync uses `poll(2)` to achieve the parallel name resolution

    ## Supported

    - Sending and receiving responses via TCP/UDP
    - Reacting on the message truncated event by trying TCP
    - Parsing /etc/hosts (all options)
    - Partial parsing /etc/resolve.conf (all options)
    - Async and Sync code (separate implementations) 
    - Sequential and pipelined requests.
    - DNS-over-TLS

    ## ToDo
    - DNS-over-HTTPS
    - Parse /etc/nsswitch.conf
    - DNSSEC
    - OPT_NO_CHECK_NAMES
    - resolv.conf (search, domain, sortlist)


    Usage:  

    - see ./examples/

    Simple Example:

    ```rust
    use cdns_rs::sync::{QDns, QuerySetup, QType, request};

    fn main()
    {
        // a, aaaa
        let res_a = request::resolve_fqdn("protonmail.com", None).unwrap();

        println!("A/AAAA:");
        for a in res_a
        {
            println!("\t{}", a);
        }
    }
    ```

    Custom query:

    ```rust
    use cdns_rs::sync::{QDns, QuerySetup, QType, request, caches::CACHE};

    fn main()
    {
        // soa
        let mut dns_req = 
            QDns::make_empty(None, QuerySetup::default()).unwrap();

        dns_req.add_request(QType::SOA, "protonmail.com");

        // sending request and receiving results
        let res = dns_req.query();


        println!("SOA:");
        let soa_res = res.get_result();

        if soa_res.is_err() == true
        {
            println!("{}", soa_res.err().unwrap());
        }
        else
        {
            let soa = soa_res.unwrap();

            if soa.is_empty() == true
            {
                println!("\tNo SOA found!")
            }
            else
            {
                for s in soa
                {
                    for i in s.resp
                    {
                        println!("\t{}", i)
                    }
                }
            }
        
        }
    }
    ```

    ### Custom resolv.conf use TCP:
    ```rust
    use std::{net::{IpAddr, SocketAddr}, sync::Arc, time::Instant};

    use cdns_rs::{cfg_resolv_parser::{OptionFlags, ResolveConfEntry}, common::bind_all, sync::{request, ResolveConfig}};

    fn main()
    {
        let now = Instant::now();

        let cfg = 
        "nameserver 8.8.8.8 \n\
        options use-vc";

        //  -- or --
        let resolver_ip: IpAddr = "8.8.8.8".parse().unwrap();

        let mut resolve = ResolveConfig::default();

        resolve.nameservers.push(Arc::new(ResolveConfEntry::new(SocketAddr::new(resolver_ip, 53), None, bind_all(resolver_ip)).unwrap()));
        resolve.option_flags = OptionFlags::OPT_USE_VC;

        let cust_parsed = Arc::new(ResolveConfig::custom_config(cfg).unwrap());
        let cust_manual = Arc::new(resolve);

        assert_eq!(cust_parsed, cust_manual);

        // a, aaaa
        let res_a = request::resolve_fqdn("protonmail.com", Some(cust_parsed)).unwrap();

        let elapsed = now.elapsed();
        println!("Elapsed: {:.2?}", elapsed);

        println!("A/AAAA:");
        for a in res_a
        {
            println!("\t{}", a);
        }

        return;
    }
    ```

    ### Custom resolv.conf use TLS:
    ```rust
    use std::{sync::Arc, time::Instant};

    use cdns_rs::sync::{request, ResolveConfig};

    fn main()
    {
        let now = Instant::now();

        let cfg = "nameserver 1.1.1.1#@853#cloudflare-dns.com \n\
        options use-vc single-request";

        let cust = Arc::new(ResolveConfig::custom_config(cfg).unwrap());

        // a, aaaa
        let res_a = request::resolve_fqdn("google.com", Some(cust.clone())).unwrap();


        let elapsed = now.elapsed();
        println!("Elapsed: {:.2?}", elapsed);

        println!("A/AAAA:");
        for a in res_a
        {
            println!("\t{}", a);
        }

        return;
    }

    ```

    ToSockAddress

    ```rust
    use std::net::UdpSocket;

    use cdns_rs::sync::query::QDnsSockerAddr;



    // run in shell `nc -u -l 44444` a "test" should be received
    fn main()
    {
        let udp = UdpSocket::bind("127.0.0.1:33333").unwrap();
        udp.connect(QDnsSockerAddr::resolve("localhost:44444").unwrap()).unwrap();

        udp.send("test".as_bytes()).unwrap();

        return;
    }
    ```
 */



extern crate rand;
#[macro_use] extern crate bitflags;
extern crate nix;

#[cfg(feature = "use_sync")]
extern crate rustls;

#[cfg(feature = "use_async")]
extern crate tokio_rustls;

#[cfg(any(feature = "use_sync", feature = "use_async"))]
extern crate webpki;
#[cfg(any(feature = "use_sync", feature = "use_async"))]
extern crate webpki_roots;
//extern crate webrtc_dtls;


extern crate httparse;

#[cfg(feature = "use_sync")]
extern crate byteorder;
#[cfg(feature = "use_sync")]
extern crate crossbeam_utils;


#[cfg(feature = "use_async")]
extern crate async_recursion;
#[cfg(feature = "use_async")]
extern crate tokio;
#[cfg(feature = "use_async")]
extern crate tokio_byteorder;
#[cfg(feature = "use_async")]
extern crate async_trait;


#[cfg(feature = "use_async")]
pub mod a_sync;

#[cfg(feature = "use_sync")]
pub mod sync;

pub mod cfg_host_parser;
pub mod cfg_resolv_parser;
mod network_common;


mod query_private;

pub mod query;
pub mod common;
mod portable;
#[macro_use] pub mod error;
mod tokenizer;

pub use error::*;
pub use common::{QType, DnsResponsePayload, DnsRdata};
pub use query::{QDnsQueryResult, QDnsQuery, QuerySetup, QDnsQueryRec};