Mesh Module =========== .. js:data:: js2p.mesh.default_protocol A :js:class:`~js2p.base.Protocol` object which is used by default in the mesh module .. js:class:: js2p.mesh.MeshConnection(sock, server, outgoing) This is the class for mesh connection abstractraction. It inherits from :js:class:`js2p.base.BaseConnection` :param sock: This is the raw socket object :param js2p.mesh.MeshSocket server: This is a link to the :js:class:`~js2p.mesh.MeshSocket` parent :param outgoing: This bool describes whether ``server`` initiated the connection .. js:function:: js2p.mesh.MeshConnection.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: ``undefined`` .. js:function:: js2p.mesh.MeshConnection.found_terminator() This method is called when the expected amount of data is received :returns: ``undefined`` .. js:function:: js2p.mesh.MeshConnection.handle_waterfall(msg, packets) This method determines whether this message has been previously received or not. If it has been previously received, this method returns ``true``. If it is older than a preset limit, this method returns ``true``. Otherwise this method returns ``undefined``, and forwards the message appropriately. :param js2p.base.InternalMessage msg: The message in question :param packets: The message's packets :returns: ``true`` or ``undefined`` .. js:function:: js2p.mesh.MeshConnection.onClose() This function is run when a connection is closed .. js:function:: js2p.mesh.MeshConnection.onEnd() This function is run when a connection is ended .. js:class:: js2p.mesh.MeshSocket(addr, port [, protocol [, out_addr [, debug_level]]]) This is the class for mesh network socket abstraction. It inherits from :js:class:`js2p.base.BaseSocket` :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:function:: js2p.mesh.MeshSocket Event 'connect'(conn) This event is called whenever you have a *new* connection to the service network. In other words, whenever the length of your routing table is increased from zero to one. If you call ``on('connect')``, that will be executed on every connection to the network. So if you are suddenly disconnected, and manage to recover, that function will execute again. To avoid this, call ``once('connect')``. That will usually be more correct. :param js2p.mesh.MeshSocket conn: A reference to this abstract socket .. js:function:: js2p.mesh.MeshSocket Event 'message'(conn) This event is called whenever you receive a new message. A reference to the message is *not* passed to you. This is to prevent potential memory leaks. If you want to register a "privileged" handler which *does* get a reference to the message, see :js:func:`~js2p.base.BaseSocket.register_handler` :param js2p.mesh.MeshSocket conn: A reference to this abstract socket .. js:attribute:: js2p.mesh.MeshSocket.routing_table A :js:class:`Map` which contains :js:class:`~js2p.mesh.MeshConnection` s keyed by their IDs .. js:attribute:: js2p.mesh.MeshSocket.awaiting_ids An array which contains :js:class:`~js2p.mesh.MeshConnection` s that are awaiting handshake information .. js:function:: js2p.mesh.MeshSocket.recv([num]) This function has two behaviors depending on whether num is truthy. If num is truthy, it will return a list of :js:class:`~js2p.base.Message` objects up to length len. If num is not truthy, it will return either a single :js:class:`~js2p.base.Message` object, or ``undefined`` :param number num: The maximum number of :js:class:`~js2p.base.Message` s you would like to pull :returns: A list of :js:class:`~js2p.base.Message` s, an empty list, a single :js:class:`~js2p.base.Message` , or ``undefined`` .. js:function:: js2p.mesh.MeshSocket._send_peers(handler) Shortcut method to send a peerlist message. This method is extracted from :js:func:`~js2p.mesh.MeshSocket.__handle_handshake` in order to allow cleaner inheritence from :js:class:`js2p.sync.sync_socket` .. js:function:: js2p.mesh.MeshSocket._send_handshake(handler) Shortcut method to send a handshake response. This method is extracted from :js:func:`~js2p.mesh.MeshSocket.__handle_handshake` in order to allow cleaner inheritence from :js:class:`js2p.sync.sync_socket` .. js:function:: js2p.mesh.MeshSocket.connect(addr, port [, id]) This function connects you to a specific node in the overall network. Connecting to one node *should* connect you to the rest of the network, however if you connect to the wrong subnet, the handshake failure involved is silent. You can check this by looking at the truthiness of this objects routing table. Example: .. code-block:: javascript > var conn = new mesh.MeshSocket('localhost', 4444); > conn.connect('localhost', 5555); > //do some other setup for your program > if (!conn.routing_table) { ... conn.connect('localhost', 6666); // any fallback address ... } :param string addr: A string address :param number port: A positive, integral port :param id: A string-like object which represents the expected ID of this node .. note:: While in the Python version there are more thorough checks on this, the Javascript implementation *can* connect to itself. There are checks to keep this from happening automatically, but it's still trivial to override this via human intervention. Please do not try to connect to yourself. .. js:function:: js2p.mesh.MeshSocket.disconnect(handler) Closes a given connection, and removes it from your routing tables :param js2p.mesh.MeshConnection handler: The connection you wish to close .. js:function:: js2p.mesh.MeshSocket.__get_peer_list() This function is used to generate a list-formatted group of your peers. It goes in format ``[ [[addr, port], ID], ...]`` :returns: An array in the above format .. js:function:: js2p.mesh.MeshSocket.__handle_handshake(msg, conn) This callback is used to deal with handshake signals. Its three primary jobs are: - reject connections seeking a different network - set connection state - deal with connection conflicts :param js2p.base.Message msg: :param js2p.mesh.MeshConnection conn: :returns: Either ``true`` or ``undefined`` .. js:function:: js2p.mesh.MeshSocket.__handle_peers(msg, conn) This callback is used to deal with peer signals. Its primary jobs is to connect to the given peers, if this does not exceed :js:data:`js2p.mesh.max_outgoing` :param js2p.base.Message msg: :param js2p.mesh.MeshConnection conn: :returns: Either ``true`` or ``undefined`` .. js:function:: js2p.mesh.MeshSocket.__handle_response(msg, conn) This callback is used to deal with response signals. Its two primary jobs are: - if it was your request, send the deferred message - if it was someone else's request, relay the information :param js2p.base.Message msg: :param js2p.mesh.MeshConnection conn: :returns: Either ``true`` or ``undefined`` .. js:function:: js2p.mesh.MeshSocket.__handle_request(msg, conn) This callback is used to deal with request signals. Its three primary jobs are: - respond with a peers signal if packets[1] is ``'*'`` - if you know the ID requested, respond to it - if you don't, make a request with your peers :param js2p.base.Message msg: :param js2p.mesh.MeshConnection conn: :returns: Either ``true`` or ``undefined`` .. js:function:: js2p.mesh.MeshSocket.send(packets [, flag [, type]]) This sends a message to all of your peers. If you use default values it will send it to everyone on the network :param packets: A list of strings or Buffer-like objects you want your peers to receive :param flag: A string or Buffer-like object which defines your flag. In other words, this defines packet 0. :param type: A string or Buffer-like object which defines your message type. Changing this from default can have adverse effects. .. warning:: If you change the type attribute from default values, bad things could happen. It **MUST** be a value from :js:data:`js2p.base.flags` , and more specifically, it **MUST** be either ``broadcast`` or ``whisper``. The only other valid flags are ``waterfall`` and ``renegotiate``, but these are **RESERVED** and must **NOT** be used. .. js:function:: js2p.mesh.MeshSocket.__clean_waterfalls() This function cleans the list of recently relayed messages based on the following heurisitics: - Delete all duplicates - Delete all older than 60 seconds .. js:function:: js2p.mesh.MeshSocket.waterfall(msg) This function handles message relays. Its return value is based on whether it took an action or not. :param js2p.base.Message msg: The message in question :returns: ``true`` if the message was then forwarded. ``false`` if not.