Add grpc-gateway helper types (#102)

Signed-off-by: Yuri Shkuro <github@ysh.us>

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}
 

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;
+}