rhostname

#pragma once
 
#include <randolf/rlabel>
 
#include <algorithm>
#include <atomic>
#include <cstring>
#include <vector>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  This @ref rhostname class provides an object-oriented internet hostname.
 
  @par Features
 
  Some of the key features are:
 
     - constructors with sensible defaults help to simplify coding
     - documentation includes code samples (with @c \#include lines as needed)
     - thread-safety is noted where it is absolutely available (or where some
       caution is warranted)
     - can handle ASCIIZ (C-strings) without needing to specify string length
     - can handle @c std::string (which tracks its own string length)
 
  @par Use case
 
  Validation of the format of a hostname from a variety of angles is helpful
  in ensuring that hostnames received from elsewhere comply with internet
  standards.
 
  @par Background
 
  I created this class to make it easier to write internet server daemons.  I
  also use it in my @ref rmailaddr class when extracting the @c domain-part.
 
  @par Getting started
 
  @author Randolf Richardson
  @version 1.00
  @par History
  2023-Jan-17 v1.00 Initial version
 
  @par Conventions
  Lower-case letter "h" is regularly used in partial example code to represent
  an instantiated rhostname object.
 
  An ASCIIZ string is a C-string (char* array) that includes a terminating null
  (0) character at the end.
 
  @par Notes
 
  I use the term "ASCIIZ string" to indicate an array of characters that's
  terminated by a 0 (a.k.a., null).  Although this is very much the same as a
  C-string, the difference is that in many API functions a C-string must often
  be accompanied by its length value.  When referring to an ASCIIZ string, I'm
  intentionally indicating that the length of the string is not needed because
  the string is null-terminated.  (This term was also commonly used in assembly
  language programming in the 1970s, 1980s, and 1990s, and as far as I know is
  still used by machine language programmers today.)
 
  @par Examples
 
  @code{.cpp}
    #include <iostream>  // std::cout, std::cerr, std::endl, etc.
    #include <stdexcept> // std::invalid_argument exception
 
    #include <randolf/rhostname>
 
    int main(int argc, char *argv[]) {
      try {
        randolf::rhostname h("www.example.com");
      } catch (const std::invalid_argument e) {
        std::cerr << "Hostname format exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      } catch (const std::exception e) {
        std::cerr << "Other exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      }
      return EXIT_SUCCESS;
    } // -x- int main -x-
  @endcode
 
  Parameter stacking is supported (with methods that return @c rhostname*); in
  this example, notice that semicolons (";") and "h." references are omittted
  (when compared with the above):
 
  @code{.cpp}
    #include <iostream>  // std::cout, std::cerr, std::endl, etc.
    #include <stdexcept> // std::invalid_argument exception
 
    #include <randolf/rhostname>
 
    int main(int argc, char *argv[]) {
      try {
        randolf::rhostname h("www.example.com");
      } catch (const std::invalid_argument e) {
        std::cerr << "Hostname format exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      } catch (const std::exception e) {
        std::cerr << "Other exception: " << e.what() << std::endl;
        return EXIT_FAILURE;
      }
      return EXIT_SUCCESS;
    } // -x- int main -x-
  @endcode
  *///=========================================================================
  class rhostname {
 
    private:
      // --------------------------------------------------------------------------
      // Hostname variables.
      // --------------------------------------------------------------------------
      std::vector<rlabel> __labels{};
      int                 __flags = 0;
      std::atomic_bool    __fqdn  = false;
      std::atomic_bool    __utf8  = false;
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty rhostname that doesn't qualify as a properly-formatted
      hostname (because the minimum length of a valid hostname is 1 character).
 
      Instantiating an empty rhostname is particularly useful for header-file
      definitions; for example:
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        randolf::rhostname h; //   <-- Empty rhostname initialization (no exceptions)
 
        int main(int argc, char *argv[]) {
          try {
            h.set("www.example.com");
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @see hostname
      *///=========================================================================
      rhostname() noexcept {}; // -x- constructor rhostname -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rhostname.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rhostname h("www.example.com");
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @throws std::invalid_argument If the hostname is improperly formatted (flags
              can limit or eliminate conditions for throwing this exception)
      @throws std::out_of_range if any DNS RR formatted label's size would require
              reaching beyond the end of the hostname provided (this is called a
              buffer overrun, which is a potential security risk that can also
              cause a segmentation fault)
      @see set()
      *///=========================================================================
      rhostname(
      /// The hostname as a std::string object
      const std::string hostname,
      /// @ref rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) {
        this->set(hostname.data(), hostname.size(), flags);
      }; // -x- constructor rhostname -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an rhostname.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            char[] example = "www.example.com";
            randolf::rhostname h(example, 15);
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @throws std::invalid_argument If the hostname is improperly formatted (flags
              can limit or eliminate conditions for throwing this exception)
      @throws std::out_of_range if any DNS RR formatted label's size would require
              reaching beyond the end of the hostname provided (this is called a
              buffer overrun, which is a potential security risk that can also
              cause a segmentation fault)
      @see set()
      *///=========================================================================
      rhostname(
      /// The hostname as a char* array
      const char* hostname,
      /// Length of hostname string (0 = ASCIIZ string)
      const size_t len = 0,
      /// @ref rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) {
        this->set(hostname, len, flags);
      }; // -x- constructor rhostname -x-
 
      /*======================================================================*//**
      @brief
      Clear this rhostname's underlying hostname and reset all states.
      @returns The same rhostname object so as to facilitate stacking
      *///=========================================================================
      rhostname* clear() {
        __labels.clear();     
        __flags = 0;    
        __fqdn  = false;
        __utf8  = false;
        return this;
      }; // -x- rhostname clear -x-
 
      /*======================================================================*//**
      @brief
      Find out whether this hostname is an FQDN (it has a final dot).
      @par Threads
      This method is thread-safe.
      @returns TRUE = hostname is an FQDN
      @returns FALSE = hostanem is not an FQDN
      *///=========================================================================
      const bool is_fqdn() noexcept {
        return __fqdn;
      }; // -x- bool is_fqdn -x-
 
      /*======================================================================*//**
      @brief
      Specify whether this hostname is an FQDN (has a final dot).
      @par Threads
      This method is thread-safe.
      @returns The same rhostname object so as to facilitate stacking
      *///=========================================================================
      rhostname* is_fqdn(
      /// TRUE = ensure this rhostname is an FQDN (has a final dot)@n
      /// FALSE = ensure this rhostname is not an FQDN (does not have a final dot)
      const bool mode) noexcept {
        __fqdn = mode;
        return this;
      }; // -x- rhostname is_fqdn -x-
 
      /*======================================================================*//**
      @brief
      Find out whether this hostname is an internationalized internet domain name
      (it has at least one label that has at least one UTF8/punycode character).
      @par Threads
      This method is thread-safe.
      @returns TRUE = hostname is an internationalized internet domain name
      @returns FALSE = hostanem is not an internationalized internet domain name
      *///=========================================================================
      const bool is_utf8() noexcept {
        return __utf8;
      }; // -x- bool is_utf8 -x-
 
      /*======================================================================*//**
      @brief
      Extract a specific label from the underlying hostname.
 
      The @c index parameter begins at 0 for the first label.  If @c index is a
      negative integer, the counting begins at -1 for the last label.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rhostname h("www.example.com", 15);
            std::cout << "Top level: " << h.label(-1) << std::endl;
            // Output will be:  Top level: com
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @throws std::out_of_range if @c index is out of range (this is the exception
              that the @c std::vector::at method throws)
      @returns The specific label extracted from the hostname that this rhostname
               represents
      @see set()
      *///=========================================================================
      std::string label(
      /// Which label to extract, with the first label beginning at index 0 (a
      /// negative index value starts from the end with -1 as the last label)
      const int index = 0,
      /// @ref rlabel::HOSTNAME_WITHOUT_EXCEPTIONS returns an empty @c std::string (@c "")
      /// instead of an exception being thrown@n
      /// @ref rlabel::HOSTNAME_DNS_RR Convert label to DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert label to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        const int MAX = __labels.size();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (flags & rlabel::HOSTNAME_WITHOUT_EXCEPTIONS) {
          if (index >=  MAX ) return "";
          if (index < -(MAX)) return "";
        } // -x- if rlabel::HOSTNAME_WITHOUT_EXCEPTIONS -x-
 
        // --------------------------------------------------------------------------
        // Copy string contents of specific label to this internal one.
        // --------------------------------------------------------------------------
        return __labels.at(index >= 0 ? index : MAX + index).get(flags);
 
      }; // -x- std::string label -x-
 
      /*======================================================================*//**
      @brief
      Find out how many labels the underlying hostname is comprised of.
      @returns Number of labels
      *///=========================================================================
      uint labels() {
        return __labels.size();
      }; // -x- uint labels -x-
 
      /*======================================================================*//**
      @brief
      Replace this rhostname's underlying hostname with a new hostname.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            char[] example = "www.example.com";
            randolf::rhostname h(example, 15);
            h.set("mail.example.net");
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @throws std::invalid_argument If the hostname is improperly formatted (flags
              can limit or eliminate conditions for throwing this exception)
      @throws std::out_of_range if any DNS RR formatted label's size would require
              reaching beyond the end of the hostname provided (this is called a
              buffer overrun, which is a potential security risk that can also
              cause a segmentation fault)
      @returns The same rhostname object so as to facilitate stacking
      @see rhostname()
      *///=========================================================================
      rhostname* set(
      /// The hostname as a std::string object
      const std::string hostname,
      /// @ref rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) {
        this->set(hostname.data(), hostname.size(), flags);
        return this;
      }; // -x- rhostname set -x-
 
      /*======================================================================*//**
      @brief
      Replace this rhostname's underlying hostname with a new hostname.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rhostname h("www.example.com", 15);
            h.set("mail.example.net");
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @throws std::invalid_argument If the hostname is improperly formatted (flags
              can limit or eliminate conditions for throwing this exception)
      @throws std::out_of_range if any DNS RR formatted label's size would require
              reaching beyond the end of the hostname provided (this is called a
              buffer overrun, which is a potential security risk that can also
              cause a segmentation fault)
      @returns The same rhostname object so as to facilitate stacking
      @see set()
      *///=========================================================================
      rhostname* set(
      /// The hostname as a char* array
      const char* hostname,
      /// Length of hostname string (0 = ASCIIZ string)
      size_t len = 0,
      /// @ref rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) {
 
        // --------------------------------------------------------------------------
        // Start over (re-initialization).
        // --------------------------------------------------------------------------
        clear();
 
        // --------------------------------------------------------------------------
        // Measure size of format string if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(hostname);
 
        // --------------------------------------------------------------------------
        // Split DNS RR into labels.
        // --------------------------------------------------------------------------
        if (flags & rlabel::HOSTNAME_DNS_RR) {
          for (int i = 0; i < len; i++) {
            size_t bytes = (u_char)hostname[i];
            if (bytes + i >= len) { // Bounds checking to prevent a buffer overrun
              throw std::out_of_range("Hostname DNS RR label size out of range");
            } // -x- if out-of-bounds -x-
            __labels.push_back(rlabel(std::string(hostname + i, bytes + 1), flags));
            i += bytes;
          } // -x- for i -x-
          return this;
        } // -x- if rlabel::HOSTNAME_DNS_RR -x-
 
        // --------------------------------------------------------------------------
        // Split hostname into labels.
        // --------------------------------------------------------------------------
        int plateau = 0;
        int i;
        for (i = 0; i < len; i++) {
          if (hostname[i] == '.') {
            __labels.push_back(rlabel(std::string(hostname + plateau, i - plateau), flags));
            plateau = i + 1; // Advance to the next position after the period (dot delimiter)
          } // -x- if . -x-
        } // -x- for i -x-
        if (plateau < i) __labels.push_back(rlabel(std::string(hostname + plateau, i - plateau), flags));
 
        return this;
      }; // -x- rhostname set -x-
 
      /*======================================================================*//**
      @brief
      Convert the underlying hostname to a DNS RR and return it as an std::string.
      @returns A new std::string with the expected data
      *///=========================================================================
      std::string to_dns_rr() {
        return to_string(rlabel::HOSTNAME_DNS_RR);
      }; // -x- std::string to_dns_rr -x-
 
      /*======================================================================*//**
      @brief
      Return as an @c std::string the hostname that this @c rhostname represents.
 
      @par Examples
 
      @code{.cpp}
        #include <iostream>  // std::cout, std::cerr, std::endl, etc.
        #include <stdexcept> // std::invalid_argument exception
 
        #include <randolf/rhostname>
 
        int main(int argc, char *argv[]) {
          try {
            randolf::rhostname h("www.example.com", 15);
            std::cout << "Hostname: " << h.to_string() << std::endl;
          } catch (const std::invalid_argument e) {
            std::cerr << "Hostname format exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          } catch (const std::exception e) {
            std::cerr << "Other exception: " << e.what() << std::endl;
            return EXIT_FAILURE;
          }
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
      @returns The hostname that this rhostname represents
      @see set()
      *///=========================================================================
      std::string to_string(
      /// @ref rlabel::HOSTNAME_FQDN_OPT includes the trailing period in the resulting
      /// std::string if @ref is_fqdn is TRUE@n
      /// @ref rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format@n
      /// @ref rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)@n
      /// @ref rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)
      const int flags = rlabel::HOSTNAME_DEFAULT) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string  hostname;
        const size_t MAX = __labels.size();
 
        // --------------------------------------------------------------------------
        // If this is empty, then end it now to avoid parsing ghosts from the heap.
        // --------------------------------------------------------------------------
        if (MAX == 0) return hostname;
 
        // --------------------------------------------------------------------------
        // If this is a DNS RR, then just build the RR and return it without an FQDN
        // check because the final period can't be expressed in a DNS RR due to its
        // different purpose.
        // --------------------------------------------------------------------------
        if (flags & rlabel::HOSTNAME_DNS_RR) {
          for (int i = 0; i < MAX; i++) hostname.append(__labels[i].get(flags));
          return hostname;
        } // -x- if rlabel::HOSTNAME_DNS_RR -x-
 
        // --------------------------------------------------------------------------
        // Optimized loop to join labels into a dot-delimited hostname, by avoiding
        // repetitive comparisons for loop position 0 to determine whether to append
        // the period ("."), we save at least a few CPU cycles overall.
        // --------------------------------------------------------------------------
        hostname.append(__labels[0].get(flags)); // Add first rlabel, no matter what
        for (int i = 1; i < MAX; i++) hostname.append(".").append(__labels[i].get(flags));
 
        // --------------------------------------------------------------------------
        // Optionally add trailing period if this is an FQDN.
        // --------------------------------------------------------------------------
        if ((flags & rlabel::HOSTNAME_FQDN_OPT) && __fqdn) hostname.append(".");
 
        return hostname;
      }; // -x- std::string to_string -x-
 
      /*======================================================================*//**
      @brief
      Convert the underlying hostname to UTF-8 and return it as an std::string.
      @returns A new std::string with the expected data
      *///=========================================================================
      std::string to_utf8() {
        return to_string(rlabel::HOSTNAME_UTF8);
      }; // -x- std::string to_utf8 -x-
 
      /*======================================================================*//**
      @brief
      Convert the underlying hostname to punycode and return it as an std::string.
      @returns A new std::string with the expected data
      *///=========================================================================
      std::string to_xn() {
        return to_string(rlabel::HOSTNAME_XN);
      }; // -x- std::string to_xn -x-
 
  }; // -x- class rhostname -x-
 
}; // -x- namespace randolf -x-