raft

Documentation

Overview

Package raft contains Raft consensus for WebMesh.

Index

• Constants
• Variables
• type BootstrapCallback
• type LeaderObservation
• type MonotonicLogStore
  • func (m *MonotonicLogStore) IsMonotonic() bool
• type Observation
• type ObservationCallback
• type Options
  • func NewOptions(nodeID string) Options
  • func (o *Options) RaftConfig(ctx context.Context, nodeID string) *raft.Config
• type PeerObservation
• type Raft
  • func New(ctx context.Context, opts Options) Raft
  • func NewPassthrough(ctx context.Context, nodeID string, dialer transport.NodeDialer) Raft
• type SnapshotMeta
• type SnapshotRestoreCallback
• type StartOptions

Constants

const (
	// DefaultListenPort is the default raft listen port
	DefaultListenPort = 9000
	// DefaultListenAddress is the default raft listen address
	DefaultListenAddress = "[::]:9000"
)

const (
	Follower  = raft.Follower
	Candidate = raft.Candidate
	Leader    = raft.Leader
	Shutdown  = raft.Shutdown
)

Raft states.

const (
	Voter    = raft.Voter
	Nonvoter = raft.Nonvoter
)

Raft suffrage states.

Variables

var (
	// ErrStarted is returned when the Raft node is already started.
	ErrStarted = errors.New("raft node already started")
	// ErrClosed is returned when the Raft node is already closed.
	ErrClosed = errors.New("raft node is closed")
	// ErrNoLeader is returned when there is no leader.
	ErrNoLeader = errors.New("no leader")
	// ErrAlreadyBootstrapped is returned when the Raft node is already bootstrapped.
	ErrAlreadyBootstrapped = transport.ErrAlreadyBootstrapped
	// ErrNotLeader is returned when the Raft node is not the leader.
	ErrNotLeader = raft.ErrNotLeader
	// ErrNotVoter is returned when the Raft node is not a voter.
	ErrNotVoter = raft.ErrNotVoter
)

var DefaultDataDir = func() string {
	if runtime.GOOS == "windows" {
		return "C:\\ProgramData\\webmesh\\store"
	}
	return "/var/lib/webmesh/store"
}()

DefaultDataDir is the default data directory.

var ErrNotRaftMember = errors.New("not a raft member")

ErrNotRaftMember is returned for methods that are only valid on raft members.

Types

type BootstrapCallback

type BootstrapCallback func(isLeader bool) error

BootstrapCallback is a callback for when the cluster is bootstrapped. The isLeader flag is set to true if the node is the leader, and false otherwise.

type LeaderObservation

type LeaderObservation = raft.LeaderObservation

LeaderObservation is an alias for raft.LeaderObservation.

type MonotonicLogStore

type MonotonicLogStore struct {
	raft.LogStore
}

MonotonicLogStore is a LogStore that is monotonic.

func (*MonotonicLogStore) IsMonotonic

func (m *MonotonicLogStore) IsMonotonic() bool

IsMonotonic returns true if the log store is monotonic.

type Observation

type Observation = raft.Observation

Observation is an alias for raft.Observation.

type ObservationCallback

type ObservationCallback func(ctx context.Context, obs Observation)

ObservationCallback is a callback that can be registered for when an observation is received.

type Options

type Options struct {
	// NodeID is the node ID.
	NodeID string
	// DataDir is the directory to store data in.
	DataDir string
	// InMemory is if the store should be in memory. This should only be used for testing and ephemeral nodes.
	InMemory bool
	// ConnectionPoolCount is the number of connections to pool. If 0, no connection pooling is used.
	ConnectionPoolCount int
	// ConnectionTimeout is the timeout for connections.
	ConnectionTimeout time.Duration
	// HeartbeatTimeout is the timeout for heartbeats.
	HeartbeatTimeout time.Duration
	// ElectionTimeout is the timeout for elections.
	ElectionTimeout time.Duration
	// ApplyTimeout is the timeout for applying.
	ApplyTimeout time.Duration
	// CommitTimeout is the timeout for committing.
	CommitTimeout time.Duration
	// MaxAppendEntries is the maximum number of append entries.
	MaxAppendEntries int
	// LeaderLeaseTimeout is the timeout for leader leases.
	LeaderLeaseTimeout time.Duration
	// SnapshotInterval is the interval to take snapshots.
	SnapshotInterval time.Duration
	// SnapshotThreshold is the threshold to take snapshots.
	SnapshotThreshold uint64
	// SnapshotRetention is the number of snapshots to retain.
	SnapshotRetention uint64
	// ObserverChanBuffer is the buffer size for the observer channel.
	ObserverChanBuffer int
	// LogLevel is the log level for the raft backend.
	LogLevel string
}

Options are the raft options.

func NewOptions

func NewOptions(nodeID string) Options

NewOptions returns new raft options with sensible defaults.

func (*Options) RaftConfig

func (o *Options) RaftConfig(ctx context.Context, nodeID string) *raft.Config

RaftConfig builds a raft config.

type PeerObservation

type PeerObservation = raft.PeerObservation

PeerObservation is an alias for raft.PeerObservation.

type Raft

type Raft interface {
	// OnApply registers a callback for when a log is applied to the state machine.
	OnApply(cb fsm.ApplyCallback)
	// OnSnapshotRestore registers a callback for when a snapshot is restored.
	OnSnapshotRestore(cb SnapshotRestoreCallback)
	// OnObservation registers a callback for when an observation is received.
	OnObservation(cb ObservationCallback)
	// Start starts the Raft node.
	Start(ctx context.Context, opts StartOptions) error
	// ID returns the node ID.
	ID() string
	// Bootstrap attempts to bootstrap the Raft cluster. If the cluster is already
	// bootstrapped, ErrAlreadyBootstrapped is returned.
	Bootstrap(ctx context.Context) error
	// Storage returns the storage. This is only valid after Start is called.
	Storage() storage.MeshStorage
	// Configuration returns the current raft configuration.
	Configuration() (raft.Configuration, error)
	// LastIndex returns the last index sent to the Raft instance.
	LastIndex() uint64
	// LastAppliedIndex returns the last applied index.
	LastAppliedIndex() uint64
	// ListenPort returns the listen port.
	ListenPort() uint16
	// LeaderID returns the leader ID.
	LeaderID() (string, error)
	// IsLeader returns true if the Raft node is the leader.
	IsLeader() bool
	// IsVoter returns true if the Raft node is a voter.
	IsVoter() bool
	// IsObserver returns true if the Raft node is an observer.
	IsObserver() bool
	// IsMember is a convenience method that returns true if the Raft node is a voter or observer.
	IsMember() bool
	// AddNonVoter adds a non-voting node to the cluster with timeout enforced by the context.
	AddNonVoter(ctx context.Context, id string, addr string) error
	// AddVoter adds a voting node to the cluster with timeout enforced by the context.
	AddVoter(ctx context.Context, id string, addr string) error
	// DemoteVoter demotes a voting node to a non-voting node with timeout enforced by the context.
	DemoteVoter(ctx context.Context, id string) error
	// RemoveServer removes a peer from the cluster with timeout enforced by the context.
	RemoveServer(ctx context.Context, id string, wait bool) error
	// Apply applies a raft log entry.
	Apply(ctx context.Context, log *v1.RaftLogEntry) (*v1.RaftApplyResponse, error)
	// Snapshot requests a raft snapshot. It returns a reader containing the contents
	// and metadata about the snapshot.
	Snapshot() (*raft.SnapshotMeta, io.ReadCloser, error)
	// Barrier issues a barrier request to the cluster. This is a no-op if the node is not the leader.
	Barrier(ctx context.Context, timeout time.Duration) (took time.Duration, err error)
	// Stop stops the Raft node.
	Stop(ctx context.Context) error
}

Raft is the interface for Raft consensus and storage.

func New

func New(ctx context.Context, opts Options) Raft

New returns a new Raft node.

func NewPassthrough

func NewPassthrough(ctx context.Context, nodeID string, dialer transport.NodeDialer) Raft

NewPassthrough creates a new raft instance that is a no-op for most methods and uses the given Dialer for storage connections.

type SnapshotMeta

type SnapshotMeta = raft.SnapshotMeta

SnapshotMeta is an alias for raft.SnapshotMeta.

type SnapshotRestoreCallback

type SnapshotRestoreCallback func(ctx context.Context, meta *raft.SnapshotMeta, data io.ReadCloser)

SnapshotRestoreCallback is a callback that can be registered for when a snapshot is restored.

type StartOptions

type StartOptions struct {
	// Transport is the Raft transport.
	Transport transport.RaftTransport
	// MeshStorage is the mesh storage.
	MeshStorage storage.MeshStorage
	// RaftStorage is the Raft storage.
	RaftStorage storage.RaftStorage
}

StartOptons are options for starting a Raft node.