Chord Module
============

.. js:function:: js2p.chord.get_hashes(key)

    Returns the (adjusted) hashes for a given key. This is in the order of:

    - SHA1 (shifted 224 bits left)
    - SHA224 (shifted 160 bits left)
    - SHA256 (shifted 128 bits left)
    - SHA384 (unadjusted)
    - SHA512 (unadjusted)

    The adjustment is made to allow better load balancing between nodes, which
    assign responisbility for a value based on their SHA384-assigned ID.

.. js:class:: js2p.chord.chord_connection(sock, server, outgoing)

    This is the class for chord connection abstractraction. It inherits from :js:class:`js2p.mesh.mesh_connection`

    :param sock:                              This is the raw socket object
    :param js2p.chord.chord_socket server:    This is a link to the :js:class:`~js2p.chord.chord_socket` parent
    :param outgoing:                          This bool describes whether ``server`` initiated the connection

.. js:class:: js2p.mesh.mesh_socket(addr, port [, protocol [, out_addr [, debug_level]]])

    This is the class for mesh network socket abstraction. It inherits from :js:class:`js2p.base.base_socket`

    :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.mesh.mesh_socket.routing_table

        An object which contains :js:class:`~js2p.mesh.mesh_connection` s keyed by their IDs

    .. js:attribute:: js2p.mesh.mesh_socket.awaiting_ids

        An array which contains :js:class:`~js2p.mesh.mesh_connection` s that are awaiting handshake information

    .. js:function:: js2p.chord.chord_socket.__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.chord.max_outgoing`

        :param js2p.base.message msg:
        :param js2p.mesh.mesh_connection conn:

        :returns: Either ``true`` or ``undefined``

    .. js:function:: js2p.chord.chord_socket.get(key [, fallback])

        Retrieves the value at a given key

        :param key:       The key you wish to look up (must be transformable into a :js:class:`Buffer` )
        :param fallback:  The value it should return when the key has no data

        :returns: The value at the given key, or ``fallback``.

        :raises TypeError:    If the key could not be transformed into a :js:class:`Buffer`

    .. js:function:: js2p.chord.chord_socket.set(key, value)

        Sets the value at a given key

        :param key:   The key you wish to look up (must be transformable into a :js:class:`Buffer` )
        :param value: The key you wish to store (must be transformable into a :js:class:`Buffer` )

        :raises TypeError:    If a key or value could not be transformed into a :js:class:`Buffer`
        :raises:              See :js:func:`~js2p.chord.chord_socket.__store`

    .. js:function:: js2p.sync.sync_socket.update(update_dict)

        For each key/value pair in the given object, calls :js:func:`~js2p.sync.sync_socket.set`

        :param Object update_dict: An object with keys and values which can be transformed into a :js:class:`Buffer`

        :raises: See :js:func:`~js2p.sync.sync_socket.set`

    .. js:function:: js2p.sync.sync_socket.del(key)

        Clears the value at a given key

        :param key:   The key you wish to look up (must be transformable into a :js:class:`Buffer` )

        :raises TypeError:    If a key or value could not be transformed into a :js:class:`Buffer`
        :raises:              See :js:func:`~js2p.sync.sync_socket.set`

    .. js:function:: js2p.chord.chord_socket.keys()

        Returns a generator for all keys presently in the dictionary

        Because this data is changed asynchronously, the key is
        only garunteed to be present at the time of generation.

        :returns: A generator which yields :js:class:`Buffer`s

    .. js:function:: js2p.chord.chord_socket.values()

        Returns a generator for all values presently in the
        dictionary

        Because this data is changed asynchronously, the value is
        only garunteed to be accurate at the time of generation.

        :returns: A generator which yields :js:class:`Buffer`s

    .. js:function:: js2p.chord.chord_socket.items()

        Returns a generator for all associations presently in the
        dictionary

        Because this data is changed asynchronously, the association
        is only garunteed to be present at the time of generation.

        :returns: A generator which yields pairs of
                  :js:class:`Buffer`s

    .. js:function:: js2p.chord.chord_socket.pop(key [, fallback])

        Returns the value at a given key. As a side effect, it
        it deletes that key.

        :returns: A :js:class:`Buffer`

    .. js:function:: js2p.chord.chord_socket.popitem()

        Returns the association at a key. As a side effect, it
        it deletes that key.

        :returns: A pair of :js:class:`Buffer`s