leadership

README

Leadership: Distributed Leader Election for Clustered Environments.

Leadership is a library for a cluster leader election on top of a distributed Key/Value store.

It's built using Swarm's pkg/store and is designed to work across multiple storage backends.

Right now only Consul is supported but etcd and Zookeeper will be coming soon.

// Create a store using pkg/store.
client, err := store.NewStore("consul", []string{"127.0.0.1:8500"}, &store.Config{})
if err != nil {
	panic(err)
}

underwood := leadership.NewCandidate(client, "service/swarm/leader", "underwood")
underwood.RunForElection()

electedCh := underwood.ElectedCh()
for isElected := range rlectedCh {
	// This loop will run every time there is a change in our leadership
	// status.

	if isElected {
		// We won the election - we are now the leader.
		// Let's do leader stuff, for example, sleep for a while.
		log.Printf("I won the election! I'm now the leader")
		time.Sleep(10 * time.Second)

		// Tired of being a leader? You can resign anytime.
		candidate.Resign()
	} else {
		// We lost the election but are still running for leadership.
		// `elected == false` is the default state and is the first event
		// we'll receive from the channel. After a successfull election,
		// this event can get triggered if someone else steals the
		// leadership or if we resign.

		log.Printf("Lost the election, let's try another time")
	}
}

It is possible to follow an election in real-time and get notified whenever there is a change in leadership:

follower := leadership.NewFollower(client, "service/swarm/leader")
follower.FollowElection()
leaderCh := follower.LeaderCh()
for leader := <-leaderCh {
	// Leader is a string containing the value passed to `NewCandidate`.
	log.Printf("%s is now the leader", leader)
}

A typical usecase for this is to be able to always send requests to the current leader.

Documentation

Index

• type Candidate
  • func NewCandidate(client store.Store, key, node string) *Candidate
  • func (c *Candidate) ElectedCh() <-chan bool
  • func (c *Candidate) Resign()
  • func (c *Candidate) RunForElection() error
  • func (c *Candidate) Stop()
• type Follower
  • func NewFollower(client store.Store, key string) *Follower
  • func (f *Follower) FollowElection() error
  • func (f *Follower) LeaderCh() <-chan string
  • func (f *Follower) Stop()

Types

type Candidate

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

Candidate runs the leader election algorithm asynchronously

func NewCandidate

func NewCandidate(client store.Store, key, node string) *Candidate

NewCandidate creates a new Candidate

func (*Candidate) ElectedCh

func (c *Candidate) ElectedCh() <-chan bool

ElectedCh is used to get a channel which delivers signals on acquiring or losing leadership. It sends true if we become the leader, and false if we lose it.

func (*Candidate) Resign

func (c *Candidate) Resign()

Resign forces the candidate to step-down and try again. If the candidate is not a leader, it doesn't have any effect. Candidate will retry immediately to acquire the leadership. If no-one else took it, then the Candidate will end up being a leader again.

func (*Candidate) RunForElection

func (c *Candidate) RunForElection() error

RunForElection starts the leader election algorithm. Updates in status are pushed through the ElectedCh channel.

func (*Candidate) Stop

func (c *Candidate) Stop()

Stop running for election.

type Follower

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

Follower can folow an election in real-time and push notifications whenever there is a change in leadership.

func NewFollower

func NewFollower(client store.Store, key string) *Follower

NewFollower creates a new follower.

func (*Follower) FollowElection

func (f *Follower) FollowElection() error

FollowElection starts monitoring the election.

func (*Follower) LeaderCh

func (f *Follower) LeaderCh() <-chan string

LeaderCh is used to get a channel which delivers the currently elected leader.

func (*Follower) Stop

func (f *Follower) Stop()

Stop stops monitoring an election.