admin.proto

// Copyright 2016 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

syntax = "proto3";
package cockroach.server.serverpb;
option go_package = "serverpb";

import "config/zonepb/zone.proto";
import "jobs/jobspb/jobs.proto";
import "server/serverpb/status.proto";
import "storage/enginepb/mvcc.proto";
import "kv/kvserver/kvserverpb/liveness.proto";
import "kv/kvserver/kvserverpb/log.proto";
import "ts/catalog/chart_catalog.proto";
import "util/metric/metric.proto";
import "gogoproto/gogo.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";

// ZoneConfigurationLevel indicates, for objects with a Zone Configuration,
// the object level at which the configuration is defined. This is needed
// because objects without a specifically indicated Zone Configuration will
// inherit the configuration of their "parent".
enum ZoneConfigurationLevel {
  UNKNOWN = 0;
  // CLUSTER indicates that this object uses the cluster default Zone Configuration.
  CLUSTER = 1;
  // DATABASE indicates that this object uses a database-level Zone Configuration.
  DATABASE = 2;
  // TABLE indicates that this object uses a table-level Zone Configuration.
  TABLE = 3;
}

// DatabasesRequest requests a list of databases.
message DatabasesRequest {
}

// DatabasesResponse contains a list of databases.
message DatabasesResponse {
  repeated string databases = 1;
}

// DatabaseDetailsRequest requests detailed information about the specified
// database
message DatabaseDetailsRequest {
  // database is the name of the database we are querying.
  string database = 1;
}

// DatabaseDetailsResponse contains grant information and table names for a
// database.
message DatabaseDetailsResponse {
  message Grant {
    // user is the user that this grant applies to.
    string user = 1;

    // privileges are the abilities this grant gives to the user.
    repeated string privileges = 2;
  }

  // grants are the results of SHOW GRANTS for this database.
  repeated Grant grants = 1 [(gogoproto.nullable) = false];

  // table_names contains the names of all tables (SHOW TABLES) in this
  // database.
  repeated string table_names = 2;
  // descriptor_id is an identifier used to uniquely identify this database.
  // It can be used to find events pertaining to this database by filtering on
  // the 'target_id' field of events.
  int64 descriptor_id = 3 [(gogoproto.customname) = "DescriptorID"];
  // The zone configuration in effect for this database.
  cockroach.config.zonepb.ZoneConfig zone_config = 4 [(gogoproto.nullable) = false];
  // The level at which this object's zone configuration is set.
  ZoneConfigurationLevel zone_config_level = 5;
}

// TableDetailsRequest is a request for detailed information about a table.
message TableDetailsRequest {
  // database is the database that contains the table we're interested in.
  string database = 1;

  // table is the name of the table that we're querying.
  string table = 2;
}

// TableDetailsResponse contains grants, column names, and indexes for
// a table.
message TableDetailsResponse {
  // Grant is an entry from SHOW GRANTS.
  message Grant {
    // user is the user that this grant applies to.
    string user = 1;

    // privileges are the abilities this grant gives to the user.
    repeated string privileges = 2;
  }

  message Column {
    // name is the name of the column.
    string name = 1;

    // type is the SQL type (INT, STRING, etc.) of this column.
    string type = 2;

    // nullable is whether this column can contain NULL.
    bool nullable = 3;

    // default_value is the default value of this column.
    string default_value = 4;

    // generation_expression is the generator expression if the column is computed.
    string generation_expression = 5;

    // hidden is whether this column is hidden.
    bool hidden = 6;
  }

  message Index {
    // name is the name of this index.
    string name = 1;

    // unique is whether this a unique index (i.e. CREATE UNIQUE INDEX).
    bool unique = 2;

    // seq is an internal variable that's passed along.
    int64 seq = 3;

    // column is the column that this index indexes.
    string column = 4;

    // direction is either "ASC" (ascending) or "DESC" (descending).
    string direction = 5;

    // storing is an internal variable that's passed along.
    bool storing = 6;

    // implicit is an internal variable that's passed along.
    bool implicit = 7;
  }

  repeated Grant grants = 1 [(gogoproto.nullable) = false];
  repeated Column columns = 2 [(gogoproto.nullable) = false];
  repeated Index indexes = 3 [(gogoproto.nullable) = false];

  // range_count is the size of the table in ranges. This provides a rough
  // estimate of the storage requirements for the table.
  // TODO(mrtracy): The TableStats method also returns a range_count field which
  // is more accurate than this one; TableDetails calculates this number using
  // a potentially faster method that is subject to cache staleness. We should
  // consider removing or renaming this field to reflect that difference. See
  // Github issue #5435 for more information.
  int64 range_count = 4;
  // create_table_statement is the output of "SHOW CREATE" for this table;
  // it is a SQL statement that would re-create the table's current schema if
  // executed.
  string create_table_statement = 5;
  // The zone configuration in effect for this table.
  cockroach.config.zonepb.ZoneConfig zone_config = 6 [(gogoproto.nullable) = false];
  // The level at which this object's zone configuration is set.
  ZoneConfigurationLevel zone_config_level = 7;
  // descriptor_id is an identifier used to uniquely identify this table.
  // It can be used to find events pertaining to this table by filtering on
  // the 'target_id' field of events.
  int64 descriptor_id = 8 [(gogoproto.customname) = "DescriptorID"];
}

// TableStatsRequest is a request for detailed, computationally expensive
// information about a table.
message TableStatsRequest {
  // database is the database that contains the table we're interested in.
  string database = 1;
  // table is the name of the table that we're querying.
  string table = 2;
}

// TableStatsResponse contains detailed, computationally expensive information
// about a table.
message TableStatsResponse {
  // range_count is the number of ranges, as determined from a query of range
  // meta keys.
  int64 range_count = 1;
  // replica_count is the number of replicas of any range of this table, as
  // found by querying nodes which are known to have replicas. When compared
  // with range_count, this can be used to estimate the current replication
  // factor of the table.
  int64 replica_count = 2;
  // node_count is the number of nodes which contain data for this table,
  // according to a query of range meta keys.
  int64 node_count = 3;
  // stats is the summation of MVCCStats for all replicas of this table
  // across the cluster.
  cockroach.storage.enginepb.MVCCStats stats = 4 [(gogoproto.nullable) = false];
  // approximate_disk_bytes is an approximation of the disk space (in bytes)
  // used for all replicas of this table across the cluster.
  uint64 approximate_disk_bytes = 6;
  // MissingNode represents information on a node which should contain data
  // for this table, but could not be contacted during this request.
  message MissingNode {
    // The ID of the missing node.
    string node_id = 1 [(gogoproto.customname) = "NodeID"];
    // The error message that resulted when the query sent to this node failed.
    string error_message = 2;
  }
  // A list of nodes which should contain data for this table (according to
  // cluster metadata), but could not be contacted during this request.
  repeated MissingNode missing_nodes = 5 [(gogoproto.nullable) = false];
}

// NonTableStatsRequest requests statistics on cluster data ranges that do not
// belong to SQL tables.
message NonTableStatsRequest {
}

// NonTableStatsResponse returns statistics on various cluster data ranges
// that do not belong to SQL tables. The statistics for each range are returned
// as a TableStatsResponse.
message NonTableStatsResponse {
  // Information on time series ranges.
  TableStatsResponse time_series_stats = 1;
  // Information for remaining (non-table, non-time-series) ranges.
  TableStatsResponse internal_use_stats = 2;
}

// UsersRequest requests a list of users.
message UsersRequest {
}

// UsersResponse returns a list of users.
message UsersResponse {
  // User is a CockroachDB user.
  message User {
    string username = 1;
  }

  // usernames is a list of users for the CockroachDB cluster.
  repeated User users = 1 [(gogoproto.nullable) = false];
}

// EventsRequest is a request for event log entries, optionally filtered
// by the specified event type and/or target_id.
message EventsRequest {
  string type = 1;
  int64 target_id = 2;
  // limit is the total number of results that are retrieved by the query. If
  // this is omitted or set to 0, the default maximum number of results are
  // returned. When set to > 0, at most only that number of results are
  // returned. When set to < 0, an unlimited number of results are returned.
  int32 limit = 3;
  // unredacted_events indicates that the values in the events should
  // not be redacted. The default is to redact, so that older versions
  // of `cockroach zip` do not see un-redacted values by default.
  // For good security, this field is only obeyed by the server after
  // checking that the client of the RPC is an admin user.
  bool unredacted_events = 4;
}

// EventsResponse contains a set of event log entries. This is always limited
// to the latest N entries (N is enforced in the associated endpoint).
message EventsResponse {
  message Event {
    // timestamp is the time at which the event occurred.
    google.protobuf.Timestamp timestamp = 1 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];

    // event_type is the type of the event (e.g. "create_table", "drop_table".
    string event_type = 2;

    // target_id is the target for this event.
    int64 target_id = 3 [(gogoproto.customname) = "TargetID"];

    // reporting_id is the reporting ID for this event.
    int64 reporting_id = 4 [(gogoproto.customname) = "ReportingID"];

    // info has more detailed information for the event. The contents vary
    // depending on the event.
    string info = 5;

    // unique_id is a unique identifier for this event.
    bytes unique_id = 6 [(gogoproto.customname) = "UniqueID"];
  }

  repeated Event events = 1 [(gogoproto.nullable) = false];
}

// SetUIDataRequest stores the given key/value pairs in the system.ui table.
message SetUIDataRequest {
  // key_values is a map of keys to bytes values. Each key will be stored
  // with its corresponding value as a separate row in system.ui.
  map<string, bytes> key_values = 1;
}

// SetUIDataResponse is currently an empty response.
message SetUIDataResponse {
}

// GETUIDataRequest requests the values for the given keys from the system.ui
// table.
message GetUIDataRequest {
  repeated string keys = 1;
}

// GetUIDataResponse contains the requested values and the times at which
// the values were last updated.
message GetUIDataResponse {
  message Value {
    // value is the value of the requested key.
    bytes value = 1;

    // last_updated is the time at which the value was last updated.
    google.protobuf.Timestamp last_updated = 2 [(gogoproto.nullable) = false, (gogoproto.stdtime) = true];
  }

  // key_values maps keys to their retrieved values. If this doesn't contain a
  // a requested key, that key was not found.
  map<string, Value> key_values = 1 [(gogoproto.nullable) = false];
}

// ClusterRequest requests metadata for the cluster.
message ClusterRequest {
}

// ClusterResponse contains metadata for the cluster.
message ClusterResponse {
  // The unique ID used to identify this cluster.
  string cluster_id = 1 [(gogoproto.customname) = "ClusterID"];
  // True if diagnostics reporting is enabled for the cluster.
  bool reporting_enabled = 2;
  // True if enterprise features are enabled for the cluster.
  bool enterprise_enabled = 3;
}

// DrainRequest requests the server to enter the specified draining mode. The
// server first deactivates all the modes specified in 'off' and then activates
// all those in 'on'.
message DrainRequest {
  // deprecated_probe_indicator works as follows:
  // - if nil, it indicates that the request is a probe only and
  //   the server should not actually drain. This indicator
  //   is supported for pre-20.1 RPC clients which do not know
  //   about the skip_drain field below.
  // - if non-nil, it must be exactly equal to the slice [0, 1].
  //   Other values result in an error. When non-nil,
  //   it implies do_drain = true regardless of the value of the
  //   other field (pre-20.1 clients don't populate the other field).
  //
  // This field will be removed in 20.2 in favor of
  // do_drain below.
  repeated int32 deprecated_probe_indicator = 1;
  reserved 2;
  // When true, terminates the process after the server has started draining.
  // Setting both shutdown and do_drain to false causes
  // the request to only operate as a probe.
  // Setting do_drain to false and shutdown to true causes
  // the server to shut down immediately without
  // first draining.
  bool shutdown = 3;
  // When true, perform the drain phase. See the comment above on
  // shutdown for an explanation of the interaction between the two.
  // do_drain is also implied by a non-nil deprecated_probe_indicator.
  bool do_drain = 4;
}

// DrainResponse is the response to a successful DrainRequest.
message DrainResponse {
  // deprecated_drain_status works as follows:
  // - if the server is NOT currently draining,
  //   it will be set to an empty or nil slice.
  // - a non-nil slice indicates the server is currently
  //   draining.
  //
  // This field exists for the benefit of 19.x clients
  // and will be removed in 20.2.
  repeated int32 deprecated_drain_status = 1;
  // is_draining is set to true iff the server is currently draining.
  // This is set to true in response to a request where skip_drain
  // is false; but it can also be set to true in response
  // to a probe request (!shutdown && skip_drain) if another
  // drain request has been issued prior or asynchronously.
  bool is_draining = 2;
  // drain_remaining_indicator measures, at the time of starting to
  // process the corresponding drain request, how many actions to
  // fully drain the node were deemed to be necessary. Some, but not
  // all, of these actions may already have been carried out by the
  // time this indicator is received by the client. The client should
  // issue requests until this indicator first reaches zero, which
  // indicates that the node is fully drained.
  //
  // The API contract is the following:
  //
  // - upon a first Drain call with do_drain set, the remaining
  //   indicator will have some value >=0. If >0, it indicates that
  //   drain is pushing state away from the node. (What this state
  //   precisely means is left unspecified for this field. See below
  //   for details.)
  //
  // - upon a subsequent Drain call with do_drain set, the remaining
  //   indicator should have reduced in value. The drain process does best
  //   effort at shedding state away from the node; hopefully, all the
  //   state is shed away upon the first call and the progress
  //   indicator can be zero as early as the second call. However,
  //   if there was a lot of state to shed, it is possible for
  //   timeout to be encountered upon the first call. In that case, the
  //   second call will do some more work and return a non-zero value
  //   as well.
  //
  // - eventually, in an iterated sequence of DrainRequests with
  //   do_drain set, the remaining indicator should reduce to zero. At
  //   that point the client can conclude that no state is left to
  //   shed, and it should be safe to shut down the node with a
  //   DrainRequest with shutdown = true.
  //
  // Note that this field is left unpopulated (and thus remains at
  // zero) for pre-20.1 nodes. A client can recognize this by
  // observing is_draining to be false after a request with do_drain =
  // true: the is_draining field is also left unpopulated by pre-20.1
  // nodes.
  uint64 drain_remaining_indicator = 3;

  // drain_remaining_description is an informal (= not
  // machine-parsable) string that explains the progress of the drain
  // process to human eyes. This is intended for use mainly for
  // troubleshooting.
  //
  // The field is only populated if do_drain is true in the
  // request.
  string drain_remaining_description = 4;
}

// CommissionStatusRequest requests the commissioning status for the specified
// or, if none are specified, all nodes.
message CommissionStatusRequest {
  repeated int32 node_ids = 1 [(gogoproto.customname) = "NodeIDs",
                               (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
}

// CommissionStatusResponse lists commissioning statuses for a number of
// NodeIDs.
message CommissionStatusResponse {
  message Status {
    int32 node_id = 1 [ (gogoproto.customname) = "NodeID",
                        (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
    bool is_live = 2;
    // The number of replicas on the node, computed by scanning meta2 ranges.
    int64 replica_count = 3;
    bool deprecated_decommissioning = 4;
    bool draining = 5;

    cockroach.kv.kvserver.storagepb.CommissionStatus CommissionStatus = 6;
  }
  // Status of all affected nodes.
  repeated Status status = 2 [(gogoproto.nullable) = false];
}

// CommissionRequest requests the server to set the commission status on
// all nodes specified by node_id to the value of CommissionStatus.
//
// If no node_id is given, it targets the recipient node.
message CommissionRequest {
  repeated int32 node_ids = 1 [(gogoproto.customname) = "NodeIDs",
                               (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
  bool deprecated_decommissioning = 2;
  cockroach.kv.kvserver.storagepb.CommissionStatus CommissionStatus = 3;
}

// SettingsRequest inquires what are the current settings in the cluster.
message SettingsRequest {
  // The array of setting names to retrieve.
  // An empty keys array means "all".
  repeated string keys = 1;

  // Indicate whether to see unredacted setting values.
  // This is opt-in so that a previous version `cockroach zip`
  // does not start reporting values when this becomes active.
  // For good security, the server only obeys this after it checks
  // that the logger-in user has admin privilege.
  bool unredacted_values = 2;
}

// SettingsResponse is the response to SettingsRequest.
message SettingsResponse {
   message Value {
      string value = 1;
      string type = 2;
      string description = 3;
      bool public = 4;
   }
   map<string, Value> key_values = 1 [(gogoproto.nullable) = false];
}

// HealthRequest requests a liveness or readiness check.
//
// A liveness check is triggered via ready set to false. In this mode,
// an empty response is returned immediately, that is, the caller merely
// learns that the process is running.
//
// A readiness check (ready == true) is suitable for determining whether
// user traffic should be directed at a given node, for example by a load
// balancer. In this mode, a successful response is returned only if the
// node:
//
// - is not in the process of shutting down or booting up (including
//   waiting for cluster bootstrap);
// - is regarded as healthy by the cluster via the recent broadcast of
//   a liveness beacon. Absent either of these conditions, an error
//   code will result.
//
message HealthRequest {
  // ready specifies whether the client wants to know whether the
  // target node is ready to receive traffic. If a node is unready, an
  // error will be returned.
  bool ready = 1;
}

// HealthResponse is the response to HealthRequest. It currently does not
// contain any information.
message HealthResponse {
}

// LivenessRequest requests liveness data for all nodes on the cluster.
message LivenessRequest {
}

// LivenessResponse contains the liveness status of each node on the cluster.
message LivenessResponse {
  repeated cockroach.kv.kvserver.storagepb.Liveness livenesses = 1 [(gogoproto.nullable) = false];
  map<int32, cockroach.kv.kvserver.storagepb.NodeLivenessStatus> statuses = 2 [
    (gogoproto.nullable) = false,
    (gogoproto.castkey) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"
  ];
}

// JobsRequest requests system job information of the given status and type.
message JobsRequest {
  int32 limit = 1;
  string status = 2;
  cockroach.sql.jobs.jobspb.Type type = 3;
}

// JobsResponse contains the job record for each matching job.
message JobsResponse {
  message Job {
    int64 id = 1 [(gogoproto.customname) = "ID"];
    string type = 2;
    string description = 3;
    string statement = 16;
    string username = 4;
    repeated uint32 descriptor_ids = 5 [
      (gogoproto.customname) = "DescriptorIDs",
      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/sql/sqlbase.ID"
    ];
    string status = 6;
    google.protobuf.Timestamp created = 7 [(gogoproto.stdtime) = true];
    google.protobuf.Timestamp started = 8 [(gogoproto.stdtime) = true];
    google.protobuf.Timestamp finished = 9 [(gogoproto.stdtime) = true];
    google.protobuf.Timestamp modified = 10 [(gogoproto.stdtime) = true];
    float fraction_completed = 11;
    string error = 12;
    // highwater_timestamp is the highwater timestamp returned as normal
    // timestamp. This is appropriate for display to humans.
    google.protobuf.Timestamp highwater_timestamp = 13 [(gogoproto.stdtime) = true];
    // highwater_decimal is the highwater timestamp in the proprietary decimal
    // form used by logical timestamps internally. This is appropriate to pass
    // to a "AS OF SYSTEM TIME" SQL statement.
    string highwater_decimal = 14;
    string running_status = 15;
  }

  repeated Job jobs = 1 [(gogoproto.nullable) = false];
}

// LocationsRequest requests system locality location information.
message LocationsRequest {
}

// JobsResponse contains the job record for each matching job.
message LocationsResponse {
  message Location {
    string locality_key = 1;
    string locality_value = 2;
    double latitude = 3;
    double longitude = 4;
  }

  repeated Location locations = 1 [(gogoproto.nullable) = false];
}

// RangeLogRequest request the history of a range from the range log.
message RangeLogRequest {
  // TODO(tamird): use [(gogoproto.customname) = "RangeID"] below. Need to
  // figure out how to teach grpc-gateway about custom names.
  // If RangeID is 0, returns range log history without filtering by range.
  int64 range_id = 1;
  // limit is the total number of results that are retrieved by the query. If
  // this is omitted or set to 0, the default maximum number of results are
  // returned. When set to > 0, at most only that number of results are
  // returned. When set to < 0, an unlimited number of results are returned.
  int32 limit = 2;
}

// RangeLogResponse contains a list of entries from the range log table.
message RangeLogResponse {
  // To avoid porting the pretty printing of keys and descriptors to
  // javascript, they will be precomputed on the serverside.
  message PrettyInfo {
    string updated_desc = 1;
    string new_desc = 2;
    string added_replica = 3;
    string removed_replica = 4;
    string reason = 5;
    string details = 6;
  }
  message Event {
    cockroach.kv.kvserver.storagepb.RangeLogEvent event = 1 [(gogoproto.nullable) = false];
    PrettyInfo pretty_info = 2 [(gogoproto.nullable) = false];
  }
  reserved 1; // Previously used.
  repeated Event events = 2 [(gogoproto.nullable) = false];
}

// QueryPlanRequest requests the query plans for a SQL string.
message QueryPlanRequest {
  // query is the SQL query string.
  string query = 1;
}

// QueryPlanResponse contains the query plans for a SQL string (currently only
// the distsql physical query plan).
message QueryPlanResponse {
  string distsql_physical_query_plan = 1 [(gogoproto.customname) = "DistSQLPhysicalQueryPlan"];
}

message DataDistributionRequest {
}

message DataDistributionResponse {
  message ZoneConfig {
    // target is the object the zone config applies to, e.g. "DATABASE db" or
    // "PARTITION north_america OF TABLE users".
    string target = 1;

    config.zonepb.ZoneConfig config = 2 [(gogoproto.nullable) = false];

    reserved 3;

    // config_sql is the SQL representation of config.
    string config_sql = 4 [(gogoproto.customname) = "ConfigSQL"];
  }

  message TableInfo {
    map<int32, int64> replica_count_by_node_id = 1 [(gogoproto.castkey) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];

    int64 zone_config_id = 2;
    google.protobuf.Timestamp dropped_at = 3 [(gogoproto.stdtime) = true];
  }

  message DatabaseInfo {
    // By table name.
    map<string, TableInfo> table_info = 1 [(gogoproto.nullable) = false];
  }

  // By database name.
  map<string, DatabaseInfo> database_info = 1 [(gogoproto.nullable) = false];

  reserved 2;

  // By zone name.
  map<string, ZoneConfig> zone_configs = 3 [(gogoproto.nullable) = false];
}

  // MetricMetadataRequest requests metadata for all metrics.
message MetricMetadataRequest {
}

// MetricMetadataResponse contains the metadata for all metics.
message MetricMetadataResponse {
  map<string, cockroach.util.metric.Metadata> metadata = 1 [(gogoproto.nullable) = false];
}

message EnqueueRangeRequest {
  // The node on which the queue should process the range. If node_id is 0,
  // the request will be forwarded to all other nodes.
  int32 node_id = 1 [(gogoproto.customname) = "NodeID",
                     (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
  // The name of the replica queue to run the range through. Matched against
  // each queue's name field. See the implementation of baseQueue for details.
  string queue = 2;
  // The ID of the range to run through the queue.
  int32 range_id = 3 [(gogoproto.customname) = "RangeID",
                      (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.RangeID"];
  // If set, run the queue's process method without first checking whether the
  // replica should be processed by calling shouldQueue.
  bool skip_should_queue = 4;
}

message EnqueueRangeResponse {
  message Details {
    int32 node_id = 1 [(gogoproto.customname) = "NodeID",
                       (gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/roachpb.NodeID"];
    // All trace events collected while processing the range in the queue.
    repeated TraceEvent events = 2;
    // The error message from the queue's processing, if any.
    string error = 3;
  }
  repeated Details details = 1;
}

// ChartCatalogRequest requests returns a catalog of Admin UI charts.
message ChartCatalogRequest {
}

// ChartCatalogResponse returns a catalog of Admin UI charts useful for debugging.
message ChartCatalogResponse {
  repeated cockroach.ts.catalog.ChartSection catalog = 1 [(gogoproto.nullable) = false];
}

// Admin is the gRPC API for the admin UI. Through grpc-gateway, we offer
// REST-style HTTP endpoints that locally proxy to the gRPC endpoints.
service Admin {
  // URL: /_admin/v1/users
  rpc Users(UsersRequest) returns (UsersResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/users"
    };
  }

  // URL: /_admin/v1/databases
  rpc Databases(DatabasesRequest) returns (DatabasesResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/databases"
    };
  }

  // Example URL: /_admin/v1/databases/system
  rpc DatabaseDetails(DatabaseDetailsRequest) returns (DatabaseDetailsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/databases/{database}"
    };
  }

  // Example URL: /_admin/v1/databases/system/tables/ui
  rpc TableDetails(TableDetailsRequest) returns (TableDetailsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/databases/{database}/tables/{table}"
    };
  }

  // Example URL: /_admin/v1/databases/system/tables/ui/stats
  rpc TableStats(TableStatsRequest) returns (TableStatsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/databases/{database}/tables/{table}/stats"
    };
  }

  // Example URL: /_admin/v1/nontablestats
  rpc NonTableStats(NonTableStatsRequest) returns (NonTableStatsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/nontablestats"
    };
  }

  // Example URLs:
  // Example URLs:
  // - /_admin/v1/events
  // - /_admin/v1/events?limit=100
  // - /_admin/v1/events?type=create_table
  // - /_admin/v1/events?type=create_table&limit=100
  // - /_admin/v1/events?type=drop_table&target_id=4
  // - /_admin/v1/events?type=drop_table&target_id=4&limit=100
  rpc Events(EventsRequest) returns (EventsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/events"
    };
  }

  // This requires a POST. Because of the libraries we're using, the POST body
  // must be in the following format:
  //
  // {"key_values":
  //   { "key1": "base64_encoded_value1"},
  //   ...
  //   { "keyN": "base64_encoded_valueN"},
  // }
  //
  // Note that all keys are quoted strings and that all values are base64-
  // encoded.
  //
  // Together, SetUIData and GetUIData provide access to a "cookie jar" for the
  // admin UI. The structure of the underlying data is meant to be opaque to the
  // server.
  rpc SetUIData(SetUIDataRequest) returns (SetUIDataResponse) {
    option (google.api.http) = {
      post: "/_admin/v1/uidata"
      body: "*"
    };
  }

  // Example URLs:
  // - /_admin/v1/uidata?keys=MYKEY
  // - /_admin/v1/uidata?keys=MYKEY1&keys=MYKEY2
  //
  // Yes, it's a little odd that the query parameter is named "keys" instead of
  // "key". I would've preferred that the URL parameter be named "key". However,
  // it's clearer for the protobuf field to be named "keys," which makes the URL
  // parameter "keys" as well.
  rpc GetUIData(GetUIDataRequest) returns (GetUIDataResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/uidata"
    };
  }

  // Cluster returns metadata for the cluster.
  rpc Cluster(ClusterRequest) returns (ClusterResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/cluster"
    };
  }

  // Settings returns the cluster-wide settings for the cluster.
  rpc Settings(SettingsRequest) returns (SettingsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/settings"
    };
  }

  // Health returns liveness for the node target of the request.
  rpc Health(HealthRequest) returns (HealthResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/health"
      additional_bindings {get : "/health"}
    };
  }

  // Liveness returns the liveness state of all nodes on the cluster.
  rpc Liveness(LivenessRequest) returns (LivenessResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/liveness"
    };
  }

  // Jobs returns the job records for all jobs of the given status and type.
  rpc Jobs(JobsRequest) returns (JobsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/jobs"
    };
  }

  // Locations returns the locality location records.
  rpc Locations(LocationsRequest) returns (LocationsResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/locations"
    };
  }

  // QueryPlan returns the query plans for a SQL string.
  rpc QueryPlan(QueryPlanRequest) returns (QueryPlanResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/queryplan"
    };
  }

  // Drain puts the node into the specified drain mode(s) and optionally
  // instructs the process to terminate.
  // We do not expose this via HTTP unless we have a way to authenticate
  // + authorize streaming RPC connections. See #42567.
  rpc Drain(DrainRequest) returns (stream DrainResponse) {
  }

  // Decommission puts the node(s) into the specified commissioning state.
  // If this ever becomes exposed via HTTP, ensure that it performs
  // authorization. See #42567.
  //
  // The name of this method, Decommission, is a misnomer for legacy
  // reasons. It should be thought of as `Commission` instead.
  rpc Decommission(CommissionRequest) returns (CommissionStatusResponse) { }

  // DecommissionStatus retrieves the commission status of the specified nodes.
  // If this ever becomes exposed via HTTP, ensure that it performs
  // authorization. See #42567.
  //
  // The name of this method, DecommissionStatus, is a misnomer for legacy
  // reasons. It should be thought of as `CommissionStatus` instead.
  rpc DecommissionStatus(CommissionStatusRequest) returns (CommissionStatusResponse) { }

  // URL: /_admin/v1/rangelog
  // URL: /_admin/v1/rangelog?limit=100
  // URL: /_admin/v1/rangelog/1
  // URL: /_admin/v1/rangelog/1?limit=100
  rpc RangeLog(RangeLogRequest) returns (RangeLogResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/rangelog"
      additional_bindings {
        get: "/_admin/v1/rangelog/{range_id}"
     }
    };
  }

  rpc DataDistribution(DataDistributionRequest) returns (DataDistributionResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/data_distribution"
    };
  }

  // URL: /_admin/v1/metricmetadata
  rpc AllMetricMetadata(MetricMetadataRequest) returns (MetricMetadataResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/metricmetadata"
    };
  }

  // URL: /_admin/v1/chartcatalog
  rpc ChartCatalog(ChartCatalogRequest) returns (ChartCatalogResponse) {
    option (google.api.http) = {
      get: "/_admin/v1/chartcatalog"
    };
  }


  // EnqueueRange runs the specified range through the specified queue on the
  // range's leaseholder store, returning the detailed trace and error
  // information from doing so. Parameters must be provided in the body of the
  // POST request.
  // For example:
  //
  // {
  //   "queue": "raftlog",
  //   "rangeId": 10
  // }
  rpc EnqueueRange(EnqueueRangeRequest) returns (EnqueueRangeResponse) {
    option (google.api.http) = {
      post: "/_admin/v1/enqueue_range"
      body : "*"
    };
  }
}