3.0.ipv8.dht.routing
====================

.. py:module:: 3.0.ipv8.dht.routing


Attributes
----------

.. autoapisummary::

   3.0.ipv8.dht.routing.NODE_LIMIT_INTERVAL
   3.0.ipv8.dht.routing.NODE_LIMIT_QUERIES
   3.0.ipv8.dht.routing.NODE_STATUS_GOOD
   3.0.ipv8.dht.routing.NODE_STATUS_UNKNOWN
   3.0.ipv8.dht.routing.NODE_STATUS_BAD
   3.0.ipv8.dht.routing.MAX_BUCKET_SIZE


Classes
-------

.. autoapisummary::

   3.0.ipv8.dht.routing.Node
   3.0.ipv8.dht.routing.Bucket
   3.0.ipv8.dht.routing.RoutingTable


Functions
---------

.. autoapisummary::

   3.0.ipv8.dht.routing.id_to_binary_string
   3.0.ipv8.dht.routing.distance
   3.0.ipv8.dht.routing.calc_node_id


Module Contents
---------------

.. py:data:: NODE_LIMIT_INTERVAL
   :value: 5


.. py:data:: NODE_LIMIT_QUERIES
   :value: 10


.. py:data:: NODE_STATUS_GOOD
   :value: 2


.. py:data:: NODE_STATUS_UNKNOWN
   :value: 1


.. py:data:: NODE_STATUS_BAD
   :value: 0


.. py:data:: MAX_BUCKET_SIZE
   :value: 8


.. py:function:: id_to_binary_string(node_id: bytes) -> str

   Convert a node id to a string.


.. py:function:: distance(a: bytes, b: bytes) -> int

   Get the XOR between two bytes strings, encoded as in int.


.. py:function:: calc_node_id(address: 3.0.ipv8.types.Address | 3.0.ipv8.messaging.interfaces.udp.endpoint.UDPv4Address | 3.0.ipv8.messaging.interfaces.udp.endpoint.UDPv6Address, mid: bytes) -> bytes

   Loosely based on the Bittorrent DHT (https://libtorrent.org/dht_sec.html), the node id is calculated as
   follows for IPv4: first 3 bytes of crc32c(ip & 0x030f3fff) + first 17 bytes of sha1(public_key).


.. py:class:: Node(key: 3.0.ipv8.types.Key | bytes, address: 3.0.ipv8.types.Address | None = None, intro: bool = True)

   Bases: :py:obj:`3.0.ipv8.peer.Peer`


   The Node class represents a peer within the DHT community.


   .. py:attribute:: bucket
      :type:  Bucket | None
      :value: None



   .. py:attribute:: last_response
      :type:  float
      :value: 0



   .. py:attribute:: last_queries
      :type:  collections.deque[float]


   .. py:attribute:: last_ping_sent
      :type:  float
      :value: 0



   .. py:attribute:: failed
      :type:  int
      :value: 0



   .. py:attribute:: rtt
      :type:  float
      :value: 0



   .. py:property:: id
      :type: bytes


      The id of this node.



   .. py:property:: last_contact
      :type: float


      The last timestamp (in seconds) that we interacted with this node.



   .. py:property:: last_query
      :type: float


      The last timestamp (in seconds) that we queried this node.



   .. py:property:: blocked
      :type: bool


      Whether this node is blocked.



   .. py:property:: status
      :type: int


      A good node is a node has responded to one of our queries within the last 15 minutes, or has ever responded
      to one of our queries and has sent us a query within the last 15 minutes. This is the same logic as
      used in BEP-5.



   .. py:method:: distance(other_node: Node | bytes) -> int

      The distance to another node.



.. py:class:: Bucket(prefix_id: str, max_size: int = MAX_BUCKET_SIZE)

   The Bucket class stores nodes that share common prefix ID.


   .. py:attribute:: nodes
      :type:  dict[bytes, Node]


   .. py:attribute:: prefix_id
      :type:  str


   .. py:attribute:: max_size
      :type:  int


   .. py:attribute:: last_changed
      :type:  float
      :value: 0



   .. py:method:: generate_id() -> bytes

      Generate a new id.



   .. py:method:: owns(node_id: bytes) -> bool

      Whether the given node id is in this bucket.



   .. py:method:: get(node_id: bytes) -> Node | None

      Get the object belonging to the given node id.



   .. py:method:: add(node: Node) -> bool

      Attempt to add the given node to this bucket.

      :param node: the node to add.
      :return: whether the addition was successful.



   .. py:method:: split() -> tuple[Bucket, Bucket] | None

      Split this bucket in two.

      :return: the new buckets.



.. py:class:: RoutingTable(my_node_id: bytes)

   The RoutingTable is a binary tree that keeps track of Nodes that we have a connection to.


   .. py:attribute:: my_node_id


   .. py:attribute:: trie


   .. py:attribute:: lock


   .. py:method:: get_bucket(node_id: bytes) -> Bucket

      Get the bucket that a given node id belongs to.



   .. py:method:: add(node: Node) -> Node | None

      Add the given node to the routing table.



   .. py:method:: remove_bad_nodes() -> list[Node]

      Remove nodes that have the BAD status.



   .. py:method:: has(node_id: bytes) -> bool

      Check if a node id is known.



   .. py:method:: get(node_id: bytes) -> Node | None

      Return a node belonging to an id, if it exists.



   .. py:method:: closest_nodes(node_id: bytes, max_nodes: int = 8, exclude_node: Node | None = None) -> list[Node]

      Return the nodes closes to a node id.