From 782b7e7d2790f15acb78d721cf25b5a07f96d3df Mon Sep 17 00:00:00 2001 From: Kagami Hiiragi Date: Wed, 11 Feb 2015 15:18:38 +0300 Subject: [PATCH] docs: structs --- lib/structs.js | 192 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 165 insertions(+), 27 deletions(-) diff --git a/lib/structs.js b/lib/structs.js index 4ccf4ae..4353f46 100644 --- a/lib/structs.js +++ b/lib/structs.js @@ -3,7 +3,6 @@ * @see {@link https://bitmessage.org/wiki/Protocol_specification#Common_structures} * @module bitmessage/structs */ -// TODO(Kagami): Document object-like params. "use strict"; @@ -83,13 +82,25 @@ var message = exports.message = { */ MAGIC: 0xE9BEB4D9, + /** + * @typedef {Object} TryDecodeResult + * @property {Object} message - Decoded message + * @property {string} message.command - Message command + * @property {Buffer} message.payload - Message payload + * @property {number} message.length - Full message length + * @property {Error} error - ...or decoding error + * @property {Buffer} rest - The rest of the input buffer after + * processing message + * @memberof module:bitmessage/structs.message + */ + /** * Decode message in "stream" mode. * NOTE: message payload and `rest` are copied (so the runtime can GC * processed buffer data). * @param {Buffer} buf - Data buffer - * @return {?{?message: Object, ?error: Error, rest: Buffer}} Decoded - * result. + * @return {?TryDecodeResult} + * [Decoded result.]{@link module:bitmessage/structs.message.TryDecodeResult} */ tryDecode: function(buf) { if (buf.length < 24) { @@ -169,12 +180,21 @@ var message = exports.message = { return res; }, + /** + * @typedef {Object} DecodeResult + * @property {string} command - Message command + * @property {Buffer} payload - Message payload + * @property {number} length - Full message length + * @property {Buffer} rest - The rest of the input buffer + * @memberof module:bitmessage/structs.message + */ + /** * Decode message structure. * NOTE: `payload` is copied, `rest` references input buffer. * @param {Buffer} buf - Buffer that starts with encoded message - * @return {{command: string, payload: Buffer, length: number, rest: Buffer}} - * Decoded message structure. + * @return {DecodeResult} + * [Decoded message structure.]{@link module:bitmessage/structs.message.DecodeResult} */ decode: function(buf) { assert(buf.length >= 24, "Buffer is too small"); @@ -237,18 +257,48 @@ var message = exports.message = { * @static */ var object = exports.object = { - // Known types. + /** + * [getpubkey]{@link module:bitmessage/objects.getpubkey} object type. + * @constant {number} + */ GETPUBKEY: 0, + /** + * [pubkey]{@link module:bitmessage/objects.pubkey} object type. + * @constant {number} + */ PUBKEY: 1, + /** + * [msg]{@link module:bitmessage/objects.msg} object type. + * @constant {number} + */ MSG: 2, + /** + * [broadcast]{@link module:bitmessage/objects.broadcast} object type. + * @constant {number} + */ BROADCAST: 3, + /** + * @typedef {Object} DecodeResult + * @property {Buffer} nonce - A 8-byte object nonce + * @property {number} ttl - Time to live in seconds + * @property {number} type - Object type + * @property {number} version - Object version + * @property {number} stream - Object stream + * @property {number} headerLength - Length of the object header + * @property {Buffer} objectPayload - Object payload + * @memberof module:bitmessage/structs.object + */ + /** * Decode `object` message. * NOTE: `nonce` and `objectPayload` are copied. * @param {Buffer} buf - Message * @param {Object=} opts - Decoding options - * @return {Object} Decoded `object` structure. + * @param {boolean} opts.allowExpired - Allow expired objects + * @param {boolean} opts.skipPow - Do not validate object POW + * @return {DecodeResult} + * [Decoded `object` structure.]{@link module:bitmessage/structs.object.DecodeResult} */ decode: function(buf, opts) { var decoded = message.decode(buf); @@ -257,11 +307,8 @@ var object = exports.object = { }, /** - * Decode `object` message payload. - * NOTE: `nonce` and `objectPayload` are copied. - * @param {Buffer} buf - Message payload - * @param {Object=} opts - Decoding options - * @return {Object} Decoded `object` structure. + * Decode `object` message payload. + * The same as [decode]{@link module:bitmessage/structs.object.decode}. */ decodePayload: function(buf, opts) { opts = opts || {}; @@ -309,6 +356,12 @@ var object = exports.object = { /** * Encode `object` message. * @param {Object} opts - Object options + * @param {Object} opts.nonce - A 8-byte object nonce + * @param {number} opts.ttl - Time to live in seconds + * @param {number} opts.type - Object type + * @param {number} opts.version - Object version + * @param {number=} opts.stream - Object stream (1 by default) + * @param {Buffer} opts.objectPayload - Object payload * @return {Buffer} Encoded message. */ encode: function(opts) { @@ -318,8 +371,7 @@ var object = exports.object = { /** * Encode `object` message payload. - * @param {Object} opts - Object options - * @return {Buffer} Encoded payload. + * The same as [encode]{@link module:bitmessage/structs.object.encode}. */ encodePayload: function(opts) { // NOTE(Kagami): We do not try to calculate nonce here if it is not @@ -343,6 +395,11 @@ var object = exports.object = { * Encode `object` message payload without leading nonce field (may be * useful if you are going to calculate it later). * @param {Object} opts - Object options + * @param {number} opts.ttl - Time to live in seconds + * @param {number} opts.type - Object type + * @param {number} opts.version - Object version + * @param {number=} opts.stream - Object stream (1 by default) + * @param {Buffer} opts.objectPayload - Object payload * @return {Buffer} Encoded payload. */ encodePayloadWithoutNonce: function(opts) { @@ -371,12 +428,20 @@ var object = exports.object = { * @static */ var var_int = exports.var_int = { + /** + * @typedef {Object} DecodeResult + * @property {number} value - Stored value + * @property {number} length - `var_int` full length + * @property {Buffer} rest - The rest of the input buffer + * @memberof module:bitmessage/structs.var_int + */ + /** * Decode `var_int`. * NOTE: `rest` references input buffer. * @param {Buffer} buf - A buffer that starts with encoded `var_int` - * @return {{value: number, length: number, rest: Buffer}} - * Decoded `var_int` structure. + * @return {DecodeResult} + * [Decoded `var_int` structure.]{@link module:bitmessage/structs.var_int.DecodeResult} */ decode: function(buf) { var value, length; @@ -464,12 +529,20 @@ var var_int = exports.var_int = { * @namespace */ exports.var_str = { + /** + * @typedef {Object} DecodeResult + * @property {number} str - The string itself + * @property {number} length - `var_str` full length + * @property {Buffer} rest - The rest of the input buffer + * @memberof module:bitmessage/structs.var_str + */ + /** * Decode `var_str`. * NOTE: `rest` references input buffer. * @param {Buffer} buf - A buffer that starts with encoded `var_str` - * @return {{str: string, length: number, rest: Buffer}} - * Decoded `var_str` structure. + * @return {DecodeResult} + * [Decoded `var_str` structure.]{@link module:bitmessage/structs.var_str.DecodeResult} */ decode: function(buf) { var decoded = var_int.decode(buf); @@ -500,13 +573,21 @@ exports.var_str = { * @namespace */ exports.var_int_list = { + /** + * @typedef {Object} DecodeResult + * @property {number} list - Stored numbers + * @property {number} length - `var_int_list` full length + * @property {Buffer} rest - The rest of the input buffer + * @memberof module:bitmessage/structs.var_int_list + */ + /** * Decode `var_int_list`. * NOTE: `rest` references input buffer. * @param {Buffer} buf - A buffer that starts with encoded * `var_int_list` - * @return {{list: number[], length: number, rest: Buffer}} - * Decoded `var_int_list` structure. + * @return {DecodeResult} + * [Decoded `var_int_list` structure.]{@link module:bitmessage/structs.var_int_list.DecodeResult} */ decode: function(buf) { var decoded = var_int.decode(buf); @@ -636,13 +717,28 @@ function inet_pton(str) { * @namespace */ exports.net_addr = { + /** + * @typedef {Object} DecodeResult + * @property {Date} time - Time the node was last active, not included + * in short mode + * @property {number} stream - Stream number of the node, not included + * in short mode + * @property {Object} services - + * [Services]{@link module:bitmessage/structs.ServicesBitfield} + * provided by the node + * @property {string} host - IPv4/IPv6 address of the node + * @property {number} port - Incoming port of the node + * @memberof module:bitmessage/structs.net_addr + */ + /** * Decode `net_addr`. * @param {Buffer} buf - A buffer that contains encoded `net_addr` * @param {Object=} opts - Decoding options; use `short` option to * decode `net_addr` from * [version message]{@link module:bitmessage/messages.version} - * @return {Object} Decoded `net_addr` structure. + * @return {DecodeResult} + * [Decoded `net_addr` structure.]{@link module:bitmessage/structs.net_addr.DecodeResult} */ decode: function(buf, opts) { var short = !!(opts || {}).short; @@ -670,9 +766,19 @@ exports.net_addr = { /** * Encode `net_addr`. - * @param {Object} opts - Encode options; use `short` option to encode - * `net_addr` for + * @param {Object} opts - Encoding options + * @param {boolean=} opts.short - Encode `net_addr` for * [version message]{@link module:bitmessage/messages.version} + * (false by default) + * @param {Date=} opts.time - Time the node was last active, not + * included in short mode (current time by default) + * @param {number=} opts.stream - Stream number of the node, not + * included in short mode (1 by default) + * @param {Object=} opts.services - + * [Services]{@link module:bitmessage/structs.ServicesBitfield} + * provided by the node (`NODE_NETWORK` by default) + * @param {string} opts.host - IPv4/IPv6 address of the node + * @param {number} opts.port - Incoming port of the node * @return {Buffer} Encoded `net_addr`. */ encode: function(opts) { @@ -707,8 +813,10 @@ exports.net_addr = { * @see {@link https://bitmessage.org/wiki/Protocol_specification#Inventory_Vectors} * @namespace */ -// Only encode operation is defined because decode is impossible. exports.inv_vect = { + // NOTE(Kagami): Only encode operation is defined because decoding of + // the encoded vector is impossible. + /** * Encode inventory vector. * @param {Buffer} buf - Payload to calculate the inventory vector for @@ -725,18 +833,34 @@ exports.inv_vect = { * @namespace encrypted * @static */ +/** + * @typedef {Object} DecodeResult + * @property {Buffer} iv - Initialization vector (16 bytes) + * @property {Buffer} ephemPrivateKey - Ephemeral private key (32 bytes) + * @property {Buffer} ciphertext - The result of encryption (variable + * size) + * @property {Buffer} mac - Message authentication code (32 bytes) + * @memberof module:bitmessage/structs.encrypted + */ /** * Decode encrypted payload. * NOTE: all structure members are copied. * @param {Buffer} buf - A buffer that contains encrypted payload - * @return {Object} Decoded encrypted structure. + * @return {DecodeResult} + * [Decoded `encrypted` structure.]{@link module:bitmessage/structs.encrypted.DecodeResult} * @function decode * @memberof module:bitmessage/structs.encrypted */ /** * Encode `encrypted`. - * @param {Object} opts - Encode options - * @return {Buffer} Encoded encrypted payload. + * @param {Object} opts - Encoding options + * @param {Buffer} opts.iv - Initialization vector (16 bytes) + * @param {Buffer} opts.ephemPrivateKey - Ephemeral private key (32 + * bytes) + * @param {Buffer} opts.ciphertext - The result of encryption (variable + * size) + * @param {Buffer} opts.mac - Message authentication code (32 bytes) + * @return {Buffer} Encoded `encrypted` payload. * @function encode * @memberof module:bitmessage/structs.encrypted */ @@ -834,6 +958,13 @@ var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), { * @return {Object} Returns self so methods can be chained. * @memberof module:bitmessage/structs.ServicesBitfield */ + /** + * The contents of the bitfield. + * @type {Buffer} + * @var buffer + * @instance + * @memberof module:bitmessage/structs.ServicesBitfield + */ /** * Bit index indicating normal network node. @@ -876,6 +1007,13 @@ exports.PubkeyBitfield = objectAssign(Bitfield(32), { * @return {Object} Returns self so methods can be chained. * @memberof module:bitmessage/structs.PubkeyBitfield */ + /** + * The contents of the bitfield. + * @type {Buffer} + * @var buffer + * @instance + * @memberof module:bitmessage/structs.PubkeyBitfield + */ /** * Bit index.