// 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
}