dorusu
v0.5.0
Published
An implementation of gRPC in Javascript
Downloads
3
Readme
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.