peering

Documentation

Overview

Package peering provides an overlay network for communicating between nodes in a peer-to-peer style with low overhead encoding and persistent connections. The network provides only the asynchronous communication.

It is intended to use for the committee consensus protocol.

Index

• Constants
• func CheckMyNetID(myNetID string, configPort int) error
• func CheckNetID(netID string) error
• func ParseNetID(netID string) (string, int, error)
• type GroupProvider
• type NetworkProvider
• type PeerCollection
• type PeerDomainProvider
• type PeerMessage
  • func NewPeerMessageFromBytes(buf []byte, peerPubKey *ed25519.PublicKey) (*PeerMessage, error)
  • func NewPeerMessageFromChunks(chunkBytes []byte, chunkSize int, msgChopper *chopper.Chopper, ...) (*PeerMessage, error)
  • func (m *PeerMessage) Bytes(nodeIdentity *ed25519.KeyPair) ([]byte, error)
  • func (m *PeerMessage) ChunkedBytes(chunkSize int, msgChopper *chopper.Chopper, nodeIdentity *ed25519.KeyPair) ([][]byte, error)
  • func (m *PeerMessage) IsUserMessage() bool
• type PeerSender
• type PeerStatusProvider
• type PeeringID
  • func RandomPeeringID(seed ...[]byte) PeeringID
  • func (pid *PeeringID) Read(r io.Reader) error
  • func (pid *PeeringID) String() string
  • func (pid *PeeringID) Write(w io.Writer) error
• type RecvEvent
• type StaticPeerNetworkConfig
  • func NewStaticPeerNetworkConfigProvider(ownNetID string, peeringPort int, neighbors ...string) (*StaticPeerNetworkConfig, error)
  • func (p *StaticPeerNetworkConfig) Neighbors() []string
  • func (p *StaticPeerNetworkConfig) OwnNetID() string
  • func (p *StaticPeerNetworkConfig) PeeringPort() int
  • func (p *StaticPeerNetworkConfig) String() string
• type TrustedNetworkManager
• type TrustedPeer
  • func TrustedPeerFromBytes(buf []byte) (*TrustedPeer, error)
  • func (tp *TrustedPeer) Bytes() ([]byte, error)
  • func (tp *TrustedPeer) PubKeyBytes() ([]byte, error)

Constants

const (
	MsgTypeReserved  = byte(0)
	MsgTypeHandshake = byte(1)
	MsgTypeMsgChunk  = byte(2)

	// FirstUserMsgCode is the first committee message type.
	// All the equal and larger msg types are committee messages.
	// those with smaller are reserved by the package for heartbeat and handshake messages
	FirstUserMsgCode = byte(0x10)
)

Functions

func CheckMyNetID

func CheckMyNetID(myNetID string, configPort int) error

CheckMyNetID checks if NetID from the committee list represents current node.

func CheckNetID

func CheckNetID(netID string) error

Check, if NetID is of proper format.

func ParseNetID

func ParseNetID(netID string) (string, int, error)

ParseNetID parses the NetID and returns the corresponding host and port.

Types

type GroupProvider

type GroupProvider interface {
	SelfIndex() uint16
	PeerIndex(peer PeerSender) (uint16, error)
	PeerIndexByNetID(peerNetID string) (uint16, error)
	SendMsgByIndex(peerIdx uint16, msg *PeerMessage)
	Broadcast(msg *PeerMessage, includingSelf bool, except ...uint16)
	ExchangeRound(
		peers map[uint16]PeerSender,
		recvCh chan *RecvEvent,
		retryTimeout time.Duration,
		giveUpTimeout time.Duration,
		sendCB func(peerIdx uint16, peer PeerSender),
		recvCB func(recv *RecvEvent) (bool, error),
	) error
	AllNodes(except ...uint16) map[uint16]PeerSender   // Returns all the nodes in the group except specified.
	OtherNodes(except ...uint16) map[uint16]PeerSender // Returns other nodes in the group (excluding Self and specified).
	PeerCollection
}

GroupProvider stands for a subset of a peer-to-peer network that is responsible for achieving some common goal, eg, consensus committee, DKG group, etc.

Indexes are only meaningful in the groups, not in the network or a particular peers.

type NetworkProvider

type NetworkProvider interface {
	Run(stopCh <-chan struct{})
	Self() PeerSender
	PeerGroup(peerAddrs []string) (GroupProvider, error)
	PeerDomain(peerAddrs []string) (PeerDomainProvider, error)
	Attach(peeringID *PeeringID, callback func(recv *RecvEvent)) interface{}
	Detach(attachID interface{})
	PeerByNetID(peerNetID string) (PeerSender, error)
	PeerByPubKey(peerPub *ed25519.PublicKey) (PeerSender, error)
	PeerStatus() []PeerStatusProvider
}

NetworkProvider stands for the peer-to-peer network, as seen from the viewpoint of a single participant.

type PeerCollection

type PeerCollection interface {
	Attach(peeringID *PeeringID, callback func(recv *RecvEvent)) interface{}
	Detach(attachID interface{})
	Close()
}

type PeerDomainProvider

type PeerDomainProvider interface {
	SendMsgByNetID(netID string, msg *PeerMessage)
	SendMsgToRandomPeers(upToNumPeers uint16, msg *PeerMessage)
	SendSimple(netID string, msgType byte, msgData []byte)
	SendMsgToRandomPeersSimple(upToNumPeers uint16, msgType byte, msgData []byte)
	ReshufflePeers(seedBytes ...[]byte)
	GetRandomPeers(upToNumPeers int) []string
	PeerCollection
}

PeerDomainProvider implements unordered set of peers which can dynamically change All peers in the domain shares same peeringID. Each peer within domain is identified via its netID

type PeerMessage

type PeerMessage struct {
	PeeringID   PeeringID
	SenderIndex uint16 // TODO: Only meaningful in a group, and when calculated by the client.
	SenderNetID string // TODO: Non persistent. Only used by PeeringDomain, filled by the receiver
	Timestamp   int64
	MsgType     byte
	MsgData     []byte
}

PeerMessage is an envelope for all the messages exchanged via the peering module.

func NewPeerMessageFromBytes

func NewPeerMessageFromBytes(buf []byte, peerPubKey *ed25519.PublicKey) (*PeerMessage, error)

func NewPeerMessageFromChunks

func NewPeerMessageFromChunks(chunkBytes []byte, chunkSize int, msgChopper *chopper.Chopper, peerPubKey *ed25519.PublicKey) (*PeerMessage, error)

NewPeerMessageFromChunks can return nil, if there is not enough chunks to reconstruct the message.

func (*PeerMessage) Bytes

func (m *PeerMessage) Bytes(nodeIdentity *ed25519.KeyPair) ([]byte, error)

func (*PeerMessage) ChunkedBytes

func (m *PeerMessage) ChunkedBytes(chunkSize int, msgChopper *chopper.Chopper, nodeIdentity *ed25519.KeyPair) ([][]byte, error)

func (*PeerMessage) IsUserMessage

func (m *PeerMessage) IsUserMessage() bool

type PeerSender

type PeerSender interface {

	// NetID identifies the peer.
	NetID() string

	// PubKey of the peer is only available, when it is
	// authenticated, therefore it can return nil, if pub
	// key is not known yet. You can call await before calling
	// this function to ensure the public key is already resolved.
	PubKey() *ed25519.PublicKey

	// SendMsg works in an asynchronous way, and therefore the
	// errors are not returned here.
	SendMsg(msg *PeerMessage)

	// IsAlive indicates, if there is a working connection with the peer.
	// It is always an approximate state.
	IsAlive() bool

	// Await for the connection to be established, handshaked, and the
	// public key resolved.
	Await(timeout time.Duration) error

	// Close releases the reference to the peer, this informs the network
	// implementation, that it can disconnect, cleanup resources, etc.
	// You need to get new reference to the peer (PeerSender) to use it again.
	Close()
}

PeerSender represents an interface to some remote peer.

type PeerStatusProvider

type PeerStatusProvider interface {
	NetID() string
	PubKey() *ed25519.PublicKey
	IsAlive() bool
	NumUsers() int
}

PeerStatusProvider is used to access the current state of the network peer without allocating it (increading usage counters, etc). This interface overlaps with the PeerSender, and most probably they both will be implemented by the same object.

type PeeringID

type PeeringID [ledgerstate.AddressLength]byte

PeeringID is relates peers in different nodes for a particular communication group. E.g. PeeringID identifies a committee in the consensus, etc.

func RandomPeeringID

func RandomPeeringID(seed ...[]byte) PeeringID

func (*PeeringID) Read

func (pid *PeeringID) Read(r io.Reader) error

func (*PeeringID) String

func (pid *PeeringID) String() string

func (*PeeringID) Write

func (pid *PeeringID) Write(w io.Writer) error

type RecvEvent

type RecvEvent struct {
	From PeerSender
	Msg  *PeerMessage
}

RecvEvent stands for a received message along with the reference to its sender peer.

type StaticPeerNetworkConfig

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

StaticPeerNetworkConfig in an implementation of registry.PeerNetworkConfigProvider. It does not change Alternatively, the configuration of peers behind could change and be dependent on chain

func NewStaticPeerNetworkConfigProvider

func NewStaticPeerNetworkConfigProvider(ownNetID string, peeringPort int, neighbors ...string) (*StaticPeerNetworkConfig, error)

NewStaticPeerNetworkConfigProvider is a configuration of the peer environment which does not change

func (*StaticPeerNetworkConfig) Neighbors

func (p *StaticPeerNetworkConfig) Neighbors() []string

func (*StaticPeerNetworkConfig) OwnNetID

func (p *StaticPeerNetworkConfig) OwnNetID() string

func (*StaticPeerNetworkConfig) PeeringPort

func (p *StaticPeerNetworkConfig) PeeringPort() int

func (*StaticPeerNetworkConfig) String

func (p *StaticPeerNetworkConfig) String() string

type TrustedNetworkManager

type TrustedNetworkManager interface {
	IsTrustedPeer(pubKey ed25519.PublicKey) error
	TrustPeer(pubKey ed25519.PublicKey, netID string) (*TrustedPeer, error)
	DistrustPeer(pubKey ed25519.PublicKey) (*TrustedPeer, error)
	TrustedPeers() ([]*TrustedPeer, error)
}

TrustedNetworkManager is used maintain a configuration which peers are trusted. In a typical implementation, this interface should be implemented by the same struct, that implements the NetworkProvider. These implementations should interact, e.g. when we distrust some peer, all the connections to it should be cut immediately.

type TrustedPeer

type TrustedPeer struct {
	PubKey ed25519.PublicKey
	NetID  string
}

TrustedPeer carries a peer information we use to trust it.

func TrustedPeerFromBytes

func TrustedPeerFromBytes(buf []byte) (*TrustedPeer, error)

func (*TrustedPeer) Bytes

func (tp *TrustedPeer) Bytes() ([]byte, error)

func (*TrustedPeer) PubKeyBytes

func (tp *TrustedPeer) PubKeyBytes() ([]byte, error)