README.md

node-msgpack-rpc

node-msgpack-rpc is an implementation of the Msgpack-RPC protocol specification for node.js. Msgpack-RPC is built ontop of the very fast MessagePack serialization format. This implementation supports tcp and unix socket transports (it may one day support UDP).

Simple Usage

The easiest way to create a server is with a handler object. All incoming calls will be invoked on the handler object:

var handler = {
  'add' : function(a, b, response) {
     response.result( a + b );
   }
}

var rpc = require('msgpack-rpc');
rpc.createServer();
rpc.setHandler(handler);
rpc.listen(8000);

a corresponding client might look like:

var c = rpc.createClient(8000, '127.0.0.1', function() {
  c.invoke('add', 5, 4, function(err, response) {
    assert.equal(9, response);
    c.close();
  }
});

Without a handler

rpc.createServer(function(rpc_stream) {
  rpc_stream.on('request', function(method, params, response) {
    if(method == 'add') {
      response.result( params[0] + params[1] );
    } else {
      response.error("unknown method!");
    }
  }

  rpc_stream.on('notify', function(method, params) {
    console.log("recieved notification: " + method);
  });
});
rpc.listen(8000);

Session Pool

This module also provides a session pool which allows you to re-use client connections:

var sp = new SesssionPool();
sp.getClient(8000, '127.0.0.1').invoke('hello','world', function(err, response) { ... });;
sp.getClient(8001, '127.0.0.1').invoke('hello','world', function(err, response) { ... });;

// Uses same tcp connection as above
sp.getClient(8000, '127.0.0.1').invoke('goodbye','world', function(err, response) { ... });;

sp.closeClients();

Installation

First you will need to install the node-msgpack add-on

To install node-msgpack-rpc with npm:

git clone http://github.com/bpot/node-msgpack-rpc/
cd node-msgpack-rpc
npm link .

RPC Stream API

Clients and the streams passed to servers for incoming connections are both instances of MsgpackRPCStream.

Methods

c.createClient(port, [hostname], [ready_cb]);
c.invoke(method, [param1, param2, ...], cb);
c.notify(method, [param1, param2, ...]);
c.setTimeout(milliseconds);  // Setting this will cause requests to fail with err "timeout" if they don't recieve a response for the specified period
c.close(); // Close the socket for this client
c.stream // underlying net.Stream object

Events

'ready' // emitted when we've connected to the server
'request' // recieved request
'notify' // recieved notification

TODO

• UDP Support?