goelect

README

Goelect is an open-source Go (Golang) library for leader election. It is heavily influenced by the election component of the Raft implementation. For more details, you can refer to Raft Wiki.

Features

• Independent Operation: No third-party services are required. You don't need to set up or rely on external systems like ZooKeeper or etcd.
• Simplified Integration: Easy to integrate into your existing Golang projects with minimal configuration.
• Supports Novote role：The no-vote node does not participate in the election.
• Highly Available: Built to be fault-tolerant, suitable for systems that require high availability.

How to use

Config

// ElectConfig is a struct that represents the configuration for an election.
type ElectConfig struct {
    // Timeout for heartbeat messages, in milliseconds
    HeartBeatInterval uint
    // Timeout for election messages, in milliseconds
    ElectTimeout uint
    // Timeout for connecting to peers, in seconds
    ConnectTimeout uint
    // List of peers in the network
    Peers []Node
    // Node represents the information of this node
    Node Node
    // State callbacks
    CallBacks *StateCallBacks
    // Timeout for callbacks, in seconds
    CallBackTimeout int
}

Example

examples/onenode/node.go is a great example of using this goelect package.

Create an Elect instance:

e, err := goelect.NewElect(&goelect.ElectConfig{
		ElectTimeout:      200,
		HeartBeatInterval: 150,
		ConnectTimeout:    10,
		Peers:             peerNodes,
		// state transition callbacks
		CallBacks: &goelect.StateCallBacks{
			EnterLeader:    enterLeader,
			LeaveLeader:    leaveLeader,
			EnterFollower:  enterFollower,
			LeaveFollower:  leaveFollower,
			EnterCandidate: enterCandidate,
			LeaveCandidate: leaveCandidate,
		},
		// self node
		Node: goelect.Node{
			Address: *nodeAddress,
			ID:      *nodeAddress,
		},
	}, slog.Default())

Start the Elect:

err = e.Run()

This is everything we need to do :)

Documentation

Index

• type Elect
  • func NewElect(cfg *ElectConfig, logger log.Logger) (*Elect, error)
  • func (e *Elect) ClusterState() (*model.ClusterState, error)
  • func (e *Elect) CurrentState() string
  • func (e *Elect) Errors() <-chan error
  • func (e *Elect) IsLeader() bool
  • func (e *Elect) Leader() (string, error)
  • func (e *Elect) Run() error
• type ElectConfig
• type Node
• type StateCallBacks
• type StateHandler

Types

type Elect

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

Elect contains information about an election

func NewElect

func NewElect(cfg *ElectConfig, logger log.Logger) (*Elect, error)

NewElect creates a new Elect instance

func (*Elect) ClusterState

func (e *Elect) ClusterState() (*model.ClusterState, error)

ClusterState returns current cluster state

func (*Elect) CurrentState

func (e *Elect) CurrentState() string

CurrentState returns current node state

func (*Elect) Errors

func (e *Elect) Errors() <-chan error

Errors returns a receive-only channel of type error from the Elect struct

func (*Elect) IsLeader

func (e *Elect) IsLeader() bool

IsLeader returns true if the current node is the leader

func (*Elect) Leader

func (e *Elect) Leader() (string, error)

Leader returns the leader node id, if no leader is found, it returns an error

func (*Elect) Run

func (e *Elect) Run() error

Run is the main function of the Elect struct It starts the RPC server, runs the consensus algorithm.

type ElectConfig

type ElectConfig struct {
	// Timeout for heartbeat messages, in milliseconds
	HeartBeatInterval uint
	// Timeout for election messages, in milliseconds
	ElectTimeout uint
	// Timeout for connecting to peers, in seconds
	ConnectTimeout uint
	// List of peers in the network
	Peers []Node
	// Node represents the information of this node
	Node Node
	// State callbacks
	CallBacks *StateCallBacks
	// Timeout for callbacks, in seconds
	CallBackTimeout int
}

ElectConfig is a struct that represents the configuration for an election.

type Node

type Node struct {
	// ID of the node
	ID string
	// Address of the node
	Address string
	// NoVote indicates whether the node is able to vote
	NoVote bool
	// Tags associated with the node
	Tags map[string]string
}

Node is a struct that represents an elect node

type StateCallBacks

type StateCallBacks struct {
	// EnterLeader is a callback function to be called when entering the leader state
	EnterLeader StateHandler
	// LeaveLeader is a callback function to be called when leaving the leader state
	LeaveLeader StateHandler
	// EnterFollower is a callback function to be called when entering the follower state
	EnterFollower StateHandler
	// LeaveFollower is a callback function to be called when leaving the follower state
	LeaveFollower StateHandler
	// EnterCandidate is a callback function to be called when entering the candidate state
	EnterCandidate StateHandler
	// LeaveCandidate is a callback function to be called when leaving the candidate state
	LeaveCandidate StateHandler
}

StateCallBacks is a struct to hold state callbacks

type StateHandler

type StateHandler func(ctx context.Context, st model.StateTransition) error