From f33f4483e66ea966a285d57d40d22001477c8a48 Mon Sep 17 00:00:00 2001
From: Yuri Shkuro <github@ysh.us>
Date: Thu, 28 Dec 2023 00:16:47 -0500
Subject: [PATCH] Add grpc-gateway helper types

Signed-off-by: Yuri Shkuro <github@ysh.us>
---
 Makefile                         |  2 +-
 proto/api_v3/query_service.proto | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 459f427..3624dcf 100644
--- a/Makefile
+++ b/Makefile
@@ -11,7 +11,7 @@ PROTOTOOL_VER=1.8.0
 PROTOTOOL_IMAGE=uber/prototool:$(PROTOTOOL_VER)
 PROTOTOOL=docker run --rm -u ${shell id -u} -v "${PWD}:/go/src/${PROJECT_ROOT}" -w /go/src/${PROJECT_ROOT} $(PROTOTOOL_IMAGE)
 
-PROTOC_VER=0.4.0
+PROTOC_VER=0.5.0
 PROTOC_IMAGE=jaegertracing/protobuf:$(PROTOC_VER)
 PROTOC=docker run --rm -u ${shell id -u} -v "${PWD}:${PWD}" -w ${PWD} ${PROTOC_IMAGE} --proto_path=${PWD}
 
diff --git a/proto/api_v3/query_service.proto b/proto/api_v3/query_service.proto
index b809e94..8a3b0b4 100644
--- a/proto/api_v3/query_service.proto
+++ b/proto/api_v3/query_service.proto
@@ -130,3 +130,30 @@ service QueryService {
   // GetOperations returns operation names.
   rpc GetOperations(GetOperationsRequest) returns (GetOperationsResponse) {}
 }
+
+// Below are some helper types when using APIv3 via HTTP endpoints implemented via grpc-gateway.
+
+// GRPCGatewayError is the type returned when GRPC server returns an error.
+// Note that for streaming responses it would be wrapped in GRPCGatewayWrapper below.
+// Example: {"error":{"grpcCode":2,"httpCode":500,"message":"...","httpStatus":"text..."}}.
+message GRPCGatewayError {
+  message GRPCGatewayErrorDetails {
+    int32 grpcCode = 1;
+    int32 httpCode = 2;
+    string message = 3;
+    string httpStatus = 4;
+  }
+
+  GRPCGatewayErrorDetails error = 1;
+}
+
+// GRPCGatewayWrapper is a type returned when GRPC service returns a stream.
+// For some unknown reason grpc-gateway/v1 wraps chunk responses in {"result": {actual output}}.
+// See https://github.com/grpc-ecosystem/grpc-gateway/issues/2189
+// TODO: it's not clear what happens when the server returns more than one chunk.
+//       The gateway will presumably combine then into a single HTTP response.
+//       Currently this is not possible because even though APIv3 GRPC Service is using output stream,
+//       its implementation reads all spans from QueryService at once and forms only a single chunk.
+message GRPCGatewayWrapper {
+  SpansResponseChunk result = 1;
+}