Bitmessage/bitmessage-js
2
0
Fork 1
Code Issues 1 Pull Requests 1 Actions Packages Releases Activity

Improve documentation

Browse Source
This commit is contained in:
Kagami Hiiragi 2015-01-31 14:51:35 +03:00
parent bbe3ec2fa8
commit 9f368d32fb
9 changed files with 131 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
lib/address.js
View File

@ -47,9 +47,9 @@ Address.prototype.clone = function() {
};
/**
* Test if given object is an Address instance. NOTE: Implementation is
* just simple `instanceof` but it improves readability and consistent
* with `isArray`, `isBuffer`, etc.
* Test if given object is an Address instance.
* NOTE: Implementation is just simple `instanceof` but it improves
* readability and consistent with `isArray`, `isBuffer`, etc.
* @param {Object} obj - Given object
* @return {boolean}
*/
@ -59,7 +59,7 @@ Address.isAddress = function(obj) {
/**
* Parse Bitmessage address into address object.
* @param {String} str - Address string (with or without `BM-` prefix)
* @param {string} str - Address string (with or without `BM-` prefix)
* @return {Address} Decoded address object.
*/
Address.decode = function(str) {
@ -116,8 +116,8 @@ function getaddrhash(addr) {
}
/**
* Calculate the encryption key used to encrypt/decrypt {@link pubkey}
* objects.
* Calculate the encryption key used to encrypt/decrypt
* [pubkey]{@link module:bitmessage/objects.pubkey} objects.
* @return {Buffer} A 32-byte private key.
*/
Address.prototype.getPubkeyPrivateKey = function() {
@ -126,7 +126,8 @@ Address.prototype.getPubkeyPrivateKey = function() {
/**
* Calculate the corresponding public key for encryption key used to
* encrypt/decrypt {@link pubkey} objects.
* encrypt/decrypt
* [pubkey]{@link module:bitmessage/objects.pubkey} objects.
* @return {Buffer} A 65-byte public key.
*/
Address.prototype.getPubkeyPublicKey = function() {
@ -135,7 +136,7 @@ Address.prototype.getPubkeyPublicKey = function() {
/**
* Calculate the encryption key used to encrypt/decrypt
* {@link broadcast} objects.
* [broadcast]{@link module:bitmessage/objects.broadcast} objects.
* @return {Buffer} A 32-byte private key.
*/
Address.prototype.getBroadcastPrivateKey = function() {
@ -148,7 +149,8 @@ Address.prototype.getBroadcastPrivateKey = function() {
/**
* Calculate the corresponding public key for encryption key used to
* encrypt/decrypt {@link broadcast} objects.
* encrypt/decrypt
* [broadcast]{@link module:bitmessage/objects.broadcast} objects.
* @return {Buffer} A 65-byte public key.
*/
Address.prototype.getBroadcastPublicKey = function() {

11
lib/crypto.js
View File

@ -1,6 +1,6 @@
/**
* Isomorphic Bitmessage crypto module. Reexports platform-dependent
* implementations and and also some common routines.
* implementations and also some common routines.
* @module bitmessage/crypto
*/
@ -72,7 +72,7 @@ exports.getPublic = eccrypto.getPublic;
/**
* Sign message using ecdsa-with-sha1 scheme.
* @param {Buffer} privateKey - A 32-byte private key
* @msg {Buffer} msg - The message being signed
* @param {Buffer} msg - The message being signed
* @return {Promise.<Buffer>} A promise that contains signature in DER
* format when fulfilled.
*/
@ -84,7 +84,7 @@ exports.sign = function(privateKey, msg) {
/**
* Verify signature using ecdsa-with-sha1 scheme.
* @param {Buffer} publicKey - A 65-byte public key
* @msg {Buffer} msg - The message being verified
* @param {Buffer} msg - The message being verified
* @param {Buffer} sig - The signature in DER format
* @return {Promise.<undefined>} A promise that resolves on correct
* signature and rejects on bad key or signature.
@ -152,6 +152,9 @@ var encrypted = exports.encrypted = {
* @return {Promise.<Buffer>} - A promise that resolves with the buffer
* in `encrypted` format successful encryption and rejects on failure.
*/
// TODO(Kagami): Properly document `opts`. Documenting multiple
// function arguments with options object at the end for now gives
// strange results (probably a bug in jsdoc).
exports.encrypt = function(publicKeyTo, msg, opts) {
return eccrypto.encrypt(publicKeyTo, msg, opts).then(function(encObj) {
return encrypted.encode(encObj);
@ -162,7 +165,7 @@ exports.encrypt = function(publicKeyTo, msg, opts) {
* Decrypt message using given private key.
* @param {Buffer} privateKey - A 32-byte private key of recepient of
* the mesage
* @param {Buffer} buf - encrypted data
* @param {Buffer} buf - Encrypted data
* @return {Promise.<Buffer>} - A promise that resolves with the
* plaintext on successful decryption and rejects on failure.
*/

7
lib/index.js
View File

@ -5,7 +5,10 @@
"use strict";
/** Current protocol version. */
/**
* Current protocol version.
* @constant {number}
*/
exports.PROTOCOL_VERSION = require("./_util").PROTOCOL_VERSION;
/** [Common structures.]{@link module:bitmessage/structs} */
@ -22,5 +25,5 @@ exports.POW = require("./pow");
/** [Working with addresses.]{@link module:bitmessage/address} */
exports.Address = require("./address");
/** [User Agent.]{@link module:bitmessage/user-agent} */
/** [User agent.]{@link module:bitmessage/user-agent} */
exports.UserAgent = require("./user-agent");

53
lib/messages.js
View File

@ -21,11 +21,12 @@ var ServicesBitfield = structs.ServicesBitfield;
/**
* Try to get command of the given encoded message.
* Note that this function doesn't do any validation because it is
* already provided by `message.decode` routine. Normally you call this
* for each incoming message and then call decode function of the
* appropriate message handler.
* already provided by
* [message.decode]{@link module:bitmessage/structs.message.decode}
* routine. Normally you call this for each incoming message and then
* call decode function of the appropriate message handler.
* @param {Buffer} buf - Buffer that starts with encoded message
* @return {?string} Message's command if any
* @return {?string} Message's command if any.
*/
exports.getCommand = function(buf) {
if (buf.length < 16) {
@ -49,7 +50,10 @@ exports.getCommand = function(buf) {
* @static
*/
var version = exports.version = {
/** Random nonce used to detect connections to self. */
/**
* Random nonce used to detect connections to self.
* @const {Buffer}
*/
NONCE: new Buffer("20bde0a3355dad78", "hex"),
/**
@ -260,7 +264,7 @@ var inv = exports.inv = {
/**
* Encode `inv` message.
* @param {Buffer[]} inventory - Inventory vector list (encoded)
* @param {Buffer[]} inventory - Inventory vector list
* @return {Buffer} Encoded message.
*/
encode: function(inventory) {
@ -270,7 +274,7 @@ var inv = exports.inv = {
/**
* Encode `inv` message payload.
* @param {Buffer[]} inventory - Inventory vector list (encoded)
* @param {Buffer[]} inventory - Inventory vector list
* @return {Buffer} Encoded payload.
*/
encodePayload: function(inventory) {
@ -281,22 +285,48 @@ var inv = exports.inv = {
};
/**
* `getdata` message. `getdata` is used in response to an `inv` message
* to retrieve the content of a specific object after filtering known
* elements.
* `getdata` message. `getdata` is used in response to an
* [inv]{@link module:bitmessage/messages.inv} message to retrieve the
* content of a specific object after filtering known elements.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#getdata}
* @namespace
*/
exports.getdata = objectAssign({}, inv, {
/**
* Decode `getdata` message.
* @param {Buffer} buf - Message
* @return {Object} Decoded `getdata` structure.
* @memberof module:bitmessage/messages.getdata
*/
decode: function(buf) {
var decoded = message.decode(buf);
assert(decoded.command === "getdata", "Bad command");
return inv.decodePayload(decoded.payload);
},
/**
* Encode `getdata` message.
* @param {Buffer[]} inventory - Inventory vector list
* @return {Buffer} Encoded message.
* @memberof module:bitmessage/messages.getdata
*/
encode: function(inventory) {
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.
* @function encodePayload
* @memberof module:bitmessage/messages.getdata
*/
});
/**
@ -308,17 +338,20 @@ exports.getdata = objectAssign({}, inv, {
var error = exports.error = {
/**
* Just a warning.
* @constant {number}
*/
WARNING: 0,
/**
* It's an error, something was going wrong (e.g. an object got lost).
* @constant {number}
*/
ERROR: 1,
/**
* It's a fatal error. The node will drop the line for that error and
* maybe ban you for some time.
* @constant {number}
*/
FATAL: 2,

40
lib/objects.js
View File

@ -1,5 +1,5 @@
/**
* Working with objects.
* Working with objects.
* NOTE: Most operations with objects in this module are asynchronous
* and return promises.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#Object_types}
@ -30,11 +30,12 @@ var object = structs.object;
/**
* Try to get type of the given encoded object message.
* Note that this function doesn't do any validation because it is
* already provided by `object.decode` routine. Normally you call this
* for each incoming object message and then call decode function of the
* appropriate object handler.
* already provided by
* [object.decode]{@link module:bitmessage/structs.object.decode}
* routine. Normally you call this for each incoming object message and
* then call decode function of the appropriate object handler.
* @param {Buffer} buf - Buffer that starts with encoded object message
* @return {?integer} Object's type if any
* @return {?number} Object's type if any.
*/
exports.getType = function(buf) {
// Message header: 4 + 12 + 4 + 4
@ -48,11 +49,13 @@ exports.getType = function(buf) {
/**
* Try to get type of the given object message payload.
* Note that this function doesn't do any validation because it is
* already provided by `object.decodePayload` routine. Normally you call
* this for each incoming object message payload and then call decode
* function of the appropriate object handler.
* already provided by
* [object.decodePayload]{@link module:bitmessage/structs.object.decodePayload}
* routine. Normally you call this for each incoming object message
* payload and then call decode function of the appropriate object
* handler.
* @param {Buffer} buf - Buffer that starts with object message payload
* @return {?integer} Object's type if any
* @return {?number} Object's type if any.
*/
exports.getPayloadType = function(buf) {
// Object header: 8 + 8 + 4
@ -258,11 +261,6 @@ var pubkey = exports.pubkey = {
* Decode `pubkey` object message payload.
* @param {Buffer} buf - Message payload
* @param {?Object} opts - Decoding options
* @param {?(Address[]|Address|Object)} opts.needed - Address objects
* which represent pubkeys that we are interested in. This is used
* only for pubkeys v4. `needed` is either single address or addresses
* array or Object addr-by-tag. Time to match the key is O(1), O(n),
* O(1) respectfully.
* @return {Promise.<Object>} A promise that contains decoded `pubkey`
* object structure when fulfilled.
*/
@ -526,22 +524,25 @@ var msg = exports.msg = {
/**
* Any data with this number may be ignored. The sending node might
* simply be sharing its public key with you.
* @constant {number}
*/
IGNORE: 0,
/**
* UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings
* of data, like URIs or magnet links.
* @constant {number}
*/
TRIVIAL: 1,
/**
* UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
* @constant {number}
*/
SIMPLE: 2,
/**
* Decode `msg` object message.
* @param {Buffer} buf - Message
* @param {?Object} opts - Decoding options
* @param {Object} opts - Decoding options
* @return {Promise.<Object>} A promise that contains decoded `msg`
* object structure when fulfilled.
*/
@ -557,8 +558,6 @@ var msg = exports.msg = {
* Decode `msg` object message payload.
* @param {Buffer} buf - Message payload
* @param {Object} opts - Decoding options
* @param {(Address[]|Address)} opts.identities - Address objects used
* to decrypt the message
* @return {Promise.<Object>} A promise that contains decoded `msg`
* object structure when fulfilled.
*/
@ -786,7 +785,7 @@ var broadcast = exports.broadcast = {
/**
* Decode `broadcast` object message.
* @param {Buffer} buf - Message
* @param {?Object} opts - Decoding options
* @param {Object} opts - Decoding options
* @return {Promise.<Object>} A promise that contains decoded
* `broadcast` object structure when fulfilled.
*/
@ -802,11 +801,6 @@ var broadcast = exports.broadcast = {
* Decode `broadcast` object message payload.
* @param {Buffer} buf - Message payload
* @param {Object} opts - Decoding options
* @param {(Address[]|Address|Object)} opts.subscriptions - Address
* objects which represent broadcast subscriptions. `subscriptions` is
* either single address or addresses array or Object
* addr-by-tag/addr-by-ripe. Time to match the key is O(1), O(n), O(1)
* respectfully.
* @return {Promise.<Object>} A promise that contains decoded `pubkey`
* object structure when fulfilled.
*/

3
lib/pow.js
View File

@ -13,9 +13,10 @@ var platform = require("./platform");
var util = require("./_util");
/**
* Calculate target
* Calculate target.
* @param {Object} opts - Target options
* @return {number} Target.
* @function
* @static
*/
// Just a wrapper around platform-specific implementation.

51
lib/structs.js
View File

@ -35,11 +35,14 @@ function getmsgchecksum(data) {
* @static
*/
var message = exports.message = {
/** Bitmessage magic value. */
/**
* Bitmessage magic value.
* @constant {number}
*/
MAGIC: 0xE9BEB4D9,
/**
* Decode message structure.
* 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}}
@ -95,9 +98,9 @@ var message = exports.message = {
};
/**
* `object` message. An `object` is a message which is shared throughout
* a stream. It is the only message which propagates; all others are
* only between two nodes.
* An `object` is a message which is shared throughout a stream. It is
* the only message which propagates; all others are only between two
* nodes.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#object}
* @namespace
* @static
@ -110,7 +113,7 @@ var object = exports.object = {
BROADCAST: 3,
/**
* Decode `object` message.
* Decode `object` message.
* NOTE: `nonce` and `objectPayload` are copied.
* @param {Buffer} buf - Message
* @param {?Object} opts - Decoding options
@ -123,7 +126,7 @@ var object = exports.object = {
},
/**
* Decode `object` message payload.
* Decode `object` message payload.
* NOTE: `nonce` and `objectPayload` are copied.
* @param {Buffer} buf - Message payload
* @param {?Object} opts - Decoding options
@ -238,7 +241,7 @@ var object = exports.object = {
*/
var var_int = exports.var_int = {
/**
* Decode `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}}
@ -331,7 +334,7 @@ var var_int = exports.var_int = {
*/
exports.var_str = {
/**
* Decode `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}}
@ -367,7 +370,7 @@ exports.var_str = {
*/
exports.var_int_list = {
/**
* Decode `var_int_list`.
* Decode `var_int_list`.
* NOTE: `rest` references input buffer.
* @param {Buffer} buf - A buffer that starts with encoded
* `var_int_list`
@ -496,7 +499,9 @@ exports.net_addr = {
/**
* Decode `net_addr`.
* @param {Buffer} buf - A buffer that contains encoded `net_addr`
* @param {?Object} opts - Decode options
* @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.
*/
decode: function(buf, opts) {
@ -526,7 +531,8 @@ exports.net_addr = {
/**
* Encode `net_addr`.
* @param {Object} opts - Encode options; use `short` option to encode
* `net_addr` used in version message
* `net_addr` for
* [version message]{@link module:bitmessage/messages.version}
* @return {Buffer} Encoded `net_addr`.
*/
encode: function(opts) {
@ -565,7 +571,7 @@ exports.net_addr = {
exports.inv_vect = {
/**
* Encode inventory vector.
* @param {Buffer} buf - Payload to calculate inventory vector for
* @param {Buffer} buf - Payload to calculate the inventory vector for
* @return {Buffer} Encoded `inv_vect`.
*/
encode: function(buf) {
@ -577,19 +583,22 @@ exports.inv_vect = {
* Encrypted payload.
* @see {@link https://bitmessage.org/wiki/Protocol_specification#Encrypted_payload}
* @namespace encrypted
* @static
*/
/**
* Decode encrypted payload.
* Decode encrypted payload.
* NOTE: all structure members are copied.
* @param {Buffer} buf - A buffer that contains encrypted payload
* @return {Object} Decoded encrypted structure.
* @function encrypted.decode
* @function decode
* @memberof module:bitmessage/structs.encrypted
*/
/**
* Encode `encrypted`.
* @param {Object} opts - Encode options
* @return {Buffer} Encoded encrypted payload.
* @function encrypted.encode
* @function encode
* @memberof module:bitmessage/structs.encrypted
*/
// Reexport struct.
exports.encrypted = bmcrypto.encrypted;
@ -662,7 +671,11 @@ var Bitfield = function(size) {
// See <https://github.com/Bitmessage/PyBitmessage/issues/769> for
// details.
var ServicesBitfield = exports.ServicesBitfield = objectAssign(Bitfield(64), {
/** This is a normal network node. */
/**
* This is a normal network node.
* @memberof module:bitmessage/structs.ServicesBitfield
* @constant {number}
*/
NODE_NETWORK: 63,
});
@ -677,11 +690,15 @@ exports.PubkeyBitfield = objectAssign(Bitfield(32), {
* Receiving node expects that the RIPE hash encoded in their address
* preceedes the encrypted message data of msg messages bound for
* them.
* @memberof module:bitmessage/structs.PubkeyBitfield
* @constant {number}
*/
INCLUDE_DESTINATION: 30,
/**
* If true, the receiving node does send acknowledgements (rather than
* dropping them).
* @memberof module:bitmessage/structs.PubkeyBitfield
* @constant {number}
*/
DOES_ACK: 31,
});

16
lib/user-agent.js
View File

@ -10,19 +10,23 @@ var var_str = require("./structs").var_str;
var BM_NAME = require("../package.json").name;
var BM_VERSION = require("../package.json").version;
/** User agent of the bitmessage library itself. */
/**
* User agent of the bitmessage library itself.
* @constant {Object[]}
* @static
*/
var SELF = exports.SELF = [{name: BM_NAME, version: BM_VERSION}];
/**
* Decode user agent `var_str`. Just an alias for
* {@link var_str.decode}
* Decode user agent's `var_str`. Just an alias for
* [var_str.decode]{@link module:bitmessage/structs.var_str.decode}.
* @function
*/
exports.decode = var_str.decode;
/**
* Parse raw user agent into software stack list. Most underlying
* software comes first.
* software comes first.
* NOTE: Decoding is rather loose, it won't fail on bad user agent
* format because it's not that important.
* @param {string} str - Raw user agent string
@ -59,8 +63,10 @@ exports.parse = function(str) {
* Encode user agent into `var_str` Buffer. Most underlying software
* comes first.
* @param {(Object[]|string[]|string)} software - List of software to
* encode or raw user agent string
* encode or just raw user agent string
* @return {Buffer} Encoded user agent.
* @function
* @static
*/
var encode = exports.encode = function(software) {
var ua;

2
package.json
View File

@ -35,7 +35,7 @@
"homepage": "https://github.com/bitchan/bitmessage",
"devDependencies": {
"chai": "*",
"jsdoc": "^3.3.0-alpha13",
"jsdoc": "^3.3.0-beta1",
"jshint": "*",
"karma": "^0.12.31",
"karma-browserify": "^2.0.0",