ai.eloquent.raft

Interface RaftAlgorithm

All Known Implementing Classes:

EloquentRaftAlgorithm, SingleThreadedRaftAlgorithm

public interface RaftAlgorithm

A simple little interface for receiving Raft RPC messages. This is also, in effect, the implementation of the Raft protocol.

Field Summary

Fields

Modifier and Type	Field and Description
static Span	DEFAULT_ELECTION_RANGE The default timeout range for elections.
static org.slf4j.Logger	log An SLF4J Logger for this class.
static java.lang.Object	summaryTiming Timing statistics for Raft.

Method Summary

Modifier and Type	Method and Description
boolean	bootstrap(boolean force) Mark this node for bootstrapping.
void	broadcastAppendEntries(long now) Send out an append entries RPC (i.e., a heartbeat) to all listeners on the transport.
default Span	electionTimeoutMillisRange() The election timeout.
RaftTransport	getTransport() This gets the RaftTransport associated with this RaftAlgorithm.
void	heartbeat(long now) A method to be called on every heartbeat interval.
default long	heartbeatMillis() The interval between heartbeats for this particular Raft node / implementation.
boolean	isRunning() Check if the algorithm has already been stopped via stop(boolean).
java.util.Optional<RaftLifecycle>	lifecycle() Get the RaftLifecycle object that this Algorithm is registered for.
RaftState	mutableState() DANGEROUS: USE ONLY IF YOU KNOW WHAT YOU ARE DOING get A REFERENCE TO the current Raft state.
RaftStateMachine	mutableStateMachine() DANGEROUS: USE ONLY IF YOU KNOW WHAT YOU ARE DOING get A REFERENCE TO the current Raft state machine.
java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage>	receiveAddServerRPC(EloquentRaftProto.AddServerRequest addServerRequest, long now) A request has been received to add a server to the cluster.
void	receiveAppendEntriesReply(EloquentRaftProto.AppendEntriesReply reply, long now) We received an asynchronous heartbeat from a server.
void	receiveAppendEntriesRPC(EloquentRaftProto.AppendEntriesRequest heartbeat, java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader, long now) Receive a request to apply a transition or multiple transitions.
java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage>	receiveApplyTransitionRPC(EloquentRaftProto.ApplyTransitionRequest transition, long now) Apply a transition to Raft.
void	receiveBadRequest(EloquentRaftProto.RaftMessage message) A bad RPC call was received.
void	receiveInstallSnapshotReply(EloquentRaftProto.InstallSnapshotReply reply, long now) We received an asynchronous snapshot reply from a server.
void	receiveInstallSnapshotRPC(EloquentRaftProto.InstallSnapshotRequest snapshot, java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader, long now) Receive a snapshot request RPC call.
default void	receiveMessage(EloquentRaftProto.RaftMessage messageProto, java.util.function.Consumer<EloquentRaftProto.RaftMessage> replySender, long now) Receive a non-blocking RPC in the form of a EloquentRaftProto.RaftMessage proto.
java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage>	receiveRemoveServerRPC(EloquentRaftProto.RemoveServerRequest removeServerRequest, long now) A request has been received to remove a server to the cluster.
void	receiveRequestVoteRPC(EloquentRaftProto.RequestVoteRequest voteRequest, java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader, long now) Clearly an election has been initiated, and some candidate is requesting votes to become the new leader.
void	receiveRequestVotesReply(EloquentRaftProto.RequestVoteReply reply, long now) We received votes from another server.
default java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage>	receiveRPC(EloquentRaftProto.RaftMessage messageProto, long now) Receive a blocking RPC in the form of a EloquentRaftProto.RaftMessage proto.
void	sendAppendEntries(java.lang.String target, long nextIndex) Send an append entries request to a particular server.
java.lang.String	serverName() The name of this server.
static void	shutdown(RaftAlgorithm raft, RaftTransport transport, boolean allowClusterDeath) Shutdown the argument Raft algorithm, using the time given in the argument transport.
RaftState	state() get A COPY OF the current Raft state.
default void	stop(boolean kill) A method, called primarily from unit tests, to stop this algorithm and clean up the underlying transport, if appropriate.
long	term() The term this node sees.
void	triggerElection(long now) Signal to the cluster that we are a candidate for an election, and we are soliciting votes

Field Detail

log

static final org.slf4j.Logger log

An SLF4J Logger for this class.

summaryTiming

static final java.lang.Object summaryTiming

Timing statistics for Raft.

DEFAULT_ELECTION_RANGE

static final Span DEFAULT_ELECTION_RANGE

The default timeout range for elections.

Method Detail

receiveMessage

default void receiveMessage(EloquentRaftProto.RaftMessage messageProto,
                            java.util.function.Consumer<EloquentRaftProto.RaftMessage> replySender,
                            long now)

Receive a non-blocking RPC in the form of a EloquentRaftProto.RaftMessage proto.

Parameters:

messageProto - The EloquentRaftProto.RaftMessage we have received.

replySender - A callback for sending a message to the sender on the underlying transport.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveRPC

default java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage> receiveRPC(EloquentRaftProto.RaftMessage messageProto,
                                                                                         long now)

Receive a blocking RPC in the form of a EloquentRaftProto.RaftMessage proto. This function will return a CompletableFuture that is completed when the RPC completes.

Parameters:

messageProto - The EloquentRaftProto.RaftMessage we have received.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

Returns:

A CompletableFuture that completes when the RPC completes.

state

RaftState state()

get A COPY OF the current Raft state.

mutableState

RaftState mutableState()

DANGEROUS: USE ONLY IF YOU KNOW WHAT YOU ARE DOING get A REFERENCE TO the current Raft state.

mutableStateMachine

RaftStateMachine mutableStateMachine()

DANGEROUS: USE ONLY IF YOU KNOW WHAT YOU ARE DOING get A REFERENCE TO the current Raft state machine.

term

long term()

The term this node sees. This should simply return RaftState.currentTerm

serverName

java.lang.String serverName()

The name of this server. This should simply return RaftState.serverName

broadcastAppendEntries

void broadcastAppendEntries(long now)

Send out an append entries RPC (i.e., a heartbeat) to all listeners on the transport.

Parameters:

now - The current time. This is usually System.currentTimeMillis(), but can be mocked by unit tests.

sendAppendEntries

void sendAppendEntries(java.lang.String target,
                       long nextIndex)

Send an append entries request to a particular server.

Parameters:

target - The server we're sending the append entries RPC to.

nextIndex - The nextIndex value on the target machine.

receiveAppendEntriesRPC

void receiveAppendEntriesRPC(EloquentRaftProto.AppendEntriesRequest heartbeat,
                             java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader,
                             long now)

Receive a request to apply a transition or multiple transitions. This also doubles as the heartbeat for the server. There are three cases here:

1. If the node is an Oligarch: The node should respond to the heartbeat.
2. If the node is a Shadow and the Oligarchy is full: The node should apply the transition and not reply.
3. If the node is a Shadow and the Oligarchy is not full: The node should apply the transition and respond to the heartbeat.

Parameters:

heartbeat - The request body, doubling both as a heartbeat and a request to mutate the state machine.

replyLeader - The method for replying to the leader with an ACK of the request.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveAppendEntriesReply

void receiveAppendEntriesReply(EloquentRaftProto.AppendEntriesReply reply,
                               long now)

We received an asynchronous heartbeat from a server. This function is called to handle that heartbeat reply.

Parameters:

reply - The heartbeat ACK from the follower node.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveInstallSnapshotRPC

void receiveInstallSnapshotRPC(EloquentRaftProto.InstallSnapshotRequest snapshot,
                               java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader,
                               long now)

Receive a snapshot request RPC call. This should install a snapshot, and does not have to issue a response.

Parameters:

snapshot - The snapshot to install.

replyLeader - The method for replying to the leader with an ACK of the request.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveInstallSnapshotReply

void receiveInstallSnapshotReply(EloquentRaftProto.InstallSnapshotReply reply,
                                 long now)

We received an asynchronous snapshot reply from a server.

Parameters:

reply - The snapshot reply from the follower node.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

triggerElection

void triggerElection(long now)

Signal to the cluster that we are a candidate for an election, and we are soliciting votes

receiveRequestVoteRPC

void receiveRequestVoteRPC(EloquentRaftProto.RequestVoteRequest voteRequest,
                           java.util.function.Consumer<EloquentRaftProto.RaftMessage> replyLeader,
                           long now)

Clearly an election has been initiated, and some candidate is requesting votes to become the new leader. This must be responded to both by Oligarch and Shadow nodes.

Parameters:

voteRequest - The request for votes for a particular server.

replyLeader - The method for replying to the leader with an ACK of the request.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveRequestVotesReply

void receiveRequestVotesReply(EloquentRaftProto.RequestVoteReply reply,
                              long now)

We received votes from another server.

Parameters:

reply - The vote from the server, which we should count to see if we have a majority.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

receiveAddServerRPC

java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage> receiveAddServerRPC(EloquentRaftProto.AddServerRequest addServerRequest,
                                                                                          long now)

A request has been received to add a server to the cluster. This is only well-defined for the leader -- if the request was not received by the leader, then it should forward to the leader.

The algorithm for this is the following:

1. Reply NOT_LEADER if not leader (in practice, we forward it to the leader).
2. Catch up server for a fixed number of rounds. Reply TIMEOUT if a server does not make progress for an election timeout or if the last round takes longer than the election timeout.
3. Wait until previous configuration in log is committed.
4. Append a new configuration entry to the log, (old configuration plus new server), commit it using a majority of the new configuration.
5. Reply OK.

Parameters:

addServerRequest - The request to add the server.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

Returns:

the RPC response, as a future.

receiveRemoveServerRPC

java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage> receiveRemoveServerRPC(EloquentRaftProto.RemoveServerRequest removeServerRequest,
                                                                                             long now)

A request has been received to remove a server to the cluster. This is only well-defined for the leader -- if the request was not received by the leader, then it should forward to the leader.

Parameters:

removeServerRequest - The snapshot to install.

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

Returns:

the RPC response, as a future.

receiveApplyTransitionRPC

java.util.concurrent.CompletableFuture<EloquentRaftProto.RaftMessage> receiveApplyTransitionRPC(EloquentRaftProto.ApplyTransitionRequest transition,
                                                                                                long now)

Apply a transition to Raft.

Parameters:

transition - The transition to apply

now - The timestamp of the current time. In non-mock cases, this is always System.currentTimeMillis().

bootstrap

boolean bootstrap(boolean force)

Mark this node for bootstrapping. This should just be an alias for RaftState.bootstrap(boolean), with some error checks beforehand. If this node cannot bootstrap, we return false.

Returns:

True if we could bootstrap this node.

stop

default void stop(boolean kill)

A method, called primarily from unit tests, to stop this algorithm and clean up the underlying transport, if appropriate. An empty implementation is OK if there's nothing to stop.

Parameters:

kill - If true, kill the server unceremoniously, without waiting for a handoff.

isRunning

boolean isRunning()

Check if the algorithm has already been stopped via stop(boolean).

heartbeatMillis

default long heartbeatMillis()

The interval between heartbeats for this particular Raft node / implementation. This should be substantially shorter than electionTimeoutMillisRange()

electionTimeoutMillisRange

default Span electionTimeoutMillisRange()

The election timeout. This should be substantially longer than heartbeatMillis()

heartbeat

void heartbeat(long now)

A method to be called on every heartbeat interval. If we're the leader, this sends out heartbeats. If we're a follower, this ensures that we can trigger the appropriate timeout events.

receiveBadRequest

void receiveBadRequest(EloquentRaftProto.RaftMessage message)

A bad RPC call was received. Signal the error appropriately. This can happen for two reasons:

1. The RPC type is not supported.
2. The proto of the RPC was poorly formatted.

Parameters:

message - The raw message received.

lifecycle

java.util.Optional<RaftLifecycle> lifecycle()

Get the RaftLifecycle object that this Algorithm is registered for.

getTransport

RaftTransport getTransport()

This gets the RaftTransport associated with this RaftAlgorithm.

shutdown

static void shutdown(RaftAlgorithm raft,
                     RaftTransport transport,
                     boolean allowClusterDeath)

Shutdown the argument Raft algorithm, using the time given in the argument transport.

Parameters:

raft - The implementing Raft algorithm.

transport - The transport to run timing on, where necessary.

allowClusterDeath - If true, allow the cluster to lose state and completely shut down. Otherwise, we wait for another live node to show up before shutting down (the default).