grpc.md

gRPC

Back to README.md

The prototool grpc command calls a gRPC endpoint using a JSON input. What this does behind the scenes:

• Compiles your Protobuf files with protoc, generating a FileDescriptorSet.
• Uses the FileDescriptorSet to figure out the request and response type for the endpoint, and to convert the JSON input to binary.
• Calls the gRPC endpoint.
• Uses the FileDescriptorSet to convert the resulting binary back to JSON, and prints it out for you.

The overhead for a file with four dependencies is about 30ms.

Example

There is a full example for gRPC in the example directory. Run make example to make sure everything is installed and generated.

Start the example server in a separate terminal by doing go run example/cmd/excited/main.go.

prototool grpc [dirOrFile] --address serverAddress --method package.service/Method --data 'requestData'

Either use --data 'requestData' as the the JSON data to input, or --stdin which will result in the input being read from stdin as JSON.

$ make example # make sure everything is built just in case
$ go run example/cmd/excited/main.go # run in another terminal

$ prototool grpc example \
  --address 0.0.0.0:8080 \
  --method uber.foo.v1.ExcitedAPI/Exclamation \
  --data '{"value":"hello"}'
{"value": "hello!"}

$ prototool grpc example \
  --address 0.0.0.0:8080 \
  --method uber.foo.v1.ExcitedAPI/ExclamationServerStream \
  --data '{"value":"hello"}'
{"value": "h"}
{"value": "e"}
{"value": "l"}
{"value": "l"}
{"value": "o"}
{"value": "!"}

$ cat input.json
{"value":"hello"}
{"value":"salutations"}

$ cat input.json | prototool grpc example \
  --address 0.0.0.0:8080 \
  --method uber.foo.v1.ExcitedAPI/ExclamationClientStream \
  --stdin
{"value": "hellosalutations!"}

$ cat input.json | prototool grpc example \
  --address 0.0.0.0:8080 \
  --method uber.foo.v1.ExcitedAPI/ExclamationBidiStream \
  --stdin
{"value": "hello!"}
{"value": "salutations!"}

$ prototool grpc example \
  --address 0.0.0.0:8080 \
  --method uber.foo.v1.ExcitedAPI/ExclamationServerStream \
  --data '{"value":"hello"}' \
  --details
{"headers":{"content-type":["application/grpc"]}}
{"response":{"value":"h"}}
{"response":{"value":"e"}}
{"response":{"value":"l"}}
{"response":{"value":"l"}}
{"response":{"value":"o"}}
{"response":{"value":"!"}}

TLS Connections

To enable TLS connections to the server, use the --tls command line flag.

If not specified, setting any of the following flags will produce an error.

The following flags mirror the flags of the same names from from the curl command line tool.

By default host validation is enabled. To disable, pass the --insecure command line flag. If using this tool in any a production setting (which is not recommended to begin with), it is HIGHLY recommended not to use the --insecure flag as it allows for multiple network exploits.

If --insecure is specified, setting any of the following flags will produce an error.

If the certificate presented by the server is not generated by a system trusted CA, you must also set the --cacert flag to a pem encoded file of the CA public certificate that generated the server certificate or the server public certificate itself. The cacert file may contain multiple certificates or certificate authorities appended together (new line separated). You must also include any intermediary certificates if required to validate the server certificate against the given CA certificate (generally only true in commercially generated certificates, not self signed ones).

By default, the "Common Name" (and any "Subject Alternative Names") will be used to validate the authenticity of the server connection based upon the --address specified. If your server certificate's common name does not match the address you are accessing it from (for example, if your address is an IP address), pass --server-name command line flag with the value expected in the "Common Name" field of the server certificate.

To use mutual TLS with a client key and certificate, pass the --key and --cert command line flag to the path of the files in pem format. If one is specified the other must also be specified. Unlike curl, you cannot pass a file with the key and cert concatenated together as the --cert flag. Also unlike curl, you cannot pass the -E flag as an alias for the --cert flag.

$ prototool grpc path/to/root \
  --address 192.168.1.15:443 \
  --method uber.foo.v1.BarAPI/Baz \
  --data '{"value":"hello"}' \
  --tls \
  --cacert server.crt \
  --cert client.crt \
  --key client.key \
  --server-name foo.bar.com