funk

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2020 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package funk contains the types needed to create a cluster using Raft and serf.

Examples

Index

Constants

View Source
const (
	// ZeroconfSerfKind is the type used to register serf endpoints in zeroconf.
	ZeroconfSerfKind = "serf"
	// ZeroconfManagementKind is the type used to register management endpoints
	// in zeroconf.
	ZeroconfManagementKind = "mgmt"
)
View Source
const (
	//These are
	//MetricsEndpoint    = "ep.metrics"    // MetricsEndpoint is the metrics endpoint
	//HTTPEndpoint       = "ep.http"       // HTTPEndpoint is the HTTP endpoint
	SerfEndpoint       = "ep.serf"
	RaftEndpoint       = "ep.raft"
	ManagementEndpoint = "ep.management" //  gRPC endpoint for management
	LivenessEndpoint   = "ep.liveness"
)

The following is a list of well-known endpoints on nodes

View Source
const (
	EndpointPrefix = "ep."
)

The following are internal tags and values for nodes

View Source
const (
	// SerfStatusKey is the key for the serf status
	SerfStatusKey = "serf.status"
)

Variables

View Source
var (
	// SerfLeft is the status of the serf node when it has left the cluster
	SerfLeft = serf.StatusLeft.String()
	// SerfAlive is the status of the serf node when it is alive and well
	SerfAlive = serf.StatusAlive.String()
	// SerfFailed is the status of the serf node when it has failed
	SerfFailed = serf.StatusFailed.String()
)

Functions

This section is empty.

Types

type Cluster

type Cluster interface {
	// NodeID is the local cluster node's ID
	NodeID() string

	// Name returns the cluster's name
	Name() string

	// Start launches the cluster, ie joins a Serf cluster and announces its
	// presence
	Start() error

	// Stop stops the cluster
	Stop()

	// Role is the current role of the node
	Role() NodeRole

	// State is the current cluster state
	State() NodeState

	// Events returns an event channel for the cluster. The channel will
	// be closed when the cluster is stopped. Events are for information only
	Events() <-chan Event

	// SetEndpoint registers an endpoint on the local node
	SetEndpoint(name string, endpoint string)

	// Leader returns the node ID of the leader in the cluster. If no leader
	// is currently elected it will return a blank string.
	Leader() string

	// Nodes returns a list of the node IDs of each member
	Nodes() []string

	// GetEndpoint returns the endpoint for a particular node. If the node
	// or endpoint isn't found it will return a blank. The endpoint is
	// retrieved from the Serf cluster. Note that there's no guarantee
	// that the node will be responding on that endpoint.
	GetEndpoint(nodeID string, endpointName string) string
}

Cluster is a wrapper for the Serf and Raft libraries. It will handle typical cluster operations.

func NewCluster

func NewCluster(params Parameters, shardManager sharding.ShardMap) Cluster

NewCluster returns a new cluster (client)

type Event

type Event struct {
	State NodeState // State is the state of the local cluster node
	Role  NodeRole  // Role is the role (leader, follower...) of the local cluster node
}

Event is the interface for cluster events that are triggered. The events are triggered by changes in the node state. The Role field is informational. When the cluster is in state Operational the shard map contains the current shard mapping. If the State field is different from Operational the shard map may contain an invalid or outdated mapping.

type GRPCServerParameters

type GRPCServerParameters struct {
	Endpoint string `kong:"help='Server endpoint'"`
	TLS      bool   `kong:"help='Enable TLS'"`
	CertFile string `kong:"help='Certificate file',type='existingfile'"`
	KeyFile  string `kong:"help='Certificate key file',type='existingfile'"`
}

GRPCServerParameters is a parameter struct for gRPC services The struct uses annotations from Kong (https://github.com/alecthomas/kong)

type LeaderChangedEvent

type LeaderChangedEvent struct {
}

LeaderChangedEvent is emitted when the leader of the cluster has changed.

type LeaderLostEvent

type LeaderLostEvent struct {
}

LeaderLostEvent is emitted when the leader is about to change.

type LivenessChecker

type LivenessChecker interface {
	// Add adds a new new check to the list.
	Add(id string, endpoint string)

	// Remove removes a single checker
	Remove(id string)

	// DeadEvents returns the event channel. The ID from the Add method is
	// echoed on this channel when a client stops responding.
	DeadEvents() <-chan string

	// AliveEvents returns an event channel for alive events.
	AliveEvents() <-chan string

	// Clear removes all endpoint checks.
	Clear()

	// Shutdown shuts down the checker and closes the event channel. The
	// checker will no longer be in an usable state after this.
	Shutdown()
}

LivenessChecker is a liveness checker. It does a (very simple) high freqyency liveness check on nodes. If it fails more than a certain number of times an event is generated on the DeadEvents channel. Only a single subscriber is supported for this channel.

func NewLivenessChecker

func NewLivenessChecker(interval time.Duration, retries int) LivenessChecker

NewLivenessChecker is a type that checks hosts for liveness

type LocalLivenessEndpoint

type LocalLivenessEndpoint interface {
	Stop()
}

LocalLivenessEndpoint launches a local liveness client. The client will respond to (short) UDP packets by echoing back the packet on the same port. This is not a *health* check, just a liveness check if the node is reachable on the network.

func NewLivenessClient

func NewLivenessClient(ep string) LocalLivenessEndpoint

NewLivenessClient creates a new liveness endpoint with the specified port/address. Response is sent immideately

type LocalNodeStoppedEvent

type LocalNodeStoppedEvent struct {
}

LocalNodeStoppedEvent is emitted when the local node is stopping

type LogMessage

type LogMessage struct {
	MessageType LogMessageType
	AckEndpoint string
	Index       uint64
	Data        []byte
}

LogMessage is log messages sent by the leader. There's only two types at this time. The payload is a byte array that can be unmarshalled into another type of message.

func NewLogMessage

func NewLogMessage(t LogMessageType, endpoint string, data []byte) LogMessage

NewLogMessage creates a new LogMessage instance

func (*LogMessage) MarshalBinary

func (m *LogMessage) MarshalBinary() ([]byte, error)

MarshalBinary converts a Raft log message into a LogMessage struct.

func (*LogMessage) UnmarshalBinary

func (m *LogMessage) UnmarshalBinary(buf []byte) error

UnmarshalBinary unmarshals the byte array into this instance

type LogMessageType

type LogMessageType byte

LogMessageType is the log message type we're writing at the start of every log message

const (
	// ProposedShardMap is the new shard map the leader proposes (dictatorship-style)
	// to the followers. The payload for this message is a marshalled ShardManager
	// instance.
	ProposedShardMap LogMessageType = 1
	// ShardMapCommitted is a  message that will synchronize the
	// shard map distributed in the previous message.
	ShardMapCommitted LogMessageType = 2
)

type NodeAddedEvent

type NodeAddedEvent struct {
}

NodeAddedEvent is emitted when a new node is added to the cluster.

type NodeEvent

type NodeEvent struct {
	Event SerfEventType
	Node  SerfMember
}

NodeEvent is used for channel notifications

type NodeRemovedEvent

type NodeRemovedEvent struct {
}

NodeRemovedEvent is emitted when a node is removed from the cluster

type NodeRetiredEvent

type NodeRetiredEvent struct {
}

NodeRetiredEvent is emitted when a node is about to be retired.

type NodeRole

type NodeRole int32

NodeRole is the roles the node can have in the cluster

const (
	Unknown   NodeRole = iota // Uknown state
	Follower                  // A follower in a cluster
	Leader                    // The current leader node
	NonVoter                  // Non voting role in cluster
	NonMember                 // NonMember nodes are part of the Serf cluster but not the Raft cluste
)

These are the roles the node might have in the cluster

func (NodeRole) String

func (n NodeRole) String() string

type NodeState

type NodeState int32

NodeState is the enumeration of different states a node can be in.

const (
	Invalid     NodeState = iota // Invalid or unknown state
	Joining                      // Joining the cluster
	Operational                  // Operational, normal operation
	Voting                       // Leader election in progress
	Resharding                   // Leader is elected, resharding in progress
	Starting                     // Starting the node
	Stopping                     // Stopping the node
)

These are the (local) states the cluster node can be in

func (NodeState) String

func (n NodeState) String() string

type Parameters

type Parameters struct {
	AutoJoin         bool                 `kong:"help='Auto join via SerfEvents',default='true'"`
	Name             string               `kong:"help='Cluster name',default='clusterfunk'"`
	Interface        string               `kong:"help='Interface address for services'"`
	Verbose          bool                 `kong:"help='Verbose logging for Serf and Raft'"`
	NodeID           string               `kong:"help='Node ID for Serf and Raft'"`
	ZeroConf         bool                 `kong:"help='Zero-conf startup',default='true'"`
	NonVoting        bool                 `kong:"help='Nonvoting node',default='false'"`
	NonMember        bool                 `kong:"help='Non-member',default='false'"`
	LivenessInterval time.Duration        `kong:"help='Liveness checker intervals',default='150ms'"`
	LivenessRetries  int                  `kong:"help='Number of retries for liveness checks',default='3'"`
	LivenessEndpoint string               `kong:"help='Liveness UDP endpoint'"`
	AckTimeout       time.Duration        `kong:"help='Ack timeout for nodes in the cluster',default='500ms'"`
	Metrics          string               `kong:"help='Metrics sink to use',enum='blackhole,prometheus',default='prometheus'"`
	Raft             RaftParameters       `kong:"embed,prefix='raft-'"`
	Serf             SerfParameters       `kong:"embed,prefix='serf-'"`
	Management       GRPCServerParameters `kong:"embed,prefix='management-'"`
	LeaderEndpoint   string               // This isn't a parameter, it's set by the service
}

Parameters is the parameters required for the cluster. The defaults are suitable for a development cluster but not for a production cluster.

func (*Parameters) Final

func (p *Parameters) Final()

Final sets the defaults for the parameters that haven't got a sensible value, f.e. endpoints and defaults. Defaults that are random values can't be set via the parameter library. Yet.

type RaftEventType

type RaftEventType int

RaftEventType is the event type for events emitted by the RaftNode type

const (
	//RaftClusterSizeChanged is emitted when a new node is added
	RaftClusterSizeChanged RaftEventType = iota
	// RaftLeaderLost is emitted when the leader is lost, ie the node enters the candidate state
	RaftLeaderLost
	// RaftBecameLeader is emitted when the leader becomes the leader
	RaftBecameLeader
	// RaftBecameFollower is emitted when the node becomes a follower
	RaftBecameFollower
	// RaftReceivedLog is emitted when a log entry is receievd
	RaftReceivedLog
	// RaftUndefinedEvent is the undefined event type
	RaftUndefinedEvent
)

func (RaftEventType) String

func (r RaftEventType) String() string

String is the string representation of the event

type RaftNode

type RaftNode struct {
	Nodes toolbox.StringSet
	// contains filtered or unexported fields
}

RaftNode is a wrapper for the Raft library. The raw events are coalesced into higher level events (particularly RaftClusterSizeChanged). Coalesced events introduce a small (millisecond) delay on the events but everything on top of this library will operate in the millisecond range.

In addition this type keeps track of the active nodes at all times via the raft events. There's no guarantee that the list of nodes in the cluster will be up to date or correct for the followers. The followers will only interact with the leader of the cluster.

func NewRaftNode

func NewRaftNode() *RaftNode

NewRaftNode creates a new RaftNode instance

func (*RaftNode) AddClusterNode

func (r *RaftNode) AddClusterNode(nodeID string, endpoint string) error

AddClusterNode adds a new node to the cluster. Must be leader to perform this operation.

func (*RaftNode) AppendLogEntry

func (r *RaftNode) AppendLogEntry(data []byte) (uint64, error)

AppendLogEntry appends a log entry to the log. The function returns when there's a quorum in the cluster

func (*RaftNode) Apply

func (r *RaftNode) Apply(l *raft.Log) interface{}

Apply log is invoked once a log entry is committed. It returns a value which will be made available in the ApplyFuture returned by Raft.Apply method if that method was called on the same Raft node as the FSM.

func (*RaftNode) DisableNode

func (r *RaftNode) DisableNode(id string)

DisableNode disables a node (in reality removing it from the local node list but it is still a member of the Raft cluster)

func (*RaftNode) EnableNode

func (r *RaftNode) EnableNode(id string)

EnableNode enables a node that has been disabled. The node might be a part of the cluster but not available.

func (*RaftNode) Endpoint

func (r *RaftNode) Endpoint() string

Endpoint returns the Raft endpoint (aka bind address)

func (*RaftNode) Events

func (r *RaftNode) Events() <-chan RaftEventType

Events returns the event channel. There is only one event channel so use multiple listeners at your own peril. You will get NodeAdded, NodeRemoved, LeaderLost and LeaderChanged events on this channel.

func (*RaftNode) GetLogMessages

func (r *RaftNode) GetLogMessages(startingIndex uint64) []LogMessage

GetLogMessages returns the replicated log message with the specified type ID

func (*RaftNode) LastLogIndex

func (r *RaftNode) LastLogIndex() uint64

LastLogIndex returns the last log index received

func (*RaftNode) Leader

func (r *RaftNode) Leader() bool

Leader returns true if this node is the leader. This will verify the leadership with the Raft library.

func (*RaftNode) LeaderNodeID

func (r *RaftNode) LeaderNodeID() string

LeaderNodeID returns the Node ID for the leader

func (*RaftNode) LocalNodeID

func (r *RaftNode) LocalNodeID() string

LocalNodeID returns the local NodeID

func (*RaftNode) RefreshNodes

func (r *RaftNode) RefreshNodes()

RefreshNodes refreshes the node list by reading the Raft configuration. If any events are skipped by the Raft library we'll get the appropriate events and an updated node list after this call.

func (*RaftNode) RemoveClusterNode

func (r *RaftNode) RemoveClusterNode(nodeID string, endpoint string) error

RemoveClusterNode removes a node from the cluster. Must be leader to perform this operation.

func (*RaftNode) Restore

func (r *RaftNode) Restore(io.ReadCloser) error

Restore is used to restore an FSM from a snapshot. It is not called concurrently with any other command. The FSM must discard all previous state.

func (*RaftNode) Snapshot

func (r *RaftNode) Snapshot() (raft.FSMSnapshot, error)

Snapshot is used to support log compaction. This call should return an FSMSnapshot which can be used to save a point-in-time snapshot of the FSM. Apply and Snapshot are not called in multiple threads, but Apply will be called concurrently with Persist. This means the FSM should be implemented in a fashion that allows for concurrent updates while a snapshot is happening.

func (*RaftNode) Start

func (r *RaftNode) Start(nodeID string, cfg RaftParameters) error

Start launches the node

func (*RaftNode) StepDown

func (r *RaftNode) StepDown() error

StepDown steps down as a leader if this is the leader node

func (*RaftNode) Stop

func (r *RaftNode) Stop(removeWhenStopping bool) error

Stop stops the node. If the removeWhenStopping flag is set and the server is the leader it will remove itself.

type RaftParameters

type RaftParameters struct {
	RaftEndpoint string `kong:"help='Endpoint for Raft',default=''"`
	DiskStore    bool   `kong:"help='Disk-based store',default='false'"`
	Bootstrap    bool   `kong:"help='Bootstrap a new Raft cluster',default='false'"`
	Verbose      bool   `kong:"help='Verbose Raft logging',default='false'"`
	DebugLog     bool   `kong:"help='Show debug log messages for Raft',default='false'"`
}

RaftParameters is the configuration for the Raft cluster

type SerfEventType

type SerfEventType int

SerfEventType is the type of events the SerfNode emits

const (
	SerfNodeJoined  SerfEventType = iota // A node joins the cluster
	SerfNodeLeft                         // A node has left the cluster
	SerfNodeUpdated                      // A node's tags are updated
)

Serf event types.

func (SerfEventType) String

func (s SerfEventType) String() string

type SerfMember

type SerfMember struct {
	NodeID string
	State  string
	Tags   map[string]string
}

SerfMember holds information on members in the Serf cluster.

type SerfNode

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

SerfNode is a wrapper around the Serf library

func NewSerfNode

func NewSerfNode() *SerfNode

NewSerfNode creates a new SerfNode instance

func (*SerfNode) Events

func (s *SerfNode) Events() <-chan NodeEvent

Events returns a notification channel. If the client isn't reading the events will be dropped.

func (*SerfNode) LoadMembers

func (s *SerfNode) LoadMembers() []SerfMember

LoadMembers reads the list of existing members in the Serf cluster

func (*SerfNode) Node

func (s *SerfNode) Node(nodeID string) SerfMember

Node returns information on a particular node. If the node isn't found the node returned will be empty

func (*SerfNode) Nodes

func (s *SerfNode) Nodes() []SerfMember

Nodes returns a list of known member nodes

func (*SerfNode) PublishTags

func (s *SerfNode) PublishTags() error

PublishTags publishes the tags to the other members of the cluster

func (*SerfNode) SetTag

func (s *SerfNode) SetTag(name, value string)

SetTag sets a tag on the serf node. The tags are not updated until PublishTags are called by the client

func (*SerfNode) Size

func (s *SerfNode) Size() int

Size returns the size of the member list

func (*SerfNode) Start

func (s *SerfNode) Start(nodeID string, cfg SerfParameters) error

Start launches the serf node

func (*SerfNode) Stop

func (s *SerfNode) Stop() error

Stop shuts down the node

type SerfParameters

type SerfParameters struct {
	Endpoint    string `kong:"help='Endpoint for Serf',default=''"`
	JoinAddress string `kong:"help='Join address and port for Serf cluster'"`
	Verbose     bool   `kong:"help='Verbose logging for Serf'"`
}

SerfParameters holds parameters for the Serf client

func (*SerfParameters) Final

func (s *SerfParameters) Final()

Final populates empty fields with default values

Directories

Path Synopsis
Package clusterpb contains the generate gRPC code
Package clusterpb contains the generate gRPC code
Package managepb contains the protobuf-generate code for the cluster management interface
Package managepb contains the protobuf-generate code for the cluster management interface
Package metrics handles metrics for the cluster.
Package metrics handles metrics for the cluster.
shardpb
Package shardpb contains the protobuf-generated code for the internal cluster communication
Package shardpb contains the protobuf-generated code for the internal cluster communication

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL