latest.ipv8.community

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

Module Contents

Classes

CommunitySettings	Community settings, extensible for Community subclasses.
Community	Base class for overlay functionality with a rich set of defaults.

Attributes

_UNUSED_FLAGS_REQ
_UNUSED_FLAGS_RESP
DEFAULT_MAX_PEERS

latest.ipv8.community._UNUSED_FLAGS_REQ

latest.ipv8.community._UNUSED_FLAGS_RESP

latest.ipv8.community.DEFAULT_MAX_PEERS = 30

class latest.ipv8.community.CommunitySettings

Bases: latest.ipv8.overlay.Settings

Community settings, extensible for Community subclasses.

max_peers: int

The number of peers we will grow to before we start rejecting new connections.

anonymize: bool = False

Request use of a TunnelEndpoint to anonymize all our traffic.

class latest.ipv8.community.Community(settings: CommunitySettings)

Bases: latest.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.

version = b'\x02'

community_id: bytes

settings_class

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.

async unload() → None

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.

add_message_handler(msg_num: int | type[latest.ipv8.types.Payload], callback: latest.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.

Parameters:

• msg_num – the message id to listen for (or a Payload object with a msg_id field)

• callback – the callback function for this message id

on_deprecated_message(source_address: latest.ipv8.types.Address, data: bytes) → None

Callback for when we receive a known-to-be-deprecated message.

bootstrap() → None

Contact the bootstrappers for new peers, initialize the bootstrappers if necessary.

async _bootstrap(bootstrapper: latest.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper) → None

Contact a single bootstrapper for new peers and initialize if necessary.

ensure_blacklisted(address: latest.ipv8.types.Address) → None

Add an address to the blacklist, if it is not already there.

guess_address(interface: str) → latest.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.

my_preferred_address() → latest.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.

create_introduction_request(socket_address: latest.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.

Parameters:

• socket_address – The address to send to.

• extra_bytes – The extra bytes to piggyback onto this message.

• new_style – Whether we support “new style” (non-IPv4) introduction requests.

• prefix – Send to a different community id (EXPERT USE ONLY).

create_introduction_response(lan_socket_address: latest.ipv8.types.Address, socket_address: latest.ipv8.types.Address, identifier: int, introduction: latest.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.

Parameters:

• lan_socket_address – What the request sender thinks our address is.

• socket_address – The request sender’s address.

• identifier – The introduction request identifier that we are responding to.

• introduction – Introduce the request sender to this given peer.

• extra_bytes – The extra bytes to piggyback onto this message.

• prefix – Send to a different community id (EXPERT USE ONLY).

• new_style – Whether we support “new style” (non-IPv4) introduction requests.

create_puncture(lan_walker: latest.ipv8.types.Address, wan_walker: latest.ipv8.types.Address, identifier: int, new_style: bool = False) → bytes

Create a puncture message for the given LAN/WAN address.

Parameters:

• lan_walker – The LAN address to puncture.

• wan_walker – The WAN address to puncture.

• identifier – The PunctureRequest identifier we are responding to.

• new_style – Whether we support “new style” (non-IPv4) introduction requests.

create_puncture_request(lan_walker: latest.ipv8.types.Address, wan_walker: latest.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.

Parameters:

• lan_walker – The LAN address to request puncturing for.

• wan_walker – The WAN address to request puncturing for.

• identifier – The identifier to use for this message.

• prefix – Send to a different community id (EXPERT USE ONLY).

• new_style – Whether we support “new style” (non-IPv4) introduction requests.

introduction_request_callback(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.IntroductionRequestPayload | latest.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

introduction_response_callback(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.IntroductionResponsePayload | latest.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

on_old_introduction_request(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.IntroductionRequestPayload | latest.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().

on_new_introduction_request(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.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().

on_introduction_request(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.IntroductionRequestPayload | latest.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.

on_old_introduction_response(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.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().

on_new_introduction_response(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.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().

on_introduction_response(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.IntroductionResponsePayload | latest.ipv8.messaging.payload.NewIntroductionResponsePayload) → None

Callback to handle introduction responses.

on_puncture(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.PuncturePayload) → None

When we receive a puncture, we do nothing.

on_new_puncture(peer: latest.ipv8.peer.Peer, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.NewPuncturePayload) → None

When we receive a new-style puncture, we do nothing.

on_old_puncture_request(source_address: latest.ipv8.types.Address, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.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().

on_new_puncture_request(source_address: latest.ipv8.types.Address, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.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().

on_puncture_request(source_address: latest.ipv8.types.Address, dist: latest.ipv8.messaging.payload_headers.GlobalTimeDistributionPayload, payload: latest.ipv8.messaging.payload.PunctureRequestPayload | latest.ipv8.messaging.payload.NewPunctureRequestPayload, new_style: bool = False) → None

Callback to handle puncture requests.

We send a puncture to the requested address.

on_packet(packet: tuple[latest.ipv8.types.Address, bytes], warn_unknown: bool = True) → None

Callback for when the Endpoint has new data for us.

Parameters:

• packet – The address, bytes tuple that was received.

• warn_unknown – Whether we should log incoming garbage data.

walk_to(address: latest.ipv8.types.Address) → None

Attempt to walk directly to the given address.

send_introduction_request(peer: latest.ipv8.peer.Peer) → None

Send an introduction request to a specific peer.

get_new_introduction(from_peer: latest.ipv8.peer.Peer | None = None) → None

Get a new introduction, or bootstrap if there are no available peers.

get_peer_for_introduction(exclude: latest.ipv8.peer.Peer | None = None, new_style: bool = False) → latest.ipv8.peer.Peer | None

Return a random peer to send an introduction request to.

get_walkable_addresses() → list[latest.ipv8.types.Address]

Get the addresses that we know of but have not been contacted to become a peer.

get_peers() → list[latest.ipv8.peer.Peer]

Get the peers that we are currently connected to (and we have received signed messages from).