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)