grafana/pkg/services/store/object/object.proto

syntax = "proto3";
package object;

option go_package = "./;object";

// Will be replaced with something from the SDK
message UserInfo {
  // internal grafana user ID
  int64 id = 1;

  // login name
  string login = 2; // string ID? 
}

// The canonical object/document data -- this represents the raw bytes and storage level metadata
message RawObject {
  // Unique ID
  string UID = 1;

  // Identify the object kind.  This kind will be used to apply a schema to the body and
  // will trigger additional indexing behavior.
  string kind = 2;

  // Time in epoch milliseconds that the object was created
  int64 created = 3;

  // Time in epoch milliseconds that the object was modified
  int64 modified = 4;

  // Who created the object
  UserInfo created_by = 5;

  // Who modified the object
  UserInfo modified_by = 6;

  // Content Length
  int64 size = 7;

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

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

  // The version will change when the object is saved. It is not necessarily sortable
  //
  // NOTE: currently managed by the dashboard+dashboard_version tables
  string version = 10;

  // Location (path/repo/etc) that defines the canonocal form
  //
  // NOTE: currently managed by the dashboard_provisioning table
  string sync_src = 11;

  // Time in epoch milliseconds that the object was last synced with an external system (provisioning/git)
  //
  // NOTE: currently managed by the dashboard_provisioning table
  int64 sync_time = 12;
}

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

  // Simple error display
  string message = 2;

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

// This is a subset of RawObject that does not include body or sync info
message ObjectVersionInfo {
  // The version will change when the object is saved. It is not necessarily sortable
  string version = 1;

  // Time in epoch milliseconds that the object was modified
  int64 modified = 2;

  // Who modified the object
  UserInfo modified_by = 3;

  // Content Length
  int64 size = 4;

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

  // optional "save" or "commit" message
  //
  // NOTE: currently managed by the dashboard_version table, and will be returned from a "history" command
  string comment = 6;
}

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

message ReadObjectRequest {
  // Unique ID (Kind is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string UID = 1;

  // Object kind (UID is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string kind = 2;

  // Fetch an explicit version
  string version = 3;

  // Include the full body bytes
  bool with_body = 4;

  // Include derived summary metadata
  bool with_summary = 5;
}

message ReadObjectResponse {
  // Object details with the body removed
  RawObject object = 1; 

  // Object summary as JSON
  bytes summary_json = 2;
}

//------------------------------------------------------
// Make many read requests at once (by Kind+ID+version)
//------------------------------------------------------

message BatchReadObjectRequest {
  repeated ReadObjectRequest batch = 3;
}

message BatchReadObjectResponse {
  repeated ReadObjectResponse results = 1;
}

//-----------------------------------------------
// Write request/response
//-----------------------------------------------

message WriteObjectRequest {
  // Unique ID (Kind is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string UID = 1;

  // Object kind (UID is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string kind = 2;

  // The raw object body
  bytes body = 3;

  // Message that can be seen when exploring object history
  string comment = 4;

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

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

  // Object details with the body removed
  ObjectVersionInfo object = 2; 

  // Object summary as JSON
  bytes summary_json = 3;

  // Status code
  Status status = 4;

  // Status enumeration
  enum Status {
    ERROR = 0;
    CREATED = 1;
    MODIFIED = 2;
    UNCHANGED = 3;
  }
}

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

message DeleteObjectRequest {
  // Unique ID (Kind is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string UID = 1;

  // Object kind (UID is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string kind = 2;

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

message DeleteObjectResponse {
  bool OK = 1;
}

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

message ObjectHistoryRequest {
  // Unique ID (Kind is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string UID = 1;

  // Object kind (UID is also required) NOTE: UID+kind will likely be replaced with GRN that encodes both
  string kind = 2;

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

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

message ObjectHistoryResponse {
  // Object metadata without the raw bytes
  repeated ObjectVersionInfo versions = 1;

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


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

message ObjectSearchRequest {
  // 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 kind (empty is all)
  repeated string kind = 4;

  // 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;

  // TODO, limit the set of fields we actually want returned
  // Only supported in the QueryResponse flavor?
  repeated string fields = 8;

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

message ObjectSearchResponse {
  repeated RawObject results = 1;

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


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

// This assumes a future grpc interface where the user info is passed in context, not in each message body
// for now it will only work with an admin API key
service ObjectStore {
  rpc Read(ReadObjectRequest) returns (ReadObjectResponse);
  rpc BatchRead(BatchReadObjectRequest) returns (BatchReadObjectResponse);
  rpc Write(WriteObjectRequest) returns (WriteObjectResponse);
  rpc Delete(DeleteObjectRequest) returns (DeleteObjectResponse);
  rpc History(ObjectHistoryRequest) returns (ObjectHistoryResponse);
  rpc Search(ObjectSearchRequest) returns (ObjectSearchResponse);

// Ideally an additional search endpoint with more flexibility to limit what you actually care about
//  https://github.com/grafana/grafana-plugin-sdk-go/blob/main/proto/backend.proto#L129
//  rpc SearchEX(ObjectSearchRequest) returns (DataResponse);
}