src/kudu/master/master.proto

// 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.
syntax = "proto2";
package kudu.master;

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

import "kudu/common/common.proto";
import "kudu/common/wire_protocol.proto";
import "kudu/consensus/metadata.proto";
import "kudu/consensus/replica_management.proto";
import "kudu/rpc/rpc_header.proto";
import "kudu/security/token.proto";
import "kudu/tablet/metadata.proto";
import "kudu/util/pb_util.proto";

////////////////////////////////////////////////////////////
// Common data structures
////////////////////////////////////////////////////////////

// Master specific errors use this protobuf.
message MasterErrorPB {
  enum Code {
    // An error which has no more specific error code.
    // The code and message in 'status' may reveal more details.
    //
    // RPCs should avoid returning this, since callers will not be
    // able to easily parse the error.
    UNKNOWN_ERROR = 1;

    // The schema provided for a request was not well-formed.
    INVALID_SCHEMA = 2;

    // The requested table does not exist
    TABLE_NOT_FOUND = 3;

    // The name requested for the table is already in use
    TABLE_ALREADY_PRESENT = 4;

    // The number of tablets requested for a new table is over the per TS limit.
    TOO_MANY_TABLETS = 5;

    // Catalog manager is not yet initialized.
    CATALOG_MANAGER_NOT_INITIALIZED = 6;

    // The operation attempted can only be invoked against either the
    // leader or a single non-distributed master, which this node
    // isn't.
    NOT_THE_LEADER = 7;

    // The number of replicas requested is greater than the number of live servers
    // in the cluster or the configured maximum.
    REPLICATION_FACTOR_TOO_HIGH = 8;

    // The request or response involved a tablet which is not yet running.
    TABLET_NOT_RUNNING = 9;

    // The number of replicas requested is even.
    EVEN_REPLICATION_FACTOR = 10;

    // The number of replicas requested is illegal (eg non-positive).
    ILLEGAL_REPLICATION_FACTOR = 11;

    // The callee detected that its replica management scheme is incompatible
    // with the caller's scheme.
    INCOMPATIBLE_REPLICA_MANAGEMENT = 12;

    // An operation involving the Hive Metastore failed.
    HIVE_METASTORE_ERROR = 13;

    // The caller is not authorized to perform the attempted operation.
    NOT_AUTHORIZED = 14;
  }

  // The error code.
  required Code code = 1;

  // The Status object for the error. This will include a textual
  // message that may be more useful to present in log messages, etc,
  // though its error code is less specific.
  required AppStatusPB status = 2;
}

// Common information sent with every request from the tablet server
// to the master.
message TSToMasterCommonPB {
  // The instance of the tablet server sending the heartbeat.
  required NodeInstancePB ts_instance = 1;
}

message TableIdentifierPB {
  // The table ID to fetch info.
  optional bytes table_id = 1;

  // The table name to fetch info.
  optional string table_name = 2;
}

////////////////////////////////////////////////////////////
// Sys Tables Metadata
////////////////////////////////////////////////////////////

// The on-disk entry in the sys.catalog table ("metadata" column) for
// tablets entries.
message SysTabletsEntryPB {
  enum State {
    UNKNOWN = 999;
    PREPARING = 0;
    CREATING = 1;
    RUNNING = 2;
    REPLACED = 3;
    DELETED = 4;
  }

  // DEPRECATED. Replaced by 'partition'.
  optional bytes DEPRECATED_start_key = 1;
  optional bytes DEPRECATED_end_key   = 2;

  // Tablet partition.
  optional PartitionPB partition = 7;

  // The latest consensus state reported to the Master.
  optional consensus.ConsensusStatePB consensus_state = 3;

  // Debug state for the tablet.
  optional State state = 4 [ default = UNKNOWN ];
  optional bytes state_msg = 5;

  // The table id for the tablet.
  required bytes table_id = 6;

  // The dimension label for the tablet. Used for dimension-specific
  // placement of the tablet's replicas.
  optional string dimension_label = 8;
}

// The on-disk entry in the sys.catalog table ("metadata" column) for
// tables entries.
message SysTablesEntryPB {
  enum State {
    UNKNOWN = 0;
    PREPARING = 1;
    RUNNING = 2;
    ALTERING = 3;
    REMOVED = 4;
  }

  // Table name
  required bytes name = 1;

  // sequence-id for the table metadata.
  // Used on tablet-report to avoid sending "alter-table" notifications.
  required uint32 version = 2;

  // Newest table schema (every TS will eventually have it).
  required SchemaPB schema = 3;

  // Last table schema that is guaranteed to have reached every TS, though
  // not necessarily the newest schema.
  //
  // This is the schema provided to the user on client->GetSchema(tableName).
  optional SchemaPB fully_applied_schema = 4;

  // The table's partitioning schema.
  optional PartitionSchemaPB partition_schema = 9;

  // The next column ID to assign to newly added columns in this table.
  // This prevents column ID reuse.
  optional int32 next_column_id = 8;

  // Number of TS replicas
  required int32 num_replicas = 5;

  // Debug state for the table.
  optional State state = 6 [ default = UNKNOWN ];
  optional bytes state_msg = 7;

  // The create time of the table, in seconds since the epoch.
  optional int64 create_timestamp = 10;
  // The last alter time of the table, in seconds since the epoch.
  optional int64 alter_timestamp = 11;
  // The table's extra configuration properties.
  optional TableExtraConfigPB extra_config = 12;
}

// The on-disk entry in the sys.catalog table ("metadata" column) to represent
// certificate authority (CA) information. Not more than one entry of this type
// should exist in the sys.catalog table at any time.
message SysCertAuthorityEntryPB {
  // Private key body in DER format. This information is sensitive,
  // that's why the REDACT attribute is present.
  required bytes private_key = 1 [(kudu.REDACT) = true];
  // Certificate body in DER format. This information is not sensitive,
  // but we are redacting most of security-related info anyway
  // (handshake/SASL tokens, etc.).
  required bytes certificate = 2 [(kudu.REDACT) = true];
}

// The on-disk entry in the sys.catalog table ("metadata" column) to represent
// a Token Signing Key (TSK) object. Multiple entries of this type
// can simultaneously co-exist in the sys.catalog table.
message SysTskEntryPB {
  // TokenSigningPrivateKeyPB message representing a TSK.
  required security.TokenSigningPrivateKeyPB tsk = 1;
}

// The on-disk entry in the sys.catalog table ("metadata" column) to represent
// the latest processed Hive Metastore notification log event ID.
message SysNotificationLogEventIdPB {
  optional int64 latest_notification_log_event_id = 1;
}

// The on-disk entry in the sys.catalog table to represent the existence of
// on-going tserver state (e.g. maintenance mode).
message SysTServerStateEntryPB {
  optional TServerStatePB state = 1;

  // Timestamp, in seconds since the epoch, at which this state was set.
  optional int64 timestamp_secs = 2;
}

////////////////////////////////////////////////////////////
// RPCs
////////////////////////////////////////////////////////////

message PingRequestPB {
}

message PingResponsePB {
}

message ReportedTabletPB {
  required bytes tablet_id = 1;
  optional tablet.TabletStatePB state = 2 [ default = UNKNOWN ];
  optional tablet.TabletDataState tablet_data_state = 6 [ default = TABLET_DATA_UNKNOWN ];

  // The latest consensus state.
  // This will be missing if the tablet is not in a RUNNING state
  // (i.e. if it is BOOTSTRAPPING).
  optional consensus.ConsensusStatePB consensus_state = 3;

  optional AppStatusPB error = 4;
  optional uint32 schema_version = 5;

  // Tablet statistics.
  // This is only included in the report if the replica is a LEADER.
  optional tablet.ReportedTabletStatsPB stats = 7;
}

// Sent by the tablet server to report the set of tablets hosted by that TS.
message TabletReportPB {
  // If false, then this is a full report, and any prior information about
  // tablets hosted by this server should be dropped.
  required bool is_incremental = 1;

  // Tablets for which to update information. If 'is_incremental' is false,
  // then this is the full set of tablets on the server, and any tablets
  // which the master is aware of but not listed in this protobuf should
  // be assumed to have been removed from this server.
  repeated ReportedTabletPB updated_tablets = 2;

  // Tablet IDs which the tablet server has removed and should no longer be
  // considered hosted here. This will always be empty in a non-incremental
  // report.
  repeated bytes removed_tablet_ids = 3;

  // Every time the TS generates a tablet report, it creates a sequence
  // number. This can be useful in debugging, and also determining which
  // changes have not yet been reported to the master.
  // The first tablet report (non-incremental) is sequence number 0.
  required int32 sequence_number = 4;
}

message ReportedTabletUpdatesPB {
  required bytes tablet_id = 1;
  optional string state_msg = 2;
}

// Sent by the Master in response to the TS tablet report (part of the heartbeats)
message TabletReportUpdatesPB {
  repeated ReportedTabletUpdatesPB tablets = 1;
}

// Heartbeat sent from the tablet-server to the master
// to establish liveness and report back any status changes.
message TSHeartbeatRequestPB {
  required TSToMasterCommonPB common = 1;

  // Sent upon start-up of the TS, or in response to 'needs_reregister' on a heartbeat
  // response.
  optional ServerRegistrationPB registration = 2;

  // Sent when the tablet information has changed, or in response to
  // 'needs_full_tablet_report'.
  optional TabletReportPB tablet_report = 3;

  // TODO; add a heartbeat sequence number?

  // TODO: perhaps add some very basic metrics reporting here, like
  // free space, reqs/sec, etc?

  // The number of tablets that are BOOTSTRAPPING or RUNNING.
  // Used by the master to determine load when creating new tablet replicas.
  optional int32 num_live_tablets = 4;

  // If the tablet server needs its certificate signed, the CSR
  // in DER format.
  optional bytes csr_der = 5;

  // The most recently known TSK sequence number. Allows the master to
  // selectively notify the tablet server of more recent TSKs.
  optional int64 latest_tsk_seq_num = 6;

  // Replica management parameters that the tablet server is running with.
  // This field is set only if the registration field is present.
  optional consensus.ReplicaManagementInfoPB replica_management_info = 7;

  // The number of tablets that are BOOTSTRAPPING or RUNNING in each dimension.
  // Used by the master to determine load when creating new tablet replicas
  // based on dimension.
  map<string, int32> num_live_tablets_by_dimension = 8;
}

message TSHeartbeatResponsePB {
  optional MasterErrorPB error = 1;

  // As with most other master RPC responses (e.g.,
  // ListTablesResponsePB), all fields below are optional as they may
  // not be set if there is an error.

  optional NodeInstancePB master_instance = 2;

  // Indicates that the server which heartbeated needs to re-register
  // with the master -- i.e send a heartbeat with the 'registration'
  // filled in.
  optional bool needs_reregister = 3 [ default = false ];

  optional bool needs_full_tablet_report = 4 [ default = false ];

  // Sent when the master receives a TabletReport
  optional TabletReportUpdatesPB tablet_report = 5;

  // Specify whether or not the node is the leader master.
  optional bool leader_master = 6;

  // If the heartbeat request had a CSR, then the successfully
  // signed certificate will be returned in DER format.
  optional bytes signed_cert_der = 7;

  // Any CA certs used by the cluster, currently only included when
  // 'signed_cert_der' is also sent (however the tablet server will always check
  // for all heartbeat responses). Currently the master only uses one cert, but
  // we may support rolling this cert in the future, so tablet servers should
  // add all returned certs to their trusted CA list.
  //
  // NOTE: this is not necessarily a "certificate chain" but rather a set of
  // independent certs to be trusted. They may or may not have any signing
  // relationship between them.
  repeated bytes ca_cert_der = 8;

  // Token signing keys which the tablet server should begin trusting.
  repeated security.TokenSigningPublicKeyPB tsks = 9;
}

//////////////////////////////
// GetTabletLocations
//////////////////////////////

message TabletLocationsPB {
  // DEPRECATED.
  // TODO: new clients should prefer the 'Interned' type below.
  // Remove 'ReplicaPB' when we stop using it internally.
  message DEPRECATED_ReplicaPB {
    required TSInfoPB ts_info = 1;
    required consensus.RaftPeerPB.Role role = 2;
    optional string dimension_label = 3;
  }

  message InternedReplicaPB {
    // Index into the 'ts_infos' list in the top-level RPC response.
    required uint32 ts_info_idx = 1;
    required consensus.RaftPeerPB.Role role = 2;
    optional string dimension_label = 3;
  }

  required bytes tablet_id = 1;

  // DEPRECATED.
  optional bytes start_key = 2;
  optional bytes end_key = 3;

  optional PartitionPB partition = 6;

  // DEPRECATED.
  // Used only if interned replicas are not supported by client.
  repeated DEPRECATED_ReplicaPB DEPRECATED_replicas = 4;

  // More efficient representation of replicas: instead of duplicating the TSInfoPB
  // in each tablet location, instead we just encode indexes into a list of TSInfoPB
  // which is serialized in the top-level response.
  //
  // Used when supported by client.
  repeated InternedReplicaPB interned_replicas = 7;

  // DEPRECATED. Still set by servers, but should be ignored by clients.
  optional bool DEPRECATED_stale = 5;
}

// Info about a single tablet server, returned to the client as part
// of the GetTabletLocations response. This can be used on the client
// to update the local cache of where each TS UUID is located. In
// the future we may also want to transmit software version info,
// load info, topology, etc.
message TSInfoPB {
  required bytes permanent_uuid = 1;

  repeated HostPortPB rpc_addresses = 2;

  optional string location = 3;

  // The path of a UNIX domain socket where the server is listening.
  // An '@' prefix indicates the abstract namespace. May be missing
  // if this feature is not enabled.
  optional string unix_domain_socket_path = 4;
}

// Selector to specify policy for listing tablet replicas in
// GetTableLocationResponsePB and GetTabletLocationsResponsePB.
enum ReplicaTypeFilter {
  UNKNOWN = 999;
  ANY_REPLICA = 0;
  VOTER_REPLICA = 1;
}

message GetTabletLocationsRequestPB {

  // The tablet IDs about which to fetch info.
  repeated bytes tablet_ids = 1;

  // What type of tablet replicas to include in the response.
  optional ReplicaTypeFilter replica_type_filter = 2 [ default = VOTER_REPLICA ];

  // Whether the response should use the 'interned_replicas' field.
  optional bool intern_ts_infos_in_response = 3 [ default = false ];
}

message GetTabletLocationsResponsePB {
  optional MasterErrorPB error = 1;

  repeated TabletLocationsPB tablet_locations = 2;

  // Used if 'intern_ts_infos_in_response' was requested.
  // See InternedReplicaPB above.
  repeated TSInfoPB ts_infos = 4;

  message Error {
    required bytes tablet_id = 1;
    required AppStatusPB status = 2;
  }
  repeated Error errors = 3;
}

// ============================================================================
//  Catalog
// ============================================================================
message CreateTableRequestPB {
  required string name = 1;
  required SchemaPB schema = 2;
  // repeated bytes pre_split_keys = 3;
  // repeated PartialRowPB split_rows = 5;
  // Holds either the split rows or the range bounds (or both) of the table.
  optional RowOperationsPB split_rows_range_bounds = 6;
  optional PartitionSchemaPB partition_schema = 7;
  optional int32 num_replicas = 4;

  // If set, uses the provided value as the table owner when creating the table
  // in external catalogs such as the Hive Metastore.
  optional string owner = 8;

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

  // The dimension label for tablets that were created during table creation. Used for
  // dimension-specific placement of tablet replicas corresponding to the partitions of
  // the newly created table.
  optional string dimension_label = 10;
}

message CreateTableResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  optional bytes table_id = 2;
}

message IsCreateTableDoneRequestPB {
  required TableIdentifierPB table = 1;
}

message IsCreateTableDoneResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  // true if the create operation is completed, false otherwise
  optional bool done = 3;
}

message DeleteTableRequestPB {
  required TableIdentifierPB table = 1;

  // Whether to apply the deletion to external catalogs, such as the Hive Metastore,
  // which the Kudu master has been configured to integrate with.
  optional bool modify_external_catalogs = 2 [default = true];
}

message DeleteTableResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;
}

message ListTablesRequestPB {
  // When used, only returns tables that satisfy a substring match on name_filter.
  optional string name_filter = 1;
}

message ListTablesResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  message TableInfo {
    required bytes id = 1;
    required string name = 2;
  }

  repeated TableInfo tables = 2;
}

message GetTableStatisticsRequestPB {
  required TableIdentifierPB table = 1;
}

message GetTableStatisticsResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  // The table statistics from table metrics.
  optional int64 on_disk_size = 2;
  optional int64 live_row_count = 3;
}

message GetTableLocationsRequestPB {
  required TableIdentifierPB table = 1;

  // Partition-key range.
  optional bytes partition_key_start = 3 [(kudu.REDACT) = true];
  optional bytes partition_key_end = 4 [(kudu.REDACT) = true];

  optional uint32 max_returned_locations = 5 [ default = 10 ];

  // What type of tablet replicas to include in the
  // 'GetTableLocationsResponsePB::tablet_locations' response field.
  optional ReplicaTypeFilter replica_type_filter = 6 [ default = VOTER_REPLICA ];

  // Whether the response should use the 'interned_replicas' field.
  optional bool intern_ts_infos_in_response = 7 [ default = false ];
}

// The response to a GetTableLocations RPC. The master guarantees that:
//
// * The response contains a location for all tablets in the requested range,
//   limited by the request's 'max_returned_locations'.
// * The tablet locations are returned in sorted order by the partition key range.
// * If *any* tablet in the response is not running, then the entire response
//   will fail with MasterErrorPB::TABLET_NOT_RUNNING, and the tablet_locations
//   field will be empty.
// * A gap between the partition key ranges of consecutive tablets indicates a
//   non-covered partition range.
// * If the request's start partition key falls in a non-covered partition
//   range, the response will contain the tablet immediately before the
//   non-covered range, if it exists.
message GetTableLocationsResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  repeated TabletLocationsPB tablet_locations = 2;

  // Used if 'intern_ts_infos_in_response' was requested.
  // See InternedReplicaPB above.
  repeated TSInfoPB ts_infos = 4;

  // If the client caches table locations, the entries should not live longer
  // than this timeout. Defaults to one hour.
  optional uint32 ttl_millis = 3 [default = 36000000];
}

message AlterTableRequestPB {
  enum StepType {
    UNKNOWN = 0;
    ADD_COLUMN = 1;
    DROP_COLUMN = 2;
    RENAME_COLUMN = 3;
    ALTER_COLUMN = 4;
    ADD_RANGE_PARTITION = 5;
    DROP_RANGE_PARTITION = 6;
  }
  message AddColumn {
    // The schema to add.
    // NOTE: the 'id' field of the schema should not be provided here --
    // the server will assign an ID.
    required ColumnSchemaPB schema = 1;
  }
  message DropColumn {
    // Name of the column to drop.
    required string name = 1;
  }
  // This should eventually be deprecated in favor of AlterColumn.
  message RenameColumn {
    // Name of the column to rename;
    required string old_name = 1;
    required string new_name = 2;
  }
  message AlterColumn {
    optional ColumnSchemaDeltaPB delta = 1;
  }
  message AddRangePartition {
    // A set of row operations containing the lower and upper range bound for
    // the range partition to add or drop.
    optional RowOperationsPB range_bounds = 1;

    // The dimension label for the tablet. Used for dimension-specific placement
    // of the tablet's replicas.
    optional string dimension_label = 2;
  }
  message DropRangePartition {
    // A set of row operations containing the lower and upper range bound for
    // the range partition to add or drop.
    optional RowOperationsPB range_bounds = 1;
  }

  message Step {
    optional StepType type = 1 [ default = UNKNOWN ];

    // Exactly one of the following must be set, based on 'type'
    optional AddColumn add_column = 2;
    optional DropColumn drop_column = 3;
    optional RenameColumn rename_column = 4;
    optional AddRangePartition add_range_partition = 5;
    optional DropRangePartition drop_range_partition = 6;
    optional AlterColumn alter_column = 7;
  }

  required TableIdentifierPB table = 1;
  repeated Step alter_schema_steps = 2;
  optional string new_table_name = 3;

  // The table schema to use when decoding the range bound row operations. Only
  // necessary when partitions are being added or dropped.
  optional SchemaPB schema = 4;

  // Whether to apply the alteration to external catalogs, such as the Hive Metastore,
  // which the Kudu master has been configured to integrate with.
  optional bool modify_external_catalogs = 5 [default = true];

  map<string, string> new_extra_configs = 6;
}

message AlterTableResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  // The schema version of the altered table.
  optional uint32 schema_version = 2;

  // The table ID of the altered table.
  optional bytes table_id = 3;
}

message IsAlterTableDoneRequestPB {
  required TableIdentifierPB table = 1;
}

message IsAlterTableDoneResponsePB {
  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  // this is the current schema, or the 'new' schema version if an alter is in progress
  optional uint32 schema_version = 2;

  // true if the alter operation is completed, false otherwise
  optional bool done = 3;
}

message GetTableSchemaRequestPB {
  required TableIdentifierPB table = 1;
}

message GetTableSchemaResponsePB {
  // create_table_done (field number 6) was removed in Kudu 1.6.
  reserved 6;

  // The error, if an error occurred with this request.
  optional MasterErrorPB error = 1;

  // This is the schema that every TS should be able to understand
  // if your alter is keeping the schema compatible.
  // In case of an alter table in progress, this is the previous schema;
  // otherwise it is the latest schema.
  optional SchemaPB schema = 2;

  // The table's partition schema.
  optional PartitionSchemaPB partition_schema = 5;

  optional int32 num_replicas = 3;

  // The ID of the table.
  optional bytes table_id = 4;

  // The table name.
  optional string table_name = 7;

  // A token that the client can use to authorize further access to the table.
  // A token can always be expected with this response, unless the response is
  // from an older version of Kudu or unless the request resulted in an error.
  optional security.SignedTokenPB authz_token = 8;

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

message ConnectToMasterRequestPB {
}

message ConnectToMasterResponsePB {
  // Set if there is an error.
  optional MasterErrorPB error = 1;

  // The current role of the master.
  optional consensus.RaftPeerPB.Role role = 2;

  // Any CA certs used by the cluster. Currently the master only uses
  // one cert, but we may support rolling this cert in the future, so
  // clients should add all returned certs to their trusted CA list.
  //
  // NOTE: this is not necessarily a "certificate chain" but rather a set of
  // independent certs to be trusted. They may or may not have any signing
  // relationship between them.
  repeated bytes ca_cert_der = 3;

  // If the client requested an authentication token, and security is
  // enabled on the cluster, the master returns a signed authn token.
  optional security.SignedTokenPB authn_token = 4;

  // The hosts and ports of the masters in this cluster.
  //
  // NOTE: Added in Kudu 1.6.
  //
  // NOTE: it is likely, but not guaranteed that the hostnames advertised here
  // will be usable by all clients. Client implementations should not use this
  // field for "discovery" of other masters, since then it's likely that
  // users will configure applications to only talk to one the masters in
  // an HA setup. If that master then fails, the applications would go
  // offline.
  repeated HostPortPB master_addrs = 5;

  // If the master is configured with the Hive Metastore integration enabled,
  // this field will include the configuration options.
  optional HiveMetastoreConfig hms_config = 6;

  // The location of the client assigned by the master.
  optional string client_location = 7;
}

// Hive Metastore integration options and configuration.
message HiveMetastoreConfig {

  // Address(es) of the Hive Metastore instance(s).
  //
  // For more info see the Kudu master --hive_metastore_uris flag for more info,
  // or the Hive Metastore hive.metastore.uris configuration.
  optional string hms_uris = 1;

  // Whether the Hive Metastore instance uses SASL (Kerberos) security.
  //
  // For more info see the Kudu master --hive_metastore_sasl_enabled flag, or
  // the Hive Metastore hive.metastore.sasl.enabled configuration.
  optional bool hms_sasl_enabled = 2;

  // An ID which uniquely identifies the Hive Metastore instance.
  //
  // NOTE: this is provided on a best-effort basis, as not all Hive Metastore
  // versions which Kudu is compatible with include the necessary APIs. See
  // HIVE-16452 for more info.
  optional string hms_uuid = 3;
}

// ============================================================================
//  Administration/monitoring
// ============================================================================

message ListTabletServersRequestPB {
  // Whether or not to include the tserver states.
  // Note: this may include states of tservers that haven't been registered and
  // thus don't have a complete response Entries. In such cases, the Entries
  // will be returned with bogus info w.r.t registration and heartbeating.
  optional bool include_states = 1;
}

message ListTabletServersResponsePB {
  optional MasterErrorPB error = 1;

  message Entry {
    required NodeInstancePB instance_id = 1;
    optional ServerRegistrationPB registration = 2;
    optional int32 millis_since_heartbeat = 3;
    optional string location = 4;
    optional TServerStatePB state = 5;
  }
  repeated Entry servers = 2;
}

// Representation of the state of a tablet server.
// TODO(KUDU-1827): add state for decommissioning.
enum TServerStatePB {
  // Default value for backwards compatibility.
  UNKNOWN_STATE = 0;

  // No state for the tserver.
  NONE = 1;

  // New replicas are not added to the tserver, and failed replicas on the
  // tserver are not re-replicated.
  MAINTENANCE_MODE = 2;
}

message TServerStateChangePB {
  // Representation of a change in tserver state.
  enum StateChange {
    // Default value for backwards compatibility.
    UNKNOWN_STATE_CHANGE = 0;

    // Transitions from having no state to being in maintenance mode. If the
    // tserver is already in maintenance mode, this is a no-op.
    ENTER_MAINTENANCE_MODE = 1;

    // Transitions from being in maintenance mode to having no tserver state. If
    // the tserver already has no state, this is a no-op.
    EXIT_MAINTENANCE_MODE = 2;
  }

  // The tserver UUID on which to apply the state change.
  optional string uuid = 1;

  // The change in tserver state.
  optional StateChange change = 2;
}

message ChangeTServerStateRequestPB {
  // TODO(awong): consider setting tserver state in batches.
  optional TServerStateChangePB change = 1;

  enum HandleMissingTS {
    UNKNOWN_HANDLING = 0;
    ALLOW_MISSING_TSERVER = 1;
    DONT_ALLOW_MISSING_TSERVER = 2;
  }
  // If set to ALLOW_MISSING_TSERVER, will allow setting the state of the
  // tserver even if it hasn't been registered with the master and there is no
  // existing state associated with that server.
  optional HandleMissingTS handle_missing_tserver = 2 [default = DONT_ALLOW_MISSING_TSERVER];
}

message ChangeTServerStateResponsePB {
  optional MasterErrorPB error = 1;
}

// GetMasterRegistrationRequest/Response: get the instance id and
// HTTP/RPC addresses for this Master server.
message GetMasterRegistrationRequestPB {
}

message GetMasterRegistrationResponsePB {
  // Node instance information is always set.
  required NodeInstancePB instance_id = 1;

  // These fields are optional, as they won't be set if there's an
  // error retrieving the host/port information.
  optional ServerRegistrationPB registration = 2;

  // This server's role in the consensus configuration.
  optional consensus.RaftPeerPB.Role role = 3;

  // Set if there an error retrieving the registration information.
  optional MasterErrorPB error = 4;
}

// ListMastersRequest/Response: get information about all of the known
// master servers, including this node.
message ListMastersRequestPB {
}

message ListMastersResponsePB {
  // An entry for each individual master server.
  repeated ServerEntryPB masters = 1;

  // DEPRECATED, use 'error' field.
  optional AppStatusPB DEPRECATED_error = 2;

  // Set if there an error retrieving the registration information.
  optional MasterErrorPB error = 3;
}

// ReplaceTabletRequest/Response: replace a tablet with a new, empty one.
// The replaced tablet is deleted.
message ReplaceTabletRequestPB {
  optional bytes tablet_id = 1;
}

message ReplaceTabletResponsePB {
  // Set if there is an error replacing the tablet.
  optional MasterErrorPB error = 1;

  // The tablet id of the replacement tablet.
  optional bytes replacement_tablet_id = 2;
}

enum MasterFeatures {
  UNKNOWN_FEATURE = 0;
  // The master supports creating tables with non-covering range partitions.
  RANGE_PARTITION_BOUNDS = 1;
  // The master supports adding and dropping range partitions.
  ADD_DROP_RANGE_PARTITIONS = 2;
  // The master supports the 'ConnectToMaster' RPC.
  CONNECT_TO_MASTER = 3;
  // The catalog manager supports different replica management schemes
  // (see "kudu/consensus/replica_management.proto"). At least, both the
  // EVICT_FIRST (a.k.a. 3-2-3) and the PREPARE_REPLACEMENT_BEFORE_EVICTION
  // (a.k.a. 3-4-3) schemes.
  REPLICA_MANAGEMENT = 4;
  // The master supports generating and dispensing authz tokens.
  GENERATE_AUTHZ_TOKEN = 5;
}

service MasterService {
  // Set the default authz method to something invalid, so that if
  // we forget to set the option on a new RPC call, we'll get a build
  // failure.
  option (kudu.rpc.default_authz_method) = "MUST_SET_AUTHZ_PER_RPC";

  // TS->Master RPCs
  // ------------------------------------------------------------
  rpc TSHeartbeat(TSHeartbeatRequestPB) returns (TSHeartbeatResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeServiceUser";
  }

  // Client->Master RPCs
  // ------------------------------------------------------------

  // Used only by Kudu 1.3 and later.
  rpc ConnectToMaster(ConnectToMasterRequestPB) returns (ConnectToMasterResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc GetTabletLocations(GetTabletLocationsRequestPB) returns (GetTabletLocationsResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc CreateTable(CreateTableRequestPB) returns (CreateTableResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc IsCreateTableDone(IsCreateTableDoneRequestPB) returns (IsCreateTableDoneResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc DeleteTable(DeleteTableRequestPB) returns (DeleteTableResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc AlterTable(AlterTableRequestPB) returns (AlterTableResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc IsAlterTableDone(IsAlterTableDoneRequestPB) returns (IsAlterTableDoneResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc ListTables(ListTablesRequestPB) returns (ListTablesResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc GetTableStatistics(GetTableStatisticsRequestPB) returns (GetTableStatisticsResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  rpc GetTableLocations(GetTableLocationsRequestPB) returns (GetTableLocationsResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc GetTableSchema(GetTableSchemaRequestPB) returns (GetTableSchemaResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }

  // Administrative/monitoring RPCs
  // ------------------------------------------------------------
  rpc ListTabletServers(ListTabletServersRequestPB) returns (ListTabletServersResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc ListMasters(ListMastersRequestPB) returns (ListMastersResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClient";
  }
  rpc Ping(PingRequestPB) returns (PingResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClientOrServiceUser";
  }
  rpc ReplaceTablet(ReplaceTabletRequestPB) returns (ReplaceTabletResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeSuperUser";
  }
  rpc ChangeTServerState(ChangeTServerStateRequestPB) returns
      (ChangeTServerStateResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeSuperUser";
  }

  // Master->Master RPCs
  // ------------------------------------------------------------

  // NOTE: this RPC is also used by Kudu client <= 1.2 when first connecting to the
  // cluster.
  rpc GetMasterRegistration(GetMasterRegistrationRequestPB) returns
      (GetMasterRegistrationResponsePB) {
    option (kudu.rpc.authz_method) = "AuthorizeClientOrServiceUser";
  }
}