Categorygithub.com/dgate-io/raft
modulepackage
0.2.8
Repository: https://github.com/dgate-io/raft.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
32
Dependents
0
Files
4.6k SLOC

# README

raft

build Go Reference GitHub GitHub go.mod Go version (subdirectory of monorepo)

Raft

This package provides a simple, easy-to-understand, and reliable implementation of Raft using Go. Raft is a consensus protocol designed to manage replicated logs in a distributed system. Its purpose is to ensure fault-tolerant coordination and consistency among a group of nodes, making it suitable for building reliable systems. Potential use cases include distributed file systems, consistent key-value stores, and service discovery.

Features

The following features are currently supported:

  • Automated Snapshots
  • Concurrent Snapshot Transfer from Leader to Followers
  • Dynamic Membership Changes
  • Linearizable and Lease-Based Read-Only Operations
  • Prevote and Leader Stickyness

Protocol Overview

Raft is based on a leader-follower model, where one node is elected as the leader and coordinates the replication process. Time is divided into terms, and the leader is elected for each term through a leader election process. The leader receives client requests, which are then replicated to other nodes called followers. The followers maintain a log of all state changes, and the leader's responsibility is to ensure that all followers have consistent logs by sending them entries to append. Safety is guaranteed by requiring a majority of nodes to agree on the state changes, ensuring that no conflicting states are committed.

Installation and Usage

First, make sure you have Go 1.20 or a higher version installed on your system. You can download and install Go from the official Go website.

Then, install the raft package by running

go get -u github.com/dgate-io/raft

Once you have the package installed, you may refer to the raft package reference page for basic usage. An example of how to use raft as well as a set of Jepsen tests can be found here.

Contributing

Other developers are encouraged to contribute to this project and pull requests are welcome. Please read these guidelines if you are interested in contributing.

# Packages

No description provided by the author

# Functions

NewConfiguration creates a new configuration with the provided members and index.
NewLog creates a new Log instance.
NewLogEntry creates a new instance of a LogEntry with the provided index, term, data, and type.
NewRaft creates a new instance of Raft with the provided ID and address.
NewSnapshotStorage creates a new SnapshotStorage instance.
NewStateStorage creates a new instance of a StateStorage.
NewTransport creates a new Transport instance.
WithElectionTimeout sets the election timeout for raft.
WithHeartbeatInterval sets the heartbeat interval for raft.
WithLeaseDuration sets the duration for which a lease remains valid upon renewal.
WithLog sets the log that will be used by raft.
WithLogger sets the log level used by raft.
WithSnapshotStorage sets the snapshot storage that will be used by raft.
WithStateStorage sets the state storage that will be used by raft.
WithTransport sets the network transport that will be used by raft.

# Constants

Broadcasted indicates that the provided operation will be written to the log and broadcasted to all followers and guarantees linearizable semantics.
Candidate is a state indicating that this node is currently holding an election.
ConfigurationEntry are log entries which contain a cluster configuration.
Follower is a state indicating that a node is responsible for accepting log entries replicated by the leader.
Leader is a state indicating that the node is responsible for replicating and committing log entries.
LeaseBasedReadOnly indicates that the provided operation will not be written to the log and requires that the server verify its leadership via its lease.
LinearizableReadOnly indicates that the provided operation will not be written to the log and requires that the recieving server verify its leadership through a round of heartbeats to its peers.
NoOpEntry log entries are those that do not contain an operation.
OperationEntry log entries are those that do contain an operation that will be applied to the state machine.
PreCandidate is a state indicating this node is holding a prevote.
Replicated indicates that the provided operation will be written to the log and guarantees linearizable semantics.
Shutdown is a state indicating that the node is currently offline.

# Variables

ErrInvalidLease is returned when a lease-based read-only operation is rejected due to the leader's lease having expired.
ErrNoCommitThisTerm is returned when a membership change is requested but a log entry has yet to be committed in the current term.
ErrNotLeader is returned when an operation or configuration change is submitted to a node that is not a leader.
ErrPendingConfiguration is returned when a membership change is requested and there is a pending membership change that has not yet been committed.
ErrTimeout is returned when a future timed out waiting for a result.

# Structs

AppendEntriesRequest is a request invoked by the leader to replicate log entries and also serves as a heartbeat.
AppendEntriesResponse is a response to a request to to replicate log entries.
Configuration represents a cluster of nodes.
InstallSnapshotRequest is invoked by the leader to send a snapshot to a follower.
InstallSnapshotResponse is a response to a snapshot installation.
LogEntry is a log entry in the log.
Operation is an operation that will be applied to the state machine.
OperationResponse is the response that is generated after applying an operation to the state machine.
Raft implements the raft consensus protocol.
RequestVoteRequest is a request invoked by candidates to gather votes.
RequestVoteResponse is a response to a request for a vote.
SnapshotMetadata contains all metadata associated with a snapshot.
Status is the status of a node.

# Interfaces

Future represents an operation that will occur at a later point in time.
Log represents the internal component of Raft that is responsible for persistently storing and retrieving log entries.
Response is the concrete result produced by a node after processing a client submitted operation.
Result represents an abstract result produced by a node after processing a client submitted operation.
SnapshotFile represents a component for reading and writing snapshots.
SnapshotStorage represents the component of Raft that manages snapshots created by the state machine.
StateMachine is an interface representing a replicated state machine.
StateStorage represents the component of Raft responsible for persistently storing term and vote.
Transport represents the underlying transport mechanism used by a node in a cluster to send and receive RPCs.

# Type aliases

LogEntryType is the type of the log entry.
OperationType is the type of the operation that is being submitted to raft.
Option is a function that updates the options associated with Raft.
State represents the current state of a node.