Browse files

spun off protocol docs into a separate file

  • Loading branch information...
1 parent 5f98bb5 commit 70fe7e4b6e652b40734dd12001cca85e68cf1bec @substack committed Jun 20, 2012
Showing with 102 additions and 85 deletions.
  1. +12 −85 README.markdown
  2. +90 −0 doc/protocol.markdown
View
97 README.markdown
@@ -4,102 +4,29 @@ dnode-protocol
This module implements the dnode protocol in a reusable form that is presently
used for both the server-side and browser-side dnode code.
-If you care about how this particular module works and want to use it for
-whatever reason, check out
-[all the tests in test/](https://github.com/substack/dnode-protocol/tree/master/test).
+[Read about the protocol itself here.](https://github.com/substack/dnode-protocol/blob/master/doc/protocol.markdown)
[![build status](https://secure.travis-ci.org/substack/dnode-protocol.png)](http://travis-ci.org/substack/dnode-protocol)
-the protocol
-============
+example
+=======
-dnode uses newline-terminated JSON messages. Each side of the connection may
-request that a method be invoked on the other side.
-
-data fields
------------
-
-All messages have this format:
-
-* method :: String or Integer
-* arguments :: Array
-* callbacks :: Object
-* links :: Array
-
-When the method field is a string, it refers to a named method at the remote.
-When the method field is an integer, it refers to an anonymous function
-declared in the callbacks field of a previous request.
-
-The arguments field contains the data to supply the remote method or callback.
-The callbacks field maps an integral callback ID to an Array of elements
-representing the callback's path in the arguments structure. For instance,
-an arguments array before transformation of
-
- [ 50, 3, { "b" : function () {}, "c" : 4 }, function () {} ]
-
-could result in a callback field of
-
- { 103 : [ 2, "b" ], 104 : [ 3 ] }
-
-if the functions were assigned IDs of 103 and 104 from left to right
-respectively. Function 103 is in the object at element index 2 and at the key
-"b", so its path is [ 2, "b" ]. Function 104 is just at index 3 in the argument
-field so its path is just [ 3 ].
-
-The contents of the arguments array at a callback location is not used, so it
-may contain any value or may be left undefined.
-
-The Array and Object fields can be omitted, in which case they default to [] and
-{}.
+``` js
+```
methods
--------
-
-After the connection is established, each side should send a message with the
-method field set to "methods". The arguments fields should contain an array with
-a single element: the object that should be wrapped. The callbacks field is
-populated from the arguments array given the procedure above.
-
-Example of this initial methods message:
-
- {
- "method" : "methods",
- "arguments" : [ { "timesTen" : "[Function]", "moo" : "[Function]" } ],
- "callbacks" : { "0" : ["0","timesTen"], "1" : ["0","moo"] }
- }
-
-Note that the string "[Function]" is just a placeholder and its value is
-unimportant.
-
-After methods are exchanged, each side may request methods from the other based
-on named keys or numeric callback IDs.
-
-links
------
+=======
-An optional field, "links" supports representing cyclic data structures over
-JSON. The "links" field is an array of hashes with "from" and "to" keys set. The
-values of the "from" and "two" keys are array encoding paths through the data
-structure from the root, as in the "callbacks" field.
+``` js
+var protocol = require('dnode-protocol')
+```
-Example of a method call with cyclic references:
+var proto = protocol(cons, localRef=[])
+---------------------------------------
- {
- "method" : 12,
- "arguments" : [ { "a" : 5, "b" : [ { "c" : 5 } ] } ],
- "callbacks" : {},
- "links" : [ { "from" : [ 0 ], "to" : [ 0, "b", 1 ] } ]
- }
-This example creates a link to the first argument within the first argument's
-"b" key's second element. The previous data structure could be generated from
-the following javascript where `fn` comes from the remote:
+Create a new protocol object with a constructor `cons`.
- var data = { a : 5, b : [ { c : 5 } ] };
- data.b.push(data);
- fn(data);
-Note that links need not necessarily be cyclic, they can just more efficiently
-encode duplicate data, for instance.
other languages
===============
View
90 doc/protocol.markdown
@@ -0,0 +1,90 @@
+the protocol
+============
+
+dnode uses newline-terminated JSON messages. Each side of the connection may
+request that a method be invoked on the other side.
+
+data fields
+-----------
+
+All messages have this format:
+
+* method :: String or Integer
+* arguments :: Array
+* callbacks :: Object
+* links :: Array
+
+When the method field is a string, it refers to a named method at the remote.
+When the method field is an integer, it refers to an anonymous function
+declared in the callbacks field of a previous request.
+
+The arguments field contains the data to supply the remote method or callback.
+The callbacks field maps an integral callback ID to an Array of elements
+representing the callback's path in the arguments structure. For instance,
+an arguments array before transformation of
+
+ [ 50, 3, { "b" : function () {}, "c" : 4 }, function () {} ]
+
+could result in a callback field of
+
+ { 103 : [ 2, "b" ], 104 : [ 3 ] }
+
+if the functions were assigned IDs of 103 and 104 from left to right
+respectively. Function 103 is in the object at element index 2 and at the key
+"b", so its path is [ 2, "b" ]. Function 104 is just at index 3 in the argument
+field so its path is just [ 3 ].
+
+The contents of the arguments array at a callback location is not used, so it
+may contain any value or may be left undefined.
+
+The Array and Object fields can be omitted, in which case they default to [] and
+{}.
+
+methods
+-------
+
+After the connection is established, each side should send a message with the
+method field set to "methods". The arguments fields should contain an array with
+a single element: the object that should be wrapped. The callbacks field is
+populated from the arguments array given the procedure above.
+
+Example of this initial methods message:
+
+ {
+ "method" : "methods",
+ "arguments" : [ { "timesTen" : "[Function]", "moo" : "[Function]" } ],
+ "callbacks" : { "0" : ["0","timesTen"], "1" : ["0","moo"] }
+ }
+
+Note that the string "[Function]" is just a placeholder and its value is
+unimportant.
+
+After methods are exchanged, each side may request methods from the other based
+on named keys or numeric callback IDs.
+
+links
+-----
+
+An optional field, "links" supports representing cyclic data structures over
+JSON. The "links" field is an array of hashes with "from" and "to" keys set. The
+values of the "from" and "two" keys are array encoding paths through the data
+structure from the root, as in the "callbacks" field.
+
+Example of a method call with cyclic references:
+
+ {
+ "method" : 12,
+ "arguments" : [ { "a" : 5, "b" : [ { "c" : 5 } ] } ],
+ "callbacks" : {},
+ "links" : [ { "from" : [ 0 ], "to" : [ 0, "b", 1 ] } ]
+ }
+This example creates a link to the first argument within the first argument's
+"b" key's second element. The previous data structure could be generated from
+the following javascript where `fn` comes from the remote:
+
+ var data = { a : 5, b : [ { c : 5 } ] };
+ data.b.push(data);
+ fn(data);
+
+Note that links need not necessarily be cyclic, they can just more efficiently
+encode duplicate data, for instance.

0 comments on commit 70fe7e4

Please sign in to comment.