core: add javadoc and tests to enshrine some existing dns behavior

Update javadoc/tests to match reality w.r.t target URI path: path isn't
actually the name to resolve, only the first path segment is actually
used. This is a side effect of authority parsing later, in
DnsNameResolver.java. Any additional path segments are silently ignored.

Also fix an javadoc error regarding port: it isn't actually an input to
the DNS layer, it's carried forward as a property of our output
addresses at the io.grpc.NameResolver layer.

Author: jdcormie

core/src/main/java/io/grpc/internal/DnsNameResolverProvider.java

@@ -31,15 +31,18 @@
  * A provider for {@link DnsNameResolver}.
  *
  * <p>It resolves a target URI whose scheme is {@code "dns"}. The (optional) authority of the target
- * URI is reserved for the address of alternative DNS server (not implemented yet). The path of the
- * target URI, excluding the leading slash {@code '/'}, is treated as the host name and the optional
- * port to be resolved by DNS. Example target URIs:
+ * URI is reserved for the address of alternative DNS server (not implemented yet). The first path
+ * segment of the hierarchical target URI is interpreted as the RFC 2396 server-based authority of
+ * the resulting {@link NameResolver} (see {@link NameResolver#getServiceAuthority()}). The "host"
+ * part of this authority becomes the name to be resolved by DNS. The optional "port" part of this
+ * authority is used as the port number of all {@link InetSocketAddress} produced by this resolver
+ * (see also {@link NameResolver.Args#getDefaultPort()}). Example target URIs:
  *
  * <ul>
- *   <li>{@code "dns:///foo.googleapis.com:8080"} (using default DNS)</li>
+ *   <li>{@code "dns:///foo.googleapis.com:8080"} (using default DNS)
  *   <li>{@code "dns://8.8.8.8/foo.googleapis.com:8080"} (using alternative DNS (not implemented
- *   yet))</li>
- *   <li>{@code "dns:///foo.googleapis.com"} (without port)</li>
+ *       yet))
+ *   <li>{@code "dns:///foo.googleapis.com"} (without port)
  * </ul>
  */
 public final class DnsNameResolverProvider extends NameResolverProvider {

core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java

@@ -16,8 +16,7 @@
 
 package io.grpc.internal;
 
-import static org.junit.Assert.assertNull;
-import static org.junit.Assert.assertSame;
+import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.Mockito.mock;
 
@@ -59,10 +58,35 @@ public void isAvailable() {
   }
 
   @Test
-  public void newNameResolver() {
-    assertSame(DnsNameResolver.class,
-        provider.newNameResolver(URI.create("dns:///localhost:443"), args).getClass());
-    assertNull(
-        provider.newNameResolver(URI.create("notdns:///localhost:443"), args));
+  public void newNameResolver_acceptsHostAndPort() {
+    NameResolver nameResolver = provider.newNameResolver(URI.create("dns:///localhost:443"), args);
+    assertThat(nameResolver).isNotNull();
+    assertThat(nameResolver.getClass()).isSameInstanceAs(DnsNameResolver.class);
+    assertThat(nameResolver.getServiceAuthority()).isEqualTo("localhost:443");
+  }
+
+  @Test
+  public void newNameResolver_rejectsNonDnsScheme() {
+    NameResolver nameResolver =
+        provider.newNameResolver(URI.create("notdns:///localhost:443"), args);
+    assertThat(nameResolver).isNull();
+  }
+
+  @Test
+  public void newNameResolver_toleratesTrailingPathSegments() {
+    NameResolver nameResolver =
+        provider.newNameResolver(URI.create("dns:///foo.googleapis.com/ig/nor/ed"), args);
+    assertThat(nameResolver).isNotNull();
+    assertThat(nameResolver.getClass()).isSameInstanceAs(DnsNameResolver.class);
+    assertThat(nameResolver.getServiceAuthority()).isEqualTo("foo.googleapis.com");
+  }
+
+  @Test
+  public void newNameResolver_toleratesAuthority() {
+    NameResolver nameResolver =
+        provider.newNameResolver(URI.create("dns://8.8.8.8/foo.googleapis.com"), args);
+    assertThat(nameResolver).isNotNull();
+    assertThat(nameResolver.getClass()).isSameInstanceAs(DnsNameResolver.class);
+    assertThat(nameResolver.getServiceAuthority()).isEqualTo("foo.googleapis.com");
   }
 }