Local Run

This guide gets you started with gRPC Mate with a simple working example.

Prerequisites

Make sure Server Reflection is enabled on gRPC target server side.

• For server written in Java, refer to this guide

• For server written in Go, refer to this guide

For demonstration, we start the gRPC example server with reflection enabled provided at https://github.com/grpc/grpc-go/tree/master/examples/features/reflection

$ go run server/main.go
server listening at [::]:50051

Run gRPC Mate

It’s really simple to run. Let’s connect to the gRPC server started above as an example, using docker or command built from source.

Run gRPC Mate via Docker

$ docker run --name grpc-mate -e GRPC_MATE_PROXIED_HOST=<your grpc server local IP> -e GRPC_MATE_PROXIED_PORT=50051 -dp 6600:6600 gdong42/grpc-mate:0.2

Note above GRPC_MATE_PROXIED_HOST has to be set to your IP address other than localhost, so that grpc-mate running inside docker can access it.

The 0.2 and latest images support linux/amd64 and linux/arm64.

Run gRPC Mate directly

$ GRPC_MATE_PROXIED_PORT=50051 ./grpc-mate

This by default listens on 6600 as HTTP port, and connects to a local gRPC server running at localhost:50051

For another host, port, or TLS-enabled backend, see Configuration.

Introspecting Services

Now try get http://localhost:6600/actuator/services, you will see all services the server exposes, as well as their enclosing methods, input and output types, e.g. one element of services:

      {  
         "name":"helloworld.Greeter",
         "methods":[  
            {  
               "name":"SayHello",
               "input":"helloworld.HelloRequest",
               "output":"helloworld.HelloReply",
               "route":"/helloworld.Greeter/SayHello"
            }
         ]
      }

It also has request/response JSON templates, convenient for construcing HTTP and JSON requests, e.g. one element of types:

      {  
         "name":"helloworld.HelloRequest",
         "template":{  
            "name":""
         }
      }

Filter /actuator/services by exact, case-sensitive service or method name:

• /actuator/services?name=helloworld.Greeter
• /actuator/services?method=SayHello
• /actuator/services?name=helloworld.Greeter&method=SayHello

Both filters must match when combined. The response includes only matching methods and their input/output templates; shared types appear once. No match returns {"services":[],"types":[]} with HTTP 200. Missing or empty filters match everything.

Making Requests

Now let’s try making gRPC requests using above inspected information

$ curl -X POST -d '{"name":"gdong42"}' "http://localhost:6600/v1/helloworld.Greeter/SayHello" 
{"message":"Hello gdong42"}

Above we invoked SayHello method of helloworld.Greeter service, with JSON message of helloworld.HelloRequest type, and got a JSON message of helloworld.HelloReply type.

Note the HTTP method is POST, the body is a JSON string, and the request path is of pattern /v1/{serviceName}/{methodName}.

Errors and limitations

If upstream reflection is unimplemented, RPC requests and /actuator/services return HTTP 502 with guidance to enable it. A gRPC ResourceExhausted error returns HTTP 429.

gRPC Mate currently supports unary calls only.