Struct libp2p_gossipsub::Behaviour

pub struct Behaviour<D = IdentityTransform, F = AllowAllSubscriptionFilter> { /* private fields */ }

Network behaviour that handles the gossipsub protocol.

NOTE: Initialisation requires a MessageAuthenticity and Config 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> Behaviour<D, F>

where D: DataTransform + Default, F: TopicSubscriptionFilter + Default,

pub fn new( privacy: MessageAuthenticity, config: Config, ) -> Result<Self, &'static str>

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

pub fn new_with_metrics( privacy: MessageAuthenticity, config: Config, metrics_registry: &mut Registry, metrics_config: MetricsConfig, ) -> Result<Self, &'static str>

Creates a Gossipsub Behaviour struct given a set of parameters specified via a Config. This has no subscription filter and uses no compression. Metrics can be evaluated by passing a reference to a Registry.

impl<D, F> Behaviour<D, F>

where D: DataTransform + Default, F: TopicSubscriptionFilter,

pub fn new_with_subscription_filter( privacy: MessageAuthenticity, config: Config, metrics: Option<(&mut Registry, MetricsConfig)>, subscription_filter: F, ) -> Result<Self, &'static str>

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

impl<D, F> Behaviour<D, F>

where D: DataTransform, F: TopicSubscriptionFilter + Default,

pub fn new_with_transform( privacy: MessageAuthenticity, config: Config, metrics: Option<(&mut Registry, MetricsConfig)>, data_transform: D, ) -> Result<Self, &'static str>

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

impl<D, F> Behaviour<D, F>

where D: DataTransform, F: TopicSubscriptionFilter,

pub fn new_with_subscription_filter_and_transform( privacy: MessageAuthenticity, config: Config, metrics: Option<(&mut Registry, MetricsConfig)>, subscription_filter: F, data_transform: D, ) -> Result<Self, &'static str>

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

impl<D, F> Behaviour<D, F>

where D: DataTransform + Send + 'static, F: TopicSubscriptionFilter + Send + 'static,

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>

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

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: Hasher>( &mut self, topic: &Topic<H>, ) -> Result<bool, SubscriptionError>

Subscribe to a topic.

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

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

Unsubscribes from a topic.

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

pub fn publish( &mut self, topic: impl Into<TopicHash>, data: impl Into<Vec<u8>>, ) -> Result<MessageId, PublishError>

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 Config::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: Hasher>( &mut self, topic: Topic<H>, params: TopicScoreParams, ) -> Result<(), &'static str>

Sets scoring parameters for a topic.

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

pub fn get_topic_params<H: Hasher>( &self, topic: &Topic<H>, ) -> Option<&TopicScoreParams>

Returns a scoring parameters for a topic if existent.

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: DataTransform, F: TopicSubscriptionFilter> Debug for Behaviour<C, F>

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

Formats the value using the given formatter.

impl<C, F> NetworkBehaviour for Behaviour<C, F>

where C: Send + 'static + DataTransform, F: Send + 'static + TopicSubscriptionFilter,

type ConnectionHandler = Handler

Handler for all the protocols the network behaviour supports.

type ToSwarm = Event

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

fn handle_established_inbound_connection( &mut self, _: ConnectionId, _: PeerId, _: &Multiaddr, _: &Multiaddr, ) -> Result<THandler<Self>, ConnectionDenied>

Callback that is invoked for every established inbound connection.

fn handle_established_outbound_connection( &mut self, _: ConnectionId, _: PeerId, _: &Multiaddr, _: Endpoint, _: PortUse, ) -> Result<THandler<Self>, ConnectionDenied>

Callback that is invoked for every established outbound connection.

fn on_connection_handler_event( &mut self, propagation_source: PeerId, _connection_id: ConnectionId, handler_event: THandlerOutEvent<Self>, )

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

fn poll( &mut self, cx: &mut Context<'_>, ) -> Poll<ToSwarm<Self::ToSwarm, THandlerInEvent<Self>>>

Polls for things that swarm should do.

fn on_swarm_event(&mut self, event: FromSwarm<'_>)

Informs the behaviour about an event from the Swarm.

fn handle_pending_inbound_connection( &mut self, _connection_id: ConnectionId, _local_addr: &Multiaddr, _remote_addr: &Multiaddr, ) -> Result<(), ConnectionDenied>

Callback that is invoked for every new inbound connection.

fn handle_pending_outbound_connection( &mut self, _connection_id: ConnectionId, _maybe_peer: Option<PeerId>, _addresses: &[Multiaddr], _effective_role: Endpoint, ) -> Result<Vec<Multiaddr>, ConnectionDenied>

Callback that is invoked for every outbound connection attempt.