End-to-end gRPC SE Example

examples/webserver/grpc/README.md

@@ -0,0 +1,22 @@
+# Helidon gRPC SE Example
+
+This example shows a simple _Strings_ service written with the Helidon gRPC SE 
+API. See `StringService` for the service implementation and `StringServiceTest`
+for how to use the Helidon's `WebClient` to access the service. Client interceptors 
+are also supported, see `StringServiceInterceptor` for an example.
+
+The gRPC service definition is found in the `strings.proto` file which is compiled 
+using `protoc` at build time. The Strings service includes all 4 types of methods:
+unary, client streaming, server streaming and bidirectional.
+
+## Build and run tests
+
+```shell
+mvn package
+```
+
+## Run the app
+
+```shell
+java -jar target/helidon-examples-webserver-grpc.jar
+```

examples/webserver/grpc/pom.xml

@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 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.
+
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.applications</groupId>
+        <artifactId>helidon-se</artifactId>
+        <version>4.1.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>io.helidon.examples.webserver</groupId>
+    <artifactId>helidon-examples-webserver-grpc</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>Helidon Examples WebServer gRPC</name>
+
+    <description>
+        Application demonstrates the use of gRPC.
+    </description>
+
+    <properties>
+        <mainClass>io.helidon.examples.webserver.grpc.GrpcMain</mainClass>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.grpc</groupId>
+            <artifactId>helidon-grpc-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webserver</groupId>
+            <artifactId>helidon-webserver-grpc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webclient</groupId>
+            <artifactId>helidon-webclient-grpc</artifactId>
+        </dependency>
+        <dependency>
+            <!-- required for @Generated -->
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webserver.testing.junit5</groupId>
+            <artifactId>helidon-webserver-testing-junit5</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.logging</groupId>
+            <artifactId>helidon-logging-jul</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>${version.plugin.os}</version>
+            </extension>
+        </extensions>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-libs</id>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${version.lib.google-protobuf}:exe:${os.detected.classifier}</protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${version.lib.grpc}:exe:${os.detected.classifier}
+                    </pluginArtifact>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

examples/webserver/grpc/src/main/java/io/helidon/examples/webserver/grpc/GrpcMain.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 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.
+ */
+
+package io.helidon.examples.webserver.grpc;
+
+import io.helidon.logging.common.LogConfig;
+import io.helidon.webserver.WebServer;
+import io.helidon.webserver.grpc.GrpcRouting;
+
+class GrpcMain {
+
+    private GrpcMain() {
+    }
+
+    /**
+     * Main method.
+     *
+     * @param args ignored
+     */
+    public static void main(String[] args) {
+        LogConfig.configureRuntime();
+
+        WebServer.builder()
+                .port(8080)
+                .addRouting(GrpcRouting.builder().service(new StringService()))
+                .build()
+                .start();
+    }
+}

examples/webserver/grpc/src/main/java/io/helidon/examples/webserver/grpc/StringService.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 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.
+ */
+
+package io.helidon.examples.webserver.grpc;
+
+import java.util.Locale;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import io.helidon.examples.webserver.grpc.Strings.StringMessage;
+import io.helidon.grpc.core.CollectingObserver;
+import io.helidon.webserver.grpc.GrpcService;
+
+import com.google.protobuf.Descriptors;
+import io.grpc.stub.StreamObserver;
+
+import static io.helidon.grpc.core.ResponseHelper.complete;
+import static io.helidon.grpc.core.ResponseHelper.stream;
+
+class StringService implements GrpcService {
+
+    @Override
+    public Descriptors.FileDescriptor proto() {
+        return Strings.getDescriptor();
+    }
+
+    @Override
+    public void update(Routing router) {
+        router.unary("Upper", this::upper)
+                .unary("Lower", this::lower)
+                .serverStream("Split", this::split)
+                .clientStream("Join", this::join)
+                .bidi("Echo", this::echo);
+    }
+
+    private void upper(StringMessage request, StreamObserver<StringMessage> observer) {
+        String requestText = request.getText();
+        complete(observer, StringMessage.newBuilder()
+                .setText(requestText.toUpperCase(Locale.ROOT))
+                .build());
+    }
+
+    private void lower(StringMessage request, StreamObserver<StringMessage> observer) {
+        String requestText = request.getText();
+        complete(observer, StringMessage.newBuilder()
+                .setText(requestText.toLowerCase(Locale.ROOT))
+                .build());
+    }
+
+    private void split(StringMessage request, StreamObserver<StringMessage> observer) {
+        String[] parts = request.getText().split(" ");
+        stream(observer, Stream.of(parts).map(this::response));
+    }
+
+    private StreamObserver<StringMessage> join(StreamObserver<StringMessage> observer) {
+        return CollectingObserver.create(
+                Collectors.joining(" "),
+                observer,
+                StringMessage::getText,
+                this::response);
+    }
+
+    private StreamObserver<Strings.StringMessage> echo(StreamObserver<Strings.StringMessage> observer) {
+        return new StreamObserver<>() {
+            @Override
+            public void onNext(Strings.StringMessage value) {
+                observer.onNext(value);
+            }
+
+            @Override
+            public void onError(Throwable t) {
+                observer.onError(t);
+            }
+
+            @Override
+            public void onCompleted() {
+                observer.onCompleted();
+            }
+        };
+    }
+
+    private StringMessage response(String text) {
+        return StringMessage.newBuilder().setText(text).build();
+    }
+}

examples/webserver/grpc/src/main/java/io/helidon/examples/webserver/grpc/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 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.
+ */
+
+/**
+ * Example of gRPC in webserver.
+ */
+package io.helidon.examples.webserver.grpc;

examples/webserver/grpc/src/main/proto/strings.proto

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 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.
+ */
+
+
+syntax = "proto3";
+option java_package = "io.helidon.examples.webserver.grpc";
+
+service StringService {
+  rpc Upper (StringMessage) returns (StringMessage) {}
+  rpc Lower (StringMessage) returns (StringMessage) {}
+  rpc Split (StringMessage) returns (stream StringMessage) {}
+  rpc Join (stream StringMessage) returns (StringMessage) {}
+  rpc Echo (stream StringMessage) returns (stream StringMessage) {}
+}
+
+message StringMessage {
+  string text = 1;
+}

examples/webserver/grpc/src/main/resources/application.yaml

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 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.
+#
+
+server:
+  port: 0
+  tls:
+    trust:
+      keystore:
+        passphrase: "password"
+        trust-store: true
+        resource:
+          resource-path: "server.p12"
+    private-key:
+      keystore:
+        passphrase: "password"
+        resource:
+          resource-path: "server.p12"