From a1464d680e5c5eab95d5d586b1e716b555cde57d Mon Sep 17 00:00:00 2001
From: John Cormie <jdcormie@google.com>
Date: Tue, 13 Jan 2026 12:33:54 -0800
Subject: [PATCH] core: clarify dns javadoc/test about trailing path segments

---
 .../io/grpc/internal/DnsNameResolverProvider.java     | 11 ++++++-----
 .../io/grpc/internal/DnsNameResolverProviderTest.java |  2 ++
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/core/src/main/java/io/grpc/internal/DnsNameResolverProvider.java b/core/src/main/java/io/grpc/internal/DnsNameResolverProvider.java
index 16edf767901..14b56f1a12a 100644
--- a/core/src/main/java/io/grpc/internal/DnsNameResolverProvider.java
+++ b/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>
diff --git a/core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java b/core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java
index 787272cf630..75b82df544f 100644
--- a/core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java
+++ b/core/src/test/java/io/grpc/internal/DnsNameResolverProviderTest.java
@@ -103,6 +103,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);