docs: messages
This commit is contained in:
Kagami Hiiragi
parent
f619a066c6
commit
96d7074b2d
156
lib/messages.js
156
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.
|
||||
* 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<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
|
||||
* @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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue