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
• type GroupProvider
• type NetworkProvider
• type PeerMessage
  • func NewPeerMessageFromBytes(buf []byte) (*PeerMessage, error)
  • func NewPeerMessageFromChunks(chunkBytes []byte, chunkSize int, msgChopper *chopper.Chopper) (*PeerMessage, error)
  • func (m *PeerMessage) Bytes() ([]byte, error)
  • func (m *PeerMessage) ChunkedBytes(chunkSize int, msgChopper *chopper.Chopper) ([][]byte, error)
  • func (m *PeerMessage) IsUserMessage() bool
• type PeerSender
• type PeerStatusProvider
• type RecvEvent

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.

Types

type GroupProvider

type GroupProvider interface {
	PeerIndex(peer PeerSender) (uint16, error)
	PeerIndexByNetID(peerNetID string) (uint16, error)
	SendMsgByIndex(peerIdx uint16, msg *PeerMessage)
	Broadcast(msg *PeerMessage, includingSelf bool)
	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() map[uint16]PeerSender   // Returns all the nodes in the group.
	OtherNodes() map[uint16]PeerSender // Returns other nodes in the group (excluding Self).
	Attach(chainID *coretypes.ChainID, callback func(recv *RecvEvent)) interface{}
	Detach(attachID interface{})
	Close()
}

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
	Group(peerAddrs []string) (GroupProvider, error)
	Attach(chainID *coretypes.ChainID, callback func(recv *RecvEvent)) interface{}
	Detach(attachID interface{})
	PeerByNetID(peerNetID string) (PeerSender, error)
	PeerByPubKey(peerPub kyber.Point) (PeerSender, error)
	PeerStatus() []PeerStatusProvider
}

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

type PeerMessage

type PeerMessage struct {
	ChainID     coretypes.ChainID
	SenderIndex uint16 // TODO: Only meaningful in a group, and when calculated by the client.
	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) (*PeerMessage, error)

func NewPeerMessageFromChunks

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

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

func (*PeerMessage) Bytes

func (m *PeerMessage) Bytes() ([]byte, error)

func (*PeerMessage) ChunkedBytes

func (m *PeerMessage) ChunkedBytes(chunkSize int, msgChopper *chopper.Chopper) ([][]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() kyber.Point

	// 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() kyber.Point
	IsInbound() bool
	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 RecvEvent

type RecvEvent struct {
	From PeerSender
	Msg  *PeerMessage
}

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