Add reverse DNS resolution support to resolver

Implement reverse DNS lookup capability for the resolver class, enabling
hostname lookups from IP addresses using getnameinfo() on POSIX and
GetNameInfoW() on Windows.

New API:
- resolve(endpoint) - reverse resolve with default flags
- resolve(endpoint, reverse_flags) - reverse resolve with custom flags
- reverse_flags enum (numeric_host, numeric_service, name_required, datagram_service)
- reverse_resolver_result class with endpoint(), host_name(), service_name()

Implementation uses worker threads on both platforms since the underlying
APIs (getnameinfo/GetNameInfoW) are synchronous. Thread lifetime is managed
via shared_ptr to prevent use-after-free during shutdown.

Author: sgerbino

include/boost/corosio/resolver.hpp

@@ -12,6 +12,7 @@
 
 #include <boost/corosio/detail/config.hpp>
 #include <boost/corosio/detail/except.hpp>
+#include <boost/corosio/endpoint.hpp>
 #include <boost/corosio/io_object.hpp>
 #include <boost/capy/io_result.hpp>
 #include <boost/corosio/resolver_results.hpp>
@@ -107,6 +108,68 @@ operator&=(resolve_flags& a, resolve_flags b) noexcept
 
 //------------------------------------------------------------------------------
 
+/** Bitmask flags for reverse resolver queries.
+
+    These flags correspond to the flags parameter of getnameinfo.
+*/
+enum class reverse_flags : unsigned int
+{
+    /// No flags.
+    none = 0,
+
+    /// Return the numeric form of the hostname instead of its name.
+    numeric_host = 0x01,
+
+    /// Return the numeric form of the service name instead of its name.
+    numeric_service = 0x02,
+
+    /// Return an error if the hostname cannot be resolved.
+    name_required = 0x04,
+
+    /// Lookup for datagram (UDP) service instead of stream (TCP).
+    datagram_service = 0x08
+};
+
+/** Combine two reverse_flags. */
+inline
+reverse_flags
+operator|(reverse_flags a, reverse_flags b) noexcept
+{
+    return static_cast<reverse_flags>(
+        static_cast<unsigned int>(a) |
+        static_cast<unsigned int>(b));
+}
+
+/** Combine two reverse_flags. */
+inline
+reverse_flags&
+operator|=(reverse_flags& a, reverse_flags b) noexcept
+{
+    a = a | b;
+    return a;
+}
+
+/** Intersect two reverse_flags. */
+inline
+reverse_flags
+operator&(reverse_flags a, reverse_flags b) noexcept
+{
+    return static_cast<reverse_flags>(
+        static_cast<unsigned int>(a) &
+        static_cast<unsigned int>(b));
+}
+
+/** Intersect two reverse_flags. */
+inline
+reverse_flags&
+operator&=(reverse_flags& a, reverse_flags b) noexcept
+{
+    a = a & b;
+    return a;
+}
+
+//------------------------------------------------------------------------------
+
 /** An asynchronous DNS resolver for coroutine I/O.
 
     This class provides asynchronous DNS resolution operations that return
@@ -192,6 +255,58 @@ class BOOST_COROSIO_DECL resolver : public io_object
         }
     };
 
+    struct reverse_resolve_awaitable
+    {
+        resolver& r_;
+        endpoint ep_;
+        reverse_flags flags_;
+        std::stop_token token_;
+        mutable system::error_code ec_;
+        mutable reverse_resolver_result result_;
+
+        reverse_resolve_awaitable(
+            resolver& r,
+            endpoint const& ep,
+            reverse_flags flags) noexcept
+            : r_(r)
+            , ep_(ep)
+            , flags_(flags)
+        {
+        }
+
+        bool await_ready() const noexcept
+        {
+            return token_.stop_requested();
+        }
+
+        capy::io_result<reverse_resolver_result> await_resume() const noexcept
+        {
+            if (token_.stop_requested())
+                return {make_error_code(system::errc::operation_canceled), {}};
+            return {ec_, std::move(result_)};
+        }
+
+        template<typename Ex>
+        auto await_suspend(
+            std::coroutine_handle<> h,
+            Ex const& ex) -> std::coroutine_handle<>
+        {
+            r_.get().reverse_resolve(h, ex, ep_, flags_, token_, &ec_, &result_);
+            return std::noop_coroutine();
+        }
+
+        template<typename Ex>
+        auto await_suspend(
+            std::coroutine_handle<> h,
+            Ex const& ex,
+            std::stop_token token) -> std::coroutine_handle<>
+        {
+            token_ = std::move(token);
+            r_.get().reverse_resolve(h, ex, ep_, flags_, token_, &ec_, &result_);
+            return std::noop_coroutine();
+        }
+    };
+
 public:
     /** Destructor.
 
@@ -306,6 +421,46 @@ class BOOST_COROSIO_DECL resolver : public io_object
         return resolve_awaitable(*this, host, service, flags);
     }
 
+    /** Initiate an asynchronous reverse resolve operation.
+
+        Resolves an endpoint into a hostname and service name using
+        reverse DNS lookup (PTR record query).
+
+        @param ep The endpoint to resolve.
+
+        @return An awaitable that completes with
+            `io_result<reverse_resolver_result>`.
+
+        @par Example
+        @code
+        endpoint ep(urls::ipv4_address({127, 0, 0, 1}), 80);
+        auto [ec, result] = co_await r.resolve(ep);
+        if (!ec)
+            std::cout << result.host_name() << ":" << result.service_name();
+        @endcode
+    */
+    auto resolve(endpoint const& ep)
+    {
+        return reverse_resolve_awaitable(*this, ep, reverse_flags::none);
+    }
+
+    /** Initiate an asynchronous reverse resolve operation with flags.
+
+        Resolves an endpoint into a hostname and service name using
+        reverse DNS lookup (PTR record query).
+
+        @param ep The endpoint to resolve.
+
+        @param flags Flags controlling resolution behavior. See reverse_flags.
+
+        @return An awaitable that completes with
+            `io_result<reverse_resolver_result>`.
+    */
+    auto resolve(endpoint const& ep, reverse_flags flags)
+    {
+        return reverse_resolve_awaitable(*this, ep, flags);
+    }
+
     /** Cancel any pending asynchronous operations.
 
         All outstanding operations complete with `errc::operation_canceled`.
@@ -326,6 +481,15 @@ class BOOST_COROSIO_DECL resolver : public io_object
             system::error_code*,
             resolver_results*) = 0;
 
+        virtual void reverse_resolve(
+            std::coroutine_handle<>,
+            capy::executor_ref,
+            endpoint const& ep,
+            reverse_flags flags,
+            std::stop_token,
+            system::error_code*,
+            reverse_resolver_result*) = 0;
+
         virtual void cancel() noexcept = 0;
     };
 

include/boost/corosio/resolver_results.hpp

@@ -200,6 +200,65 @@ class resolver_results
     }
 };
 
+//------------------------------------------------------------------------------
+
+/** The result of a reverse DNS resolution.
+
+    This class holds the result of resolving an endpoint
+    into a hostname and service name.
+
+    @par Thread Safety
+    Distinct objects: Safe.@n
+    Shared objects: Safe.
+*/
+class reverse_resolver_result
+{
+    corosio::endpoint ep_;
+    std::string host_;
+    std::string service_;
+
+public:
+    /** Default constructor. */
+    reverse_resolver_result() = default;
+
+    /** Construct with endpoint, host name, and service name.
+
+        @param ep The endpoint that was resolved.
+        @param host The resolved host name.
+        @param service The resolved service name.
+    */
+    reverse_resolver_result(
+        corosio::endpoint ep,
+        std::string host,
+        std::string service)
+        : ep_(ep)
+        , host_(std::move(host))
+        , service_(std::move(service))
+    {
+    }
+
+    /** Get the endpoint that was resolved. */
+    corosio::endpoint
+    endpoint() const noexcept
+    {
+        return ep_;
+    }
+
+    /** Get the resolved host name. */
+    std::string const&
+    host_name() const noexcept
+    {
+        return host_;
+    }
+
+    /** Get the resolved service name. */
+    std::string const&
+    service_name() const noexcept
+    {
+        return service_;
+    }
+};
+
 } // namespace corosio
 } // namespace boost