network

Documentation

Overview

(c) 2019 Dapper Labs - ALL RIGHTS RESERVED

Index

• func AllPeerUnreachableError(errs ...error) bool
• func IsPeerUnreachableError(e error) bool
• func NewPeerUnreachableError(err error) error
• type Channel
  • func (c Channel) String() string
• type ChannelList
  • func (cl ChannelList) ID() flow.Identifier
  • func (cl ChannelList) Len() int
  • func (cl ChannelList) Less(i, j int) bool
  • func (cl ChannelList) Swap(i, j int)
• type Codec
• type Conduit
• type Connection
• type Decoder
• type Encoder
• type Engine
• type MessageQueue
• type MessageValidator
• type Middleware
• type Overlay
• type PeerUnreachableError
  • func (e PeerUnreachableError) Error() string
  • func (e PeerUnreachableError) Unwrap() error
• type SubscriptionManager
• type Topic
  • func (t Topic) String() string
• type Topology

Functions

func AllPeerUnreachableError

func AllPeerUnreachableError(errs ...error) bool

AllPeerUnreachableError returns whether all errors are PeerUnreachableError

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

Types

type Channel

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 (Channel) String

func (c Channel) String() string

type ChannelList

type ChannelList []Channel

func (ChannelList) ID

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

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

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

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 Conduit

type Conduit interface {

	// Submit will submit an event to the network layer. The network layer will
	// ensure that the event is delivered to the same engine on the desired target
	// nodes. It's possible that the event traverses other nodes than the target
	// nodes on its path across the network. The network codec needs to be aware
	// of how to encode the given event type, otherwise the send will fail.
	//
	// Note: Submit method is planned for deprecation soon.
	// Alternative methods are recommended, e.g., Publish, Unicast, and Multicast.
	Submit(event interface{}, targetIDs ...flow.Identifier) error

	// 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 Connection

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 {

	// SubmitLocal submits an event originating on the local node.
	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.
	Submit(originID flow.Identifier, event interface{})

	// ProcessLocal processes an event originating on the local node.
	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.
	Process(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.

type MessageQueue

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

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.

type Middleware

type Middleware interface {
	// Start will start the middleware.
	Start(overlay Overlay) error

	// Stop will end the execution of the middleware and wait for it to end.
	Stop()

	// Send sends the message to the set of target ids
	// If there is only one target NodeID, then a direct 1-1 connection is used by calling middleware.sendDirect
	// Otherwise, middleware.Publish is used, which uses the PubSub method of communication.
	//
	// Deprecated: Send exists for historical compatibility, and should not be used on new
	// developments. It is planned to be cleaned up in near future. Proper utilization of Dispatch or
	// Publish are recommended instead.
	Send(channel Channel, msg *message.Message, targetIDs ...flow.Identifier) error

	// Dispatch 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

	// Ping pings the target node and returns the ping RTT or an error
	Ping(targetID flow.Identifier) (time.Duration, error)

	// UpdateAllowList fetches the most recent identity of the nodes from overlay
	// and updates the underlying libp2p node.
	UpdateAllowList() 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 Overlay

type Overlay interface {
	// Topology returns an identity list of nodes which this node should be directly connected to as peers
	Topology() (flow.IdentityList, error)
	// Identity returns a map of all identifier to flow identity
	Identity() (map[flow.Identifier]flow.Identity, error)
	Receive(nodeID flow.Identifier, msg *message.Message) 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 SubscriptionManager

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

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

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

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

type Topic

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 (Topic) String

func (t Topic) String() string

type Topology

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.