core: clarify dns javadoc/tests about trailing path segments

Author: jdcormie

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

@@ -33,11 +33,12 @@
  * 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 first path
- * segment of the hierarchical target URI is interpreted as an RFC 2396 "server-based" authority and
- * used as the "service authority" of the resulting {@link NameResolver}. The "host" part of this
- * authority is the name to be resolved by DNS. The "port" part of this authority (if present) will
- * become the port number for all {@link InetSocketAddress} produced by this resolver. For example:
+ * URI is reserved for the address of alternative DNS server (not implemented yet). The target URI
+ * must be hierarchical and have exactly one path segment which will be interpreted as an RFC 2396
+ * "server-based" authority and used as the "service authority" of the resulting {@link
+ * NameResolver}. The "host" part of this authority is the name to be resolved by DNS. The "port"
+ * part of this authority (if present) will become the port number for all {@link InetSocketAddress}
+ * produced by this resolver. For example:
  *
  * <ul>
  *   <li>{@code "dns:///foo.googleapis.com:8080"} (using default DNS)</li>

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

@@ -47,21 +47,23 @@ public static Iterable<Object[]> data() {
 
   @Parameter public boolean enableRfc3986UrisParam;
 
-  private final SynchronizationContext syncContext = new SynchronizationContext(
-      new Thread.UncaughtExceptionHandler() {
-        @Override
-        public void uncaughtException(Thread t, Throwable e) {
-          throw new AssertionError(e);
-        }
-      });
-  private final NameResolver.Args args = NameResolver.Args.newBuilder()
-      .setDefaultPort(8080)
-      .setProxyDetector(GrpcUtil.DEFAULT_PROXY_DETECTOR)
-      .setSynchronizationContext(syncContext)
-      .setServiceConfigParser(mock(ServiceConfigParser.class))
-      .setChannelLogger(mock(ChannelLogger.class))
-      .setScheduledExecutorService(fakeClock.getScheduledExecutorService())
-      .build();
+  private final SynchronizationContext syncContext =
+      new SynchronizationContext(
+          new Thread.UncaughtExceptionHandler() {
+            @Override
+            public void uncaughtException(Thread t, Throwable e) {
+              throw new AssertionError(e);
+            }
+          });
+  private final NameResolver.Args args =
+      NameResolver.Args.newBuilder()
+          .setDefaultPort(8080)
+          .setProxyDetector(GrpcUtil.DEFAULT_PROXY_DETECTOR)
+          .setSynchronizationContext(syncContext)
+          .setServiceConfigParser(mock(ServiceConfigParser.class))
+          .setChannelLogger(mock(ChannelLogger.class))
+          .setScheduledExecutorService(fakeClock.getScheduledExecutorService())
+          .build();
 
   private DnsNameResolverProvider provider = new DnsNameResolverProvider();
 
@@ -103,6 +105,8 @@ public void newNameResolver_validDnsNameWithoutPort_usesDefaultPort() {
     assertThat(nameResolver.getPort()).isEqualTo(args.getDefaultPort());
   }
 
+  // TODO(jdcormie): Trailing path segments *should* be forbidden. This test just demonstrates that
+  // both newNameResolver() overloads behave the same with respect to this bug.
   @Test
   public void newNameResolver_toleratesTrailingPathSegments() {
     NameResolver nameResolver = newNameResolver("dns:///foo.googleapis.com/ig/nor/ed", args);