api.proto

// Copyright 2014 The Cockroach Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
// implied. See the License for the specific language governing
// permissions and limitations under the License.

syntax = "proto3";
package cockroach.roachpb;
option go_package = "roachpb";

import "roachpb/data.proto";
import "roachpb/errors.proto";
import "roachpb/metadata.proto";
import "storage/engine/enginepb/mvcc.proto";
import "storage/engine/enginepb/mvcc3.proto";
import "util/hlc/timestamp.proto";
import "util/tracing/recorded_span.proto";
import "gogoproto/gogo.proto";

// ReadConsistencyType specifies what type of consistency is observed
// during read operations.
enum ReadConsistencyType {
  option (gogoproto.goproto_enum_prefix) = false;

  // CONSISTENT reads are guaranteed to read committed data; the
  // mechanism relies on clocks to determine lease expirations.
  CONSISTENT = 0;
  // READ_UNCOMMITTED reads return both committed and uncommitted data.
  // The consistency type is similar to INCONSISTENT in that using it
  // can result in dirty reads. However, like the CONSISTENT type, it
  // requires the replica performing the read to hold a valid read lease,
  // meaning that it can't return arbitrarily stale data.
  READ_UNCOMMITTED = 1;
  // INCONSISTENT reads return the latest available, committed values.
  // They are more efficient, but may read stale values as pending
  // intents are ignored.
  INCONSISTENT = 2;
}

// RangeInfo describes a range which executed a request. It contains
// the range descriptor and lease information at the time of execution.
message RangeInfo {
  RangeDescriptor desc = 1 [(gogoproto.nullable) = false];
  Lease lease = 2 [(gogoproto.nullable) = false];
}

// RequestHeader is supplied with every storage node request.
message RequestHeader {
  option (gogoproto.equal) = true;

  reserved 1, 2;
  // The key for request. If the request operates on a range, this
  // represents the starting key for the range.
  bytes key = 3 [(gogoproto.casttype) = "Key"];
  // The end key is empty if the request spans only a single key. Otherwise,
  // it must order strictly after Key. In such a case, the header indicates
  // that the operation takes place on the key range from Key to EndKey,
  // including Key and excluding EndKey.
  bytes end_key = 4 [(gogoproto.casttype) = "Key"];
  // A zero-indexed transactional sequence number.
  int32 sequence = 5 [
    (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/storage/engine/enginepb.TxnSeq"];
}

// ResponseHeader is returned with every storage node response.
message ResponseHeader {
  enum ResumeReason {
    option (gogoproto.goproto_enum_prefix) = false;
    // Zero value; no resume.
    RESUME_UNKNOWN = 0;
    // The spanning operation didn't finish because the key limit was
    // exceeded.
    RESUME_KEY_LIMIT = 1;
    // The spanning operation didn't finish because a range boundary
    // was encountered and the command was configured to stop at range
    // boundaries.
    RESUME_RANGE_BOUNDARY = 2;
  }

  // txn is non-nil if the request specified a non-nil transaction.
  // The transaction timestamp and/or priority may have been updated,
  // depending on the outcome of the request.
  Transaction txn = 3;
  // The next span to resume from when the response doesn't cover the full span
  // requested. This can happen when a bound on the keys is set through
  // max_span_request_keys in the batch header or when a scan has been stopped
  // before covering the requested data because of scan_options.
  //
  // ResumeSpan is unset when the entire span of keys have been
  // operated on. The span is set to the original span if the request
  // was ignored because max_span_request_keys was hit due to another
  // request in the batch. For a reverse scan the end_key is updated.
  Span resume_span = 4;
  // When resume_span is populated, this specifies the reason why the operation
  // wasn't completed and needs to be resumed.
  // This field appeared in v2.0. Responses from storage coming from older
  // servers will not contain it, but the conversion from a BatchResponse to a
  // client.Result always fills it in.
  ResumeReason resume_reason = 7;

  // The number of keys operated on.
  int64 num_keys = 5;
  // Range or list of ranges used to execute the request. Multiple
  // ranges may be returned for Scan, ReverseScan or DeleteRange.
  repeated RangeInfo range_infos = 6 [(gogoproto.nullable) = false];
}

// A GetRequest is the argument for the Get() method.
message GetRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A GetResponse is the return value from the Get() method.
// If the key doesn't exist, Value will be nil.
message GetResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Value value = 2;

  // The intent seen, if any, when using the READ_UNCOMMITTED consistency level.
  Value intent_value = 3;
}

// A PutRequest is the argument to the Put() method.
message PutRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Value value = 2 [(gogoproto.nullable) = false];
  // Specify as true to put the value without a corresponding
  // timestamp. This option should be used with care as it precludes
  // the use of this value with transactions.
  bool inline = 3;
  // NOTE: For internal use only! Set to indicate that the put is
  // writing to virgin keyspace and no reads are necessary to
  // rationalize MVCC.
  bool blind = 4;
}

// A PutResponse is the return value from the Put() method.
message PutResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A ConditionalPutRequest is the argument to the ConditionalPut() method.
//
// - Returns true and sets value if exp_value equals existing value.
// - If key doesn't exist and exp_value is nil, sets value.
// - If key exists, but value is empty and exp_value is not nil but empty, sets value.
// - Otherwise, returns an error containing the actual value of the key.
message ConditionalPutRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The value to put.
  Value value = 2 [(gogoproto.nullable) = false];
  // Set exp_value.bytes empty to test for non-existence. Specify as nil
  // to indicate there should be no existing entry. This is different
  // from the expectation that the value exists but is empty.
  Value exp_value = 3;
  // NOTE: For internal use only! Set to indicate that the put is
  // writing to virgin keyspace and no reads are necessary to
  // rationalize MVCC.
  bool blind = 4;
  // Typically if a specific, non-empty expected value is supplied, it *must*
  // exist with that value. Passing this indicates that it is also OK if the key
  // does not exist. This is useful when a given value is expected but it is
  // possible it has not yet been written.
  bool allow_if_does_not_exist = 5;
}

// A ConditionalPutResponse is the return value from the
// ConditionalPut() method.
message ConditionalPutResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An InitPutRequest is the argument to the InitPut() method.
//
// - If key doesn't exist, sets value.
// - If key exists, returns a ConditionFailedError if value != existing value
//   If failOnTombstones is set to true, tombstone values count as mismatched
//   values and will cause a ConditionFailedError.
message InitPutRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Value value = 2 [(gogoproto.nullable) = false];
  // NOTE: For internal use only! Set to indicate that the put is
  // writing to virgin keyspace and no reads are necessary to
  // rationalize MVCC.
  bool blind = 3;
  // If true, tombstones cause ConditionFailedErrors.
  bool failOnTombstones = 4;
}

// A InitPutResponse is the return value from the InitPut() method.
message InitPutResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An IncrementRequest is the argument to the Increment() method. It
// increments the value for key, and returns the new value. If no
// value exists for a key, incrementing by 0 is not a noop, but will
// create a zero value. IncrementRequest cannot be called on a key set
// by Put() or ConditionalPut(). Similarly, Put() and ConditionalPut()
// cannot be invoked on an incremented key.
message IncrementRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  int64 increment = 2;
}

// An IncrementResponse is the return value from the Increment
// method. The new value after increment is specified in NewValue. If
// the value could not be decoded as specified, Error will be set.
message IncrementResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  int64 new_value = 2;
}

// A DeleteRequest is the argument to the Delete() method.
message DeleteRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A DeleteResponse is the return value from the Delete() method.
message DeleteResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A DeleteRangeRequest is the argument to the DeleteRange() method. It
// specifies the range of keys to delete.
message DeleteRangeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  reserved 2;
  // return the keys that are deleted in the response.
  bool return_keys = 3;
  // delete "inline" keys which are stored without MVCC timestamps. Note that
  // an "inline" DeleteRange will fail if it attempts to delete any keys which
  // contain timestamped (non-inline) values; this option should only be used on
  // keys which are known to store inline values, such as data in cockroach's
  // time series system.
  //
  // Similarly, attempts to delete keys with inline values will fail unless this
  // flag is set to true; the setting must match the data being deleted.
  //
  // Inline values cannot be deleted transactionally; a DeleteRange with
  // "inline" set to true will fail if it is executed within a transaction.
  bool inline = 4;
}

// A DeleteRangeResponse is the return value from the DeleteRange()
// method.
message DeleteRangeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // All the deleted keys if return_keys is set.
  repeated bytes keys = 2 [(gogoproto.casttype) = "Key"];
}

// A ClearRangeRequest is the argument to the ClearRange() method. It
// specifies a range of keys to clear from the underlying engine. Note
// that this differs from the behavior of DeleteRange, which sets
// transactional intents and writes tombstones to the deleted
// keys. ClearRange is used when permanently dropping or truncating
// table data.
//
// ClearRange also updates the GC threshold for the range to the
// timestamp at which this command executes, to prevent reads at
// earlier timestamps from incorrectly returning empty results.
//
// NOTE: it is important that this method only be invoked on a key
// range which is guaranteed to be both inactive and not see future
// writes. Ignoring this warning may result in data loss.
message ClearRangeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A ClearRangeResponse is the return value from the ClearRange() method.
message ClearRangeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// ScanOptions is a collection of options for a batch of scans. The options
// apply to all the scans in the batch.
//
// If ScanOptions is present on a batch, the batch can only be made up of scan
// requests (i.e.  {Reverse,}ScanReques), except for
// {Begin,End}TransactionRequest which are still allowed. Moreover, the batch
// cannot mix forward and reverse scans.
//
// TODO(andrei): add option to stop scan(s) when an intent is encountered.
message ScanOptions {
  option (gogoproto.equal) = true;

  // stop_at_range_boundary, if set, means that the scans will stop at the first
  // range boundary after min_results is specified (if it is
  // specified). If the end of a range stops the scans, the resume_span returned
  // (for all the scans whose spans weren't fully scanned) represents the
  // beginning of the next range (as ranges were at the time of the read).
  //
  // This flag can be combined with header.max_span_request_keys but that means
  // that the desired number of keys may not be scanned.
  //
  // stop_at_range_boundary implies that DistSender will no longer parallelize
  // the execution of requests between ranges; instead, either we're only
  // speaking about scanning one range (if min_results is not set) or
  // it executes the scan serially over different ranges. Note that this is
  // also the case when max_span_request_keys is set (as the scan needs to
  // return results in order), and SQL always sets max_span_request_keys.
  bool stop_at_range_boundary = 1;

  // min_results, if != 0, prevents the stop_at_range_boundary option from
  // terminating the scans before this many keys have been touched. The
  // counting is done across all the scans in the batch.
  //
  // A common value is 1, used if either the client knows that one key will be
  // sufficient for its purposes or if the client wants to skip a prefix of
  // empty ranges and seek to the point where some data is present.
  //
  // This can only be set if stop_at_range_boundary is set. If
  // header.max_span_request_keys is set, min_results needs to be <=
  // header.max_span_request_keys.
  int64 min_results = 2;
}

// ScanFormat is an enumeration of the available response formats for MVCCScan
// operations.
enum ScanFormat {
  option (gogoproto.goproto_enum_prefix) = false;

  // The standard MVCCScan format: a slice of KeyValue messages.
  KEY_VALUES = 0;
  // The batch_response format: a byte slice of alternating keys and values,
  // each prefixed by their length as a varint.
  BATCH_RESPONSE = 1;
}


// A ScanRequest is the argument to the Scan() method. It specifies the
// start and end keys for an ascending scan of [start,end) and the maximum
// number of results (unbounded if zero).
message ScanRequest {
  option (gogoproto.equal) = true;

  reserved 2, 3;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // The desired format for the response. If set to BATCH_RESPONSE, the server
  // will set the batch_responses field in the ScanResponse instead of the rows
  // field.
  ScanFormat scan_format = 4;
}

// A ScanResponse is the return value from the Scan() method.
message ScanResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Empty if no rows were scanned.
  repeated KeyValue rows = 2 [(gogoproto.nullable) = false];
  // The intent rows seen when performing a scan at the READ_UNCOMMITTED
  // consistency level. These rows do not count against the MaxSpanRequestKeys
  // count.
  repeated KeyValue intent_rows = 3 [(gogoproto.nullable) = false];

  // If set, each item in this repeated bytes field contains part of the results
  // in batch format - the key/value pairs are a buffer of varint-prefixed
  // slices, alternating from key to value. Each entry in this field is
  // complete - there are no key/value pairs that are split across more than one
  // entry. There are num_keys total pairs across all entries, as defined by the
  // ResponseHeader. If set, rows will not be set and vice versa.
  repeated bytes batch_responses = 4;
}

// A ReverseScanRequest is the argument to the ReverseScan() method. It specifies the
// start and end keys for a descending scan of [start,end) and the maximum
// number of results (unbounded if zero).
message ReverseScanRequest {
  option (gogoproto.equal) = true;

  reserved 2, 3;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // The desired format for the response. If set to BATCH_RESPONSE, the server
  // will set the batch_responses field in the ScanResponse instead of the rows
  // field.
  ScanFormat scan_format = 4;
}

// A ReverseScanResponse is the return value from the ReverseScan() method.
message ReverseScanResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Empty if no rows were scanned.
  repeated KeyValue rows = 2 [(gogoproto.nullable) = false];
  // The intent rows seen when performing a scan at the READ_UNCOMMITTED
  // consistency level. These rows do not count against the MaxSpanRequestKeys
  // count.
  repeated KeyValue intent_rows = 3 [(gogoproto.nullable) = false];

  // If set, each item in this repeated bytes field contains part of the results
  // in batch format - the key/value pairs are a buffer of varint-prefixed
  // slices, alternating from key to value. Each entry in this field is
  // complete - there are no key/value pairs that are split across more than one
  // entry. There are num_keys total pairs across all entries, as defined by the
  // ResponseHeader. If set, rows will not be set and vice versa.
  repeated bytes batch_responses = 4;
}


enum ChecksumMode {
    // CHECK_VIA_QUEUE is set for requests made from the consistency queue. In
    // this mode, a full check is carried out, and depending on the result a
    // recursive consistency check is triggered:
    //
    // 1. no inconsistency found: if recomputed stats don't match persisted stats,
    //    trigger a RecomputeStatsRequest.
    // 2. inconsistency found: if a diff is available, print it and trigger fatal
    //    error. If no diff found, trigger recursive check with diff requested
    //    (which then triggers fatal error).
    //
    // TODO(tbg): these semantics are an artifact of how consistency checks were
    // first implemented. The extra behavior here should move to the consistency
    // check queue instead and this option dropped from the enum.
    CHECK_VIA_QUEUE = 0;
    // CHECK_FULL recomputes the hash of the replicate data in all replicas and
    // uses this to determine whether there is an inconsistency.
    CHECK_FULL = 1;
    // CHECK_STATS only hashes the persisted lease applied state (which notably
    // includes the persisted MVCCStats) only. This catches a large class of
    // replica inconsistencies observed in the wild (where replicas apply a
    // nonidentical log of commands, and as a result almost always have
    // divergent stats), while doing work independent of the size of the data
    // contained in the replicas.
    CHECK_STATS = 2;
}

// A CheckConsistencyRequest is the argument to the CheckConsistency() method.
// It specifies the start and end keys for a span of ranges to which a
// consistency check should be applied. A consistency check on a range involves
// running a ComputeChecksum on the range followed by a storage.CollectChecksum.
message CheckConsistencyRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // log a diff of inconsistencies if such inconsistencies are found. This is only
  // valid if mode == FROM_QUEUE
  bool with_diff = 2;

  ChecksumMode mode = 3;
}

// A CheckConsistencyResponse is the return value from the CheckConsistency() method.
// It returns the status the range was found in.
message CheckConsistencyResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  enum Status {
    // No inconsistency was detected, but not all replicas returned a checksum.
    RANGE_INDETERMINATE = 0;
    // A definite inconsistency was detected.
    RANGE_INCONSISTENT = 1;
    // All replicas of the range agreed on the checksum.
    RANGE_CONSISTENT = 2;
    // Like RANGE_CONSISTENT, but the recomputed stats disagreed with the
    // persisted stats. The persisted stats indicates estimates, so this is
    // expected.
    RANGE_CONSISTENT_STATS_ESTIMATED = 3;
    // Like RANGE_CONSISTENT_STATS_ESTIMATED, but the mismatch occurred with
    // persisted stats that claimed to be accurate. This is unexpected and
    // likely indicates a bug in our logic to incrementally update the stats
    // as commands are evaluated and applied.
    RANGE_CONSISTENT_STATS_INCORRECT = 4;
  }

  message Result {
    int64 range_id = 1 [(gogoproto.customname) = "RangeID", (gogoproto.casttype) = "RangeID"];
    // start_key of the range corresponding to range_id (at the time of the
    // check). This is useful to send additional requests to only a subset of
    // ranges contained within a result later, as requests can only be routed by
    // key.
    bytes start_key = 2;
    Status status = 3;
    // detail contains information related to the operation. If no inconsistency
    // is found, it contains informational value such as observed stats. If an
    // inconsistency is found, it contains information about that inconsistency
    // including the involved replica and, if requested, the diff.
    string detail = 4;
  }

  // result contains a Result for each Range checked, in no particular order.
  repeated Result result = 2 [(gogoproto.nullable) = false];
}

// An RecomputeStatsRequest triggers a stats recomputation on the Range addressed by
// the request.
//
// An error will be returned if the start key does not match the start key of the
// target Range.
//
// The stats recomputation touches essentially the whole range, but the command
// avoids having to block other commands by taking care to not interleave
// with splits, and by using the commutativity of stats updates. As a result,
// it is safe to invoke at any time, including repeatedly, though it should be
// used conservatively due to performing a full scan of the Range.
message RecomputeStatsRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // When dry_run is true, the stats delta is computed, but no stats adjustment
  // is performed. This isn't useful outside of testing since RecomputeStats is
  // safe and idempotent.
  bool dry_run = 2;
}

// An RecomputeStatsResponse is the response to an RecomputeStatsRequest.
message RecomputeStatsResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // added_delta is the adjustment made to the range's stats, i.e. `new_stats = old_stats + added_delta`.
  storage.engine.enginepb.MVCCStatsDelta added_delta = 2 [(gogoproto.nullable) = false];
}

// A BeginTransactionRequest is the argument to the BeginTransaction() method.
message BeginTransactionRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A BeginTransactionResponse is the return value from the BeginTransaction() method.
message BeginTransactionResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An EndTransactionRequest is the argument to the EndTransaction() method. It
// specifies whether to commit or roll back an extant transaction.
message EndTransactionRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // False to abort and rollback.
  bool commit = 2;
  // If set, deadline represents the maximum (exclusive) timestamp at which the
  // transaction can commit (i.e. the maximum timestamp for the txn's reads and
  // writes).
  // If EndTransaction(Commit=true) finds that the txn's timestamp has been
  // pushed above this deadline, an error will be returned and the client is
  // supposed to rollback the txn.
  util.hlc.Timestamp deadline = 3;
  // commit triggers. Note that commit triggers are for
  // internal use only and will cause an error if requested through the
  // external-facing KV API.
  InternalCommitTrigger internal_commit_trigger = 4;
  // List of intents written by the transaction. These are spans where
  // write intents have been written which must be resolved on txn
  // completion. Note that these spans may be condensed to cover
  // aggregate spans if the keys written by the transaction exceeded
  // a size threshold.
  repeated Span intent_spans = 5 [(gogoproto.nullable) = false];
  // Requires that the transaction completes as a 1 phase commit. This
  // guarantees that all writes are to the same range and that no
  // intents are left in the event of an error.
  bool require_1pc = 6 [(gogoproto.customname) = "Require1PC"];
  // Set to true if this transaction is serializable isolation but has
  // accummulated no refresh spans. This allows the executing server
  // to retry it locally on the fast path.
  bool no_refresh_spans = 8;
  // True to indicate that intent spans should be resolved with
  // poison=true.  This is used when the transaction is being aborted
  // independently of the main thread of client operation, as in the
  // case of an asynchronous abort from the TxnCoordSender on a failed
  // heartbeat.
  bool poison = 9;
  reserved 7;
}

// An EndTransactionResponse is the return value from the
// EndTransaction() method. The final transaction record is returned
// as part of the response header. In particular, transaction status
// and timestamp will be updated to reflect final committed
// values. Clients may propagate the transaction timestamp as the
// final txn commit timestamp in order to preserve causal ordering
// between subsequent transactions.
message EndTransactionResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  reserved 2;
  reserved 3;
  // True if the transaction committed on the one phase commit path.
  // This means that all writes which were part of the transaction
  // were written as a single, atomic write batch to just one range.
  bool one_phase_commit = 4;
}

// An AdminSplitRequest is the argument to the AdminSplit() method. The
// existing range which contains header.key is split by
// split_key. If split_key is not specified, then this method will
// determine a split key that is roughly halfway through the
// range. The existing range is resized to cover only its start key to
// the split key. The new range created by the split starts at the
// split key and extends to the original range's end key. If split_key
// is known, header.key should also be set to split_key.
//
// New range IDs for each of the split range's replica and a new Raft
// ID are generated by the operation. Split requests are done in the
// context of a distributed transaction which updates range addressing
// records, range metadata and finally, provides a commit trigger to
// update bookkeeping and instantiate the new range on commit.
//
// The new range contains range replicas located on the same stores;
// no range data is moved during this operation. The split can be
// thought of as a mostly logical operation, though some other
// metadata (e.g. abort span and range stats must be copied or
// recomputed).
message AdminSplitRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  bytes split_key = 2 [(gogoproto.casttype) = "Key"];
}

// An AdminSplitResponse is the return value from the AdminSplit()
// method.
message AdminSplitResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An AdminMergeRequest is the argument to the AdminMerge() method. A
// merge is performed by calling AdminMerge on the left-hand range of
// two consecutive ranges (i.e. the range which contains keys which
// sort first). This range will be the subsuming range and the right
// hand range will be subsumed. After the merge operation, the
// subsumed range will no longer exist and the subsuming range will
// now encompass all keys from its original start key to the end key
// of the subsumed range. If AdminMerge is called on the final range
// in the key space, it is a noop.
message AdminMergeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An AdminMergeResponse is the return value from the AdminMerge()
// method.
message AdminMergeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An AdminTransferLeaseRequest is the argument to the AdminTransferLease()
// method. A lease transfer allows an external entity to control the lease
// holder for a range. The target of the lease transfer needs to be a valid
// replica of the range.
message AdminTransferLeaseRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  int32 target = 2 [(gogoproto.casttype) = "StoreID"];
}

message AdminTransferLeaseResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// An AdminChangeReplicasRequest is the argument to the AdminChangeReplicas()
// method. A change replicas operation allows adding or removing a set of
// replicas for a range.
message AdminChangeReplicasRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  ReplicaChangeType change_type = 2;
  repeated ReplicationTarget targets = 3 [(gogoproto.nullable) = false];
  // ExpDesc is the expected current range descriptor to modify. If ExpDesc is
  // not nil and the value of the range descriptor is not identical to ExpDesc
  // for the request will fail.
  // This field was added for 19.1 release and must remain optional until 19.2.
  // TODO(ajwerner): Make this non-nullable for 19.2.
  RangeDescriptor exp_desc = 4;
}

message AdminChangeReplicasResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Desc is the value of the range descriptor upon success.
  // This field was added for 19.1 release and must remain optional until 19.2.
  // TODO(ajwerner): Make this non-nullable for 19.2.
  RangeDescriptor desc = 2;
}

// An AdminRelocateRangeRequest is the argument to the AdminRelocateRange()
// method. Relocates the replicas for a range to the specified target stores.
// The first store in the list of targets becomes the new leaseholder.
message AdminRelocateRangeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated ReplicationTarget targets = 2 [(gogoproto.nullable) = false];
  // TODO(a-robinson): Add "reason"/"details" string fields?
}

message AdminRelocateRangeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A HeartbeatTxnRequest is arguments to the HeartbeatTxn()
// method. It's sent by transaction coordinators to let the system
// know that the transaction is still ongoing. Note that this
// heartbeat message is different from the heartbeat message in the
// gossip protocol.
message HeartbeatTxnRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  util.hlc.Timestamp now = 2 [(gogoproto.nullable) = false];
}

// A HeartbeatTxnResponse is the return value from the HeartbeatTxn()
// method. It returns the transaction info in the response header. The
// returned transaction lets the coordinator know the disposition of
// the transaction (i.e. aborted, committed, or pending).
message HeartbeatTxnResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A GCRequest is arguments to the GC() method. It's sent by range
// lease holders after scanning range data to find expired MVCC values.
message GCRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  message GCKey {
    option (gogoproto.equal) = true;

    bytes key = 1 [(gogoproto.casttype) = "Key"];
    util.hlc.Timestamp timestamp = 2 [(gogoproto.nullable) = false];
  }
  repeated GCKey keys = 3 [(gogoproto.nullable) = false];
  // Threshold is the expiration timestamp.
  util.hlc.Timestamp threshold = 4 [(gogoproto.nullable) = false];
  // TxnSpanGCThreshold is the timestamp below which inactive transactions were
  // considered for GC (and thus might have been removed).
  // TODO(nvanbenschoten): Remove this in 2.3, at which point we won't need to
  // update it because no nodes in the cluster will ever consult it.
  util.hlc.Timestamp txn_span_gc_threshold = 5 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "TxnSpanGCThreshold"];
}

// A GCResponse is the return value from the GC() method.
message GCResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// PushTxnType determines what action to take when pushing a transaction.
enum PushTxnType {
  option (gogoproto.goproto_enum_prefix) = false;

  // Push the timestamp forward if possible to accommodate a concurrent reader.
  PUSH_TIMESTAMP = 0;
  // Abort the transaction if possible to accommodate a concurrent writer.
  PUSH_ABORT = 1;
  // Abort the transaction if it's abandoned, but don't attempt to mutate it
  // otherwise.
  PUSH_TOUCH = 2;

  reserved 3;
}

// A PushTxnRequest is arguments to the PushTxn() method. It's sent by
// readers or writers which have encountered an "intent" laid down by
// another transaction. The goal is to resolve the conflict. Note that
// args.Key should be set to the txn ID of args.PusheeTxn, not
// args.PusherTxn. This RPC is addressed to the range which owns the pushee's
// txn record.
//
// Resolution is trivial if the txn which owns the intent has either
// been committed or aborted already. Otherwise, the existing txn can
// either be aborted (for write/write conflicts), or its commit
// timestamp can be moved forward (for read/write conflicts). The
// course of action is determined by the specified push type, and by
// the owning txn's status and priority.
message PushTxnRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Transaction which encountered the intent, if applicable. For a
  // non-transactional pusher, pusher_txn will only have the priority set (in
  // particular, ID won't be set). Used to compare priorities and timestamps if
  // priorities are equal.
  Transaction pusher_txn = 2 [(gogoproto.nullable) = false];
  // Transaction to be pushed, as specified at the intent which led to
  // the push transaction request. Note that this may not be the most
  // up-to-date value of the transaction record, but will be set or
  // merged as appropriate.
  storage.engine.enginepb.TxnMeta pushee_txn = 3 [(gogoproto.nullable) = false];
  // PushTo is the timestamp which PusheeTxn should be pushed to. During
  // conflict resolution, it should be set just after the timestamp of the
  // conflicting read or write.
  util.hlc.Timestamp push_to = 4 [(gogoproto.nullable) = false];
  // InclusivePushTo is sent by nodes to specify that their PushTo timestamp
  // is the timestamp they want the transaction to be pushed to, instead of
  // the timestamp before the one they want the transaction to be pushed to.
  // It is used to assist that field's migration.
  // TODO(nvanbenschoten): Remove this field in 19.2.
  bool inclusive_push_to = 9;
  // DeprecatedNow holds the timestamp used to compare the last heartbeat of the
  // pushee against.
  //
  // The field remains for compatibility with 2.1 nodes. Users should set the
  // same value for this field and the batch header timestamp.
  // TODO(nvanbenschoten): Remove this field in 19.2.
  util.hlc.Timestamp deprecated_now = 5 [(gogoproto.nullable) = false];
  // Readers set this to PUSH_TIMESTAMP to move pushee_txn's provisional
  // commit timestamp forward. Writers set this to PUSH_ABORT to request
  // that pushee_txn be aborted if possible. Inconsistent readers set
  // this to PUSH_TOUCH to determine whether the pushee can be aborted
  // due to inactivity (based on the now field).
  PushTxnType push_type = 6;
  // Forces the push by overriding the normal expiration and priority checks
  // in PushTxn to either abort or push the timestamp.
  bool force = 7;

  reserved 8;
}

// A PushTxnResponse is the return value from the PushTxn() method. It
// returns success and the resulting state of PusheeTxn if the
// conflict was resolved in favor of the caller; the caller should
// subsequently invoke ResolveIntent() on the conflicted key. It
// returns an error otherwise.
message PushTxnResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // pushee_txn is non-nil if the transaction was pushed and contains
  // the current value of the transaction.
  // TODO(tschottdorf): Maybe this can be a TxnMeta instead; probably requires
  // factoring out the new Priority.
  Transaction pushee_txn = 2 [(gogoproto.nullable) = false];
}

// A RecoverTxnRequest is arguments to the RecoverTxn() method. It is sent
// during the recovery process for a transaction abandoned in the STAGING state.
// The sender is expected to have queried all of the abandoned transaction's
// in-flight writes and determined whether they all succeeded or not. This is
// used to determine whether the result of the recovery should be committing the
// abandoned transaction or aborting it.
message RecoverTxnRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Transaction record to recover.
  storage.engine.enginepb.TxnMeta txn = 2 [(gogoproto.nullable) = false];
  // Did all of the STAGING transaction's writes succeed? If so, the transaction
  // is implicitly committed and the commit can be made explicit by giving its
  // record a COMMITTED status. If not, the transaction can be aborted as long
  // as a write that was found to have failed was prevented from ever succeeding
  // in the future.
  bool implicitly_committed = 3;
}

// A RecoverTxnResponse is the return value from the RecoverTxn() method.
message RecoverTxnResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // Contains the finalized state of the recovered transaction.
  Transaction recovered_txn = 2 [(gogoproto.nullable) = false];
}

// A QueryTxnResponse is arguments to the QueryTxn() method. It's sent
// by transactions which are waiting to push another transaction because
// of conflicting write intents to fetch updates to either the pusher's
// or the pushee's transaction records.
message QueryTxnRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Transaction record to query.
  storage.engine.enginepb.TxnMeta txn = 2 [(gogoproto.nullable) = false];
  // If true, the query will not return until there are changes to either the
  // transaction status or priority -OR- to the set of dependent transactions.
  bool wait_for_update = 3;
  // Set of known dependent transactions.
  repeated bytes known_waiting_txns = 4 [(gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID"];
}

// A QueryTxnResponse is the return value from the QueryTxn() method.
message QueryTxnResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Contains the current state of the queried transaction. If the queried
  // transaction record does not exist, this will be empty.
  Transaction queried_txn = 2 [(gogoproto.nullable) = false];
  // Specifies a list of transaction IDs which are waiting on the txn.
  repeated bytes waiting_txns = 3 [(gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID"];
}

// A QueryIntentRequest is arguments to the QueryIntent() method. It visits
// the specified key and checks whether an intent is present for the given
// transaction.
message QueryIntentRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // The TxnMeta that the intent is expected to have. Specifically, whether an
  // intent is a match or not is defined as whether an intent exists that could
  // be committed by the provided transaction. If an intent is found at the
  // specified key, the intent is only considered a match if it has the same ID,
  // the same epoch, and a provisional commit timestamp that is equal to or less
  // than that in the provided transaction. For SERIALIZABLE transactions, if
  // the intent's timestamp is greater than that in the provided transaction, it
  // would prevent the transaction from committing and is therefore not a match.
  // However, for SNAPSHOT transactions, if the intent's timestamp is greater
  // than that in the provided transaction, it would not prevent the transaction
  // from committing and therefore is a match.
  //
  // Additionally, the intent is only considered a match if its sequence number
  // is equal to or greater than the expected txn's sequence number. The
  // requests doesn't require an exact sequence number match because the
  // transaction could have performed overlapping writes, in which case only the
  // latest sequence number will remain. We assume that if a transaction has
  // successfully written an intent at a larger sequence number then it must
  // have succeeeded in writing an intent at the smaller sequence number as
  // well.
  storage.engine.enginepb.TxnMeta txn = 2 [(gogoproto.nullable) = false];

  enum IfMissingBehavior {
    // Don't do anything special, just note that the intent was not found in the
    // response.
    DO_NOTHING = 0;
    // Return an IntentMissingError. Special-cased to return a SERIALIZABLE
    // retry error if a SERIALIZABLE transaction queries its own intent and
    // finds it has been pushed.
    RETURN_ERROR = 1;
    // Prevent the intent from ever being written in the future. If set as the
    // behavior, a response with found_intent=false implies that an intent will
    // never be writtable at the key at the transaction's timestamp or below.
    PREVENT = 2;
  }
  // The behavior of the request if the expected intent is found to be not
  // present.
  IfMissingBehavior if_missing = 3;
}

// A QueryIntentResponse is the return value from the QueryIntent() method.
message QueryIntentResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Whether an intent matching the expected transaction was found at the key.
  bool found_intent = 2;
}

// A ResolveIntentRequest is arguments to the ResolveIntent()
// method. It is sent by transaction coordinators after success
// calling PushTxn to clean up write intents: either to remove, commit
// or move them forward in time.
message ResolveIntentRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The transaction whose intent is being resolved.
  storage.engine.enginepb.TxnMeta intent_txn = 2 [(gogoproto.nullable) = false];
  // The status of the transaction.
  TransactionStatus status = 3;
  // Optionally poison the abort span for the transaction the intent's
  // range.
  bool poison = 4;
}

// A ResolveIntentResponse is the return value from the
// ResolveIntent() method.
message ResolveIntentResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A ResolveIntentRangeRequest is arguments to the ResolveIntentRange() method.
// It is sent by transaction coordinators after success calling PushTxn to
// clean up write intents: either to remove, commit or move them forward in
// time.
message ResolveIntentRangeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The transaction whose intents are being resolved.
  storage.engine.enginepb.TxnMeta intent_txn = 2 [(gogoproto.nullable) = false];
  // The status of the transaction.
  TransactionStatus status = 3;
  // Optionally poison the abort span for the transaction on all ranges
  // on which the intents reside.
  bool poison = 4;
  // The minimum timestamp for any intents written by this
  // transaction. If present, this value can be used to optimize the
  // iteration over the span to find intents to resolve.
  util.hlc.Timestamp min_timestamp = 5 [(gogoproto.nullable) = false];
}

// A ResolveIntentRangeResponse is the return value from the
// ResolveIntent() method.
message ResolveIntentRangeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A MergeRequest contains arguments to the Merge() method. It
// specifies a key and a value which should be merged into the
// existing value at that key.
message MergeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Value value = 2 [(gogoproto.nullable) = false];
}

// MergeResponse is the response to a Merge() operation.
message MergeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// TruncateLogRequest is used to remove a prefix of the raft log. While there
// is no requirement for correctness that the raft log truncation be synchronized across
// replicas, it is nice to preserve the property that all replicas of a range are as close
// to identical as possible. The raft leader can also inform decisions about the cutoff point
// with its knowledge of the replicas' acknowledgment status.
message TruncateLogRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // Log entries < this index are to be discarded.
  uint64 index = 2;

  // RangeID is used to double check that the correct range is being truncated.
  // The header specifies a span, start and end keys, but not the range id
  // itself. The range may have changed from the one specified in the header
  // in the case of a merge.
  int64 range_id = 3 [(gogoproto.customname) = "RangeID", (gogoproto.casttype) = "RangeID"];
}

// TruncateLogResponse is the response to a TruncateLog() operation.
message TruncateLogResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A RequestLeaseRequest is arguments to the RequestLease()
// method. It is sent by the store on behalf of one of its ranges upon receipt
// of a command requiring a lease when none is found.
message RequestLeaseRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Lease lease = 2 [(gogoproto.nullable) = false];
  // The previous lease is specified by the caller to verify
  // it has not changed when executing this command.
  Lease prev_lease = 3 [(gogoproto.nullable) = false];
  // The MinLeaseProposedTS of the proposing replica to make sure that leases
  // issued after a node restart receive a new sequence number (instead of
  // counting as a lease extension). See #23204.
  util.hlc.Timestamp min_proposed_ts = 4 [(gogoproto.customname) = "MinProposedTS"];
}

// A TransferLeaseRequest represents the arguments to the TransferLease()
// method. It is sent by a replica that currently holds the range lease and
// wants to transfer it away.
//
// Like a RequestLeaseRequest, this request has the effect of instituting a new
// lease. The difference is that the new lease is allowed to overlap the
// existing one. It is a separate request because the RequestLeaseRequest is
// special - it's not subject to the same replay protection restrictions as
// other requests, instead being protected from replays by the fact that leases
// are not generally allowed to overlap. The TransferLeaseRequest is not
// special in this respect (for example, the proposer of this command is
// checked to have been holding the lease when the proposal was made).
message TransferLeaseRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Lease lease = 2 [(gogoproto.nullable) = false];
  // The previous lease is specified by the caller to verify
  // it has not changed when executing this command.
  Lease prev_lease = 3 [(gogoproto.nullable) = false];
}

// LeaseInfoRequest is the argument to the LeaseInfo() method, for getting
// information about a range's lease.
// It's a point request, so it addresses one single range, and returns the lease
// currently in effect for that range.
message LeaseInfoRequest{
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}
// LeaseInfoResponse is the response to a LeaseInfo() operation.
message LeaseInfoResponse{
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The last lease known by the replica serving the request. It can also be the
  // tentative future lease, if a lease transfer is in progress.
  Lease lease = 2 [(gogoproto.nullable) = false];
}

// A RequestLeaseResponse is the response to a RequestLease() or TransferLease()
// operation.
message RequestLeaseResponse{
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// A ComputeChecksumRequest is arguments to the ComputeChecksum() method, to
// start computing the checksum for the specified range at the snapshot for this
// request command. A response is returned without the checksum. The computed
// checksum is retrieved via a storage.CollectChecksumRequest.
message ComputeChecksumRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The version used to pick the checksum method. It allows us to use a
  // consistent checksumming method across replicas.
  uint32 version = 2;
  reserved 3;
  // Compute a checksum along with a snapshot of the entire range, that will be
  // used in logging a diff during checksum verification.
  bool snapshot = 4;
  // The type of checksum to compute. See ChecksumMode.
  ChecksumMode mode = 5;
}

// A ComputeChecksumResponse is the response to a ComputeChecksum() operation.
message ComputeChecksumResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // ChecksumID is the unique identifier that can be used to get the computed
  // checksum in a future storage.CollectChecksumRequest.
  bytes checksum_id = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ChecksumID",
      (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID"];
}

enum ExportStorageProvider {
  Unknown = 0;
  LocalFile = 1;
  Http = 2;
  S3 = 3;
  GoogleCloud = 4;
  Azure = 5;
  Workload = 6;
}

message ExportStorage {
  option (gogoproto.equal) = true;

  ExportStorageProvider provider = 1;

  message LocalFilePath {
    option (gogoproto.equal) = true;

    string path = 1;
    uint32 node_id = 2 [(gogoproto.customname) = "NodeID", (gogoproto.casttype) = "NodeID"];
  }
  message Http {
    option (gogoproto.equal) = true;

    string baseUri = 1;
  }
  message S3 {
    option (gogoproto.equal) = true;

    string bucket = 1;
    string prefix = 2;

    string access_key = 3;
    string secret = 4;
    string temp_token = 5;
    string endpoint = 6;
    string region = 7;
  }
  message GCS {
    option (gogoproto.equal) = true;

    string bucket = 1;
    string prefix = 2;
    string auth = 3;

    // BillingProject if non-empty, is the Google Cloud project to bill for all storage requests.
    // This is required to be set if using a "requestor pays" bucket.
    string billing_project = 4;

    string credentials = 5;
  }
  message Azure {
    option (gogoproto.equal) = true;

    string container = 1;
    string prefix = 2;

    string account_name = 3;
    string account_key = 4;
  }
  message Workload {
    option (gogoproto.equal) = true;

    string generator = 1;
    string version = 2;
    string table = 3;
    repeated string flags = 4;
    string format = 5;
    int64 batch_begin = 6;
    int64 batch_end = 7;
  }
  LocalFilePath LocalFile = 2 [(gogoproto.nullable) = false];
  Http HttpPath = 3 [(gogoproto.nullable) = false];
  GCS GoogleCloudConfig = 4;
  S3 S3Config = 5;
  Azure AzureConfig = 6;
  Workload WorkloadConfig = 7;
}

// WriteBatchRequest is arguments to the WriteBatch() method, to apply the
// operations encoded in a BatchRepr.
message WriteBatchRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // The span of keys encoded in data, duplicated because the header span can
  // be modified by DistSender and we use this one to fail fast.
  Span data_span = 2 [(gogoproto.nullable) = false];
  // A BatchRepr, the serialized form of a RocksDB Batch.
  bytes data = 3;
}

// WriteBatchResponse is the response to a WriteBatch() operation.
message WriteBatchResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

enum MVCCFilter {
  Latest = 0;
  All = 1;
}

// ExportRequest is the argument to the Export() method, to dump a keyrange into
// files under a basepath.
message ExportRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  ExportStorage storage = 2 [(gogoproto.nullable) = false];
  util.hlc.Timestamp start_time = 3 [(gogoproto.nullable) = false];
  MVCCFilter mvcc_filter = 4 [(gogoproto.customname) = "MVCCFilter"];

  // Return the exported SST data in the response.
  bool return_sst = 5 [(gogoproto.customname) = "ReturnSST"];
  // OmitChecksum, if true, will skip checksumming the sst and leave the
  // `Sha512` field empty in the response. During a rolling upgrade to 2.1, it
  // may still be set if the request is served by an old node, but since the
  // caller has declare they're not going to use it, that's okay.
  bool omit_checksum = 6;
}

message BulkOpSummary {
  int64 data_size = 1;
  int64 rows = 2;
  int64 index_entries = 3;
  int64 system_records = 4;
}

// ExportResponse is the response to an Export() operation.
message ExportResponse {
  // File describes a keyrange that has been dumped to a file at the given
  // path.
  message File {
    Span span = 1 [(gogoproto.nullable) = false];
    string path = 2;
    reserved 3;
    reserved 4;
    bytes sha512 = 5;

    BulkOpSummary exported = 6 [(gogoproto.nullable) = false];

    bytes sst = 7 [(gogoproto.customname) = "SST"];
  }

  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated File files = 2 [(gogoproto.nullable) = false];
  util.hlc.Timestamp start_time = 3 [(gogoproto.nullable) = false];
}

// ImportRequest is the argument to the Import() method, to bulk load key/value
// entries.
message ImportRequest {
  option (gogoproto.equal) = true;

  message File {
    option (gogoproto.equal) = true;

    ExportStorage dir = 1 [(gogoproto.nullable) = false];
    string path = 2;
    reserved 3;
    bytes sha512 = 4;
  }
  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // Files contains an ordered list of files, each containing kv entries to
  // import. Entries in later files with the same key override earlier ones.
  repeated File files = 2 [(gogoproto.nullable) = false];
  // DataSpan is the pre-rewrite keyrange of the data in `Files`.
  Span data_span = 3 [(gogoproto.nullable) = false];
  // EndTime, if not the zero value, will cause only entries before it to be
  // imported.
  util.hlc.Timestamp end_time = 6 [(gogoproto.nullable) = false];
  reserved 4;
  message TableRekey {
    option (gogoproto.equal) = true;

    // OldID is the previous ID of `new_desc`.
    uint32 old_id = 1 [(gogoproto.customname) = "OldID"];
    // NewDesc is an encoded Descriptor message.
    bytes new_desc = 2;
  }
  // Rekeys contains the descriptors for the data being Imported and the
  // previous ID for each (which is the ID used in the source data pointed to by
  // `files`).
  // TODO(dan): This field is a superset of the information represented by
  // `key_rewrites` and will supercede it once rekeying of interleaved tables is
  // fixed.
  repeated TableRekey rekeys = 5 [(gogoproto.nullable) = false];
}

// ImportResponse is the response to a Import() operation.
message ImportResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  reserved 2;
  BulkOpSummary imported = 3 [(gogoproto.nullable) = false];
}

// AdminScatterRequest is the argument to the AdminScatter() method, which moves
// replicas and leaseholders for a selection of ranges. Scatter is best-effort;
// ranges that cannot be moved will include an error detail in the response and
// won't fail the request.
message AdminScatterRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  bool randomize_leases = 2;
}

// ScatterResponse is the response to a Scatter() operation.
message AdminScatterResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  message Range {
    Span span = 1 [(gogoproto.nullable) = false];
    reserved 2;
  }
  repeated Range ranges = 2 [(gogoproto.nullable) = false];
}

// AddSSTableRequest is arguments to the AddSSTable() method, to link a file
// into the RocksDB log-structured merge-tree.
message AddSSTableRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  bytes data = 2;
}

// AddSSTableResponse is the response to a AddSSTable() operation.
message AddSSTableResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// RefreshRequest is arguments to the Refresh() method, which verifies
// that no write has occurred since the transaction's orig timestamp
// to the specified key. Either the read or write timestamp cache is
// updated according to the write parameter. A transaction must be
// supplied with this request. If the key has been written more
// recently than the original txn timestamp, an error is returned
// and the timestamp cache is not updated.
message RefreshRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // If set, indicates that the write timestamp cache should be
  // updated. This handles the case of DeleteRange, which must set the
  // write too old flag on transactions which attempt earlier writes.
  bool write = 2;
}

// RefreshResponse is the response to a Refresh() operation.
message RefreshResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// RefreshRangeRequest is arguments to the RefreshRange() method, which
// is similar to RefreshRequest (see comments above), but operates on
// a key span instead of a single key.
message RefreshRangeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // If set, indicates that the write timestamp cache should be
  // updated. This handles the case of DeleteRange, which must set the
  // write too old flag on transactions which attempt earlier writes.
  bool write = 2;
}

// RefreshRangeResponse is the response to a RefreshRange() operation.
message RefreshRangeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// SubsumeRequest is the argument to the Subsume() method, which freezes a range
// for merging with its left-hand neighbor.
//
// Subsume, when called correctly, provides important guarantees that ensure
// there is no moment in time where the ranges involved in the merge could both
// process commands for the same keys. See the comment on Subsume for details.
//
// Subsume may return stale MVCC statistics when used outside of a merge
// transaction. As a rule of thumb, it is incorrect to call Subsume, except from
// its carefully-chosen location within a merge transaction.
message SubsumeRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // The range descriptor for the left-hand side of the merge. Used by the
  // right-hand side to sanity-check the validity of the merge.
  RangeDescriptor left_range = 2 [(gogoproto.nullable) = false];
}

// SubsumeResponse is the response to a SubsumeRequest.
message SubsumeResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  reserved 2;

  // MVCCStats are the MVCC statistics for the range.
  storage.engine.enginepb.MVCCStats mvcc_stats = 3 [
    (gogoproto.nullable) = false,
    (gogoproto.customname) = "MVCCStats"
  ];

  // LeaseAppliedIndex is the lease index of the last applied command at the
  // time that the Subsume request executed.
  uint64 lease_applied_index = 4;

  // FreezeStart is a timestamp that is guaranteed to be greater than the
  // timestamps at which any requests were serviced by the responding replica
  // before it stopped responding to requests altogether (in anticipation of
  // being subsumed). It is suitable for use as the timestamp cache's low water
  // mark for the keys previously owned by the subsumed range.
  util.hlc.Timestamp freeze_start = 5 [(gogoproto.nullable) = false];
}

// RangeStatsRequest is the argument to the RangeStats() method. It requests the
// MVCC statistics of the receiving range.
message RangeStatsRequest {
  option (gogoproto.equal) = true;

  RequestHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

// RangeStatsResponse is the response to a RangeStatsRequest.
message RangeStatsResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];

  // MVCCStats are the MVCC statistics for the range that processed the
  // request.
  storage.engine.enginepb.MVCCStats mvcc_stats = 2 [
    (gogoproto.nullable) = false,
    (gogoproto.customname) = "MVCCStats"
  ];

  // QueriesPerSecond is the rate of request/s or QPS for the range.
  double queries_per_second = 3;
}

// A RequestUnion contains exactly one of the requests.
// The values added here must match those in ResponseUnion.
//
// Be cautious about deprecating fields as doing so can lead to inconsistencies
// between replicas.
message RequestUnion {
  oneof value {
    GetRequest get = 1;
    PutRequest put = 2;
    ConditionalPutRequest conditional_put = 3;
    IncrementRequest increment = 4;
    DeleteRequest delete = 5;
    DeleteRangeRequest delete_range = 6;
    ClearRangeRequest clear_range = 38;
    ScanRequest scan = 7;
    BeginTransactionRequest begin_transaction = 8;
    EndTransactionRequest end_transaction = 9;
    AdminSplitRequest admin_split = 10;
    AdminMergeRequest admin_merge = 11;
    AdminTransferLeaseRequest admin_transfer_lease = 29;
    AdminChangeReplicasRequest admin_change_replicas = 35;
    AdminRelocateRangeRequest admin_relocate_range = 45;
    HeartbeatTxnRequest heartbeat_txn = 12;
    GCRequest gc = 13;
    PushTxnRequest push_txn = 14;
    RecoverTxnRequest recover_txn = 46;
    ResolveIntentRequest resolve_intent = 16;
    ResolveIntentRangeRequest resolve_intent_range = 17;
    MergeRequest merge = 18;
    TruncateLogRequest truncate_log = 19;
    RequestLeaseRequest request_lease = 20;
    ReverseScanRequest reverse_scan = 21;
    ComputeChecksumRequest compute_checksum = 22;
    CheckConsistencyRequest check_consistency = 24;
    InitPutRequest init_put = 26;
    TransferLeaseRequest transfer_lease = 28;
    LeaseInfoRequest lease_info = 30;
    WriteBatchRequest write_batch = 31;
    ExportRequest export = 32;
    ImportRequest import = 34;
    QueryTxnRequest query_txn = 33;
    QueryIntentRequest query_intent = 42;
    AdminScatterRequest admin_scatter = 36;
    AddSSTableRequest add_sstable = 37;
    RecomputeStatsRequest recompute_stats = 39;
    RefreshRequest refresh = 40;
    RefreshRangeRequest refresh_range = 41;
    SubsumeRequest subsume = 43;
    RangeStatsRequest range_stats = 44;
  }
  reserved 15, 23, 25, 27;
}

// A ResponseUnion contains exactly one of the responses.
// The values added here must match those in RequestUnion.
message ResponseUnion {
  oneof value {
    GetResponse get = 1;
    PutResponse put = 2;
    ConditionalPutResponse conditional_put = 3;
    IncrementResponse increment = 4;
    DeleteResponse delete = 5;
    DeleteRangeResponse delete_range = 6;
    ClearRangeResponse clear_range = 38;
    ScanResponse scan = 7;
    BeginTransactionResponse begin_transaction = 8;
    EndTransactionResponse end_transaction = 9;
    AdminSplitResponse admin_split = 10;
    AdminMergeResponse admin_merge = 11;
    AdminTransferLeaseResponse admin_transfer_lease = 29;
    AdminChangeReplicasResponse admin_change_replicas = 35;
    AdminRelocateRangeResponse admin_relocate_range = 45;
    HeartbeatTxnResponse heartbeat_txn = 12;
    GCResponse gc = 13;
    PushTxnResponse push_txn = 14;
    RecoverTxnResponse recover_txn = 46;
    ResolveIntentResponse resolve_intent = 16;
    ResolveIntentRangeResponse resolve_intent_range = 17;
    MergeResponse merge = 18;
    TruncateLogResponse truncate_log = 19;
    RequestLeaseResponse request_lease = 20;
    ReverseScanResponse reverse_scan = 21;
    ComputeChecksumResponse compute_checksum = 22;
    CheckConsistencyResponse check_consistency = 24;
    InitPutResponse init_put = 26;
    LeaseInfoResponse lease_info = 30;
    WriteBatchResponse write_batch = 31;
    ExportResponse export = 32;
    ImportResponse import = 34;
    QueryTxnResponse query_txn = 33;
    QueryIntentResponse query_intent = 42;
    AdminScatterResponse admin_scatter = 36;
    AddSSTableResponse add_sstable = 37;
    RecomputeStatsResponse recompute_stats = 39;
    RefreshResponse refresh = 40;
    RefreshRangeResponse refresh_range = 41;
    SubsumeResponse subsume = 43;
    RangeStatsResponse range_stats = 44;
  }
  reserved 15, 23, 25, 27, 28;
}

// A Header is attached to a BatchRequest, encapsulating routing and auxiliary
// information required for executing it.
message Header {
  reserved 7;
  // timestamp specifies time at which read or writes should be
  // performed. If the timestamp is set to zero value, its value
  // is initialized to the wall time of the receiving node.
  util.hlc.Timestamp timestamp = 1 [(gogoproto.nullable) = false];
  // replica specifies the destination of the request.
  ReplicaDescriptor replica = 2 [(gogoproto.nullable) = false];
  // range_id specifies the ID of the Raft consensus group which the key
  // range belongs to. This is used by the receiving node to route the
  // request to the correct range.
  int64 range_id = 3 [(gogoproto.customname) = "RangeID", (gogoproto.casttype) = "RangeID"];
  // user_priority allows any command's priority to be biased from the
  // default random priority. It specifies a multiple. If set to 0.5,
  // the chosen priority will be 1/2x as likely to beat any default
  // random priority. If set to 1, a default random priority is
  // chosen. If set to 2, the chosen priority will be 2x as likely to
  // beat any default random priority, and so on. As a special case, 0
  // priority is treated the same as 1. This value is ignored if txn
  // is specified. The min and max user priorities are set via
  // MinUserPriority and MaxUserPriority in data.go.
  double user_priority = 4 [(gogoproto.casttype) = "UserPriority"];
  // txn is set non-nil if a transaction is underway. To start a txn,
  // the first request should set this field to non-nil with name and
  // isolation level set as desired. The response will contain the
  // fully-initialized transaction with txn ID, priority, initial
  // timestamp, and maximum timestamp.
  Transaction txn = 5;
  // read_consistency specifies the consistency for read
  // operations. The default is CONSISTENT. This value is ignored for
  // write operations.
  ReadConsistencyType read_consistency = 6;
  // If set to a non-zero value, it limits the total number of keys touched
  // by span requests in the batch. Span requests are requests like
  // Scan, ReverseScan, and DelRange. If two requests touch the
  // same key it is double counted.
  //
  // If a batch limit is used with Scan requests, the spans for the requests
  // must be non-overlapping and in increasing order.
  //
  // If a batch limit is used with ReverseScan requests, the spans for the
  // requests must be non-overlapping and in decreasing order.
  int64 max_span_request_keys = 8;
  // If set, all of the spans in the batch are distinct. Note that the
  // calculation of distinct spans does not include intents in an
  // EndTransactionRequest. Currently set conservatively: a request
  // might be composed of distinct spans yet have this field set to
  // false.
  bool distinct_spans = 9;
  // If set, return_range_info causes RangeInfo details to be returned with
  // each ResponseHeader.
  bool return_range_info = 10;
  // gateway_node_id is the ID of the gateway node where the request originated.
  int32 gateway_node_id = 11 [(gogoproto.customname) = "GatewayNodeID", (gogoproto.casttype) = "NodeID"];
  ScanOptions scan_options = 12;
  // If set, the request will return to the client before proposing the
  // request into Raft. All consensus processing will be performed
  // asynchronously. Because consensus may fail, this means that the
  // request cannot be expected to succeed. Instead, its success must
  // be verified.
  // TODO(nvanbenschoten): Handling cases where consensus fails would
  // be much more straightforward if all transactional requests were
  // idempotent. We could just re-issue requests. See #26915.
  bool async_consensus = 13;
}


// A BatchRequest contains one or more requests to be executed in
// parallel, or if applicable (based on write-only commands and
// range-locality), as a single update.
message BatchRequest {
  option (gogoproto.goproto_stringer) = false;

  Header header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated RequestUnion requests = 2 [(gogoproto.nullable) = false];
}

// A BatchResponse contains one or more responses, one per request
// corresponding to the requests in the matching BatchRequest. The
// error in the response header is set to the first error from the
// slice of responses, if applicable.
message BatchResponse {
  option (gogoproto.goproto_stringer) = false;

  message Header {
    reserved 4;
    // error communicates a structured error (i.e. one originating from a Node)
    // while the BatchResponse is sent over the network. If the code were
    // written today, the RPC endpoint would return a message containing both a
    // BatchResponse and an Error, and this embedding would go away. However, it
    // returns only a BatchResponse, and so the Error needs to be tucked away
    // somewhere (the structured error cannot be communicated via an RPC-level
    // error).
    //
    // Outside of the RPC boundaries, this field is nil and must neither be
    // checked nor populated (it is reset by the DistSender, which extracts this
    // error and returns it separately). In effect, nearly no usage of
    // BatchResponse needs to care about this field.
    Error error = 1;
    // timestamp is set only for non-transactional responses and denotes the
    // timestamp at which the batch executed. The timestamp cache is updated
    // at this timestamp.
    util.hlc.Timestamp Timestamp = 2 [(gogoproto.nullable) = false];
    // txn is non-nil if the request specified a non-nil
    // transaction. The transaction timestamp and/or priority may have
    // been updated, depending on the outcome of the request.
    Transaction txn = 3;
    // now is the highest current time from any node contacted during the request.
    // It can be used by the receiver to update its local HLC.
    util.hlc.Timestamp now = 5 [(gogoproto.nullable) = false];
    // collected_spans stores trace spans recorded during the execution of this
    // request.
    repeated util.tracing.RecordedSpan collected_spans = 6 [(gogoproto.nullable) = false];
    // NB: if you add a field here, don't forget to update combine().
  }
  Header header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated ResponseUnion responses = 2 [(gogoproto.nullable) = false];
}

// RangeFeedRequest is a request that expresses the intention to establish a
// RangeFeed stream over the provided span, starting at the specified timestamp.
message RangeFeedRequest {
  Header header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  Span   span   = 2 [(gogoproto.nullable) = false];
}

// RangeFeedValue is a variant of RangeFeedEvent that represents an update to
// the specified key with the provided value.
message RangeFeedValue {
  bytes key   = 1 [(gogoproto.casttype) = "Key"];
  Value value = 2 [(gogoproto.nullable) = false];
}

// RangeFeedCheckpoint is a variant of RangeFeedEvent that represents the
// promise that no more RangeFeedValue events with keys in the specified span
// with timestamps less than or equal to the specified resolved timestamp will
// be emitted on the RangeFeed response stream.
message RangeFeedCheckpoint {
  Span               span        = 1 [(gogoproto.nullable) = false];
  util.hlc.Timestamp resolved_ts = 2 [
    (gogoproto.nullable) = false, (gogoproto.customname) = "ResolvedTS"];
}

// RangeFeedError is a variant of RangeFeedEvent that indicates that an error
// occurred during the processing of the RangeFeed. If emitted, a RangeFeedError
// event will always be the final event on a RangeFeed response stream before
// it is torn down.
message RangeFeedError {
  Error error = 1 [(gogoproto.nullable) = false];
}

// RangeFeedEvent is a union of all event types that may be returned on a
// RangeFeed response stream.
message RangeFeedEvent {
  option (gogoproto.onlyone) = true;

  RangeFeedValue      val        = 1;
  RangeFeedCheckpoint checkpoint = 2;
  RangeFeedError      error      = 3;
}

// Batch and RangeFeed service implemeted by nodes for KV API requests.
service Internal {
  rpc Batch     (BatchRequest)     returns (BatchResponse)         {}
  rpc RangeFeed (RangeFeedRequest) returns (stream RangeFeedEvent) {}
}