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

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 iOS it doesn't — the iOS app sandbox forbids execve of any binary the app didn't get a special pass for, and there's no equivalent of Android's lib*.so escape hatch. Result: :inet.getaddr/2 (and therefore Req, Finch, Mint, ReqLLM, and basically every Elixir HTTP library) fails on iOS the moment a request hits a hostname rather than a literal IP.

This module side-steps the problem by calling Darwin's getaddrinfo directly via a NIF, then seeding :inet_db with the result so subsequent BEAM-level lookups for the same host succeed from the in-process file table.

Android isn't affected — mob_beam.zig ships inet_gethost as libinet_gethost.so in jniLibs/, which the SELinux policy allows to execve. The NIF here would work on Android too but isn't wired up by default; the BEAM path is already functional there.

How to use it

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

resolve/1 calls Darwin's getaddrinfo via a NIF — iOS's own resolver — 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 cellular (it resolves via the carrier's DNS). This is the recommended path and is device-verified on cellular.

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:

• Gate it to iOS. On Android :native works (mob ships inet_gethost as a .so); forcing pure-:dns there breaks lookups. (And never reset the chain to include :native on iOS — exec'ing inet_gethost there is fatal, it crashes the BEAM.)
• 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. If a backend's IP changes mid-session, the cached entry will be stale — call resolve/1 again to refresh.
• 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 on iOS. Only :inet-mediated lookups (which covers almost all Elixir HTTP libraries) need our help.
• iOS only effectively. On Android and host (dev, macOS, Linux) the NIF works but is unnecessary; BEAM's built-in path is fine there.

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)