The next step is to produce an interface with the service methods that the client requires.

For example, suppose we have a simple server side service that has a unary method to convert a string to uppercase.

@ApplicationScoped
@io.helidon.microprofile.grpc.core.Grpc
public interface StringService {

    @io.helidon.microprofile.grpc.core.Unary
    public String upper(String s) {
        return s == null ? null : s.toUpperCase();
    }
}

The service has been written using the Helidon MP APIs but could just as easily be a traditional gRPC Java service generated from Protobuf files. The client API is agnostic of the server side implementation, it only cares about the method type, the request and response types and the type of Marshaller used to serialize the request and response.

To write a client for the StringService all that is required is an interface.

@ApplicationScoped
@io.helidon.microprofile.grpc.core.Grpc
public interface StringService {

    @io.helidon.microprofile.grpc.core.Unary
    public String upper(String s);
}

There is no need to write any code to implement the client. The Helidon MP gRPC APIs will create a dynamic proxy for the interface using the information from the annotations and method signatures.

The interface in the example above used the same method signature as the server but this does not have to be the case, the interface could have used any supported signature for a unary method, so for example it could just have easily been the standard unary method signature:

@ApplicationScoped
@io.helidon.microprofile.grpc.core.Grpc
public interface StringService {

    @io.helidon.microprofile.grpc.core.Unary
    public void upper(String s, StreamObserver<String> response);
}

We could also have made the client asynchronous by using one of the async method signatures:

@ApplicationScoped
@io.helidon.microprofile.grpc.core.Grpc
public interface StringService {

    @io.helidon.microprofile.grpc.core.Unary
    public CompletableFuture<String> upper(String s);
}

For a gRPC client to connect to a server it requires a Channel. The Helidon MP gRPC APIs provide a way to inject channels into CDI beans that require them.

Channels are configured in the grpc section of the Helidon application configuration. The examples below use an application.yaml file but there are many other ways to use and override configuration in Helidon

grpc:
  channels:                
    test-server:           
      host: localhost      
      port: 1408           

• Channels are configured in the`channels` section
• Each sub-section is the Channel name that is then used to refer to this Channel in the application code
• Each channel contains a host name
• and a port.

While most client application only connect to a single server it is possible to configure multiple named channels if the client needs to connect to multiple servers.

grpc:
  channels:
    london:
      host: london.foo.com
      port: 1408
    new-york:
      host: ny.foo.com
      port: 1408

The above example shows two channel configurations, one named london and the other new-york.

Configuring TLS

grpc:
  channels:
    test-server:
      host: localhost
      port: 1408
      tls:                          
        enabled: true               
        tls-cert-path: /certs/foo.cert    
        tls-key-path: /certs/foo.key      
        tls-ca-cert-path: /certs/ca.cert   

Once one or more channels have been configured they can be used by client code. The simplest way to use a channel is to inject it into beans using CDI. The Helidon gRPC client APIs have CDI producers that can provide io.grpc.Channel instances.

For example, a class might have an injectable io.grpc.Channel field:

    @Inject                             
    @GrpcChannel(name = "test-server")  
    private Channel channel;

• The @Inject annotation tells CDI to inject the channel.
• The @GrpcChannel annotation is the qualifier that supplies the Channel name. This is the same name as used in the channel configuration in the configuration examples above.

When an instance of the CDI bean with the channel field is instantiated a channel will be injected into it.

The In-Process Channel

    @Inject                  
    @InProcessGrpcChannel    
    private Channel channel;

Now that there is a client interface and a Channel configuration we can use these in the client application. The simplest way is to use the client in a CDI microprofile application.

In the application class that requires the client we can declare a field of the same type as the client service interface. The field is then annotated so that CDI will inject the client proxy into the field.

@ApplicationScoped
public class Client {

    @Inject                                  
    @GrpcProxy                        
    @GrpcChannel(name = "test-server")       
    private StringService stringService;

• The @Inject annotation tells the CDI to inject the client implementation; the gRPC MP APIs have a bean provider that does this.
• The @GrpcProxy annotation is used by the CDI container to match the injection point to the gRPC MP APIs provider
• The @GrpcChannel annotation identifies the gRPC channel to be used by the client. The name used in the annotation refers to a channel name in the application configuration.

Now when the CDI container instantiates instances of the Client it will inject a dynamic proxy into the stringService field and then any code in methods in the Client class can call methods on the StringService which will be translated to gRPC calls.

In the example above there is no need to directly use a Channel directly. The correct channel is added to the dynamic client proxy internally by the Helidon MP gRPC APIs.