NodeJS gRPC Code Reference

While working at Indeed, I did a fair amount with gRPC. I became rather familiar with the Java, Go, NodeJS, and python implementations. During my vacation between jobs, I decided to revisit one of my old projects and try to migrate it to using gRPC. By doing so, I would be able to support a larger variety of request types (streaming, non-streaming, etc). When I started to look for good NodeJS code samples or reference implementations, I was rather disappointed with what I found. Many of the ones I could get my hands on only demonstrated unary methods and not any of the streaming API’s. After a lot of time digging through source and a few implementations online, I finally assembled a good reference.

In this post, I only wanted to detail what the method calls look like on both ends of the wire. There are some additional best practices that should be taken into consideration, but I do not plan on covering those here.

Protocol Buffers Definition

message Request {
}

message Response {
}

service MyService {
    rpc unaryMethod(Request) returns (Response);
    rpc clientStreamingMethod(stream Request) returns (Response);
    rpc serverStreamingMethod(Request) returns (stream Response);
    rpc bidirectionalStreamingMethod(stream Request) returns (stream Response);
}

Service Implementation

const grpc = require('grpc');
const MyServiceGrpc = grpc.load(require.resolve('./MyService.proto'));

class MyServiceImpl {
    unaryMethod(call, callback) {
        const request = call.request;
        // handle request
        callback('error', response);
    }
    
    clientStreamingMethod(call, callback) {
        call.on('data', (request) => {
            // handle request
        });
        
        call.on('end', () => {
            callback(response);
        });
    }
    
    serverStreamingMethod(call) {
        const request = call.request;
        
        // call N times
        call.write(response);
        
        // call once
        call.end();
    }
    
    bidirectionalStreamingMethod(call) {
        call.on('data', (request) => {
            // handle request
            call.write(response);
        });
        
        call.on('end', () => {
            call.end();
        });
    }
}

const server = new grpc.Server();
server.addService(MyServiceGrpc.MyService.service, new MyServiceImpl());
server.bind('0.0.0.0:1234', grpc.ServerCredentials.createInsecure());
server.start();

Client Usage

const grpc = require('grpc');
const MyServiceGrpc = grpc.load(require.resolve('./MyService.proto'));

const credentials = grpc.credentials.createInsecure();
const client = new MyServiceGrpc.MyService('0.0.0.0:1234', credentials);
const md = new grpc.Metadata();

// unary
client.unaryMethod(request, md, (err, response) => {
    if (err) {
        // handle err
    } else {
        // handle response
    }
});

// client streaming
{
    const call = client.clientStreamingMethod(md, (err, response) => {
        if (err) {
            // handle err
        } else {
            // handle response
        }
    });
    
    // call N times
    call.write(request);
    
    // call once
    call.end();
}

// server streaming
{
    const call = client.serverStreamingMethod(request, md);
    
    call.on('data', (response) => {
        // handle response
    });
    
    call.on('end', () => {
        // handle end of server
    });
}

// bidirectional streaming
{
    const call = client.bidirectionalStreamingMethod(md);
    
    call.on('data', (response) => {
        // handle response
    });
    
    call.on('end', () => {
        // handle end of server
    });
    
    // call N times
    call.write(request);
    
    // call once
    call.end();
}

Other Points of Reference

Code in grpc/grpc-node

Source code is always a great point of reference. gRPC has several good integration tests where you can see some of these approaches being used.