network

package
v0.26.14-test-synchron... Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2022 License: AGPL-3.0 Imports: 19 Imported by: 47

Documentation

Overview

(c) 2019 Dapper Labs - ALL RIGHTS RESERVED

Index

Constants

View Source 
const (

	// Channels used for testing
	TestNetworkChannel = Channel("test-network")
	TestMetricsChannel = Channel("test-metrics")

	// Channels for consensus protocols
	ConsensusCommittee     = Channel("consensus-committee")
	ConsensusClusterPrefix = "consensus-cluster" // dynamic channel, use ChannelConsensusCluster function

	// Channels for protocols actively synchronizing state across nodes
	SyncCommittee     = Channel("sync-committee")
	SyncClusterPrefix = "sync-cluster" // dynamic channel, use ChannelSyncCluster function
	SyncExecution     = Channel("sync-execution")

	// Channels for dkg communication
	DKGCommittee = "dkg-committee"

	// Channels for actively pushing entities to subscribers
	PushTransactions = Channel("push-transactions")
	PushGuarantees   = Channel("push-guarantees")
	PushBlocks       = Channel("push-blocks")
	PushReceipts     = Channel("push-receipts")
	PushApprovals    = Channel("push-approvals")

	// Channels for actively requesting missing entities
	RequestCollections       = Channel("request-collections")
	RequestChunks            = Channel("request-chunks")
	RequestReceiptsByBlockID = Channel("request-receipts-by-block-id")
	RequestApprovalsByChunk  = Channel("request-approvals-by-chunk")

	// Channel aliases to make the code more readable / more robust to errors
	ReceiveTransactions = PushTransactions
	ReceiveGuarantees   = PushGuarantees
	ReceiveBlocks       = PushBlocks
	ReceiveReceipts     = PushReceipts
	ReceiveApprovals    = PushApprovals

	ProvideCollections       = RequestCollections
	ProvideChunks            = RequestChunks
	ProvideReceiptsByBlockID = RequestReceiptsByBlockID
	ProvideApprovalsByChunk  = RequestApprovalsByChunk

	// Public network channels
	PublicSyncCommittee = Channel("public-sync-committee")

	// Execution data service
	ExecutionDataService = Channel("execution-data-service")
)

channels

Variables

View Source 
var (
	EmptyTargetList = errors.New("target list empty")
)

Functions

func AllPeerUnreachableError 

func AllPeerUnreachableError(errs ...error) bool

AllPeerUnreachableError returns whether all errors are PeerUnreachableError

func ChannelExists 

func ChannelExists(channel Channel) bool

ChannelExists returns true if the channel exists.

func ClusterChannelPrefix 

func ClusterChannelPrefix(clusterChannel Channel) (string, bool)

ClusterChannelPrefix returns the cluster channel prefix and true if clusterChannel exists inclusterChannelPrefixRoleMap

func ClusterChannelRoles 

func ClusterChannelRoles(clusterChannel Channel) flow.RoleList

ClusterChannelRoles returns the list of roles that are involved in the given cluster-based channel.

func IsClusterChannel 

func IsClusterChannel(channel Channel) bool

IsClusterChannel returns true if channel is cluster-based. Currently, only collection nodes are involved in a cluster-based channels.

func IsPeerUnreachableError 

func IsPeerUnreachableError(e error) bool

IsPeerUnreachableError returns whether the given error is PeerUnreachableError

func NewPeerUnreachableError 

func NewPeerUnreachableError(err error) error

NewPeerUnreachableError creates a PeerUnreachableError instance with an error

func RolesByChannel 

func RolesByChannel(channel Channel) (flow.RoleList, bool)

RolesByChannel returns list of flow roles involved in the channel. If the given channel is a public channel, the returned list will contain all roles.

Types

type Adapter added in v0.25.0 

type Adapter interface {
	// UnicastOnChannel sends the message in a reliable way to the given recipient.
	UnicastOnChannel(Channel, interface{}, flow.Identifier) error

	// PublishOnChannel sends the message in an unreliable way to all the given recipients.
	PublishOnChannel(Channel, interface{}, ...flow.Identifier) error

	// MulticastOnChannel unreliably sends the specified event over the channel to randomly selected number of recipients
	// selected from the specified targetIDs.
	MulticastOnChannel(Channel, interface{}, uint, ...flow.Identifier) error

	// UnRegisterChannel unregisters the engine for the specified channel. The engine will no longer be able to send or
	// receive messages from that channel.
	UnRegisterChannel(channel Channel) error
}

Adapter is a wrapper around the Network implementation. It only exposes message dissemination functionalities. Adapter is meant to be utilized by the Conduit interface to send messages to the Network layer to be delivered to the remote targets.

type BasicResolver added in v0.21.0 

type BasicResolver interface {
	LookupIPAddr(context.Context, string) ([]net.IPAddr, error)
	LookupTXT(context.Context, string) ([]string, error)
}

BasicResolver is a low level interface for DNS resolution Note: this is the resolver interface that libp2p expects. We keep a copy of it here for mock generation. https://github.com/multiformats/go-multiaddr-dns/blob/master/resolve.go

type BlobGetter added in v0.23.9 

type BlobGetter interface {
	// GetBlob gets the requested blob.
	GetBlob(ctx context.Context, c cid.Cid) (blobs.Blob, error)

	// GetBlobs does a batch request for the given cids, returning blobs as
	// they are found, in no particular order.
	//
	// It may not be able to find all requested blobs (or the context may
	// be canceled). In that case, it will close the channel early. It is up
	// to the consumer to detect this situation and keep track which blobs
	// it has received and which it hasn't.
	GetBlobs(ctx context.Context, ks []cid.Cid) <-chan blobs.Blob
}

BlobGetter is the common interface shared between blobservice sessions and the blobservice.

type BlobService added in v0.23.9 

type BlobService interface {
	component.Component
	BlobGetter

	// AddBlob puts a given blob to the underlying datastore
	AddBlob(ctx context.Context, b blobs.Blob) error

	// AddBlobs adds a slice of blobs at the same time using batching
	// capabilities of the underlying datastore whenever possible.
	AddBlobs(ctx context.Context, bs []blobs.Blob) error

	// DeleteBlob deletes the given blob from the blobservice.
	DeleteBlob(ctx context.Context, c cid.Cid) error

	// GetSession creates a new session that allows for controlled exchange of wantlists to decrease the bandwidth overhead.
	GetSession(ctx context.Context) BlobGetter

	// TriggerReprovide updates the BlobService's provider entries in the DHT
	TriggerReprovide(ctx context.Context) error
}

BlobService is a hybrid blob datastore. It stores data in a local datastore and may retrieve data from a remote Exchange. It uses an internal `datastore.Datastore` instance to store values.

type BlobServiceOption added in v0.23.9 

type BlobServiceOption func(BlobService)

type Channel added in v0.14.0 

type Channel string

Channel specifies a virtual and isolated communication medium. Nodes subscribed to the same channel can disseminate epidemic messages among each other, i.e.. multicast and publish.

func ChannelConsensusCluster 

func ChannelConsensusCluster(clusterID flow.ChainID) Channel

ChannelConsensusCluster returns a dynamic cluster consensus channel based on the chain ID of the cluster in question.

func ChannelFromTopic 

func ChannelFromTopic(topic Topic) (Channel, bool)

func ChannelSyncCluster 

func ChannelSyncCluster(clusterID flow.ChainID) Channel

ChannelSyncCluster returns a dynamic cluster sync channel based on the chain ID of the cluster in question.

func (Channel) String added in v0.14.0 

func (c Channel) String() string

type ChannelList added in v0.14.0 

type ChannelList []Channel

func Channels 

func Channels() ChannelList

Channels returns all channels that nodes of any role have subscribed to (except cluster-based channels).

func ChannelsByRole 

func ChannelsByRole(role flow.Role) ChannelList

ChannelsByRole returns a list of all channels the role subscribes to (except cluster-based channels and public channels).

func PublicChannels 

func PublicChannels() ChannelList

PublicChannels returns all channels that are used on the public network.

func UniqueChannels 

func UniqueChannels(channels ChannelList) ChannelList

UniqueChannels returns list of non-cluster channels with a unique RoleList accompanied with the list of all cluster channels. e.g. if channel X and Y both are non-cluster channels and have role IDs [A,B,C] then only one of them will be in the returned list.

func (ChannelList) Contains added in v0.21.1 

func (cl ChannelList) Contains(channel Channel) bool

Contains retuns true if the ChannelList contains the given channel.

func (ChannelList) ID added in v0.14.0 

func (cl ChannelList) ID() flow.Identifier

ID returns hash of the content of ChannelList. It first sorts the ChannelList and then takes its hash value.

func (ChannelList) Len added in v0.14.0 

func (cl ChannelList) Len() int

Len returns length of the ChannelList in the number of stored Channels. It satisfies the sort.Interface making the ChannelList sortable.

func (ChannelList) Less added in v0.14.0 

func (cl ChannelList) Less(i, j int) bool

Less returns true if element i in the ChannelList is less than j based on the numerical value of its Channel. Otherwise it returns true. It satisfies the sort.Interface making the ChannelList sortable.

func (ChannelList) Swap added in v0.14.0 

func (cl ChannelList) Swap(i, j int)

Swap swaps the element i and j in the ChannelList. It satisfies the sort.Interface making the ChannelList sortable.

type Codec 

type Codec interface {
	NewEncoder(w io.Writer) Encoder
	NewDecoder(r io.Reader) Decoder
	Encode(v interface{}) ([]byte, error)
	Decode(data []byte) (interface{}, error)
}

Codec provides factory functions for encoders and decoders.

type Compressor added in v0.23.0 

type Compressor interface {
	NewReader(io.Reader) (io.ReadCloser, error)
	NewWriter(io.Writer) (WriteCloseFlusher, error)
}

Compressor offers compressing and decompressing services for sending and receiving a byte slice at network layer.

type Conduit 

type Conduit interface {

	// Publish submits an event to the network layer for unreliable delivery
	// to subscribers of the given event on the network layer. It uses a
	// publish-subscribe layer and can thus not guarantee that the specified
	// recipients received the event.
	// The event is published on the channels of this Conduit and will be received
	// by the nodes specified as part of the targetIDs
	Publish(event interface{}, targetIDs ...flow.Identifier) error

	// Unicast sends the event in a reliable way to the given recipient.
	// It uses 1-1 direct messaging over the underlying network to deliver the event.
	// It returns an error if the unicast fails.
	Unicast(event interface{}, targetID flow.Identifier) error

	// Multicast unreliably sends the specified event over the channel
	// to the specified number of recipients selected from the specified subset.
	// The recipients are selected randomly from the targetIDs.
	Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error

	// Close unsubscribes from the channels of this conduit. After calling close,
	// the conduit can no longer be used to send a message.
	Close() error
}

Conduit represents the interface for engines to communicate over the peer-to-peer network. Upon registration with the network, each engine is assigned a conduit, which it can use to communicate across the network in a network-agnostic way. In the background, the network layer connects all engines with the same ID over a shared bus, accessible through the conduit.

type ConduitFactory added in v0.25.0 

type ConduitFactory interface {
	// RegisterAdapter sets the Adapter component of the factory.
	// The Adapter is a wrapper around the Network layer that only exposes the set of methods
	// that are needed by a conduit.
	RegisterAdapter(Adapter) error

	// NewConduit creates a conduit on the specified channel.
	// Prior to creating any conduit, the factory requires an Adapter to be registered with it.
	NewConduit(context.Context, Channel) (Conduit, error)
}

ConduitFactory is an interface type that is utilized by the Network to create conduits for the channels.

type Connection added in v0.12.3 

type Connection interface {
	Send(msg interface{}) error
	Receive() (interface{}, error)
}

Connection represents an interface to read from & write to a connection.

type Decoder 

type Decoder interface {
	Decode() (interface{}, error)
}

Decoder decodes from the underlying reader into the given message.

type Encoder 

type Encoder interface {
	Encode(v interface{}) error
}

Encoder encodes the given message into the underlying writer.

type Engine 

type Engine interface {
	module.ReadyDoneAware

	// SubmitLocal submits an event originating on the local node.
	// Deprecated: To asynchronously communicate a local message between components:
	// * Define a message queue on the component receiving the message
	// * Define a function (with a concrete argument type) on the component receiving
	//   the message, which adds the message to the message queue
	SubmitLocal(event interface{})

	// Submit submits the given event from the node with the given origin ID
	// for processing in a non-blocking manner. It returns instantly and logs
	// a potential processing error internally when done.
	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
	Submit(channel Channel, originID flow.Identifier, event interface{})

	// ProcessLocal processes an event originating on the local node.
	// Deprecated: To synchronously process a local message:
	// * Define a function (with a concrete argument type) on the component receiving
	//   the message, which blocks until the message is processed
	ProcessLocal(event interface{}) error

	// Process processes the given event from the node with the given origin ID
	// in a blocking manner. It returns the potential processing error when
	// done.
	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
	Process(channel Channel, originID flow.Identifier, event interface{}) error
}

Engine represents an isolated process running across the peer-to-peer network as part of the node business logic. It provides the network layer with the necessary interface to forward events to engines for processing. Deprecated: Use MessageProcessor instead

type MessageProcessor added in v0.17.2 

type MessageProcessor interface {
	Process(channel Channel, originID flow.Identifier, message interface{}) error
}

MessageProcessor represents a component which receives messages from the networking layer. Since these messages come from other nodes, which may be Byzantine, implementations must expect and handle arbitrary message inputs (including invalid message types, malformed messages, etc.). Because of this, node-internal messages should NEVER be submitted to a component using Process.

type MessageQueue added in v0.12.3 

type MessageQueue interface {
	// Insert inserts the message in queue
	Insert(message interface{}) error
	// Remove removes the message from the queue in priority order. If no message is found, this call blocks.
	// If two messages have the same priority, items are de-queued in insertion order
	Remove() interface{}
	// Len gives the current length of the queue
	Len() int
}

MessageQueue is the interface of the inbound message queue

type MessageValidator added in v0.12.3 

type MessageValidator interface {
	// Validate validates the message and returns true if the message is to be retained and false if it needs to be dropped
	Validate(msg message.Message) bool
}

MessageValidator validates the incoming message. Message validation happens in the middleware right before it is delivered to the network.

type Middleware added in v0.12.3 

type Middleware interface {
	component.Component

	// SetOverlay sets the overlay used by the middleware. This must be called before the middleware can be Started.
	SetOverlay(Overlay)

	// SendDirect sends msg on a 1-1 direct connection to the target ID. It models a guaranteed delivery asynchronous
	// direct one-to-one connection on the underlying network. No intermediate node on the overlay is utilized
	// as the router.
	//
	// Dispatch should be used whenever guaranteed delivery to a specific target is required. Otherwise, Publish is
	// a more efficient candidate.
	SendDirect(msg *message.Message, targetID flow.Identifier) error

	// Publish publishes a message on the channel. It models a distributed broadcast where the message is meant for all or
	// a many nodes subscribing to the channel. It does not guarantee the delivery though, and operates on a best
	// effort.
	Publish(msg *message.Message, channel Channel) error

	// Subscribe subscribes the middleware to a channel.
	Subscribe(channel Channel) error

	// Unsubscribe unsubscribes the middleware from a channel.
	Unsubscribe(channel Channel) error

	// UpdateNodeAddresses fetches and updates the addresses of all the authorized participants
	// in the Flow protocol.
	UpdateNodeAddresses()

	// NewBlobService creates a new BlobService for the given channel.
	NewBlobService(channel Channel, store datastore.Batching, opts ...BlobServiceOption) BlobService

	// NewPingService creates a new PingService for the given ping protocol ID.
	NewPingService(pingProtocol protocol.ID, provider PingInfoProvider) PingService

	IsConnected(nodeID flow.Identifier) (bool, error)
}

Middleware represents the middleware layer, which manages the connections to our direct neighbours on the network. It handles the creation & teardown of connections, as well as reading & writing to/from the connections.

type MsgAuthConfig 

type MsgAuthConfig struct {
	String string
	// contains filtered or unexported fields
}

MsgAuthConfig contains authorization information for a specific flow message. The authorization is represented as a map from network channel -> list of all roles allowed to send the message on the channel.

func GetMessageAuthConfig 

func GetMessageAuthConfig(v interface{}) (MsgAuthConfig, error)

func (MsgAuthConfig) IsAuthorized 

func (m MsgAuthConfig) IsAuthorized(role flow.Role, channel Channel) error

IsAuthorized checks if the specified role is authorized to send the message on channel and asserts that the message is authorized to be sent on channel.

type Network added in v0.23.0 

type Network interface {
	component.Component
	// Register will subscribe to the channel with the given engine and
	// the engine will be notified with incoming messages on the channel.
	// The returned Conduit can be used to send messages to engines on other nodes subscribed to the same channel
	// On a single node, only one engine can be subscribed to a channel at any given time.
	Register(channel Channel, messageProcessor MessageProcessor) (Conduit, error)

	// RegisterBlobService registers a BlobService on the given channel, using the given datastore to retrieve values.
	// The returned BlobService can be used to request blocks from the network.
	// TODO: We should return a function that can be called to unregister / close the BlobService
	RegisterBlobService(channel Channel, store datastore.Batching, opts ...BlobServiceOption) (BlobService, error)

	// RegisterPingService registers a ping protocol handler for the given protocol ID
	RegisterPingService(pingProtocolID protocol.ID, pingInfoProvider PingInfoProvider) (PingService, error)
}

Network represents the network layer of the node. It allows processes that work across the peer-to-peer network to register themselves as an engine with a unique engine ID. The returned conduit allows the process to communicate to the same engine on other nodes across the network in a network-agnostic way.

type Overlay added in v0.12.3 

type Overlay interface {
	// Topology returns an identity list of nodes which this node should be directly connected to as peers
	Topology() (flow.IdentityList, error)

	// Identities returns a list of all Flow identities on the network
	Identities() flow.IdentityList

	// GetIdentity returns the Identity associated with the given peer ID, if it exists
	Identity(peer.ID) (*flow.Identity, bool)

	Receive(nodeID flow.Identifier, msg *message.Message, decodedMsgPayload interface{}) error
}

Overlay represents the interface that middleware uses to interact with the overlay network layer.

type PeerUnreachableError 

type PeerUnreachableError struct {
	Err error
}

PeerUnreachableError is the error when submitting events to target fails due to the target peer is unreachable

func (PeerUnreachableError) Error 

func (e PeerUnreachableError) Error() string

func (PeerUnreachableError) Unwrap 

func (e PeerUnreachableError) Unwrap() error

Unwrap returns the wrapped error value

type PingInfoProvider added in v0.23.9 

type PingInfoProvider interface {
	SoftwareVersion() string
	SealedBlockHeight() uint64
	HotstuffView() uint64
}

PingInfoProvider is the interface used by the PingService to respond to incoming PingRequest with a PingResponse populated with the necessary details

type PingService added in v0.23.9 

type PingService interface {
	Ping(ctx context.Context, peerID peer.ID) (message.PingResponse, time.Duration, error)
}

type SubscriptionManager added in v0.12.3 

type SubscriptionManager interface {
	// Register registers an engine on the channel into the subscription manager.
	Register(channel Channel, engine MessageProcessor) error

	// Unregister removes the engine associated with a channel.
	Unregister(channel Channel) error

	// GetEngine returns engine associated with a channel.
	GetEngine(channel Channel) (MessageProcessor, error)

	// Channels returns all the channels registered in this subscription manager.
	Channels() ChannelList
}

type Topic added in v0.14.0 

type Topic string

Topic is the internal type of Libp2p which corresponds to the Channel in the network level. It is a virtual medium enabling nodes to subscribe and communicate over epidemic dissemination.

func TopicFromChannel 

func TopicFromChannel(channel Channel, rootBlockID flow.Identifier) Topic

TopicFromChannel returns the unique LibP2P topic form the channel. The channel is made up of name string suffixed with root block id. The root block id is used to prevent cross talks between nodes on different sporks.

func (Topic) String added in v0.14.0 

func (t Topic) String() string

type Topology added in v0.12.3 

type Topology interface {
	// GenerateFanout receives IdentityList of entire network, and list of channels the node is subscribing to.
	// It constructs and returns the fanout IdentityList of node.
	// A node directly communicates with its fanout IdentityList on epidemic dissemination
	// of the messages (i.e., publish and multicast).
	// Independent invocations of GenerateFanout on different nodes collaboratively must construct a cohesive
	// connected graph of nodes that enables them talking to each other.
	//
	// As a convention, GenerateFanout is not required to guarantee any deterministic behavior, i.e.,
	// invocations of GenerateFanout with the same input may result in different fanout sets.
	// One may utilize topology Cache to have a more deterministic endpoint on generating fanout.
	//
	// GenerateFanout is not concurrency safe. It is responsibility of caller to lock for it.
	// with the channels argument, it allows the returned topology to be cached, which is necessary for randomized topology.
	GenerateFanout(ids flow.IdentityList, channels ChannelList) (flow.IdentityList, error)
}

Topology provides a subset of nodes which a given node should directly connect to for 1-k messaging.

type WriteCloseFlusher added in v0.23.0 

type WriteCloseFlusher interface {
	io.WriteCloser
	Flush() error
}

Source Files

View all Source files

Directories

Path Synopsis
cbor
Package mocknetwork is a generated GoMock package.
 Package mocknetwork is a generated GoMock package.
p2p
Package p2p encapsulates the libp2p library
 Package p2p encapsulates the libp2p library
compressed
conduit
dns
keyutils
unicast
pubsub

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.