Struct libp2p::gossipsub::Gossipsub

pub struct Gossipsub<D = IdentityTransform, F = AllowAllSubscriptionFilter> where
    D: DataTransform,
    F: TopicSubscriptionFilter,  { /* private fields */ }

Network behaviour that handles the gossipsub protocol.

NOTE: Initialisation requires a MessageAuthenticity and GossipsubConfig instance. If message signing is disabled, the ValidationMode in the config should be adjusted to an appropriate level to accept unsigned messages.

The DataTransform trait allows applications to optionally add extra encoding/decoding functionality to the underlying messages. This is intended for custom compression algorithms.

The TopicSubscriptionFilter allows applications to implement specific filters on topics to prevent unwanted messages being propagated and evaluated.

Implementations

impl<D, F> Gossipsub<D, F> where
    D: DataTransform + Default,
    F: TopicSubscriptionFilter + Default, 

pub fn new(
    privacy: MessageAuthenticity,
    config: GossipsubConfig
) -> Result<Gossipsub<D, F>, &'static str>

Creates a Gossipsub struct given a set of parameters specified via a GossipsubConfig. This has no subscription filter and uses no compression.

impl<D, F> Gossipsub<D, F> where
    D: DataTransform + Default,
    F: TopicSubscriptionFilter, 

pub fn new_with_subscription_filter(
    privacy: MessageAuthenticity,
    config: GossipsubConfig,
    subscription_filter: F
) -> Result<Gossipsub<D, F>, &'static str>

Creates a Gossipsub struct given a set of parameters specified via a GossipsubConfig and a custom subscription filter.

impl<D, F> Gossipsub<D, F> where
    D: DataTransform,
    F: TopicSubscriptionFilter + Default, 

pub fn new_with_transform(
    privacy: MessageAuthenticity,
    config: GossipsubConfig,
    data_transform: D
) -> Result<Gossipsub<D, F>, &'static str>

Creates a Gossipsub struct given a set of parameters specified via a GossipsubConfig and a custom data transform.

impl<D, F> Gossipsub<D, F> where
    D: DataTransform,
    F: TopicSubscriptionFilter, 

pub fn new_with_subscription_filter_and_transform(
    privacy: MessageAuthenticity,
    config: GossipsubConfig,
    subscription_filter: F,
    data_transform: D
) -> Result<Gossipsub<D, F>, &'static str>

Creates a Gossipsub struct given a set of parameters specified via a GossipsubConfig and a custom subscription filter and data transform.

impl<D, F> Gossipsub<D, F> where
    D: DataTransform,
    F: TopicSubscriptionFilter, 

pub fn topics(&self) -> impl Iterator<Item = &TopicHash>

Lists the hashes of the topics we are currently subscribed to.

pub fn mesh_peers(
    &self,
    topic_hash: &TopicHash
) -> impl Iterator<Item = &PeerId>

Lists all mesh peers for a certain topic hash.

pub fn all_mesh_peers(&self) -> impl Iterator<Item = &PeerId>

Lists all mesh peers for all topics.

pub fn all_peers(
    &self
) -> impl Iterator<Item = (&PeerId, Vec<&TopicHash, Global>)>

Lists all known peers and their associated subscribed topics.

pub fn peer_protocol(&self) -> impl Iterator<Item = (&PeerId, &PeerKind)>

Lists all known peers and their associated protocol.

pub fn peer_score(&self, peer_id: &PeerId) -> Option<f64>

Returns the gossipsub score for a given peer, if one exists.

pub fn subscribe<H>(
    &mut self,
    topic: &Topic<H>
) -> Result<bool, SubscriptionError> where
    H: Hasher, 

Subscribe to a topic.

Returns [Ok(true)] if the subscription worked. Returns [Ok(false)] if we were already subscribed.

pub fn unsubscribe<H>(&mut self, topic: &Topic<H>) -> Result<bool, PublishError> where
    H: Hasher, 

Unsubscribes from a topic.

Returns [Ok(true)] if we were subscribed to this topic.

pub fn publish<H>(
    &mut self,
    topic: Topic<H>,
    data: impl Into<Vec<u8, Global>>
) -> Result<MessageId, PublishError> where
    H: Hasher, 

Publishes a message with multiple topics to the network.

pub fn report_message_validation_result(
    &mut self,
    msg_id: &MessageId,
    propagation_source: &PeerId,
    acceptance: MessageAcceptance
) -> Result<bool, PublishError>

This function should be called when GossipsubConfig::validate_messages() is true after the message got validated by the caller. Messages are stored in the [‘Memcache’] and validation is expected to be fast enough that the messages should still exist in the cache. There are three possible validation outcomes and the outcome is given in acceptance.

If acceptance = MessageAcceptance::Accept the message will get propagated to the network. The propagation_source parameter indicates who the message was received by and will not be forwarded back to that peer.

If acceptance = MessageAcceptance::Reject the message will be deleted from the memcache and the P₄ penalty will be applied to the propagation_source. If acceptance = MessageAcceptance::Ignore the message will be deleted from the memcache but no P₄ penalty will be applied.

This function will return true if the message was found in the cache and false if was not in the cache anymore.

This should only be called once per message.

pub fn add_explicit_peer(&mut self, peer_id: &PeerId)

Adds a new peer to the list of explicitly connected peers.

pub fn remove_explicit_peer(&mut self, peer_id: &PeerId)

This removes the peer from explicitly connected peers, note that this does not disconnect the peer.

pub fn blacklist_peer(&mut self, peer_id: &PeerId)

Blacklists a peer. All messages from this peer will be rejected and any message that was created by this peer will be rejected.

pub fn remove_blacklisted_peer(&mut self, peer_id: &PeerId)

Removes a peer from the blacklist if it has previously been blacklisted.

pub fn with_peer_score(
    &mut self,
    params: PeerScoreParams,
    threshold: PeerScoreThresholds
) -> Result<(), String>

Activates the peer scoring system with the given parameters. This will reset all scores if there was already another peer scoring system activated. Returns an error if the params are not valid or if they got already set.

pub fn with_peer_score_and_message_delivery_time_callback(
    &mut self,
    params: PeerScoreParams,
    threshold: PeerScoreThresholds,
    callback: Option<fn(&PeerId, &TopicHash, f64)>
) -> Result<(), String>

Activates the peer scoring system with the given parameters and a message delivery time callback. Returns an error if the parameters got already set.

pub fn set_topic_params<H>(
    &mut self,
    topic: Topic<H>,
    params: TopicScoreParams
) -> Result<(), &'static str> where
    H: Hasher, 

Sets scoring parameters for a topic.

The Self::with_peer_score() must first be called to initialise peer scoring.

pub fn set_application_score(
    &mut self,
    peer_id: &PeerId,
    new_score: f64
) -> bool

Sets the application specific score for a peer. Returns true if scoring is active and the peer is connected or if the score of the peer is not yet expired, false otherwise.

Trait Implementations

impl<C, F> Debug for Gossipsub<C, F> where
    C: DataTransform,
    F: TopicSubscriptionFilter, 

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<C, F> NetworkBehaviour for Gossipsub<C, F> where
    C: 'static + Send + DataTransform,
    F: 'static + Send + TopicSubscriptionFilter, 

type ProtocolsHandler = GossipsubHandler

Handler for all the protocols the network behaviour supports.

type OutEvent = GossipsubEvent

Event generated by the NetworkBehaviour and that the swarm will report back.

pub fn new_handler(
    &mut self
) -> <Gossipsub<C, F> as NetworkBehaviour>::ProtocolsHandler

Creates a new ProtocolsHandler for a connection with a peer.

pub fn addresses_of_peer(&mut self, &PeerId) -> Vec<Multiaddr, Global>

Addresses that this behaviour is aware of for this specific peer, and that may allow reaching the peer.

pub fn inject_connected(&mut self, peer_id: &PeerId)

Indicates the behaviour that we connected to the node with the given peer id.

pub fn inject_disconnected(&mut self, peer_id: &PeerId)

Indicates the behaviour that we disconnected from the node with the given peer id.

pub fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    &ConnectionId,
    endpoint: &ConnectedPoint
)

Informs the behaviour about a newly established connection to a peer.

pub fn inject_connection_closed(
    &mut self,
    peer: &PeerId,
    &ConnectionId,
    endpoint: &ConnectedPoint
)

Informs the behaviour about a closed connection to a peer.

pub fn inject_address_change(
    &mut self,
    peer: &PeerId,
    &ConnectionId,
    endpoint_old: &ConnectedPoint,
    endpoint_new: &ConnectedPoint
)

Informs the behaviour that the ConnectedPoint of an existing connection has changed.

pub fn inject_event(
    &mut self,
    propagation_source: PeerId,
    ConnectionId,
    handler_event: HandlerEvent
)

Informs the behaviour about an event generated by the handler dedicated to the peer identified by peer_id. for the behaviour.

pub fn poll(
    &mut self,
    cx: &mut Context<'_>,
    &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<<<Gossipsub<C, F> as NetworkBehaviour>::ProtocolsHandler as ProtocolsHandler>::InEvent, <Gossipsub<C, F> as NetworkBehaviour>::OutEvent>>

Polls for things that swarm should do.

fn inject_addr_reach_failure(
    &mut self,
    _peer_id: Option<&PeerId>,
    _addr: &Multiaddr,
    _error: &dyn Error
)

Indicates to the behaviour that we tried to reach an address, but failed.

fn inject_dial_failure(&mut self, _peer_id: &PeerId)

Indicates to the behaviour that we tried to dial all the addresses known for a node, but failed.

fn inject_new_listen_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that we have started listening on a new multiaddr.

fn inject_expired_listen_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that a new multiaddr we were listening on has expired, which means that we are no longer listening in it.

fn inject_new_external_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that we have discovered a new external address for us.

fn inject_listener_error(
    &mut self,
    _id: ListenerId,
    _err: &(dyn Error + 'static)
)

A listener experienced an error.

fn inject_listener_closed(
    &mut self,
    _id: ListenerId,
    _reason: Result<(), &Error>
)

A listener closed.