itess.client.1.2.0.source-code.vtrpc.proto Maven / Gradle / Ivy
The newest version!
// This file contains useful data structures for RPCs in Vitess.
syntax = "proto3";
option java_package="com.youtube.vitess.proto";
package vtrpc;
// CallerID is passed along RPCs to identify the originating client
// for a request. It is not meant to be secure, but only
// informational. The client can put whatever info they want in these
// fields, and they will be trusted by the servers. The fields will
// just be used for logging purposes, and to easily find a client.
// VtGate propagates it to VtTablet, and VtTablet may use this
// information for monitoring purposes, to display on dashboards, or
// for blacklisting purposes.
message CallerID {
// principal is the effective user identifier. It is usually filled in
// with whoever made the request to the appserver, if the request
// came from an automated job or another system component.
// If the request comes directly from the Internet, or if the Vitess client
// takes action on its own accord, it is okay for this field to be absent.
string principal = 1;
// component describes the running process of the effective caller.
// It can for instance be the hostname:port of the servlet initiating the
// database call, or the container engine ID used by the servlet.
string component = 2;
// subcomponent describes a component inisde the immediate caller which
// is responsible for generating is request. Suggested values are a
// servlet name or an API endpoint name.
string subcomponent = 3;
}
// Code represents canonical error codes. The names, numbers and comments
// must match the ones defined by grpc:
// https://godoc.org/google.golang.org/grpc/codes.
enum Code {
// OK is returned on success.
OK = 0;
// CANCELED indicates the operation was cancelled (typically by the caller).
CANCELED = 1;
// UNKNOWN error. An example of where this error may be returned is
// if a Status value received from another address space belongs to
// an error-space that is not known in this address space. Also
// errors raised by APIs that do not return enough error information
// may be converted to this error.
UNKNOWN = 2;
// INVALID_ARGUMENT indicates client specified an invalid argument.
// Note that this differs from FAILED_PRECONDITION. It indicates arguments
// that are problematic regardless of the state of the system
// (e.g., a malformed file name).
INVALID_ARGUMENT = 3;
// DEADLINE_EXCEEDED means operation expired before completion.
// For operations that change the state of the system, this error may be
// returned even if the operation has completed successfully. For
// example, a successful response from a server could have been delayed
// long enough for the deadline to expire.
DEADLINE_EXCEEDED = 4;
// NOT_FOUND means some requested entity (e.g., file or directory) was
// not found.
NOT_FOUND = 5;
// ALREADY_EXISTS means an attempt to create an entity failed because one
// already exists.
ALREADY_EXISTS = 6;
// PERMISSION_DENIED indicates the caller does not have permission to
// execute the specified operation. It must not be used for rejections
// caused by exhausting some resource (use RESOURCE_EXHAUSTED
// instead for those errors). It must not be
// used if the caller cannot be identified (use Unauthenticated
// instead for those errors).
PERMISSION_DENIED = 7;
// UNAUTHENTICATED indicates the request does not have valid
// authentication credentials for the operation.
UNAUTHENTICATED = 16;
// RESOURCE_EXHAUSTED indicates some resource has been exhausted, perhaps
// a per-user quota, or perhaps the entire file system is out of space.
RESOURCE_EXHAUSTED = 8;
// FAILED_PRECONDITION indicates operation was rejected because the
// system is not in a state required for the operation's execution.
// For example, directory to be deleted may be non-empty, an rmdir
// operation is applied to a non-directory, etc.
//
// A litmus test that may help a service implementor in deciding
// between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
// (a) Use UNAVAILABLE if the client can retry just the failing call.
// (b) Use ABORTED if the client should retry at a higher-level
// (e.g., restarting a read-modify-write sequence).
// (c) Use FAILED_PRECONDITION if the client should not retry until
// the system state has been explicitly fixed. E.g., if an "rmdir"
// fails because the directory is non-empty, FAILED_PRECONDITION
// should be returned since the client should not retry unless
// they have first fixed up the directory by deleting files from it.
// (d) Use FAILED_PRECONDITION if the client performs conditional
// REST Get/Update/Delete on a resource and the resource on the
// server does not match the condition. E.g., conflicting
// read-modify-write on the same resource.
FAILED_PRECONDITION = 9;
// ABORTED indicates the operation was aborted, typically due to a
// concurrency issue like sequencer check failures, transaction aborts,
// etc.
//
// See litmus test above for deciding between FAILED_PRECONDITION,
// ABORTED, and UNAVAILABLE.
ABORTED = 10;
// OUT_OF_RANGE means operation was attempted past the valid range.
// E.g., seeking or reading past end of file.
//
// Unlike INVALID_ARGUMENT, this error indicates a problem that may
// be fixed if the system state changes. For example, a 32-bit file
// system will generate INVALID_ARGUMENT if asked to read at an
// offset that is not in the range [0,2^32-1], but it will generate
// OUT_OF_RANGE if asked to read from an offset past the current
// file size.
//
// There is a fair bit of overlap between FAILED_PRECONDITION and
// OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific
// error) when it applies so that callers who are iterating through
// a space can easily look for an OUT_OF_RANGE error to detect when
// they are done.
OUT_OF_RANGE = 11;
// UNIMPLEMENTED indicates operation is not implemented or not
// supported/enabled in this service.
UNIMPLEMENTED = 12;
// INTERNAL errors. Means some invariants expected by underlying
// system has been broken. If you see one of these errors,
// something is very broken.
INTERNAL = 13;
// UNAVAILABLE indicates the service is currently unavailable.
// This is a most likely a transient condition and may be corrected
// by retrying with a backoff.
//
// See litmus test above for deciding between FAILED_PRECONDITION,
// ABORTED, and UNAVAILABLE.
UNAVAILABLE = 14;
// DATA_LOSS indicates unrecoverable data loss or corruption.
DATA_LOSS = 15;
}
// LegacyErrorCode is the enum values for Errors. This type is deprecated.
// Use Code instead. Background: In the initial design, we thought
// that we may end up with a different list of canonical error codes
// than the ones defined by grpc. In hindisght, we realize that
// the grpc error codes are fairly generic and mostly sufficient.
// In order to avoid confusion, this type will be deprecated in
// favor of the new Code that matches exactly what grpc defines.
// Some names below have a _LEGACY suffix. This is to prevent
// name collisions with Code.
enum LegacyErrorCode {
// SUCCESS_LEGACY is returned from a successful call.
SUCCESS_LEGACY = 0;
// CANCELLED_LEGACY means that the context was cancelled (and noticed in the app layer,
// as opposed to the RPC layer).
CANCELLED_LEGACY = 1;
// UNKNOWN_ERROR_LEGACY includes:
// 1. MySQL error codes that we don't explicitly handle.
// 2. MySQL response that wasn't as expected. For example, we might expect a MySQL
// timestamp to be returned in a particular way, but it wasn't.
// 3. Anything else that doesn't fall into a different bucket.
UNKNOWN_ERROR_LEGACY = 2;
// BAD_INPUT_LEGACY is returned when an end-user either sends SQL that couldn't be parsed correctly,
// or tries a query that isn't supported by Vitess.
BAD_INPUT_LEGACY = 3;
// DEADLINE_EXCEEDED_LEGACY is returned when an action is taking longer than a given timeout.
DEADLINE_EXCEEDED_LEGACY = 4;
// INTEGRITY_ERROR_LEGACY is returned on integrity error from MySQL, usually due to
// duplicate primary keys.
INTEGRITY_ERROR_LEGACY = 5;
// PERMISSION_DENIED_LEGACY errors are returned when a user requests access to something
// that they don't have permissions for.
PERMISSION_DENIED_LEGACY = 6;
// RESOURCE_EXHAUSTED_LEGACY is returned when a query exceeds its quota in some dimension
// and can't be completed due to that. Queries that return RESOURCE_EXHAUSTED
// should not be retried, as it could be detrimental to the server's health.
// Examples of errors that will cause the RESOURCE_EXHAUSTED code:
// 1. TxPoolFull: this is retried server-side, and is only returned as an error
// if the server-side retries failed.
// 2. Query is killed due to it taking too long.
RESOURCE_EXHAUSTED_LEGACY = 7;
// QUERY_NOT_SERVED_LEGACY means that a query could not be served right now.
// Client can interpret it as: "the tablet that you sent this query to cannot
// serve the query right now, try a different tablet or try again later."
// This could be due to various reasons: QueryService is not serving, should
// not be serving, wrong shard, wrong tablet type, blacklisted table, etc.
// Clients that receive this error should usually retry the query, but after taking
// the appropriate steps to make sure that the query will get sent to the correct
// tablet.
QUERY_NOT_SERVED_LEGACY = 8;
// NOT_IN_TX_LEGACY means that we're not currently in a transaction, but we should be.
NOT_IN_TX_LEGACY = 9;
// INTERNAL_ERROR_LEGACY means some invariants expected by underlying
// system has been broken. If you see one of these errors,
// something is very broken.
INTERNAL_ERROR_LEGACY = 10;
// TRANSIENT_ERROR_LEGACY is used for when there is some error that we expect we can
// recover from automatically - often due to a resource limit temporarily being
// reached. Retrying this error, with an exponential backoff, should succeed.
// Clients should be able to successfully retry the query on the same backends.
// Examples of things that can trigger this error:
// 1. Query has been throttled
// 2. VtGate could have request backlog
TRANSIENT_ERROR_LEGACY = 11;
// UNAUTHENTICATED_LEGACY errors are returned when a user requests access to something,
// and we're unable to verify the user's authentication.
UNAUTHENTICATED_LEGACY = 12;
}
// RPCError is an application-level error structure returned by
// VtTablet (and passed along by VtGate if appropriate).
// We use this so the clients don't have to parse the error messages,
// but instead can depend on the value of the code.
message RPCError {
LegacyErrorCode legacy_code = 1;
string message = 2;
Code code = 3;
}