docs: structs

This commit is contained in:
Kagami Hiiragi 2015-02-11 15:18:38 +03:00
parent 5c981309df
commit 782b7e7d27

View File

@ -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);
@ -258,10 +308,7 @@ 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.
* 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.