// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you 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.

// Protobufs which are specific to client implementations.
syntax = "proto2";
package kudu.client;

option java_package = "org.apache.kudu.client";

import "kudu/common/common.proto";
import "kudu/consensus/metadata.proto";
import "kudu/security/token.proto";
import "kudu/util/pb_util.proto";

// All of the metadata required to create a KuduTable object in the C++
// and Java clients.
// TODO(KUDU-3135): Use for generic metadata tokens outside of the scan token.
message TableMetadataPB {
  optional string table_id = 1;
  optional string table_name = 2;
  optional int32 num_replicas = 3;

  optional SchemaPB schema = 4;
  optional PartitionSchemaPB partition_schema = 5;

  // The table's extra configuration properties.
  map<string, string> extra_configs = 6;

  optional string owner = 7;

  optional string comment = 8;
}

// Metdata about a single server.
// This can be used on the client to update the local cache of where
// each server is located.
message ServerMetadataPB {
  optional bytes uuid = 1;

  repeated HostPortPB rpc_addresses = 2;

  // The location assignment for this server.
  optional string location = 3;
}

// All of the metadata required to create a RemoteTablet object in the C++
// and Java clients.
message TabletMetadataPB {

  optional string tablet_id = 1;

  optional PartitionPB partition = 2;

  // The servers that host the replicas.
  repeated ServerMetadataPB tablet_servers = 3;

  message ReplicaMetadataPB {
      // The index of the tablet server in tablet_servers.
      required uint32 ts_idx = 1;
      required consensus.RaftPeerPB.Role role = 2;
      optional string dimension_label = 3;
  }

  repeated ReplicaMetadataPB replicas = 4;

  // Cached table locations should not live longer than this timeout.
  // Note: Some time will pass between serializing and deserializing
  // the token. This means that that effective TTL would be longer
  // than initially set. This shouldn't be a problem in normal usage
  // given the time shouldn't be an extended period. Additionally,
  // the client can retry if any failures occur due to outdated metadata.
  optional uint64 ttl_millis = 5;
}

// Serialization format for client scan tokens. Scan tokens are serializable
// scan descriptors that are used by query engines to plan a set of parallizable
// scanners that are executed on remote task runners. The scan token protobuf
// format includes all of the information necessary to recreate a scanner in the
// remote task.
message ScanTokenPB {

  // Features used by the scan token message. Every time the ScanTokenPB message
  // is updated with a new feature, the feature should be added to this enum, so
  // that clients that lack the feature can recognize when they receive a token
  // that uses unknown features.
  enum Feature {
    Unknown = 0;
  }

  // The feature set used by this scan token.
  repeated Feature feature_flags = 1;

  // The table to scan. To remain backwards compatible, clients should set
  // both the table name and the table id, but should prefer to use the id
  // when rehydrating the scanner because the id cannot change.
  optional string table_id = 20;
  optional string table_name = 2;

  // Optional table metadata. If provided the scan token can avoid
  // an extra GetTableSchema RPC call to the master.
  // If set, neither table_id or table_name above are required.
  optional TableMetadataPB table_metadata = 21;

  // Optional tablet metadata. If provided the scan token can avoid
  // an extra GetTableLocations RPC call to the master.
  optional TabletMetadataPB tablet_metadata = 22;

  // The index of which columns in table_metadata to select.
  // This can be used in place of projected_columns if this
  // scan token has table_metadata.
  repeated int32 projected_column_idx = 23;

  // Which columns to select.
  // if this is an empty list, no data will be returned, but the num_rows
  // field of the returned RowBlock will indicate how many rows passed
  // the predicates. Note that in some cases, the scan may still require
  // multiple round-trips, and the caller must aggregate the counts.
  repeated ColumnSchemaPB projected_columns = 3;

  // Any column predicates to enforce.
  repeated ColumnPredicatePB column_predicates = 4;

  // Encoded primary key to begin scanning at (inclusive).
  optional bytes lower_bound_primary_key = 5 [(kudu.REDACT) = true];

  // Encoded primary key to stop scanning at (exclusive).
  optional bytes upper_bound_primary_key = 6 [(kudu.REDACT) = true];

  // Encoded partition key to begin scanning at (inclusive).
  optional bytes lower_bound_partition_key = 7 [(kudu.REDACT) = true];

  // Encoded partition key to stop scanning at (exclusive).
  optional bytes upper_bound_partition_key = 8 [(kudu.REDACT) = true];

  // The maximum number of rows to scan.
  // The scanner will automatically stop yielding results and close
  // itself after reaching this number of result rows.
  optional uint64 limit = 9;

  // The read mode for this scan request.
  // See common.proto for further information about read modes.
  optional ReadMode read_mode = 10 [default = READ_LATEST];

  // The requested snapshot timestamp. This is only used
  // when the read mode is set to READ_AT_SNAPSHOT.
  optional fixed64 snap_timestamp = 11;

  // The requested snapshot start timestamp. This is only used
  // when the read mode is set to READ_AT_SNAPSHOT.
  // Setting this indicates the scan should be a diff scan, the
  // snap_timestamp will be used as the snapshot end timestamp.
  optional fixed64 snap_start_timestamp = 19;

  // Sent by clients which previously executed CLIENT_PROPAGATED writes.
  // This updates the server's time so that no op will be assigned
  // a timestamp lower than or equal to 'previous_known_timestamp'
  optional fixed64 propagated_timestamp = 12;

  // Whether data blocks will be cached when read from the files or discarded after use.
  // Disable this to lower cache churn when doing large scans.
  optional bool cache_blocks = 13 [default = true];

  // Whether the scan should be fault tolerant.
  optional bool fault_tolerant = 14 [default = false];

  // The maximum number of bytes to send in the response.
  // This is a hint, not a requirement: the server may send
  // arbitrarily fewer or more bytes than requested.
  optional uint32 batch_size_bytes = 15;

  // The replica selection policy for the scan request.
  // See common.proto for further information about replica selections.
  optional ReplicaSelection replica_selection = 16 [default = LEADER_ONLY];

  // The maximum length of time, in milliseconds, that each scan request to a
  // server can take. If not set, the default value is controlled by the client
  // scanner implementation.
  optional int64 scan_request_timeout_ms = 17;

  // The period, in milliseconds, at which to send keep-alive requests to the tablet
  // server to ensure this scanner won't time out.
  optional int64 keep_alive_period_ms = 18;

  // An authorization token with which to authorize the scan requests.
  optional security.SignedTokenPB authz_token = 24;
}

// All of the data necessary to authenticate to a cluster from a client with
// no Kerberos credentials.
message AuthenticationCredentialsPB {

  // A signed token with user credentials issued by the master.
  optional security.SignedTokenPB authn_token = 1;

  // The real user name, used for SASL PLAIN authentication.
  optional string real_user = 3;

  // Trusted root CA certificates.
  repeated bytes ca_cert_ders = 2;
}