Docs: Discovery via DNS (#29153)

akka-docs/src/main/paradox/discovery/index.md

@@ -73,6 +73,12 @@ Port can be used when a service opens multiple ports e.g. a HTTP port and an Akk
 
 ## Discovery Method: DNS
 
+@@@ note { title="Async DNS" }
+
+Akka Discovery with DNS does always use the @ref[Akka-native "async-dns" implementation](../io-dns.md) (it is independent of the `akka.io.dns.resolver` setting).
+
+@@@
+
 DNS discovery maps `Lookup` queries as follows:
 
 * `serviceName`, `portName` and `protocol` set: SRV query in the form: `_port._protocol.name` Where the `_`s are added.
@@ -86,27 +92,15 @@ The mapping between Akka service discovery terminology and SRV terminology:
 
 Configure `akka-dns` to be used as the discovery implementation in your `application.conf`:
 
-@@snip[application.conf](/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala){ #configure-dns }
+@@snip[application.conf](/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala){ #configure-dns }
 
 From there on, you can use the generic API that hides the fact which discovery method is being used by calling:
 
 Scala
-:   ```scala
-    import akka.discovery.ServiceDiscovery
-    val system = ActorSystem("Example")
-    // ...
-    val discovery = ServiceDiscovery(system).discovery
-    val result: Future[Resolved] = discovery.lookup("service-name", resolveTimeout = 500 milliseconds)
-    ```
+:   @@snip[snip](/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala){ #lookup-dns }
 
 Java
-:   ```java
-    import akka.discovery.ServiceDiscovery;
-    ActorSystem system = ActorSystem.create("Example");
-    // ...
-    SimpleServiceDiscovery discovery = ServiceDiscovery.get(system).discovery();
-    Future<SimpleServiceDiscovery.Resolved> result = discovery.lookup("service-name", Duration.create("500 millis"));
-    ```
+:   @@snip[snip](/akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java){ #lookup-dns }
 
 ### DNS records used
 

akka-docs/src/main/paradox/io-dns.md

@@ -30,6 +30,12 @@ Users should pick one of the built in extensions.
 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`.
 
+@@@ note { title="DNS via Akka Discovery" }
+
+@ref[Akka Discovery](discovery/index.md) can be backed by the Akka DNS implementation and provides a more general API for service lookups which is not limited to domain name lookup.
+
+@@@
+
 To select which `DnsProvider` to use set `akka.io.dns.resolver ` to the location of the configuration.
 
 There are currently two implementations:

akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.discovery;
+
+import akka.actor.ActorSystem;
+// #lookup-dns
+import akka.discovery.Discovery;
+import akka.discovery.ServiceDiscovery;
+// #lookup-dns
+import akka.testkit.javadsl.TestKit;
+import docs.discovery.DnsDiscoveryDocSpec;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.scalatestplus.junit.JUnitSuite;
+
+import java.time.Duration;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.Assert.assertFalse;
+
+@SuppressWarnings("unused")
+public class DnsDiscoveryDocTest extends JUnitSuite {
+
+  private static ActorSystem system;
+
+  @BeforeClass
+  public static void setup() {
+    system = ActorSystem.create("LeaseDocTest", DnsDiscoveryDocSpec.config());
+  }
+
+  @AfterClass
+  public static void teardown() {
+    TestKit.shutdownActorSystem(system);
+    system = null;
+  }
+
+  @Test
+  public void dnsDiscoveryShouldResolveAkkaIo() throws Exception {
+    // #lookup-dns
+
+    ServiceDiscovery discovery = Discovery.get(system).discovery();
+    // ...
+    CompletionStage<ServiceDiscovery.Resolved> result =
+        discovery.lookup("akka.io", Duration.ofMillis(500));
+    // #lookup-dns
+    ServiceDiscovery.Resolved resolved =
+        result.toCompletableFuture().get(500, TimeUnit.MILLISECONDS);
+    assertFalse(resolved.getAddresses().isEmpty());
+  }
+}

akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.discovery
+
+import akka.testkit.AkkaSpec
+import com.typesafe.config.ConfigFactory
+
+import scala.concurrent.duration._
+import scala.concurrent.Future
+
+object DnsDiscoveryDocSpec {
+  val config = ConfigFactory.parseString("""
+    // #configure-dns
+    akka {
+      discovery {
+        method = akka-dns
+      }
+    }
+    // #configure-dns
+    """)
+}
+
+class DnsDiscoveryDocSpec extends AkkaSpec(DnsDiscoveryDocSpec.config) {
+
+  "DNS Discovery" should {
+    "find akka.io" in {
+      // #lookup-dns
+      import akka.discovery.Discovery
+      import akka.discovery.ServiceDiscovery
+
+      val discovery: ServiceDiscovery = Discovery(system).discovery
+      // ...
+      val result: Future[ServiceDiscovery.Resolved] = discovery.lookup("akka.io", resolveTimeout = 500.millis)
+      // #lookup-dns
+      val resolved = result.futureValue
+      resolved.serviceName shouldBe "akka.io"
+      resolved.addresses shouldNot be(Symbol("empty"))
+    }
+  }
+
+}