3.0.ipv8.community ================== .. py:module:: 3.0.ipv8.community .. autoapi-nested-parse:: the community module provides the Community base class that should be used when a new Community is implemented. It provides a simplified interface between the Dispersy instance and a running Community instance. @author: Boudewijn Schoon @organization: Technical University Delft @contact: dispersy@frayja.com Attributes ---------- .. autoapisummary:: 3.0.ipv8.community._UNUSED_FLAGS_REQ 3.0.ipv8.community._UNUSED_FLAGS_RESP 3.0.ipv8.community.DEFAULT_MAX_PEERS Classes ------- .. autoapisummary:: 3.0.ipv8.community.CommunitySettings 3.0.ipv8.community.Community Module Contents --------------- .. py:data:: _UNUSED_FLAGS_REQ .. py:data:: _UNUSED_FLAGS_RESP .. py:data:: DEFAULT_MAX_PEERS :value: 30 .. py:class:: CommunitySettings Bases: :py:obj:`3.0.ipv8.overlay.Settings` Community settings, extensible for Community subclasses. .. py:attribute:: max_peers :type: int The number of peers we will grow to before we start rejecting new connections. .. py:attribute:: anonymize :type: bool :value: False Request use of a ``TunnelEndpoint`` to anonymize all our traffic. .. py:class:: Community(settings: CommunitySettings) Bases: :py:obj:`3.0.ipv8.lazy_community.EZPackOverlay` Base class for overlay functionality with a rich set of defaults. Inherit from this class if you want IPv8 to handle peer introduction logic for you. .. py:attribute:: version :value: b'\x02' .. py:attribute:: community_id :type: bytes .. py:attribute:: settings_class .. py:attribute:: _prefix .. py:attribute:: max_peers .. py:attribute:: anonymize .. py:attribute:: bootstrappers :type: list[3.0.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper] :value: [] .. py:attribute:: decode_map :type: list[3.0.ipv8.types.MessageHandlerFunction | None] .. py:attribute:: deprecated_message_names .. py:method:: get_prefix() -> bytes Get the prefix for all data that is to be routed to this Community. Note that this can be shared with other communities. This is used, for example, for statistics tracking. .. py:method:: unload() -> None :async: Perform a clean exit of this Community. Clean shutdown consists of three steps: - First, unload the bootstrappers. - Second, stop listening on the endpoint. - Last, disallow new tasks from being registered. .. py:method:: add_message_handler(msg_num: int | type[3.0.ipv8.types.Payload], callback: 3.0.ipv8.types.MessageHandlerFunction) -> None Add a handler for a message identifier. Any messages coming in with this identifier will be delivered to the specified callback function. :param msg_num: the message id to listen for (or a Payload object with a msg_id field) :param callback: the callback function for this message id .. py:method:: on_deprecated_message(source_address: 3.0.ipv8.types.Address, data: bytes) -> None Callback for when we receive a known-to-be-deprecated message. .. py:method:: bootstrap() -> None Contact the bootstrappers for new peers, initialize the bootstrappers if necessary. .. py:method:: _bootstrap(bootstrapper: 3.0.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper) -> None :async: Contact a single bootstrapper for new peers and initialize if necessary. .. py:method:: ensure_blacklisted(address: 3.0.ipv8.types.Address) -> None Add an address to the blacklist, if it is not already there. .. py:method:: guess_address(interface: str) -> 3.0.ipv8.types.Address | None GUESS our own address. There is no way to be sure this address is "correct". There may not even BE a consistent address that other peers can contact us by. .. py:method:: my_preferred_address() -> 3.0.ipv8.types.Address Get our own preferred address or ``("0.0.0.0", 0)`` if we don't know of any of our own addresses. .. py:method:: create_introduction_request(socket_address: 3.0.ipv8.types.Address, extra_bytes: bytes = b'', new_style: bool = False, prefix: bytes | None = None) -> bytes Create a new introduction request message, without sending it. :param socket_address: The address to send to. :param extra_bytes: The extra bytes to piggyback onto this message. :param new_style: Whether we support "new style" (non-IPv4) introduction requests. :param prefix: Send to a different community id (EXPERT USE ONLY). .. py:method:: create_introduction_response(lan_socket_address: 3.0.ipv8.types.Address, socket_address: 3.0.ipv8.types.Address, identifier: int, introduction: 3.0.ipv8.peer.Peer | None = None, extra_bytes: bytes = b'', prefix: bytes | None = None, new_style: bool = False) -> bytes Create a new introduction response message, without sending it. :param lan_socket_address: What the request sender thinks our address is. :param socket_address: The request sender's address. :param identifier: The introduction request identifier that we are responding to. :param introduction: Introduce the request sender to this given peer. :param extra_bytes: The extra bytes to piggyback onto this message. :param prefix: Send to a different community id (EXPERT USE ONLY). :param new_style: Whether we support "new style" (non-IPv4) introduction requests. .. py:method:: create_puncture(lan_walker: 3.0.ipv8.types.Address, wan_walker: 3.0.ipv8.types.Address, identifier: int, new_style: bool = False) -> bytes Create a puncture message for the given LAN/WAN address. :param lan_walker: The LAN address to puncture. :param wan_walker: The WAN address to puncture. :param identifier: The PunctureRequest identifier we are responding to. :param new_style: Whether we support "new style" (non-IPv4) introduction requests. .. py:method:: create_puncture_request(lan_walker: 3.0.ipv8.types.Address, wan_walker: 3.0.ipv8.types.Address, identifier: int, prefix: bytes | None = None, new_style: bool = False) -> bytes Create a request for another peer to puncture a given LAN/WAN address pair. :param lan_walker: The LAN address to request puncturing for. :param wan_walker: The WAN address to request puncturing for. :param identifier: The identifier to use for this message. :param prefix: Send to a different community id (EXPERT USE ONLY). :param new_style: Whether we support "new style" (non-IPv4) introduction requests. .. py:method:: introduction_request_callback(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.IntroductionRequestPayload | 3.0.ipv8.messaging.payload.NewIntroductionRequestPayload) -> None Callback that gets called after an introduction-request has been processed. If you want to some action to trigger upon receipt of an introduction-request, this would be the place to do so. :param peer the peer that sent us an introduction-request :param dist the GlobalTimeDistributionPayload :param payload the IntroductionRequestPayload .. 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 Callback that gets called after an introduction-response has been processed. If you want to some action to trigger upon receipt of an introduction-response, this would be the place to do so. :param peer the peer that sent us an introduction-response :param dist the GlobalTimeDistributionPayload :param payload the IntroductionResponsePayload .. py:method:: on_old_introduction_request(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.IntroductionRequestPayload | 3.0.ipv8.messaging.payload.NewIntroductionRequestPayload) -> None Interception callback for when we receive an old IPv4-only introduction request. Message handling is performed in ``on_introduction_request()``. .. py:method:: on_new_introduction_request(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.NewIntroductionRequestPayload) -> None Interception callback for when we receive a new (non-IPv4-only) introduction request. Message handling is performed in ``on_introduction_request()``. .. py:method:: on_introduction_request(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.IntroductionRequestPayload | 3.0.ipv8.messaging.payload.NewIntroductionRequestPayload) -> None Callback to handle introduction requests. We don't answer if we are at our peer capacity, triggering peer churn for the other peer. Otherwise, we respond with an introduction response. .. py:method:: on_old_introduction_response(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.IntroductionResponsePayload) -> None Interception callback for when we receive an old IPv4-only introduction response. Message handling is performed in ``on_introduction_response()``. .. py:method:: on_new_introduction_response(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.NewIntroductionResponsePayload) -> None Interception callback for when we receive a new (non-IPv4-only) introduction response. Message handling is performed in ``on_introduction_response()``. .. py:method:: on_introduction_response(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 Callback to handle introduction responses. .. py:method:: on_puncture(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.PuncturePayload) -> None When we receive a puncture, we do nothing. .. py:method:: on_new_puncture(peer: 3.0.ipv8.peer.Peer, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.NewPuncturePayload) -> None When we receive a new-style puncture, we do nothing. .. py:method:: on_old_puncture_request(source_address: 3.0.ipv8.types.Address, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.PunctureRequestPayload) -> None Interception callback for when we receive an old IPv4-only puncture request. Message handling is performed in ``on_puncture_request()``. .. py:method:: on_new_puncture_request(source_address: 3.0.ipv8.types.Address, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.NewPunctureRequestPayload) -> None Interception callback for when we receive a new (non-IPv4-only) puncture request. Message handling is performed in ``on_puncture_request()``. .. py:method:: on_puncture_request(source_address: 3.0.ipv8.types.Address, dist: 3.0.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: 3.0.ipv8.messaging.payload.PunctureRequestPayload | 3.0.ipv8.messaging.payload.NewPunctureRequestPayload, new_style: bool = False) -> None Callback to handle puncture requests. We send a puncture to the requested address. .. py:method:: on_packet(packet: tuple[3.0.ipv8.types.Address, bytes], warn_unknown: bool = True) -> None Callback for when the Endpoint has new data for us. :param packet: The address, bytes tuple that was received. :param warn_unknown: Whether we should log incoming garbage data. .. py:method:: walk_to(address: 3.0.ipv8.types.Address) -> None Attempt to walk directly to the given address. .. py:method:: send_introduction_request(peer: 3.0.ipv8.peer.Peer) -> None Send an introduction request to a specific peer. .. py:method:: get_new_introduction(from_peer: 3.0.ipv8.peer.Peer | None = None) -> None Get a new introduction, or bootstrap if there are no available peers. .. py:method:: get_peer_for_introduction(exclude: 3.0.ipv8.peer.Peer | None = None, new_style: bool = False) -> 3.0.ipv8.peer.Peer | None Return a random peer to send an introduction request to. .. py:method:: get_walkable_addresses() -> list[3.0.ipv8.types.Address] Get the addresses that we know of but have not been contacted to become a peer. .. py:method:: get_peers() -> list[3.0.ipv8.peer.Peer] Get the peers that we are currently connected to (and we have received signed messages from).