core

Documentation

Index

• type ASCON
  • func NewASCON(key []byte) (ASCON, error)
• type GossipManager
  • func NewGossipManager(logger *zap.Logger, maxTx int) GossipManager
• type Invalidator
• type NodeList
  • func NewNodeList(logger *zap.Logger, selfAddr proto.IP) NodeList
• type NodeManager
  • func NewNodeManager(logger *zap.Logger, selfAddr proto.IP) NodeManager
• type NodeType
  • func (n NodeType) Is(o NodeType) bool
  • func (n NodeType) Remote() bool
  • func (n NodeType) Stable() bool
  • func (i NodeType) String() string
  • func (n NodeType) Suspect() bool
• type RunLoop
  • func NewRunLoop(log *zap.Logger, protocolPeriod time.Duration, delegate RunLoopDelegate, ...) RunLoop
• type RunLoopDelegate
• type Suspect
  • func (s Suspect) String() string
• type SyncManager
  • func NewSyncManager(logger *zap.Logger, delegate SyncManagerDelegate) SyncManager
• type SyncManagerDelegate
• type TCPPacketDecoder
• type TCPPacketEncoder

Types

type ASCON

type ASCON interface {
	// Seal seals the provided buffer and returns its ciphered data, except
	// when ASCON is initialized without a key. On the latter, the input is
	// immediately returned to the caller as-is.
	Seal(data []byte) ([]byte, error)

	// Open opens a provided sealed buffer and returns its plain data, except
	// when ASCON is initialized without a key. On the latter, the input is
	// immediately returned to the caller as-is. In case decoding fails, nil
	// is returned.
	Open(data []byte) []byte
}

ASCON represents an instance capable of sealing and opening data encrypted by the ASCON cipher suite, using 128-bit security and 320-bit permutation with different round numbers, thus being enough to implement AEAD with low overhead.

func NewASCON

func NewASCON(key []byte) (ASCON, error)

NewASCON returns a new ASCON handler. When key is empty or nil, the returned handler performs NOOPs on both Seal and Open operations.

type GossipManager

type GossipManager interface {
	// Add attempts to add a given event to the internal queue, depending on the
	// current contents (i.e. if the received event can override an existing event)
	Add(item *proto.Event)

	// Next returns a slice of proto.Event that fits in the provided maxLength.
	// Events returned have their transmission counters automatically incremented,
	// and events transmitted the maximum transmission count are automatically
	// removed.
	Next(maxLength int) []proto.Event

	// AdjustMaxTransmission sets the amount of transmission quantity for next
	// messages to a given integer value. This does not affect messages that were
	// enqueued before the call.
	AdjustMaxTransmission(maxTx int)
	LastGossipAbout(addr proto.IP) *proto.Event
	CurrentGossips() []proto.Event
}

GossipManager implements a mechanism to register and obtain gossips about items we received through the piggyback mechanism.

func NewGossipManager

func NewGossipManager(logger *zap.Logger, maxTx int) GossipManager

NewGossipManager returns a new gossipManager that will attempt to retransmit known events up to maxTx times.

type Invalidator

type Invalidator interface {
	Invalidates(ev *proto.Event) bool
}

type NodeList

type NodeList interface {
	// Add stores a given node in case it is not a member of the current list
	Add(currentPeriod uint16, node *proto.Node)

	// Range ranges over nodes present in this list. Filter can be used to
	// limit which kind of node will be yielded. NodeType is a bitfield, meaning
	// it can be bitwise ORed in order to compose filters. The parameter fn is a
	// function that will be called for each node matching the provided filter;
	// its return value determines whether iteration should continue.
	// Do not attempt use other methods during ranges, as it will result in a
	// deadlock.
	Range(filter NodeType, fn func(n *proto.Node) bool)

	// MarkStable marks a previously added node with proto.NodeHash `hash` as
	// stable, in case it has any other state.
	MarkStable(hash proto.NodeHash)

	// MarkSuspect moves a node identified by a given `hash` to the suspect list
	// under the current protocol `period`. `remote` indicates whether the node
	// is being marked as suspect due to a report from a remote peer. If the
	// current instance has deemed the hash as suspicious by itself, this value
	// must be set to `false`.
	MarkSuspect(period uint16, remote bool, hash proto.NodeHash)

	// MarkFaulty marks a node with given `hash` as Faulty (by removing it from
	// the members list).
	MarkFaulty(hash proto.NodeHash)

	// ExpiredSuspects returns a list of nodes that have status NodeTypeSuspect
	// for at least `expirationRounds` relative to the `currentPeriod`. This
	// method does not return nodes marked as suspect by other nodes; those are
	// automatically expunged as Faulty.
	ExpiredSuspects(currentPeriod, expirationRounds uint16) []*proto.Node

	// Delete removes a node identified by a given proto.NodeHash from the
	// members list, ignoring its current state.
	Delete(hash proto.NodeHash)

	// Bootstrap accepts an initial list of nodes to be added to the current
	// member list.
	Bootstrap(period uint16, list []proto.Node)

	// NodeByHash returns a known node identified by the provided proto.NodeHash
	NodeByHash(hash proto.NodeHash) *proto.Node

	// NodeByIP work like NodeByHash, but searching for a node with a given IP
	// address.
	NodeByIP(ip proto.IP) *proto.Node

	// IndirectPingCandidates returns at most k random nodes from the list of
	// members to be used as indirect ping delegates.
	IndirectPingCandidates(k int, except proto.NodeHash) []*proto.Node
}

func NewNodeList

func NewNodeList(logger *zap.Logger, selfAddr proto.IP) NodeList

NewNodeList returns a new nodeList

type NodeManager

type NodeManager interface {
	NodeList

	// Bootstrap initializes both the internal node list and the ping list from
	// a list provided by another node. See also nodeList.Bootstrap.
	Bootstrap(period uint16, list []proto.Node)

	// Add inserts a node to the member and ping lists. See also nodeList.Add.
	Add(period uint16, node *proto.Node)

	// MarkFaulty removes a node from both the member and node lists. See also
	// nodeList.MarkFaulty.
	MarkFaulty(hash proto.NodeHash)

	// NextPing returns the next node to be pinged as part of the protocol period.
	// Returns nil in case no node is currently in the members list.
	NextPing() *proto.Node

	// UpdateOrCreate updates or creates the provided node, considering its
	// provided status.
	UpdateOrCreate(period uint16, node *proto.Node)

	// WrapIncarnation forcefully updates a given node to contain a new
	// incarnation identifier provided by the `node` parameter.
	WrapIncarnation(period uint16, node *proto.Node)

	// All returns a copy of the list of all nodes known by this manager that
	// matches the provided filter.
	All(filter NodeType) []proto.Node
}

NodeManager holds a list of nodes and handles all state transitions between them. It also provides nodes to be used as indirect probes, and retains the node order for ping operations during the protocol period.

func NewNodeManager

func NewNodeManager(logger *zap.Logger, selfAddr proto.IP) NodeManager

NewNodeManager returns a new nodeManager

type NodeType

type NodeType uint8

const (
	NodeTypeStable NodeType = 1 << iota
	NodeTypeSuspect
	NodeTypeRemote

	NodeTypeInvalid NodeType = 0
)

func (NodeType) Is

func (n NodeType) Is(o NodeType) bool

func (NodeType) Remote

func (n NodeType) Remote() bool

func (NodeType) Stable

func (n NodeType) Stable() bool

func (NodeType) String

func (i NodeType) String() string

func (NodeType) Suspect

func (n NodeType) Suspect() bool

type RunLoop

type RunLoop interface {
	// Start starts the RunLoop in another routine, servicing messages, and
	// performing all protocol operations.
	Start()

	// ReceiveMessage enqueues a given message to be processed by the RunLoop.
	ReceiveMessage(packet *proto.Packet)

	// Shutdown signals that the current RunLoop should stop in the next
	// iteration. This method blocks until the loop has stopped.
	Shutdown()

	// CurrentPeriod returns the current protocol period identifier. This
	// operation is not atomic.
	CurrentPeriod() uint16
}

func NewRunLoop

func NewRunLoop(log *zap.Logger, protocolPeriod time.Duration, delegate RunLoopDelegate, udpMaxLen int, useAdaptivePing bool, syncProtoRounds int) RunLoop

NewRunLoop returns a new RunLoop

type RunLoopDelegate

type RunLoopDelegate interface {
	// NextProbeSubject returns the next node to be probed as part of the
	// protocol period.
	NextProbeSubject() *proto.Node

	// GossipEvents returns the next list of events that should be relayed to
	// the node being probed.
	GossipEvents(maxLen int) []proto.Event

	// DispatchMessage dispatches a given proto.Message to the provided
	// destination.
	DispatchMessage(dst net.IP, message proto.Message)

	// SignalHealthyNode signals that a node identified by the provided
	// proto.NodeHash has successfully been probed by the current protocol
	// period.
	SignalHealthyNode(node proto.NodeHash)

	// SignalSuspectNode signals that a node identified by the provided
	// proto.NodeHash has not met the current protocol period expectations and
	// must be considered suspect.
	SignalSuspectNode(node proto.NodeHash)

	// ProcessExpiredSuspects requests the delegate to process the current
	// suspects list in order to locate nodes that have expired the allowed
	// suspect timeout.
	ProcessExpiredSuspects()

	// PingTimeout specifies the maximum duration to wait for a ping
	// acknowledgment from a node. If this duration is exceeded without
	// receiving an acknowledgment, the node is marked as suspect. This delegate
	// will not be called if Options.UseAdaptivePingTimeout is enabled.
	PingTimeout() time.Duration

	// IndirectPingMembers returns a list of nodes to be used to probe a given
	// node identified by the provided proto.NodeHash
	IndirectPingMembers(node proto.NodeHash) []*proto.Node

	// NodeByHash returns a node identified under a given proto.NodeHash
	NodeByHash(node proto.NodeHash) *proto.Node

	// PerformFullSync instructs the delegate to perform a full sync with any
	// known member of the cluster
	PerformFullSync()
}

type Suspect

type Suspect struct {
	// Node contains information about the node being suspected of being
	// at fault.
	Node *proto.Node

	// SuspectAtPeriod represents the protocol period number when this node was
	// assumed as unstable by the current node.
	SuspectAtPeriod uint16

	// FromRemote indicates whether this suspect was assumed as suspect by the
	// current node (false), of it was assumed as suspect through the gossip
	// sub-protocol. When set, this suspect node must be handled normally by
	// the suspect timeout check, but once it expires, instead of disseminating
	// a faulty message, the current node will only silently mark it as faulty,
	// as the responsibility of disseminating the proto.EventFaulty pertains
	// to the node that announced it as suspect. This prevents a stale suspect
	// from staying in the node list in case the responsible for announcing it
	// goes down before announcing it as faulty.
	FromRemote bool
}

Suspect represents a suspect node in the cluster

func (Suspect) String

func (s Suspect) String() string

type SyncManager

type SyncManager interface {
	HandleBootstrap(msg *proto.Sync, client wire.TCPControlClient)
	HandleSyncRequest(msg *proto.Sync, client wire.TCPControlClient)
	PerformSync(target proto.Node)
	PerformBootstrap(target proto.Node)
	SetBootstrapSource(source net.IP)
}

func NewSyncManager

func NewSyncManager(logger *zap.Logger, delegate SyncManagerDelegate) SyncManager

type SyncManagerDelegate

type SyncManagerDelegate interface {
	TCPPacketDecoder
	TCPPacketEncoder
	BootstrapCompleted(manager SyncManager)
	HandleIncomingNodeList(manager SyncManager, nodes []proto.Node)
	DispatchTCPPacket(manager SyncManager, msg proto.Message, client wire.TCPControlClient) error
	EstablishTCP(manager SyncManager, node proto.Node) (wire.TCPControlClient, error)
	AllKnownNodes(manager SyncManager) []proto.Node
	PerformBootstrapComplete(manager SyncManager, target proto.Node)
}

type TCPPacketDecoder

type TCPPacketDecoder interface {
	DecodeTCPPacket(tcpPkt *proto.TCPPacket, client wire.TCPControlClient) (*proto.Packet, error)
}

type TCPPacketEncoder

type TCPPacketEncoder interface {
	EncodeTCPPacket(message proto.Message) (*proto.TCPPacket, error)
}