blob: 89c7ad0a4b59afccb837e894df17bfcd8d801323 [file] [log] [blame]
// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
package raft
// This vdl defines the interface between raft members and not the library interface to raft.
// Every log entry is represented by a Term and an Index.
// Term is a counter incremented each time a member starts an election. The log will
// show gaps in Term numbers because all elections need not be successful.
type Term uint64
// Index is an index into the log. The log entries are numbered sequentially. At the moment
// the entries RaftClient.Apply()ed should be sequential but that will change if we introduce
// system entries. For example, we could have an entry type that is used to add members to the
// set of replicas.
type Index uint64
// LogEntry types.
const (
ClientEntry = byte(0)
RaftEntry = byte(1)
)
// The LogEntry is what the log consists of. 'error' starts nil and is never written to stable
// storage. It represents the result of RaftClient.Apply(Cmd, Index). This is a hack but I
// haven't figured out a better way.
type LogEntry struct {
Term Term
Index Index
Cmd []byte
Type byte
}
// raftProto is used by the members of a raft set to communicate with each other.
type raftProto interface {
// Members returns the current set of ids of raft members.
Members() ([]string | error)
// Leader returns the id of the current leader.
Leader() (string | error)
// RequestVote starts a new round of voting. It returns the server's current Term and true if
// the server voted for the client.
RequestVote(term Term, candidateId string, lastLogTerm Term, lastLogIndex Index) (Term Term, Granted bool | error)
// AppendToLog is sent by the leader to tell followers to append an entry. If cmds
// is empty, this is a keep alive message (at a random interval after a keep alive, followers
// will initiate a new round of voting).
// term -- the current term of the sender
// leaderId -- the id of the sender
// prevIndex -- the index of the log entry immediately preceding cmds
// prevTerm -- the term of the log entry immediately preceding cmds. The receiver must have
// received the previous index'd entry and it must have had the same term. Otherwise
// an error is returned.
// leaderCommit -- the index of the last committed entry, i.e., the one a quorum has gauranteed
// to have logged.
// cmds -- sequential log entries starting at prevIndex+1
AppendToLog(term Term, leaderId string, prevIndex Index, prevTerm Term, leaderCommit Index, cmds []LogEntry) error
// Append is sent to the leader by followers. Only the leader is allowed to send AppendToLog.
// If a follower receives an Append() call it performs an Append() to the leader to run the actual
// Raft algorithm. The leader will respond after it has RaftClient.Apply()ed the command.
//
// Returns the term and index of the append entry or an error.
Append(cmd []byte) (term Term, index Index | error)
// Committed returns the commit index of the leader.
Committed() (index Index | error)
// InstallSnapshot is sent from the leader to follower to install the given snapshot. It is
// sent when it becomes apparent that the leader does not have log entries needed by the follower
// to progress. 'term' and 'index' represent the last LogEntry RaftClient.Apply()ed to the
// snapshot.
InstallSnapshot(term Term, leaderId string, appliedTerm Term, appliedIndex Index) stream<[]byte> error
}