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 :js:class:`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`. .. js:data:: 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. .. js:data:: js2p.base.node_policy_version This is the last number in :js:data:`~js2p.base.version_info` .. js:data:: js2p.base.protocol_version This is the first two numbers of :js:data:`~js2p.base.version_info` joined in the format ``'a.b'`` .. warning:: Nodes with different versions of this variable will actively reject connections with each other .. js:data:: js2p.base.version This is :js:data:`~js2p.base.version_info` joined in the format ``'a.b.c'`` .. js:data:: js2p.base.flags A "namespace" which defines protocol reserved flags .. js:function:: js2p.base.compress(text, method) This function is a shortcut for compressing data using a predefined method :param text: The string or Buffer-like object you wish to compress :param method: A compression method as defined in :js:data:`~js2p.base.flags` :returns: A variabley typed object containing a compressed version of text .. js:function:: js2p.base.decompress(text, method) This function is a shortcut for decompressing data using a predefined method :param text: The string or Buffer-like object you wish to decompress :param method: A compression method as defined in :js:data:`~js2p.base.flags` :returns: A variabley typed object containing a decompressed version of text .. js:function:: 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. :param arrayn: Any array-like object :returns: An array .. js:function:: js2p.base.unpack_value(str) This function unpacks a string into its corresponding big endian value :param str: The string you want to unpack :returns: A big-integer .. js:function:: js2p.base.pack_value(len, i) This function packs an integer i into a buffer of length len :param len: An integral value :param i: An integeral value :returns: A big endian buffer of length len .. js:function:: js2p.base.to_base_58(i) Takes an integer and returns its corresponding base_58 string :param i: An integral value :returns: the corresponding base_58 string .. js:function:: js2p.base.from_base_58(string) Takes a base_58 string and returns its corresponding integer :param string: A base_58 string or string-like object :returns: A big-integer .. js:function:: js2p.base.getUTC() :returns: An integral value containing the unix timestamp in seconds UTC .. js:function:: js2p.base.SHA384(text) This function returns the hex digest of the SHA384 hash of the input text :param string text: A string you wish to hash :returns: the hex SHA384 hash .. js:function:: js2p.base.SHA256(text) This function returns the hex digest of the SHA256 hash of the input text :param string text: A string you wish to hash :returns: the hex SHA256 hash .. js: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. :param string subnet: The subnet ID you wish to connect to. Ex: ``'mesh'`` :param string encryption: The encryption method you wish to use. Ex: ``'Plaintext'`` .. js:attribute:: js2p.base.Protocol.id The ID of your desired network .. js:class:: js2p.base.InternalMessage(msg_type, sender, payload, compression, timestamp) This is the message serialization/deserialization class. :param msg_type: This is the main flag checked by nodes, used for routing information :param sender: The ID of the person sending the message :param payload: A list of "packets" that you want your peers to receive :param compression: A list of compression methods that the receiver supports :param number timestamp: The time at which this message will be sent in seconds UTC .. js:function:: js2p.base.InternalMessage.feed_string(string, sizeless, compressions) This method deserializes a message :param string: The message you would like to deserialize :param sizeless: A bool-like object describing whether the size header is present :param compressions: A list of possible compression methods this message may be under :returns: A :js:class:`~js2p.base.InternalMessage` object containing the deserialized message .. js:attribute:: js2p.base.InternalMessage.compression_used Returns the compression method used in this message, as defined in :js:data:`~js2p.base.flags`, or ``undefined`` if none .. js:attribute:: js2p.base.InternalMessage.time Returns the timestamp of this message .. js:attribute:: js2p.base.InternalMessage.time_58 Returns the timestamp encoded in base_58 .. js:attribute:: js2p.base.InternalMessage.id Returns the ID/checksum associated with this message .. js:attribute:: js2p.base.InternalMessage.payload Returns the payload "packets" associated with this message .. js:attribute:: js2p.base.InternalMessage.packets Returns the total "packets" associated with this message .. js:attribute:: js2p.base.InternalMessage.string Returns a Buffer containing the serialized version of this message .. js:attribute:: js2p.base.InternalMessage.length Returns the length of this message when serialized .. js:class:: js2p.base.Message(msg, server) This is the Message class we present to the user. :param js2p.base.InternalMessage msg: This is the serialization object you received :param js2p.base.BaseSocket sender: This is the "socket" object that received it .. js:attribute:: js2p.base.Message.time Returns the time (in seconds UTC) this Message was sent at .. js:attribute:: js2p.base.Message.time_58 Returns the time (in seconds UTC) this Message was sent at, encoded in base_58 .. js:attribute:: js2p.base.Message.sender Returns the ID of this Message's sender .. js:attribute:: js2p.base.Message.id Returns the ID/checksum associated with this Message .. js:attribute:: js2p.base.Message.packets Returns the packets the sender wished you to have, sans metadata .. js:attribute:: js2p.base.Message.length Returns the serialized length of this Message .. js:attribute:: js2p.base.Message.protocol Returns the :js:class:`~js2p.base.Protocol` associated with this Message .. js:function:: 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. :param packs: A list of packets you want the other user to receive .. js:class:: js2p.base.BaseConnection(sock, server, outgoing) This is the template class for connection abstracters. :param sock: This is the raw socket object :param js2p.base.BaseSocket server: This is a link to the :js:class:`~js2p.base.BaseSocket` parent :param outgoing: This bool describes whether ``server`` initiated the connection .. js:function:: js2p.base.BaseConnection.onEnd() This function is run when a connection is ended .. js:function:: js2p.base.BaseConnection.onError() This function is run when a connection experiences an error .. js:function:: js2p.base.BaseConnection.onClose() This function is run when a connection is closed .. js:function:: js2p.base.BaseConnection.send_InternalMessage(msg) Sends a message through its connection. :param js2p.base.InternalMessage msg: A :js:class:`~js2p.base.InternalMessage` object :returns: the :js:class:`~js2p.base.InternalMessage` object you just sent, or ``undefined`` if the sending was unsuccessful .. js:function:: js2p.base.BaseConnection.send(msg_type, packs, id, time) Sends a message through its connection. :param msg_type: Message type, corresponds to the header in a :js:class:`~js2p.base.InternalMessage` object :param packs: A list of Buffer-like objects, which correspond to the packets to send to you :param id: The ID this message should appear to be sent from (default: your ID) :param number time: The time this message should appear to be sent from (default: now in UTC) :returns: the :js:class:`~js2p.base.InternalMessage` object you just sent, or ``undefined`` if the sending was unsuccessful .. js:function:: js2p.base.BaseConnection.collect_incoming_data(self, data) Collects and processes data which just came in on the socket :param self: A reference to this connection. Will be refactored out. :param Buffer data: The data which was just received .. js:function:: js2p.base.BaseConnection.found_terminator() This method is called when the expected amount of data is received :returns: The deserialized message received .. js:function:: js2p.base.BaseConnection.handle_renegotiate(packets) This function handles connection renegotiations. This is used when compression methods fail, or when a node needs a message resent. :param packs: The array of packets which were received to initiate the renegotiation :returns: ``true`` if action was taken, ``undefined`` if not .. js:class:: js2p.base.BaseSocket(addr, port [, protocol [, out_addr [, debug_level]]]) This is the template class for socket abstracters. This class extends :js:class:`EventEmitter`. :param string addr: The address you'd like to bind to :param number port: The port you'd like to bind to :param js2p.base.Protocol protocol: The subnet you're looking to connect to :param array out_addr: Your outward-facing address :param number debug_level: The verbosity of debug prints .. js:attribute:: js2p.base.BaseSocket.routing_table A :js:class:`Map` which contains :js:class:`~js2p.base.BaseConnection` s keyed by their IDs .. js:attribute:: js2p.base.BaseSocket.awaiting_ids An array which contains :js:class:`~js2p.base.BaseConnection` s that are awaiting handshake information .. js:attribute:: js2p.base.BaseSocket.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 .. js:attribute:: js2p.mesh.MeshSocket.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 .. js:function:: js2p.base.BaseSocket.register_handler(callback) This registers a message callback. Each is run through until one returns ``true``, rather like :js:func:`Array.some()`. The callback is expected to be of the form: .. code-block:: javascript function callback(msg, conn) { var packets = msg.packets; if (packets[0] === some_expected_value) { some_action(msg, conn); return true; } } :param function callback: A function formatted like the above