API target strings

Target String vs. Authority String

Many of our high-level APIs (e.g. GrpcChannelFactory and GrpcChannelBuilderCustomizer) accept a "target" string which can be either a valid NameResolver-compliant URI, an authority string, or the name of a user-configured channel.

Our definition of "target" string is the same as the grpc-java framework we sit on top of with the additional concept of a user-configured channel.

NameResolver-compliant URI

A NameResolver-compliant URI is an absolute hierarchical URI as defined by java.net.URI. For example:

• dns:///foo.googleapis.com:8080

• dns:///foo.googleapis.com

• dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443

• dns://8.8.8.8/foo.googleapis.com:8080

• dns://8.8.8.8/foo.googleapis.com

• zookeeper://zk.example.com:9900/example_service

Authority String

An authority string is the section of a URI following the scheme (e.g. https://) and preceding the path, typically containing the hostname, optional user information, and optional port. It defines the specific server to which the request is sent. For example:

• localhost

• 127.0.0.1

• localhost:8080

• foo.googleapis.com:8080

• 127.0.0.1:8080

• [2001:db8:85a3:8d3:1319:8a2e:370:7348]

• [2001:db8:85a3:8d3:1319:8a2e:370:7348]:443

Note	An authority string will be converted to a NameResolver-compliant URI, which has the scheme from the name resolver with the highest priority (e.g. dns), no authority, and the original authority string as its path after properly escaped.

User-configured channel

A user-configured channel, also referred to as a "named" channel, is a pre-configured channel. When using Spring Boot, this is provided via GrpcClientProperties (i.e. spring.grpc.client.channels.my-channel.* in application properties).

For example, the target string would be "my-channel" and application properties like this:

spring:
  grpc:
    client:
      channels:
        my-channel:
          address: localhost:9999