grpc

What is grpc?

The grpc npm package is a Node.js library for making and handling remote procedure calls (RPC) using the gRPC framework. It allows for efficient communication between services, supports multiple programming languages, and provides features like load balancing, authentication, and more.

What are grpc's main functionalities?

Creating a gRPC Server

This code demonstrates how to create a basic gRPC server in Node.js. It loads a .proto file, defines a service, and starts the server to listen for incoming requests.

const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('path/to/your/protofile.proto', {});
const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const yourService = protoDescriptor.yourService;

function yourFunction(call, callback) {
  callback(null, { message: 'Hello ' + call.request.name });
}

const server = new grpc.Server();
server.addService(yourService.service, { yourFunction: yourFunction });
server.bind('127.0.0.1:50051', grpc.ServerCredentials.createInsecure());
server.start();

Creating a gRPC Client

This code demonstrates how to create a gRPC client in Node.js. It connects to a gRPC server, makes a request, and handles the response.

const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('path/to/your/protofile.proto', {});
const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const yourService = protoDescriptor.yourService;

const client = new yourService('localhost:50051', grpc.credentials.createInsecure());

client.yourFunction({ name: 'World' }, (error, response) => {
  if (!error) {
    console.log('Greeting:', response.message);
  } else {
    console.error(error);
  }
});

Streaming RPC

This code demonstrates how to implement a streaming RPC in a gRPC server. It handles incoming stream data and sends responses back to the client.

const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('path/to/your/protofile.proto', {});
const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const yourService = protoDescriptor.yourService;

function yourStreamFunction(call) {
  call.on('data', (request) => {
    console.log('Received:', request);
    call.write({ message: 'Hello ' + request.name });
  });
  call.on('end', () => {
    call.end();
  });
}

const server = new grpc.Server();
server.addService(yourService.service, { yourStreamFunction: yourStreamFunction });
server.bind('127.0.0.1:50051', grpc.ServerCredentials.createInsecure());
server.start();

Other packages similar to grpc

grpc-web

The grpc-web package allows gRPC to be used in web applications. It provides a JavaScript client library that can communicate with gRPC services from the browser. This package is useful for integrating gRPC with frontend applications, whereas the grpc package is primarily focused on server-side and backend communication.

README

Node.js gRPC Library

This library is now only receiving bug fixes and runtime compatibility updates. In April 2021 it will be deprecated and will no longer receive any updates. We recommend using @grpc/grpc-js instead.

PREREQUISITES

• node: This requires node to be installed, version 4.0 or above. If you instead have the nodejs executable on Debian, you should install the nodejs-legacy package.

• Note: If you installed node via a package manager and the version is still less than 4.0, try directly installing it from nodejs.org.

LATEST VERSIONS SUPPORTED

• Node: 14
• Electron: 11.2

INSTALLATION

Install the gRPC NPM package

npm install grpc

BUILD FROM SOURCE

The following command can be used to build from source when installing the package from npm:

npm install grpc --build-from-source

The --build-from-source option will work even when installing another package that depends on grpc. To build only grpc from source, you can use the argument --build-from-source=grpc.

ABOUT ELECTRON

The official electron documentation recommends to build all of your native packages from source. While the reasons behind this are technically good - many native extensions won't be packaged to work properly with electron - the gRPC source code is fairly difficult to build from source due to its complex nature, and we're also providing working electron pre-built binaries. Therefore, we recommend that you do not follow this model for using gRPC with electron. Also, for the same reason, electron-rebuild will always build from source. We advise you to not use this tool if you are depending on gRPC. Please note that there's not just one way to get native extensions running in electron, and that there's never any silver bullet for anything. The following instructions try to cater about some of the most generic ways, but different edge cases might require different methodologies.

The best way to get gRPC to work with electron is to do this, possibly in the postinstall script of your package.json file:

npm rebuild --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron

Note that the 2.0.0 above is the electron runtime version number. You will need to update this every time you go on a different version of the runtime.

If you have more native dependencies than gRPC, and they work better when built from source, you can explicitely specify which extension to build the following way:

npm rebuild --build-from-source=sqlite3 --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron

This way, if you depend on both grpc and sqlite3, only the sqlite3 package will be rebuilt from source, leaving the grpc package to use its precompiled binaries.

BUILD IN GIT REPOSITORY

1. Clone the grpc-node Git Repository.
2. Run git submodule update --init --recursive from the repository root.
3. Run cd packages/grpc-native-core.
4. Run npm install --build-from-source.

• Note: On Windows, this might fail due to nodejs issue #4932 in which case, you will see something like the following in npm install's output (towards the very beginning):

   ..
   Building the projects in this solution one at a time. To enable parallel build, please add the "/m" switch.
   WINDOWS_BUILD_WARNING
    "..\IMPORTANT: Due to https:\github.com\nodejs\node\issues\4932, to build this library on Windows, you must first remove C:\Users\jenkins\.node-gyp\4.4.0\include\node\openssl"
    ...
    ..
  

  To fix this, you will have to delete the folder C:\Users\<username>\.node-gyp\<node_version>\include\node\openssl and retry npm install

CONFIGURE BINARIES' LOCATION

You can configure the location from which the pre-compiled binaries are downloaded during installation.

npm install --grpc_node_binary_host_mirror=https://your-url.com

Or defining grpc_node_binary_host_mirror in your .npmrc.

API DOCUMENTATION

See the API Documentation.

TESTING

To run the test suite, simply run npm test in the install location.