Base Module¶

This module contains common classes and functions which are used throughout the rest of the js2p library.

Note

This library will likely issue a warning over the size of data that Buffer() can hold. On most implementations of Javascript this is 2GiB, but the maximum size message that can be transmitted in our serialization scheme is 4GiB. This shouldn’t be a problem for most applications, but you can discuss it in issue #83.

js2p.base.version_info¶

A list containing the version numbers in the format [major, minor, patch].

The first two numbers refer specifically to the protocol version. The last number increments with each build.

js2p.base.node_policy_version¶: This is the last number in version_info

js2p.base.protocol_version¶: This is the first two numbers of version_info joined in the format 'a.b'

Warning

Nodes with different versions of this variable will actively reject connections with each other

js2p.base.version¶: This is version_info joined in the format 'a.b.c'

js2p.base.flags¶: A “namespace” which defines protocol reserved flags

js2p.base.intersect(array1, array2[, array3[, ...]])¶

This function returns the intersection of two or more arrays. That is, it returns an array of the elements present in all arrays, in the order that they were present in the first array.

Arguments:	arrayn – Any array-like object
Returns:	An array

js2p.base.unpack_value(str)¶

This function unpacks a string into its corresponding big endian value

Arguments:	str – The string you want to unpack
Returns:	A big-integer

js2p.base.pack_value(len, i)¶

This function packs an integer i into a buffer of length len

Arguments:	len – An integral value i – An integeral value
Returns:	A big endian buffer of length len

js2p.base.to_base_58(i)¶

Takes an integer and returns its corresponding base_58 string

Arguments:	i – An integral value
Returns:	the corresponding base_58 string

js2p.base.from_base_58(string)¶

Takes a base_58 string and returns its corresponding integer

Arguments:	string – A base_58 string or string-like object
Returns:	A big-integer

js2p.base.getUTC()¶

Returns:	An integral value containing the unix timestamp in seconds UTC

js2p.base.SHA384(text)¶

This function returns the hex digest of the SHA384 hash of the input text

Arguments:	text (string) – A string you wish to hash
Returns:	the hex SHA384 hash

js2p.base.SHA256(text)¶

This function returns the hex digest of the SHA256 hash of the input text

Arguments:	text (string) – A string you wish to hash
Returns:	the hex SHA256 hash

js2p.base.compress(text, method)¶

This function is a shortcut for compressing data using a predefined method

Arguments:	text – The string or Buffer-like object you wish to compress method – A compression method as defined in `flags`
Returns:	A variabley typed object containing a compressed version of text

js2p.base.decompress(text, method)¶

This function is a shortcut for decompressing data using a predefined method

Arguments:	text – The string or Buffer-like object you wish to decompress method – A compression method as defined in `flags`
Returns:	A variabley typed object containing a decompressed version of text

class js2p.base.protocol(subnet, encryption)¶

This class is used as a subnet object. Its role is to reject undesired connections. If you connect to someone who has a different protocol object than you, this descrepency is detected, and you are silently disconnected.

Arguments:	subnet (string) – The subnet ID you wish to connect to. Ex: `'mesh'` encryption (string) – The encryption method you wish to use. Ex: `'Plaintext'`

js2p.base.protocol.id¶: The ID of your desired network

class js2p.base.pathfinding_message(msg_type, sender, payload, compression, timestamp)¶

This is the message serialization/deserialization class.

Arguments:	msg_type – This is the main flag checked by nodes, used for routing information sender – The ID of the person sending the message payload – A list of “packets” that you want your peers to receive compression – A list of compression methods that the receiver supports timestamp (number) – The time at which this message will be sent in seconds UTC

js2p.base.pathfinding_message.feed_string(string, sizeless, compressions)¶

This method deserializes a message

Arguments:	string – The message you would like to deserialize sizeless – A bool-like object describing whether the size header is present compressions – A list of possible compression methods this message may be under
Returns:	A `pathfinding_message()` object containing the deserialized message

js2p.base.pathfinding_message.compression_used¶: Returns the compression method used in this message, as defined in flags, or undefined if none

js2p.base.pathfinding_message.time¶: Returns the timestamp of this message

js2p.base.pathfinding_message.time_58¶: Returns the timestamp encoded in base_58

js2p.base.pathfinding_message.id¶: Returns the ID/checksum associated with this message

js2p.base.pathfinding_message.payload¶: Returns the payload “packets” associated with this message

js2p.base.pathfinding_message.packets¶: Returns the total “packets” associated with this message

js2p.base.pathfinding_message.string¶: Returns a Buffer containing the serialized version of this message

js2p.base.pathfinding_message.length¶: Returns the length of this message when serialized

class js2p.base.message(msg, server)¶

This is the message class we present to the user.

Arguments:	msg (js2p.base.pathfinding_message) – This is the serialization object you received sender (js2p.base.base_socket) – This is the “socket” object that received it

js2p.base.message.time¶: Returns the time (in seconds UTC) this message was sent at

js2p.base.message.time_58¶: Returns the time (in seconds UTC) this message was sent at, encoded in base_58

js2p.base.message.sender¶: Returns the ID of this message’s sender

js2p.base.message.id¶: Returns the ID/checksum associated with this message

js2p.base.message.packets¶: Returns the packets the sender wished you to have, sans metadata

js2p.base.message.length¶: Returns the serialized length of this message

js2p.base.message.protocol¶: Returns the protocol() associated with this message

js2p.base.message.reply(packs)¶

Replies privately to this message.

Warning

Using this method has potential effects on the network composition. If you are not connected to the sender, we cannot garuntee the message will get through. If successful, you will experience higher network load on average.

Arguments:	packs – A list of packets you want the other user to receive

class js2p.base.base_connection(sock, server, outgoing)¶

This is the template class for connection abstracters.

Arguments:	sock – This is the raw socket object server (js2p.base.base_socket) – This is a link to the `base_socket()` parent outgoing – This bool describes whether `server` initiated the connection

js2p.base.base_connection.onEnd()¶: This function is run when a connection is ended

js2p.base.base_connection.onError()¶: This function is run when a connection experiences an error

js2p.base.base_connection.onClose()¶: This function is run when a connection is closed

js2p.base.base_connection.send(msg_type, packs, id, time)¶

Sends a message through its connection.

Arguments:	msg_type – Message type, corresponds to the header in a `pathfinding_message()` object packs – A list of Buffer-like objects, which correspond to the packets to send to you id – The ID this message should appear to be sent from (default: your ID) time (number) – The time this message should appear to be sent from (default: now in UTC)
Returns:	the `pathfinding_message()` object you just sent, or `undefined` if the sending was unsuccessful

js2p.base.base_connection.collect_incoming_data(self, data)¶

Collects and processes data which just came in on the socket

Arguments:	self – A reference to this connection. Will be refactored out. data (Buffer) – The data which was just received

js2p.base.base_connection.found_terminator()¶

This method is called when the expected amount of data is received

Returns:	The deserialized message received

js2p.base.base_connection.handle_renegotiate(packets)¶

This function handles connection renegotiations. This is used when compression methods fail, or when a node needs a message resent.

Arguments:	packs – The array of packets which were received to initiate the renegotiation
Returns:	`true` if action was taken, `undefined` if not

class js2p.base.base_socket(addr, port[, protocol[, out_addr[, debug_level]]])¶

This is the template class for socket abstracters.

Arguments:	addr (string) – The address you’d like to bind to port (number) – The port you’d like to bind to protocol (js2p.base.protocol) – The subnet you’re looking to connect to out_addr (array) – Your outward-facing address debug_level (number) – The verbosity of debug prints

js2p.base.base_socket.routing_table¶: An object which contains base_connection() s keyed by their IDs

js2p.base.base_socket.awaiting_ids¶: An array which contains base_connection() s that are awaiting handshake information

js2p.base.base_socket.status¶

This attribute describes whether the socket is operating as expected.

It will either return a string "Nominal" or a list of Error/Traceback pairs

js2p.base.base_socket.register_handler(callback)¶

This registers a message callback. Each is run through until one returns true, rather like Array.some(). The callback is expected to be of the form:

function callback(msg, conn)  {
    var packets = msg.packets;
    if (packets[0] === some_expected_value)   {
        some_action(msg, conn);
        return true;
    }
}

Arguments:	callback (function) – A function formatted like the above