1syntax = "proto2";
2package raftpb;
3
4import "gogoproto/gogo.proto";
5
6option (gogoproto.marshaler_all) = true;
7option (gogoproto.sizer_all) = true;
8option (gogoproto.unmarshaler_all) = true;
9option (gogoproto.goproto_getters_all) = false;
10option (gogoproto.goproto_enum_prefix_all) = false;
11option (gogoproto.goproto_unkeyed_all) = false;
12option (gogoproto.goproto_unrecognized_all) = false;
13option (gogoproto.goproto_sizecache_all) = false;
14
15enum EntryType {
16 EntryNormal = 0;
17 EntryConfChange = 1; // corresponds to pb.ConfChange
18 EntryConfChangeV2 = 2; // corresponds to pb.ConfChangeV2
19}
20
21message Entry {
22 optional uint64 Term = 2 [(gogoproto.nullable) = false]; // must be 64-bit aligned for atomic operations
23 optional uint64 Index = 3 [(gogoproto.nullable) = false]; // must be 64-bit aligned for atomic operations
24 optional EntryType Type = 1 [(gogoproto.nullable) = false];
25 optional bytes Data = 4;
26}
27
28message SnapshotMetadata {
29 optional ConfState conf_state = 1 [(gogoproto.nullable) = false];
30 optional uint64 index = 2 [(gogoproto.nullable) = false];
31 optional uint64 term = 3 [(gogoproto.nullable) = false];
32}
33
34message Snapshot {
35 optional bytes data = 1;
36 optional SnapshotMetadata metadata = 2 [(gogoproto.nullable) = false];
37}
38
39// For description of different message types, see:
40// https://pkg.go.dev/go.etcd.io/etcd/raft/v3#hdr-MessageType
41enum MessageType {
42 MsgHup = 0;
43 MsgBeat = 1;
44 MsgProp = 2;
45 MsgApp = 3;
46 MsgAppResp = 4;
47 MsgVote = 5;
48 MsgVoteResp = 6;
49 MsgSnap = 7;
50 MsgHeartbeat = 8;
51 MsgHeartbeatResp = 9;
52 MsgUnreachable = 10;
53 MsgSnapStatus = 11;
54 MsgCheckQuorum = 12;
55 MsgTransferLeader = 13;
56 MsgTimeoutNow = 14;
57 MsgReadIndex = 15;
58 MsgReadIndexResp = 16;
59 MsgPreVote = 17;
60 MsgPreVoteResp = 18;
61}
62
63message Message {
64 optional MessageType type = 1 [(gogoproto.nullable) = false];
65 optional uint64 to = 2 [(gogoproto.nullable) = false];
66 optional uint64 from = 3 [(gogoproto.nullable) = false];
67 optional uint64 term = 4 [(gogoproto.nullable) = false];
68 // logTerm is generally used for appending Raft logs to followers. For example,
69 // (type=MsgApp,index=100,logTerm=5) means leader appends entries starting at
70 // index=101, and the term of entry at index 100 is 5.
71 // (type=MsgAppResp,reject=true,index=100,logTerm=5) means follower rejects some
72 // entries from its leader as it already has an entry with term 5 at index 100.
73 optional uint64 logTerm = 5 [(gogoproto.nullable) = false];
74 optional uint64 index = 6 [(gogoproto.nullable) = false];
75 repeated Entry entries = 7 [(gogoproto.nullable) = false];
76 optional uint64 commit = 8 [(gogoproto.nullable) = false];
77 optional Snapshot snapshot = 9 [(gogoproto.nullable) = false];
78 optional bool reject = 10 [(gogoproto.nullable) = false];
79 optional uint64 rejectHint = 11 [(gogoproto.nullable) = false];
80 optional bytes context = 12;
81}
82
83message HardState {
84 optional uint64 term = 1 [(gogoproto.nullable) = false];
85 optional uint64 vote = 2 [(gogoproto.nullable) = false];
86 optional uint64 commit = 3 [(gogoproto.nullable) = false];
87}
88
89// ConfChangeTransition specifies the behavior of a configuration change with
90// respect to joint consensus.
91enum ConfChangeTransition {
92 // Automatically use the simple protocol if possible, otherwise fall back
93 // to ConfChangeJointImplicit. Most applications will want to use this.
94 ConfChangeTransitionAuto = 0;
95 // Use joint consensus unconditionally, and transition out of them
96 // automatically (by proposing a zero configuration change).
97 //
98 // This option is suitable for applications that want to minimize the time
99 // spent in the joint configuration and do not store the joint configuration
100 // in the state machine (outside of InitialState).
101 ConfChangeTransitionJointImplicit = 1;
102 // Use joint consensus and remain in the joint configuration until the
103 // application proposes a no-op configuration change. This is suitable for
104 // applications that want to explicitly control the transitions, for example
105 // to use a custom payload (via the Context field).
106 ConfChangeTransitionJointExplicit = 2;
107}
108
109message ConfState {
110 // The voters in the incoming config. (If the configuration is not joint,
111 // then the outgoing config is empty).
112 repeated uint64 voters = 1;
113 // The learners in the incoming config.
114 repeated uint64 learners = 2;
115 // The voters in the outgoing config.
116 repeated uint64 voters_outgoing = 3;
117 // The nodes that will become learners when the outgoing config is removed.
118 // These nodes are necessarily currently in nodes_joint (or they would have
119 // been added to the incoming config right away).
120 repeated uint64 learners_next = 4;
121 // If set, the config is joint and Raft will automatically transition into
122 // the final config (i.e. remove the outgoing config) when this is safe.
123 optional bool auto_leave = 5 [(gogoproto.nullable) = false];
124}
125
126enum ConfChangeType {
127 ConfChangeAddNode = 0;
128 ConfChangeRemoveNode = 1;
129 ConfChangeUpdateNode = 2;
130 ConfChangeAddLearnerNode = 3;
131}
132
133message ConfChange {
134 optional ConfChangeType type = 2 [(gogoproto.nullable) = false];
135 optional uint64 node_id = 3 [(gogoproto.nullable) = false, (gogoproto.customname) = "NodeID" ];
136 optional bytes context = 4;
137
138 // NB: this is used only by etcd to thread through a unique identifier.
139 // Ideally it should really use the Context instead. No counterpart to
140 // this field exists in ConfChangeV2.
141 optional uint64 id = 1 [(gogoproto.nullable) = false, (gogoproto.customname) = "ID" ];
142}
143
144// ConfChangeSingle is an individual configuration change operation. Multiple
145// such operations can be carried out atomically via a ConfChangeV2.
146message ConfChangeSingle {
147 optional ConfChangeType type = 1 [(gogoproto.nullable) = false];
148 optional uint64 node_id = 2 [(gogoproto.nullable) = false, (gogoproto.customname) = "NodeID"];
149}
150
151// ConfChangeV2 messages initiate configuration changes. They support both the
152// simple "one at a time" membership change protocol and full Joint Consensus
153// allowing for arbitrary changes in membership.
154//
155// The supplied context is treated as an opaque payload and can be used to
156// attach an action on the state machine to the application of the config change
157// proposal. Note that contrary to Joint Consensus as outlined in the Raft
158// paper[1], configuration changes become active when they are *applied* to the
159// state machine (not when they are appended to the log).
160//
161// The simple protocol can be used whenever only a single change is made.
162//
163// Non-simple changes require the use of Joint Consensus, for which two
164// configuration changes are run. The first configuration change specifies the
165// desired changes and transitions the Raft group into the joint configuration,
166// in which quorum requires a majority of both the pre-changes and post-changes
167// configuration. Joint Consensus avoids entering fragile intermediate
168// configurations that could compromise survivability. For example, without the
169// use of Joint Consensus and running across three availability zones with a
170// replication factor of three, it is not possible to replace a voter without
171// entering an intermediate configuration that does not survive the outage of
172// one availability zone.
173//
174// The provided ConfChangeTransition specifies how (and whether) Joint Consensus
175// is used, and assigns the task of leaving the joint configuration either to
176// Raft or the application. Leaving the joint configuration is accomplished by
177// proposing a ConfChangeV2 with only and optionally the Context field
178// populated.
179//
180// For details on Raft membership changes, see:
181//
182// [1]: https://github.com/ongardie/dissertation/blob/master/online-trim.pdf
183message ConfChangeV2 {
184 optional ConfChangeTransition transition = 1 [(gogoproto.nullable) = false];
185 repeated ConfChangeSingle changes = 2 [(gogoproto.nullable) = false];
186 optional bytes context = 3;
187}
View as plain text