p2p

README

P2P protocol description

The Messenger interface with its implementation are used to define the way to communicate between Elrond nodes.

There are 2 ways to send data to the other peers:

1. Broadcasting messages on a pubsub using topics;
2. Direct sending messages to the connected peers.

The first type is used to send messages that has to reach every node (from corresponding shard, metachain, consensus group, etc.) and the second type is used to resolve requests comming from directly connected peers.

Documentation

Index

• Variables
• type BlacklistHandler
• type ChannelLoadBalancer
• type Config
• type ConnectionMonitor
• type ContextProvider
• type DirectSender
• type FloodPreventer
• type MessageP2P
• type MessageProcessor
• type Messenger
• type Option
• type PeerDiscoverer
• type PeerDiscoveryFactory
• type PeerID
  • func (pid PeerID) Bytes() []byte
  • func (pid PeerID) Pretty() string
• type Reconnecter
• type SendableData

Variables

var ErrAlreadySeenMessage = errors.New("already seen this message")

ErrAlreadySeenMessage signals that the message has already been seen

var ErrChannelAlreadyExists = errors.New("channel already exists")

ErrChannelAlreadyExists signals that the channel is already defined (and used)

var ErrChannelCanNotBeDeleted = errors.New("channel can not be deleted")

ErrChannelCanNotBeDeleted signals that a channel can not be deleted (might be the default channel)

var ErrChannelDoesNotExist = errors.New("channel does not exist")

ErrChannelDoesNotExist signals that a requested channel does not exist

var ErrEmptyTopicList = errors.New("empty topicIDs")

ErrEmptyTopicList signals that a message with empty topic ids has been received

var ErrInvalidDurationProvided = errors.New("invalid time.Duration provided")

ErrInvalidDurationProvided signals that an invalid time.Duration has been provided

var ErrInvalidPort = errors.New("invalid port provided")

ErrInvalidPort signals that an invalid port was provided

var ErrInvalidValue = errors.New("invalid value")

ErrInvalidValue signals that an invalid value has been provided

var ErrMessageTooLarge = errors.New("buffer too large")

ErrMessageTooLarge signals that the message provided is too large

var ErrNegativeOrZeroPeersRefreshInterval = errors.New("negative or zero peers refresh interval")

ErrNegativeOrZeroPeersRefreshInterval signals that a negative or zero peers refresh interval has been provided

var ErrNilChannelLoadBalancer = errors.New("nil channel load balancer object")

ErrNilChannelLoadBalancer signals that a nil data throttler object has been provided

var ErrNilConfigVariable = errors.New("nil config variable")

ErrNilConfigVariable signals that a nil config variable has been provided

var ErrNilContext = errors.New("nil context")

ErrNilContext signals that a nil context was provided

var ErrNilContextProvider = errors.New("nil context provider")

ErrNilContextProvider signals that a nil context applier has been provided

var ErrNilDirectSendMessageHandler = errors.New("nil direct sender message handler")

ErrNilDirectSendMessageHandler signals that the message handler for new message has not been wired

var ErrNilFetchPeersOnTopicHandler = errors.New("nil fetch peers on topic handler")

ErrNilFetchPeersOnTopicHandler signals that a nil handler was provided

var ErrNilFloodPreventer = errors.New("nil flood preventer")

ErrNilFloodPreventer signals that a nil flood preventer has been provided

var ErrNilHost = errors.New("nil host")

ErrNilHost signals that a nil host has been provided

var ErrNilMessage = errors.New("nil message")

ErrNilMessage signals that a nil message has been received

var ErrNilMockNet = errors.New("nil mocknet provided")

ErrNilMockNet signals that a nil mocknet was provided. Should occur only in testing!!!

var ErrNilP2PprivateKey = errors.New("nil P2P private key")

ErrNilP2PprivateKey signals that a nil P2P private key has been provided

var ErrNilPeerBlacklistHandler = errors.New("nil peer black list handler")

ErrNilPeerBlacklistHandler signals that a nil peer black list handler was provided

var ErrNilPeerDiscoverer = errors.New("nil peer discoverer")

ErrNilPeerDiscoverer signals that a nil peer dicoverer has been provided

var ErrNilTopic = errors.New("nil topic")

ErrNilTopic signals that a nil topic has been provided

var ErrNilValidator = errors.New("no validator has been set for this topic")

ErrNilValidator signals that a validator hasn't been set for the required topic

var ErrPeerBlacklisted = errors.New("peer is blacklisted")

ErrPeerBlacklisted signals that a peer is blacklisted

var ErrPeerDiscoveryProcessAlreadyStarted = errors.New("peer discovery is already turned on")

ErrPeerDiscoveryProcessAlreadyStarted signals that a peer discovery is already turned on

var ErrPeerNotDirectlyConnected = errors.New("peer is not directly connected")

ErrPeerNotDirectlyConnected signals that the peer is not directly connected to self

var ErrSystemBusy = errors.New("system busy")

ErrSystemBusy signals that the system is busy

var ErrTooManyGoroutines = errors.New(" number of goroutines exceeded")

ErrTooManyGoroutines is raised when the number of goroutines has exceeded a threshold

var ErrTopicAlreadyExists = errors.New("topic already exists")

ErrTopicAlreadyExists signals that a topic already exists

var ErrTopicValidatorOperationNotSupported = errors.New("topic validator operation is not supported")

ErrTopicValidatorOperationNotSupported signals that an unsupported validator operation occurred

var ErrWrongContextApplier = errors.New("wrong type of ContextApplier")

ErrWrongContextApplier signals that a wrong type of context applier has been provided

Types

type BlacklistHandler

type BlacklistHandler interface {
	Has(key string) bool
	IsInterfaceNil() bool
}

BlacklistHandler defines the behavior of a component that is able to decide if a key (peer ID) is black listed or not

type ChannelLoadBalancer

type ChannelLoadBalancer interface {
	AddChannel(channel string) error
	RemoveChannel(channel string) error
	GetChannelOrDefault(channel string) chan *SendableData
	CollectOneElementFromChannels() *SendableData
	IsInterfaceNil() bool
}

ChannelLoadBalancer defines what a load balancer that uses chans should do

type Config

type Config struct {
	BlacklistHandler BlacklistHandler
}

Config is a DTO used for config passing variables

type ConnectionMonitor

type ConnectionMonitor interface {
	HandleConnectedPeer(pid PeerID) error
	HandleDisconnectedPeer(pid PeerID) error
	DoReconnectionBlocking()
	CheckConnectionsBlocking()
	IsInterfaceNil() bool
}

ConnectionMonitor defines what a peer-management component should do

type ContextProvider

type ContextProvider interface {
	Context() context.Context
	IsInterfaceNil() bool
}

ContextProvider defines an interface for providing context to various messenger components

type DirectSender

type DirectSender interface {
	NextSeqno(counter *uint64) []byte
	Send(topic string, buff []byte, peer PeerID) error
	IsInterfaceNil() bool
}

DirectSender defines a component that can send direct messages to connected peers

type FloodPreventer

type FloodPreventer interface {
	AccumulateGlobal(identifier string, size uint64) bool
	Accumulate(identifier string, size uint64) bool
	Reset()
	IsInterfaceNil() bool
}

FloodPreventer defines the behavior of a component that is able to signal that too many events occurred on a provided identifier between Reset calls

type MessageP2P

type MessageP2P interface {
	From() []byte
	Data() []byte
	SeqNo() []byte
	TopicIDs() []string
	Signature() []byte
	Key() []byte
	Peer() PeerID
	IsInterfaceNil() bool
}

MessageP2P defines what a p2p message can do (should return)

type MessageProcessor

type MessageProcessor interface {
	ProcessReceivedMessage(message MessageP2P, fromConnectedPeer PeerID) error
	IsInterfaceNil() bool
}

MessageProcessor is the interface used to describe what a receive message processor should do All implementations that will be called from Messenger implementation will need to satisfy this interface If the function returns a non nil value, the received message will not be propagated to its connected peers

type Messenger

type Messenger interface {
	io.Closer

	ApplyOptions(opts ...Option) error

	// ID is the Messenger's unique peer identifier across the network (a
	// string). It is derived from the public key of the P2P credentials.
	ID() PeerID

	// Peers is the list of IDs of peers known to the Messenger.
	Peers() []PeerID

	// Addresses is the list of addresses that the Messenger is currently bound
	// to and listening to.
	Addresses() []string

	// ConnectToPeer explicitly connect to a specific peer with a known address (note that the
	// address contains the peer ID). This function is usually not called
	// manually, because any underlying implementation of the Messenger interface
	// should be keeping connections to peers open.
	ConnectToPeer(address string) error

	// IsConnected returns true if the Messenger are connected to a specific peer.
	IsConnected(peerID PeerID) bool

	// ConnectedPeers returns the list of IDs of the peers the Messenger is
	// currently connected to.
	ConnectedPeers() []PeerID

	// ConnectedAddresses returns the list of addresses of the peers to which the
	// Messenger is currently connected.
	ConnectedAddresses() []string

	// PeerAddress builds an address for the given peer ID, e.g.
	// ConnectToPeer(PeerAddress(somePeerID)).
	PeerAddress(pid PeerID) string

	// ConnectedPeersOnTopic returns the IDs of the peers to which the Messenger
	// is currently connected, but filtered by a topic they are registered to.
	ConnectedPeersOnTopic(topic string) []PeerID

	// TrimConnections tries to optimize the number of open connections, closing
	// those that are considered expendable.
	TrimConnections()

	// Bootstrap runs the initialization phase which includes peer discovery,
	// setting up initial connections and self-announcement in the network.
	Bootstrap() error

	// CreateTopic defines a new topic for sending messages, and optionally
	// creates a channel in the LoadBalancer for this topic (otherwise, the topic
	// will use a default channel).
	CreateTopic(name string, createChannelForTopic bool) error

	// HasTopic returns true if the Messenger has declared interest in a topic
	// and it is listening to messages referencing it.
	HasTopic(name string) bool

	// HasTopicValidator returns true if the Messenger has registered a custom
	// validator for a given topic name.
	HasTopicValidator(name string) bool

	// RegisterMessageProcessor adds the provided MessageProcessor to the list
	// of handlers that are invoked whenever a message is received on the
	// specified topic.
	RegisterMessageProcessor(topic string, handler MessageProcessor) error

	// UnregisterMessageProcessor removes the MessageProcessor set by the
	// Messenger from the list of registered handlers for the messages on the
	// given topic.
	UnregisterMessageProcessor(topic string) error

	// OutgoingChannelLoadBalancer returns the ChannelLoadBalancer instance
	// through which the Messenger is sending messages to the network.
	OutgoingChannelLoadBalancer() ChannelLoadBalancer

	// BroadcastOnChannelBlocking asynchronously waits until it can send a
	// message on the channel, but once it is able to, it synchronously sends the
	// message, blocking until sending is completed.
	BroadcastOnChannelBlocking(channel string, topic string, buff []byte) error

	// BroadcastOnChannel asynchronously sends a message on a given topic
	// through a specified channel.
	BroadcastOnChannel(channel string, topic string, buff []byte)

	// Broadcast is a convenience function that calls BroadcastOnChannelBlocking,
	// but implicitly sets the channel to be identical to the specified topic.
	Broadcast(topic string, buff []byte)

	// SendToConnectedPeer asynchronously sends a message to a peer directly,
	// bypassing pubsub and topics. It opens a new connection with the given
	// peer, but reuses a connection and a stream if possible.
	SendToConnectedPeer(topic string, buff []byte, peerID PeerID) error

	IsConnectedToTheNetwork() bool
	ThresholdMinConnectedPeers() int
	SetThresholdMinConnectedPeers(minConnectedPeers int) error

	// IsInterfaceNil returns true if there is no value under the interface
	IsInterfaceNil() bool
}

Messenger is the main struct used for communication with other peers

type Option

type Option func(*Config) error

Option represents a functional configuration parameter that can operate

over the networkMessenger struct.

type PeerDiscoverer

type PeerDiscoverer interface {
	Bootstrap() error
	Name() string

	ApplyContext(ctxProvider ContextProvider) error
	IsInterfaceNil() bool
}

PeerDiscoverer defines the behaviour of a peer discovery mechanism

type PeerDiscoveryFactory

type PeerDiscoveryFactory interface {
	CreatePeerDiscoverer() (PeerDiscoverer, error)
	IsInterfaceNil() bool
}

PeerDiscoveryFactory defines the factory for peer discoverer implementation

type PeerID

type PeerID string

PeerID is a p2p peer identity.

func (PeerID) Bytes

func (pid PeerID) Bytes() []byte

Bytes returns the peer ID as byte slice

func (PeerID) Pretty

func (pid PeerID) Pretty() string

Pretty returns a b58-encoded string of the peer id

type Reconnecter

type Reconnecter interface {
	ReconnectToNetwork()
	Pause()  // pause the peer discovery
	Resume() // resume the peer discovery
	IsInterfaceNil() bool
}

Reconnecter defines the behaviour of a network reconnection mechanism

type SendableData

type SendableData struct {
	Buff  []byte
	Topic string
}

SendableData represents the struct used in data throttler implementation