Module net/dns

Name resolution — getaddrinfo behind typed lookup functions.

These calls BLOCK the event loop. They are spelled like every other awaited I/O operation, but the runtime calls getaddrinfo synchronously on the loop thread and hands back an already-resolved future (src/codegen/async/runtime_io_common.yo), so no other task makes progress for the duration of the lookup — which is the resolver's own timeout, seconds, when a nameserver is unreachable. getaddrinfo has no non-blocking kernel counterpart, which is why libuv, tokio and Go all run it on a thread pool; Yo does not yet have the spawn_blocking that would let it do the same (issues/stddoc-io-dns-resolution-blocks-the-event-loop.md). Resolve once at startup rather than per request.

Failures throw NetError.DNSFailed (D1). Nothing here caches: every call is a fresh resolver query, subject to the system resolver's own cache.

{ lookup_host } :: import("std/net/dns");
{ IoExn } :: import("std/error");

addrs := io.await(lookup_host(`localhost`, io), IoExn(io : io, exn : exn));

Stability

unstable, and it is the least finished module in std/net. Two things have to be decided before the two functions here can be frozen: the blocking-on-the-loop behaviour above (a fix changes no signature, but it is the reason this surface should not attract callers yet); and the result list, which today repeats each address once per socket type (issues/stddoc-io-dns-lookup-host-returns-duplicate-addresses.md). The error carries its reason since 2026-10-03 (NetError.DNSFailed(host, reason), DnsError). Reverse lookup is absent even though getnameinfo is plumbed one layer down in std/sys/dns.