rlabel

#pragma once
 
// #include <randolf/rhostname_flags>
 
#include <idn2.h> // apt install libidn2-dev
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  Internal structure that @ref rhostname uses to store @ref rlabel portions, of
  which at least one comprises a hostname.
 
  @note
  See the `UTF-8 Everywhere` web site for simple, straight-forward, and helpful
  insights and advice on how to properly work with UTF8 data in C++ (and other
  languages) at:  https://www.utf8everywhere.org/
 
  @author Randolf Richardson
  @version 1.00
  @par History
    - 2023-Apr-27 v1.00 Initial version
    - 2025-Feb-03 v1.00 Increased use of references and pointers
 
  @see rhostname
  *///=========================================================================
  struct rlabel {
    /// Label data
    std::string data;
    /// The DNS RR flag indicates that this label is derived from a DNS RR
    /// wherein the first character indicates the length of the label in bytes)
    bool        dns_rr = false;
    /// The UTF-8 flag indicates that this label is an internationalized label
    /// because it contains at least one UTF-8 sequence
    bool        utf8   = false;
    /// The xn flag indicates that this label seems to be in punycode format,
    /// because it begins with the sequence "xn--" and is at least 5 bytes long
    bool        xn     = false;
    /// Conversion return code (@c IDN2_OK = successful conversion to UTF8 or
    /// punycode; or this is the default because no conversion was performed)
    int         idn2rc = IDN2_OK;
 
  public:
    /*======================================================================*//**
    @brief
    Optional flags that alter, modify, or enhance the operation of hostname
    handling.
    *///=========================================================================
    enum HOSTNAME_FLAGS: int {
 
      /*----------------------------------------------------------------------*//**
      The HOSTNAME_DEFAULT flag isn't necessary, but it's included here for
      completeness as it accomodates programming styles that prefer to emphasize
      when defaults are being relied upon.
      *///-------------------------------------------------------------------------
      HOSTNAME_DEFAULT = 0,
 
      /*----------------------------------------------------------------------*//**
      Alternate between an IP address and its IN-ADDR.ARPA formatted counter-part.
 
      This causes an IP address's octets (IPv4 format) or segments (IPv6 format),
      when supplied where a hostname would normally be expected, to be effectively
      reveresed.
 
      Or, deconvert for output an effectively-reversed IP-address-as-a-hostname in
      the appropriate IPv4/IPv6 format.  (All remaining labels will be removed.)
 
      @note
      This format is commonly used to query DNS-based blocklists/blacklists,
      greylists, whitelists, etc.
      *///-------------------------------------------------------------------------
      HOSTNAME_IP_ADDR = 1,
 
      /*----------------------------------------------------------------------*//**
      Convert path to hostname.  This converts a path, delimited by slashes (as is
      standard in UNIX, Linux, etc., as well as with internet URIs), to a hostname
      with the top-level portion corresponding to the top-level label as used in
      the Domain Name System, the second-level portion with the second-level label,
      etc.
 
      For example:  The path "/internet/com/example/www/" gets converted into the
                    DNS hostname "www.example.com.internet" (to remove the top/last
                    label, use the @c remove(-1) method after conversion, or use
                    the @c path_to_hostname method which provides an additional
                    parameter to specify how many elements of the path to skip from
                    both the beginning and the end).
      *///-------------------------------------------------------------------------
      HOSTNAME_FROM_PATH = 2,
 
      /*----------------------------------------------------------------------*//**
      Don't throw exceptions when parsing a hostname string when the format is
      invalid (or the data is corrupt).
 
      When an index parameter is out of range, automatically truncate it to the
      maximum bounds of any underlying vector instead of throwing an exception when
      an index is out of range.
 
      This is useful for evaluating a hostname from a data source that is intended
      to be reported on in a diagnostic fashion, or as part of a debugging effort.
      *///-------------------------------------------------------------------------
      HOSTNAME_WITHOUT_EXCEPTIONS = 4,
 
      /*----------------------------------------------------------------------*//**
      If hostname is an FQDN, then include the final period at the end (used by the
      @ref rhostname method, primarily).
 
      (The "OPT" portion of this flag name means "optional.")
      *///-------------------------------------------------------------------------
      HOSTNAME_FQDN_OPT = 8,
 
      /*----------------------------------------------------------------------*//**
      Convert label from/to DNS RR format (this is mostly only useful for authors
      of DNS client or server software, or raw DNS packet analysis code).
 
      This format is used in DNS packets, and so this flag could be useful in
      software projects like DNS resolvers, DNS daemons, and DNS packet analyzers.
      *///-------------------------------------------------------------------------
      HOSTNAME_DNS_RR = 16,
 
      /*----------------------------------------------------------------------*//**
      Convert label from/to normal UTF-8 data.
 
      @warning
      The HOSTNAME_UTF8 and HOSTNAME_XN flags represent two exclusively different
      formats, and combining them in for a hostname (or for an individual label) is
      likely to yield unpredictable results (the order in which these two flags are
      tested will vary depending on which blocks of code are doing the processing,
      and the programming logic being used; and future updates to the code may also
      affect changes to the order of flag tests and the programming logic).
 
      This format is normally presented to users to present hostnames natively in
      different languages.
      @see HOSTNAME_XN
      *///-------------------------------------------------------------------------
      HOSTNAME_UTF8 = 32,
 
      /*----------------------------------------------------------------------*//**
      Convert label from/to punycode format wherein the first four characters will
      begin with the ASCII sequence "xn--" if any UTF-8 sequences are present.
 
      @warning
      The HOSTNAME_XN and HOSTNAME_UTF8 flags represent two exclusively different
      formats, and combining them in for a hostname (or for an individual label) is
      likely to yield unpredictable results (the order in which these two flags are
      tested will vary depending on which blocks of code are doing the processing,
      and the programming logic being used; and future updates to the code may also
      affect changes to the order of flag tests and the programming logic).
 
      This format is used by client software (e.g., eMail applicaitons and web
      browsers) when attempting to resolve the IP addresses of remote hosts or
      lookup other DNS records.
      @see HOSTNAME_UTF8
      *///-------------------------------------------------------------------------
      HOSTNAME_XN = 64,
 
    }; // -x- enum HOSTNAME_FLAGS -x-
 
    /*======================================================================*//**
    @brief
    Structure constructor that detects whether any UTF-8 sequence is present in
    the data and/or if it's already in punycode format (e.g., it begins with the
    "xn--" sequence).
 
    Although the default behaviour is to not convert the data between UTF-8 and
    punycode, either the @ref HOSTNAME_UTF8 or @ref HOSTNAME_XN flag may be
    specified to cause such a conversion for underlying storage.  The benefit of
    using these flags here is mostly for performance optimization where repeated
    outbound conversions can be prevented when accessing the data multiple times.
    @throws std::invalid_argument If the label is blank or there is a problem
                                  with the format (e.g., invalid characters)
    *///=========================================================================
    rlabel(
    /// Label data
    const std::string& data,
    /// @ref HOSTNAME_DNS_RR Convert label from DNS RR format@n
    /// @ref HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional)@n
    /// @ref HOSTNAME_XN Convert label to punycode format (optional)
    const int flags = HOSTNAME_DEFAULT) {
 
      // --------------------------------------------------------------------------
      // Syntax checks.
      // --------------------------------------------------------------------------
      if (data.empty()) throw std::invalid_argument("rlabel is empty");
 
      // --------------------------------------------------------------------------
      // Convert label from DNS RR format where the first byte specifies the length
      // of the remaining data that follows (the std::min function is used to
      // prevent a buffer overrun by automatically truncating the data; this will
      // already have been vetted by rhostname::hostname, so we don't need to do
      // this again here at this time).
      // --------------------------------------------------------------------------
      this->data = (flags & HOSTNAME_DNS_RR) ? data.substr(1, std::min((size_t)((u_char)data.front()), data.size()))
                                             : data;
 
      // --------------------------------------------------------------------------
      // Peform conversions, depending on the flags.  Our switch statement's scope
      // is limited only to specific flags, which are logically OR'd together so as
      // to handle multi-purposed bitfield options in an elegant fashion since each
      // of these particular flags is exclusive.
      // --------------------------------------------------------------------------
      switch (flags & (HOSTNAME_UTF8 | HOSTNAME_XN)) {
        case HOSTNAME_UTF8: // Convert to UTF8
          if (this->data.starts_with("xn--")) { // Label is in punycode format, so it doesn't yet qualify as being in UTF-8 format
            char* p = nullptr;
            idn2rc = idn2_to_unicode_8z8z(this->data.data(), &p, 0);
            if (idn2rc == IDN2_OK) this->data = std::string((char*)p);
            if (p != nullptr) idn2_free(p);
          } // -x- if ^xn-- -x-
          break;
        case HOSTNAME_XN: // Convert to punycode
          if (!this->data.starts_with("xn--")) { // Label is not already in punycode format
            char* p = nullptr;
            idn2rc = idn2_to_ascii_8z(this->data.data(), &p, 0);
            if (idn2rc == IDN2_OK) this->data = std::string((char*)p);
            if (p != nullptr) idn2_free(p);
          } // -x- if !xn-- -x-
          break;
      } // -x- switch flags -x-
 
      // --------------------------------------------------------------------------
      // Record whether this label is already in punycode format.
      //
      // Note:  A 4-byte label of "xn--" is not valid punycode, so we intentionally
      //        check for a "greater than 4" string size (this is not erroneous).
      // --------------------------------------------------------------------------
      if (this->data.size() > 4 && this->data.starts_with("xn--")) xn = true;
 
      // --------------------------------------------------------------------------
      // Loop through string to determine UTF8 (any character is greater than 127).
      // --------------------------------------------------------------------------
      for (int i = this->data.size() - 1; i > 0; i--) {
        if ((u_char)this->data[i] >= 128) { // UTF8 byte detected
          utf8 = true;
          break;
        } // -x- if utf8 -x-
      } // -x- for i -x-
 
//std::cout << "Label:  " << this->data << std::endl; // Debug
//std::cout << "   XN:  " << xn   << std::endl; // Debug
//std::cout << " UTF8:  " << utf8 << std::endl; // Debug
 
    } // -x- constructor rlabel -x-
 
//    ~rlabel() {
//      std::cout << "Destructor:  rlabel = " << data << std::endl; // Debug
//    }
 
    /*======================================================================*//**
    @brief
    Provice label as an std::string with any needed conversions.
    @returns Label as an std::string object
    *///=========================================================================
    std::string get(
    /// @ref HOSTNAME_DNS_RR Convert label to DNS RR format@n
    /// @ref HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional)@n
    /// @ref HOSTNAME_XN Convert label to punycode format (optional)
    const int flags = HOSTNAME_DEFAULT) {
 
      // --------------------------------------------------------------------------
      // Internal variables.
      // --------------------------------------------------------------------------
      std::string _label;
 
      // --------------------------------------------------------------------------
      // Peform conversions, depending on the flags.  Our switch statement's scope
      // is limited only to specific flags, which are logically OR'd together so as
      // to handle multi-purposed bitfield options in an elegant fashion since each
      // of these particular flags is exclusive.
      // --------------------------------------------------------------------------
      switch (flags & (HOSTNAME_UTF8 | HOSTNAME_XN)) {
        case HOSTNAME_UTF8: // Convert to UTF8
          if (data.starts_with("xn--")) { // Label is in punycode format, so it doesn't yet qualify as being in UTF-8 format
            char* p = nullptr;
            idn2rc = idn2_to_unicode_8z8z(data.data(), &p, 0);
            if (idn2rc == IDN2_OK) _label.assign((char*)p);
            if (p != nullptr) idn2_free(p);
          } else {
            _label.assign(data);
          } // -x- if ^xn-- -x-
          break;
        case HOSTNAME_XN: // Convert to punycode
          if (!data.starts_with("xn--")) { // Label is not already in punycode format
            char* p = nullptr;
            idn2rc = idn2_to_ascii_8z(data.data(), &p, 0);
            if (idn2rc == IDN2_OK) _label.assign((char*)p);
            if (p != nullptr) idn2_free(p);
          } else {
            _label.assign(data);
          } // -x- if !xn-- -x-
          break;
        default: // No conversions necessary, so just assign the label as is
          _label.assign(data);
      } // -x- switch flags -x-
 
      // --------------------------------------------------------------------------
      // Insert label's length (maximum 255 characters) if it is to be converted to
      // DNS RR format.
      // --------------------------------------------------------------------------
      if (flags & HOSTNAME_DNS_RR)
        _label.insert(0,                                               // Position: before first character
                      1,                                               // Insert only one character
                      (u_char)(std::min(_label.size(), (size_t)255))); // Convert size to u_char, limit to 255
 
      // --------------------------------------------------------------------------
      // Return the label.
      // --------------------------------------------------------------------------
      return _label;
 
    } // -x- std::string get -x-
 
    /*======================================================================*//**
    @brief
    Built-in comparison operator used by @c std::set for ordering rlabel
    objects by the underlying label data.
    @returns Underlying rsocket_label
    *///=========================================================================
    bool operator<(
    /// This rlabel structure
    const rlabel& rhl) const {
      return data < rhl.data;
    } // -x- bool < -x-
 
  }; // -x- struct rlabel -x-
 
}; // -x- namespace randolf -x-