api: Turn on RFC 3986 parsing by default and update javadoc.

Removed the "NameResolver-compliant" terminology because it's no longer
needed. All RFC 3986 URIs are absolute in the sense that have a scheme
(URI != "URI-reference"). RFC 3986 also does away with the hierarchical
vs opaque distinction. All URIs now have a hierarchy of components
(scheme, authority, path, query and fragment) it's just that some
components can be absent and/or the empty string.

Added discussion of ambiguity which is technically new with the RFC 3986
change. If you believed the current javadoc, a target like foo:8888
didn't used to be ambiguous because it is not a "valid NameResolver-
compliant" URI -- the path doesn't start with / and so java.net.URI
considers it opaque, not hierarchical as required. Fortunately (???)
ManagedChannelImplBuilder never enforced the !isOpaque() requirement
mentioned in the javadoc and so this ambiguity isn't actually new in
practice. gRPC C++ also appears to suffer from the same problem.

Author: jdcormie

api/src/main/java/io/grpc/FeatureFlags.java

@@ -20,7 +20,7 @@
 import com.google.common.base.Strings;
 
 class FeatureFlags {
-  private static boolean enableRfc3986Uris = getFlag("GRPC_ENABLE_RFC3986_URIS", false);
+  private static boolean enableRfc3986Uris = getFlag("GRPC_ENABLE_RFC3986_URIS", true);
 
   /** Whether to parse targets as RFC 3986 URIs (true), or use {@link java.net.URI} (false). */
   @VisibleForTesting

api/src/main/java/io/grpc/Grpc.java

@@ -73,25 +73,24 @@ private Grpc() {
   public @interface TransportAttr {}
 
   /**
-   * Creates a channel builder with a target string and credentials. The target can be either a
-   * valid {@link NameResolver}-compliant URI, or an authority string.
+   * Creates a channel builder with a target string and credentials. The target can be either an RFC
+   * 3986 URI, or an authority string.
    *
-   * <p>A {@code NameResolver}-compliant URI is an absolute hierarchical URI as defined by {@link
-   * java.net.URI}. Example URIs:
+   * <p>Example URIs:
    * <ul>
    *   <li>{@code "dns:///foo.googleapis.com:8080"}</li>
    *   <li>{@code "dns:///foo.googleapis.com"}</li>
    *   <li>{@code "dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443"}</li>
    *   <li>{@code "dns://8.8.8.8/foo.googleapis.com:8080"}</li>
    *   <li>{@code "dns://8.8.8.8/foo.googleapis.com"}</li>
    *   <li>{@code "zookeeper://zk.example.com:9900/example_service"}</li>
+   *   <li>{@code "intent:#Intent;package=com.some.app;action=a;category=c;end;"}</li>
    * </ul>
    *
-   * <p>An authority string will be converted to a {@code NameResolver}-compliant URI, which has
-   * the scheme from the name resolver with the highest priority (e.g. {@code "dns"}),
-   * no authority, and the original authority string as its path after properly escaped.
-   * We recommend libraries to specify the schema explicitly if it is known, since libraries cannot
-   * know which NameResolver will be default during runtime.
+   * <p>An authority string will be converted to a URI having the scheme of the name resolver with
+   * the highest priority (e.g. {@code "dns"}), the empty string as the authority, and
+   * {@code target} as its absolute path. We recommend libraries specify {@code target} as a URI
+   * instead since they cannot know which NameResolver will be default at runtime.
    * Example authority strings:
    * <ul>
    *   <li>{@code "localhost"}</li>
@@ -102,6 +101,12 @@ private Grpc() {
    *   <li>{@code "[2001:db8:85a3:8d3:1319:8a2e:370:7348]"}</li>
    *   <li>{@code "[2001:db8:85a3:8d3:1319:8a2e:370:7348]:443"}</li>
    * </ul>
+   *
+   * <p>The URI form of {@code target} is preferred because it is less ambiguous. For example, the
+   * target string {@code foo:8080} is a valid authority string with host {@code foo} and port
+   * {@code 8080} but it is also a valid RFC 3986 URI with scheme {@code foo} and path {@code 8080}.
+   * gRPC prioritizes the URI form, which means {@code foo:8080} will be treated as a URI with
+   * scheme {@code foo}. Using {@code dns:///foo:8080} avoids this ambiguity.
    */
   public static ManagedChannelBuilder<?> newChannelBuilder(
       String target, ChannelCredentials creds) {

api/src/main/java/io/grpc/ManagedChannelBuilder.java

@@ -45,25 +45,24 @@ public static ManagedChannelBuilder<?> forAddress(String name, int port) {
   }
 
   /**
-   * Creates a channel with a target string, which can be either a valid {@link
-   * NameResolver}-compliant URI, or an authority string.
+   * Creates a channel with a target string, which can be either an RFC 3986 URI, or an authority
+   * string.
    *
-   * <p>A {@code NameResolver}-compliant URI is an absolute hierarchical URI as defined by {@link
-   * java.net.URI}. Example URIs:
+   * <p>Example URIs:
    * <ul>
    *   <li>{@code "dns:///foo.googleapis.com:8080"}</li>
    *   <li>{@code "dns:///foo.googleapis.com"}</li>
    *   <li>{@code "dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443"}</li>
    *   <li>{@code "dns://8.8.8.8/foo.googleapis.com:8080"}</li>
    *   <li>{@code "dns://8.8.8.8/foo.googleapis.com"}</li>
    *   <li>{@code "zookeeper://zk.example.com:9900/example_service"}</li>
+   *   <li>{@code "intent:#Intent;package=com.some.app;action=a;category=c;end;"}</li>
    * </ul>
    *
-   * <p>An authority string will be converted to a {@code NameResolver}-compliant URI, which has
-   * the scheme from the name resolver with the highest priority (e.g. {@code "dns"}),
-   * no authority, and the original authority string as its path after properly escaped.
-   * We recommend libraries to specify the schema explicitly if it is known, since libraries cannot
-   * know which NameResolver will be default during runtime.
+   * <p>An authority string will be converted to a URI having the scheme of the name resolver with
+   * the highest priority (e.g. {@code "dns"}), the empty string as the authority, and
+   * {@code target} as its absolute path. We recommend libraries specify {@code target} as a URI
+   * instead since they cannot know which NameResolver will be default at runtime.
    * Example authority strings:
    * <ul>
    *   <li>{@code "localhost"}</li>
@@ -75,6 +74,12 @@ public static ManagedChannelBuilder<?> forAddress(String name, int port) {
    *   <li>{@code "[2001:db8:85a3:8d3:1319:8a2e:370:7348]:443"}</li>
    * </ul>
    *
+   * <p>The URI form of {@code target} is preferred because it is less ambiguous. For example, the
+   * target string {@code foo:8080} is a valid authority string with host {@code foo} and port
+   * {@code 8080} but it is also a valid RFC 3986 URI with scheme {@code foo} and path {@code 8080}.
+   * gRPC prioritizes the URI form, which means {@code foo:8080} will be treated as a URI with
+   * scheme {@code foo}. Using {@code dns:///foo:8080} avoids this ambiguity.
+   *
    * <p>Note that there is an open JDK bug on {@link java.net.URI} class parsing an ipv6 scope ID:
    * bugs.openjdk.org/browse/JDK-8199396. This method is exposed to this bug. If you experience an
    * issue, a work-around is to convert the scope ID to its numeric form (e.g. by using