dorusu v0.5.0

Dorusu-js - gRPC for Node.js in javascript

This is not an official Google project.

The official Google-maintained implementation of gRPC for node.js is available at grpc-nodejs. Note that Google only maintains one offical implementation of gRPC in any programming language - all the official support for nodejs is focused on grpc-nodejs.

This is an alternate implementation written in javascript by a Googler. It

• interoperates successfully with the official gRPC implementations, i.e it implements the gRPC spec and passes all the core gRPC interop tests

• has an incompatible API surface to grpc-nodejs, for reasons explained in the DESIGN SUMMARY.

  • There is a meta issue that triages other issues that will explain the differences via code snippets.

  • This meta issue will also be used to triage the impact that not being able use dorusu-js as a drop-in replacement for grpc-nodejs has on users.

DESIGN SUMMARY

dorusu-js provides strongly-idiomatic client and server implementations supporting the gRPC rpc protocol.

The main governing power behind the dorusu API design is that it provides elements similar to the existing node.js HTTP2 API, node-http2, which is in turn very similar to the node HTTP API/HTTPS API.

In part, the similarity comes from direct use of classes defined in node-http2. In other cases the classes have been extended to enforce additional restrictions the RPC Protocol places on the use HTTP2.

The goal of the design is that

• the client rpc api surface has a strong similarity to the builtin node.js https library surface
• the server rpc api surface has a strong similarity to the Express API

The result should be an rpc client and server with an intuitive surface that is easy to learn due to its similarity to existing node.js code. I.e, most of the API should already be familiar to developers, and important new rpc features like streaming requests and responses are available as minor deltas that are easily understood.

Missing Features

At this point in time, dorusu-js is missing features that grpc-nodejs provides, e.g,

• automatic connection retrys with exponential backoff in clients
• cascading cancellation in servers
• deadline propagation in servers
• automated stress tests in the CI environment
• automated perfomance tests in the CI environment
• error-code compliance
• a health-check service

There are also other features that are planned for grpc-nodejs that dorusu-js should implement:

• client-side load-balancing
• compression
• enabling per-message compression (once compression is implemented)

These missing features are tracked with issues and triaged via single meta tracking issue

EXAMPLES

Given the greeter protobuf IDL: helloworld.proto

syntax = "proto3";

option java_package = "ex.grpc";

package helloworld;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Serve greetings with a server: helloworld_server.js

var protobuf = require('dorusu/protobuf');
var server = require('dorusu/server');

/**
 * Implements the SayHello RPC method.
 */
function sayHello(request, response) {
  request.on('data', function(msg) {
    response.write({message: 'Hello ' + msg.name});
  });
  request.on('end', function() {
    response.end();
  });
  request.on('error', function() {
    response.end();
  });
};

/**
 * Starts an RPC server that receives requests for the Greeter service at the
 * sample server port
 */
function main() {
  var hellopb = protobuf.requireProto('./helloworld', require);
  var app = hellopb.helloworld.Greeter.serverApp;
  app.register('/helloworld/SayHello', sayHello);

  /* server.raw.CreateServer is insecure, server.createServer is alway secure */
  s = server.raw.createServer({
    app: app,
    host: '0.0.0.0'
  });
  s.listen(50051);
}

main();

Access greetings with a client: helloworld_client.js

var protobuf = require('dorusu/protobuf');

function main() {
  var hellopb = protobuf.requireProto('./helloworld', require);
  /* <package>.Client.raw is insecure, <package>.Client is alway secure */
  var GreeterClient = hellopb.helloworld.Greeter.Client.raw;
  var client = new GreeterClient({
    host: 'localhost',
    port: 50051,
    protocol: 'http:'
  });

  var user = process.argv[2] || 'world';
  // Call the say hello method remotely.
  client.sayHello({name: user}, function (resp) {
    resp.on('data', function(pb) {
      console.log('Greeting:', pb.message);
    });
  });
}

main();

Try it out

node helloworld_server.js &
node helloworld_client.js
node helloworld_client.js dorusu

Other examples

You can also try out the large math_server and math_client examples in this repo

npm update  # install dorusu locally
example/math_server.js &

# (same directory, another terminal window)
example/math_client.js

Try it out with much nicer log output by installing bunyan

npm install -g bunyan # installs bunyan, may require sudo depending on how node is set up

# (from this directory)
HTTP2_LOG=info example/math_server.js | bunyan -o short &

# (same directory, another terminal)
example/math_client.js
HTTP2_LOG=info example/math_client.js | bunyan -o short

TESTING

unit tests

npm test

interop tests

npm run interop-test

Note The node interop test client is tested against the node interop test server as part of the unit tests. interop-test here actual runs against grpc-go.

• the test is skipped unless Go is installed.
• when Go is available, the test installs grpc-go to a temporary location and runs the interop client against the grpc-go server and vice versa.

CONTRIBUTING/REPORTING ISSUES

Contributions to this library are always welcome and highly encouraged. See the CONTRIBUTING documentation for more information on how to get started.