election

Documentation

Index

• func NewElection(name string, key string, bucket nats.KeyValue, opts ...Option) (*election, error)
• type Backoff
• type Option
  • func OnCampaign(cb func(s State)) Option
  • func OnLost(cb func()) Option
  • func OnWon(cb func()) Option
  • func WithBackoff(bo Backoff) Option
  • func WithDebug(cb func(format string, a ...any)) Option
• type State
  • func (s State) String() string

Functions

func NewElection

func NewElection(name string, key string, bucket nats.KeyValue, opts ...Option) (*election, error)

NewElection creates a new leader election for a member name.

Leader election is done using a KV Bucket where each key is an election, the key therefore should be a unique identifier for the election. Bucket is a loaded bucket using either NATS libraries of the helper in the choria package.

Buckets can be created using the NATS libraries or the "choria kv add ELECTION --ttl 30s --replicas 3" command, here we set a 30s TTL on the bucket which would be used to influence campaign frequency and the failover time after an outage of the leader. The smallest allowed TTL is 5 seconds though we suggest picking the biggest number in the range of 30 to 60 seconds that works for your use case.

A standard bucket CHORIA_LEADER_ELECTION gets made for Choria Streams and it's replicas and ttl is configurable in the config file.

Types

type Backoff

type Backoff interface {
	// Duration returns the time to sleep for the nth invocation
	Duration(n int) time.Duration
}

Backoff controls the interval of campaigns

type Option

type Option func(o *options)

Option configures the election system

func OnCampaign

func OnCampaign(cb func(s State)) Option

OnCampaign is called each time a campaign is done by the leader or a candidate

func OnLost

func OnLost(cb func()) Option

OnLost is a callback called when losing an election

func OnWon

func OnWon(cb func()) Option

OnWon is a callback called when winning an election

func WithBackoff

func WithBackoff(bo Backoff) Option

WithBackoff will use the provided Backoff timer source to decrease campaign intervals over time

func WithDebug

func WithDebug(cb func(format string, a ...any)) Option

WithDebug sets a function to do debug logging with

type State

type State uint

State indicates the current state of the election

const (
	// UnknownState indicates the state is unknown, like when the election is not started
	UnknownState State = 0
	// CandidateState is a campaigner that is not the leader
	CandidateState State = 1
	// LeaderState is the leader
	LeaderState State = 2
)

func (State) String

func (s State) String() string