diff --git a/api/src/main/java/io/grpc/FeatureFlags.java b/api/src/main/java/io/grpc/FeatureFlags.java index 0e414ed7b31..36fec1b9a59 100644 --- a/api/src/main/java/io/grpc/FeatureFlags.java +++ b/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 diff --git a/api/src/main/java/io/grpc/Grpc.java b/api/src/main/java/io/grpc/Grpc.java index a45c613fd18..ad1de210854 100644 --- a/api/src/main/java/io/grpc/Grpc.java +++ b/api/src/main/java/io/grpc/Grpc.java @@ -73,11 +73,10 @@ 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. * - *
A {@code NameResolver}-compliant URI is an absolute hierarchical URI as defined by {@link - * java.net.URI}. Example URIs: + *
Example URIs: *
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. + *
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: *
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) { diff --git a/api/src/main/java/io/grpc/ManagedChannelBuilder.java b/api/src/main/java/io/grpc/ManagedChannelBuilder.java index 3f370ab3003..7681c8f7b62 100644 --- a/api/src/main/java/io/grpc/ManagedChannelBuilder.java +++ b/api/src/main/java/io/grpc/ManagedChannelBuilder.java @@ -45,11 +45,10 @@ 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. * - *
A {@code NameResolver}-compliant URI is an absolute hierarchical URI as defined by {@link - * java.net.URI}. Example URIs: + *
Example URIs: *
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. + *
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: *
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. + * *
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