From df2ee59a9711133ce79dac2fdfe6fb3dd41c159e Mon Sep 17 00:00:00 2001 From: Daniel Fiala Date: Thu, 25 Apr 2024 11:16:05 +0200 Subject: [PATCH] docs(transcoding): added grpc transcoding docs --- docs/src/main/asciidoc/grpc-transcoding.adoc | 166 +++++++++++++++++++ docs/src/main/asciidoc/grpc.adoc | 1 + 2 files changed, 167 insertions(+) create mode 100644 docs/src/main/asciidoc/grpc-transcoding.adoc diff --git a/docs/src/main/asciidoc/grpc-transcoding.adoc b/docs/src/main/asciidoc/grpc-transcoding.adoc new file mode 100644 index 0000000000000..1660f0b1b8a92 --- /dev/null +++ b/docs/src/main/asciidoc/grpc-transcoding.adoc @@ -0,0 +1,166 @@ +//// +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 Transcoding +include::_attributes.adoc[] +:categories: serialization +:summary: This page explains how to enable gRPC Transcoding in your Quarkus application for RESTful interactions with gRPC services. +:topics: grpc, transcoding, rest, json +:extensions: io.quarkus:quarkus-grpc + +gRPC Transcoding lets you expose your gRPC services as RESTful JSON endpoints. +This is particularly useful in these scenarios: + +1. **Client-side limitations:** When you need to interact with gRPC services from environments (like web browsers) that don't directly support gRPC. +2. **Simplified local development:** While services like Google Cloud Run and Google Cloud Endpoints offer built-in gRPC transcoding, replicating this locally often requires setting up a proxy like Envoy. Transcoding directly within your Quarkus application streamlines your development process. + +== Configuring Your Project + +First, add the `quarkus-grpc` extension to your project: + +[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] +.pom.xml +---- + + io.quarkus + quarkus-grpc + +---- + +[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] +.build.gradle +---- +implementation("io.quarkus:quarkus-grpc") +---- + +== Transcoding configuration + +include::{generated-dir}/config/quarkus-grpc-transcoding-config-grpc-transcoding-config.adoc[opts=optional,leveloffset=+1] + +== Example + +Let's imagine you have a gRPC service defined. +Here's an example of a simple service: + +[source,protobuf] +---- +syntax = "proto3"; + +import "google/api/annotations.proto"; //<1> + +option java_multiple_files = true; +option java_package = "examples"; +option java_outer_classname = "HelloWorldProto"; +option objc_class_prefix = "HLW"; + +package helloworld; + +// The greeting service definition. +service Greeter { + // RPC with simple path + rpc SimplePath (HelloRequest) returns (HelloReply) { + option (google.api.http) = { //<2> + post: "/v1/simple" + body: "*" + }; + } +} + +message HelloRequest { + string name = 1; +} + +message HelloReply { + string message = 1; +} +---- + +<1> We need to import the `google/api/annotations.proto` file so that we can use the `google.api.http` option. +<2> This option is used to define the RESTful path for the gRPC service. + +Now we need to implement the service: + +[source,java] +---- +@GrpcService +public class HelloWorldNewService implements Greeter { + + @Override + public Uni simplePath(HelloRequest request) { + return Uni.createFrom().item(HelloReply.newBuilder().setMessage("Hello " + request.getName()).build()); + } +} +---- + +To enable gRPC Transcoding, you need to add the following configuration to your `application.properties` file: + +[source,properties] +---- +quarkus.grpc.transcoding.enabled=true +---- + +Now you can access the gRPC service through a RESTful JSON interface. +For example, you can use the following `curl` command: + +[source,shell] +---- +curl -X POST http://localhost:8080/v1/simple -H "Content-Type: application/json" -d '{"name": "World"}' +---- + +This command should return response similar to the following: + +[source,json] +---- +{ + "message": "Hello World" +} +---- + +== Advanced Usage + +While the above example demonstrates a simple use case, gRPC Transcoding can be configured in more complex scenarios. +For example, you can define paths with variables, query parameters, and more. + +For example you can define methods with path variables: + +[source,protobuf] +---- +service Greeter { + rpc PathWithVariable (HelloRequest) returns (HelloReply) { + option (google.api.http) = { + post: "/v1/path/{name}" //<1> + body: "*" + }; + } +} + +message HelloRequest { + string name = 1; //<2> +} +---- + +<1> The path variable is defined using curly braces. +<2> The `name` field is used to define the path variable. + +Now if you send a request to the `/v1/path/World` path, like this: + +[source,shell] +---- +curl -X POST http://localhost:8080/v1/path/World +---- + +You should receive a response similar to the following: + +[source,json] +---- +{ + "message": "Hello World" +} +---- + +**Important Notes:** + +* You also should consult https://cloud.google.com/endpoints/docs/grpc/transcoding[google's documentation on gRPC transcoding] for more information. +* Consider whether you need a proxy like Envoy for advanced transcoding and routing. diff --git a/docs/src/main/asciidoc/grpc.adoc b/docs/src/main/asciidoc/grpc.adoc index d0a7abe6bb151..804ad34c42d43 100644 --- a/docs/src/main/asciidoc/grpc.adoc +++ b/docs/src/main/asciidoc/grpc.adoc @@ -34,5 +34,6 @@ Quarkus gRPC is based on https://vertx.io/docs/vertx-grpc/java/[Vert.x gRPC]. * xref:grpc-service-consumption.adoc[Consuming a gRPC Service] * xref:grpc-kubernetes.adoc[Deploying your gRPC Service in Kubernetes] * xref:grpc-xds.adoc[Enabling xDS gRPC support] +* xref:grpc-transcoding.adoc[Enabling gRPC transcoding support] * xref:grpc-generation-reference.adoc[gRPC code generation reference guide] * xref:grpc-reference.adoc[gRPC reference guide]