feat: async DNS resolver (hdns) + integrate into evpp clients

[ithewei]

Summary

Add a self-contained, non-blocking, native UDP async DNS resolver that runs
entirely inside the hloop event loop, and integrate it into the evpp client
connect path so hostname resolution no longer blocks the loop with a synchronous
getaddrinfo().

Approach follows libevent's evdns (event-driven UDP), not libuv's thread-pool
offload, and adds no third-party dependency (independent from the demo
protocol/dns.c).

What's included

Core resolver — event/hdns.{h,c} (compiled by default, no build flag)

• Async A / AAAA queries, results merged (IPv4 first).
• Nameservers from /etc/resolv.conf (Unix) / GetAdaptersAddresses (Windows),
  universal fallback to 8.8.8.8.
• Loads /etc/hosts; numeric-IP fast path; per-attempt timeout + retry +
  multi-nameserver rotation (IPv4/IPv6 sockets); DNS name-compression parsing.
• TTL-respecting per-loop cache (positive + negative).
• hdns_t is an hevent_t subclass (like htimer_t/hio_t); C API returns a
  hdns_t* handle, callback receives the handle, hdns_cancel(hdns_t*).

C++ handle model — evpp/Event.h, EventLoop.h

• EventLoop::resolveDns()/cancelDns() mirror setTimer()/killTimer() with a
  DnsID -> query map, making the handle use-after-free-proof (a stale id
  no-ops), same pattern as TimerID.

Client integration

• TcpClientEventLoopTmpl resolves hostnames asynchronously on first connect and
  every reconnect; numeric IPs keep the sync fast path. WebSocketClient and any
  other TcpClientTmpl subclass inherit this for free (no per-client glue).
• AsyncHttpClient uses EventLoop::resolveDns on its hostname path.
• First-attempt resolve failure still notifies onConnection with a valid
  (NULL-io) channel; Channel::error() surfaces the reason (ERR_DNS_RESOLVE
  added to herr.h) and is null-safe.

Build / examples / tests / docs

• Wired into Makefile, CMake and Bazel; iphlpapi linked on Windows.
• examples/host.c (async DNS lookup tool, nc/curl/wget style).
• unittest/hdns_test.c (mock nameserver, wire round-trip, cache, cancel,
  NXDOMAIN), unittest/tcpclient_dns_test.cpp (connect+reconnect, destroy-mid-
  resolve lifetime, resolve-failure notification), unittest/hdns_benchmark.c
  (getaddrinfo vs async comparison).
• docs/cn/hdns.md + README index; docs/PLAN.md marks async DNS done.

Testing

All DNS tests pass under both Makefile and CMake; real-network resolve verified;
benchmark shows async concurrent resolution is far faster than sequential
blocking and, more importantly, never stalls the event loop.

Notes / scope

• First version intentionally excludes: search domains / ndots, TCP fallback on
  truncation, nameserver health-checking, and raw record types (SRV/TXT/MX...).
  These are documented as future enhancements.
• AddressSanitizer could not run in the dev environment (a trivial ASan binary
  hangs at startup), so UAF-freedom is argued by the DnsID design plus the
  non-ASan lifetime regression test.

[Copilot]

Pull request overview

This PR introduces a native, non-blocking UDP-based async DNS resolver (hdns) that runs inside hloop, and integrates it into the C++ evpp client connect flow (and AsyncHttpClient) so hostname resolution no longer blocks the event loop.

Changes:

• Add core async DNS resolver implementation (event/hdns.{h,c}) with caching, retry/timeout, hosts lookup, and system nameserver discovery.
• Add C++ handle-based DNS APIs (EventLoop::resolveDns/cancelDns with DnsID) and integrate async resolution into TcpClient and AsyncHttpClient.
• Add tests/benchmarks and wire them into Makefile/CMake/scripts; add example and documentation updates.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
unittest/tcpclient_dns_test.cpp	Integration tests for evpp connect/reconnect, lifetime safety, and DNS-failure notification behavior.
unittest/hdns_test.c	Deterministic unit tests for hdns using a mock UDP nameserver and cache/cancel/NXDOMAIN coverage.
unittest/hdns_benchmark.c	Benchmark comparing blocking getaddrinfo() vs concurrent async hdns resolves.
unittest/CMakeLists.txt	Adds new DNS unit test and benchmark targets (and evpp DNS integration test under WITH_EVPP).
scripts/unittest.sh	Runs the new DNS unit tests when built.
Makefile.vars	Installs/exports the new public header event/hdns.h.
Makefile	Builds new example and DNS tests under make unittest and adds cleanup for evpp DNS test binary.
http/client/AsyncHttpClient.h	Adds internal continuation helper and clarifies teardown behavior re: in-flight DNS.
http/client/AsyncHttpClient.cpp	Replaces blocking host resolution with async DNS for hostname targets.
examples/http_client_test.cpp	Switches test URL host to localhost (hostname path).
examples/host.c	Adds an async DNS demo example using hdns_resolve.
examples/CMakeLists.txt	Builds and links the new host example.
evpp/TcpClient.h	Integrates async DNS into connect/reconnect path and surfaces DNS errors via Channel::error().
evpp/EventLoop.h	Adds resolveDns/cancelDns APIs with DnsID -> DnsQuery tracking.
evpp/Event.h	Introduces DnsID, DnsCallback, and DnsQuery holder types.
evpp/Channel.h	Adds explicit upper-layer error storage and makes error() null-safe for NULL-io channels.
event/hloop.c	Frees per-loop DNS resolver state during loop cleanup.
event/hevent.h	Adds dns_resolver field to hloop_t and declares hdns_resolver_free.
event/hdns.h	New public C API for async DNS resolution and cancellation.
event/hdns.c	New async DNS resolver implementation (wire codec, config, per-loop resolver, cache, lifecycle).
docs/PLAN.md	Marks async DNS as completed.
docs/cn/README.md	Adds hdns documentation link in the Chinese docs index.
docs/cn/hdns.md	Adds comprehensive Chinese documentation for hdns and the C++ integration model.
cmake/vars.cmake	Adds event/hdns.h to exported/installable headers list.
BUILD.bazel	Adds event/hdns.h to Bazel header lists.
base/herr.h	Introduces ERR_DNS_RESOLVE error code for surfacing DNS failures to users.

Comments suppressed due to low confidence (1)

event/hdns.c:993

• hdns_cancel() will double-free if it is (incorrectly) called from within the query's own callback: hdns__deliver() sets q->node.next/prev to NULL before invoking the callback, but hdns_cancel() still HV_FREE(q) unconditionally. Adding a guard makes this misuse fail-safe instead of crashing.

void hdns_cancel(hdns_t* q) {
    if (!q) return;
    if (q->node.next) list_del(&q->node);
    if (q->timer) { htimer_del(q->timer); q->timer = NULL; }
    if (q->defer_timer) { htimer_del(q->defer_timer); q->defer_timer = NULL; }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

evpp/TcpClient.h:89

• TcpClientEventLoopTmpl::createsocket uses return 0 to mean "pending hostname resolution", but createsocket(struct sockaddr*) can legally return a real socket fd of 0 on POSIX (and SOCKET 0 can also be valid). That makes the API ambiguous and contradicts the doc comment that says @retval >0 connfd.

Consider using an explicit non-fd sentinel (e.g. a distinct negative code like -EINPROGRESS / a library-defined HV_PENDING) and updating callers/tests to treat that sentinel as success, or otherwise guaranteeing that a successfully created fd is never 0.

    // NOTE: By default, not bind local port. If necessary, you can call bind() after createsocket().
    //
    // @retval >0  connfd: the socket was created immediately (remote_host is a
    //             numeric IP, or a Unix Domain Socket when remote_port < 0).
    // @retval =0  pending: remote_host is a hostname, so socket creation is
    //             deferred until the address is resolved asynchronously in
    //             startConnect() (avoids blocking the event loop on getaddrinfo).
    //             This is NOT an error; the real fd is available later via
    //             channel->fd(). Callers should treat >=0 as success and only
    //             <0 as failure.
    // @retval <0  error.
    //
    // Rationale for the =0 case: a socket's address family (AF_INET vs AF_INET6)
    // must be known before socket() is called, but for a hostname the family is
    // only known after DNS returns an A (IPv4) or AAAA (IPv6) record. So the
    // socket cannot be created up front and is created once resolution completes
    // in startConnectWithAddr() -- the same order as the standard getaddrinfo
    // connect loop.
    int createsocket(int remote_port, const char* remote_host = "127.0.0.1") {
        this->remote_host = remote_host;
        this->remote_port = remote_port;
        memset(&remote_addr, 0, sizeof(remote_addr));
        // numeric IP (or UDS: port < 0) -> resolve now (non-blocking) and
        // create the socket immediately, returning the connfd (>0).
        if (remote_port < 0 || is_ipaddr(remote_host)) {
            int ret = sockaddr_set_ipport(&remote_addr, remote_host, remote_port);
            if (ret != 0) {
                return NABS(ret);
            }
            return createsocket(&remote_addr.sa);
        }
        // hostname -> defer socket creation to async resolution in
        // startConnect(); return 0 (pending), not an error.
        return 0;
    }

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

evpp/TcpClient.h:214

• The comment above notifyDisconnectThenReconnect() says the code will “touch no members afterwards”, but the function calls startReconnect() after onConnection returns. This is misleading and can give a false sense of lifetime safety for users who call setReconnect(NULL) or destroy the client inside onConnection.

    // @internal: notify a disconnect via onConnection, then reconnect if set.
    // NOTE: onConnection is a user callback that may delete this object, so we
    // snapshot whether to reconnect into a local BEFORE the callback and touch
    // no members afterwards (a user destroying the object must first call
    // setReconnect(NULL)). Shared by the onclose path and DNS-failure path.

evpp/TcpClient.h:88

• Using return value 0 to mean “pending hostname resolution” collides with a valid OS socket fd value (0 is possible if stdio fds are closed), and it also breaks call sites that treat the return value as the actual connfd (e.g. examples/protorpc/protorpc_client.cpp returns that fd to callers on success). Consider using a distinct sentinel that cannot be a real fd (e.g. a negative HV_* code like -EINPROGRESS), or adding a separate async-hostname API while keeping createsocket()’s “returns real fd” contract intact.

        // hostname -> defer socket creation to async resolution in
        // startConnect(); return 0 (pending), not an error.
        return 0;

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

evpp/TcpClient.h:61

• The createsocket() return-value documentation is internally inconsistent and can be ambiguous in edge cases: it says the immediate connfd is ">0" but file descriptor 0 can be a valid socket fd if stdin/stdout/stderr are closed. Since 0 is also used as the "pending DNS" sentinel, callers should not rely on "0 means pending" unless they also know the host is a hostname (and the docs should spell this out).

    // @retval >0  connfd: the socket was created immediately (remote_host is a
    //             numeric IP, or a Unix Domain Socket when remote_port < 0).
    // @retval =0  pending: remote_host is a hostname, so socket creation is
    //             deferred until the address is resolved asynchronously in
    //             startConnect() (avoids blocking the event loop on getaddrinfo).

event/hdns.c:833

• hdns__on_udp_read demuxes purely by transaction id and does not validate that the UDP response came from the nameserver that was queried. This allows off-path/local injection of spoofed DNS replies to the resolver's UDP socket (especially when an attacker can send to the ephemeral local port). At minimum, compare the sender address/port (hio_peeraddr) against the expected nameserver before accepting the packet.

            // parse this sub-query's answer
            uint32_t ttl = HDNS_CACHE_MAX_TTL;
            int rc = hdns__parse_response(pkt, readbytes, txid,
                                          q->addrs, HDNS_MAX_ADDRS,
                                          &q->naddrs, &ttl);

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

evpp/TcpClient.h:65

• The createsocket() return-value contract is documented as ">0 connfd" for the immediate-socket path, but socket() can legally return fd==0 (e.g., if stdin is closed). This makes the documentation incorrect and also makes "0 == pending" ambiguous on POSIX. At minimum, update the comment to not claim ">0" and warn callers not to use the numeric return value to distinguish pending vs created; consider using a distinct negative sentinel (e.g., -EINPROGRESS) if you need an unambiguous pending indicator.

    // NOTE: By default, not bind local port. If necessary, you can call bind() after createsocket().
    //
    // @retval >0  connfd: the socket was created immediately (remote_host is a
    //             numeric IP, or a Unix Domain Socket when remote_port < 0).
    // @retval =0  pending: remote_host is a hostname, so socket creation is
    //             deferred until the address is resolved asynchronously in
    //             startConnect() (avoids blocking the event loop on getaddrinfo).
    //             This is NOT an error; the real fd is available later via
    //             channel->fd(). Callers should treat >=0 as success and only
    //             <0 as failure.
    // @retval <0  error.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

evpp/TcpClient.h:58

• The createsocket() return-value docs say the immediate socket fd is ">0", but ::socket() can legally return 0. Since callers are told to treat ">=0" as success, the comment should match that to avoid confusion and mis-documentation.

    // @retval >0  connfd: the socket was created immediately (remote_host is a
    //             numeric IP, or a Unix Domain Socket when remote_port < 0).

evpp/TcpClient.h:78

• This comment says the immediate createsocket() path returns a connfd ">0", but 0 is also a valid fd from ::socket(). Update the comment to avoid implying 0 always means the "pending" (hostname) case.

        // numeric IP (or UDS: port < 0) -> resolve now (non-blocking) and
        // create the socket immediately, returning the connfd (>0).