se.grpc.server.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2019, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= gRPC Server
:description: Helidon gRPC Server
:keywords: helidon, grpc, java, se
:feature-name: gRPC Server
:rootdir: {docdir}/../..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
** <>
** <>
- <>
** <>
- <>
== Overview
gRPC scope is temporarily smaller in Helidon, please follow issue
https://github.com/helidon-io/helidon/issues/5418
As this is still work in progress, the WebServer gRPC module is release in preview mode, as we may introduce backward
incompatible changes to our APIs, so we can re-introduce features.
The Helidon gRPC server provides a framework for creating link:http://grpc.io/[gRPC] applications.
While it allows you to deploy any standard gRPC service that
implements `io.grpc.BindableService` interface, including services generated
from the Protobuf IDL files (and even allows you to customize them to a certain
extent), using Helidon gRPC framework to implement your services has a number of
benefits:
* It allows you to define both HTTP and gRPC services using a similar programming
model, simplifying the learning curve for developers.
* It provides a number of helper methods that make service implementation
significantly simpler.
* It allows you to run gRPC and HTTP endpoints on the same WebServer, and even on the same port.
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.webserver
helidon-webserver-grpc
----
== Usage
=== gRPC Server Routing
- <>
Unlike the HTTP server, which allows you to route requests based on path expression
and the HTTP verb, the gRPC server always routes requests based on the service and
method name. This makes routing configuration somewhat simpler -- all you need
to do is register your services:
[source,java]
----
include::{sourcedir}/se/grpc/ServerSnippets.java[tag=snippet_1, indent=0]
----
<1> Register `GreetService` instance.
<2> Register `EchoService` instance.
<3> Register `MathService` instance.
<4> Register a custom unary gRPC route
Both "standard" gRPC services that implement `io.grpc.BindableService` interface
(typically implemented by extending the generated server-side stub and overriding
its methods), and Helidon gRPC services that implement
`io.helidon.grpc.server.GrpcService` interface can be registered.
The difference is that Helidon gRPC services allow you to customize behavior
down to the method level, and provide a number of useful helper methods that
make service implementation easier, as we'll see in a moment.
==== Customizing Service Definitions
When registering a service, regardless of its type, you can customize its
descriptor by providing an instance of `ServerServiceDefinition` to `service` method.
=== Service Implementation
==== Implementing Protobuf Services
In order to implement Protobuf-based service, you would follow the official
link:https://grpc.io/docs/quickstart/java.html[instructions] on the gRPC
website, which boil down to the following:
===== Define the Service IDL
For this example, we will re-implement the `EchoService` above as a Protobuf
service in `echo.proto` file.
[source, proto]
----
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;
}
----
Based on this IDL, the gRPC compiler will generate message classes (`EchoRequest`
and `EchoResponse`), client stubs that can be used to make RPC calls to the server,
as well as the base class for the server-side service implementation.
We can ignore the last one, and implement the service using Helidon gRPC framework
instead.
===== Implement the Service
The service implementation will be very similar to our original implementation:
[source,java]
----
include::{sourcedir}/se/grpc/ServerSnippets.java[tag=snippet_2, indent=0]
----
<1> Specify the proto descriptor in order to provide necessary type information and
enable Protobuf marshalling.
<2> Define unary method `Echo` and map it to the `this::echo` handler.
<3> Create a handler for the `Echo` method, using Protobuf message types for request and response.
<4> Extract message string from the request.
<5> Create the response containing extracted message.
<6> Send the response back to the client by completing response observer.
NOTE: The `complete` method shown in the example above is just one of many helper
methods available in the `ResponseHelper` class. See the full list
link:{grpc-server-javadoc-base-url}/io/helidon/webserver/grpc/ResponseHelper.html[here].
== Configuration
Configure the gRPC server using the Helidon configuration framework, either programmatically
or via a configuration file.
=== Configuring the gRPC Server in the Code
Currently, we do not have any custom configuration options for gRPC protocol.
To register a routing with Helidon WebServer, simply add the routing to the listener
(WebServer configuration is itself the default listener configuration)
[source,java]
----
include::{sourcedir}/se/grpc/ServerSnippets.java[tag=snippet_3, indent=0]
----
<1> Configure HTTP routing of the server
<2> Configure gRPC routing of the server
== Examples
The following gRPC examples for Helidon SE are available:
* link:{helidon-github-examples-url}/webserver/protocols[Multiple protocols on a single WebServer]