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

Recommended (set-and-forget): configure_pure_beam/1

At app startup, flip BEAM's lookup chain from the broken :native path to [:file, :dns] and seed fallback nameservers. After this, every :inet.getaddr/2 resolves via raw DNS queries from inside BEAM (no port program, no execve), and the usual HTTP libraries just work:

def on_start do
  Mob.DNS.configure_pure_beam()
  # …rest of startup…
end

Defaults to Google + Cloudflare DNS. Override via opt if your network requires it. See configure_pure_beam/1 for details and trade-offs vs the Apple-resolver-via-NIF path below.

Per-host (when Apple-resolver semantics matter): resolve/1

For hostnames that need iOS's resolver — VPN-pushed DNS, .local / mDNS, search-domain expansion, captive portals — call resolve/1 for each one. Idempotent and cheap; safe to call alongside configure_pure_beam/0 (the :file lookup runs first, so manually-resolved entries win over the :dns fallback).

{:ok, _ip} = Mob.DNS.resolve("internal.corp.local")

For a small fixed set, preresolve/1 does the whole list at once:

Mob.DNS.preresolve([
  "internal.corp.local",
  "service.local"
])

Both paths compose. The recommended pattern is configure_pure_beam at startup as the default, then resolve/1 only for the OS-resolver specials.

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)