couchbase 3.0.0.alpha.2 → 3.0.0

data/ext/couchbase/io/dns_codec.hxx

@@ -0,0 +1,207 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2020 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <cstring>
+
+#include <arpa/inet.h>
+
+#include <io/dns_message.hxx>
+
+namespace couchbase::io::dns
+{
+class dns_codec
+{
+  public:
+    static dns_message decode(const std::vector<uint8_t>& payload)
+    {
+        dns_message message{};
+        std::size_t offset = 0;
+
+        std::memcpy(&message.header.id, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.id = ntohs(message.header.id);
+
+        uint16_t flags = 0;
+        std::memcpy(&flags, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.flags.decode(ntohs(flags));
+
+        std::memcpy(&message.header.question_records, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.question_records = ntohs(message.header.question_records);
+
+        std::memcpy(&message.header.answer_records, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.answer_records = ntohs(message.header.answer_records);
+
+        std::memcpy(&message.header.authority_records, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.authority_records = ntohs(message.header.authority_records);
+
+        std::memcpy(&message.header.additional_records, payload.data() + offset, sizeof(std::uint16_t));
+        offset += sizeof(std::uint16_t);
+        message.header.additional_records = ntohs(message.header.additional_records);
+
+        for (std::uint16_t idx = 0; idx < message.header.question_records; ++idx) {
+            question_record qr;
+            qr.name = get_name(payload, offset);
+
+            std::uint16_t val = 0;
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            val = ntohs(val);
+            qr.type = static_cast<resource_type>(val);
+
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            val = ntohs(val);
+            qr.klass = static_cast<resource_class>(val);
+
+            message.questions.emplace_back(qr);
+        }
+
+        message.answers.reserve(message.header.answer_records);
+        for (std::uint16_t idx = 0; idx < message.header.answer_records; ++idx) {
+            srv_record ar;
+            ar.name = get_name(payload, offset);
+
+            std::uint16_t val = 0;
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            val = ntohs(val);
+            ar.type = static_cast<resource_type>(val);
+
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            val = ntohs(val);
+            ar.klass = static_cast<resource_class>(val);
+
+            std::memcpy(&ar.ttl, payload.data() + offset, sizeof(std::uint32_t));
+            offset += static_cast<std::uint16_t>(4U);
+            ar.ttl = ntohl(ar.ttl);
+
+            std::uint16_t size = 0;
+            std::memcpy(&size, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            size = ntohs(size);
+
+            if (ar.klass != resource_class::in || ar.type != resource_type::srv) {
+                // ignore everything except SRV answers
+                offset += size;
+                continue;
+            }
+
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            ar.priority = ntohs(val);
+
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            ar.weight = ntohs(val);
+
+            std::memcpy(&val, payload.data() + offset, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+            ar.port = ntohs(val);
+
+            ar.target = get_name(payload, offset);
+
+            message.answers.emplace_back(ar);
+        }
+        return message;
+    }
+
+    static std::vector<uint8_t> encode(const dns_message& message)
+    {
+        std::vector<std::uint8_t> payload;
+        payload.resize(message.request_size(), 0);
+        std::size_t offset = 0;
+
+        // write header
+        {
+            uint16_t val;
+
+            val = htons(message.header.id);
+            std::memcpy(payload.data() + offset, &val, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+
+            val = htons(message.header.flags.encode());
+            std::memcpy(payload.data() + offset, &val, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+
+            val = htons(static_cast<std::uint16_t>(message.questions.size()));
+            std::memcpy(payload.data() + offset, &val, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t) + 3 * sizeof(std::uint16_t); // answer, authority, additional are all zeros
+        }
+
+        // write body
+        for (const auto& question : message.questions) {
+            for (const auto& label : question.name.labels) {
+                payload[offset] = static_cast<std::uint8_t>(label.size());
+                ++offset;
+                std::memcpy(payload.data() + offset, label.data(), label.size());
+                offset += label.size();
+            }
+            payload[offset] = '\0';
+            ++offset;
+
+            uint16_t val;
+
+            val = htons(static_cast<std::uint16_t>(question.type));
+            std::memcpy(payload.data() + offset, &val, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+
+            val = htons(static_cast<std::uint16_t>(question.klass));
+            std::memcpy(payload.data() + offset, &val, sizeof(std::uint16_t));
+            offset += sizeof(std::uint16_t);
+        }
+        return payload;
+    }
+
+  private:
+    static resource_name get_name(const std::vector<std::uint8_t>& payload, std::size_t& offset)
+    {
+        resource_name name{};
+        std::optional<std::size_t> save_offset{};
+        while (true) {
+            std::uint8_t len = payload[offset];
+            if (len == 0) {
+                offset += 1;
+                if (save_offset) {
+                    // restore offset after pointer jump
+                    offset = *save_offset;
+                }
+                return name;
+            }
+            if ((len & 0b1100'0000U) != 0) {
+                std::uint16_t ptr = 0;
+                std::memcpy(&ptr, payload.data() + offset, sizeof(std::uint16_t));
+                ptr = ntohs(ptr);
+                ptr &= 0b0011'1111'1111'1111U;
+                // store old offset and jump to pointer
+                save_offset = offset + sizeof(std::uint16_t);
+                offset = ptr;
+            } else {
+                std::string label(payload.data() + offset + 1, payload.data() + offset + 1 + len);
+                name.labels.emplace_back(label);
+                offset += static_cast<std::uint16_t>(1U + len);
+            }
+        }
+    }
+};
+} // namespace couchbase::io::dns

data/ext/couchbase/io/dns_config.hxx

@@ -0,0 +1,116 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2020 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <unistd.h>
+
+#include <string>
+#include <fstream>
+
+#include <asio/ip/address.hpp>
+
+#include <timeout_defaults.hxx>
+
+namespace couchbase::io::dns
+{
+class dns_config
+{
+  public:
+    static inline constexpr auto default_resolv_conf_path = "/etc/resolv.conf";
+    static inline constexpr auto default_host = "8.8.8.8";
+    static inline constexpr std::uint16_t default_port = 53;
+
+    [[nodiscard]] const asio::ip::address& address() const
+    {
+        return address_;
+    }
+
+    [[nodiscard]] std::uint16_t port() const
+    {
+        return port_;
+    }
+
+    [[nodiscard]] std::chrono::milliseconds timeout() const
+    {
+        return timeout_;
+    }
+
+    static dns_config& get()
+    {
+        static dns_config instance{};
+
+        instance.initialize();
+
+        return instance;
+    }
+
+  private:
+    void initialize()
+    {
+        if (!initialized_) {
+            load_resolv_conf(default_resolv_conf_path);
+            std::error_code ec;
+            address_ = asio::ip::address::from_string(host_, ec);
+            if (ec) {
+                host_ = default_host;
+                address_ = asio::ip::address::from_string(host_, ec);
+            }
+            initialized_ = true;
+        }
+    }
+
+    void load_resolv_conf(const char* conf_path)
+    {
+        if (access(conf_path, R_OK) == 0) {
+            std::ifstream conf(conf_path);
+            while (conf.good()) {
+                std::string line;
+                std::getline(conf, line);
+                if (line.empty()) {
+                    continue;
+                }
+                std::size_t offset = 0;
+                while (line[offset] == ' ') {
+                    ++offset;
+                }
+                if (line[offset] == '#') {
+                    continue;
+                }
+                std::size_t space = line.find(' ', offset);
+                if (space == std::string::npos || space == offset || line.size() < space + 2) {
+                    continue;
+                }
+                std::string keyword = line.substr(offset, space);
+                if (keyword != "nameserver") {
+                    continue;
+                }
+                offset = space + 1;
+                space = line.find(' ', offset);
+                host_ = line.substr(offset, space);
+                break;
+            }
+        }
+    }
+
+    std::atomic_bool initialized_{ false };
+    std::string host_{ default_host };
+    asio::ip::address address_{};
+    std::uint16_t port_{ default_port };
+    std::chrono::milliseconds timeout_{ timeout_defaults::dns_srv_timeout };
+};
+} // namespace couchbase::io::dns

data/ext/couchbase/io/dns_message.hxx

@@ -0,0 +1,555 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2020 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <vector>
+#include <string>
+
+namespace couchbase::io::dns
+{
+/**
+ * 3.2.2. TYPE values
+ * ==================
+ *
+ * TYPE fields are used in resource records.  Note that these types are a subset of QTYPEs.
+ */
+enum class resource_type : std::uint16_t {
+    /**
+     * a host address
+     */
+    a = 1,
+
+    /**
+     * an authoritative name server
+     */
+    ns = 2,
+
+    /**
+     * a mail destination (Obsolete - use MX)
+     */
+    md = 3,
+
+    /**
+     * a mail forwarder (Obsolete - use MX)
+     */
+    mf = 4,
+
+    /**
+     * the canonical name for an alias
+     */
+    cname = 5,
+
+    /**
+     * marks the start of a zone of authority
+     */
+    soa = 6,
+
+    /**
+     * a mailbox domain name (EXPERIMENTAL)
+     */
+    mb = 7,
+
+    /**
+     * a mail group member (EXPERIMENTAL)
+     */
+    mg = 8,
+
+    /**
+     * a mail rename domain name (EXPERIMENTAL)
+     */
+    mr = 9,
+
+    /**
+     * a null RR (EXPERIMENTAL)
+     */
+    null = 10,
+
+    /**
+     * a well known service description
+     */
+    wks = 11,
+
+    /**
+     * a domain name pointer
+     */
+    ptr = 12,
+
+    /**
+     * host information
+     */
+    hinfo = 13,
+
+    /**
+     * mailbox or mail list information
+     */
+    minfo = 14,
+
+    /**
+     * mail exchange
+     */
+    mx = 15,
+
+    /**
+     * text strings
+     */
+    txt = 16,
+
+    /**
+     * location services (RFC2782)
+     */
+    srv = 33,
+};
+
+/**
+ * 3.2.4. CLASS values
+ * ===================
+ *
+ * CLASS fields appear in resource records. The following CLASS mnemonics and values are defined:
+ *
+ *
+ * 3.2.5. QCLASS values
+ * ====================
+ *
+ * QCLASS fields appear in the question section of a query.  QCLASS values are a superset of CLASS values; every CLASS is a valid QCLASS. In
+ * addition to CLASS values, the following QCLASSes are defined:
+ */
+enum class resource_class : std::uint16_t {
+    /**
+     * the Internet
+     */
+    in = 1,
+
+    /**
+     * the CSNET class (Obsolete - used only for examples in some obsolete RFCs)
+     */
+    cs = 2,
+
+    /**
+     * the CHAOS class
+     */
+    ch = 3,
+
+    /**
+     * Hesiod [Dyer 87]
+     */
+    hs = 4,
+
+    /**
+     * any class
+     */
+    any = 255,
+};
+
+/**
+ * [OPCODE]
+ *
+ * A four bit field that specifies kind of query in this message. This value is set by the originator of a query and copied into the
+ * response. The values are:
+ *
+ *   3-15  reserved for future use
+ */
+enum class opcode : std::uint8_t {
+    /**
+     * a standard query (QUERY)
+     */
+    standard_query = 0,
+
+    /**
+     * an inverse query (IQUERY)
+     */
+    inverse_query = 1,
+
+    /**
+     * a server status request (STATUS)
+     */
+    status = 2,
+};
+
+/**
+ * [QR]
+ *
+ * A one bit field that specifies whether this message is a query (0), or a response (1).
+ */
+enum class message_type : std::uint8_t {
+    query = 0,
+    response = 1,
+};
+
+/**
+ * [AA]
+ *
+ * Authoritative Answer - this bit is valid in responses, and specifies that the responding name server is an authority for the domain name
+ * in question section.
+ *
+ * Note that the contents of the answer section may have multiple owner names because of aliases. The AA bit corresponds to the name which
+ * matches the query name, or the first owner name in the answer section.
+ */
+enum class authoritative_answer : std::uint8_t {
+    no = 0,
+    yes = 1,
+};
+
+/**
+ * [TC]
+ *
+ * TrunCation - specifies that this message was truncated due to length greater than that permitted on the transmission channel.
+ */
+enum class truncation : std::uint8_t {
+    no = 0,
+    yes = 1,
+};
+
+/**
+ * [RD]
+ *
+ * Recursion Desired - this bit may be set in a query and is copied into the response. If RD is set, it directs the name server to pursue
+ * the query recursively. Recursive query support is optional.
+ */
+enum class recursion_desired : std::uint8_t {
+    no = 0,
+    yes = 1,
+};
+
+/**
+ * [RA]
+ *
+ * Recursion Available - this be is set or cleared in a response, and denotes whether recursive query support is available in the name
+ * server.
+ */
+enum class recursion_available : std::uint8_t {
+    no = 0,
+    yes = 1,
+};
+
+/**
+ * [RCODE]
+ *
+ * Response code - this 4 bit field is set as part of responses. The values have the following interpretation:
+ *
+ * 6-15  Reserved for future use.
+ */
+enum class response_code : std::uint8_t {
+    /**
+     * No error condition
+     */
+    no_error = 0,
+
+    /**
+     * The name server was unable to interpret the query.
+     */
+    format_error = 1,
+
+    /**
+     * The name server was unable to process this query due to a problem with the name server.
+     */
+    server_failure = 2,
+
+    /**
+     * Meaningful only for responses from an authoritative name server, this code signifies that the domain name referenced in the query
+     * does not exist.
+     */
+    name_error = 3,
+
+    /**
+     * The name server does not support the requested kind of query.
+     */
+    not_implemented = 4,
+
+    /**
+     * The name server refuses to perform the specified operation for policy reasons.  For example, a name server may not wish to provide
+     * the information to the particular requester, or a name server may not wish to perform a particular operation (e.g., zone transfer)
+     * for particular data.
+     */
+    refused = 5,
+};
+
+/**
+ * 4.1.1. Header section format
+ * ============================
+ *
+ * The header contains the following fields:
+ *
+ *                                    1  1  1  1  1  1
+ *      0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |                      ID                       |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |QR|   OPCODE  |AA|TC|RD|RA| <zero> |   RCODE   |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |                    QDCOUNT                    |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |                    ANCOUNT                    |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |                    NSCOUNT                    |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *    |                    ARCOUNT                    |
+ *    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ */
+struct dns_header {
+    struct dns_flags {
+        message_type qr{ message_type::query };
+        dns::opcode opcode{ dns::opcode::standard_query };
+        authoritative_answer aa{ authoritative_answer::no };
+        truncation tc{ truncation::no };
+        recursion_desired rd{ recursion_desired::yes };
+        recursion_available ra{ recursion_available::no };
+        response_code rcode{ response_code::no_error };
+
+        [[nodiscard]] std::uint16_t encode() const
+        {
+            return std::uint16_t((static_cast<std::uint32_t>(qr) & 1U) << 15U | (static_cast<std::uint32_t>(opcode) & 15U) << 11U |
+                                 (static_cast<std::uint32_t>(aa) & 1U) << 10U | (static_cast<std::uint32_t>(tc) & 1U) << 9U |
+                                 (static_cast<std::uint32_t>(rd) & 1U) << 8U | (static_cast<std::uint32_t>(ra) & 1U) << 7U |
+                                 (static_cast<std::uint32_t>(rcode) & 15U));
+        }
+
+        void decode(std::uint16_t blob)
+        {
+            qr = static_cast<message_type>((static_cast<std::uint32_t>(blob) >> 15U) & 1U);
+            opcode = static_cast<dns::opcode>((static_cast<std::uint32_t>(blob) >> 11U) & 15U);
+
+            aa = ((static_cast<std::uint32_t>(blob) >> 10U) & 1U) != 0U ? authoritative_answer::yes : authoritative_answer::no;
+            tc = ((static_cast<std::uint32_t>(blob) >> 9U) & 1U) != 0U ? truncation::yes : truncation::no;
+            rd = ((static_cast<std::uint32_t>(blob) >> 8U) & 1U) != 0U ? recursion_desired::yes : recursion_desired::no;
+            ra = ((static_cast<std::uint32_t>(blob) >> 7U) & 1U) != 0U ? recursion_available::yes : recursion_available::no;
+
+            rcode = static_cast<response_code>(blob & 15U);
+        }
+    };
+
+    /**
+     * [ID]
+     *
+     * A 16 bit identifier assigned by the program that generates any kind of query. This identifier is copied the corresponding reply and
+     * can be used by the requester to match up replies to outstanding queries.
+     */
+    std::uint16_t id;
+
+    dns_flags flags;
+
+    /**
+     * [QDCOUNT]
+     *
+     * an unsigned 16 bit integer specifying the number of entries in the question section.
+     */
+    std::uint16_t question_records;
+
+    /**
+     * [ANCOUNT]
+     *
+     * an unsigned 16 bit integer specifying the number of resource records in the answer section.
+     */
+    std::uint16_t answer_records;
+
+    /**
+     * [NSCOUNT]
+     *
+     * an unsigned 16 bit integer specifying the number of name server resource records in the authority records section.
+     */
+    std::uint16_t authority_records;
+
+    /**
+     * [ARCOUNT]
+     *
+     * an unsigned 16 bit integer specifying the number of resource records in the additional records section.
+     */
+    std::uint16_t additional_records;
+};
+
+struct resource_name {
+    std::vector<std::string> labels{};
+};
+
+/**
+ * 4.1.2. Question section format
+ * ==============================
+ *
+ * The question section is used to carry the "question" in most queries, i.e., the parameters that define what is being asked.  The section
+ * contains QDCOUNT (usually 1) entries, each of the following format:
+ *
+ *                                     1  1  1  1  1  1
+ *       0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                                               |
+ *     /                     QNAME                     /
+ *     /                                               /
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                     QTYPE                     |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                     QCLASS                    |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ */
+struct question_record {
+    /**
+     * [QNAME]
+     *
+     * a domain name represented as a sequence of labels, where each label consists of a length octet followed by that number of octets. The
+     * domain name terminates with the zero length octet for the null label of the root.  Note that this field may be an odd number of
+     * octets; no padding is used.
+     */
+    resource_name name{};
+
+    /**
+     * [QTYPE]
+     *
+     * a two octet code which specifies the type of the query. The values for this field include all codes valid for a TYPE field, together
+     * with some more general codes which can match more than one type of RR.
+     */
+    resource_type type{};
+
+    /**
+     * [QCLASS]
+     *
+     * a two octet code that specifies the class of the query. For example, the QCLASS field is IN for the Internet.
+     */
+    resource_class klass{};
+
+    [[nodiscard]] std::size_t size() const
+    {
+        std::size_t res = 2 * sizeof(std::uint16_t); // type + class
+        for (const auto& label : name.labels) {
+            res += sizeof(std::uint8_t) + label.size();
+        }
+        ++res; // '\0'
+        return res;
+    }
+};
+
+/**
+ * 4.1.3. Resource record format
+ * =============================
+ *
+ * The answer, authority, and additional sections all share the same format: a variable number of resource records, where
+ * the number of records is specified in the corresponding count field in the header. Each resource record has the
+ * following format:
+ *
+ *                                     1  1  1  1  1  1
+ *       0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                                               |
+ *     /                                               /
+ *     /                      NAME                     /
+ *     |                                               |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                      TYPE                     |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                     CLASS                     |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                      TTL                      |
+ *     |                                               |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *     |                   RDLENGTH                    |
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
+ *     /                     RDATA                     /
+ *     /                                               /
+ *     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+ *
+ * [RDLENGTH]
+ *
+ * an unsigned 16 bit integer that specifies the length in octets of the RDATA field.
+ *
+ * [RDATA]
+ *
+ * a variable length string of octets that describes the resource. The format of this information varies according to the TYPE and CLASS
+ * of the resource record. For example, the if the TYPE is A and the CLASS is IN, the RDATA field is a 4 octet ARPA Internet address.
+ */
+struct resource_record {
+    /**
+     * [NAME]
+     *
+     * a domain name to which this resource record pertains.
+     */
+    resource_name name{};
+
+    /**
+     * [TYPE]
+     *
+     * two octets containing one of the RR type codes. This field specifies the meaning of the data in the RDATA field.
+     */
+    resource_type type{};
+
+    /**
+     * [CLASS]
+     *
+     * two octets which specify the class of the data in the RDATA field.
+     */
+    resource_class klass{};
+
+    /**
+     *
+     * [TTL]
+     *
+     * a 32 bit unsigned integer that specifies the time interval (in seconds) that the resource record may be cached before it should be
+     * discarded. Zero values are interpreted to mean that the RR can only be used for the transaction in progress, and should not be
+     * cached.
+     */
+    std::uint32_t ttl{};
+};
+
+struct srv_record : resource_record {
+    std::uint16_t priority{};
+    std::uint16_t weight{};
+    std::uint16_t port{};
+    resource_name target{};
+};
+
+/**
+ * 4.1. Format
+ * ===========
+ *
+ * All communications inside of the domain protocol are carried in a single format called a message. The top level format of message is
+ * divided into 5 sections (some of which are empty in certain cases) shown below:
+ *
+ *      +---------------------+
+ *      |        Header       |
+ *      +---------------------+
+ *      |       Question      | the question for the name server
+ *      +---------------------+
+ *      |        Answer       | RRs answering the question
+ *      +---------------------+
+ *      |      Authority      | RRs pointing toward an authority
+ *      +---------------------+
+ *      |      Additional     | RRs holding additional information
+ *      +---------------------+
+ *
+ * The header section is always present.  The header includes fields that specify which of the remaining sections are present, and also
+ * specify whether the message is a query or a response, a standard query or some other opcode, etc.
+ *
+ * The names of the sections after the header are derived from their use in standard queries.  The question section contains fields that
+ * describe a question to a name server.  These fields are a query type (QTYPE), a query class (QCLASS), and a query domain name (QNAME).
+ * The last three sections have the same format: a possibly empty list of concatenated resource records (RRs).  The answer section contains
+ * RRs that answer the question; the authority section contains RRs that point toward an authoritative name server; the additional records
+ * section contains RRs which relate to the query, but are not strictly answers for the question.
+ */
+struct dns_message {
+    dns_header header{};
+    std::vector<question_record> questions{};
+    std::vector<srv_record> answers{};
+    // the implementation only cares about SRV answers, so ignore everything else
+
+    [[nodiscard]] std::size_t request_size() const
+    {
+        std::size_t res = 6 * sizeof(std::uint16_t); // header
+        for (const auto& question : questions) {
+            res += question.size();
+        }
+        return res;
+    }
+};
+} // namespace couchbase::io::dns