github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/kv/kvserver/raft.proto

// Copyright 2015 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

syntax = "proto2";
package cockroach.kv.kvserver;
option go_package = "kvserver";

import "roachpb/errors.proto";
import "roachpb/metadata.proto";
import "kv/kvserver/kvserverpb/state.proto";
import "etcd/raft/raftpb/raft.proto";
import "gogoproto/gogo.proto";

// RaftHeartbeat is a request that contains the barebones information for a
// raftpb.MsgHeartbeat raftpb.Message. RaftHeartbeats are coalesced and sent
// in a RaftMessageRequest, and reconstructed by the receiver into individual
// raftpb.Message protos.
message RaftHeartbeat {
  optional uint64 range_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "RangeID",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.RangeID"];
  optional uint32 from_replica_id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "FromReplicaID",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.ReplicaID"];
  optional uint32 to_replica_id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ToReplicaID",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.ReplicaID"];
  optional uint64 term = 4 [(gogoproto.nullable) = false];
  optional uint64 commit = 5 [(gogoproto.nullable) = false];
  optional bool quiesce = 6 [(gogoproto.nullable) = false];

  // ToIsLearner was added in v19.2 to aid in the transition from preemptive
  // snapshots to learner replicas. If a Replica learns its ID from a message
  // which indicates that it is a learner and it is not currently a part of the
  // range (due to being from a preemptive snapshot) then it must delete all of
  // its data.
  //
  // TODO(ajwerner): remove in 20.2 once we ensure that preemptive snapshots can
  // no longer be present and that we're never talking to a 19.2 node.
  optional bool to_is_learner = 7 [(gogoproto.nullable) = false];
}

// RaftMessageRequest is the request used to send raft messages using our
// protobuf-based RPC codec. If a RaftMessageRequest has a non-empty number of
// heartbeats or heartbeat_resps, the contents of the message field is treated
// as a dummy message and discarded. A coalesced heartbeat request's replica
// descriptor's range ID must be zero.
message RaftMessageRequest {
  optional uint64 range_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "RangeID",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.RangeID"];
  // Optionally, the start key of the sending replica. This is only populated
  // as a "hint" under certain conditions.
  optional bytes range_start_key = 8 [(gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.RKey"];

  optional roachpb.ReplicaDescriptor from_replica = 2 [(gogoproto.nullable) = false];
  optional roachpb.ReplicaDescriptor to_replica = 3 [(gogoproto.nullable) = false];

  optional raftpb.Message message = 4 [(gogoproto.nullable) = false];

  // Is this a quiesce request? A quiesce request is a MsgHeartbeat
  // which is requesting the recipient to stop ticking its local
  // replica as long as the current Raft state matches the heartbeat
  // Term/Commit. If the Term/Commit match, the recipient is marked as
  // quiescent. If they don't match, the message is passed along to
  // Raft which will generate a MsgHeartbeatResp that will unquiesce
  // the sender.
  optional bool quiesce = 5 [(gogoproto.nullable) = false];

  // A coalesced heartbeat request is any RaftMessageRequest with a nonzero number of
  // heartbeats or heartbeat_resps.
  repeated RaftHeartbeat heartbeats = 6 [(gogoproto.nullable) = false];
  repeated RaftHeartbeat heartbeat_resps = 7 [(gogoproto.nullable) = false];
}

message RaftMessageRequestBatch {
  repeated RaftMessageRequest requests = 1 [(gogoproto.nullable) = false];
}

message RaftMessageResponseUnion {
  option (gogoproto.onlyone) = true;

  optional roachpb.Error error = 1;
}

// RaftMessageResponse may be sent to the sender of a
// RaftMessageRequest. RaftMessage does not use the usual
// request/response pattern; it is primarily modeled as a one-way
// stream of requests. Normal 'responses' are usually sent as new
// requests on a separate stream in the other direction.
// RaftMessageResponse is not sent for every RaftMessageRequest, but
// may be used for certain error conditions.
message RaftMessageResponse {
  optional uint64 range_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "RangeID",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.RangeID"];

  optional roachpb.ReplicaDescriptor from_replica = 2 [(gogoproto.nullable) = false];
  optional roachpb.ReplicaDescriptor to_replica = 3 [(gogoproto.nullable) = false];

  optional RaftMessageResponseUnion union = 4 [(gogoproto.nullable) = false];
}

// SnapshotRequest is the request used to send streaming snapshot requests.
message SnapshotRequest {
  enum Priority {
    UNKNOWN = 0;
    // RECOVERY is used for a Raft-initiated snapshots and for
    // up-replication snapshots (i.e. when a dead node has been
    // removed and the range needs to be up-replicated).
    RECOVERY = 1;
    // REBALANCE is used for snapshots involved in rebalancing.
    REBALANCE = 2;
  }

  enum Strategy {
    // KV_BATCH snapshots stream batches of KV pairs for all keys in a
    // range from the sender the the receiver. These KV pairs are then
    // combined into a large RocksDB WriteBatch that is atomically
    // applied.
    KV_BATCH = 0;
  }

  enum Type {
    RAFT = 0;
    LEARNER = 1;
    reserved 2;
  }

  message Header {
    reserved 1;

    // The replica state at the time the snapshot was generated. Note
    // that ReplicaState.Desc differs from the above range_descriptor
    // field which holds the updated descriptor after the new replica
    // has been added while ReplicaState.Desc holds the descriptor
    // before the new replica has been added.
    optional storagepb.ReplicaState state = 5 [(gogoproto.nullable) = false];

    // The inner raft message is of type MsgSnap, and its snapshot data contains a UUID.
    optional RaftMessageRequest raft_message_request = 2 [(gogoproto.nullable) = false];

    // The estimated size of the range, to be used in reservation decisions.
    optional int64 range_size = 3 [(gogoproto.nullable) = false];

    // can_decline is set on preemptive snapshots, but not those generated
    // by raft because at that point it is better to queue up the stream
    // than to cancel it.
    optional bool can_decline = 4 [(gogoproto.nullable) = false];

    // The priority of the snapshot.
    optional Priority priority = 6 [(gogoproto.nullable) = false];

    // The strategy of the snapshot.
    optional Strategy strategy = 7 [(gogoproto.nullable) = false];

    // The type of the snapshot.
    optional Type type = 9 [(gogoproto.nullable) = false];

    // Whether the snapshot uses the unreplicated RaftTruncatedState or not.
    // This is generally always true at 2.2 and above outside of the migration
    // phase, though theoretically it could take a long time for all ranges
    // to update to the new mechanism. This bool is true iff the Raft log at
    // the snapshot's applied index is using the new key. In particular, it
    // is true if the index itself carries out the migration (in which case
    // the data in the snapshot contains neither key).
    //
    // See VersionUnreplicatedRaftTruncatedState.
    optional bool unreplicated_truncated_state = 8 [(gogoproto.nullable) = false];
  }

  optional Header header = 1;

  // A RocksDB BatchRepr. Multiple kv_batches may be sent across multiple request messages.
  optional bytes kv_batch = 2 [(gogoproto.customname) = "KVBatch"];

  // These are really raftpb.Entry, but we model them as raw bytes to avoid
  // roundtripping through memory. They are separate from the kv_batch to
  // allow flexibility in log implementations.
  repeated bytes log_entries = 3;

  optional bool final = 4 [(gogoproto.nullable) = false];
}

message SnapshotResponse {
  enum Status {
    UNKNOWN = 0;
    ACCEPTED = 1;
    APPLIED = 2;
    ERROR = 3;
    DECLINED = 4;
  }
  optional Status status = 1 [(gogoproto.nullable) = false];
  optional string message = 2 [(gogoproto.nullable) = false];
  reserved 3;
}

// ConfChangeContext is encoded in the raftpb.ConfChange.Context field.
message ConfChangeContext {
  optional string command_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "CommandID"];

  // Payload is the application-level command (i.e. an encoded
  // kvserverpb.RaftCommand).
  optional bytes payload = 2;
}