errors.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.
//
// Author: Spencer Kimball (spencer.kimball@gmail.com)

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

import "cockroach/pkg/roachpb/metadata.proto";
import "cockroach/pkg/roachpb/data.proto";
import "cockroach/pkg/util/hlc/timestamp.proto";
import "gogoproto/gogo.proto";

// Issue #1246. Commented out because
// https://github.com/golang/protobuf/commit/d3d78384b82d449651d2435ed3
// requires that all messages implement Message, which includes
// `String() string`.
// option (gogoproto.goproto_stringer_all) = false;

// A NotLeaseHolderError indicates that the current range is not the lease
// holder. If the lease holder is known, its Replica is set in the error.
message NotLeaseHolderError {
  // The replica the error originated from. Used in the error's string
  // representation.
  optional ReplicaDescriptor replica = 1 [(gogoproto.nullable) = false];
  // The lease holder, if known.
  optional ReplicaDescriptor lease_holder = 2;
  // The current lease, if known. This might be nil even when lease_holder is
  // set, as sometimes one can create this error without actually knowing the
  // current lease, but having a guess about who the leader is.
  optional Lease lease = 4;
  optional int64 range_id = 3 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "RangeID", (gogoproto.casttype) = "RangeID"];
  // If set, the Error() method will return this instead of composing its
  // regular spiel. Useful because we reuse this error when rejecting a command
  // because the lease under which its application was attempted is different
  // than the lease under which it had been proposed.
  optional string custom_msg = 5 [(gogoproto.nullable) = false];
}

// A NodeUnavailableError indicates that the sending gateway can
// not process requests at the time, and that the client should
// retry the request with another peer.
message NodeUnavailableError {
}

// A RangeNotFoundError indicates that a command was sent to a range
// which is not hosted on this store.
message RangeNotFoundError {
  optional int64 range_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "RangeID", (gogoproto.casttype) = "RangeID"];
}

// A RangeKeyMismatchError indicates that a command was sent to a
// range which did not contain the key(s) specified by the command.
message RangeKeyMismatchError {
  optional bytes request_start_key = 1 [(gogoproto.casttype) = "Key"];
  optional bytes request_end_key = 2 [(gogoproto.casttype) = "Key"];
  // mismatched_range is the range that the command was incorrectly sent to.
  // It is used to update the sender's range cache without an additional range
  // lookup.
  optional RangeDescriptor mismatched_range = 3;
  // suggested_range is a hint to the sender of a command about the range
  // they may be looking for. It is only populated when the recipient has
  // authoritative knowledge of the range requested by the sender.
  optional RangeDescriptor suggested_range = 4;
}

// A ReadWithinUncertaintyIntervalError indicates that a read at timestamp
// encountered a write within the uncertainty interval of the reader.
// The read should be retried at a higher timestamp; the timestamps contained
// within are purely informational, though typically existing_timestamp is a
// lower bound for a new timestamp at which at least the read producing
// this error would succeed on retry.
message ReadWithinUncertaintyIntervalError {
  optional util.hlc.Timestamp read_timestamp = 1 [(gogoproto.nullable) = false];
  optional util.hlc.Timestamp existing_timestamp = 2 [(gogoproto.nullable) = false];
}

// A TransactionAbortedError indicates that the transaction was aborted by
// another concurrent transaction. Upon seeing this error, the client is
// supposed to reset its Transaction proto and try the transaction again.
//
// In contrast with other errors, the Transaction that the client gets in the
// pErr carrying this ErrorDetail is not supposed to be used by the client,
// besides checking that the transaction's ID is right.
message TransactionAbortedError {
}

// A TransactionPushError indicates that the transaction could not
// continue because it encountered a write intent from another
// transaction which it was unable to push.
message TransactionPushError {
  optional Transaction pushee_txn = 1 [(gogoproto.nullable) = false];
}

// A TransactionRetryError indicates that the transaction must be
// retried, usually with an increased transaction timestamp.
message TransactionRetryError {
}

// A TransactionReplayError indicates that a BeginTransaction request
// is being replayed. This can happen on network replays in which a
// BeginTransaction request is sent again either from the client or
// is belatedly delivered after an earlier attempt succeeded.
message TransactionReplayError {
}

// A TransactionStatusError indicates that the transaction status is
// incompatible with the requested operation. This might mean the
// transaction has already been committed. It might also be the case
// that the request to modify the transaction failed due to a
// regression in transaction epoch or timestamp, both of which may
// only monotonically increase.
message TransactionStatusError {
  optional string msg = 1 [(gogoproto.nullable) = false];
}

// A WriteIntentError indicates that one or more write intent
// belonging to another transaction were encountered leading to a
// read/write or write/write conflict. The keys at which the intent
// was encountered are set, as are the txn records for the intents'
// transactions.
message WriteIntentError {
  repeated Intent intents = 1 [(gogoproto.nullable) = false];
  reserved 2;
}

// A WriteTooOldError indicates that a write encountered a versioned
// value newer than its timestamp, making it impossible to rewrite
// history. The write is instead done at actual timestamp, which is
// the timestamp of the existing version+1.
message WriteTooOldError {
  optional util.hlc.Timestamp timestamp = 1 [(gogoproto.nullable) = false];
  optional util.hlc.Timestamp actual_timestamp = 2 [(gogoproto.nullable) = false];
}

// An OpRequiresTxnError indicates that a command required to be
// carried out in a transactional context but was not.
// For example, a Scan which spans ranges requires a transaction.
// The operation should be retried inside of a transaction.
message OpRequiresTxnError {
}

// A ConditionFailedError indicates that the expected value
// of a ConditionalPutRequest was not found, either
// because it was missing or was not equal. The error will
// contain the actual value found.
message ConditionFailedError {
  optional Value actual_value = 1;
}

// A LeaseRejectedError indicates that the requested replica could
// not acquire the desired lease because of an existing range lease.
message LeaseRejectedError {
  optional string message = 1 [(gogoproto.nullable) = false];
  optional Lease requested = 2 [(gogoproto.nullable) = false];
  optional Lease existing = 3 [(gogoproto.nullable) = false];
}

// A SendError indicates that a message could not be delivered to
// the desired recipient(s).
message SendError {
  optional string message = 1 [(gogoproto.nullable) = false];
  reserved 2;
}

// An AmbiguousResultError indicates that a request may have succeeded or
// failed, but the response was not received and the final result is ambiguous.
message AmbiguousResultError {
  optional string message = 1 [(gogoproto.nullable) = false];
  // This can be set to give extra information about which error was converted
  // into an AmbiguousResultError. Useful for tests.
  optional Error wrapped_err = 2;
}

// A RaftGroupDeletedError indicates a raft group has been deleted for
// the replica.
message RaftGroupDeletedError {
}

// A ReplicaCorruptionError indicates that the replica has experienced
// an error which puts its integrity at risk.
message ReplicaCorruptionError {
  optional string error_msg = 1 [(gogoproto.nullable) = false];;
  // processed indicates that the error has been taken into account and
  // necessary steps will be taken. For now, required for testing.
  optional bool processed = 2 [(gogoproto.nullable) = false];;
}

// ReplicaTooOldError is sent in response to a raft message when the
// recipient of the raft message believes the sender of the raft
// message to have been removed from the raft group
message ReplicaTooOldError {
  // replica_id is the ID of the replica that is too old.
  optional int32 replica_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "ReplicaID", (gogoproto.casttype) = "ReplicaID"];
}

// A StoreNotFoundError indicates that a command was sent to a store
// which is not hosted on this node.
message StoreNotFoundError {
  optional int64 store_id = 1 [(gogoproto.nullable) = false,
      (gogoproto.customname) = "StoreID", (gogoproto.casttype) = "StoreID"];
}

// ErrorDetail is a union type containing all available errors.
message ErrorDetail {
  option (gogoproto.onlyone) = true;

  optional NotLeaseHolderError not_lease_holder = 1;
  optional RangeNotFoundError range_not_found = 2;
  optional RangeKeyMismatchError range_key_mismatch = 3;
  optional ReadWithinUncertaintyIntervalError read_within_uncertainty_interval = 4;
  optional TransactionAbortedError transaction_aborted = 5;
  optional TransactionPushError transaction_push = 6;
  optional TransactionRetryError transaction_retry = 7;
  optional TransactionReplayError transaction_replay = 22;
  optional TransactionStatusError transaction_status = 8;
  optional WriteIntentError write_intent = 9;
  optional WriteTooOldError write_too_old = 10;
  optional OpRequiresTxnError op_requires_txn = 11;
  optional ConditionFailedError condition_failed = 12;
  optional LeaseRejectedError lease_rejected = 13;
  optional NodeUnavailableError node_unavailable = 14;
  optional SendError send = 15;
  reserved 25;
  optional AmbiguousResultError ambiguous_result = 26;
  optional StoreNotFoundError store_not_found = 27;
  optional HandledRetryableError handled_retryable_error = 28;

  // TODO(kaneda): Following are added to preserve the type when
  // converting Go errors from/to proto Errors. Revisit this design.
  optional RaftGroupDeletedError raft_group_deleted = 16;
  optional ReplicaCorruptionError replica_corruption = 17;
  optional ReplicaTooOldError replica_too_old = 18;
}

// TransactionRestart indicates how an error should be handled in a
// transactional context.
enum TransactionRestart {
  //  NONE (the default) is used for errors which have no effect on the
  //  transaction state. That is, a transactional operation which receives such
  //  an error is still PENDING and does not need to restart (at least not as a
  //  result of the error). Examples are a CPut whose condition wasn't met, or
  //  a spurious RPC error.
  NONE = 0;

  // BACKOFF is for errors that can retried by restarting the transaction
  // after an exponential backoff.
  // Note: Deprecated.
  BACKOFF = 1;

  // IMMEDIATE is for errors that can be retried by restarting the
  // transaction immediately.
  IMMEDIATE = 2;
}

// ErrPosition describes the position of an error in a Batch. A simple nullable
// primitive field would break compatibility with proto3, where primitive fields
// are no longer allowed to be nullable.
message ErrPosition {
  optional int32 index = 1 [(gogoproto.nullable) = false];
}

// Error is a generic representation including a string message
// and information about retryability.
message Error {
  option (gogoproto.goproto_stringer) = false;

  // message is a human-readable error message.
  optional string message = 1 [(gogoproto.nullable) = false];

  // If transaction_restart is not ABORT, the error condition may be handled by
  // restarting the transaction.
  optional TransactionRestart transaction_restart = 3 [(gogoproto.nullable) = false];

  // An optional updated transaction. This is to be used by the client in case
  // of retryable errors.
  //
  // Not to be accessed directly - use Error.GetTxn().
  optional Transaction unexposed_txn = 4;

  // Node at which the error was generated (zero if does not apply).
  optional int32 origin_node = 5 [(gogoproto.nullable) = false, (gogoproto.casttype) = "NodeID" ];

  // If an ErrorDetail is present, it may contain additional structured data
  // about the error.
  optional ErrorDetail detail = 6;

  // The index, if given, contains the index of the request (in the batch)
  // whose execution caused the error.
  optional ErrPosition index = 7;

  // now is the current time at the node sending the response,
  // which can be used by the receiver to update its local HLC.
  optional util.hlc.Timestamp now = 8 [(gogoproto.nullable) = false];

  reserved 2;
}

// InternalRetryableTxnError tells the recipient that the transaction it
// attempted to use to perform an operation must be retried. This is returned
// generally as a result of a transaction conflict.
//
// This is not an ErrorDetail; it is a higher-level error than a pErr. It is
// created based details such as TransactionRetryError or
// TransactionAbortedError. It implements the go error interface and is used by
// the TxnCoordSender and DistSQL. It is a proto because DistSQL needs to send
// it over the wire. It needs to be in this package because it both depends on
// and is depended on by roachpb.
//
// The TxnCoordSender will transform this into a HandledRetryableError (an
// ErrorDetail), so that restart information can be passed to the next layer up
// (the client.Txn) through the client.Sender() interface.
message InternalRetryableTxnError {
  // A user-readable message.
  optional string msg = 1 [(gogoproto.nullable) = false];

  // The ID of the transaction being restarted. The client is supposed to check
  // this against the ID of its transaction and make sure the retryable error
  // is meant for its level and didn't escape from some inner transaction.
  //
  // TODO(andrei): make this non-nullable (and thus required) if we manage to
  // make Transaction.ID non-nullable.
  optional bytes txn_id = 2 [
    (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID",
    (gogoproto.customname) = "TxnID"];

  // The Transaction that the client is supposed to use for the next attempt.
  // If not set, the client is supposed to use a brand new Transaction. This is
  // set by all retryable errors except TransactionAbortedError to communicate
  // the new timestamp and epoch for the next attempt.
  //
  // When retrying, a client is supposed to call Transaction.Restart() on
  // this transaction.
  optional Transaction transaction = 3;

  // The fields below are filled in when "transaction" is not present (i.e. as a
  // result of a TransactionAbortedError). They're supposed to be
  // used with the Transaction.Restart() call. If transaction is not set, these
  // will also not be set.
  //
  // NOTE(andrei): I think a better design would be for the server to always be
  // in charge of updating the Transaction to the final form in which it should
  // be used by the client. I couldn't easily do that, though, due to the
  // current mechanics through which pErrs and their details are partially
  // filled in by multiple layers.
  // I've also tried to apply these fields to the transaction in pErr.GoError().
  // The problem I hit in doing that was that Transaction.Restart() needs a
  // request's UserPriority, and pErr.GoError() doesn't have a request.

  // If set, this is a lower-bound on the priority of the restarted transaction.
  // This can only be set if transaction is not set.
  optional int32 retry_priority = 4;
  // If set, a retry should use this timestamp.
  optional util.hlc.Timestamp retry_timestamp = 5;
}

// HandledRetryableError is an error detail representing a retryable error that
// has been "handled" by the TxnCoordSender. This contains the final form of
// the Transaction proto that should be used on next attempts. This error is
// handled by the client.Txn, which transforms it into a RetryableTxnError.
message HandledRetryableError {
  // A user-readable message.
  optional string msg = 1 [(gogoproto.nullable) = false];

  // The ID of the transaction being restarted. The client is supposed to check
  // this against the ID of its transaction and make sure the retryable error
  // is meant for its level and didn't escape from some inner transaction.
  //
  // TODO(andrei): make this non-nullable (and thus required) if we manage to
  // make Transaction.ID non-nullable.
  optional bytes txn_id = 2 [
    (gogoproto.customtype) = "github.com/cockroachdb/cockroach/pkg/util/uuid.UUID",
    (gogoproto.customname) = "TxnID"];

  // The Transaction that should be used by next attempts. Depending on the
  // original cause of this method, this can either be the same Transaction as
  // before, but with an incremented epoch and timestamp, or a completely new
  // Transaction.
  optional Transaction transaction = 3;
}