// SPDX-License-Identifier: Apache-2.0
// Tasks, events and alarms.
syntax = "proto3";

package kyvernon.v1;

import "kyvernon/v1/common.proto";

// Tasks: long-running operations with state, progress and result.
service TaskService {
  // One task by id.
  rpc GetTask(GetTaskRequest) returns (Task);
  // Tasks that match a filter.
  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
  // Asks a running or queued task to stop; returns the task.
  rpc CancelTask(CancelTaskRequest) returns (Task);
  // Blocks until the task is terminal or `timeout_seconds` elapses.
  rpc WaitTask(WaitTaskRequest) returns (Task);
}

// The event log of the inventory.
service EventService {
  // Events that match a filter.
  rpc QueryEvents(QueryEventsRequest) returns (QueryEventsResponse);
}

// Alarm states of inventory objects.
service AlarmService {
  // Alarm states.
  rpc ListAlarms(ListAlarmsRequest) returns (ListAlarmsResponse);
  // Acknowledges a triggered alarm on an object.
  rpc AcknowledgeAlarm(AcknowledgeAlarmRequest) returns (Empty);
}

// State of a task.
enum TaskState {
  TASK_STATE_QUEUED = 0;
  TASK_STATE_RUNNING = 1;
  TASK_STATE_SUCCESS = 2;
  TASK_STATE_ERROR = 3;
  TASK_STATE_CANCELLED = 4;
}

// A long-running operation.
message Task {
  // Id of the task.
  string id = 1;
  // Message id of what the task does (`task.virtual_machine.power_on`).
  string description_id = 2;
  // Id of the object the task works on.
  string entity = 3;
  // Name of that object when the task started.
  string entity_name = 4;
  // State of the task.
  TaskState state = 5;
  // Progress in percent, 0 to 100.
  uint32 progress = 6;
  // Result of a successful task as JSON; empty otherwise.
  string result_json = 7;
  // Error of a failed task.
  ErrorDetail error = 8;
  // User who started the task.
  string user = 9;
  // Id shared by the task and the events and tasks it caused.
  string chain_id = 10;
  // Time the task was queued, RFC 3339.
  string queued_at = 11;
  // Time the task started, RFC 3339; empty while queued.
  string started_at = 12;
  // Time the task ended, RFC 3339; empty while it runs.
  string completed_at = 13;
  // Attempt number, 1 for the first run.
  uint32 attempt = 14;
  // A cancellation was asked for and the task has not ended yet.
  bool cancel_requested = 15;
}

// Reads one task.
message GetTaskRequest {
  // Id of the task.
  string id = 1;
}

// Lists tasks.
message ListTasksRequest {
  // Only the tasks of this object.
  string entity = 1;
  // Only the tasks in these states.
  repeated TaskState states = 2;
  // Only the tasks of this user.
  string user = 3;
  // Only the tasks of this chain.
  string chain_id = 4;
  // Paging.
  PageRequest page = 5;
}

// A page of tasks.
message ListTasksResponse {
  // The tasks of the page.
  repeated Task items = 1;
  // Store version and cursor of the next page.
  PageInfo page = 2;
}

// Asks a task to stop.
message CancelTaskRequest {
  // Id of the task.
  string id = 1;
}

// Waits for a task to end.
message WaitTaskRequest {
  // Id of the task.
  string id = 1;
  // Longest wait in seconds; the answer is the task as it is then.
  uint32 timeout_seconds = 2;
}

// Severity of an event.
enum Severity {
  SEVERITY_INFO = 0;
  SEVERITY_WARNING = 1;
  SEVERITY_ERROR = 2;
  SEVERITY_USER = 3;
}

// One entry of the event log.
message Event {
  // Id of the event.
  string id = 1;
  // Event type (`VmPoweredOnEvent`).
  string event_type = 2;
  // Severity.
  Severity severity = 3;
  // Message id the console localises.
  string message_key = 4;
  // Arguments of the message id.
  map<string, string> message_args = 5;
  // Id of the object the event is about.
  string entity = 6;
  // Name of that object when the event happened.
  string entity_name = 7;
  // Ids of further objects involved.
  repeated string related = 8;
  // User whose action caused the event.
  string user = 9;
  // Id of the chain of tasks and events it belongs to.
  string chain_id = 10;
  // Id of the task that caused the event.
  string task = 11;
  // Time of the event, RFC 3339.
  string created_at = 12;
  // Further attributes of the event type.
  map<string, string> attributes = 13;
}

// Queries the event log.
message QueryEventsRequest {
  // Only the events of this object.
  string entity = 1;
  // Also the events of the objects under it.
  bool recursive = 2;
  // Only these event types.
  repeated string event_types = 3;
  // Only the events caused by this user.
  string user = 4;
  // Only the events of this chain.
  string chain_id = 5;
  // Earliest time, RFC 3339.
  string begin = 6;
  // Latest time, RFC 3339.
  string end = 7;
  // Collector cursor: only events with id number greater than this.
  uint64 after_id = 8;
  // Paging.
  PageRequest page = 9;
}

// A page of events.
message QueryEventsResponse {
  // The events of the page.
  repeated Event items = 1;
  // Store version and cursor of the next page.
  PageInfo page = 2;
}

// Status of an alarm on an object; gray means not evaluated.
enum AlarmStatus {
  ALARM_STATUS_GRAY = 0;
  ALARM_STATUS_GREEN = 1;
  ALARM_STATUS_YELLOW = 2;
  ALARM_STATUS_RED = 3;
}

// The status of an alarm on one object.
message AlarmState {
  // Id of the object.
  string entity = 1;
  // Status.
  AlarmStatus status = 2;
  // Time of the last status change, RFC 3339.
  string since = 3;
  // Someone acknowledged the triggered status.
  bool acknowledged = 4;
}

// An alarm definition with its states.
message Alarm {
  // Id of the alarm.
  string id = 1;
  // Name.
  string name = 2;
  // What the alarm watches.
  string description = 3;
  // Id of the object the alarm applies to and below.
  string scope = 4;
  // The alarm is evaluated.
  bool enabled = 5;
  // Trigger definition as JSON, the same shape as in the REST API.
  string trigger_json = 6;
  // Status on each object in scope.
  repeated AlarmState states = 7;
}

// Lists the alarms.
message ListAlarmsRequest {
  // Only alarms applicable to this entity (empty = all).
  string entity = 1;
}

// The alarms.
message ListAlarmsResponse {
  // Every alarm with its states.
  repeated Alarm items = 1;
}

// Acknowledges a triggered alarm.
message AcknowledgeAlarmRequest {
  // Id of the alarm.
  string alarm = 1;
  // Id of the object it triggered on.
  string entity = 2;
}