docs: structs
This commit is contained in:
Kagami Hiiragi
parent
5c981309df
commit
782b7e7d27
192
lib/structs.js
192
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue