grafana/pkg/services/store/entity/entity.proto

syntax = "proto3";
package entity;

option go_package = "github.com/grafana/grafana/pkg/services/store/entity";

// The canonical entity/document data -- this represents the raw bytes and storage level metadata
message Entity {
  // Globally unique ID set by the system.  This can not be set explicitly
  string guid = 1;

  // The resource version, this is a snowflake id controlled by storage
  int64 resource_version = 2;

  // group
  string group = 24;
  // kind resource
  string resource = 25;
  // namespace
  string namespace = 26;
  // k8s name
  string name = 27;
  // subresource
  string subresource = 28;

  // group version
  string group_version = 23;

  // k8s key value (TODO remove -- it is duplicate of group+resource+version)
  string key = 22;

  // The folder k8s name
  string folder = 4;

  // Raw meta from k8s
  bytes meta = 5;

  // Raw bytes of the storage entity.  The kind will determine what is a valid payload
  bytes body = 6;

  // k8s style status (ignored for now)
  bytes status = 7;

  // the friendly name of the entity
  string title = 8;

  // Content Length
  int64 size = 9;

  // MD5 digest of the body
  string ETag = 10;

  // Time in epoch milliseconds that the entity was created
  int64 created_at = 11;

  // Who created the entity
  string created_by = 12;

  // Time in epoch milliseconds that the entity was updated
  int64 updated_at = 13;

  // Who updated the entity
  string updated_by = 14;

  // External location info
  EntityOriginInfo origin = 15;

  // human-readable description of the entity
  string description = 16;

  // URL safe version of the name.  It will be unique within the folder
  string slug = 17;

  // Commit message (optional)
  string message = 18;

  // Key value pairs.  Tags are are represented as keys with empty values
  map<string,string> labels = 19;

  // Optional field values.  The schema will define and document possible values for a given kind
  map<string, string> fields = 20;

  // When errors exist
  repeated EntityErrorInfo errors = 21;

  // Action code
  Action action = 3;

  // Status enumeration
  enum Action {
    UNKNOWN = 0;
    CREATED = 1;
    UPDATED = 2;
    DELETED = 3;
    ERROR = 4;
    BOOKMARK = 5;
  }
}

// This stores additional metadata for items entities that were synced from external systmes
message EntityOriginInfo {
  // identify the external source (plugin, git instance, etc)
  string source = 1;

  // Key in the upstream system (git hash, file path, etc)
  string key = 2;

  // Time in epoch milliseconds that the entity was last synced with an external system (provisioning/git)
  int64 time = 3;
}

// Report error while working with entitys
// NOTE: real systems at scale will contain errors.
message EntityErrorInfo {
  // Match an error code registry?
  int64 code = 1;

  // Simple error display
  string message = 2;

  // Details encoded in JSON
  bytes details_json = 3;
}

//-----------------------------------------------
// Get request/response
//-----------------------------------------------

message ReadEntityRequest {
  // Entity identifier
  string key = 1;

  // Fetch an explicit version (default is latest)
  int64 resource_version = 2;

  // Include the full body
  bool with_body = 4;

  // Include the status
  bool with_status = 5;
}

//-----------------------------------------------
// Create request/response
//-----------------------------------------------

message CreateEntityRequest {
  // Entity details
  Entity entity = 1;
}

message CreateEntityResponse {
  // Error info -- if exists, the save did not happen
  EntityErrorInfo error = 1;

  // Entity details
  Entity entity = 2;

  // Status code
  Status status = 3;

  // Status enumeration
  enum Status {
    ERROR = 0;
    CREATED = 1;
  }
}

//-----------------------------------------------
// Update request/response
//-----------------------------------------------

message UpdateEntityRequest {
  // Entity details
  Entity entity = 1;

  // Used for optimistic locking.  If missing, the previous version will be replaced regardless
  int64 previous_version = 2;
}

message UpdateEntityResponse {
  // Error info -- if exists, the save did not happen
  EntityErrorInfo error = 1;

  // Entity details
  Entity entity = 2;

  // Status code
  Status status = 3;

  // Status enumeration
  enum Status {
    ERROR = 0;
    UPDATED = 1;
    UNCHANGED = 2;
  }
}

//-----------------------------------------------
// Delete request/response
//-----------------------------------------------

message DeleteEntityRequest {
  // Entity identifier
  string key = 1;

  // Used for optimistic locking.  If missing, the current version will be deleted regardless
  int64 previous_version = 2;
}

message DeleteEntityResponse {
  // Error info -- if exists, the delete did not happen
  EntityErrorInfo error = 1;

  // Entity details
  Entity entity = 2;

  // Status code
  Status status = 3;

  // Status enumeration
  enum Status {
    ERROR = 0;
    DELETED = 1;
    NOTFOUND = 2;
  }
}

//-----------------------------------------------
// History request/response
//-----------------------------------------------

message EntityHistoryRequest {
  // Entity identifier
  string key = 1;

  // return the history from before this version
  int64 before = 2;

  // Maximum number of items to return
  int64 limit = 3;

  // guid of the entity
  string guid = 4;

  // Starting from the requested page
  string next_page_token = 5;

  // Sorting instructions `field ASC/DESC`
  repeated string sort = 7;

  // Return the full body in each payload
  bool with_body = 8;

  // Return the status in each payload
  bool with_status = 10;
}

message EntityHistoryResponse {
  // Entity identifier
  string key = 1;

  // Entity metadata without the raw bytes
  repeated Entity versions = 2;

  // More results exist... pass this in the next request
  string next_page_token = 3;

  // Resource version of the response
  int64 resource_version = 4;
}


//-----------------------------------------------
// List request/response
//-----------------------------------------------

message EntityListRequest {
  // Starting from the requested page (other query parameters must match!)
  string next_page_token = 1;

  // Maximum number of items to return
  int64 limit = 2;

  // Free text query string -- mileage may vary :)
  string query = 3;

  // limit to a specific group (empty is all)
  repeated string group = 9;

  // limit to a specific resource (empty is all)
  repeated string resource = 4;

  // limit to a specific key
  repeated string key = 11;

  // Limit results to items in a specific folder
  string folder = 5;

  // Must match all labels
  map<string,string> labels = 6;

  // Sorting instructions `field ASC/DESC`
  repeated string sort = 7;

  // Return the full body in each payload
  bool with_body = 8;

  // Return the full body in each payload
  bool with_status = 10;

  // list deleted entities instead of active ones
  bool deleted = 12;

  // Limit to a set of origin keys (empty is all)
  repeated string origin_keys = 13;
}

message ReferenceRequest {
  // Starting from the requested page (other query parameters must match!)
  string next_page_token = 1;

  // Maximum number of items to return
  int64 limit = 2;

  // Free text query string -- mileage may vary :)
  string namespace = 5;

  string group = 6;

  string resource = 3;

  // Free text query string -- mileage may vary :)
  string name = 4;
}

message EntityListResponse {
  repeated Entity results = 1;

  // More results exist... pass this in the next request
  string next_page_token = 2;

  // ResourceVersion of the list response
  int64 resource_version = 3;
}

//-----------------------------------------------
// Watch request/response
//-----------------------------------------------

message EntityWatchRequest {
  enum WatchAction {
    START = 0;
    STOP = 1;
  }

  // Start or stop the watch
  WatchAction action = 8;

  // ResourceVersion of last changes. Empty will default to full history
  int64 since = 1;

  // Watch specific entities
  repeated string key = 2;

  // limit to a specific resource (empty is all)
  repeated string resource = 3;

  // Limit results to items in a specific folder
  string folder = 4;

  // Must match all labels
  map<string,string> labels = 5;

  // Return the full body in each payload
  bool with_body = 6;

  // Return the full status in each payload
  bool with_status = 7;

  // Return initial events
  bool send_initial_events = 9;

  bool allow_watch_bookmarks = 10;
}

message EntityWatchResponse {
  // Timestamp the event was sent
  int64 timestamp = 1;

  // Entity that was created, updated, or deleted
  Entity entity = 2;

  // previous version of the entity
  Entity previous = 3;
}

message EntitySummary {
  string UID = 1;
  string kind = 2;

  string name = 3;
  string description = 4;

  // Key value pairs.  Tags are are represented as keys with empty values
  map<string,string> labels = 5;

  // Parent folder UID
  string folder = 6;

  // URL safe version of the name.  It will be unique within the folder
  string slug = 7;

  // When errors exist
  EntityErrorInfo error = 8;

  // Optional field values.  The schema will define and document possible values for a given kind
  map<string, string> fields = 9;

  // eg: panels within dashboard
  repeated EntitySummary nested = 10;

  // Optional references to external things
  repeated EntityExternalReference references = 11;
}

message EntityExternalReference {
  // Category of dependency
  // eg: datasource, plugin, runtime
  string family = 1;

  // datasource > prometheus|influx|...
  // plugin > panel | datasource
  // runtime > transformer
  string type = 2;

  // datasource > UID
  // plugin > plugin identifier
  // runtime > name lookup
  string identifier = 3;
}

//-----------------------------------------------
// Health
//-----------------------------------------------

message HealthCheckRequest {
  string service = 1;
}

message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
    SERVICE_UNKNOWN = 3;  // Used only by the Watch method.
  }
  ServingStatus status = 1;
}

//-----------------------------------------------
// Storage interface
//-----------------------------------------------

// The entity store provides a basic CRUD (+watch eventually) interface for generic entities
service EntityStore {
  rpc Read(ReadEntityRequest) returns (Entity);
  rpc Create(CreateEntityRequest) returns (CreateEntityResponse);
  rpc Update(UpdateEntityRequest) returns (UpdateEntityResponse);
  rpc Delete(DeleteEntityRequest) returns (DeleteEntityResponse);
  rpc History(EntityHistoryRequest) returns (EntityHistoryResponse);
  rpc List(EntityListRequest) returns (EntityListResponse);
  rpc Watch(stream EntityWatchRequest) returns (stream EntityWatchResponse);
  rpc IsHealthy(HealthCheckRequest) returns (HealthCheckResponse);
}