raft

Documentation

Overview

Package raft provides raft coordination.

Index

• Variables
• type Service
  • func Start(laddr, dir string, httpClient *http.Client, state State) (*Service, error)
  • func (sv *Service) Err() error
  • func (sv *Service) Evict(ctx context.Context, nodeAddr string) error
  • func (sv *Service) Exec(ctx context.Context, instruction []byte) (satisfied bool, err error)
  • func (sv *Service) Init() error
  • func (sv *Service) Join(bootURL string) error
  • func (sv *Service) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (sv *Service) Stop() error
  • func (sv *Service) WaitRead(ctx context.Context) error
• type State

Variables

var (
	// ErrExistingCluster is returned from Init or Join when the Service
	// is already connected to a raft cluster.
	ErrExistingCluster = errors.New("already connected to a raft cluster")

	// ErrUninitialized is returned when the Service is not yet connected
	// to any cluster.
	ErrUninitialized = errors.New("no raft cluster configured")

	// ErrAddressNotAllowed is returned from Join when the node's address
	// is not in the provided cluster's allowed address list.
	ErrAddressNotAllowed = errors.New("address is not allowed")

	// ErrPeerUninitialized is returned when a peer node indicates it's
	// not yet initialized.
	ErrPeerUninitialized = errors.New("peer is uninitialized")

	// ErrUnknownPeer is returned when the specified peer doesn't exist.
	ErrUnknownPeer = errors.New("unknown peer")
)

Types

type Service

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

Service performs raft coordination.

func Start

func Start(laddr, dir string, httpClient *http.Client, state State) (*Service, error)

Start starts the raft algorithm.

Param laddr is the local address, to be used by peers to send messages to the local node. The returned *Service handles HTTP requests matching the ServeMux pattern /raft/. The caller is responsible for registering this handler to receive incoming requests on laddr. For example:

rs, err := raft.Start(addr, ...)
...
http.Handle("/raft/", rs)
http.ListenAndServe(addr, nil)

Param dir is the filesystem location for all persistent storage for this raft node. If dir exists and is populated, the returned Service will be immediately ready for use. It has three entries:

id    file containing the node's member id (never changes)
snap  file containing the last complete state snapshot
wal   dir containing the write-ahead log

If dir doesn't exist or is empty, the caller must configure the Service before using it by either calling Init to initialize a new raft cluster or Join to join an existing raft cluster.

The returned *Service will use httpClient for outbound connections to peers.

func (*Service) Err

func (sv *Service) Err() error

Err returns a serious error preventing this process from operating normally or making progress, if any. Note that it is possible for a Service to recover automatically from some errors returned by Err.

func (*Service) Evict

func (sv *Service) Evict(ctx context.Context, nodeAddr string) error

Evict removes the node with the provided address from the raft cluster. It does not modify the allowed member list.

func (*Service) Exec

func (sv *Service) Exec(ctx context.Context, instruction []byte) (satisfied bool, err error)

Exec proposes the provided instruction and waits for it to be satisfied.

func (*Service) Init

func (sv *Service) Init() error

Init initializes a new Raft cluster.

func (*Service) Join

func (sv *Service) Join(bootURL string) error

Join connects to an existing Raft cluster. bootURL gives the location of an existing cluster for the local process to join. It can be either the concrete address of any single cluster member or it can point to a load balancer for the whole cluster, if one exists.

func (*Service) ServeHTTP

func (sv *Service) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP responds to raft consensus messages at /raft/x, where x is any raft internode RPC. When sv sends outgoing messages, it acts as an HTTP client and sends requests to its peers at /raft/x.

func (*Service) Stop

func (sv *Service) Stop() error

Stop stops the Raft algorithm, stopping log replication. Once a Service has been stopped, it's unusable. Stop must be called at most once.

func (*Service) WaitRead

func (sv *Service) WaitRead(ctx context.Context) error

WaitRead waits for a linearizable read. Upon successful return, subsequent reads will observe all writes that happened before the call to WaitRead. (There is still no guarantee an intervening Set won't have changed the value again, but it is guaranteed not to read stale data.)

type State

type State interface {
	AppliedIndex() uint64
	Apply(data []byte, index uint64) (satisfied bool)
	Snapshot() (data []byte, index uint64, err error)
	RestoreSnapshot(data []byte, index uint64) error
	SetAppliedIndex(index uint64)
	Peers() map[uint64]string
	SetPeerAddr(id uint64, addr string)
	RemovePeerAddr(id uint64)
	IsAllowedMember(addr string) bool
	NextNodeID() (id, version uint64)
	EmptyWrite() (instruction []byte)
	WriteFile(name string, data []byte, perm os.FileMode) error
	IncrementNextNodeID(oldID uint64, index uint64) (instruction []byte)
}

State provides access to the actual replicated data set. It must be safe for concurrent access.