Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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