raft-grpc.proto

syntax = "proto3";
package raftgrpc;

// LogEntryType is the type of the LogEntry
enum LogEntryType {
  LOG_ENTRY_COMMAND = 0;
  LOG_ENTRY_NOOP = 1;
  LOG_ENTRY_ADD_PEER_DEPRECATED = 2;
  LOG_ENTRY_REMOVE_PEER_DEPRECATED = 3;
  LOG_ENTRY_BARRIER = 4;
  LOG_ENTRY_CONFIGURATION = 5;
}

// RaftHeader describes information contained in every RPC command + response.
message RaftHeader {
  int32 protocol_version = 1;
}

// LogEntry contains a raft log entry.
message LogEntry {
  // Index holds the index of the log entry.
  uint64 index = 1;
  // Term holds the election term of the log entry.
  uint64 term = 2;
  // Type holds the type of the log entry.
  LogEntryType type = 3;
  // Data holds the log entry's type-specific data.
  bytes data = 4;
  // Extensions holds an opaque byte slice of information for middleware.
  bytes extensions = 5;
}

// PeerNameContainer encodes a peer name to bytes.
message PeerNameContainer {
  // PeerName is the peer name in the container.
  string peer_name = 1;
}

// AppendEntriesRequest maps to the raft AppendEntriesRequest.
message AppendEntriesRequest {
  // Term is the current election term.
  uint64 term = 1;
  // Leader is the current leader id.
  bytes leader = 2;
  // PrevLogEntry is the previous log entry.
  uint64 prev_log_entry = 3;
  // PrevLogTerm is the previous log term.
  uint64 prev_log_term = 4;
  // Entries are the new log entries to commit.
  repeated LogEntry entries = 5;
  // LeaderCommitIndex is the commit index on the leader.
  uint64 leader_commit_index = 6;

  RaftHeader raft_header = 99;
}

// AppendEntriesResponse is the response to the appendentries request.
message AppendEntriesResponse {
  // Term is the newer term if the leader is out of date.
  uint64 term = 1;
  // LastLog is a hint to help accelerate rebuilding slow nodes.
  uint64 last_log = 2;
  // Success will be false if we have a conflicting entry.
  bool success = 3;
  // NoRetryBackoff indicates we don't need to backoff the next attempt.
  bool no_retry_backoff = 4;

  RaftHeader raft_header = 99;
}

// RequestVoteRequest is the command used by a candidate to ask a Raft peer for a vote in an election.
message RequestVoteRequest {
  // Term is the new voting term.
  uint64 term = 1;
  // Candidate is the candidate id
  bytes candidate = 2;
  // LastLogIndex is the last log index.
  uint64 last_log_index = 3;
  // LastLogTerm is the last log term.
  uint64 last_log_term = 4;
  // LeadershipTransfer indicates to peers if the vote was triggered by
  // a leadership transfer.
  bool leadership_transfer = 5;

  RaftHeader raft_header = 99;
}

// RequestVoteResponse is the response returned from a RequestVoteRequest.
message RequestVoteResponse {
  // Term is the newer term if the lader is out of date.
  uint64 term = 1;
  // Peers contains the current peers list so a node can shutdown on removal.
  bytes peers = 2;
  // Granted if the vote was granted.
  bool granted = 3;

  RaftHeader raft_header = 99;
}

// InstallSnapshotStream encodes information used when transmitting a snapshot.
message InstallSnapshotStream {
  oneof payload {
    InstallSnapshotRequest request = 1;
    bytes data = 2;
  };
}

// InstallSnapshotRequest is the command sent to a Raft peer to bootstrap its log (and state machine) from a snapshot on another peer.
message InstallSnapshotRequest {
  // Term is the current term.
  uint64 term = 1;
  // Leader is the current leader.
  bytes leader = 2;
  // LastLogIndex is the last log index included in the snapshot.
  uint64 last_log_index = 3;
  // LastLogTerm is the last log term included in the snapshot.
  uint64 last_log_term = 4;
  // Peers is the peer set in the snapshot
  bytes peers = 5;
  // Configuration stores the cluster membership information.
  bytes configuration = 6;
  // ConfigurationIdx is the log index where configuration was originally committed.
  uint64 config_idx = 7;
  // Size is the size of the snapshot.
  int64 size = 8;

  RaftHeader raft_header = 99;
}

// InstallSnapshotResponse is the response to the InstallSnapshot call.
message InstallSnapshotResponse {
  // Term is the term in the snapshot.
  uint64 term = 1;
  // Success indiciates if the snapshot was installed properly.
  bool success = 2;

  RaftHeader raft_header = 99;
}

// AppendEntriesPipelineResponse is the wrapper of an AppendEntriesResponse in a pipeline.
message AppendEntriesPipelineResponse {
  // Error is any potential error.
  string error = 1;
  // Response is the response object if necessary
  AppendEntriesResponse response = 2;
}

// TimeoutNowRequest is the command used by a leader to signal another server to start an election.
message TimeoutNowRequest {
  RaftHeader raft_header = 99;
}

// TimeoutNowResponse is the response to TimeoutNowRequest.
message TimeoutNowResponse {
  RaftHeader raft_header = 99;
}

// RaftService implements the raft pipelining receiver.
service RaftService {
  // AppendEntriesPipeline opens an AppendEntries message stream.
  rpc AppendEntriesPipeline(stream AppendEntriesRequest) returns (stream AppendEntriesPipelineResponse) {}
  // AppendEntries performs a single append entries request / response.
  rpc AppendEntries(AppendEntriesRequest) returns (AppendEntriesResponse) {}
  // RequestVote is the command used by a candidate to ask a Raft peer for a vote in an election.
  rpc RequestVote(RequestVoteRequest) returns (RequestVoteResponse) {}
  // InstallSnapshot is the command sent to a Raft peer to bootstrap its log (and state machine) from a snapshot on another peer.
  rpc InstallSnapshot(stream InstallSnapshotStream) returns (InstallSnapshotResponse) {}
  // TimeoutNow is used to start a leadership transfer to the target node.
  rpc TimeoutNow(TimeoutNowRequest) returns (TimeoutNowResponse) {}
}