DNS Extension

Warning

async-dns does not currently support TCP fallback and so DNS repsonses may be truncated. See #25460

Note

The async-dns API is marked as ApiMayChange as more information is expected to be added to the protocol.

Akka DNS is a pluggable way to interact with DNS. Implementations much implement akka.io.DnsProvider and provide a configuration block that specifies the implementation via provider-object.

To select which DnsProvider to use set akka.io.dns.resolver to the location of the configuration.

There are currently two implementations:

  • inet-address - Based on the JDK’s InetAddress. Using this will be subject to both the JVM’s DNS cache and its built in one.
  • async-dns - A native implemention of the DNS protocol that does not use any JDK classes or caches.

inet-address is the default implementation as it pre-dates async-dns, async-dns will likely become the default in the next major release.

DNS lookups can be done via the DNS extension:

Scala
val initial: Option[Dns.Resolved] = Dns(system).cache.resolve("google.com")(system, actorRef)
val cached: Option[Dns.Resolved] = Dns(system).cache.cached("google.com")
Full source at GitHub
Java
Option<Dns.Resolved> initial = Dns.get(system).cache().resolve("google.com", system, actorRef);
Option<Dns.Resolved> cached = Dns.get(system).cache().cached("google.com");
Full source at GitHub

Alternatively the IO(Dns) actor can be interacted with directly. However this exposes the different protocols of the DNS provider. inet-adddress uses Dns.Resolved and Dns.Resolved where as the async-dns uses DnsProtocol.Resolve and DnsProtocol.Resolved. The reason for the difference is inet-address predates async-dns and async-dns exposes additional information such as SRV records and it wasn’t possible to evolve the original API in a backward compatible way.

Inet-Address API:

Scala
val resolved: Future[Dns.Resolved] = (IO(Dns) ? Dns.Resolve("google.com")).mapTo[Dns.Resolved]
Full source at GitHub
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, new Dns.Resolve("google.com"), timeout);
Full source at GitHub

Async-DNS API:

Scala
val resolved: Future[DnsProtocol.Resolved] = (IO(Dns) ? DnsProtocol.Resolve("google.com")).mapTo[DnsProtocol.Resolved]
Full source at GitHub
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, DnsProtocol.resolve("google.com"), timeout);
Full source at GitHub

The Async DNS provider has the following advantages:

  • No JVM DNS caching. It is expected that future versions will expose more caching related information.
  • No blocking. InetAddress resolving is a blocking operation.
  • Exposes SRV, A and AAAA records.

SRV Records

To get DNS SRV records akka.io.dns.resolver must be set to async-dns and DnsProtocol.Resolve’s requestType must be set to DnsProtocol.Srv

Scala
val resolved: Future[DnsProtocol.Resolved] = (IO(Dns) ? DnsProtocol.Resolve("your-service", Srv))
  .mapTo[DnsProtocol.Resolved]
Full source at GitHub
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, DnsProtocol.resolve("google.com", DnsProtocol.srvRequestType()), timeout);
Full source at GitHub

The DnsProtocol.Resolved will contain akka.io.dns.SRVRecords.

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.