ai.eloquent.raft

Class RaftState

java.lang.Object

ai.eloquent.raft.RaftState

public class RaftState
extends java.lang.Object

The state of a Raft node.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RaftState.LeadershipStatus The leadership status of the given Raft node.

Field Summary

Fields

Modifier and Type	Field and Description
java.util.Optional<java.util.Set<java.lang.String>>	alreadyKilled The set of servers that have timed out, but we have already removed their transient entries.
long	currentTerm Latest term server has seen (initialized to 0 on first boot, increases monotonically.
long	electionTimeoutCheckpoint The timestamp of the last message received by this node from the leader.
java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>>	lastMessageTimestamp The timestamp of the last message received from each of the servers.
java.util.Optional<java.lang.String>	leader The identity of the leader, if we know it.
RaftState.LeadershipStatus	leadership The leadership status of this node (leader / candidate / other)
RaftLog	log The Raft log.
java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>>	matchIndex For each server, the index of the highest log entry known to be replicated on server.
java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>>	nextIndex For each server, the index of the next log entry to send to that server (initialized to leader last log index + 1).
java.lang.String	serverName The name (i.e., id) of this server.
int	targetClusterSize ADDITION: the target size of the cluster, for auto-scaling.
java.util.Optional<java.lang.String>	votedFor candidateId that received vote in the current term (or null if none)
java.util.Set<java.lang.String>	votesReceived The timestamp of the last message received by this node from the leader.

Constructor Summary

Constructors

Constructor and Description
RaftState(java.lang.String serverName, RaftLog log)
RaftState(java.lang.String serverName, RaftLog log, int targetClusterSize) The straightforward constructor
RaftState(java.lang.String serverName, RaftStateMachine stateMachine, java.util.Collection<java.lang.String> clusterMembers, java.util.concurrent.ExecutorService pool) Create a new Raft state with the given cluster members.
RaftState(java.lang.String serverName, RaftStateMachine stateMachine, java.util.concurrent.ExecutorService pool) Create a new Raft state with only one node -- the given argument server name.
RaftState(java.lang.String serverName, RaftStateMachine stateMachine, int targetClusterSize, java.util.concurrent.ExecutorService pool) Create a new Raft state with the given target cluster size.

Method Summary

Modifier and Type	Method and Description
void	becomeCandidate() Trigger a new election, and become a candidate.
void	bootstrap()
void	bootstrap(boolean force) Bootstrap this cluster by adding this node to our own list of known nodes.
long	commitIndex() Index of the highest log entry know to be committed (initialized to 0, increases monotonically).
void	commitUpTo(long commitIndex, long now) Commit up until a given index (inclusive).
RaftState	copy() Create a copy of the Raft state at this moment in time.
void	elect(long now) Mark this state as a leader, setting the appropriate variables.
boolean	equals(java.lang.Object o)
int	hashCode()
boolean	isCandidate() If true, we are a candidate to become leader in an election.
boolean	isLeader() If true, we [think we] are the leader.
java.util.Set<java.lang.String>	killNodes(long now, long timeout) Get the set of dead nodes that we should clear transient entries for.
long	lastApplied() The index of the highest log entry applied to state machine (initialized to 0, increases monotonically).
void	observeLifeFrom(java.lang.String followerName, long now) Signal to the state that we have signs of life from a particular follower.
void	receiveVoteFrom(java.lang.String voter) Receive a vote from a particular server.
RaftLogEntryLocation	reconfigure(java.util.Collection<java.lang.String> quorum, boolean force, long now) This creates a new configuration log entry, and appends it.
RaftLogEntryLocation	reconfigure(java.util.Collection<java.lang.String> quorum, long now)
void	resetElectionTimeout(long now, java.util.Optional<java.lang.String> leader) Reset the election timeout.
void	resetElectionTimeout(long now, java.lang.String leader)
void	revive(java.lang.String node) If we could not kill the transient state on a node, we need to revive it with this function.
java.util.Optional<java.lang.String>	serverToAdd(long now, long maxLatency) Get the server to add to the cluster, if one should be added.
java.util.Optional<java.lang.String>	serverToRemove(long now, long timeout) Get the server to remove from the cluster, if one should be removed.
void	setCurrentTerm(long term) Set the current term for the state.
boolean	shouldTriggerElection(long now, Span electionTimeoutMillisRange) If true, we should trigger an election.
void	stepDownFromElection() Step down from an election -- become a simple follower.
RaftLogEntryLocation	transition(byte[] transition) Transition with only a regular transition, but no hospice member.
RaftLogEntryLocation	transition(java.util.Optional<byte[]> transition, java.util.Optional<java.lang.String> newHospiceMember) This creates a new transition log entry, and appends it.
void	voteFor(java.lang.String vote) Vote for a particular server as the leader.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

serverName

public final java.lang.String serverName

The name (i.e., id) of this server.

log

public final RaftLog log

The Raft log.

currentTerm

public long currentTerm

Latest term server has seen (initialized to 0 on first boot, increases monotonically.

votedFor

public java.util.Optional<java.lang.String> votedFor

candidateId that received vote in the current term (or null if none)

targetClusterSize

public final int targetClusterSize

ADDITION: the target size of the cluster, for auto-scaling. A value of -1 disables auto-scaling altogether.

leadership

public volatile RaftState.LeadershipStatus leadership

The leadership status of this node (leader / candidate / other)

electionTimeoutCheckpoint

public volatile long electionTimeoutCheckpoint

The timestamp of the last message received by this node from the leader. This is used to compute the election timeout.

leader

public volatile java.util.Optional<java.lang.String> leader

The identity of the leader, if we know it.

votesReceived

public volatile java.util.Set<java.lang.String> votesReceived

The timestamp of the last message received by this node from the leader. This is used to compute the election timeout.

nextIndex

public volatile java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>> nextIndex

For each server, the index of the next log entry to send to that server (initialized to leader last log index + 1).

matchIndex

public volatile java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>> matchIndex

For each server, the index of the highest log entry known to be replicated on server. (initialized to 0, increases monotonically).

lastMessageTimestamp

public volatile java.util.Optional<java.util.Map<java.lang.String,java.lang.Long>> lastMessageTimestamp

The timestamp of the last message received from each of the servers. This value should never be absent for any server -- we initialize it optimistically.

alreadyKilled

public volatile java.util.Optional<java.util.Set<java.lang.String>> alreadyKilled

The set of servers that have timed out, but we have already removed their transient entries. This prevents us spamming the |ClearTransient| transition.

Constructor Detail

RaftState

public RaftState(java.lang.String serverName,
                 RaftStateMachine stateMachine,
                 java.util.concurrent.ExecutorService pool)

Create a new Raft state with only one node -- the given argument server name.

RaftState

public RaftState(java.lang.String serverName,
                 RaftStateMachine stateMachine,
                 int targetClusterSize,
                 java.util.concurrent.ExecutorService pool)

Create a new Raft state with the given target cluster size. If this size is -1, this becomes a single-node Raft cluster with just this node. If this size is non-negative, it'll become a resizing cluster with the given number of target nodes.

RaftState

public RaftState(java.lang.String serverName,
                 RaftStateMachine stateMachine,
                 java.util.Collection<java.lang.String> clusterMembers,
                 java.util.concurrent.ExecutorService pool)

Create a new Raft state with the given cluster members. This cluster is non-resizing.

RaftState

public RaftState(java.lang.String serverName,
                 RaftLog log,
                 int targetClusterSize)

The straightforward constructor

RaftState

public RaftState(java.lang.String serverName,
                 RaftLog log)

Method Detail

lastApplied

public long lastApplied()

The index of the highest log entry applied to state machine (initialized to 0, increases monotonically). This is a computed value, but appears here with the variables because it is part of the core Raft spec as a variable.

copy

public RaftState copy()

Create a copy of the Raft state at this moment in time.

commitIndex

public long commitIndex()

Index of the highest log entry know to be committed (initialized to 0, increases monotonically).

bootstrap

public void bootstrap(boolean force)

Bootstrap this cluster by adding this node to our own list of known nodes. This is inherently an unsafe operation! You should only call this function on one node, or else we may have split-brain

bootstrap

public void bootstrap()

See Also:

bootstrap(boolean)

setCurrentTerm

public void setCurrentTerm(long term)

Set the current term for the state.

Parameters:

term - The new term.

See Also:

currentTerm

observeLifeFrom

public void observeLifeFrom(java.lang.String followerName,
                            long now)

Signal to the state that we have signs of life from a particular follower. This updates lastMessageTimestamp.

Parameters:

followerName - The name of the follower we observed life from.

now - The current time. This is useful to be explicit about for mocks.

isLeader

public boolean isLeader()

If true, we [think we] are the leader.

isCandidate

public boolean isCandidate()

If true, we are a candidate to become leader in an election.

elect

public void elect(long now)

Mark this state as a leader, setting the appropriate variables.

Parameters:

now - The current time, so we can initialize lastMessageTimestamp. This is mostly useful for mocks -- otherwise it should be System.currentTimeMillis().

stepDownFromElection

public void stepDownFromElection()

Step down from an election -- become a simple follower.

becomeCandidate

public void becomeCandidate()

Trigger a new election, and become a candidate.

resetElectionTimeout

public void resetElectionTimeout(long now,
                                 java.util.Optional<java.lang.String> leader)

Reset the election timeout. That is, register that we've either just started an election, or we've received a message from the leader that suggests that we don't need to start an election.

Parameters:

now - The current timestamp. Should be System.currentTimeMillis() unless we're in a mock

resetElectionTimeout

public void resetElectionTimeout(long now,
                                 java.lang.String leader)

See Also:

resetElectionTimeout(long, Optional)

shouldTriggerElection

public boolean shouldTriggerElection(long now,
                                     Span electionTimeoutMillisRange)

If true, we should trigger an election. If we have no timeout checkpoint, this starts the clock on the election timeout.

Parameters:

now - The current time, so that we can start the timer.

electionTimeoutMillisRange - The timeout before we should trigger an election, as a range. The chosen value in this range will be fixed for a given server + term.

Returns:

True if we should trigger an election.

voteFor

public void voteFor(java.lang.String vote)

Vote for a particular server as the leader.

Parameters:

vote - The server we voted for.

receiveVoteFrom

public void receiveVoteFrom(java.lang.String voter)

Receive a vote from a particular server. If we recieve a majority of the votes, then we are considered elected.

Parameters:

voter - The server that voted for us.

transition

public RaftLogEntryLocation transition(java.util.Optional<byte[]> transition,
                                       java.util.Optional<java.lang.String> newHospiceMember)

This creates a new transition log entry, and appends it. Must be the current LEADER, or will throw an assert.

Parameters:

transition - the transition we'd like to add to the log.

newHospiceMember - an optional new hospice member to add to the state machine.

Returns:

(term, index) of the new entry

transition

public RaftLogEntryLocation transition(byte[] transition)

Transition with only a regular transition, but no hospice member.

Parameters:

transition - The transition to implement.

Returns:

(term, index) of the new entry

commitUpTo

public void commitUpTo(long commitIndex,
                       long now)

Commit up until a given index (inclusive). Note that we can never commit backwards

Parameters:

commitIndex - The index to commit up to.

now - The current time.

reconfigure

public RaftLogEntryLocation reconfigure(java.util.Collection<java.lang.String> quorum,
                                        boolean force,
                                        long now)

This creates a new configuration log entry, and appends it. Must be the current LEADER, or will throw an assert.

Parameters:

quorum - the new quorum of nodes we'd like to have in the cluster.

force - force the new configuration, even through it's an error.

now - The current timestamp.

Returns:

(index, term) of the new entry

reconfigure

public RaftLogEntryLocation reconfigure(java.util.Collection<java.lang.String> quorum,
                                        long now)

See Also:

reconfigure(Collection, boolean, long)

serverToAdd

public java.util.Optional<java.lang.String> serverToAdd(long now,
                                                        long maxLatency)

Get the server to add to the cluster, if one should be added. If no server should (or is available to) be added, we return Optional.empty(). A server should be added if all of:

1. targetClusterSize is nonnegative, and
2. the current cluster size is less than targetClusterSize.
3. the new server is not delinquent (i.e., is not timed out)

Parameters:

now - The current time in millis. This should be a value relative to lastMessageTimestamp -- usually the time on the transport (itself usually machine-local time).

maxLatency - The maximum amount of time that we tolerate, in milliseconds, of the last heartbeat we received from the node we're adding.

Returns:

The server to add, or Optional.empty() if none should / can be added.

serverToRemove

public java.util.Optional<java.lang.String> serverToRemove(long now,
                                                           long timeout)

Get the server to remove from the cluster, if one should be removed. If no server should be removed, we return Optional.empty(). A server should be removed if both:

1. targetClusterSize is nonnegative, and
2. One of:
   1. The current cluster is larger than targetClusterSize, or
   2. There exists a server that has been down for longer than the given timeout

Parameters:

now - The current time in millis. This should be a value relative to lastMessageTimestamp -- usually the time on the transport (itself usually machine-local time).

timeout - The maximum amount of time, in milliseconds, to keep a node in the configuration before removing it from the cluster.

Returns:

The server to remove, or Optional.empty() if none should be removed.

killNodes

public java.util.Set<java.lang.String> killNodes(long now,
                                                 long timeout)

Get the set of dead nodes that we should clear transient entries for. This is only relevant for a KeyValueStateMachine where the notion of ownership exists.

Parameters:

now - The current time in millis. This should be a value relative to lastMessageTimestamp -- usually the time on the transport (itself usually machine-local time).

timeout - The maximum amount of time, in milliseconds, to keep a node "alive" before clearing it's transient state from the Raft state.

Returns:

The set of nodes to remove. After returned, they are marked as already killed.

revive

public void revive(java.lang.String node)

If we could not kill the transient state on a node, we need to revive it with this function.

Parameters:

node - The node we have revived.

See Also:

killNodes(long, long)

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object