Initial gRPC CLI

quarkusio · Jul 17, 2024 · c213eb8 · c213eb8
1 parent da74db3
commit c213eb8
Show file tree

Hide file tree

Showing 23 changed files with 894 additions and 5 deletions.
diff --git a/bom/application/pom.xml b/bom/application/pom.xml
@@ -2170,6 +2170,11 @@
                 <artifactId>quarkus-grpc-stubs</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-grpc-reflection</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
                 <artifactId>quarkus-grpc-deployment</artifactId>

diff --git a/docs/src/main/asciidoc/grpc-cli.adoc b/docs/src/main/asciidoc/grpc-cli.adoc
@@ -0,0 +1,129 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Using gRPC CLI
+include::_attributes.adoc[]
+:categories: serialization
+:summary: This page explains how to use gRPC CLI.
+:topics: grpc,cli
+:extensions: io.quarkus:quarkus-grpc-cli
+
+This page explains how to use gRPC CLI -- a grpcurl-like tool.
+
+See basic Quarkus CLI usage first:
+
+* xref:cli-tooling.adoc[CLI tooling]
+
+== Examples
+
+Display gRPC CLI help:
+
+[source,shell]
+----
+quarkus grpc
+Usage: grpc [-h] [COMMAND]
+  -h, --help   Display this help message.
+Commands:
+  list      grpc list
+  describe  grpc describe
+  invoke    grpc invoke
+----
+
+List all available gRPC services:
+
+[source,shell]
+----
+quarkus grpc list localhost:8080
+
+helloworld.Greeter
+grpc.health.v1.Health
+----
+
+Describe a service:
+
+[source,shell]
+----
+quarkus grpc describe localhost:8080 helloworld.Greeter
+
+{
+  "name": "helloworld.proto",
+  "package": "helloworld",
+  "dependency": ["google/protobuf/empty.proto"],
+  "messageType": [{
+    "name": "HelloRequest",
+    "field": [{
+      "name": "name",
+      "number": 1,
+      "label": "LABEL_OPTIONAL",
+      "type": "TYPE_STRING"
+    }]
+  }, {
+    "name": "HelloReply",
+    "field": [{
+      "name": "message",
+      "number": 1,
+      "label": "LABEL_OPTIONAL",
+      "type": "TYPE_STRING"
+    }]
+  }],
+  "service": [{
+    "name": "Greeter",
+    "method": [{
+      "name": "SayHello",
+      "inputType": ".helloworld.HelloRequest",
+      "outputType": ".helloworld.HelloReply",
+      "options": {
+      }
+    }, {
+      "name": "SayJo",
+      "inputType": ".google.protobuf.Empty",
+      "outputType": ".helloworld.HelloReply",
+      "options": {
+      }
+    }, {
+      "name": "ThreadName",
+      "inputType": ".helloworld.HelloRequest",
+      "outputType": ".helloworld.HelloReply",
+      "options": {
+      }
+    }]
+  }],
+  "options": {
+    "javaPackage": "examples",
+    "javaOuterClassname": "HelloWorldProto",
+    "javaMultipleFiles": true,
+    "objcClassPrefix": "HLW"
+  },
+  "syntax": "proto3"
+}
+{
+  "name": "google/protobuf/empty.proto",
+  "package": "google.protobuf",
+  "messageType": [{
+    "name": "Empty"
+  }],
+  "options": {
+    "javaPackage": "com.google.protobuf",
+    "javaOuterClassname": "EmptyProto",
+    "javaMultipleFiles": true,
+    "goPackage": "google.golang.org/protobuf/types/known/emptypb",
+    "ccEnableArenas": true,
+    "objcClassPrefix": "GPB",
+    "csharpNamespace": "Google.Protobuf.WellKnownTypes"
+  },
+  "syntax": "proto3"
+}
+----
+
+Invoke a service method:
+
+[source,shell]
+----
+quarkus grpc invoke localhost:8080 helloworld.Greeter/SayHello -d '{"name" : "gRPC"}'
+
+{
+  "message": "Hello gRPC"
+}
+----
diff --git a/docs/src/main/asciidoc/grpc.adoc b/docs/src/main/asciidoc/grpc.adoc
@@ -36,3 +36,4 @@ Quarkus gRPC is based on https://vertx.io/docs/vertx-grpc/java/[Vert.x gRPC].
 * xref:grpc-xds.adoc[Enabling xDS gRPC support]
 * xref:grpc-generation-reference.adoc[gRPC code generation reference guide]
 * xref:grpc-reference.adoc[gRPC reference guide]
+* xref:grpc-cli.adoc[gRPC CLI support]
diff --git a/extensions/grpc/cli/pom.xml b/extensions/grpc/cli/pom.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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>
+        <artifactId>quarkus-grpc-parent</artifactId>
+        <groupId>io.quarkus</groupId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>quarkus-grpc-cli</artifactId>
+    <name>Quarkus - gRPC - CLI</name>
+    <description>gRPC CLI</description>
+
+    <properties>
+        <main.class>io.quarkus.grpc.cli.GrpcCommand</main.class>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.vertx</groupId>
+            <artifactId>vertx-grpc-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java-util</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-grpc-reflection</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-core-deployment</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-picocli</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-arc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-junit5</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-grpc</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- Minimal test dependencies to *-deployment artifacts for consistent build order -->
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-grpc-deployment</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>build</goal>
+                            <goal>generate-code</goal>
+                            <goal>generate-code-tests</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <compilerArgs>
+                        <arg>-parameters</arg>
+                    </compilerArgs>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <systemPropertyVariables>
+                        <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
+                        <maven.home>${maven.home}</maven.home>
+                    </systemPropertyVariables>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-assembly-plugin</artifactId>
+
+                <configuration>
+                    <descriptorRefs>
+                        <descriptorRef>jar-with-dependencies</descriptorRef>
+                    </descriptorRefs>
+                    <finalName>${project.artifactId}-${project.version}</finalName>
+                    <appendAssemblyId>false</appendAssemblyId>
+                    <archive>
+                        <manifest>
+                            <addClasspath>true</addClasspath>
+                            <mainClass>${main.class}</mainClass>
+                        </manifest>
+                    </archive>
+                </configuration>
+
+                <executions>
+                    <execution>
+                        <id>make-assembly</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>single</goal>
+                        </goals>
+                    </execution>
+                </executions>
+
+            </plugin>
+        </plugins>
+    </build>
+</project>
diff --git a/extensions/grpc/cli/src/main/java/io/quarkus/grpc/cli/DescribeCommand.java b/extensions/grpc/cli/src/main/java/io/quarkus/grpc/cli/DescribeCommand.java
@@ -0,0 +1,44 @@
+package io.quarkus.grpc.cli;
+
+import java.util.List;
+
+import com.google.protobuf.ByteString;
+import com.google.protobuf.DescriptorProtos;
+import com.google.protobuf.util.JsonFormat;
+
+import io.grpc.reflection.v1.MutinyServerReflectionGrpc;
+import io.grpc.reflection.v1.ServerReflectionRequest;
+import io.grpc.reflection.v1.ServerReflectionResponse;
+import io.smallrye.mutiny.Multi;
+import picocli.CommandLine;
+
+@CommandLine.Command(name = "describe", sortOptions = false, header = "gRPC describe")
+public class DescribeCommand extends GcurlBaseCommand {
+
+    public String getAction() {
+        return "describe";
+    }
+
+    @Override
+    protected void execute(MutinyServerReflectionGrpc.MutinyServerReflectionStub stub) {
+        ServerReflectionRequest request = ServerReflectionRequest
+                .newBuilder()
+                .setFileContainingSymbol(unmatched.get(1))
+                .build();
+        Multi<ServerReflectionResponse> response = stub.serverReflectionInfo(Multi.createFrom().item(request));
+        response.toUni().map(r -> {
+            List<ByteString> list = r.getFileDescriptorResponse().getFileDescriptorProtoList();
+            for (ByteString bs : list) {
+                try {
+                    DescriptorProtos.FileDescriptorProto fdp = DescriptorProtos.FileDescriptorProto.parseFrom(bs);
+                    log(JsonFormat.printer().print(fdp));
+                } catch (RuntimeException e) {
+                    throw e;
+                } catch (Exception e) {
+                    throw new RuntimeException(e);
+                }
+            }
+            return null;
+        }).await().indefinitely();
+    }
+}