BERT-RPC client and server for node.js
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
test
.gitignore
COPYING
README
package.json

README

                         bertrpc.js

This is a BERT-RPC server and client library for
node.js <http://nodejs.org/>, the V8 based evented
IO framework.

BERT-RPC is a schemaless binary remote procedure call
protocol by Tom Preston-Werner, based on the BERT
(Binary ERlang Term) serialization format.

See <http://bert-rpc.org/> for more information about
BERT and BERT-RPC, including additional language
implementations.

The  bert.js library  was  taken  from  Rusty Klophaus's
BERT-JS  project:  <http://github.com/rklophaus/BERT-JS>
but has been modified quite a bit at this point.

STATUS

This package is lightly maintained in hopes somebody finds it useful.

INSTALL

node.js must be installed and available on your PATH
before continuing. It's trivial:

    cd /tmp
    curl -L http://bit.ly/nodejs | tar xvzf -
    cd node-*
    ./configure PREFIX=/usr/local
    make && sudo make install

EXAMPLES

Once you have node installed, grab a clone of the
node-bertrpc git repo

    $ git clone git://github.com/znull/node-bertrpc
    $ cd node-bertrpc
    $ node examples/helloworld.js
      <--  exposing: say [funs: hello, echo]

Leave that there and then run the example client in a
separate shell:

    $ node examples/helloclient.js

You should see something like the following output from
the server:

      -->   connect
      -->   30: {call, say, hello, []}
      <--   21: {reply, <<"hello">>}
      -->   45: {call, say, echo, [<<"Hello World">>]}
      <--   33: {reply, [<<"Hello World">>]}
      -->   85: {call, say, echo, [[{foo, <<"bar">>}, {bar, <<"baz">>}], 21]}
      <--   73: {reply, [[{foo, <<"bar">>}, {bar, <<"baz">>}], 21]}
      -->   eof
      <--   close

Connect with the Ruby BERT-RPC client (or any other
BERT-RPC client) to play at a REPL:

    $ sudo gem install bertrpc -s http://gemcutter.org/
    $ irb -rubygems -rbertrpc
    >> service = BERTRPC::Service.new('localhost', 7000)
    >> service.call.say.echo('hello', 'world', { 'foo' => %w[bar baz bizle] })
    => ["hello", "world", {:foo=>["bar", "baz", "bizzle"]}]

BERT-RPC SERVERS

Require the "bertrpc" lib and expose objects:

    var rpc = require('bertrpc');
    rpc.expose('hello', {
       add: function (a, b) {
          return a + b;
       },
       subtract: function (a, b) {
          return a - b;
       }
    });

    rpc.listen(7001, 'localhost');

Start the node server by running your script directly:

    node yourstuff.js

That exposes a BERT-RPC module named "hello" with two
remotely callable functions: "add" and "subtract" but you
can pass any object to expose to make all of its functions
available.

BERT-RPC CLIENTS

The BERT-RPC client library is still very experimental and
likely to change significantly:

    var sys = require('sys'),
        rpc = require('bertrpc');
    rpc.connect(7001, 'localhost', function (service) {
       sys.puts("client calling the add fun in the hello module");
       service.call('hello', 'add', [1, 2], function (result) {
          sys.puts("client received response: " + sys.inspect(result));
          // do something useful
       });
    });

BERT ENCODING / DECODING

The bert.js library includes functions for encoding,
decoding, and getting a formatting string representation of
BERT objects.

Get in a REPL:

    $ NODE_PATH=./src node-repl
    Welcome to the Node.js REPL.
    Enter ECMAScript at the prompt.
    node> bert = require('bert');

bert.encode serializes an object graph as a BERT:

    node> holabert = bert.encode('hello')
    "\u0083m\u0000\u0000\u0000\u0005hello"
    node> sys.puts(bert.bin_repr(holabert))
    <<131,109,0,0,0,5,104,101,108,108,111>>

bert.decode deserializes a BERT, creating an object graph:

    node> bert.decode("\u0083m\u0000\u0000\u0000\u0005hello")
    "hello"

DEVELOPMENT

The tests have been converted to use `nodeunit`. Make sure it is installed
and available in your path, then run `nodeunit test/test_*` to execute the
tests.

SEE ALSO

CODE: git clone git://github.com/znull/node-bertrpc.git
HOME: http://github.com/znull/node-bertrpc/
BUGS: http://github.com/znull/node-bertrpc/issues
COPY: See the file COPYING (it's MIT)