Menu

Subscribe

grpcc: A simple CLI for gRPC services

on grpc, node.js, grpcc

Recently, I've been using gRPC more and more when writing backend services and have loved working with it's stricter API definitions, nicer error handling, and type-checking. I also love how easy it is to communicate with services written in different languages with minimal boilerplate.

At this point, I'd almost always choose gRPC over REST for these kinds of services (at least for what I do, your use cases may vary), however there is one thing I really miss from working with REST services: running requests via curl or in Postman to test or debug APIs.

I went out looking for something similar for gRPC services but came up short. There are references to tools like grpc_cli, but they seem like way too much work to get started, and not quite what I had in mind in any case.

What I wanted was something that could sit in a tmux pane ready for me to run and re-run requests until I was happy with the outcome. Something easy to use for debugging too, and ideally without having to think too much about crafting request arguments or remembering reply schemas. And, most importantly, something that could work with any gRPC service, rather than a specific one.

The node.js REPL seemed perfect for the UX, it could easily do all these things and meant that args/replies would just be Javascript objects, and it could handle the more complex gRPC streaming APIs pretty easily via EventEmitters.

However, it needed to be super-charged with gRPC powers. And so, with some reading of the gRPC node bindings & a quick look at the node.js REPL docs, I put together grpcc:

The grpcc CLI

The image above shows grpcc being used to communicate with the Skizze database (written in Go) via it's protobuf file.

Installation and Usage

grpcc is easy to install via npm:

$ npm install -g grpcc

With [grpcc](https://github.com/njpatel/grpcc) installed, you can create a flexible client for any gRPC service by just pointing it to the `protobuf` file describing the service, and giving it the address of the service: 
$ grpcc --proto ./service/myservice.proto --address 127.0.0.1:3466

Once `grpcc` is started, it will inspect the `protobuf` file, print out some usage instructions, attach a `client` global to the REPL, as well as a convenient `printReply` global function for simple RPC calls. The `client` object will attempt to connect to the service asynchronously (and can handle disconnects, thanks to the excellent underlying gRPC library).

At the prompt, you can start executing calls on the client by simply sending in the arguments as a Javacript objects, and a standard callback of type function(Error, Object). Streaming calls are also supported, see the project page for more info.

Upcoming Features

I didn't have a chance to implement all the features I'd have liked for the first version (as is always the case!), but here's what I'm looking to add soon (feel free to submit a PR!):

  • REPL history between sessions
  • Nicer API for streaming (all types), e.g. a function wrapper that listens to the events and pretty prints
  • Easily reload the client when protobuf file changes
  • Intercept more known error messages from gRPC bindings and pretty-print them

Having grpcc has made working with gRPC services much easier for me day-to-day, and so I hope grpcc is useful for others too. I'd love to hear feedback, so feel free to file bugs/feature-requests on the Issues page.

More information about installation, usage, and upcoming features are available on the project's Github page, so Check It Out!