peers

Documentation

Overview

Package peers defines the concept of a Babble peer and implements functions to manage collections of peers.

A Babble peer is an entity that operates a Babble node. When a peer belongs to a collection of peers engaged in a Babble network, we refer to it as a validator, or a participant, to indicate that it is actively involved in the underlying consensus algorithm. The distinction is relevant because a peer can be in or out of consensus network as the group membership evolves.

A peer-set refers to a collection of peers, whilst a validator-set refers to a collection of peers simultaneously involved in the same consensus network. Again, the distinction is relevant because a collection of peers forming a validator-set at a given time in a Babble network, may become out of date as peers join or leave the network.

Peers are identified by their public keys, and optionaly a moniker which is a non-unique user-friendly name. When WebRTC is not activated, a peer should also specify an IP address and port where it can be reached by other peers. With WebRTC, the public key is enough to indentify a peer within the signaling server, and the network address is not necessary.

Upon starting up, Babble expects to find a peers.json file, and optionaly a peers.genesis.json file, in its data directory. The peers.json file represents a list of peers that the node should attempt to connect to. The peers.genesis.json file defines the initial validator-set corresponding to the inception of the Babble network. If a peers.genesis.json file is not found, the peers.json file is used for the initial validator-set. The reason for having two peers files is explained in the node package,

Index

• type JSONPeerSet
  • func NewJSONPeerSet(base string, isCurrent bool) *JSONPeerSet
  • func (j *JSONPeerSet) PeerSet() (*PeerSet, error)
  • func (j *JSONPeerSet) Write(peers []*Peer) error
• type Peer
  • func ExcludePeer(peers []*Peer, peer uint32) (int, []*Peer)
  • func NewPeer(pubKeyHex, netAddr, moniker string) *Peer
  • func (p *Peer) ID() uint32
  • func (p *Peer) Marshal() ([]byte, error)
  • func (p *Peer) PubKeyBytes() []byte
  • func (p *Peer) PubKeyString() string
  • func (p *Peer) Unmarshal(data []byte) error
• type PeerSet
  • func NewPeerSet(peers []*Peer) *PeerSet
  • func (peerSet *PeerSet) Hash() ([]byte, error)
  • func (peerSet *PeerSet) Hex() string
  • func (peerSet *PeerSet) IDs() []uint32
  • func (peerSet *PeerSet) Len() int
  • func (peerSet *PeerSet) Marshal() ([]byte, error)
  • func (peerSet *PeerSet) PubKeys() []string
  • func (peerSet *PeerSet) SuperMajority() int
  • func (peerSet *PeerSet) TrustCount() int
  • func (peerSet *PeerSet) Unmarshal(peerSliceBytes []byte) error
  • func (peerSet *PeerSet) WithNewPeer(peer *Peer) *PeerSet
  • func (peerSet *PeerSet) WithRemovedPeer(peer *Peer) *PeerSet

Types

type JSONPeerSet

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

JSONPeerSet is used to provide peer persistence on disk in the form of a JSON file.

func NewJSONPeerSet

func NewJSONPeerSet(base string, isCurrent bool) *JSONPeerSet

NewJSONPeerSet creates a new JSONPeerSet with reference to a base directory where the JSON files reside.

func (*JSONPeerSet) PeerSet

func (j *JSONPeerSet) PeerSet() (*PeerSet, error)

PeerSet parses the underlying JSON file and returns the corresponding PeerSet.

func (*JSONPeerSet) Write

func (j *JSONPeerSet) Write(peers []*Peer) error

Write persists a PeerSet to a JSON file.

type Peer

type Peer struct {
	// NetAddr is the IP:PORT of the Babble node. Not necessary with WebRTC.
	NetAddr string
	// PubKeyHex is the hexadecimal representation of the peer's public key.
	PubKeyHex string
	// Moniker is an optional friendly name for the peer. It does not need to be
	// unique.
	Moniker string
	// contains filtered or unexported fields
}

Peer is a struct that holds Peer data.

func ExcludePeer

func ExcludePeer(peers []*Peer, peer uint32) (int, []*Peer)

ExcludePeer is used to exclude a single peer from a list of peers.

func NewPeer

func NewPeer(pubKeyHex, netAddr, moniker string) *Peer

NewPeer instantiates a Peer.

func (*Peer) ID

func (p *Peer) ID() uint32

ID returns an ID for the peer, calculated from the public key.

func (*Peer) Marshal

func (p *Peer) Marshal() ([]byte, error)

Marshal marshals the Peer object. Note that this excludes the id field, forcing consumers to recalculate it.

func (*Peer) PubKeyBytes

func (p *Peer) PubKeyBytes() []byte

PubKeyBytes returns the byte slice representation of the Peer's public key.

func (*Peer) PubKeyString

func (p *Peer) PubKeyString() string

PubKeyString returns the upper-case version of PubKeyHex. It is used for indexing in maps with string keys.

func (*Peer) Unmarshal

func (p *Peer) Unmarshal(data []byte) error

Unmarshal unmarshals a byte slice into a Peer object.

type PeerSet

type PeerSet struct {
	Peers    []*Peer          `json:"peers"`
	ByPubKey map[string]*Peer `json:"-"`
	ByID     map[uint32]*Peer `json:"-"`
	// contains filtered or unexported fields
}

PeerSet represents a collection of peers.

func NewPeerSet

func NewPeerSet(peers []*Peer) *PeerSet

NewPeerSet creates a new PeerSet from a list of Peers.

func (*PeerSet) Hash

func (peerSet *PeerSet) Hash() ([]byte, error)

Hash uniquely identifies a PeerSet. It is computed by hashing (SHA256) their public keys together, one by one.

func (*PeerSet) Hex

func (peerSet *PeerSet) Hex() string

Hex is the hexadecimal representation of Hash

func (*PeerSet) IDs

func (peerSet *PeerSet) IDs() []uint32

IDs returns the PeerSet's slice of IDs

func (*PeerSet) Len

func (peerSet *PeerSet) Len() int

Len returns the number of Peers in the PeerSet

func (*PeerSet) Marshal

func (peerSet *PeerSet) Marshal() ([]byte, error)

Marshal marshals the PeerSet.

func (*PeerSet) PubKeys

func (peerSet *PeerSet) PubKeys() []string

PubKeys returns the PeerSet's slice of public keys

func (*PeerSet) SuperMajority

func (peerSet *PeerSet) SuperMajority() int

SuperMajority return the number of peers that forms a strong majortiy (+2/3) in the PeerSet

func (*PeerSet) TrustCount

func (peerSet *PeerSet) TrustCount() int

TrustCount calculates the minimum number of signatures associated to a state, such that those signatures may represent the finality of such state, given the assumptions of the consensus algorithm.

func (*PeerSet) Unmarshal

func (peerSet *PeerSet) Unmarshal(peerSliceBytes []byte) error

Unmarshal unmarshals a PeerSet.

func (*PeerSet) WithNewPeer

func (peerSet *PeerSet) WithNewPeer(peer *Peer) *PeerSet

WithNewPeer returns a new PeerSet with a list of peers including the new one.

func (*PeerSet) WithRemovedPeer

func (peerSet *PeerSet) WithRemovedPeer(peer *Peer) *PeerSet

WithRemovedPeer returns a new PeerSet with a list of peers excluding the provided one