Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_RESOLVER_HPP

#ifndef BOOST_COROSIO_RESOLVER_HPP

#define BOOST_COROSIO_RESOLVER_HPP

#define BOOST_COROSIO_RESOLVER_HPP

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/io_object.hpp>

#include <boost/corosio/io_object.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/corosio/resolver_results.hpp>

#include <boost/corosio/resolver_results.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/concept/executor.hpp>

#include <system_error>

#include <system_error>

#include <cassert>

#include <cassert>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <cstdint>

#include <cstdint>

#include <stop_token>

#include <stop_token>

#include <string>

#include <string>

#include <string_view>

#include <string_view>

#include <type_traits>

#include <type_traits>

namespace boost::corosio {

namespace boost::corosio {

/** Bitmask flags for resolver queries.

/** Bitmask flags for resolver queries.

    These flags correspond to the hints parameter of getaddrinfo.

    These flags correspond to the hints parameter of getaddrinfo.

*/

*/

enum class resolve_flags : unsigned int

enum class resolve_flags : unsigned int

{

{

    /// No flags.

    /// No flags.

    none = 0,

    none = 0,

    /// Indicate that returned endpoint is intended for use as a locally

    /// Indicate that returned endpoint is intended for use as a locally

    /// bound socket endpoint.

    /// bound socket endpoint.

    passive = 0x01,

    passive = 0x01,

    /// Host name should be treated as a numeric string defining an IPv4

    /// Host name should be treated as a numeric string defining an IPv4

    /// or IPv6 address and no name resolution should be attempted.

    /// or IPv6 address and no name resolution should be attempted.

    numeric_host = 0x04,

    numeric_host = 0x04,

    /// Service name should be treated as a numeric string defining a port

    /// Service name should be treated as a numeric string defining a port

    /// number and no name resolution should be attempted.

    /// number and no name resolution should be attempted.

    numeric_service = 0x08,

    numeric_service = 0x08,

    /// Only return IPv4 addresses if a non-loopback IPv4 address is

    /// Only return IPv4 addresses if a non-loopback IPv4 address is

    /// configured for the system. Only return IPv6 addresses if a

    /// configured for the system. Only return IPv6 addresses if a

    /// non-loopback IPv6 address is configured for the system.

    /// non-loopback IPv6 address is configured for the system.

    address_configured = 0x20,

    address_configured = 0x20,

    /// If the query protocol family is specified as IPv6, return

    /// If the query protocol family is specified as IPv6, return

    /// IPv4-mapped IPv6 addresses on finding no IPv6 addresses.

    /// IPv4-mapped IPv6 addresses on finding no IPv6 addresses.

    v4_mapped = 0x800,

    v4_mapped = 0x800,

    /// If used with v4_mapped, return all matching IPv6 and IPv4 addresses.

    /// If used with v4_mapped, return all matching IPv6 and IPv4 addresses.

    all_matching = 0x100

    all_matching = 0x100

};

};

/** Combine two resolve_flags. */

/** Combine two resolve_flags. */

inline

inline

resolve_flags

resolve_flags

{

{

    return static_cast<resolve_flags>(

    return static_cast<resolve_flags>(

        static_cast<unsigned int>(a) |

        static_cast<unsigned int>(a) |

}

}

/** Combine two resolve_flags. */

/** Combine two resolve_flags. */

inline

inline

resolve_flags&

resolve_flags&

{

{

}

}

/** Intersect two resolve_flags. */

/** Intersect two resolve_flags. */

inline

inline

resolve_flags

resolve_flags

{

{

    return static_cast<resolve_flags>(

    return static_cast<resolve_flags>(

        static_cast<unsigned int>(a) &

        static_cast<unsigned int>(a) &

}

}

/** Intersect two resolve_flags. */

/** Intersect two resolve_flags. */

inline

inline

resolve_flags&

resolve_flags&

{

{

}

}

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------

/** Bitmask flags for reverse resolver queries.

/** Bitmask flags for reverse resolver queries.

    These flags correspond to the flags parameter of getnameinfo.

    These flags correspond to the flags parameter of getnameinfo.

*/

*/

enum class reverse_flags : unsigned int

enum class reverse_flags : unsigned int

{

{

    /// No flags.

    /// No flags.

    none = 0,

    none = 0,

    /// Return the numeric form of the hostname instead of its name.

    /// Return the numeric form of the hostname instead of its name.

    numeric_host = 0x01,

    numeric_host = 0x01,

    /// Return the numeric form of the service name instead of its name.

    /// Return the numeric form of the service name instead of its name.

    numeric_service = 0x02,

    numeric_service = 0x02,

    /// Return an error if the hostname cannot be resolved.

    /// Return an error if the hostname cannot be resolved.

    name_required = 0x04,

    name_required = 0x04,

    /// Lookup for datagram (UDP) service instead of stream (TCP).

    /// Lookup for datagram (UDP) service instead of stream (TCP).

    datagram_service = 0x08

    datagram_service = 0x08

};

};

/** Combine two reverse_flags. */

/** Combine two reverse_flags. */

inline

inline

reverse_flags

reverse_flags

{

{

    return static_cast<reverse_flags>(

    return static_cast<reverse_flags>(

        static_cast<unsigned int>(a) |

        static_cast<unsigned int>(a) |

}

}

/** Combine two reverse_flags. */

/** Combine two reverse_flags. */

inline

inline

reverse_flags&

reverse_flags&

{

{

}

}

/** Intersect two reverse_flags. */

/** Intersect two reverse_flags. */

inline

inline

reverse_flags

reverse_flags

{

{

    return static_cast<reverse_flags>(

    return static_cast<reverse_flags>(

        static_cast<unsigned int>(a) &

        static_cast<unsigned int>(a) &

}

}

/** Intersect two reverse_flags. */

/** Intersect two reverse_flags. */

inline

inline

reverse_flags&

reverse_flags&

{

{

}

}

//------------------------------------------------------------------------------

//------------------------------------------------------------------------------

/** An asynchronous DNS resolver for coroutine I/O.

/** An asynchronous DNS resolver for coroutine I/O.

    This class provides asynchronous DNS resolution operations that return

    This class provides asynchronous DNS resolution operations that return

    awaitable types. Each operation participates in the affine awaitable

    awaitable types. Each operation participates in the affine awaitable

    protocol, ensuring coroutines resume on the correct executor.

    protocol, ensuring coroutines resume on the correct executor.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Unsafe. A resolver must not have concurrent resolve

    Shared objects: Unsafe. A resolver must not have concurrent resolve

    operations.

    operations.

    @par Semantics

    @par Semantics

    Wraps platform DNS resolution (getaddrinfo/getnameinfo).

    Wraps platform DNS resolution (getaddrinfo/getnameinfo).

    Operations dispatch to OS resolver APIs via the io_context

    Operations dispatch to OS resolver APIs via the io_context

    thread pool.

    thread pool.

    @par Example

    @par Example

    @code

    @code

    io_context ioc;

    io_context ioc;

    resolver r(ioc);

    resolver r(ioc);

    // Using structured bindings

    // Using structured bindings

    auto [ec, results] = co_await r.resolve("www.example.com", "https");

    auto [ec, results] = co_await r.resolve("www.example.com", "https");

    if (ec)

    if (ec)

        co_return;

        co_return;

    for (auto const& entry : results)

    for (auto const& entry : results)

        std::cout << entry.get_endpoint().port() << std::endl;

        std::cout << entry.get_endpoint().port() << std::endl;

    // Or using exceptions

    // Or using exceptions

    auto results = (co_await r.resolve("www.example.com", "https")).value();

    auto results = (co_await r.resolve("www.example.com", "https")).value();

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL resolver : public io_object

class BOOST_COROSIO_DECL resolver : public io_object

{

{

    struct resolve_awaitable

    struct resolve_awaitable

    {

    {

        resolver& r_;

        resolver& r_;

        std::string host_;

        std::string host_;

        std::string service_;

        std::string service_;

        resolve_flags flags_;

        resolve_flags flags_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable resolver_results results_;

        mutable resolver_results results_;

            resolver& r,

            resolver& r,

            std::string_view host,

            std::string_view host,

            std::string_view service,

            std::string_view service,

            resolve_flags flags) noexcept

            resolve_flags flags) noexcept

        {

        {

        {

        {

        }

        }

        {

        {

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            capy::io_env const* env) -> std::coroutine_handle<>

            capy::io_env const* env) -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

    struct reverse_resolve_awaitable

    struct reverse_resolve_awaitable

    {

    {

        resolver& r_;

        resolver& r_;

        endpoint ep_;

        endpoint ep_;

        reverse_flags flags_;

        reverse_flags flags_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable reverse_resolver_result result_;

        mutable reverse_resolver_result result_;

            resolver& r,

            resolver& r,

            endpoint const& ep,

            endpoint const& ep,

            reverse_flags flags) noexcept

            reverse_flags flags) noexcept

        {

        {

        {

        {

        }

        }

        {

        {

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            capy::io_env const* env) -> std::coroutine_handle<>

            capy::io_env const* env) -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    /** Destructor.

    /** Destructor.

        Cancels any pending operations.

        Cancels any pending operations.

    */

    */

    ~resolver();

    ~resolver();

    /** Construct a resolver from an execution context.

    /** Construct a resolver from an execution context.

        @param ctx The execution context that will own this resolver.

        @param ctx The execution context that will own this resolver.

    */

    */

    explicit resolver(capy::execution_context& ctx);

    explicit resolver(capy::execution_context& ctx);

    /** Construct a resolver from an executor.

    /** Construct a resolver from an executor.

        The resolver is associated with the executor's context.

        The resolver is associated with the executor's context.

        @param ex The executor whose context will own the resolver.

        @param ex The executor whose context will own the resolver.

    */

    */

    template<class Ex>

    template<class Ex>

        requires (!std::same_as<std::remove_cvref_t<Ex>, resolver>) &&

        requires (!std::same_as<std::remove_cvref_t<Ex>, resolver>) &&

                 capy::Executor<Ex>

                 capy::Executor<Ex>

    {

    {

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the resolver resources.

        Transfers ownership of the resolver resources.

        @param other The resolver to move from.

        @param other The resolver to move from.

    */

    */

    {

    {

    /** Move assignment operator.

    /** Move assignment operator.

        Cancels any existing operations and transfers ownership.

        Cancels any existing operations and transfers ownership.

        The source and destination must share the same execution context.

        The source and destination must share the same execution context.

        @param other The resolver to move from.

        @param other The resolver to move from.

        @return Reference to this resolver.

        @return Reference to this resolver.

        @throws std::logic_error if the resolvers have different

        @throws std::logic_error if the resolvers have different

            execution contexts.

            execution contexts.

    */

    */

    {

    {

        {

        {

                    "cannot move resolver across execution contexts");

                    "cannot move resolver across execution contexts");

        }

        }

    }

    }

    resolver(resolver const&) = delete;

    resolver(resolver const&) = delete;

    resolver& operator=(resolver const&) = delete;

    resolver& operator=(resolver const&) = delete;

    /** Initiate an asynchronous resolve operation.

    /** Initiate an asynchronous resolve operation.

        Resolves the host and service names into a list of endpoints.

        Resolves the host and service names into a list of endpoints.

        @param host A string identifying a location. May be a descriptive

        @param host A string identifying a location. May be a descriptive

            name or a numeric address string.

            name or a numeric address string.

        @param service A string identifying the requested service. This may

        @param service A string identifying the requested service. This may

            be a descriptive name or a numeric string corresponding to a

            be a descriptive name or a numeric string corresponding to a

            port number.

            port number.

        @return An awaitable that completes with `io_result<resolver_results>`.

        @return An awaitable that completes with `io_result<resolver_results>`.

        @par Example

        @par Example

        @code

        @code

        auto [ec, results] = co_await r.resolve("www.example.com", "https");

        auto [ec, results] = co_await r.resolve("www.example.com", "https");

        @endcode

        @endcode

    */

    */

        std::string_view host,

        std::string_view host,

        std::string_view service)

        std::string_view service)

    {

    {

    }

    }

    /** Initiate an asynchronous resolve operation with flags.

    /** Initiate an asynchronous resolve operation with flags.

        Resolves the host and service names into a list of endpoints.

        Resolves the host and service names into a list of endpoints.

        @param host A string identifying a location.

        @param host A string identifying a location.

        @param service A string identifying the requested service.

        @param service A string identifying the requested service.

        @param flags Flags controlling resolution behavior.

        @param flags Flags controlling resolution behavior.

        @return An awaitable that completes with `io_result<resolver_results>`.

        @return An awaitable that completes with `io_result<resolver_results>`.

    */

    */

        std::string_view host,

        std::string_view host,

        std::string_view service,

        std::string_view service,

        resolve_flags flags)

        resolve_flags flags)

    {

    {

    }

    }

    /** Initiate an asynchronous reverse resolve operation.

    /** Initiate an asynchronous reverse resolve operation.

        Resolves an endpoint into a hostname and service name using

        Resolves an endpoint into a hostname and service name using

        reverse DNS lookup (PTR record query).

        reverse DNS lookup (PTR record query).

        @param ep The endpoint to resolve.

        @param ep The endpoint to resolve.

        @return An awaitable that completes with

        @return An awaitable that completes with

            `io_result<reverse_resolver_result>`.

            `io_result<reverse_resolver_result>`.

        @par Example

        @par Example

        @code

        @code

        endpoint ep(ipv4_address({127, 0, 0, 1}), 80);

        endpoint ep(ipv4_address({127, 0, 0, 1}), 80);

        auto [ec, result] = co_await r.resolve(ep);

        auto [ec, result] = co_await r.resolve(ep);

        if (!ec)

        if (!ec)

            std::cout << result.host_name() << ":" << result.service_name();

            std::cout << result.host_name() << ":" << result.service_name();

        @endcode

        @endcode

    */

    */

    {

    {

    }

    }

    /** Initiate an asynchronous reverse resolve operation with flags.

    /** Initiate an asynchronous reverse resolve operation with flags.

        Resolves an endpoint into a hostname and service name using

        Resolves an endpoint into a hostname and service name using

        reverse DNS lookup (PTR record query).

        reverse DNS lookup (PTR record query).

        @param ep The endpoint to resolve.

        @param ep The endpoint to resolve.

        @param flags Flags controlling resolution behavior. See reverse_flags.

        @param flags Flags controlling resolution behavior. See reverse_flags.

        @return An awaitable that completes with

        @return An awaitable that completes with

            `io_result<reverse_resolver_result>`.

            `io_result<reverse_resolver_result>`.

    */

    */

    {

    {

    }

    }

    /** Cancel any pending asynchronous operations.

    /** Cancel any pending asynchronous operations.

        All outstanding operations complete with `errc::operation_canceled`.

        All outstanding operations complete with `errc::operation_canceled`.

        Check `ec == cond::canceled` for portable comparison.

        Check `ec == cond::canceled` for portable comparison.

    */

    */

    void cancel();

    void cancel();

public:

public:

    struct resolver_impl : io_object_impl

    struct resolver_impl : io_object_impl

    {

    {

        virtual std::coroutine_handle<> resolve(

        virtual std::coroutine_handle<> resolve(

            std::coroutine_handle<>,

            std::coroutine_handle<>,

            capy::executor_ref,

            capy::executor_ref,

            std::string_view host,

            std::string_view host,

            std::string_view service,

            std::string_view service,

            resolve_flags flags,

            resolve_flags flags,

            std::stop_token,

            std::stop_token,

            std::error_code*,

            std::error_code*,

            resolver_results*) = 0;

            resolver_results*) = 0;

        virtual std::coroutine_handle<> reverse_resolve(

        virtual std::coroutine_handle<> reverse_resolve(

            std::coroutine_handle<>,

            std::coroutine_handle<>,

            capy::executor_ref,

            capy::executor_ref,

            endpoint const& ep,

            endpoint const& ep,

            reverse_flags flags,

            reverse_flags flags,

            std::stop_token,

            std::stop_token,

            std::error_code*,

            std::error_code*,

            reverse_resolver_result*) = 0;

            reverse_resolver_result*) = 0;

        virtual void cancel() noexcept = 0;

        virtual void cancel() noexcept = 0;

    };

    };

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif