Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 319 lines (221 sloc) 9.284 kB
cd50a59 @substack pared down the readme
authored
1 dnode
05ad7c4 @substack more examples in the readme
authored
2 =====
3
5f92d41 @substack update the readme about the other languages and the turtle logo
authored
4 ![dnode: freestyle rpc](http://substack.net/images/dnode.png)
5
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
6 DNode is an asynchronous object-oriented RPC system for node.js that lets you
7 call remote functions.
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
8
12ead0d @substack update express and browserify deps, travis badge
authored
9 [![build status](https://secure.travis-ci.org/substack/dnode.png)](http://travis-ci.org/substack/dnode)
10
5f92d41 @substack update the readme about the other languages and the turtle logo
authored
11 It works over network sockets and even in the browser with
773cabd @substack feature the browser example more prominently and link to my slides
authored
12 [socket.io](https://github.com/LearnBoost/Socket.IO).
13
5f92d41 @substack update the readme about the other languages and the turtle logo
authored
14 Plus, there are dnode implementations for
15 [perl](http://github.com/substack/dnode-perl),
16 [ruby](http://github.com/substack/dnode-ruby),
0b488ef @substack mention dnode-php
authored
17 [php](https://github.com/bergie/dnode-php),
5f92d41 @substack update the readme about the other languages and the turtle logo
authored
18 and
19 [java](https://github.com/aslakhellesoy/dnode-java),
20 so you can glue
12ead0d @substack update express and browserify deps, travis badge
authored
21 together all your backend processes.
5f92d41 @substack update the readme about the other languages and the turtle logo
authored
22
773cabd @substack feature the browser example more prominently and link to my slides
authored
23 dnode between two node.js processes
24 -----------------------------------
25
26 Just write a server.js:
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
27
fb04af3 @substack fenced code blocks for syntax highlighting
authored
28 ```javascript
29 var dnode = require('dnode');
30
31 var server = dnode({
32 zing : function (n, cb) { cb(n * 100) }
33 });
34 server.listen(5050);
35 ````
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
36
37 Run it...
38
39 $ node server.js
40
773cabd @substack feature the browser example more prominently and link to my slides
authored
41 Then you can whip up a client.js that calls the server's `zing` function!
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
42
fb04af3 @substack fenced code blocks for syntax highlighting
authored
43 ```javascript
44 var dnode = require('dnode');
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
45
fb04af3 @substack fenced code blocks for syntax highlighting
authored
46 dnode.connect(5050, function (remote) {
47 remote.zing(66, function (n) {
48 console.log('n = ' + n);
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
49 });
fb04af3 @substack fenced code blocks for syntax highlighting
authored
50 });
51 ````
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
52
53 ***
54
55 $ node client.js
773cabd @substack feature the browser example more prominently and link to my slides
authored
56 n = 6600
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
57 ^C
58
773cabd @substack feature the browser example more prominently and link to my slides
authored
59 dnode on the browser
60 --------------------
61
62 We can retrofit the previous example to run in the browser.
63
64 Just write a server.js:
65
fb04af3 @substack fenced code blocks for syntax highlighting
authored
66 ````javascript
67 var express = require('express');
68 var app = express.createServer();
69 app.use(express.static(__dirname));
70
71 app.listen(8080);
72 console.log('http://localhost:8080/');
73
74 // then just pass the server app handle to .listen()!
75
76 var dnode = require('dnode');
77 var server = dnode({
78 zing : function (n, cb) { cb(n * 100) }
79 });
80 server.listen(app);
81 ````
773cabd @substack feature the browser example more prominently and link to my slides
authored
82
83 and whip up an index.html:
84
fb04af3 @substack fenced code blocks for syntax highlighting
authored
85 ````html
86 <html>
87 <head>
88 <script src="/dnode.js" type="text/javascript"></script>
89 <script type="text/javascript">
90 window.onload = function () {
91
92 DNode.connect(function (remote) {
93 remote.zing(66, function (n) {
94 document.getElementById('result').innerHTML = n;
773cabd @substack feature the browser example more prominently and link to my slides
authored
95 });
fb04af3 @substack fenced code blocks for syntax highlighting
authored
96 });
97
98 };
99 </script>
100 </head>
101 <body>
102
103 n = <span id="result">?</span>
104
105 </body>
106 </html>
107 ````
773cabd @substack feature the browser example more prominently and link to my slides
authored
108
109 then just run the server.js:
110
111 $ node server.js
112 http://localhost:8080/
113
114 and navigate to http://localhost:8080:
115
116 ![dnode in the browser](http://substack.net/images/dnode-slides/browser.png)
117
118 Awesome it works!
119
120 The dnode browser source automatically gets hosted at `/dnode.js` and it also
121 works with
7f1f1f0 @substack update browserify link
authored
122 [browserify](https://github.com/substack/node-browserify)
773cabd @substack feature the browser example more prominently and link to my slides
authored
123 [out of the box](https://github.com/substack/dnode/tree/master/examples/web-browserify).
124
125 how it works
126 ------------
127
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
128 When you throw an object at dnode, a recursive traversal scrubs out all of the
129 `function` objects nested in your data structure and a secondary data structure
130 is sent along with remote requests that creates shim functions that create RPC
131 calls back to the side where the functions were originally defined.
132
133 When you call a remote function, the same recursive traversal trick happens to
134 the arguments you pass along, so you can pass callbacks to your remote functions
135 that actually call you back over the wire when the remote side calls the shim
136 function on the other end.
137
138 Basically, dnode lets you call remote functions as if they were defined locally
139 without using `eval()` or `Function.prototype.toString()`. Awesome!
140
141 The only catch is that because the function calls are traveling down the
142 high-latency network, the return values of your functions are ignored. Use
143 [continuation-passing
144 style](http://en.wikipedia.org/wiki/Continuation-passing_style) instead!
145
146 More features:
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
147
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
148 * symmetric design: both sides of the connection can host up methods for the
149 other side to call
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
150
785bdf4 Added UNIX domain socket support.
Michael S. Fischer authored
151 * use TCP streams, UNIX domain sockets, or websockets courtesy of socket.io!
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
152 (see below, just throw a webserver at `listen()`)
153
154 methods
155 =======
156
157 dnode(wrapper)
158 --------------
159
160 If `wrapper` is an object, serve this object up to the other side every time.
161
162 If `wrapper` is a function, use it to build a new object for each new client.
163 The result of `new wrapper(remote, conn)` will be used, where `remote` is an
164 empty object that will be filled with the other side's methods once the initial
165 protocol phase finishes and where `conn` is the connection object.
166
167 Both client and server can call `dnode()` with a wrapper.
168 `dnode.connect()` and `dnode.listen()` are shortcut that set `wrapper` to `{}`.
169
170 .connect(...)
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
171 -------------
172
785bdf4 Added UNIX domain socket support.
Michael S. Fischer authored
173 Connect to a remote dnode service. Pass in a port, host, UNIX domain socket
174 path, block, or options object in any order. The block function if present will
175 be executed with the remote object and the connection object once the remote
176 object is ready.
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
177
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
178 You can reconnect when the connection is refused or drops by passing in a
179 `reconnect` option as the number of milliseconds to wait between reconnection
180 attempts.
181
182 Returns `this` so you can chain multiple connections.
164f85e @substack note about reconnect
authored
183
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
184 .listen(...)
e565c1c @substack updated the intro and put some function usage before the examples sec…
authored
185 ------------
186
785bdf4 Added UNIX domain socket support.
Michael S. Fischer authored
187 Listen for incoming dnode clients. Pass in a port, host, UNIX domain socket
188 path, block, or options object in any order. The block function if present will
189 be executed with the remote object and the connection object once the remote
190 object is ready for each client.
2d36d00 @substack dependency info in the readme
authored
191
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
192 If you pass a webserver (http.Server, https.Server, connect, express) to
193 listen(), socket.io will be bound to the webserver and the dnode browser source
194 will be hosted at `options.mount || "/dnode.js"`.
195
a9ba38f @substack bump and readme notes for passing parameters through to socket.io
authored
196 You can pass options through to socket.io with the `io` parameter:
197
fb04af3 @substack fenced code blocks for syntax highlighting
authored
198 ````javascript
199 dnode(...).listen(webserver, { io : { flashPolicyServer : false } });
200 ````
a9ba38f @substack bump and readme notes for passing parameters through to socket.io
authored
201
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
202 Returns `this` so you can chain multiple listeners.
203
204 .use(middleware)
205 ----------------
f2d386d @substack bump to 0.5 and readme notes about .use()
authored
206
207 You can write your own dnode middleware with `.use()`. The `middleware` function
208 you pass will be called just like the constructor function that `dnode()` takes.
209 You can modify `this`, `remote`, and `conn` objects after the instance computed
210 with the `dnode()` constructor executes but before the methods are sent over the
211 wire.
212
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
213 Returns `this` so you can chain middlewares.
05ad7c4 @substack more examples in the readme
authored
214
773cabd @substack feature the browser example more prominently and link to my slides
authored
215 the connection object
216 =====================
979efc1 @substack very basic .listen() part with a README
authored
217
773cabd @substack feature the browser example more prominently and link to my slides
authored
218 When you pass a constructor function to `dnode()` you'll get a connection
219 object as the second argument to your constructor.
2a9e1e7 @substack socket.io instructions for installation
authored
220
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
221 The connection object (`conn`) is an EventEmitter.
2a9e1e7 @substack socket.io instructions for installation
authored
222
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
223 * conn.id is a random hex string that uniquely identifies clients
224
225 * conn.end() closes the connection and won't reconnect
05ad7c4 @substack more examples in the readme
authored
226
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
227 * conn emits 'ready' when the remote object has been fully populated from
228 the methods exchange
229
230 * conn emits 'remote' at the same time as 'ready', except with the remote object
231 as an argument
232
233 * conn emits 'end' when the connection drops
234
235 * conn emits 'connect' when the connection is established
236
237 * conn re-emits error events from the stream object
238
239 * conn emits 'refused', 'drop', and 'reconnect' when reconnect is enabled
240
241 more examples
242 -------------
243
244 Check out
245 [the examples directory](https://github.com/substack/dnode/tree/master/examples/)
246 of this distribution.
05ad7c4 @substack more examples in the readme
authored
247
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
248 You'll find examples for using dnode with
249 [connect](https://github.com/SenchaLabs/connect),
250 [express](http://expressjs.com/),
251 [https](https://github.com/substack/dnode/tree/master/examples/https),
252 and authentication.
253
254 There's a chat server too!
255
256 installation
cd50a59 @substack pared down the readme
authored
257 ============
258
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
259 Using [npm](http://npmjs.org):
cd50a59 @substack pared down the readme
authored
260
261 npm install dnode
262
6c53146 @substack bump, updated docs with the build step
authored
263 Or check out the repository and fetch the deps with npm, then build the bundle:
cd50a59 @substack pared down the readme
authored
264
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
265 git clone https://github.com/substack/dnode.git
6c53146 @substack bump, updated docs with the build step
authored
266 cd dnode
267 npm install --dev
268 node bin/bundle.js
cd50a59 @substack pared down the readme
authored
269
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
270 The dnode dependencies are listed in the
271 [package.json](https://github.com/substack/dnode/tree/master/package.json).
272 If you install with npm they will be fetched automatically.
cd50a59 @substack pared down the readme
authored
273
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
274 read more
2bab437 @substack blog links
authored
275 =========
276
773cabd @substack feature the browser example more prominently and link to my slides
authored
277 * [slides from my dnode talk at parisoma](http://substack.net/posts/9aabb1)
278
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
279 * [Roll your own PubSub with DNode](http://substack.net/posts/9bac3e/Roll-your-own-PubSub-with-DNode)
280 (Note: EventEmitters are no longer exported directly, use
281 [browserify](https://github.com/substack/node-browserify) to get them back)
2bab437 @substack blog links
authored
282
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
283 * [DNode: Asynchronous Remote Method Invocation for Node.js and the Browser](http://substack.net/posts/85e1bd/DNode-Asynchronous-Remote-Method-Invocation-for-Node-js-and-the-Browser)
7646c59 @substack new message protocol description
authored
284
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
285 * [Simon Willison's Weblog](http://simonwillison.net/2010/Jul/11/dnode/)
7646c59 @substack new message protocol description
authored
286
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
287 protocol
05ad7c4 @substack more examples in the readme
authored
288 ========
289
e583e4f @substack rewrote the readme to cut it down length-wise and bumped an example t…
authored
290 DNode uses a newline-terminated JSON protocol
291 [documented in the dnode-protocol
292 readme](https://github.com/substack/dnode-protocol).
293
294 dnode in other languages
295 ========================
7e213dc @substack unicode test, note about dnode-perl
authored
296
6b00223 @substack blarg caps fixes
authored
297 These libraries implement the dnode protocol too so you can make RPC calls
7e213dc @substack unicode test, note about dnode-perl
authored
298 between scripts written in different languages.
299
cd50a59 @substack pared down the readme
authored
300 * [dnode-perl](http://github.com/substack/dnode-perl)
301 * [dnode-ruby](http://github.com/substack/dnode-ruby)
34f007b @substack also mention dnode-php down here
authored
302 * [dnode-php](https://github.com/bergie/dnode-php)
55d90e3 @substack added link to dnode-java
authored
303 * [dnode-java](https://github.com/aslakhellesoy/dnode-java)
cd50a59 @substack pared down the readme
authored
304
773cabd @substack feature the browser example more prominently and link to my slides
authored
305 There's a
306 [dnode-python](https://github.com/jesusabdullah/dnode-python)
307 in the works too but it's not finished yet.
10bc093 @substack shameless browserling plug
authored
308
309 shameless plug
310 ==============
311
312 Want to make sure your crazy javascript-heavy app still works in other
313 browsers?
314 Give [browserling](http://browserling.com) a spin!
315 Browsers in your browser. Powered by dnode.
1f24314 @substack use an older version of express, travis badge
authored
316
317 [![build status](https://secure.travis-ci.org/substack/dnode.png)](http://travis-ci.org/substack/dnode)
318
Something went wrong with that request. Please try again.