syntax = "proto2";

import "google/protobuf/descriptor.proto";
import "scalapb/scalapb.proto";

package mlflow;

option java_package = "com.databricks.api.proto.databricks";
option (scalapb.options).flat_package = true;


// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.FieldOptions {
  // Indicates an overriding visibility for this field. This can only reduce the visibility;
  // a public field in an internal API will not have an effect.
  optional Visibility visibility = 51310;

  // This annotation indicates that certain fields must be supplied for the request to be carried
  // out successfully.
  // A request field may go from being required to optional over time, but a field may not
  // go from being optional to required, for backwards compatiblity reasons.
  // Request RPCs are validated automatically prior to processing for required fields, but
  // returned values are not validated in any way.
  optional bool validate_required = 51311;

  // Causes the fields within the tagged Message to be inlined into this Message, for the purposes
  // of our JSON API.
  // For example, rather than serializing
  //   {
  //     "attrs" : {
  //       "cluster_name" : "Foo"
  //     }
  //   }
  // If "attrs" were marked json_inline, we would upgrade cluster_name to a top-level field:
  //   {
  //     "cluster_name" : "Foo"
  //   }
  // Note that this is only applicable to singular Message fields.
  optional bool json_inline = 51312;

  // Causes a field which conceptually represents a Map to be serialized as a JSON Map.
  // The given field must be a Message with exactly 2 fields called "key" and "value", where key
  // must be a string.
  // For example, rather than serializing
  //   [ { "key" : "spark.speculation", "value" : "false" } ]
  // If this field were marked json_map, we would serialize it as
  //   { "spark.speculation" : "false" }
  optional bool json_map = 51313;

  // The documentation meta data for this field. This gets added automatically when the proto is
  // parsed.
  // There are as many doc blocks as visibility levels.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata field_doc = 51314;
}

// Defines the set of options declared for every service RPC which are used to
// direct RPCs to endpoints, as well as other metadata about the RPC.
message DatabricksRpcOptions {
  repeated HttpEndpoint endpoints = 1;

  // Indicates which users are allowed to initiate this RPC.
  optional Visibility visibility = 2;

  // Complete definition of all error codes (from a statically defined set) which this method
  // may return.
  repeated ErrorCode error_codes = 3;

  // If defined, a rate limit will be applied to this RPC for all requests from the API proxy.
  optional RateLimit rate_limit = 4;

  // If defined, overrides the default title used for in the API docs. See ProtobufDocGenerator
  // for more info.
  optional string rpc_doc_title = 5;
}

// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.MethodOptions {
  optional DatabricksRpcOptions rpc = 51310;

  // The documentation metadata.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata method_doc = 51314; // Same id everywhere
}

// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.MessageOptions {
  // The documentation metadata.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata message_doc = 51314; // Same id everywhere
}

// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.ServiceOptions {
  // The documentation metadata.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata service_doc = 51314; // Same id everywhere
}

// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.EnumOptions {
  // The documentation metadata.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata enum_doc = 51314; // Same id everywhere
}

// Note: 51310 is the beginning of the range of proto extension values for use by applications.
extend google.protobuf.EnumValueOptions {
  // Indicates an overriding visibility for this field. This can only reduce the visibility;
  // a public field in an internal API will not have an effect.
  optional Visibility enum_value_visibility = 51310;
  // The documentation metadata.
  // This is not meant to be crafted by hand; this will be automatically generated when parsing
  // the proto file.
  repeated DocumentationMetadata enum_value_doc = 51314; // Same id everywhere
}

message HttpEndpoint {
  // HTTP method like POST or GET.
  optional string method = 1 [default = "POST"];

  // Conceptual path of the API, like "/clusters" or "/clusters/create". Should start with a slash.
  optional string path = 2;

  // A version like 1.1 which is prepended to the URL (e.g., GET /1.1/clusters).
  // Breaking changes to an RPC must use a different version number.
  optional ApiVersion since = 3;
}

message ApiVersion {
  optional int32 major = 1;
  optional int32 minor = 2;
}

// API rate limits applied to RPCs coming from the API Proxy. The rate limits are applied on a
// per organization basis.
message RateLimit {
  // The maximum burst of API requests allowed for a single endpoint. In the context of the
  // token bucket algorithm, this constant represents the total capacity of the token bucket.
  optional int64 max_burst = 1;

  // The maximum sustained request per second limit for a single endpoint. In the context of the,
  // token bucket algorithm, this constant represents the rate at which the token bucket fills.
  optional int64 max_sustained_per_second = 2;
}

// Visibility defines who is allowed to use the RPC.
enum Visibility {
  // Public indicates visible to both external and internal customers.
  PUBLIC = 1;

  // Internal is only available to Databricks-internal clients.
  INTERNAL = 2;

  // Public-undocumented are accessible via public endpoints, but not documented. This is useful
  // for internal clients that depend on public endpoints (e.g. workflows running in the driver).
  PUBLIC_UNDOCUMENTED = 3;
}

// A block of documentation that is added to the AST after parsing the original protocol buffer.
message DocumentationMetadata {
  // The string of documentation attached to this particular item.
  optional string docstring = 1;
  // The string of documentation that is *before* this item. This only makes sense for top-level
  // items such as (top-level) messages, (top-level) enumerations, or services. In all other
  // cases, this string is empty.
  optional string lead_doc = 2;
  // The visibility level when the docstring was generated.
  // The documentation extractor builds multiple versions of the documentation, one for each
  // visibility level. The documentation is then generated for each visibility level.
  optional Visibility visibility = 3;
  // The original proto path in the internal representation. This is useful when performing field
  // flattening to figure out what the original field was.
  // One example is ["jobs","Run","original_attempt_run_id"] for jobs.
  // This path is unique.
  repeated string original_proto_path = 4;
  // The location (line number) of the start of the documentation. This is required to keep the
  // pieces of documentation sorted.
  optional int32 position = 5;
}

enum ErrorCode {
  //
  // Internal, system-level error codes, which generally cannot be resolved by the user, but
  // instead are due to service issues.
  //
  // Generic internal error occurred.
  INTERNAL_ERROR = 1;

  // An internal system could not be contacted due to a period of unavailability.
  TEMPORARILY_UNAVAILABLE = 2;

  // Indicates that an IOException has been internally thrown.
  IO_ERROR = 3;

  // The request is invalid.
  BAD_REQUEST = 4;

  //
  // Common application-level error codes, which were caused by the user input but may be returned
  // by multiple services.
  //
  // Supplied value for a parameter was invalid (e.g., giving a number for a string parameter).
  INVALID_PARAMETER_VALUE = 1000;

  // Indicates that the given API endpoint does not exist.
  ENDPOINT_NOT_FOUND = 1001;

  // Indicates that the given API request was malformed.
  MALFORMED_REQUEST = 1002;

  // If one or more of the inputs to a given RPC are not in a valid state for the action.
  INVALID_STATE = 1003;

  // If a given user/entity doesn't have the required permission(s) to perform an action
  PERMISSION_DENIED = 1004;

  // If a given user/entity is trying to use a feature which has been disabled
  FEATURE_DISABLED = 1005;

  // If customer-provided credentials are not authorized to perform an operation
  CUSTOMER_UNAUTHORIZED = 1006;

  // If the API request is rejected due to throttling
  REQUEST_LIMIT_EXCEEDED = 1007;

  ///////////
  // VAULT //
  ///////////

  // If the user attempts to perform an invalid state transition on a shard.
  INVALID_STATE_TRANSITION = 2001;

  // Unable to perform the operation because the shard was locked by some other operation.
  COULD_NOT_ACQUIRE_LOCK = 2002;

  ///////////////
  // EXECUTION //
  ///////////////

  // Operation was performed on a resource that already exists.
  RESOURCE_ALREADY_EXISTS = 3001;

  // Operation was performed on a resource that does not exist.
  RESOURCE_DOES_NOT_EXIST = 3002;

  ///////////
  // DBFS ///
  ///////////

  QUOTA_EXCEEDED = 4001;

  MAX_BLOCK_SIZE_EXCEEDED = 4002;

  MAX_READ_SIZE_EXCEEDED = 4003;

  //////////////
  // CLUSTERS //
  //////////////

  DRY_RUN_FAILED = 5001;

  // Cluster request was rejected because it would exceed a resource limit.
  RESOURCE_LIMIT_EXCEEDED = 5002;

  //////////////
  // WORKSPACE //
  //////////////

  DIRECTORY_NOT_EMPTY = 6001;

  DIRECTORY_PROTECTED = 6002;

  MAX_NOTEBOOK_SIZE_EXCEEDED = 6003;
}

// Serialization format for DatabricksServiceException.
message DatabricksServiceExceptionProto {
  optional ErrorCode error_code = 1;
  optional string message = 2;
  optional string stack_trace = 3;
}
