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/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;
  // CONSENSUS requires that reads must achieve consensus. This is a
  // stronger guarantee of consistency than CONSISTENT.
  //
  // TODO(spencer): current unimplemented.
  CONSENSUS = 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];
}

// 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 scan didn't finish because the key limit was hit for the batch.
    RESUME_KEY_LIMIT = 1;
    // The scan didn't finish because a range boundary was hit and the batch
    // asked to be stopped 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 v1.2. Responses from storage coming from older
  // servers will not contain it, but the DistSender 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;

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

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

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

  Span 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 error and the actual value of the key in the response.
message ConditionalPutRequest {
  option (gogoproto.equal) = true;

  Span 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;
}

// 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;

  Span 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;

  Span 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;

  Span 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;

  Span 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.
//
// 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;

  Span header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  util.hlc.Timestamp gc_threshold = 2 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "GCThreshold"];
  Span suggested_compaction = 3 [(gogoproto.nullable) = false];
}

// 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;
}

// 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;

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

  // Set to true if the KeyValue pairs for all intents encountered during the
  // scan should also be returned. An error will be thrown if this is set to
  // true for a consistent scan.
  bool return_intents = 3;
}

// 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];
  // Empty if return_intents was not set to true of if no intent rows were
  // scanned. These rows do not count against the MaxSpanRequestKeys count.
  repeated KeyValue intent_rows = 3 [(gogoproto.nullable) = false];
}

// 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;

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

  // Set to true if the KeyValue pairs for all intents encountered during the
  // scan should also be returned. An error will be thrown if this is set to
  // true for a consistent scan.
  bool return_intents = 3;
}

// 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];
  // Empty if return_intents was not set to true of if no intent rows were
  // scanned. These rows do not count against the MaxSpanRequestKeys count.
  repeated KeyValue intent_rows = 3 [(gogoproto.nullable) = false];
}

// 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;

  Span header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // log a diff of inconsistencies if such inconsistencies are found.
  bool with_diff = 2;
}

// A CheckConsistencyResponse is the return value from the CheckConsistency() method.
// If a replica finds itself to be inconsistent with its lease holder it will panic.
message CheckConsistencyResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
}

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

  Span 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;

  Span header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  // False to abort and rollback.
  bool commit = 2;
  // If set, deadline represents the maximum timestamp at which the transaction
  // can commit (i.e. the maximum timestamp for the txn's 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.
  // N.B. Assuming that the deadline was valid to begin with (i.e. it was higher
  // than the txn's OrigTimestamp), only Snapshot transactions can get in
  // trouble with the deadline check. A Serializable txn that has had its
  // timestamp pushed has already lost before the deadline check: it will be
  // forced to restart.
  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.
  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"];
}

// 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. sequence cache and range stats must be copied or
// recomputed).
message AdminSplitRequest {
  option (gogoproto.equal) = true;

  Span 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;

  Span 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;

  Span 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;

  Span header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  ReplicaChangeType change_type = 2;
  repeated ReplicationTarget targets = 3 [(gogoproto.nullable) = false];
}

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

// A RangeLookupRequest is arguments to the RangeLookup() method. A
// forward lookup request returns a range containing the requested
// key. A reverse lookup request returns a range containing the
// previous key of the requested key (e.g., if a requested key is the
// end key of range R, the reverse lookup request returns R).
//
// RangeLookupRequest also specifies the maximum number of range
// descriptors that should be returned, if there are additional
// consecutive addressable ranges. Specify max_ranges > 1 to pre-fill the
// range descriptor cache. The additional ranges are scanned in the same
// direction as lookup (forward v.s. reverse).
message RangeLookupRequest {
  option (gogoproto.equal) = true;

  Span header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  int32 max_ranges = 2;
  reserved 3;
  // Use a reverse scan to pre-fill the range descriptor cache instead
  // of an ascending scan.
  bool reverse = 4;
}

// A RangeLookupResponse is the return value from the RangeLookup()
// method. It returns metadata for the range containing the requested
// key, optionally returning the metadata for additional consecutive
// ranges beyond the requested range to pre-fill the range descriptor
// cache.
message RangeLookupResponse {
  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated RangeDescriptor ranges = 2 [(gogoproto.nullable) = false];
  repeated RangeDescriptor prefetched_ranges = 3 [(gogoproto.nullable) = false];
}

// 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;

  Span 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;

  Span 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).
  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];
}

// TxnPushType 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;
  // Deprecated. Use QueryTxn instead.
  PUSH_QUERY = 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;

  Span 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 just after which PusheeTxn is attempted to be
  // pushed. During conflict resolution, it should be set to the timestamp
  // of the its conflicting write.
  util.hlc.Timestamp push_to = 4 [(gogoproto.nullable) = false];
  // Now holds the timestamp used to compare the last heartbeat of the pushee
  // against. This is necessary since the request header's timestamp does not
  // necessarily advance with the node clock across retries and hence cannot
  // detect abandoned transactions.
  util.hlc.Timestamp 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 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 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;

  Span 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 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;

  Span 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 sequence cache 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;

  Span 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 sequence cache for the transaction on all ranges
  // on which the intents reside.
  bool poison = 4;
}

// A NoopResponse is the return value from a no-op operation.
message NoopResponse {}

// A NoopRequest is a no-op.
message NoopRequest {}

// 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;

  Span 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;

  Span 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;

  Span 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];
}

// 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;

  Span 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;

  Span 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;

  Span 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;
  // A unique identifier to match a future storage.CollectChecksumRequest with
  // this request.
  bytes checksum_id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ChecksumID",
      (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID"];
  // 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;
}

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

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

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

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

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

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

  ExportStorageProvider provider = 1;

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

    string path = 1;
  }
  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;
  }
  message Azure {
    option (gogoproto.equal) = true;

    string container = 1;
    string prefix = 2;

    string account_name = 3;
    string account_key = 4;
  }
  LocalFilePath LocalFile = 2 [(gogoproto.nullable) = false];
  Http HttpPath = 3 [(gogoproto.nullable) = false];
  GCS GoogleCloudConfig = 4;
  S3 S3Config = 5;
  Azure AzureConfig = 6;
}

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

  Span 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;

  Span 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"];
}

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];
  }

  ResponseHeader header = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
  repeated File files = 2 [(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;
  }
  Span 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;

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

// 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;

  Span 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];
}

// A RequestUnion contains exactly one of the requests.
// The values added here must match those in ResponseUnion.
//
// WARNING: Do not remove fields from RequestUnion. Instead, remove
// all non-header fields from the request message and prepend its
// name with "Deprecated". See DeprecatedVerifyChecksumRequest for an
// example.
//
// Be cautious about deprecating fields as doing so can lead to inconsistencies
// between replicas.
message RequestUnion {
  option (gogoproto.onlyone) = true;

  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;
  HeartbeatTxnRequest heartbeat_txn = 12;
  GCRequest gc = 13;
  PushTxnRequest push_txn = 14;
  RangeLookupRequest range_lookup = 15;
  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;
  DeprecatedVerifyChecksumRequest deprecated_verify_checksum = 23;
  CheckConsistencyRequest check_consistency = 24;
  NoopRequest noop = 25;
  InitPutRequest init_put = 26;
  reserved 27;
  TransferLeaseRequest transfer_lease = 28;
  LeaseInfoRequest lease_info = 30;
  WriteBatchRequest write_batch = 31;
  ExportRequest export = 32;
  ImportRequest import = 34;
  QueryTxnRequest query_txn = 33;
  AdminScatterRequest admin_scatter = 36;
  AddSSTableRequest add_sstable = 37;
}

// A ResponseUnion contains exactly one of the responses.
// The values added here must match those in RequestUnion.
//
// WARNING: Do not remove fields from ResponseUnion. Instead, remove
// all non-header fields from the response message and prepend its
// name with "Deprecated". See DeprecatedVerifyChecksumResponse for an
// example.
message ResponseUnion {
  option (gogoproto.onlyone) = true;

  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;
  HeartbeatTxnResponse heartbeat_txn = 12;
  GCResponse gc = 13;
  PushTxnResponse push_txn = 14;
  RangeLookupResponse range_lookup = 15;
  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;
  DeprecatedVerifyChecksumResponse deprecated_verify_checksum = 23;
  CheckConsistencyResponse check_consistency = 24;
  NoopResponse noop = 25;
  InitPutResponse init_put = 26;
  reserved 27;
  reserved 28; // TransferLease and RequestLease both use RequestLeaseResponse
  LeaseInfoResponse lease_info = 30;
  WriteBatchResponse write_batch = 31;
  ExportResponse export = 32;
  ImportResponse import = 34;
  QueryTxnResponse query_txn = 33;
  AdminScatterResponse admin_scatter = 36;
  AddSSTableResponse add_sstable = 37;
}

// 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;
}


// 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 is non-nil if an error occurred.
    Error error = 1;
    // timestamp is set only for non-transactional responses and denotes the
    // highest timestamp at which a command from the batch executed. At the
    // time of writing, it is used solely for informational purposes and tests.
    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];
}

// The two Batch services below are identical, except that some internal
// Request types are not permitted in batches processed by External.Batch. This
// distinction exists e.g. to prevent command-line tools from accessing
// internal-only RPC methods.

service Internal {
  rpc Batch (BatchRequest) returns (BatchResponse) {}
}

service External {
  rpc Batch (BatchRequest) returns (BatchResponse) {}
}