Profile picture of Justin Capalbo

Staff Engineer

Justin Capalbo

In this post, I'll cover the "why" of gRPC, the structure of protobuf files, and some of the Typescript interop offered by two NodeJS packages for gRPC: 

This post assumes some familiarity with microservice architecture and RESTful API calls. With all APIs, including the well known REST and SOAP flavors, there are two players:

A deep discussion on the "how" and "why" of RESTful microservices (statelessness, etc.) is best left for another post. Instead, we'll dive into gRPC, an alternative to REST and SOAP that's been gaining some traction recently. gRPC is another protocol for two back-end services can use to communicate that confers some unique advantages.

gRPC is an efficient means of service to service communication and is an alternative to REST and SOAP. gRPC sends messages over HTTP/2 using a binary serialization standard called protocol buffers. Google initially released the gRPC serialization standard in 2016. Protocol buffers are often referred to in the shorthand "protobufs". 

RPC is a ubiquitous term that stands for "Remote Procedure Call", a fancy way of saying that we want to run some code on another machine. The "g" doesn't actually stand for "Google", even though they created and continue to maintain gRPC. They use the letter G to name releases, such as version 1.12, 

Like any HTTP request made with a library like Axios/Fetch in Node or HttpClient in .NET, gRPC is language agnostic. As such, clients needn't concern themselves over the implementation details of the API on the server. Rather, they need only be aware that the gRPC service exists to serve the request, as well as the name and shape of the request and response.

gRPC comes with a couple of advantages, or rather, use cases in which it might be preferable to REST.

Now that we know a little more about what gRPC is and when we might consider it for a project, let's dive into an example using Typescript.

"Hello, World" for the tiny gRPC service we'll build starts with our service definition. Whatever language our caller or server are using isn't really important just yet. Google maintains reference 

 for protocol buffer version 3, the newest production-ready version of the syntax. In our contract, we want a single function that accepts a 

// greeter_service.proto

syntax = "proto3";

package greeter_service;

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

Pretty straightforward, but let's break this down.

syntax = "proto3";

package greeter_service;

You'll see something like this at the top of most protobufs. 

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

 methods/functions that some service must provide, as well as the types of the request and response messages. A single .proto file can contain multiple logical  

 keywords, and a single service can have as many 

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

 keyword specifies the shape of the messages that will be passed back and forth. It's possible to nest messages, just like nesting objects in JSON. Arrays are there as well. This allows for some pretty robust messages with structures that everyone who's used to JSON should be familiar with.

The only thing that should stand out as a little unusual here are the things that look like assignment operators (=) with a number after them. These numbers specify the 

 for each field in the message. This is the order in which the binary data will be arranged before the messages are transmitted. Having a mismatched field order between client and server 

 cause errors, or might not. Imagine having two string fields with mismatched field order. The server would just see two strings, but we might end up with data from the 

 field on the server! Quite tricky to debug. 

Now that we've got a protobuf definition, let's build a Typescript service that can handle the request. I ran a few commands to set up my dependencies in a brand new Node project.

For this project, we start with an empty npm package that I've called 

. The project consists solely of the following:

npm i @grpc/grpc-js @grpc/proto-loader ts-node

npm i --save-dev rimraf typescript ts-node-dev

Of these, the two gRPC packages and rimraf will be part of our build workflow. We'll also need a couple of scripts:

"scripts": {
  "dev": "tsnd --transpile-only --ignore-watch node_modules ./src/main.ts",
  "generate": "rimraf ./proto && proto-loader-gen-types --longs=String --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --outDir=proto greeter_service.proto"
}

 will generate the types necessary for us to write code for our handler and server setup. 

 script looks a little daunting, but that's largely due to the number of 

 folder at the project root that consists of several helper types. Since we added 

 to .gitignore, we won't source control this folder. Furthermore, any time our protobuf definition changes, we can simply run the script again.

A handler refers to a function on the server that will be invoked whenever a client calls a given RPC. The handler's job is to accept the request message specified in the protobuf, and provide the required response message. For our simple case, we'll need a Greet function that accepts an object with 

 properties, that returns an object consisting of a single 

With Typescript, we can use the generated type 

 to specify what the shape of our handler (a Javascript object) should look like:

// ./src/greeter.handler.ts

import { GreeterServiceHandlers } from "../proto/greeter_service/GreeterService";

export const greeterHandler: GreeterServiceHandlers = {
	Greet: (call, callback) => {
		const { name, location } = call.request;
		callback(null, {
			greeting: `Hello, ${name}, how is the weather in ${location}?`,
		});
	},
}


When the handler is invoked, the request data is available on the 

 function is used to "return" the response to the client, in lieu of the return statement you'd typically see in an Express REST API. The first parameter in 

 is reserved for an error, if the server happens to catch an Exception and wants to report it back to the caller. If we had more than one RPC in our protobuf, we'd just implement them as siblings of 

Finally, we're ready to start the server by writing the implementation for 

// ./src/main.ts (Server project)

import { Server, ServerCredentials } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { loadPackageDefinition } from "@grpc/grpc-js";
import { ProtoGrpcType } from "../proto/greeter_service";
import { greeterHandler } from "./greeter.handler";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);
grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});


There's a lot to unpack here, but the actual code is only around 6-8 lines long.

// Loading the service definition from the protobuf
const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

 function, which constructs a utility object for us based on the service definition that it parses from the specified .proto file. We'll use this in a bit.

// Construct the server and add the Greeter Service, mapping greeterHandler 
const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);

 helper object by adding the GreeterService to our gRPC server. Importantly, this step is where we set up the mapping between the gRPC service and the handler that we created earlier to handle requests to this service.

grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});

Lastly, we start the service using 0.0.0.0:50051 as an alias for localhost, port 50051. When using SSL on a production server, 

, but this will suffice for dev work. In the callback, we show a helpful message and finally start the server.

 on our server, we'll be able to make Greet requests to the handler using any gRPC client like 

. To finish the example, though, let's create a new project and make our own client using Typescript.

For the initial setup, I created an npm package called 

and performed the following initial setup steps: 

 to generate types, just like on the server!

Your client might end up becoming an Express service, a GraphQL service, a serverless function deployed in Azure/AWS, or a CRON job. As such, I'll show the bare minimum code necessary to get a response from the Greeter Service. The rest is left as an exercise for the reader. We'll do our client implementation in 

// ./src/main.ts (Client project)

import { credentials, loadPackageDefinition } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { ProtoGrpcType } from "../proto/greeter_service";
import { GreetRequest } from "../proto/greeter_service/GreetRequest";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

const greetRequest: GreetRequest = {
	name: "Justin",
	location: "MA",
};

greeterClient.Greet(greetRequest, (err, response) => {
	if (err) {
		console.error(err);
	} else {
		console.log(response.greeting);
	}
});

We can break this into a couple of distinct parts.

// Create the client 
const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

Much like server creation, we load the package definition for the Greeter Service from the protobuf. This time though, we use this definition to construct a client object instead. After specifying our server's address and our credentials, we're now ready to make requests.

// Create the request object
const greetRequest: GreetRequest = {
	name: "Justin",
	location: "MA",
};

// Invoke the RPC "Greet"
greeterClient.Greet(greetRequest, (err, response) => {
	if (err) {
		console.error(err);
	} else {
		console.log(response.greeting);
	}
});

 type, it's easy to make sure that our request is structured properly. From there, it's as simple as calling 

 on the client, and handling the response in the callback.  As long as the server is running, the output of this code is:

'Hello, Justin, how is the weather in MA?'

When you're used to working with Promises and async functions, you can Promisify this code with a wrapper function, like so:

// ./src/main.ts

import { credentials, loadPackageDefinition } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { ProtoGrpcType } from "../proto/greeter_service";
import { GreetRequest } from "../proto/greeter_service/GreetRequest";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

const start = async () => {
	const greetRequest: GreetRequest = {
		name: "Justin",
		location: "MA",
	};
	const response = await greet(greetRequest);
	console.log(response);
}

const greet = (request: GreetRequest): Promise<GreetResponse> => {
	return new Promise((resolve, reject) => {
		greeterClient.Greet(request, (err, response) => {
			if (err) {
				reject(err);
			} else {
				resolve(response);
			}
		});
	});
}

start();


The amended version is a little simpler to work with when you're already deep inside a stack of async functions, possibly making other API calls using 

As with any technology, keep a few things in mind when considering gRPC as an addition to your architecture.

That last point kind of snuck in there, since the same caveats apply to RESTful API design. But it's important to keep in mind that the benefits of gRPC can't outweigh risky design decisions from the outset. "If you've got a hammer, everything looks like a nail" is true more often than we'd sometimes like to admit.

If you map out your service-to-service calls and they resemble this picture, you probably have some tech debt to pay down.

At Go Ahead Tours Engineering, gRPC has been our go-to choice of protocol when we happen to have need of service to service communication. 

gRPC can be a powerful REST or SOAP replacement if your use case calls for it. The strictness prescribed by protobufs can be a bit of a paradigm shift, but can also encourage good habits and a cleaner architecture. Like any technology, it's important to make sure that you aren't using gRPC as a solution in search of a problem. Take a step back from your use case and observe carefully. The speed and type safety offered by gRPC may be just what the doctor ordered!

 source code on Github. Not production ready!

gRPC Client Server Diagram

When developing  an API, we very often reach for REST.  In some cases, however, we can instead take advantage of a structured and speedy standard called gRPC.

Justin Capalbo

gRPC Services with a Type Generation Example for NodeJS and Typescript