Struct libp2p_gossipsub::Gossipsub

pub struct Gossipsub<D: DataTransform = IdentityTransform, F: TopicSubscriptionFilter = AllowAllSubscriptionFilter> { /* 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<Self, &'static str>

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

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

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

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

pub fn new_with_subscription_filter(
    privacy: MessageAuthenticity,
    config: GossipsubConfig,
    metrics: Option<(&mut Registry, MetricsConfig)>,
    subscription_filter: F
) -> Result<Self, &'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,
    metrics: Option<(&mut Registry, MetricsConfig)>,
    data_transform: D
) -> Result<Self, &'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,
    metrics: Option<(&mut Registry, MetricsConfig)>,
    subscription_filter: F,
    data_transform: D
) -> Result<Self, &'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 + 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>

Lists all mesh peers for all topics.

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<H: Hasher>(
    &mut self,
    topic: Topic<H>,
    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 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: 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 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 Gossipsub<C, F>

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

Formats the value using the given formatter.

impl<C, F> NetworkBehaviour for Gossipsub<C, F> where
    C: Send + 'static + DataTransform,
    F: Send + 'static + 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.

fn new_handler(&mut self) -> Self::ProtocolsHandler

Creates a new ProtocolsHandler for a connection with a peer.

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

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

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

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

fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    connection_id: &ConnectionId,
    endpoint: &ConnectedPoint,
    _: Option<&Vec<Multiaddr>>
)

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

fn inject_connection_closed(
    &mut self,
    peer_id: &PeerId,
    connection_id: &ConnectionId,
    endpoint: &ConnectedPoint,
    _: <Self::ProtocolsHandler as IntoProtocolsHandler>::Handler
)

Informs the behaviour about a closed connection to a peer.

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.

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.

fn poll(
    &mut self,
    cx: &mut Context<'_>,
    _: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ProtocolsHandler>>

Polls for things that swarm should do.

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.

fn inject_dial_failure(
    &mut self,
    _peer_id: Option<PeerId>,
    _handler: Self::ProtocolsHandler,
    _error: &DialError
)

Indicates to the behaviour that the dial to a known or unknown node failed.

fn inject_listen_failure(
    &mut self,
    _local_addr: &Multiaddr,
    _send_back_addr: &Multiaddr,
    _handler: Self::ProtocolsHandler
)

Indicates to the behaviour that an error happened on an incoming connection during its initial handshake.

fn inject_new_listener(&mut self, _id: ListenerId)

Indicates to the behaviour that a new listener was created.

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

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

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

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

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.

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_expired_external_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that an external address was removed.