• Customizing Service Definitions

Unlike the HTTP server—which routes requests based on path expressions and HTTP verbs—the gRPC server routes requests by service and method names. This simplifies routing configuration: all you need to do is register your services.

private static GrpcRouting.Builder createRouting(Config config) {
    return GrpcRouting.builder()
            .service(new GreetService(config)) 
            .service(new EchoService())        
            .service(new MathService())        
            .unary(Strings.getDescriptor(),    
                   "StringService",
                   "Upper",
                   Main::grpcUpper);
}

• Register GreetFeature instance.
• Register EchoService instance.
• Register MathService instance.
• Register a custom unary gRPC route

Both standard gRPC services that implement the io.grpc.BindableService interface (typically created by extending generated server-side stubs and overriding their methods) and Helidon gRPC services that implement the io.helidon.grpc.server.GrpcService interface can be registered.

The key difference is that Helidon gRPC services provide finer-grained control—allowing you to customize behavior at the method level—and include several helper methods that simplify service implementation, as we’ll see shortly.

Customizing Service Definitions

Implementing Protobuf Services

syntax = "proto3";
option java_package = "org.example.services.echo";

service EchoService {
  rpc Echo (EchoRequest) returns (EchoResponse) {}
}

message EchoRequest {
  string message = 1;
}

message EchoResponse {
  string message = 1;
}

class EchoService implements GrpcService {
    @Override
    public Descriptors.FileDescriptor proto() {
        return Echo.getDescriptor(); 
    }

    @Override
    public void update(Routing routing) {
        routing.unary("Echo", this::echo); 
    }

    /**
     * Echo the message back to the caller.
     *
     * @param request  the echo request containing the message to echo
     * @param observer the response observer
     */
    public void echo(Echo.EchoRequest request, StreamObserver<Echo.EchoResponse> observer) {  
        String message = request.getMessage();  
        Echo.EchoResponse response = Echo.EchoResponse.newBuilder().setMessage(message).build();  
        complete(observer, response);  
    }
}

gRPC supports the concept of server interceptors, which are useful for implementing cross-cutting concerns across any subset of methods or services. Interceptors implement the io.grpc.ServerInterceptor interface, which defines a single interceptCall method. Server interceptors are arranged in a chain that wraps the actual gRPC method invocation and can be ordered by weight.

Server interceptors are registered during route creation and will intercept all subsequent gRPC method calls. Because of this, registration order is important to ensure that interceptor chains are constructed correctly to achieve the desired behavior. For example, consider the following routing definition:

GrpcRouting.builder()
        .service(new GreetService(config))
        .intercept(new Interceptor1())
        .service(new EchoService())
        .intercept(InterceptorWeights.USER + 100, new Interceptor2())
        .service(new MathService())
        .build();

This routing includes two server interceptor instances of types Interceptor1 and Interceptor2. As stated above, the order in which these interceptors are registered is important. In this example, Interceptor1 will be called for any method in EchoService and MathService, but not for GreetService. Similarly, Interceptor2 will be called only for methods in MathService. The default weight of a server interceptor is InterceptorWeights.USER; it follows that for MathService, Interceptor2 will be called before Interceptor1 given its higher weight of Interceptor.USER + 100.

Helidon supports a few metrics that are specific to gRPC and are based on those defined in gRPC OpenTelemetry Metrics. Metrics are disabled by default, but can be easily enabled via configuration as we shall discuss shortly.

Here is the list of gRPC server metrics available in Helidon:

At the time of writing, Helidon only tracks successful method calls, so the value of the grpc.status label is always set to the string "OK". Support for metrics of unsuccessful calls may be added in the future, hence the need to include the label at this time.

As stated above, gRPC metrics are disabled by default but can be enabled by configuring the gRPC protocol in the Webserver. This can be accomplished either programmatically or directly in your server config file as follows:

server:
  port: 8080
  host: 0.0.0.0
  protocols:
    grpc:
      enable-metrics: true

The configuration above shall enable metrics on the Webserver’s default port 8080. For more information see Helidon Metrics.

Currently, we do not have any custom configuration options for the gRPC protocol.

To register a routing with Helidon WebServer, simply add the routing to the listener (WebServer configuration is itself the default listener configuration)

WebServer.builder()
        .port(8080)
        .routing(httpRouting -> httpRouting.get("/greet", (req, res) -> res.send("Hi!"))) 
        .addRouting(GrpcRouting.builder()  
                            .unary(Strings.getDescriptor(),
                                   "StringService",
                                   "Upper",
                                   Main::grpcUpper))
        .build()
        .start();

• Configure HTTP routing of the server
• Configure gRPC routing of the server

When a gRPC client interacts with a server, it must have access to the corresponding .proto file to understand the available services, methods, and message types. In many applications, this information is common knowledge shared between the client and server.

However, during development—especially when testing a new service—it can be useful to use tools such as grpcurl to invoke service methods directly. In such cases, one option is to provide the .proto file as a command-line argument, as shown below:

>> grpcurl -proto strings.proto -d '{ "text": "hello world" }' localhost:8080 StringService.Split

The parameter -proto is used by grpcurl to learn about the methods and messages types available in the proto file, and ultimately execute the requested gRPC call.

Helidon includes a gRPC reflection service that can be queried by tools such as grpcurl to learn about the available services—​similar to OpenAPI for REST services. The reflection service is implemented as a feature and can be enabled programmatically when adding the feature, or via config as follows:

  features:
    grpc-reflection:
      enabled: true

The feature accepts a list of sockets, or if omitted as seen above, it would enable the feature on all sockets. For security reasons, the gRPC reflection service is disabled by default; if enabled, it is recommended to disable the feature for production to avoid any unwanted requests. For more information about gRPC reflection, see gRPC Reflection.

gRPC compression is typically driven by client requests and can be asymmetric—that is, the server may use a different compression type than the client. In certain scenarios, such as debugging or performance testing, it may be useful to disable compression on the server side. As with most Helidon features, this can be configured either programmatically or through configuration.

server:
  port: 8080
  host: 0.0.0.0
  protocols:
    grpc:
      enable-compression: false

Compression is always enabled by default in Helidon, but can be disabled as shown above.