dnode
dnode is an asynchronous rpc system for node.js that lets you
call remote functions.
You can pass callbacks to remote functions, and the remote end can call
the functions you passed in with callbacks of its own and so on.
It's callbacks all the way down!
example
listen and connect
server:
var dnode = require('dnode');
var server = dnode({
transform : function (s, cb) {
cb(s.replace(/[aeiou]{2,}/, 'oo').toUpperCase())
}
});
server.listen(5004);
client:
var dnode = require('dnode');
var d = dnode.connect(5004);
d.on('remote', function (remote) {
remote.transform('beep', function (s) {
console.log('beep => ' + s);
d.end();
});
});
output:
$ node server.js &
[1] 27574
$ node client.js
beep => BOOP
streaming
The .connect()
and .listen()
calls in the previous example are just
convenience methods for piping to and from readable/writable streams.
Here's the previous example with the streams set up explicitly:
server:
var dnode = require('dnode');
var net = require('net');
var server = net.createServer(function (c) {
var d = dnode({
transform : function (s, cb) {
cb(s.replace(/[aeiou]{2,}/, 'oo').toUpperCase())
}
});
c.pipe(d).pipe(c);
});
server.listen(5004);
client:
var dnode = require('dnode');
var net = require('net');
var d = dnode();
d.on('remote', function (remote) {
remote.transform('beep', function (s) {
console.log('beep => ' + s);
d.end();
});
});
var c = net.connect(5004);
c.pipe(d).pipe(c);
output:
$ node server.js &
[1] 27586
$ node client.js
beep => BOOP
dnode in the browser
Since dnode instances are just readable/writable streams, you can use them with
any streaming transport, including in the browser!
This example uses the streaming interface provided by
shoe, which is just a thin wrapper on top of
sockjs that provides websockets with fallbacks.
First whip up a server:
var http = require('http');
var shoe = require('shoe');
var ecstatic = require('ecstatic')(__dirname + '/static');
var dnode = require('dnode');
var server = http.createServer(ecstatic);
server.listen(9999);
var sock = shoe(function (stream) {
var d = dnode({
transform : function (s, cb) {
var res = s.replace(/[aeiou]{2,}/, 'oo').toUpperCase();
cb(res);
}
});
d.pipe(stream).pipe(d);
});
sock.install(server, '/dnode');
Then write some browser code:
var domready = require('domready');
var shoe = require('shoe');
var dnode = require('dnode');
domready(function () {
var result = document.getElementById('result');
var stream = shoe('/dnode');
var d = dnode();
d.on('remote', function (remote) {
remote.transform('beep', function (s) {
result.textContent = 'beep => ' + s;
});
});
d.pipe(stream).pipe(d);
});
Install the dependencies for this example then compile the browser code with
browserify:
$ npm install dnode shoe domready ecstatic
$ npm install -g browserify
$ browserify client.js -o static/bundle.js
Now drop a script tag into static/index.html:
<script src="/bundle.js"></script>
<div id="result"></div>
and navigate to http://localhost:9999.
You should see beep => BOOP
on the page!
Check out the
complete shoe example.
methods
var dnode = require('dnode')
var d = dnode(cons, opts={})
Create a new readable/writable dnode stream object d
.
All the usual stream methods are at your disposal: pipe(), write(), end().
If cons
is a function, it will be called new cons(remote, d)
to create a new
instance object. Otherwise its value will be used directly. When cons
is
called as a function, the remote
ref will be an empty unpopulated object.
By default, dnode uses weakmaps to garbage collect unused callbacks
automatically. This behavior prevents memory leaks in long-running connections.
You can turn weakmaps off by setting opts.weak = false
.
d.connect(...)
This method is a shortcut for setting up a pipe between d
and a new
net.connect()
stream.
The host, port, and callback arguments supplied will be inferred by their
types.
If you pass a callback in as an argument, it will be added as a listener to the
'remote'
event.
Returns the d
object.
dnode.connect(...)
Shortcut to create a connection without a constructor.
d.listen(...)
This method is a shortcut for setting up a net.createServer()
and piping
network streams to and from new dnode streams.
The host, port, and callback parameters will be inferred from the types of the
arguments.
Returns a net server object that will also emit 'local'
and 'remote'
events
from the underlying dnode streams..
dnode.listen(...)
Shortcut to create a listener without a constructor.
events
d.on('remote', cb)
This event fires with cb(remote, d)
when the remote side of the connection
has constructed its instance.
d.on('local', cb)
This event fires right after the constructed instance has been created locally
but before it gets sent to the remote end so you can modify the ref object.
This event fires with cb(ref, d)
where ref
is the local instance object.
d.on('fail', cb)
This event fires when the remote end causes errors in the protocol layer.
These are non-fatal and can probably be ignored but you could also terminate the
connection here.
d.on('error', cb)
This event fires when local code causes errors in its callbacks.
Not all errors can be caught here since some might be in async functions.
d.on('end', cb)
This event fires when the input stream finishes.
install
With npm do:
npm install dnode
protocol
dnode uses a newline-terminated JSON protocol
documented in the dnode-protocol project.
dnode in other languages
These libraries implement the dnode protocol too so you can make RPC calls
between scripts written in different languages.
shameless plug
Want to make sure your crazy javascript-heavy app still works in other
browsers?
Give browserling a spin!
Browsers in your browser. Powered by dnode.