GelRpc for Node.js

GelRpc is a dead simple (~300 loc) rpc system that works over any full-duplex text/byte/json stream. It has one dependency - through. Matching libraries for Python and .NET are planned.

Table of Contents

• Usage
  • Over TCP
• API Reference
  • gelrpc.router
  • gelrpc.serializer
  • gelrpc.stream(route, opts)
  • Class: Stream
    • stream.wrap(methodNames)
    • stream.rpc(name, args, cb)
    • stream.pipe(stream)
• Ports
• Credits
• WTF?

Usage

var gelrpc = require('gelrpc');

// Create a server, that answers questions.
// Pass in functions that may be called remotely. (Alternatively, 
// you may pass a route function to gelrpc.stream.)
var server = gelrpc.stream({
  hello: function(name, cb) {
    cb(null, 'hello, ' + name);
  }
});

// Create a client, that asks questions.
var client = gelrpc.stream();

// Pipe them together!
client.pipe(server).pipe(client);

// Make a call without further ado.
client.rpc('hello', ['JIM'], function (err, message) {
  if (err)
    console.log('ERROR: ' + err);
  else if (message === 'hello, JIM')
    console.log('Got the message!');
});

// Or create a remote facade to call with.
var remote = client.wrap(['hello']);
remote.hello('JIM', function (err, mess) {
  if (err)
    console.log('ERROR: ' + err);
  else if (message === 'hello, JIM')
    console.log('Got the message!');
})

Over TCP

Server

net.createServer(function(con) {
  // Create one server per connection.
  var server = gelrpc.stream(/* ... */);
  server.pipe(con).pipe(server);
}).listen(3000));

Client

var client = gelrpc.stream();
var con = net.connect(3000);
client.pipe(con).pipe(client);

var remote = client.wrap(['hola']);
remote.hola('steve', function(err, res) {
  console.log(res);
});

API Reference

gelrpc.router

Documentation for gelrpc.router will be coming shortly.

gelrpc.serializer

Documentation for gelrpc.serializer will be coming shortly.

gelrpc.stream(route, opts)

Returns a Stream that will call methods when written to.

Parameters

• [route] Object - contains one key per callable function.
• [route] Function - accepts (path, args, callback) where path is a string, args any type and callback a standard Node.js error-first callback function.
• [opts] Object - contains one or more of the following options.
  • [EOL] String - end of line marker to use. Default: '\n'.
  • [flattenError] Function - accepts (err) and returns an object to serialize.
  • [prefix] String - a value to use as an include-filter for each EOL-separated line in the stream.
  • [raw] Boolean - when true, the default serializer which uses JSON.stringify is disabled and you just get a stream of objects. Use this if you want to do your own parsing and serializing.

Class: Stream

A class that is derived from Stream.

stream.wrap(methodNames)

Returns a wrapped object with the remote's methods. The client needs to already know the names of the methods. Accepts a string, and array of strings, or a object. If it's an object, wrap will use the keys as the method names.

Example

// Create rpc stream around the fs module.
var fsrpc = gelrpc.stream(require('fs'));
// pipe, etc

Then, in another process...

var fsrpc = gelrpc.stream();
// pipe, etc

// wrap, with the right method names.
var remoteFs = fsrpc.wrap(require('fs'));

remoteFs.mkdir('/tmp/whatever', function (err, dir) {
  // yay!
})

Now, the second process can call the fs module in the first process! wrap does not use the methods for anything. It just wants the names.

stream.rpc(name, args, cb)

Directly send a call to the remote side without any wrapper function.

Parameters

• name String - name (or 'path/to/name') of a remote function.
• [args] Any - array of arguments to pass to the remote function.
• [cb] Function - a standard Node.js error-first callback that will be called when the remote side responds.

Example

var client = gelrpc.stream();
client.rpc('hello', [name], callback);
// Another way of sending the same remote call is by using a 
// wrapper function: 
client.wrap('hello').hello(name, callback);

stream.pipe(stream)

Read about piping streams here.

Ports

(Coming Soon!)

...

Credits

This project contains a fork of Dominic Tarr's excellent rpc-stream and stream-serializer libraries, which form the core of this library. Thanks for your work!

WTF?

(Why the Fork?)

I needed a single, tightly-coupled library that I can easily maintain instead of multiple loosely-coupled libraries that I don't control. This library will also be used in a larger library that it must be compatible with.