Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 91 lines (66 sloc) 3.108 kb
70fe7e4 @substack spun off protocol docs into a separate file
authored
1 the protocol
2 ============
3
4 dnode uses newline-terminated JSON messages. Each side of the connection may
5 request that a method be invoked on the other side.
6
7 data fields
8 -----------
9
10 All messages have this format:
11
12 * method :: String or Integer
13 * arguments :: Array
14 * callbacks :: Object
15 * links :: Array
16
17 When the method field is a string, it refers to a named method at the remote.
18 When the method field is an integer, it refers to an anonymous function
19 declared in the callbacks field of a previous request.
20
21 The arguments field contains the data to supply the remote method or callback.
22 The callbacks field maps an integral callback ID to an Array of elements
23 representing the callback's path in the arguments structure. For instance,
24 an arguments array before transformation of
25
26 [ 50, 3, { "b" : function () {}, "c" : 4 }, function () {} ]
27
28 could result in a callback field of
29
30 { 103 : [ 2, "b" ], 104 : [ 3 ] }
31
32 if the functions were assigned IDs of 103 and 104 from left to right
33 respectively. Function 103 is in the object at element index 2 and at the key
34 "b", so its path is [ 2, "b" ]. Function 104 is just at index 3 in the argument
35 field so its path is just [ 3 ].
36
37 The contents of the arguments array at a callback location is not used, so it
38 may contain any value or may be left undefined.
39
40 The Array and Object fields can be omitted, in which case they default to [] and
41 {}.
42
43 methods
44 -------
45
46 After the connection is established, each side should send a message with the
47 method field set to "methods". The arguments fields should contain an array with
48 a single element: the object that should be wrapped. The callbacks field is
49 populated from the arguments array given the procedure above.
50
51 Example of this initial methods message:
52
53 {
54 "method" : "methods",
55 "arguments" : [ { "timesTen" : "[Function]", "moo" : "[Function]" } ],
56 "callbacks" : { "0" : ["0","timesTen"], "1" : ["0","moo"] }
57 }
58
59 Note that the string "[Function]" is just a placeholder and its value is
60 unimportant.
61
62 After methods are exchanged, each side may request methods from the other based
63 on named keys or numeric callback IDs.
64
65 links
66 -----
67
68 An optional field, "links" supports representing cyclic data structures over
69 JSON. The "links" field is an array of hashes with "from" and "to" keys set. The
70 values of the "from" and "two" keys are array encoding paths through the data
71 structure from the root, as in the "callbacks" field.
72
73 Example of a method call with cyclic references:
74
75 {
76 "method" : 12,
77 "arguments" : [ { "a" : 5, "b" : [ { "c" : 5 } ] } ],
78 "callbacks" : {},
79 "links" : [ { "from" : [ 0 ], "to" : [ 0, "b", 1 ] } ]
80 }
81 This example creates a link to the first argument within the first argument's
82 "b" key's second element. The previous data structure could be generated from
83 the following javascript where `fn` comes from the remote:
84
85 var data = { a : 5, b : [ { c : 5 } ] };
86 data.b.push(data);
87 fn(data);
88
89 Note that links need not necessarily be cyclic, they can just more efficiently
90 encode duplicate data, for instance.
Something went wrong with that request. Please try again.