Struct libp2p::gossipsub::GossipsubConfigBuilder

pub struct GossipsubConfigBuilder { /* private fields */ }

The builder struct for constructing a gossipsub configuration.

Implementations

impl GossipsubConfigBuilder

pub fn protocol_id_prefix(
    &mut self,
    protocol_id: impl Into<Cow<'static, str>>
) -> &mut GossipsubConfigBuilder

The protocol id to negotiate this protocol (default is /meshsub/1.0.0).

pub fn history_length(
    &mut self,
    history_length: usize
) -> &mut GossipsubConfigBuilder

Number of heartbeats to keep in the memcache (default is 5).

pub fn history_gossip(
    &mut self,
    history_gossip: usize
) -> &mut GossipsubConfigBuilder

Number of past heartbeats to gossip about (default is 3).

pub fn mesh_n(&mut self, mesh_n: usize) -> &mut GossipsubConfigBuilder

Target number of peers for the mesh network (D in the spec, default is 6).

pub fn mesh_n_low(&mut self, mesh_n_low: usize) -> &mut GossipsubConfigBuilder

Minimum number of peers in mesh network before adding more (D_lo in the spec, default is 4).

pub fn mesh_n_high(&mut self, mesh_n_high: usize) -> &mut GossipsubConfigBuilder

Maximum number of peers in mesh network before removing some (D_high in the spec, default is 12).

pub fn retain_scores(
    &mut self,
    retain_scores: usize
) -> &mut GossipsubConfigBuilder

Affects how peers are selected when pruning a mesh due to over subscription.

At least Self::retain_scores of the retained peers will be high-scoring, while the remainder are chosen randomly (D_score in the spec, default is 4).

pub fn gossip_lazy(&mut self, gossip_lazy: usize) -> &mut GossipsubConfigBuilder

Minimum number of peers to emit gossip to during a heartbeat (D_lazy in the spec, default is 6).

pub fn gossip_factor(
    &mut self,
    gossip_factor: f64
) -> &mut GossipsubConfigBuilder

Affects how many peers we will emit gossip to at each heartbeat.

We will send gossip to gossip_factor * (total number of non-mesh peers), or gossip_lazy, whichever is greater. The default is 0.25.

pub fn heartbeat_initial_delay(
    &mut self,
    heartbeat_initial_delay: Duration
) -> &mut GossipsubConfigBuilder

Initial delay in each heartbeat (default is 5 seconds).

pub fn heartbeat_interval(
    &mut self,
    heartbeat_interval: Duration
) -> &mut GossipsubConfigBuilder

Time between each heartbeat (default is 1 second).

pub fn check_explicit_peers_ticks(
    &mut self,
    check_explicit_peers_ticks: u64
) -> &mut GossipsubConfigBuilder

The number of heartbeat ticks until we recheck the connection to explicit peers and reconnecting if necessary (default 300).

pub fn fanout_ttl(
    &mut self,
    fanout_ttl: Duration
) -> &mut GossipsubConfigBuilder

Time to live for fanout peers (default is 60 seconds).

pub fn max_transmit_size(
    &mut self,
    max_transmit_size: usize
) -> &mut GossipsubConfigBuilder

The maximum byte size for each gossip (default is 2048 bytes).

pub fn duplicate_cache_time(
    &mut self,
    cache_size: Duration
) -> &mut GossipsubConfigBuilder

Duplicates are prevented by storing message id’s of known messages in an LRU time cache. This settings sets the time period that messages are stored in the cache. Duplicates can be received if duplicate messages are sent at a time greater than this setting apart. The default is 1 minute.

pub fn validate_messages(&mut self) -> &mut GossipsubConfigBuilder

When set, prevents automatic forwarding of all received messages. This setting allows a user to validate the messages before propagating them to their peers. If set, the user must manually call crate::Gossipsub::report_message_validation_result() on the behaviour to forward a message once validated.

pub fn validation_mode(
    &mut self,
    validation_mode: ValidationMode
) -> &mut GossipsubConfigBuilder

Determines the level of validation used when receiving messages. See ValidationMode for the available types. The default is ValidationMode::Strict.

pub fn message_id_fn(
    &mut self,
    id_fn: fn(&GossipsubMessage) -> MessageId
) -> &mut GossipsubConfigBuilder

A user-defined function allowing the user to specify the message id of a gossipsub message. The default value is to concatenate the source peer id with a sequence number. Setting this parameter allows the user to address packets arbitrarily. One example is content based addressing, where this function may be set to hash(message). This would prevent messages of the same content from being duplicated.

The function takes a GossipsubMessage as input and outputs a String to be interpreted as the message id.

pub fn fast_message_id_fn(
    &mut self,
    fast_id_fn: fn(&RawGossipsubMessage) -> FastMessageId
) -> &mut GossipsubConfigBuilder

A user-defined optional function that computes fast ids from raw messages. This can be used to avoid possibly expensive transformations from RawGossipsubMessage to GossipsubMessage for duplicates. Two semantically different messages must always have different fast message ids, but it is allowed that two semantically identical messages have different fast message ids as long as the message_id_fn produces the same id for them.

The function takes a RawGossipsubMessage as input and outputs a String to be interpreted as the fast message id. Default is None.

pub fn do_px(&mut self) -> &mut GossipsubConfigBuilder

Enables Peer eXchange. This should be enabled in bootstrappers and other well connected/trusted nodes. The default is true.

pub fn prune_peers(&mut self, prune_peers: usize) -> &mut GossipsubConfigBuilder

Controls the number of peers to include in prune Peer eXchange.

When we prune a peer that’s eligible for PX (has a good score, etc), we will try to send them signed peer records for up to Self::prune_peers] other peers that we know of. It is recommended that this value is larger than [Self::mesh_n_high` so that the pruned peer can reliably form a full mesh. The default is 16.

pub fn prune_backoff(
    &mut self,
    prune_backoff: Duration
) -> &mut GossipsubConfigBuilder

Controls the backoff time for pruned peers. This is how long a peer must wait before attempting to graft into our mesh again after being pruned. When pruning a peer, we send them our value of Self::prune_backoff so they know the minimum time to wait. Peers running older versions may not send a backoff time, so if we receive a prune message without one, we will wait at least Self::prune_backoff before attempting to re-graft. The default is one minute.

pub fn backoff_slack(
    &mut self,
    backoff_slack: u32
) -> &mut GossipsubConfigBuilder

Number of heartbeat slots considered as slack for backoffs. This gurantees that we wait at least backoff_slack heartbeats after a backoff is over before we try to graft. This solves problems occuring through high latencies. In particular if backoff_slack * heartbeat_interval is longer than any latencies between processing prunes on our side and processing prunes on the receiving side this guarantees that we get not punished for too early grafting. The default is 1.

pub fn flood_publish(
    &mut self,
    flood_publish: bool
) -> &mut GossipsubConfigBuilder

Whether to do flood publishing or not. If enabled newly created messages will always be sent to all peers that are subscribed to the topic and have a good enough score. The default is true.

pub fn graft_flood_threshold(
    &mut self,
    graft_flood_threshold: Duration
) -> &mut GossipsubConfigBuilder

If a GRAFT comes before graft_flood_threshold has elapsed since the last PRUNE, then there is an extra score penalty applied to the peer through P7.

pub fn mesh_outbound_min(
    &mut self,
    mesh_outbound_min: usize
) -> &mut GossipsubConfigBuilder

Minimum number of outbound peers in the mesh network before adding more (D_out in the spec). This value must be smaller or equal than mesh_n / 2 and smaller than mesh_n_low. The default is 2.

pub fn opportunistic_graft_ticks(
    &mut self,
    opportunistic_graft_ticks: u64
) -> &mut GossipsubConfigBuilder

Number of heartbeat ticks that specifcy the interval in which opportunistic grafting is applied. Every opportunistic_graft_ticks we will attempt to select some high-scoring mesh peers to replace lower-scoring ones, if the median score of our mesh peers falls below a threshold (see https://godoc.org/github.com/libp2p/go-libp2p-pubsub#PeerScoreThresholds). The default is 60.

pub fn gossip_retransimission(
    &mut self,
    gossip_retransimission: u32
) -> &mut GossipsubConfigBuilder

Controls how many times we will allow a peer to request the same message id through IWANT gossip before we start ignoring them. This is designed to prevent peers from spamming us with requests and wasting our resources.

pub fn opportunistic_graft_peers(
    &mut self,
    opportunistic_graft_peers: usize
) -> &mut GossipsubConfigBuilder

The maximum number of new peers to graft to during opportunistic grafting. The default is 2.

pub fn max_messages_per_rpc(
    &mut self,
    max: Option<usize>
) -> &mut GossipsubConfigBuilder

The maximum number of messages we will process in a given RPC. If this is unset, there is no limit. The default is None.

pub fn max_ihave_length(
    &mut self,
    max_ihave_length: usize
) -> &mut GossipsubConfigBuilder

The maximum number of messages to include in an IHAVE message. Also controls the maximum number of IHAVE ids we will accept and request with IWANT from a peer within a heartbeat, to protect from IHAVE floods. You should adjust this value from the default if your system is pushing more than 5000 messages in GossipSubHistoryGossip heartbeats; with the defaults this is 1666 messages/s. The default is 5000.

pub fn max_ihave_messages(
    &mut self,
    max_ihave_messages: usize
) -> &mut GossipsubConfigBuilder

GossipSubMaxIHaveMessages is the maximum number of IHAVE messages to accept from a peer within a heartbeat.

pub fn allow_self_origin(
    &mut self,
    allow_self_origin: bool
) -> &mut GossipsubConfigBuilder

By default, gossipsub will reject messages that are sent to us that has the same message source as we have specified locally. Enabling this, allows these messages and prevents penalizing the peer that sent us the message. Default is false.

pub fn iwant_followup_time(
    &mut self,
    iwant_followup_time: Duration
) -> &mut GossipsubConfigBuilder

Time to wait for a message requested through IWANT following an IHAVE advertisement. If the message is not received within this window, a broken promise is declared and the router may apply behavioural penalties. The default is 3 seconds.

pub fn support_floodsub(&mut self) -> &mut GossipsubConfigBuilder

Enable support for flooodsub peers.

pub fn published_message_ids_cache_time(
    &mut self,
    published_message_ids_cache_time: Duration
) -> &mut GossipsubConfigBuilder

Published message ids time cache duration. The default is 10 seconds.

pub fn build(&self) -> Result<GossipsubConfig, &str>

Constructs a GossipsubConfig from the given configuration and validates the settings.

Trait Implementations

impl Default for GossipsubConfigBuilder

pub fn default() -> GossipsubConfigBuilder

Returns the “default value” for a type.

impl From<GossipsubConfig> for GossipsubConfigBuilder

pub fn from(config: GossipsubConfig) -> GossipsubConfigBuilder

Performs the conversion.