A Helidon gRPC client can be configured from generated protobuf stubs. In what follows, we shall use the following proto file and the corresponding stubs generated using the protoc command:

syntax = "proto3";
option java_package = "my.package";

service StringService {
  rpc Upper (StringMessage) returns (StringMessage) {}
  rpc Split (StringMessage) returns (stream StringMessage) {}
}

message StringMessage {
  string text = 1;
}

The gRPC protocol runs on top of HTTP/2, and as such requires TLS configuration to establish a connection. Thus, the first step is to configure TLS as shown next:

Tls clientTls = Tls.builder()
        .trust(trust -> trust
                .keystore(store -> store
                        .passphrase("password")
                        .trustStore(true)
                        .keystore(Resource.create("client.p12"))))
        .build();

After creating a Tls instance, a WebClient can be created as follows:

WebClient webClient = WebClient.builder()
        .tls(clientTls)
        .baseUri("https://localhost:8080")
        .build();

So far, this is all the same as for accessing any protected REST endpoint; the next step is to obtain a gRPC client stub using our newly created client. This can be accomplished by switching the client protocol to gRPC, and using its channel to create a stub:

GrpcClient grpcClient = webClient.client(GrpcClient.PROTOCOL);
StringServiceGrpc.StringServiceBlockingStub service =
        StringServiceGrpc.newBlockingStub(grpcClient.channel());

Once a stub is created, it can be used to invoke any of its declared methods, such as upper to uppercase a string:

Strings.StringMessage msg1 = newMessage("hello");
Strings.StringMessage res1 = service.upper(msg1);
String uppercased = res1.getText();

When it comes to invoking a method that can return more than one value, there are two options: it can block (we are using virtual theads after all!) and return back an Iterator or you can provide a StreamObserver as it is more commonly done when using gRPC. Let’s consider the case of the split method that breaks up a sentence into individual words, and can thus return multiple string messages.

Using an iterator as a result:

Strings.StringMessage msg2 = newMessage("hello world");
Iterator<Strings.StringMessage> res2 = service.split(msg2);
while (res2.hasNext()) {
    // ...
}

Passing a stream observer and collecting all the messages into a Future that returns an iterator:

Strings.StringMessage msg3 = newMessage("hello world");
CompletableFuture<Iterator<Strings.StringMessage>> future = new CompletableFuture<>();
service.split(msg3, new StreamObserver<Strings.StringMessage>() {
    private final List<Strings.StringMessage> value = new ArrayList<>();

    @Override
    public void onNext(Strings.StringMessage value) {
        this.value.add(value);
    }

    @Override
    public void onError(Throwable t) {
        future.completeExceptionally(t);
    }

    @Override
    public void onCompleted() {
        future.complete(value.iterator());
    }
});

Service descriptors are an alternative to using generated stubs and the protoc compiler. A service descriptor provides service meta-data to the WebClient for the purpose of carrying out invocations. The descriptor includes, the service name, and a description of each service method, including its type, what it accepts and what it returns.

The following is a descriptor for a service that includes the methods called in the previous section using a stub:

GrpcServiceDescriptor serviceDescriptor = GrpcServiceDescriptor.builder()
        .serviceName("StringService")
        .putMethod("Upper",
                   GrpcClientMethodDescriptor.unary("StringService", "Upper")
                           .requestType(Strings.StringMessage.class)
                           .responseType(Strings.StringMessage.class)
                           .build())
        .putMethod("Split",
                   GrpcClientMethodDescriptor.serverStreaming("StringService", "Split")
                           .requestType(Strings.StringMessage.class)
                           .responseType(Strings.StringMessage.class)
                           .build())
        .build();

Configuring a WebClient with Tls is done in the same manner as shown above for the stub case. Once the gRPC client is created, a service descriptor can be provided, and a method invoked using the methods unary, clientStream, serverStream or bidi. For example,

Strings.StringMessage res = grpcClient.serviceClient(serviceDescriptor)
        .unary("Upper", newMessage("hello"));

A ClientURISupplier can be used to dynamically obtain a sequence of ClientUri instances to access when executing a gRPC request. If a client URI supplier is configured, the Helidon gRPC implementation will attempt to connect to each endpoint one by one, in the order provided, until a connection is successfully established. This feature is useful in certain environments in which more than one identical server is available, but with some potentially unavailable or unreachable.

A few common implementations are provided in ClientUriSuppliers. These include suppliers for strategies such as random, round-robin, among others. Applications can either use one of the built-in suppliers or create their own.

The following example configures a round-robin supplier using a collection of known servers:

GrpcClient grpcClient = GrpcClient.builder()
        .tls(clientTls)
        .clientUriSupplier(RoundRobinSupplier.create(myServers()))
        .build();

If both a base URI and a client URI supplier are configured, the latter will take precendence over the former.

The gRPC API supports the notion of an interceptor on a channel. Interceptors are useful to implement cross-cutting concerns that apply to many or all invocations. These may include security, logging, metrics, etc. They can be specified directly on the channel returned by a GrpcClient, effectively wrapping that channel with a list of interceptors to execute on every invocation.

Channel newChannel = grpcClient.channel(myInterceptors());