Hostname → IP resolution that works around BEAM's broken DNS path on iOS and physical Android devices.

Why this exists

BEAM resolves hostnames by spawning an external helper called inet_gethost (a port program). On macOS, Linux, Windows that works fine. On mobile it doesn't, for two distinct reasons:

• iOS — the app sandbox forbids execve of any binary the app didn't get a special pass for. inet_gethost never runs.
• Physical Android (some devices) — inet_gethost does run (mob ships it as libinet_gethost.so, allowed to execve by the apk_data_file SELinux label), but on some devices Bionic's getaddrinfo from the execve'd child process returns :nxdomain for hostnames the same app's in-process HTTPS stack resolves fine. Confirmed on a Moto G Power 5G 2024 (Android 14): app-uid TCP-by-IP succeeds, but BEAM's :inet.getaddr/2 fails with :nxdomain. A Moto G Power 2021 (Android 11) resolves fine through the same path, as does the Android emulator (its DNS proxy at 10.0.2.3 is reachable to anything) — so don't rely on it.

In either case :inet.getaddr/2 (and therefore Req, Finch, Mint, ReqLLM, and basically every Elixir HTTP library) fails the moment a request hits a hostname rather than a literal IP.

This module side-steps the problem by calling the OS resolver (getaddrinfo) in-process via a NIF — same address space, same uid as the rest of the app — then seeding :inet_db with the result so subsequent BEAM-level lookups for the same host succeed from the in-process file table.

How to use it

Robust everywhere, incl. cellular: resolve/1 · preresolve/1

resolve/1 calls the OS's getaddrinfo via a NIF — Darwin's on iOS, Bionic's on Android — then seeds :inet_db's :file table, so subsequent :inet.getaddr/2 lookups (Req / Finch / Mint) find the result. Because it uses the OS resolver, it works wherever the OS does — including iOS cellular (carrier's DNS) and physical Android devices where the forked inet_gethost path is broken. This is the recommended path on both platforms.

Preresolve your known hosts at startup — that's all most apps need:

def on_start do
  Mob.DNS.preresolve(["api.example.com", "cdn.example.com"])
  # …rest of startup…
end

For a host not known until request time, call resolve/1 just before the request. Idempotent and cheap.

General fallback (WiFi-friendly): configure_pure_beam/1

Flips the lookup chain to [:file, :dns] and seeds nameservers so any hostname resolves via raw DNS from inside BEAM — useful when you can't enumerate hosts up front:

def on_start do
  if :mob_nif.platform() == :ios, do: Mob.DNS.configure_pure_beam()
end

Two caveats that make this the fallback, not the default:

• Don't reset the chain to include :native on iOS — exec'ing inet_gethost there is fatal, it crashes the BEAM. On physical Android :native is non-fatal but unreliable (returns :nxdomain for hostnames that do resolve in-process); Mob.DNS.resolve/1 is the recommended path there too.
• It can't resolve on cellular by default. Its default nameservers are public (Google / Cloudflare), which carriers commonly block → :nxdomain. iOS exposes no reliable API to read the carrier's resolvers, so there's nothing dependable to seed instead. On cellular, prefer preresolve/resolve above, or pass :nameservers you know are reachable.

The two compose: :file is consulted before :dns, so anything you resolve/1 wins over the configure_pure_beam fallback.

Scope and limitations

• IPv4 only. Most cloud endpoints serve A records; IPv6 is a follow-up if it becomes useful.
• One IP per host. If the hostname has multiple A records, the first one is used. BEAM caches the result; failover isn't automatic. If your endpoint cycles IPs frequently you may need to re-resolve.
• No automatic refresh. Mappings stay in :inet_db until the BEAM exits or the host is resolved again. Call resolve/1 after a network change (or when a backend's IP may have moved): the fresh answer replaces the host's previous address, and other hosts seeded through resolve/1 on a shared address keep theirs.
• Don't hand-edit seeded hosts with :inet_db.del_host(ip). It removes the address for every hostname seeded under it — with a DNS sinkhole answering 0.0.0.0 for many names, that unseeds all of them. Re-resolve instead.
• Doesn't help raw NIF networking. If a third-party NIF calls libc getaddrinfo itself, it never goes through BEAM's DNS layer and doesn't need (or benefit from) this fix — it already works. Only :inet-mediated lookups (which covers almost all Elixir HTTP libraries) need our help.
• Background-app network restrictions still apply. Android's App Standby / battery optimizer can block all outbound network from a backgrounded app, including TCP-by-IP — resolving a name won't help if the OS is silently dropping the connect(). Use a foreground service or keep the app foregrounded for sustained DNS / connectivity.
• Host dev (Mac, Linux) doesn't need this. The NIF isn't loaded off-device; callers get {:error, :nif_not_loaded} and should fall back to BEAM's normal path (which works on dev).

Errors

{:ok, {a, b, c, d}}              # success
{:error, :badarg}                # host arg invalid
{:error, :nxdomain}              # no such hostname
{:error, :timeout}               # resolver TRY_AGAIN
{:error, :no_address}            # resolved but no IPv4
{:error, {:gai, code}}           # raw getaddrinfo error code
{:error, :nif_not_loaded}        # called off-device (host tests)