From 96d7074b2d59853dbc013bfe6f536c7d831c8e28 Mon Sep 17 00:00:00 2001 From: Kagami Hiiragi Date: Wed, 11 Feb 2015 18:16:43 +0300 Subject: [PATCH] docs: messages --- lib/messages.js | 156 ++++++++++++++++++++++++++++++++---------- lib/net/tcp.js | 1 + lib/net/ws.browser.js | 1 + lib/net/ws.js | 1 + 4 files changed, 124 insertions(+), 35 deletions(-) diff --git a/lib/messages.js b/lib/messages.js index 27e9125..5f8d9a5 100644 --- a/lib/messages.js +++ b/lib/messages.js @@ -56,11 +56,33 @@ var randomNonce = bmcrypto.randomBytes(8); // TODO(Kagami): User agent and stream numbers size limits per // . 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. - * NOTE: `nonce` is copied. - * @param {Buffer} buf - Message payload - * @return {Object} Decoded `version` structure. + * Decode `version` message payload. + * The same as [decode]{@link module:bitmessage/messages.version.decode}. */ 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=} 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 - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/messages.version.encode}. */ 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 - * @return {Object} Decoded `addr` structure. + * The same as [decode]{@link module:bitmessage/messages.addr.decode}. */ 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 - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/messages.addr.encode}. */ 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 - * @return {Object} Decoded `inv` structure. + * The same as [decode]{@link module:bitmessage/messages.inv.decode}. */ 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 - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/messages.inv.encode}. */ 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 - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/messages.getdata.encode}. * @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 - * @return {Object} Decoded `error` structure. + * The same as [decode]{@link module:bitmessage/messages.error.decode}. */ 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 - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/messages.error.encode}. */ encodePayload: function(opts) { var fatal = opts.fatal || error.WARNING; diff --git a/lib/net/tcp.js b/lib/net/tcp.js index 43caeda..96d8dd5 100644 --- a/lib/net/tcp.js +++ b/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; diff --git a/lib/net/ws.browser.js b/lib/net/ws.browser.js index 7832c45..dc66e82 100644 --- a/lib/net/ws.browser.js +++ b/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; diff --git a/lib/net/ws.js b/lib/net/ws.js index df44115..d4f0f05 100644 --- a/lib/net/ws.js +++ b/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;