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.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
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
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.InternalMessage(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.InternalMessage.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 InternalMessage() object containing the deserialized message
js2p.base.InternalMessage.compression_used

Returns the compression method used in this message, as defined in flags, or undefined if none

js2p.base.InternalMessage.time

Returns the timestamp of this message

js2p.base.InternalMessage.time_58

Returns the timestamp encoded in base_58

js2p.base.InternalMessage.id

Returns the ID/checksum associated with this message

js2p.base.InternalMessage.payload

Returns the payload “packets” associated with this message

js2p.base.InternalMessage.packets

Returns the total “packets” associated with this message

js2p.base.InternalMessage.string

Returns a Buffer containing the serialized version of this message

js2p.base.InternalMessage.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:
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_InternalMessage(msg)

Sends a message through its connection.

Arguments:
Returns:

the InternalMessage() object you just sent, or undefined if the sending was unsuccessful
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 InternalMessage() 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 InternalMessage() 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.mesh.mesh_socket.outgoing

This is an array of all outgoing connections. The length of this array is used to determine whether the “socket” should automatically initiate connections

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