Diff coverage report for

//

//

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

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

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Steve Gerbino

//

//

// 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/endpoint.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/io/io_object.hpp>

#include <boost/corosio/io/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 <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 resolve_flags

inline resolve_flags

{

{

    return static_cast<resolve_flags>(

    return static_cast<resolve_flags>(

}

}

/** Combine two resolve_flags. */

/** Combine two resolve_flags. */

inline resolve_flags&

inline resolve_flags&

{

{

}

}

/** Intersect two resolve_flags. */

/** Intersect two resolve_flags. */

inline resolve_flags

inline resolve_flags

{

{

    return static_cast<resolve_flags>(

    return static_cast<resolve_flags>(

}

}

/** Intersect two resolve_flags. */

/** Intersect two resolve_flags. */

inline resolve_flags&

inline 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 reverse_flags

inline reverse_flags

{

{

    return static_cast<reverse_flags>(

    return static_cast<reverse_flags>(

}

}

/** Combine two reverse_flags. */

/** Combine two reverse_flags. */

inline reverse_flags&

inline reverse_flags&

{

{

}

}

/** Intersect two reverse_flags. */

/** Intersect two reverse_flags. */

inline reverse_flags

inline reverse_flags

{

{

    return static_cast<reverse_flags>(

    return static_cast<reverse_flags>(

}

}

/** Intersect two reverse_flags. */

/** Intersect two reverse_flags. */

inline reverse_flags&

inline 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<>

            -> 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, endpoint const& ep, reverse_flags flags) noexcept

            resolver& r, endpoint const& ep, reverse_flags flags) noexcept

        {

        {

        {

        {

        }

        }

        {

        {

            -> std::coroutine_handle<>

            -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    /** Destructor.

    /** Destructor.

        Cancels any pending operations.

        Cancels any pending operations.

    */

    */

    ~resolver() override;

    ~resolver() override;

    /** 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. After the move,

        Transfers ownership of the resolver resources. After the move,

        @p other is in a moved-from state and may only be destroyed or

        @p other is in a moved-from state and may only be destroyed or

        assigned to.

        assigned to.

        @param other The resolver to move from.

        @param other The resolver to move from.

        @pre No awaitables returned by @p other's `resolve` methods

        @pre No awaitables returned by @p other's `resolve` methods

            exist.

            exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this resolver.

            outlive this resolver.

    */

    */

    /** Move assignment operator.

    /** Move assignment operator.

        Destroys the current implementation and transfers ownership

        Destroys the current implementation and transfers ownership

        from @p other. After the move, @p other is in a moved-from

        from @p other. After the move, @p other is in a moved-from

        state and may only be destroyed or assigned to.

        state and may only be destroyed or assigned to.

        @param other The resolver to move from.

        @param other The resolver to move from.

        @pre No awaitables returned by either `*this` or @p other's

        @pre No awaitables returned by either `*this` or @p other's

            `resolve` methods exist.

            `resolve` methods exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this resolver.

            outlive this resolver.

        @return Reference to this resolver.

        @return Reference to this resolver.

    */

    */

    {

    {

    }

    }

    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.

        This resolver must outlive the returned awaitable.

        This resolver must outlive the returned awaitable.

        @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

    */

    */

    {

    {

    }

    }

    /** 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.

        This resolver must outlive the returned awaitable.

        This resolver must outlive the returned awaitable.

        @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 service, resolve_flags flags)

        std::string_view host, std::string_view service, 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).

        This resolver must outlive the returned awaitable.

        This resolver must outlive the returned awaitable.

        @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).

        This resolver must outlive the returned awaitable.

        This resolver must outlive the returned awaitable.

        @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 implementation : io_object::implementation

    struct implementation : io_object::implementation

    {

    {

        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;

    };

    };

protected:

protected:

    explicit resolver(handle h) noexcept : io_object(std::move(h)) {}

    explicit resolver(handle h) noexcept : io_object(std::move(h)) {}

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif