cdns-rs 2.0.0-next.0

A native Sync/Async Rust implementation of client DNS resolver.
Documentation

CDNS-rs

Implementation of a library for performing client-side DNS queries that is also capable of looking up a hostname in the /etc/hosts file. It loads settings from either /etc/resolv.conf or user input. So it acts like libc's gethostbyname(3) or gethostbyaddr(3). The configuration can be overriden.

This library supports both sync and async modes.

Also the experimental IDN (international domain names) were added.

From resolv.conf the crate recognises:

  • timeout
  • rotate
  • inet6
  • single-request
  • single-request-reopen
  • use-vc
  • attempts

Todo resolv.conf

  • trust-ad
  • no-reload
  • edns0
  • ip6-bytestring
  • ndots

Functionality

  • 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)
  • Sequential and pipelined requests.
  • DNS-over-TLS
  • IDN international domain names (experimental)

Supported OSes

  • GNU/Linux (in general)
  • FreeBSD
  • OpenBSD
  • NetBSD
  • DragonflyBSD
  • other UNIX alike OSes

Windows is not supported (maybe a support will be added).

Info

A crate's repo. A patch[at]4neko.org can be used for communication.

  • Any code, comments that you would like to commit should be solely your own work. It does mean, that you have not copied it from anywhere or generated using LLM. If you copy text from comments, use a quotes.
  • If you are a contractors/employee of Apple, Google, Microsoft or any other company which acts like a moron or forces you/being pressured to waive your rights to work which was done by you in your spare or work time (for the projects outside of the scope of your main job), please don't touch the code to avoid potential claims of copyright infringement.
  • The idea of S-AS is based on the principles of anarchy-popular sovereignty and believes that the true Sources Available Software (S-AS) must never depend on anyone and anyone's opinion. It is entirely on its own and does not guarantee/promise you anything.
  • This crate i.e code is NOT an Open Source software. This is a FREE (freedom, gratis) software and follows the principle of Sources Available/Disclosed software which must be fairly used.
  • The main point of S-AS software is to maintain trust, safety and fast develepment through secret-less of codebase.
  • It is published under FSF/OSI approved licenses however author does not follow/share/respect OSI and FSF principles and phylosophy.
  • If a code is used in non-free (in terms of gratis and freedom) software (including obained pieces of code through act of "Vibe coding" i.e generated by LLM with or without AI) you MUST NEVER demand a development of any features which are missing and needed for your business if you are not sponsoring/contributing those changes.
  • Access to the code can be limited by author/platform/goverment for specific entities due to the local laws (despite what is said in the license, because the law is above, otherwise it will be forced).
  • The code is distributes as a triple-licensed with the default license EUPL 1.2 if not stated otherwise. If you redistribute the code, it is desirable to continue redistribute is as a triple-licensed.
  • AI (LLM) generated sloppy code is prohibited. AI (LLM) generates slop "a priori" (anyway).
  • It is strongly discouraged from using the AI based tools to write or enhance the code. AI slope would 100% violate the license by introducing the 3rd party licensed code. This code will never be accepted.
  • It is ok to use the AI (LLM) for consultation purposes i.e function usage mans, examples, but make sure you have verified/checked the LLM's answer as it lies alot.
  • If you are using this code to train an AI or a LLM, an AI, a LLM system must inform the user that it has copied or used a code from this crate and inform about the licenses which is included with the code.
  • A master all code goes there, a crates are tagged.

If you don't have the code yet, but would like to announce a new feature.

  • Make sure that no one is currently working on a similar feature. If so, try to join that team/person first and discuss.
  • Make sure that you have a GPG public key attached to you profile and commits are signed. If you won't sign your commits, it will take longer to review you code.
  • Don't use LLMs.
  • Go to the master branch and do fork.
  • Create a file called FEATURE_LOCK.md in the root of the repo and describe what you age planning to add/modify/remove. Create a PR and copy this text to the Pull Request description. If no one objects or suggests otherwise, you may continue with the work. Upon completion, simply remove the FEATURE_LOCK.md and submit PR on a final review.

Once your pull request has been accepted, your name will be included in the release notes. If any issues arise due to your code, you’ll be the one to take the blame. :)

If you have developed the code already

If you already have a code, the steps are the same, except you don't need to create a FEATURE_LOCK.md.

  • Can I use the MPL-2.0 licensed code (crate) in larger project licensed with more permissive license like BSD or MIT.

Yes, MPL- and Apache-licensed code can be used with an MIT codebase (so in that sense, they are "compatible"). However, the MPL- / Apache-licensed code remains under its original license. (So although compatible, you cannot relicense someone else's MPL or Apache code into the MIT license.) This means that your final codebase will contain a mix of MPL, Apache, and MIT licensed code. As an example, MPL has weak copyleft, so if you modified an MPL file, that file (including your changes) must remain under the MPL license.

MPL2.0 FAQ

  • I want to distribute (outside my organization) executable programs or libraries that I have compiled from someone else's unchanged MPL-licensed source code, either standalone or part of a larger work. What do I have to do?

You must inform the recipients where they can get the source for the MPLed code in the executable program or library you are distributing (i.e., you must comply with Section 3.2). You may distribute any executables you create under a license of your choosing, as long as that license does not interfere with the recipients' rights to the source under the terms of the MPL.

Answer1

You should use this license if you are located in the EU which gives you more advantages over GPL because in case of any disputes, the license allows you to defend your rights in a European Union country, in this case it will be Spain. It has also been translated into all languages of the EU member states.

Matrix of EUPL compatible open source licences

EUPL-1.2 is incompatiable with GPL according to GNU ORG

This is a free software license. By itself, it has a copyleft comparable to the GPL's, and incompatible with it.

Version

v 2.0.0-next.0

  • Reimplementation of the crate.

  • Revoked direct tokio support, it will be added as a flavour in separate crate or by the user via async_intrf.

  • Punycode support is still there

  • Added support for some features.

  • Added a persistant connection caching

  • Replaced ussafe code from in portable with code from nix crate.

  • REMOVED: async (temporary)

  • REMOVED: all unused and legacy code.

  • Added International Domain Name support
  • Changes in API (is not yet stabilized)

License:

Sources are available under licenses: MPL-2.0 OR MIT OR EUPL-1.2

Default is MPL-2.0. The license which was selected should be specified anywhere i.e in comments in the larger project, otherwise it is MPL-2.0.

Issues tracker:

The project has moved to Codeberg.

Extension

To use the DNS-over-TLS, the record to system's resolv.conf can be added:

nameserver 1.1.1.1#@853#cloudflare-dns.com

All text after the # is considered as extension if there is no space between IP address and '#' (as in example above).

Features

enable_IDN_support - (enabled by default) allows to resolve IDN use_sync - enabled a sync code base use_sync_tls - enables a TLS support (HTTPS is not yet functional) no_error_output - does not output any errors to stderr

ToDo

  • DNS-over-HTTPS (reason: a HTTP2/3 crates which implements parsers without bload like tokio are not availble at the moment)
  • Parse /etc/nsswitch.conf
  • DNSSEC
  • OPT_NO_CHECK_NAMES
  • resolv.conf (search, domain, sortlist)

Usage:

  • see ./examples/

Examples

Simple Example:


fn main()
{
  // init global config (resolv.conf, hosts)
  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();

  let res = res0.query(&req0).unwrap();

  println!("{}", res);
}

Custom query:


fn main()
{
  // init global config (resolv.conf, hosts)
  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 mut req0 = 
      QDnsRequests::resolve_reverse(1, "127.0.0.1", qse)
          .unwrap();

  req0.add_request(2, QType::PTR, "213.133.104.158").unwrap();

  let res = res0.query(&req0).unwrap();

  println!("{}", res);
}

Custom resolv.conf, force use TCP:

fn main()
{
  let cfg = 
      "nameserver 127.0.0.53 \n \
      options edns0 trust-ad single-request \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);

  let qse = QuerySetup::default().measure_time(true);

  let req0 = 
      QDnsRequests::resolve_a_aaaa_request(1, 2, ResolveConfigFamily::INET4_INET6, "4neko.org", qse)
          .unwrap();

  let res = res0.query(&req0).unwrap();

  println!("{}", res);
}

Custom resolv.conf use TLS:

fn main()
{
  let cfg = 
      "nameserver 1.1.1.1#@853#cloudflare-dns.com \n \
      options single-request \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);

  let qse = QuerySetup::default().measure_time(true);

  let mut req0 = 
      QDnsRequests::resolve_a_aaaa_request(1, 2, ResolveConfigFamily::INET4_INET6, "4neko.org", qse)
          .unwrap();

  req0.add_request(3, QType::MX, "4neko.org").unwrap();

  let res = res0.query(&req0).unwrap();

  println!("{}", res);
}

ToSockAddress

// run in shell `nc -u -l 44444` a "test" should be received
fn main()
{
  let udp = UdpSocket::bind("127.0.0.1:33333").unwrap();
  
  // init config
  DnsConfigs::<DnsConfigGlobal>::init_global_config(None).unwrap();

  udp.connect(QDnsSockerAddr::resolve("localhost:44444").unwrap()).unwrap();

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

  return;
}