/*
 * Copyright The Stargate 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";

import "google/protobuf/any.proto";
import "google/protobuf/wrappers.proto";

option java_package = "io.stargate.proto";
option go_package = "stargate/proto";

package stargate;

// The consistency level used to execute a request.
enum Consistency {
  ANY = 0x00;
  ONE = 0x01;
  TWO = 0x02;
  THREE = 0x03;
  QUORUM = 0x04;
  ALL = 0x05;
  LOCAL_QUORUM = 0x06;
  EACH_QUORUM = 0x07;
  SERIAL = 0x08;
  LOCAL_SERIAL = 0x09;
  LOCAL_ONE = 0x0A;
}

// A wrapper message for Consistency, for cases where the consistency level can be unset.
message ConsistencyValue {
  Consistency value = 1;
}

// A CQL value for a collection type.
// For lists, sets and tuples, this contains the collection elements.
// For maps, this contains the key and values in order (e.g. key1, value1, key2, value2...)
message Collection {
  repeated Value elements = 1;
}

// A value for a CQL user-defined type.
message UdtValue {
  map<string, Value> fields = 1;
}

// A 128-bit (16-byte) UUID type encoded using big-endian byte order. For example, the UUID
// "00112233-4455-6677-8899-aabbccddeeff" would be store as the bytes:
// | 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x99 0xAA 0xBB 0xCC 0xDD 0xEE 0xFF |
// | MSB                                                                        LSB  |
message Uuid {
  bytes value = 1;
}

// Either an IPv4 or IPv6 address stored as either 4 or 16 bytes, respectively. The addresses are
// encoded using big-endian byte order.
message Inet {
  bytes value = 1;
}

message Varint {
  bytes value = 1;
}

message Decimal {
  uint32 scale = 1;
  bytes value = 3;
}

// A CQL value. This is used both in requests to bind parameterized query strings, and in responses
// to represent the result data.
message Value {
  message Null {}
  message Unset {}
  oneof inner {
    // The CQL value NULL.
    Null null = 1;

    // An unset value.
    // This can only be used for bind values in requests.
    Unset unset = 2;

    // CQL types: tinyint, smallint, int, bigint, counter, timestamp
    sint64 int = 3;

    // CQL types: float
    float float = 4;

    // CQL types: double
    double double = 5;

    // CQL types: boolean
    bool boolean = 6;

    // CQL types: ascii, varchar, text
    string string = 7;

    // CQL types: blob, custom
    bytes bytes = 8;

    // CQL types: inet
    Inet inet = 9;

    // CQL types: uuid, timeuuid
    Uuid uuid = 10;

    // CQL types: date
    // An unsigned integer representing days with Unix epoch (January, 1 1970) at 2^31.
    // Examples:
    // 0:    -5877641-06-23
    // 2^31: 1970-1-1
    // 2^32: 5881580-07-11
    uint32 date = 11;

    // CQL types: time
    // An unsigned integer representing the number of nanoseconds since midnight. Valid values are
    // in the range 0 to 86399999999999 (inclusive).
    uint64 time = 12;

    // CQL types: list, set, map, tuple
    Collection collection = 13;

    // CQL types: user defined types
    UdtValue udt = 14;

    // CQL types: varint
    Varint varint = 15;

    // CQL types: decimal
    Decimal decimal = 16;
  }
}

// A single CQL query.
message Query {
  // The query string. It can contain anonymous placeholders identified by a question mark (?), or
  // named placeholders prefixed by a column (:name).
  string cql = 1;

  // The values to fill the placeholders in the query string.
  Values values = 2;

  // The execution parameters for the query.
  QueryParameters parameters = 3;
}

// The values to bind to the placeholders in a query.
message Values {
  // The values.
  repeated Value values = 1;
  // The value names, if the query uses named placeholders.
  repeated string value_names = 2;
}

// The execution parameters for a Query message.
message QueryParameters {
  // The keyspace to use when schema element names in the query (tables, UDTs, functions) are not
  // fully qualified.
  google.protobuf.StringValue keyspace = 1;

  // The consistency level.
  // If unset, it defaults to LOCAL_QUORUM.
  ConsistencyValue consistency = 2;

  // The maximum number of rows that will be returned in the response. If there are more results,
  // the response will contain a paging state, and additional queries will be needed to retrieve
  // subsequent pages.
  // Note that this is only a suggestion, the server reserves the right to return slightly smaller
  // or bigger pages.
  // If unset, it defaults to 100.
  google.protobuf.Int32Value page_size = 3;

  // A paging state that indicates where to resume iteration in the result set. This is used to
  // retrieve the next page of data when the number of results exceeds the page size.
  // This should be filled with the value returned by the previous response (see
  // ResultSet.paging_state). It is an opaque binary string that is only intended to be collected,
  // stored and reused; any attempt to modify its contents or reuse it with a different statement
  // will yield unpredictable results.
  google.protobuf.BytesValue paging_state = 4;

  // Whether the server should collect tracing information about the execution of the query.
  // If this is set, then a Traces message will be included in the Response message.
  bool tracing = 5;

  // Whether to omit ResultSet.columns in the response.
  // This can be used to optimize response size when the client already knows that information (for
  // example when fetching multiple pages for the same query).
  bool skip_metadata = 6;

  // The query timestamp (in microseconds). This is used to order mutations on the server.
  // If unset, the server will assign one based on the time it received the query.
  google.protobuf.Int64Value timestamp = 7;

  // The serial consistency level (if the query is a lightweight transaction).
  // If unset, it defaults to SERIAL.
  ConsistencyValue serial_consistency = 8;

  // Forces the current time for the query (for testing purposes).
  // This affects TTL cell liveness in read queries and local deletion time for tombstones and TTL
  // cells in update requests.
  google.protobuf.Int32Value now_in_seconds = 9;

  // The consistency level to use to retrieve the query trace (if tracing is set).
  // If unset, it defaults to ONE.
  ConsistencyValue tracing_consistency = 10;
}

// A CQL column type.
message TypeSpec {

  // A CQL primitive type.
  enum Basic {
    CUSTOM = 0x00;
    ASCII = 0x01;
    BIGINT = 0x02;
    BLOB = 0x03;
    BOOLEAN = 0x04;
    COUNTER = 0x05;
    DECIMAL = 0x06;
    DOUBLE = 0x07;
    FLOAT = 0x08;
    INT = 0x09;
    TEXT = 0xA;
    TIMESTAMP = 0x0B;
    UUID = 0x0C;
    VARCHAR = 0x0D;
    VARINT = 0x0E;
    TIMEUUID = 0x0F;
    INET = 0x10;
    DATE = 0x11;
    TIME = 0x12;
    SMALLINT = 0x13;
    TINYINT = 0x14;
  }

  message Map {
    TypeSpec key = 1;
    TypeSpec value = 2;
  }

  message List {
    TypeSpec element = 1;
  }

  message Set {
    TypeSpec element = 1;
  }

  // A CQL User-Defined type: a collection of named fields.
  message Udt {
    map<string, TypeSpec> fields = 1;
  }

  // A CQL tuple: a collection of anonymous fields.
  message Tuple {
    repeated TypeSpec elements = 1;
  }

  oneof spec {
    Basic basic = 1;
    Map map = 2;
    List list = 3;
    Set set = 4;
    Udt udt = 5;
    Tuple tuple = 6;
  };
}

// Metadata about a CQL column.
message ColumnSpec {
  // The CQL type.
  TypeSpec type = 1;

  // The name.
  string name = 2;
}

// Tracing information, included in the Response when it was requested by the client (see
// QueryParameters.tracing or BatchParameters.tracing)
message Traces {
  // An event in a query trace.
  message Event {
    // Which activity the event corresponds to.
    string activity = 1;
    // Identifies the host having generated the event.
    string source = 2;
    // The number of microseconds elapsed on the source when this event occurred since the moment
    // when the source started handling the query.
    int64 source_elapsed = 3;
    // The name of the server thread on which this event occurred.
    string thread = 4;
    // A technical identifier for the event.
    string event_id = 5;
  }
  // A technical identifier for this trace.
  string id = 1;
  // The server-side duration of the query (in microseconds).
  int64 duration = 2;
  // The server-side timestamp of the start of the query.
  int64 started_at = 3;
  repeated Event events = 4;
}

// If a Query message is a DDL statement, this will be included in the Response to describe the
// how the CQL schema was impacted.
message SchemaChange {
  enum Type {
    CREATED = 0;
    UPDATED = 1;
    DROPPED = 2;
  }
  enum Target {
    KEYSPACE = 0;
    TABLE = 1;
    TYPE = 2;
    FUNCTION = 3;
    AGGREGATE = 4;
  }
  // The nature of the change (created, updated or dropped).
  Type change_type = 1;
  // The type of schema object that was affected.
  Target target = 2;
  // The name of the keyspace.
  string keyspace = 3;
  // If the target is a keyspace element (table, type, etc), its name.
  google.protobuf.StringValue name = 4;
  // If the target is a function or aggregate, the CQL types of the arguments.
  repeated string argument_types = 5;
}

// The response to a Query or Batch message.
message Response {
  oneof result {
    // The result data.
    ResultSet result_set = 1;
    // How the query changed the CQL schema.
    SchemaChange schema_change = 4;
  }
  // The server-side warnings for the query, if any.
  repeated string warnings = 2;
  // The tracing information, if it was requested for the query.
  Traces traces = 3;
}

// Thrown when the coordinator knows there is not enough replicas alive to perform a query with the
// requested consistency level.
message Unavailable {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica acknowledgements/responses required to perform the operation (with its
  // required consistency level).
  int32 required = 2;
  // The number of replicas that were known to be alive by the coordinator node when it tried to
  // execute the operation.
  int32 alive = 3;
};

// A server-side timeout during a write query.
message WriteTimeout {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica that had acknowledged/responded to the operation before it failed.
  int32 received = 2;
  // The minimum number of replica acknowledgements/responses that were required to fulfill the
  // operation.
  int32 block_for = 3;
  // The type of the write for which a timeout was raised.
  string write_type = 4;
};

// A server-side timeout during a read query.
message ReadTimeout {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica that had acknowledged/responded to the operation before it failed.
  int32 received = 2;
  // The minimum number of replica acknowledgements/responses that were required to fulfill the
  // operation.
  int32 block_for = 3;
  // Whether the actual data was amongst the received replica responses.
  // During reads, Cassandra doesn't request data from every replica to minimize internal network
  // traffic. Instead, some replicas are only asked for a checksum of the data. A read timeout may
  // occur even if enough replicas have responded to fulfill the consistency level, if only checksum
  // responses have been received. This field allows to detect that case.
  bool data_present = 4;
};

// A non-timeout error during a read query.
// This happens when some of the replicas that were contacted by the coordinator replied with an
// error.
message ReadFailure {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica that had acknowledged/responded to the operation before it failed.
  int32 received = 2;
  // The minimum number of replica acknowledgements/responses that were required to fulfill the
  // operation.
  int32 block_for = 3;
  // The number of replicas that experienced a failure while executing the request.
  int32 num_failures = 4;
  // Whether the actual data was amongst the received replica responses.
  // During reads, Cassandra doesn't request data from every replica to minimize internal network
  // traffic. Instead, some replicas are only asked for a checksum of the data. A read timeout may
  // occur even if enough replicas have responded to fulfill the consistency level, if only checksum
  // responses have been received. This field allows to detect that case.
  bool data_present = 5;
};

// An error during the execution of a CQL function.
message FunctionFailure {
  // The keyspace containing the function.
  string keyspace = 1;
  // The name of the function.
  string function = 2;
  // The CQL types of the arguments of the function.
  repeated string arg_types = 3;
}

// A non-timeout error during a write query.
// This happens when some of the replicas that were contacted by the coordinator replied with an
// error.
message WriteFailure {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica that had acknowledged/responded to the operation before it failed.
  int32 received = 2;
  // The minimum number of replica acknowledgements/responses that were required to fulfill the
  // operation.
  int32 block_for = 3;
  // The number of replicas that experienced a failure while executing the request.
  int32 num_failures = 4;
  // The type of the write for which an error was raised.
  string write_type = 5;
}

// Thrown when a query attempts to create a keyspace or table that already exists.
message AlreadyExists {
  string keyspace = 1;
  string table = 2;
}

// An exception occured due to a contended Compare And Set write/update.
// The CAS operation was only partially completed and the operation may or may not get completed by
// the contending CAS write or SERIAL/LOCAL_SERIAL read.
message CasWriteUnknown {
  // The consistency level of the operation that failed.
  Consistency consistency = 1;
  // The number of replica that had acknowledged/responded to the operation before it failed.
  int32 received = 2;
  // The minimum number of replica acknowledgements/responses that were required to fulfill the
  // operation.
  int32 block_for = 3;
}

// A single row in a result set.
message Row {
  // The values for the columns (in the same order as ResultSet.columns).
  repeated Value values = 1;
}

// The data returned in response to a CQL query.
message ResultSet {
  // Metadata about the columns that this result set contains.
  // This may be omitted if explicitly requested by the client (see QueryParameters.skip_metadata
  // and BatchParameters.skip_metadata).
  repeated ColumnSpec columns = 1;

  // The rows of CQL data.
  repeated Row rows = 2;

  // If there are more pages, a paging state that will allow the client to build a new query for the
  // next page.
  google.protobuf.BytesValue paging_state = 3;
}

// A query inside of a Batch message.
message BatchQuery {
  // The query string. It can contain anonymous placeholders identified by a question mark (?), or
  // named placeholders prefixed by a column (:name).
  string cql = 1;

  // The values to fill the placeholders in the query string.
  Values values = 2;
}

// The execution parameters for a Batch message.
message BatchParameters {
  // The keyspace to use when schema element names in the queries (tables, UDTs, functions) are not
  // fully qualified.
  google.protobuf.StringValue keyspace = 1;

  // The consistency level.
  // If unset, it defaults to LOCAL_QUORUM.
  ConsistencyValue consistency = 2;

  // Whether the server should collect tracing information about the execution of the query.
  // If this is set, then a Traces message will be included in the Response message.
  bool tracing = 3;

  // The query timestamp (in microseconds). This is used to order mutations on the server.
  // If unset, the server will assign one based on the time it received the batch.
  google.protobuf.Int64Value timestamp = 4;

  // The serial consistency level (if the batch contains lightweight transactions).
  // If unset, it defaults to SERIAL.
  ConsistencyValue serial_consistency = 5;

  // Forces the current time for the query (for testing purposes).
  // This affects TTL cell liveness in read queries and local deletion time for tombstones and TTL
  // cells in update requests.
  google.protobuf.Int32Value now_in_seconds = 6;

  // The consistency level to use to retrieve the query trace (if tracing is set).
  // If unset, it defaults to ONE.
  ConsistencyValue tracing_consistency = 7;

  // Whether to omit ResultSet.columns in the response.
  // This can be used to optimize response size when the client already knows that information.
  bool skip_metadata = 8;
}

// A batch containing multiple CQL queries.
message Batch {
  enum Type {
    // A logged batch: Cassandra will first write the batch to its distributed batch log to ensure
    // the atomicity of the batch (atomicity meaning that if any statement in the batch succeeds,
    // all will eventually succeed).
    LOGGED = 0;

    // A batch that doesn't use Cassandra's distributed batch log. Such batch are not guaranteed to
    // be atomic.
    UNLOGGED = 1;

    // A counter batch. Note that such batch is the only type that can contain counter operations
    // and it can only contain these.
    COUNTER = 2;
  }
  // The type of batch.
  Type type = 1;
  // The CQL queries with their values.
  repeated BatchQuery queries = 2;
  // The execution parameters for the batch.
  BatchParameters parameters = 3;
}