election

Documentation

Overview

Package election is a JetStream backed leader election system.

It lets one or more processes elect a leader based on competing for ownership of a JetStream consumer on a Stream configured to allow maximum 1 consumer per stream

JetStream will monitor the health of the leadership by observing the state of of a subscription - as long as the subscription exist the leadership is held. Subscription propagation is a core capability in NATS and an extremely reliable way to determine the health of a connected NATS client. Once the subscription is not valid anymore the Ephemeral consumer is removed, ready for a new leader to recreate it. A short grace period exists allowing for short client connection interruptions.

The leader will monitor Heartbeats sent from the Ephemeral consumer to it, if a number of these heartbeats are missed it will assume it lost access and the consumer will be removed. It will then trigger a process of standing down from leadership

Together this creates a leadership election system that's highly available and works across clusters, super cluster and leafnodes.

This feature is experimental

Index

• Constants
• func NewElection(name string, wonCb func(), lostCb func(), streamName string, mgr *jsm.Manager, ...) (*election, error)
• type Backoff
• type Option
  • func WithBackoff(bo Backoff) Option
  • func WithCampaignInterval(i time.Duration) Option
  • func WithDebug(cb func(format string, a ...interface{})) Option
  • func WithHeartBeatInterval(i time.Duration) Option
  • func WithMemoryStorage() Option
  • func WithMissedHeartbeatThreshold(t int) Option
  • func WithStream(stream *jsm.Stream) Option
  • func WithSubjectPrefix(p string) Option

Constants

const (
	// DefaultCampaignInterval how frequently campaigners will try to make the consumer
	DefaultCampaignInterval = 500 * time.Millisecond

	// DefaultHeartBeatInterval how frequently the consumer will inform the leader that it's still alive
	DefaultHeartBeatInterval = 500 * time.Millisecond

	// DefaultMissedHBThreshold how many heartbeats we can miss before we decide we lost leadership
	DefaultMissedHBThreshold = 3

	// DefaultSubjectPrefix is the prefix to use for election related subjects
	DefaultSubjectPrefix = "$LE"
)

Functions

func NewElection

func NewElection(name string, wonCb func(), lostCb func(), streamName string, mgr *jsm.Manager, opts ...Option) (*election, error)

NewElection creates a leader election, it will either create/join a stream called streamName or use the pre-made stream passed as option

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(*options) error

Option configures the leader election system

func WithBackoff

func WithBackoff(bo Backoff) Option

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

func WithCampaignInterval

func WithCampaignInterval(i time.Duration) Option

WithCampaignInterval sets the interval at which campaigners will attempt to become leader

func WithDebug

func WithDebug(cb func(format string, a ...interface{})) Option

WithDebug sets a function to do debug logging with

func WithHeartBeatInterval

func WithHeartBeatInterval(i time.Duration) Option

WithHeartBeatInterval sets the interval JetStream will notify the leader that it's still active

func WithMemoryStorage

func WithMemoryStorage() Option

WithMemoryStorage campaigns using a memory based stream

func WithMissedHeartbeatThreshold

func WithMissedHeartbeatThreshold(t int) Option

WithMissedHeartbeatThreshold configures how many heartbeats we can miss from JetStream

func WithStream

func WithStream(stream *jsm.Stream) Option

WithStream sets a specific stream as campaign target, must have max_consumers=1

func WithSubjectPrefix

func WithSubjectPrefix(p string) Option

WithSubjectPrefix sets the prefix to use for subjects used by the election