p2p

package
v0.31.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 7, 2023 License: AGPL-3.0 Imports: 34 Imported by: 10

Documentation

Index

Constants

View Source 
const (
	// DefaultReceiveCacheSize represents size of receive cache that keeps hash of incoming messages
	// for sake of deduplication.
	DefaultReceiveCacheSize = 10e4
)

Variables

View Source 
var (
	// ErrInvalidId indicates that the given ID (either `peer.ID` or `flow.Identifier`) has an invalid format.
	ErrInvalidId = errors.New("empty peer ID")

	// ErrUnknownId indicates that the given ID (either `peer.ID` or `flow.Identifier`) is unknown.
	ErrUnknownId = errors.New("unknown ID")
)
View Source 
var ErrNetworkShutdown = errors.New("network has already shutdown")
View Source 
var NotEjectedFilter = filter.Not(filter.Ejected)

NotEjectedFilter is an identity filter that, when applied to the identity table at a given snapshot, returns all nodes that we should communicate with over the networking layer.

NOTE: The protocol state includes nodes from the previous/next epoch that should be included in network communication. We omit any nodes that have been ejected.

Functions

func IsInvalidSubscriptionError added in v0.31.0 

func IsInvalidSubscriptionError(this error) bool

func NewInvalidSubscriptionError added in v0.31.0 

func NewInvalidSubscriptionError(topic string) error

Types

type BasePubSubAdapterConfig added in v0.29.0 

type BasePubSubAdapterConfig struct {
	// MaxMessageSize is the maximum size of a message that can be sent on the pubsub network.
	MaxMessageSize int
}

BasePubSubAdapterConfig is the base configuration for the underlying pubsub implementation. These configurations are common to all pubsub implementations and must be observed by all implementations.

type BasicRateLimiter added in v0.30.0 

type BasicRateLimiter interface {
	component.Component
	// Allow returns true if a message with the give size should be allowed to be processed.
	Allow(peerID peer.ID, msgSize int) bool
}

BasicRateLimiter rate limiter interface

type ConnectionGater added in v0.29.0 

type ConnectionGater interface {
	InterceptPeerDial(p peer.ID) (allow bool)

	InterceptAddrDial(peer.ID, multiaddr.Multiaddr) (allow bool)

	InterceptAccept(network.ConnMultiaddrs) (allow bool)

	InterceptSecured(network.Direction, peer.ID, network.ConnMultiaddrs) (allow bool)

	InterceptUpgraded(network.Conn) (allow bool, reason control.DisconnectReason)
}

ConnectionGater is a copy of the libp2p ConnectionGater interface: https://github.com/libp2p/go-libp2p/blob/master/core/connmgr/gater.go#L54 We use it here to generate a mock for testing through testify mock.

type Connector 

type Connector interface {
	// UpdatePeers connects to the given peer.IDs. It also disconnects from any other peers with which it may have
	// previously established connection.
	// UpdatePeers implementation should be idempotent such that multiple calls to connect to the same peer should not
	// create multiple connections
	UpdatePeers(ctx context.Context, peerIDs peer.IDSlice)
}

Connector connects to peer and disconnects from peer using the underlying networking library

type ConnectorHost added in v0.31.0 

type ConnectorHost interface {
	// Connections returns all the connections of the underlying host.
	Connections() []network.Conn

	// PeerInfo returns the peer.AddrInfo for the given peer.ID.
	// Args:
	// 	id: peer.ID for which the peer.AddrInfo is requested
	// Returns:
	// 	peer.AddrInfo for the given peer.ID
	PeerInfo(id peer.ID) peer.AddrInfo

	// IsProtected returns true if the given peer.ID is protected from pruning.
	// Args:
	// 	id: peer.ID for which the protection status is requested
	// Returns:
	// 	true if the given peer.ID is protected from pruning
	IsProtected(id peer.ID) bool

	// ClosePeer closes the connection to the given peer.ID.
	// Args:
	// 	id: peer.ID for which the connection is to be closed
	// Returns:
	// 	error if there is any error while closing the connection to the given peer.ID. All errors are benign.
	ClosePeer(id peer.ID) error

	// ID returns the peer.ID of the underlying host.
	// Returns:
	// 	peer.ID of the underlying host.
	ID() peer.ID
}

ConnectorHost is a wrapper around the libp2p host.Host interface to provide the required functionality for the Connector interface.

type ControlMessageType added in v0.30.0 

type ControlMessageType string

ControlMessageType is the type of control message, as defined in the libp2p pubsub spec. 

const (
	CtrlMsgIHave ControlMessageType = "IHAVE"
	CtrlMsgIWant ControlMessageType = "IWANT"
	CtrlMsgGraft ControlMessageType = "GRAFT"
	CtrlMsgPrune ControlMessageType = "PRUNE"
)

func ControlMessageTypes added in v0.30.0 

func ControlMessageTypes() []ControlMessageType

ControlMessageTypes returns list of all libp2p control message types.

func (ControlMessageType) String added in v0.31.0 

func (c ControlMessageType) String() string

type CreateNodeFunc added in v0.30.0 

type CreateNodeFunc func(zerolog.Logger, host.Host, ProtocolPeerCache, PeerManager) LibP2PNode

type DisallowListConsumer added in v0.30.0 

type DisallowListConsumer interface {
	// OnNodeDisallowListUpdate notifications whenever the node block list is updated.
	// Prerequisites:
	// Implementation must be concurrency safe; Non-blocking;
	// and must handle repetition of the same events (with some processing overhead).
	OnNodeDisallowListUpdate(list flow.IdentifierList)
}

DisallowListConsumer consumes notifications from the cache.NodeBlocklistWrapper whenever the block list is updated. Implementations must:

  • be concurrency safe
  • be non-blocking

type DisallowListNotificationConsumer added in v0.30.0 

type DisallowListNotificationConsumer interface {
	// OnDisallowListNotification is called when a new disallow list update notification is distributed.
	// Any error on consuming event must handle internally.
	// The implementation must be concurrency safe, but can be blocking.
	OnDisallowListNotification(*DisallowListUpdateNotification)
}

type DisallowListNotificationDistributor added in v0.30.0 

type DisallowListNotificationDistributor interface {
	component.Component
	// DistributeBlockListNotification distributes the event to all the consumers.
	// Any error returned by the distributor is non-recoverable and will cause the node to crash.
	// Implementation must be concurrency safe, and non-blocking.
	DistributeBlockListNotification(list flow.IdentifierList) error

	// AddConsumer adds a consumer to the distributor. The consumer will be called the distributor distributes a new event.
	// AddConsumer must be concurrency safe. Once a consumer is added, it must be called for all future events.
	// There is no guarantee that the consumer will be called for events that were already received by the distributor.
	AddConsumer(DisallowListNotificationConsumer)
}

type DisallowListUpdateNotification added in v0.30.0 

type DisallowListUpdateNotification struct {
	DisallowList flow.IdentifierList
}

DisallowListUpdateNotification is the event that is submitted to the distributor when the disallow list is updated.

type GossipSubAdapterConfigFunc added in v0.30.0 

type GossipSubAdapterConfigFunc func(*BasePubSubAdapterConfig) PubSubAdapterConfig

type GossipSubBuilder added in v0.30.0 

type GossipSubBuilder interface {
	PeerScoringBuilder
	// SetHost sets the host of the builder.
	// If the host has already been set, a fatal error is logged.
	SetHost(host.Host)

	// SetSubscriptionFilter sets the subscription filter of the builder.
	// If the subscription filter has already been set, a fatal error is logged.
	SetSubscriptionFilter(pubsub.SubscriptionFilter)

	// SetGossipSubFactory sets the gossipsub factory of the builder.
	// We expect the node to initialize with a default gossipsub factory. Hence, this function overrides the default config.
	SetGossipSubFactory(GossipSubFactoryFunc)

	// SetGossipSubConfigFunc sets the gossipsub config function of the builder.
	// We expect the node to initialize with a default gossipsub config. Hence, this function overrides the default config.
	SetGossipSubConfigFunc(GossipSubAdapterConfigFunc)

	// SetGossipSubPeerScoring sets the gossipsub peer scoring of the builder.
	// If the gossipsub peer scoring flag has already been set, a fatal error is logged.
	SetGossipSubPeerScoring(bool)

	// SetGossipSubScoreTracerInterval sets the gossipsub score tracer interval of the builder.
	// If the gossipsub score tracer interval has already been set, a fatal error is logged.
	SetGossipSubScoreTracerInterval(time.Duration)

	// SetGossipSubTracer sets the gossipsub tracer of the builder.
	// If the gossipsub tracer has already been set, a fatal error is logged.
	SetGossipSubTracer(PubSubTracer)

	// SetIDProvider sets the identity provider of the builder.
	// If the identity provider has already been set, a fatal error is logged.
	SetIDProvider(module.IdentityProvider)

	// SetRoutingSystem sets the routing system of the builder.
	// If the routing system has already been set, a fatal error is logged.
	SetRoutingSystem(routing.Routing)

	// SetGossipSubRPCInspectorSuite sets the gossipsub rpc inspector suite of the builder. It contains the
	// inspector function that is injected into the gossipsub rpc layer, as well as the notification distributors that
	// are used to notify the app specific scoring mechanism of misbehaving peers.
	SetGossipSubRPCInspectorSuite(GossipSubInspectorSuite)

	// Build creates a new GossipSub pubsub system.
	// It returns the newly created GossipSub pubsub system and any errors encountered during its creation.
	//
	// Arguments:
	// - context.Context: the irrecoverable context of the node.
	//
	// Returns:
	// - PubSubAdapter: a GossipSub pubsub system for the libp2p node.
	// - PeerScoreTracer: a peer score tracer for the GossipSub pubsub system (if enabled, otherwise nil).
	// - error: if an error occurs during the creation of the GossipSub pubsub system, it is returned. Otherwise, nil is returned.
	// Note that on happy path, the returned error is nil. Any error returned is unexpected and should be handled as irrecoverable.
	Build(irrecoverable.SignalerContext) (PubSubAdapter, PeerScoreTracer, error)
}

GossipSubBuilder provides a builder pattern for creating a GossipSub pubsub system.

type GossipSubControlMetricsObserver added in v0.30.0 

type GossipSubControlMetricsObserver interface {
	ObserveRPC(peer.ID, *pubsub.RPC)
}

GossipSubControlMetricsObserver funcs used to observe gossipsub related metrics.

type GossipSubFactoryFunc added in v0.30.0 

type GossipSubFactoryFunc func(context.Context, zerolog.Logger, host.Host, PubSubAdapterConfig) (PubSubAdapter, error)

type GossipSubInspectorNotifDistributor added in v0.31.0 

type GossipSubInspectorNotifDistributor interface {
	component.Component
	// Distribute distributes the event to all the consumers.
	// Any error returned by the distributor is non-recoverable and will cause the node to crash.
	// Implementation must be concurrency safe, and non-blocking.
	Distribute(notification *InvCtrlMsgNotif) error

	// AddConsumer adds a consumer to the distributor. The consumer will be called the distributor distributes a new event.
	// AddConsumer must be concurrency safe. Once a consumer is added, it must be called for all future events.
	// There is no guarantee that the consumer will be called for events that were already received by the distributor.
	AddConsumer(GossipSubInvCtrlMsgNotifConsumer)
}

GossipSubInspectorNotifDistributor is the interface for the distributor that distributes gossip sub inspector notifications. It is used to distribute notifications to the consumers in an asynchronous manner and non-blocking manner. The implementation should guarantee that all registered consumers are called upon distribution of a new event.

type GossipSubInspectorSuite added in v0.31.0 

type GossipSubInspectorSuite interface {
	component.Component
	// InspectFunc returns the inspect function that is used to inspect the gossipsub rpc messages.
	// This function follows a dependency injection pattern, where the inspect function is injected into the gossipsu, and
	// is called whenever a gossipsub rpc message is received.
	InspectFunc() func(peer.ID, *pubsub.RPC) error

	// AddInvCtrlMsgNotifConsumer adds a consumer to the invalid control message notification distributor.
	// This consumer is notified when a misbehaving peer regarding gossipsub control messages is detected. This follows a pub/sub
	// pattern where the consumer is notified when a new notification is published.
	// A consumer is only notified once for each notification, and only receives notifications that were published after it was added.
	AddInvCtrlMsgNotifConsumer(GossipSubInvCtrlMsgNotifConsumer)
	// Inspectors returns all inspectors in the inspector suite.
	Inspectors() []GossipSubRPCInspector
}

GossipSubInspectorSuite is the interface for the GossipSub inspector suite. It encapsulates the rpc inspectors and the notification distributors.

type GossipSubInvCtrlMsgNotifConsumer added in v0.31.0 

type GossipSubInvCtrlMsgNotifConsumer interface {
	// OnInvalidControlMessageNotification is called when a new invalid control message notification is distributed.
	// Any error on consuming event must handle internally.
	// The implementation must be concurrency safe, but can be blocking.
	OnInvalidControlMessageNotification(*InvCtrlMsgNotif)
}

GossipSubInvCtrlMsgNotifConsumer is the interface for the consumer that consumes gossip sub inspector notifications. It is used to consume notifications in an asynchronous manner. The implementation must be concurrency safe, but can be blocking. This is due to the fact that the consumer is called asynchronously by the distributor.

type GossipSubMsgValidationRpcInspector added in v0.31.0 

type GossipSubMsgValidationRpcInspector interface {
	collection.ClusterEvents
	GossipSubRPCInspector
}

GossipSubMsgValidationRpcInspector abstracts the general behavior of an app specific RPC inspector specifically used to inspect and validate incoming. It is used to implement custom message validation logic. It is injected into the GossipSubRouter and run on every incoming RPC message before the message is processed by libp2p. If the message is invalid the RPC message will be dropped. Implementations must:

  • be concurrency safe
  • be non-blocking

type GossipSubRPCInspector added in v0.30.0 

type GossipSubRPCInspector interface {
	component.Component

	// Name returns the name of the rpc inspector.
	Name() string

	// Inspect inspects an incoming RPC message. This callback func is invoked
	// on ever RPC message received before the message is processed by libp2p.
	// If this func returns any error the RPC message will be dropped.
	Inspect(peer.ID, *pubsub.RPC) error
}

GossipSubRPCInspector app specific RPC inspector used to inspect and validate incoming RPC messages before they are processed by libp2p. Implementations must:

  • be concurrency safe
  • be non-blocking

type GossipSubSpamRecord added in v0.31.0 

type GossipSubSpamRecord struct {
	// Decay factor of gossipsub spam penalty.
	// The Penalty is multiplied by the Decay factor every time the Penalty is updated.
	// This is to prevent the Penalty from being stuck at a negative value.
	// Each peer has its own Decay factor based on its behavior.
	// Valid decay value is in the range [0, 1].
	Decay float64
	// Penalty is the application specific Penalty of the peer.
	Penalty float64
}

GossipSubSpamRecord represents spam record of a peer in the GossipSub protocol. It acts as a penalty card for a peer in the GossipSub protocol that keeps the spam penalty of the peer as well as its decay factor. GossipSubSpam record is used to calculate the application specific score of a peer in the GossipSub protocol.

type GossipSubSpamRecordCache added in v0.31.0 

type GossipSubSpamRecordCache interface {
	// Add adds the GossipSubSpamRecord of a peer to the cache.
	// Args:
	// - peerID: the peer ID of the peer in the GossipSub protocol.
	// - record: the GossipSubSpamRecord of the peer.
	//
	// Returns:
	// - bool: true if the record was added successfully, false otherwise.
	Add(peerId peer.ID, record GossipSubSpamRecord) bool

	// Get returns the GossipSubSpamRecord of a peer from the cache.
	// Args:
	// - peerID: the peer ID of the peer in the GossipSub protocol.
	// Returns:
	// - *GossipSubSpamRecord: the GossipSubSpamRecord of the peer.
	// - error on failure to retrieve the record. The returned error is irrecoverable and indicates an exception.
	// - bool: true if the record was retrieved successfully, false otherwise.
	Get(peerID peer.ID) (*GossipSubSpamRecord, error, bool)

	// Update updates the GossipSub spam penalty of a peer in the cache using the given adjust function.
	// Args:
	// - peerID: the peer ID of the peer in the GossipSub protocol.
	// - adjustFn: the adjust function to be applied to the record.
	// Returns:
	// - *GossipSubSpamRecord: the updated record.
	// - error on failure to update the record. The returned error is irrecoverable and indicates an exception.
	Update(peerID peer.ID, updateFunc UpdateFunction) (*GossipSubSpamRecord, error)

	// Has returns true if the cache contains the GossipSubSpamRecord of the given peer.
	// Args:
	// - peerID: the peer ID of the peer in the GossipSub protocol.
	// Returns:
	// - bool: true if the cache contains the GossipSubSpamRecord of the given peer, false otherwise.
	Has(peerID peer.ID) bool
}

GossipSubSpamRecordCache is a cache for storing the GossipSub spam records of peers. The spam records of peers is used to calculate the application specific score, which is part of the GossipSub score of a peer. Note that none of the spam records, application specific score, and GossipSub score are shared publicly with other peers. Rather they are solely used by the current peer to select the peers to which it will connect on a topic mesh.

Implementation must be thread-safe.

type IDTranslator added in v0.21.1 

type IDTranslator interface {
	// GetPeerID returns the peer ID for the given `flow.Identifier`.
	// During normal operations, the following error returns are expected
	//  * ErrUnknownId if the given Identifier is unknown
	//  * ErrInvalidId if the given Identifier has an invalid format.
	//    This error return is only possible, when the Identifier is generated from some
	//    other input (e.g. the node's public key). While the Flow protocol itself makes
	//    no assumptions about the structure of the `Identifier`, protocol extensions
	//    (e.g. for Observers) might impose a strict relationship between both flow
	//    Identifier and peer ID, in which case they can use this error.
	// TODO: implementations do not fully adhere to this convention on error returns
	GetPeerID(flow.Identifier) (peer.ID, error)

	// GetFlowID returns the `flow.Identifier` for the given `peer.ID`.
	// During normal operations, the following error returns are expected
	//  * ErrUnknownId if the given Identifier is unknown
	//  * ErrInvalidId if the given Identifier has an invalid format.
	//    This error return is only possible, when the Identifier is generated from some
	//    other input (e.g. the node's public key). While the Flow protocol itself makes
	//    no assumptions about the structure of the `Identifier`, protocol extensions
	//    (e.g. for Observers) might impose a strict relationship between both flow
	//    Identifier and peer ID, in which case they can use this error.
	// TODO: implementations do not fully adhere to this convention on error returns
	GetFlowID(peer.ID) (flow.Identifier, error)
}

IDTranslator provides an interface for converting from Flow ID's to LibP2P peer ID's and vice versa.

type InvCtrlMsgNotif added in v0.31.0 

type InvCtrlMsgNotif struct {
	// PeerID is the ID of the peer that sent the invalid control message.
	PeerID peer.ID
	// MsgType is the type of control message that was received.
	MsgType ControlMessageType
	// Count is the number of invalid control messages received from the peer that is reported in this notification.
	Count uint64
	// Err any error associated with the invalid control message.
	Err error
}

InvCtrlMsgNotif is the notification sent to the consumer when an invalid control message is received. It models the information that is available to the consumer about a misbehaving peer.

func NewInvalidControlMessageNotification added in v0.30.0 

func NewInvalidControlMessageNotification(peerID peer.ID, msgType ControlMessageType, count uint64, err error) *InvCtrlMsgNotif

NewInvalidControlMessageNotification returns a new *InvCtrlMsgNotif

type InvalidSubscriptionError added in v0.31.0 

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

InvalidSubscriptionError indicates that a peer has subscribed to a topic that is not allowed for its role. This error is benign, i.e., it does not indicate an illegal state in the execution of the code. We expect this error when there are malicious peers in the network. But such errors should not lead to a crash of the node.32

func (InvalidSubscriptionError) Error added in v0.31.0 

func (e InvalidSubscriptionError) Error() string

type LibP2PNode added in v0.29.0 

type LibP2PNode interface {
	module.ReadyDoneAware
	Subscriptions
	// PeerConnections connection status information per peer.
	PeerConnections
	// PeerScore exposes the peer score API.
	PeerScore
	// Start the libp2p node.
	Start(ctx irrecoverable.SignalerContext)
	// Stop terminates the libp2p node.
	Stop() error
	// AddPeer adds a peer to this node by adding it to this node's peerstore and connecting to it.
	AddPeer(ctx context.Context, peerInfo peer.AddrInfo) error
	// RemovePeer closes the connection with the peer.
	RemovePeer(peerID peer.ID) error
	// GetPeersForProtocol returns slice peer IDs for the specified protocol ID.
	GetPeersForProtocol(pid protocol.ID) peer.IDSlice
	// CreateStream returns an existing stream connected to the peer if it exists, or creates a new stream with it.
	CreateStream(ctx context.Context, peerID peer.ID) (libp2pnet.Stream, error)
	// GetIPPort returns the IP and Port the libp2p node is listening on.
	GetIPPort() (string, string, error)
	// RoutingTable returns the node routing table
	RoutingTable() *kbucket.RoutingTable
	// ListPeers returns list of peer IDs for peers subscribed to the topic.
	ListPeers(topic string) []peer.ID
	// Subscribe subscribes the node to the given topic and returns the subscription
	Subscribe(topic channels.Topic, topicValidator TopicValidatorFunc) (Subscription, error)
	// UnSubscribe cancels the subscriber and closes the topic.
	UnSubscribe(topic channels.Topic) error
	// Publish publishes the given payload on the topic.
	Publish(ctx context.Context, topic channels.Topic, data []byte) error
	// Host returns pointer to host object of node.
	Host() host.Host
	// WithDefaultUnicastProtocol overrides the default handler of the unicast manager and registers all preferred protocols.
	WithDefaultUnicastProtocol(defaultHandler libp2pnet.StreamHandler, preferred []protocols.ProtocolName) error
	// WithPeersProvider sets the PeersProvider for the peer manager.
	// If a peer manager factory is set, this method will set the peer manager's PeersProvider.
	WithPeersProvider(peersProvider PeersProvider)
	// PeerManagerComponent returns the component interface of the peer manager.
	PeerManagerComponent() component.Component
	// RequestPeerUpdate requests an update to the peer connections of this node using the peer manager.
	RequestPeerUpdate()
	// SetRouting sets the node's routing implementation.
	// SetRouting may be called at most once.
	SetRouting(r routing.Routing)
	// Routing returns node routing object.
	Routing() routing.Routing
	// SetPubSub sets the node's pubsub implementation.
	// SetPubSub may be called at most once.
	SetPubSub(ps PubSubAdapter)
	// SetComponentManager sets the component manager for the node.
	// SetComponentManager may be called at most once.
	SetComponentManager(cm *component.ComponentManager)
}

LibP2PNode represents a flow libp2p node. It provides the network layer with the necessary interface to control the underlying libp2p node. It is essentially the flow wrapper around the libp2p node, and allows us to define different types of libp2p nodes that can operate in different ways by overriding these methods. TODO: this interface is highly coupled with the current implementation of the libp2p node. We should 

consider refactoring it to be more generic and less coupled with the current implementation.
https://github.com/dapperlabs/flow-go/issues/6575

type Network 

type Network struct {
	sync.RWMutex
	*component.ComponentManager
	// contains filtered or unexported fields
}

Network represents the overlay network of our peer-to-peer network, including the protocols for handshakes, authentication, gossiping and heartbeats.

func NewNetwork 

func NewNetwork(param *NetworkConfig, opts ...NetworkOption) (*Network, error)

NewNetwork creates a new naive overlay network, using the given middleware to communicate to direct peers, using the given codec for serialization, and using the given state & cache interfaces to track volatile information. csize determines the size of the cache dedicated to keep track of received messages

func (*Network) Identities added in v0.21.1 

func (n *Network) Identities() flow.IdentityList

func (*Network) Identity 

func (n *Network) Identity(pid peer.ID) (*flow.Identity, bool)

func (*Network) MulticastOnChannel added in v0.25.0 

func (n *Network) MulticastOnChannel(channel channels.Channel, message interface{}, num uint, targetIDs ...flow.Identifier) error

MulticastOnChannel unreliably sends the specified event over the channel to randomly selected 'num' number of recipients selected from the specified targetIDs.

func (*Network) PublishOnChannel added in v0.25.0 

func (n *Network) PublishOnChannel(channel channels.Channel, message interface{}, targetIDs ...flow.Identifier) error

PublishOnChannel sends the message in an unreliable way to the given recipients. In this context, unreliable means that the message is published over a libp2p pub-sub channel and can be read by any node subscribed to that channel. The selector could be used to optimize or restrict delivery.

func (*Network) Receive 

func (n *Network) Receive(msg *network.IncomingMessageScope) error

func (*Network) Register 

func (n *Network) Register(channel channels.Channel, messageProcessor network.MessageProcessor) (network.Conduit, error)

Register will register the given engine with the given unique engine engineID, returning a conduit to directly submit messages to the message bus of the engine.

func (*Network) RegisterBlobService added in v0.23.9 

func (n *Network) RegisterBlobService(channel channels.Channel, ds datastore.Batching, opts ...network.BlobServiceOption) (network.BlobService, error)

RegisterBlobService registers a BlobService on the given channel. The returned BlobService can be used to request blobs from the network.

func (*Network) RegisterPingService added in v0.23.9 

func (n *Network) RegisterPingService(pingProtocol protocol.ID, provider network.PingInfoProvider) (network.PingService, error)

func (*Network) ReportMisbehaviorOnChannel added in v0.31.0 

func (n *Network) ReportMisbehaviorOnChannel(channel channels.Channel, report network.MisbehaviorReport)

ReportMisbehaviorOnChannel reports the misbehavior of a node on sending a message to the current node that appears valid based on the networking layer but is considered invalid by the current node based on the Flow protocol. The misbehavior report is sent to the current node's networking layer on the given channel to be processed. Args: - channel: The channel on which the misbehavior report is sent. - report: The misbehavior report to be sent. Returns: none

func (*Network) Topology 

func (n *Network) Topology() flow.IdentityList

func (*Network) UnRegisterChannel added in v0.25.0 

func (n *Network) UnRegisterChannel(channel channels.Channel) error

UnRegisterChannel unregisters the engine for the specified channel. The engine will no longer be able to send or receive messages from that channel.

func (*Network) UnicastOnChannel added in v0.25.0 

func (n *Network) UnicastOnChannel(channel channels.Channel, payload interface{}, targetID flow.Identifier) error

UnicastOnChannel sends the message in a reliable way to the given recipient. It uses 1-1 direct messaging over the underlying network to deliver the message. It returns an error if unicasting fails.

type NetworkConfig added in v0.31.0 

type NetworkConfig struct {
	Logger              zerolog.Logger
	Codec               network.Codec
	Me                  module.Local
	MiddlewareFactory   func() (network.Middleware, error)
	Topology            network.Topology
	SubscriptionManager network.SubscriptionManager
	Metrics             module.NetworkCoreMetrics
	IdentityProvider    module.IdentityProvider
	ReceiveCache        *netcache.ReceiveCache
	ConduitFactory      network.ConduitFactory
	AlspCfg             *alspmgr.MisbehaviorReportManagerConfig
}

NetworkConfig is a configuration struct for the network. It contains all the necessary components to create a new network.

type NetworkConfigOption added in v0.31.0 

type NetworkConfigOption func(*NetworkConfig)

NetworkConfigOption is a function that can be used to override network config parmeters.

func WithAlspConfig added in v0.31.0 

func WithAlspConfig(cfg *alspmgr.MisbehaviorReportManagerConfig) NetworkConfigOption

WithAlspConfig overrides the default misbehavior report manager config. It is mostly used for testing purposes. Note: do not override the default misbehavior report manager config in production unless you know what you are doing. Args: cfg: misbehavior report manager config Returns: NetworkConfigOption: network param option

type NetworkOption added in v0.31.0 

type NetworkOption func(*Network)

NetworkOption is a function that can be used to override network attributes. It is mostly used for testing purposes. Note: do not override network attributes in production unless you know what you are doing.

func WithAlspManager added in v0.31.0 

func WithAlspManager(mgr network.MisbehaviorReportManager) NetworkOption

WithAlspManager sets the misbehavior report manager for the network. It overrides the default misbehavior report manager that is created from the config. Note that this option is mostly used for testing purposes, do not use it in production unless you know what you are doing.

Args: 

mgr: misbehavior report manager

Returns: 

NetworkOption: network option

type NodeBuilder added in v0.21.0 

type NodeBuilder interface {
	SetBasicResolver(madns.BasicResolver) NodeBuilder
	SetSubscriptionFilter(pubsub.SubscriptionFilter) NodeBuilder
	SetResourceManager(network.ResourceManager) NodeBuilder
	SetConnectionManager(connmgr.ConnManager) NodeBuilder
	SetConnectionGater(connmgr.ConnectionGater) NodeBuilder
	SetRoutingSystem(func(context.Context, host.Host) (routing.Routing, error)) NodeBuilder
	SetPeerManagerOptions(bool, time.Duration) NodeBuilder

	// EnableGossipSubPeerScoring enables peer scoring for the GossipSub pubsub system.
	// Arguments:
	// - module.IdentityProvider: the identity provider for the node (must be set before calling this method).
	// - *PeerScoringConfig: the peer scoring configuration for the GossipSub pubsub system. If nil, the default configuration is used.
	EnableGossipSubPeerScoring(module.IdentityProvider, *PeerScoringConfig) NodeBuilder
	SetCreateNode(CreateNodeFunc) NodeBuilder
	SetGossipSubFactory(GossipSubFactoryFunc, GossipSubAdapterConfigFunc) NodeBuilder
	SetStreamCreationRetryInterval(time.Duration) NodeBuilder
	SetRateLimiterDistributor(UnicastRateLimiterDistributor) NodeBuilder
	SetGossipSubTracer(PubSubTracer) NodeBuilder
	SetGossipSubScoreTracerInterval(time.Duration) NodeBuilder
	SetGossipSubRpcInspectorSuite(GossipSubInspectorSuite) NodeBuilder
	Build() (LibP2PNode, error)
}

NodeBuilder is a builder pattern for creating a libp2p Node instance.

type PeerConnections added in v0.30.0 

type PeerConnections interface {
	// IsConnected returns true if address is a direct peer of this node else false.
	// Peers are considered not connected if the underlying libp2p host reports the
	// peers as not connected and there are no connections in the connection list.
	// The following error returns indicate a bug in the code:
	//  * network.ErrIllegalConnectionState if the underlying libp2p host reports connectedness as NotConnected but the connections list
	// 	  to the peer is not empty. This indicates a bug within libp2p.
	IsConnected(peerID peer.ID) (bool, error)
}

PeerConnections subset of funcs related to underlying libp2p host connections.

type PeerFilter added in v0.23.9 

type PeerFilter func(peer.ID) error

func AllowAllPeerFilter added in v0.29.0 

func AllowAllPeerFilter() PeerFilter

AllowAllPeerFilter returns a peer filter that does not do any filtering.

type PeerManager 

type PeerManager interface {
	component.Component
	RateLimiterConsumer

	// RequestPeerUpdate requests an update to the peer connections of this node.
	// If a peer update has already been requested (either as a periodic request or an on-demand
	// request) and is outstanding, then this call is a no-op.
	RequestPeerUpdate()

	// ForceUpdatePeers initiates an update to the peer connections of this node immediately
	ForceUpdatePeers(context.Context)

	// SetPeersProvider sets the peer managers's peers provider and may be called at most once
	SetPeersProvider(PeersProvider)
}

PeerManager adds and removes connections to peers periodically and on request

type PeerManagerFactoryFunc added in v0.21.1 

type PeerManagerFactoryFunc func(host host.Host, peersProvider PeersProvider, logger zerolog.Logger) (PeerManager, error)

PeerManagerFactoryFunc is a factory function type for generating a PeerManager instance using the given host, peersProvider and logger

type PeerScore added in v0.30.0 

type PeerScore interface {
	// SetPeerScoreExposer sets the node's peer score exposer implementation.
	// SetPeerScoreExposer may be called at most once. It is an irrecoverable error to call this
	// method if the node's peer score exposer has already been set.
	SetPeerScoreExposer(e PeerScoreExposer)
	// PeerScoreExposer returns the node's peer score exposer implementation.
	// If the node's peer score exposer has not been set, the second return value will be false.
	PeerScoreExposer() (PeerScoreExposer, bool)
}

PeerScore is the interface for the peer score module. It is used to expose the peer score to other components of the node. It is also used to set the peer score exposer implementation.

type PeerScoreExposer added in v0.30.0 

type PeerScoreExposer interface {
	// GetScore returns the overall score for the given peer.
	GetScore(peerID peer.ID) (float64, bool)
	// GetAppScore returns the application score for the given peer.
	GetAppScore(peerID peer.ID) (float64, bool)
	// GetIPColocationFactor returns the IP colocation factor for the given peer.
	GetIPColocationFactor(peerID peer.ID) (float64, bool)
	// GetBehaviourPenalty returns the behaviour penalty for the given peer.
	GetBehaviourPenalty(peerID peer.ID) (float64, bool)
	// GetTopicScores returns the topic scores for the given peer for all topics.
	// The returned map is keyed by topic name.
	GetTopicScores(peerID peer.ID) (map[string]TopicScoreSnapshot, bool)
}

PeerScoreExposer is the interface for the tracer that is used to expose the peers score.

type PeerScoreSnapshot added in v0.30.0 

type PeerScoreSnapshot struct {
	// Score the overall score of the peer.
	Score float64
	// Topics map that stores the score of the peer per topic.
	Topics map[string]*TopicScoreSnapshot
	// AppSpecificScore application specific score (set by Flow protocol).
	AppSpecificScore float64

	// A positive value indicates that the peer is colocated with other nodes on the same network id,
	// and can be used to warn of sybil attacks.
	IPColocationFactor float64
	// A positive value indicates that GossipSub has caught the peer misbehaving, and can be used to warn of an attack.
	BehaviourPenalty float64
}

PeerScoreSnapshot is a snapshot of the overall peer score at a given time.

func (PeerScoreSnapshot) IsWarning added in v0.30.0 

func (p PeerScoreSnapshot) IsWarning() bool

IsWarning returns true if the peer score is in warning state. When the peer score is in warning state, the peer is considered to be misbehaving.

type PeerScoreTracer added in v0.30.0 

type PeerScoreTracer interface {
	component.Component
	PeerScoreExposer
	// UpdatePeerScoreSnapshots updates the peer score snapshot/
	UpdatePeerScoreSnapshots(map[peer.ID]*PeerScoreSnapshot)

	// UpdateInterval returns the update interval for the tracer. The tracer will be receiving updates
	// at this interval.
	UpdateInterval() time.Duration
}

PeerScoreTracer is the interface for the tracer that is used to trace the peer score.

type PeerScoringBuilder added in v0.30.0 

type PeerScoringBuilder interface {
	// SetTopicScoreParams sets the topic score parameters for the given topic.
	// If the topic score parameters have already been set for the given topic, it is overwritten.
	SetTopicScoreParams(topic channels.Topic, topicScoreParams *pubsub.TopicScoreParams)

	// SetAppSpecificScoreParams sets the application specific score parameters for the given topic.
	// If the application specific score parameters have already been set for the given topic, it is overwritten.
	SetAppSpecificScoreParams(func(peer.ID) float64)
}

type PeerScoringConfig added in v0.30.0 

type PeerScoringConfig struct {
	// TopicScoreParams is a map of topic score parameters for each topic.
	TopicScoreParams map[channels.Topic]*pubsub.TopicScoreParams
	// AppSpecificScoreParams is a function that returns the application specific score parameters for a given peer.
	AppSpecificScoreParams func(peer.ID) float64
}

PeerScoringConfig is a configuration for peer scoring parameters for a GossipSub pubsub system.

type PeersProvider added in v0.21.1 

type PeersProvider func() peer.IDSlice

type ProtocolPeerCache added in v0.30.0 

type ProtocolPeerCache interface {
	// RemovePeer removes the specified peer from the protocol cache.
	RemovePeer(peerID peer.ID)

	// AddProtocols adds the specified protocols for the given peer to the protocol cache.
	AddProtocols(peerID peer.ID, protocols []protocol.ID)

	// RemoveProtocols removes the specified protocols for the given peer from the protocol cache.
	RemoveProtocols(peerID peer.ID, protocols []protocol.ID)

	// GetPeers returns a copy of the set of peers that support the given protocol.
	GetPeers(pid protocol.ID) map[peer.ID]struct{}
}

ProtocolPeerCache is an interface that stores a mapping from protocol ID to peers who support that protocol.

type PubSubAdapter added in v0.29.0 

type PubSubAdapter interface {
	component.Component
	// RegisterTopicValidator registers a validator for topic.
	RegisterTopicValidator(topic string, topicValidator TopicValidatorFunc) error

	// UnregisterTopicValidator removes a validator from a topic.
	// Returns an error if there was no validator registered with the topic.
	UnregisterTopicValidator(topic string) error

	// Join joins the topic and returns a Topic handle.
	// Only one Topic handle should exist per topic, and Join will error if the Topic handle already exists.
	Join(topic string) (Topic, error)

	// GetTopics returns all the topics within the pubsub network that the current peer has subscribed to.
	GetTopics() []string

	// ListPeers returns all the peers subscribed to a topic.
	// Note that the current peer must be subscribed to the topic for it to query for other peers.
	// If the current peer is not subscribed to the topic, an empty list is returned.
	// For example, if current peer has subscribed to topics A and B, then ListPeers only return
	// subscribed peers for topics A and B, and querying for topic C will return an empty list.
	ListPeers(topic string) []peer.ID
}

PubSubAdapter is the abstraction of the underlying pubsub logic that is used by the Flow network.

type PubSubAdapterConfig added in v0.29.0 

type PubSubAdapterConfig interface {
	WithRoutingDiscovery(routing.ContentRouting)
	WithSubscriptionFilter(SubscriptionFilter)
	WithScoreOption(ScoreOptionBuilder)
	WithMessageIdFunction(f func([]byte) string)
	WithTracer(t PubSubTracer)
	// WithScoreTracer sets the tracer for the underlying pubsub score implementation.
	// This is used to expose the local scoring table of the GossipSub node to its higher level components.
	WithScoreTracer(tracer PeerScoreTracer)
	WithInspectorSuite(GossipSubInspectorSuite)
}

PubSubAdapterConfig abstracts the configuration for the underlying pubsub implementation.

type PubSubTracer added in v0.30.0 

type PubSubTracer interface {
	component.Component
	pubsub.RawTracer
}

PubSubTracer is the abstraction of the underlying pubsub tracer that is used by the Flow network. It wraps the pubsub.RawTracer interface with the component.Component interface so that it can be started and stopped. The RawTracer interface is used to trace the internal events of the pubsub system.

type RateLimiter added in v0.29.0 

type RateLimiter interface {
	BasicRateLimiter
	// IsRateLimited returns true if a peer is rate limited.
	IsRateLimited(peerID peer.ID) bool
}

RateLimiter rate limiter with lockout feature that can be used via the IsRateLimited method. This limiter allows users to flag a peer as rate limited for a lockout duration.

type RateLimiterConsumer added in v0.30.0 

type RateLimiterConsumer interface {
	OnRateLimitedPeer(pid peer.ID, role, msgType, topic, reason string)
}

RateLimiterConsumer consumes notifications from the ratelimit.RateLimiters whenever a peer is rate limited. Implementations must:

  • be concurrency safe
  • be non-blocking

type RateLimiterOpt added in v0.29.0 

type RateLimiterOpt func(limiter RateLimiter)

type ScoreOptionBuilder added in v0.29.0 

type ScoreOptionBuilder interface {
	// BuildFlowPubSubScoreOption builds the pubsub score options as pubsub.Option for the Flow network.
	BuildFlowPubSubScoreOption() pubsub.Option
}

ScoreOptionBuilder abstracts the configuration for the underlying pubsub score implementation.

type Subscription added in v0.29.0 

type Subscription interface {
	// Cancel cancels the subscription so that the caller will no longer receive messages from the topic.
	Cancel()

	// Topic returns the topic that the subscription is subscribed to.
	Topic() string

	// Next returns the next message from the subscription.
	Next(context.Context) (*pubsub.Message, error)
}

Subscription is the abstraction of the underlying pubsub subscription that is used by the Flow network.

type SubscriptionFilter added in v0.29.0 

type SubscriptionFilter interface {
	// CanSubscribe returns true if the current peer can subscribe to the topic.
	CanSubscribe(string) bool

	// FilterIncomingSubscriptions is invoked for all RPCs containing subscription notifications.
	// It filters and returns the subscriptions of interest to the current node.
	FilterIncomingSubscriptions(peer.ID, []*pb.RPC_SubOpts) ([]*pb.RPC_SubOpts, error)
}

SubscriptionFilter is the abstraction of the underlying pubsub subscription filter that is used by the Flow network.

type SubscriptionProvider added in v0.28.0 

type SubscriptionProvider interface {
	// GetSubscribedTopics returns all the subscriptions of a peer within the pubsub network.
	// Note that the current peer must be subscribed to the topic for it to the same topics in order
	// to query for other peers, e.g., if current peer has subscribed to topics A and B, and peer1
	// has subscribed to topics A, B, and C, then GetSubscribedTopics(peer1) will return A and B. Since this peer
	// has not subscribed to topic C, it will not be able to query for other peers subscribed to topic C.
	GetSubscribedTopics(pid peer.ID) []string
}

SubscriptionProvider provides a list of topics a peer is subscribed to.

type SubscriptionValidator added in v0.31.0 

type SubscriptionValidator interface {
	// RegisterSubscriptionProvider registers the subscription provider with the subscription validator.
	// If there is a subscription provider already registered, it will be replaced by the new one.
	RegisterSubscriptionProvider(provider SubscriptionProvider) error
	// CheckSubscribedToAllowedTopics checks if a peer is subscribed to topics that it is allowed to subscribe to.
	// Args:
	// 	pid: the peer ID of the peer to check
	//  role: the role of the peer to check
	// Returns:
	// error: if the peer is subscribed to topics that it is not allowed to subscribe to, an InvalidSubscriptionError is returned.
	// The error is benign, i.e., it does not indicate an illegal state in the execution of the code. We expect this error
	// when there are malicious peers in the network. But such errors should not lead to a crash of the node.
	CheckSubscribedToAllowedTopics(pid peer.ID, role flow.Role) error
}

SubscriptionValidator validates the subscription of a peer to a topic. It is used to ensure that a peer is only subscribed to topics that it is allowed to subscribe to.

type Subscriptions added in v0.30.0 

type Subscriptions interface {
	// HasSubscription returns true if the node currently has an active subscription to the topic.
	HasSubscription(topic channels.Topic) bool
	// SetUnicastManager sets the unicast manager for the node.
	SetUnicastManager(uniMgr UnicastManager)
}

Subscriptions set of funcs related to current subscription info of a node.

type Topic added in v0.29.0 

type Topic interface {
	// String returns the topic name as a string.
	String() string

	// Close closes the topic.
	Close() error

	// Publish publishes a message to the topic.
	Publish(context.Context, []byte) error

	// Subscribe returns a subscription to the topic so that the caller can receive messages from the topic.
	Subscribe() (Subscription, error)
}

Topic is the abstraction of the underlying pubsub topic that is used by the Flow network.

type TopicProvider added in v0.28.0 

type TopicProvider interface {
	// GetTopics returns all the topics within the pubsub network that the current peer has subscribed to.
	GetTopics() []string

	// ListPeers returns all the peers subscribed to a topic.
	// Note that the current peer must be subscribed to the topic for it to query for other peers.
	// If the current peer is not subscribed to the topic, an empty list is returned.
	// For example, if current peer has subscribed to topics A and B, then ListPeers only return
	// subscribed peers for topics A and B, and querying for topic C will return an empty list.
	ListPeers(topic string) []peer.ID
}

TopicProvider provides a low-level abstraction for pubsub to perform topic-related queries. This abstraction is provided to encapsulate the pubsub implementation details from the rest of the codebase.

type TopicScoreSnapshot added in v0.30.0 

type TopicScoreSnapshot struct {
	// TimeInMesh total time in mesh.
	TimeInMesh time.Duration
	// FirstMessageDeliveries counter of first message deliveries.
	FirstMessageDeliveries float64
	// MeshMessageDeliveries total mesh message deliveries (in the mesh).
	MeshMessageDeliveries float64
	// InvalidMessageDeliveries counter of invalid message deliveries.
	InvalidMessageDeliveries float64
}

TopicScoreSnapshot is a snapshot of the peer score within a topic at a given time. Note that float64 is used for the counters as they are decayed over the time.

func (TopicScoreSnapshot) IsWarning added in v0.30.0 

func (s TopicScoreSnapshot) IsWarning() bool

IsWarning returns true if the topic score is in warning state.

func (TopicScoreSnapshot) String added in v0.30.0 

func (s TopicScoreSnapshot) String() string

String returns the string representation of the peer score snapshot.

type TopicValidatorFunc added in v0.29.0 

type TopicValidatorFunc func(context.Context, peer.ID, *pubsub.Message) ValidationResult

type UnicastManager added in v0.30.0 

type UnicastManager interface {
	// WithDefaultHandler sets the default stream handler for this unicast manager. The default handler is utilized
	// as the core handler for other unicast protocols, e.g., compressions.
	WithDefaultHandler(defaultHandler libp2pnet.StreamHandler)
	// Register registers given protocol name as preferred unicast. Each invocation of register prioritizes the current protocol
	// over previously registered ones.
	// All errors returned from this function can be considered benign.
	Register(unicast protocols.ProtocolName) error
	// CreateStream tries establishing a libp2p stream to the remote peer id. It tries creating streams in the descending order of preference until
	// it either creates a successful stream or runs out of options. Creating stream on each protocol is tried at most `maxAttempts`, and then falls
	// back to the less preferred one.
	// All errors returned from this function can be considered benign.
	CreateStream(ctx context.Context, peerID peer.ID, maxAttempts int) (libp2pnet.Stream, []multiaddr.Multiaddr, error)
}

UnicastManager manages libp2p stream negotiation and creation, which is utilized for unicast dispatches.

type UnicastRateLimiterDistributor added in v0.30.0 

type UnicastRateLimiterDistributor interface {
	RateLimiterConsumer
	AddConsumer(consumer RateLimiterConsumer)
}

UnicastRateLimiterDistributor consumes then distributes notifications from the ratelimit.RateLimiters whenever a peer is rate limited.

type UpdateFunction added in v0.31.0 

type UpdateFunction func(record GossipSubSpamRecord) GossipSubSpamRecord

UpdateFunction is a function that adjusts the GossipSub spam record of a peer. Args: - record: the GossipSubSpamRecord of the peer. Returns: - *GossipSubSpamRecord: the adjusted GossipSubSpamRecord of the peer.

type ValidationResult added in v0.29.0 

type ValidationResult int
const (
	ValidationAccept ValidationResult = iota
	ValidationIgnore
	ValidationReject
)

Source Files

View all Source files

Directories

Path Synopsis
internal
internal
internal/cache
internal/ratelimit
validation
config
gossipsub
inspector
inspector/suite
Package p2pnode encapsulates the libp2p library
 Package p2pnode encapsulates the libp2p library
protocols
ratelimit
stream
ratelimiter
ratelimiter/internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.