3.0.ipv8.peerdiscovery.community
================================

.. py:module:: 3.0.ipv8.peerdiscovery.community


Classes
-------

.. autoapisummary::

   3.0.ipv8.peerdiscovery.community.PeriodicSimilarity
   3.0.ipv8.peerdiscovery.community.PingRequestCache
   3.0.ipv8.peerdiscovery.community.DiscoveryCommunity


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

.. py:class:: PeriodicSimilarity(overlay: DiscoveryCommunity)

   Bases: :py:obj:`3.0.ipv8.peerdiscovery.churn.DiscoveryStrategy`


   Periodically send a request for similar Communities to a random peer.


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



   .. py:method:: take_step() -> None

      Select a random peer, at most every second, to send a similarity request to.



.. py:class:: PingRequestCache(request_cache: 3.0.ipv8.requestcache.RequestCache, identifier: int, peer: 3.0.ipv8.peer.Peer, start_time: float)

   Bases: :py:obj:`3.0.ipv8.requestcache.NumberCache`


   Cache for ping measurements to a peer.


   .. py:attribute:: name
      :value: 'discoverypingcache'



   .. py:attribute:: peer


   .. py:attribute:: start_time


   .. py:method:: finish() -> None

      Complete the ping measurement by adding it to a peer's pings.



   .. py:property:: timeout_delay
      :type: float


      After 5 seconds, consider the peer unreachable.



   .. py:method:: on_timeout() -> None

      If we can't reach a peer, we assume accidental packet drop. Actually dropping the peer is left to the churn.



.. py:class:: DiscoveryCommunity(settings: 3.0.ipv8.community.CommunitySettings)

   Bases: :py:obj:`3.0.ipv8.community.Community`


   Community for peers to more quickly discover peers in other communities.

   Peers exchange the community ids they are part of with each other.


   .. py:attribute:: version
      :value: b'\x02'



   .. py:attribute:: community_id


   .. py:attribute:: request_cache


   .. py:method:: get_available_strategies() -> dict[str, type[3.0.ipv8.peerdiscovery.churn.DiscoveryStrategy]]

      Expose strategies for periodically checking similarity and unreachable peer churn.



   .. py:method:: unload() -> None
      :async:


      Unload the pending ping cache and then shut down the pending tasks.



   .. py:method:: on_old_introduction_request(source_address: 3.0.ipv8.types.Address, data: bytes) -> None

      A backward-compatible (2014) introduction request handler.

      The old logic flow was to first try to unpack the special DiscoveryCommunity intro request and then fall
      back to the actual intro request payload.



   .. py:method:: introduction_response_callback(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.IntroductionResponsePayload | 3.0.ipv8.messaging.payload.NewIntroductionResponsePayload) -> None

      If a peer sent us a response, send them a request for similarity.



   .. py:method:: send_similarity_request(address: 3.0.ipv8.types.Address) -> None

      Send a request for similarity with our communities.



   .. py:method:: on_similarity_request(node: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.peerdiscovery.payload.SimilarityRequestPayload) -> None

      We received a request for similarity (overlap with another peer's communities).

      We update the known community ids for this peer and we send a response that contains our own ids.



   .. py:method:: on_similarity_response(node: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.peerdiscovery.payload.SimilarityResponsePayload) -> None

      We received a response to our request for similarity.



   .. py:method:: on_ping(source_address: 3.0.ipv8.types.Address, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.peerdiscovery.payload.PingPayload) -> None

      We received a ping, send a pong back.

      For backward compatibility, this message is unsigned.



   .. py:method:: on_pong(source_address: 3.0.ipv8.types.Address, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.peerdiscovery.payload.PongPayload, cache: PingRequestCache) -> None

      We got a valid pong to our existing ping (retrieve_cache ensures this), finish the request in the cache handler.

      Note: For backward compatibility, this message is UNSIGNED. The only thing guaranteeing that the response
            is not faked, is its nonce.



   .. py:method:: get_my_overlays(peer: 3.0.ipv8.peer.Peer) -> list[bytes]

      Get the known community ids that we are a part of.



   .. py:method:: custom_pack(peer: 3.0.ipv8.peer.Peer, msg_num: int, payloads: collections.abc.Sequence[3.0.ipv8.messaging.serialization.Serializable]) -> bytes

      You can have different key material for different communities. So, in order for you to cross-communicate,
      you should sign messages with the key material that is used by a particular community.



   .. py:method:: create_similarity_request(peer: 3.0.ipv8.peer.Peer) -> bytes

      Create a similarity request message to send to the given peer.



   .. py:method:: create_similarity_response(identifier: int, peer: 3.0.ipv8.peer.Peer) -> bytes

      Create a response message to a similarity request from a given peer.



   .. py:method:: send_ping(peer: 3.0.ipv8.peer.Peer) -> None

      Send a ping message to the given peer.



   .. py:method:: create_pong(identifier: int) -> bytes

      Create a pong message for the given identifier.