docs: messages

lib/messages.js

@@ -56,11 +56,33 @@ var randomNonce = bmcrypto.randomBytes(8);
 // TODO(Kagami): User agent and stream numbers size limits per
 // <https://github.com/Bitmessage/PyBitmessage/issues/767>.
 var version = exports.version = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Object} services -
+   * [Service]{@link module:bitmessage/structs.ServicesBitfield}
+   * features to be enabled for this connection
+   * @property {Date} time - Node time
+   * @property {string} remoteHost - IPv4/IPv6 address of the node
+   * receiving this message
+   * @property {number} remotePort - Port of the node receiving this
+   * message
+   * @property {number} port - Incoming port of the node sending this
+   * message
+   * @property {Buffer} nonce - Random nonce used to detect connection
+   * to self
+   * @property {(Array|string|Buffer)} userAgent -
+   * [User agent]{@link module:bitmessage/user-agent} of the node
+   * @property {number[]} streamNumbers - Streams accepted by the node
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/messages.version
+   */
+
   /**
    * Decode `version` message.  
    * NOTE: `nonce` is copied.
    * @param {Buffer} buf - Message
-   * @return {Object} Decoded `version` structure.
+   * @return {DecodeResult}
+   * [Decoded `version` structure.]{@link module:bitmessage/messages.version.DecodeResult}
    */
   decode: function(buf) {
     var decoded = message.decode(buf);
@@ -69,10 +91,8 @@ var version = exports.version = {
   },
 
   /**
-   * Decode `version` message payload.  
+   * Decode `version` message payload.
-   * NOTE: `nonce` is copied.
+   * The same as [decode]{@link module:bitmessage/messages.version.decode}.
-   * @param {Buffer} buf - Message payload
-   * @return {Object} Decoded `version` structure.
    */
   decodePayload: function(buf) {
     // 4 + 8 + 8 + 26 + 26 + 8 + (1+) + (1+)
@@ -109,6 +129,24 @@ var version = exports.version = {
   /**
    * Encode `version` message.
    * @param {Object} opts - Version options
+   * @param {Object=} opts.services -
+   * [Service]{@link module:bitmessage/structs.ServicesBitfield}
+   * features to be enabled for this connection (`NODE_NETWORK` by
+   * default)
+   * @param {Date=} opts.time - Node time (current time by default)
+   * @param {string} opts.remoteHost - IPv4/IPv6 address of the node
+   * receiving this message
+   * @param {number} opts.remotePort - Port of the node receiving this
+   * message
+   * @param {number=} opts.port - Incoming port of the node (8444 by
+   * default)
+   * @param {Buffer=} opts.nonce - Random nonce used to detect connection
+   * to self (unique per node.js process by default)
+   * @param {(Array|string|Buffer)=} opts.userAgent -
+   * [User agent]{@link module:bitmessage/user-agent} of the node
+   * (bitmessage's by default)
+   * @param {Array<number>=} opts.streamNumbers - Streams accepted by the
+   * node (1 by default)
    * @return {Buffer} Encoded message.
    */
   encode: function(opts) {
@@ -118,8 +156,7 @@ var version = exports.version = {
 
   /**
    * Encode `version` message payload.
-   * @param {Object} opts - Version options
+   * The same as [encode]{@link module:bitmessage/messages.version.encode}.
-   * @return {Buffer} Encoded payload.
    */
   encodePayload: function(opts) {
     // Deal with default options.
@@ -166,10 +203,19 @@ var version = exports.version = {
  * @static
  */
 var addr = exports.addr = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Object[]} addrs - List of
+   * [decoded `net_addr` structures]{@link module:bitmessage/structs.net_addr.DecodeResult}
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/messages.addr
+   */
+
   /**
    * Decode `addr` message.
    * @param {Buffer} buf - Message
-   * @return {Object} Decoded `addr` structure.
+   * @return {DecodeResult}
+   * [Decoded `addr` structure.]{@link module:bitmessage/messages.addr.DecodeResult}
    */
   decode: function(buf) {
     var decoded = message.decode(buf);
@@ -179,8 +225,7 @@ var addr = exports.addr = {
 
   /**
    * Decode `addr` message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decode]{@link module:bitmessage/messages.addr.decode}.
-   * @return {Object} Decoded `addr` structure.
    */
   decodePayload: function(buf) {
     var decoded = structs.var_int.decode(buf);
@@ -202,7 +247,8 @@ var addr = exports.addr = {
 
   /**
    * Encode `addr` message.
-   * @param {Object[]} addrs - Network addresses
+   * @param {Object[]} addrs - List of
+   * [net_addr encode options]{@link module:bitmessage/structs.net_addr.encode}
    * @return {Buffer} Encoded message.
    */
   encode: function(addrs) {
@@ -212,8 +258,7 @@ var addr = exports.addr = {
 
   /**
    * Encode `addr` message payload.
-   * @param {Object[]} addrs - Network addresses
+   * The same as [encode]{@link module:bitmessage/messages.addr.encode}.
-   * @return {Buffer} Encoded payload.
    */
   encodePayload: function(addrs) {
     assert(addrs.length <= 1000, "Too many address entires");
@@ -231,10 +276,19 @@ var addr = exports.addr = {
  * @static
  */
 var inv = exports.inv = {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Buffer[]} inventory - List of
+   * [inventory vectors]{@link module:bitmessage/structs.inv_vect}
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/messages.inv
+   */
+
   /**
    * Decode `inv` message.
    * @param {Buffer} buf - Message
-   * @return {Object} Decoded `inv` structure.
+   * @return {DecodeResult}
+   * [Decoded `inv` structure.]{@link module:bitmessage/messages.inv.DecodeResult}
    */
   decode: function(buf) {
     var decoded = message.decode(buf);
@@ -244,8 +298,7 @@ var inv = exports.inv = {
 
   /**
    * Decode `inv` message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decode]{@link module:bitmessage/messages.inv.decode}.
-   * @return {Object} Decoded `inv` structure.
    */
   decodePayload: function(buf) {
     var decoded = structs.var_int.decode(buf);
@@ -267,7 +320,8 @@ var inv = exports.inv = {
 
   /**
    * Encode `inv` message.
-   * @param {Buffer[]} inventory - Inventory vector list
+   * @param {Buffer[]} inventory -
+   * [Inventory vector]{@link module:bitmessage/structs.inv_vect} list
    * @return {Buffer} Encoded message.
    */
   encode: function(inventory) {
@@ -277,8 +331,7 @@ var inv = exports.inv = {
 
   /**
    * Encode `inv` message payload.
-   * @param {Buffer[]} inventory - Inventory vector list
+   * The same as [encode]{@link module:bitmessage/messages.inv.encode}.
-   * @return {Buffer} Encoded payload.
    */
   encodePayload: function(inventory) {
     assert(inventory.length <= 50000, "Too many inventory entires");
@@ -296,10 +349,19 @@ var inv = exports.inv = {
  * @namespace
  */
 exports.getdata = objectAssign({}, inv, {
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {Buffer[]} inventory - List of
+   * [inventory vectors]{@link module:bitmessage/structs.inv_vect}
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/messages.getdata
+   */
+
   /**
    * Decode `getdata` message.
    * @param {Buffer} buf - Message
-   * @return {Object} Decoded `getdata` structure.
+   * @return {DecodeResult}
+   * [Decoded `getdata` structure.]{@link module:bitmessage/messages.getdata.DecodeResult}
    * @memberof module:bitmessage/messages.getdata
    */
   decode: function(buf) {
@@ -307,9 +369,18 @@ exports.getdata = objectAssign({}, inv, {
     assert(decoded.command === "getdata", "Bad command");
     return inv.decodePayload(decoded.payload);
   },
+
+  /**
+   * Decode `getdata` message payload.
+   * The same as [decode]{@link module:bitmessage/messages.getdata.decode}.
+   * @function decodePayload
+   * @memberof module:bitmessage/messages.getdata
+   */
+
   /**
    * Encode `getdata` message.
-   * @param {Buffer[]} inventory - Inventory vector list
+   * @param {Buffer[]} inventory -
+   * [Inventory vector]{@link module:bitmessage/structs.inv_vect} list
    * @return {Buffer} Encoded message.
    * @memberof module:bitmessage/messages.getdata
    */
@@ -317,17 +388,10 @@ exports.getdata = objectAssign({}, inv, {
     var payload = inv.encodePayload(inventory);
     return message.encode("getdata", payload);
   },
-  /**
+
-   * Decode `getdata` message payload.
-   * @param {Buffer} buf - Message payload
-   * @return {Object} Decoded `inv` structure.
-   * @function decodePayload
-   * @memberof module:bitmessage/messages.getdata
-   */
   /**
    * Encode `getdata` message payload.
-   * @param {Buffer[]} inventory - Inventory vector list
+   * The same as [encode]{@link module:bitmessage/messages.getdata.encode}.
-   * @return {Buffer} Encoded payload.
    * @function encodePayload
    * @memberof module:bitmessage/messages.getdata
    */
@@ -359,10 +423,24 @@ var error = exports.error = {
    */
   FATAL: 2,
 
+  /**
+   * @typedef {Object} DecodeResult
+   * @property {number} fatal - Type of the error
+   * @property {number} banTime - The other node informs that it will
+   * not accept further connections for this number of seconds
+   * @property {?Buffer} vector -
+   * [Inventory vector]{@link module:bitmessage/structs.inv_vect}
+   * related to the error
+   * @property {string} errorText - A human-readable error description
+   * @property {number} length - Real data length
+   * @memberof module:bitmessage/messages.error
+   */
+
   /**
    * Decode `error` message.
    * @param {Buffer} buf - Message
-   * @return {Object} Decoded `error` structure.
+   * @return {DecodeResult}
+   * [Decoded `error` structure.]{@link module:bitmessage/messages.error.DecodeResult}
    */
   decode: function(buf) {
     var decoded = message.decode(buf);
@@ -372,8 +450,7 @@ var error = exports.error = {
 
   /**
    * Decode `error` message payload.
-   * @param {Buffer} buf - Message payload
+   * The same as [decode]{@link module:bitmessage/messages.error.decode}.
-   * @return {Object} Decoded `error` structure.
    */
   decodePayload: function(buf) {
     assert(buf.length >= 4, "Buffer is too small");
@@ -413,6 +490,16 @@ var error = exports.error = {
   /**
    * Encode `error` message.
    * @param {Object} opts - Error options
+   * @param {number=} opts.fatal - Type of the error
+   * ([warning]{@link module:bitmessage/messages.error.WARNING} by
+   * default)
+   * @param {number=} opts.banTime - Inform the other node, that you
+   * will not accept further connections for this number of seconds (0
+   * by default)
+   * @param {Buffer=} opts.vector - A 32-byte
+   * [inventory vector]{@link module:bitmessage/structs.inv_vect}
+   * related to the error (empty by default)
+   * @param {string} opts.errorText - A human-readable error description
    * @return {Buffer} Encoded message.
    */
   encode: function(opts) {
@@ -422,8 +509,7 @@ var error = exports.error = {
 
   /**
    * Encode `error` message payload.
-   * @param {Object} opts - Error options
+   * The same as [encode]{@link module:bitmessage/messages.error.encode}.
-   * @return {Buffer} Encoded payload.
    */
   encodePayload: function(opts) {
     var fatal = opts.fatal || error.WARNING;

lib/net/tcp.js

@@ -122,6 +122,7 @@ TcpTransport.prototype._setupClient = function(client, accepted) {
   self.on("message", function(command) {
     if (!established) {
       // TODO: Process version data.
+      // TODO: Disconnect if proto version < 3.
       if (command === "version") {
         if (verackSent) {
           return;

lib/net/ws.browser.js

@@ -65,6 +65,7 @@ WsTransport.prototype.connect = function(url, protocols) {
   self.on("message", function(command) {
     if (!established) {
       // TODO: Process version data.
+      // TODO: Disconnect if proto version < 3.
       if (command === "version") {
         if (verackSent) {
           return;

lib/net/ws.js

@@ -121,6 +121,7 @@ WsTransport.prototype._setupClient = function(client, accepted) {
   self.on("message", function(command) {
     if (!established) {
       // TODO: Process version data.
+      // TODO: Disconnect if proto version < 3.
       if (command === "version") {
         if (verackSent) {
           return;