peers

Documentation

Overview

Package peers provides a peer manager that handles peer discovery and peer selection for the shrex getter.

The peer manager is responsible for:

• Discovering peers
• Selecting peers for data retrieval
• Validating peers
• Blacklisting peers
• Garbage collecting peers

The peer manager is not responsible for:

• Connecting to peers
• Disconnecting from peers
• Sending data to peers
• Receiving data from peers

The peer manager is a mechanism to store peers from shrexsub, a mechanism that handles "peer discovery" and "peer selection" by relying on a shrexsub subscription and header subscriptions, such that it listens for new headers and new shares and uses this information to pool peers by shares.

This gives the peer manager an ability to block peers that gossip invalid shares, but also access a list of peers that are known to have been gossiping valid shares. The peers are then returned on request using a round-robin algorithm to return a different peer each time. If no peers are found, the peer manager will rely on full nodes retrieved from discovery.

The peer manager is only concerned with recent heights, thus it retrieves peers that were active since `initialHeight`. The peer manager will also garbage collect peers such that it blacklists peers that have been active since `initialHeight` but have been found to be invalid.

The peer manager is passed to the shrex getter and is used at request time to select peers for a given data hash for data retrieval.

Usage

The peer manager is created using NewManager constructor:

peerManager := peers.NewManager(headerSub, shrexSub, discovery, host, connGater, opts...)

After creating the peer manager, it should be started to kick off listening and validation routines that enable peer selection and retrieval:

err := peerManager.Start(ctx)

The peer manager can be stopped at any time to stop all peer discovery and validation routines:

err := peerManager.Stop(ctx)

The peer manager can be used to select peers for a given datahash for shares retrieval:

peer, err := peerManager.Peer(ctx, hash)

Index

• Constants
• type DoneFunc
• type Manager
  • func NewManager(params Parameters, host host.Host, connGater *conngater.BasicConnectionGater, ...) (*Manager, error)
  • func (m *Manager) GC(ctx context.Context)
  • func (m *Manager) Peer(ctx context.Context, datahash share.DataHash) (peer.ID, DoneFunc, error)
  • func (m *Manager) Start(startCtx context.Context) error
  • func (m *Manager) Stop(ctx context.Context) error
  • func (m *Manager) UpdateFullNodePool(peerID peer.ID, isAdded bool)
  • func (m *Manager) Validate(_ context.Context, peerID peer.ID, msg shrexsub.Notification) pubsub.ValidationResult
  • func (m *Manager) WithMetrics() error
• type Option
  • func WithShrexSubPools(shrexSub *shrexsub.PubSub, ...) Option
• type Parameters
  • func DefaultParameters() Parameters
  • func (p *Parameters) Validate() error

Constants

const (
	// ResultNoop indicates operation was successful and no extra action is required
	ResultNoop result = "result_noop"
	// ResultSynced will save the status of pool as "synced" and will remove peers from it
	ResultSynced = "result_synced"
	// ResultCooldownPeer will put returned peer on cooldown, meaning it won't be available by Peer
	// method for some time
	ResultCooldownPeer = "result_cooldown_peer"
	// ResultBlacklistPeer will blacklist peer. Blacklisted peers will be disconnected and blocked from
	// any p2p communication in future by libp2p Gater
	ResultBlacklistPeer = "result_blacklist_peer"
)

Types

type DoneFunc

type DoneFunc func(result)

DoneFunc updates internal state depending on call results. Should be called once per returned peer from Peer method

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager keeps track of peers coming from shrex.Sub and from discovery

func NewManager

func NewManager(
	params Parameters,
	host host.Host,
	connGater *conngater.BasicConnectionGater,
	options ...Option,
) (*Manager, error)

func (*Manager) GC

func (m *Manager) GC(ctx context.Context)

func (*Manager) Peer

func (m *Manager) Peer(
	ctx context.Context, datahash share.DataHash,
) (peer.ID, DoneFunc, error)

Peer returns peer collected from shrex.Sub for given datahash if any available. If there is none, it will look for full nodes collected from discovery. If there is no discovered full nodes, it will wait until any peer appear in either source or timeout happen. After fetching data using given peer, caller is required to call returned DoneFunc using appropriate result value

func (*Manager) Start

func (m *Manager) Start(startCtx context.Context) error

func (*Manager) Stop

func (m *Manager) Stop(ctx context.Context) error

func (*Manager) UpdateFullNodePool

func (m *Manager) UpdateFullNodePool(peerID peer.ID, isAdded bool)

UpdateFullNodePool is called by discovery when new full node is discovered or removed

func (*Manager) Validate

func (m *Manager) Validate(_ context.Context, peerID peer.ID, msg shrexsub.Notification) pubsub.ValidationResult

Validate will collect peer.ID into corresponding peer pool

func (*Manager) WithMetrics

func (m *Manager) WithMetrics() error

WithMetrics turns on metric collection in peer manager.

type Option

type Option func(*Manager) error

func WithShrexSubPools

func WithShrexSubPools(shrexSub *shrexsub.PubSub, headerSub libhead.Subscriber[*header.ExtendedHeader]) Option

WithShrexSubPools passes a shrexsub and headersub instance to be used to populate and validate pools from shrexsub notifications.

type Parameters

type Parameters struct {
	// PoolValidationTimeout is the timeout used for validating incoming datahashes. Pools that have
	// been created for datahashes from shrexsub that do not see this hash from headersub after this
	// timeout will be garbage collected.
	PoolValidationTimeout time.Duration

	// PeerCooldown is the time a peer is put on cooldown after a ResultCooldownPeer.
	PeerCooldown time.Duration

	// GcInterval is the interval at which the manager will garbage collect unvalidated pools.
	GcInterval time.Duration

	// EnableBlackListing turns on blacklisting for misbehaved peers
	EnableBlackListing bool
}

func DefaultParameters

func DefaultParameters() Parameters

DefaultParameters returns the default configuration values for the peer manager parameters

func (*Parameters) Validate

func (p *Parameters) Validate() error

Validate validates the values in Parameters