rvbox/protos/rvbox/v1/control.proto

syntax = "proto3";

package rvbox.v1;

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "rvbox/v1/common.proto";

option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";

service Control {
  rpc ListClients(ListClientsRequest) returns (ListClientsResponse);
  rpc GetClient(GetClientRequest) returns (GetClientResponse);
  rpc ListCommands(ListCommandsRequest) returns (ListCommandsResponse);
  rpc GetCommand(GetCommandRequest) returns (GetCommandResponse);
  rpc RunCommand(RunCommandRequest) returns (RunCommandResponse);
  rpc FollowCommand(FollowCommandRequest) returns (stream FollowCommandResponse);
  rpc AppendStdin(AppendStdinRequest) returns (AppendStdinResponse);
  rpc CloseStdin(CloseStdinRequest) returns (CloseStdinResponse);
  rpc SignalCommand(ControlSignalCommandRequest) returns (ControlSignalCommandResponse);
  rpc GetOutput(GetOutputRequest) returns (GetOutputResponse);
  rpc ListStorageIncidents(ListStorageIncidentsRequest) returns (ListStorageIncidentsResponse);
  rpc RepairStorageIncident(RepairStorageIncidentRequest) returns (RepairStorageIncidentResponse);
  rpc AcknowledgeStorageIncident(AcknowledgeStorageIncidentRequest) returns (AcknowledgeStorageIncidentResponse);
  rpc AuthorizeClientTakeover(AuthorizeClientTakeoverRequest) returns (AuthorizeClientTakeoverResponse);
}

message ClientSummary {
  string client_id = 1;
  bool connected = 2;
  google.protobuf.Timestamp connected_at = 3;
  google.protobuf.Timestamp last_seen_at = 4;
  uint32 running_commands = 5;
  uint32 queued_commands = 6;
  Platform platform = 7;
  string architecture = 8;
  string daemon_version = 9;
  // Omitted-CWD default on Unix; protected per-identity work root on Windows.
  string daemon_cwd = 10;
  repeated ShellType supported_shells = 11;
  string client_instance_id = 12;
  // Most recently rejected different instance while this client is live.
  string pending_instance_id = 13;
  google.protobuf.Timestamp pending_instance_seen_at = 14;
}

message ListClientsRequest {
  uint32 page_size = 1;
  string page_token = 2;
}

message ListClientsResponse {
  repeated ClientSummary clients = 1;
  string next_page_token = 2;
}

message GetClientRequest {
  string client_id = 1;
}

message GetClientResponse {
  ClientSummary client = 1;
}

message ListCommandsRequest {
  string client_id = 1;
  bool include_terminal = 2;
  uint32 page_size = 3;
  string page_token = 4;
}

message ListCommandsResponse {
  repeated CommandRecord commands = 1;
  string next_page_token = 2;
}

message GetCommandRequest {
  string client_id = 1;
  string issue_uuid = 2;
}

message GetCommandResponse {
  CommandRecord command = 1;
  ResourceSnapshot latest_resource = 2;
}

// For script execution, script_content contains the bytes whose descriptor is
// placed in spec.script. The server chunks it for the Agent protocol.
message RunCommandRequest {
  string target_client_id = 1;
  ExecutionSpec spec = 2;
  bytes script_content = 3;
  // Becomes issue_uuid when supplied; generated by the server when omitted.
  string request_id = 4;
  // Omitted uses the server default; zero explicitly requests no expiry.
  google.protobuf.Duration queue_ttl = 5;
}

message RunCommandResponse {
  string issue_uuid = 1;
  CommandLifecycle lifecycle = 2;
}

message FollowCommandRequest {
  string client_id = 1;
  string issue_uuid = 2;
  uint64 after_event_seq = 3;
  bool include_existing = 4;
}

message FollowCommandResponse {
  oneof item {
    CommandEvent event = 1;
    // Server retention metadata; does not advance the client event cursor.
    RetentionTruncation retention_truncation = 2;
  }
  // Set for a client event; server-created retention uses its own recorded_at.
  google.protobuf.Timestamp server_receipt_time = 3;
}

message AppendStdinRequest {
  string client_id = 1;
  string issue_uuid = 2;
  bytes data = 3;
  bool append_newline = 4;
  string request_id = 5;
}

message AppendStdinResponse {
  uint64 write_seq = 1;
}

message CloseStdinRequest {
  string client_id = 1;
  string issue_uuid = 2;
  string request_id = 3;
}

message CloseStdinResponse {
  uint64 write_seq = 1;
}

message ControlSignalCommandRequest {
  string client_id = 1;
  string issue_uuid = 2;
  SignalKind signal = 3;
  string request_id = 4;
}

message ControlSignalCommandResponse {
  uint64 command_revision = 1;
}

message GetOutputRequest {
  string client_id = 1;
  string issue_uuid = 2;
  repeated StreamKind streams = 3;
  uint64 after_event_seq = 4;
  uint64 max_bytes = 5;
  string page_token = 6;
}

// An uncompressed slice of one persisted output event. Opaque pagination may
// resume within an event; event_byte_offset identifies that position.
message OutputSlice {
  uint64 event_seq = 1;
  google.protobuf.Timestamp observed_at = 2;
  StreamKind stream = 3;
  bytes data = 4;
  uint64 event_byte_offset = 5;
  bool end_of_event = 6;
  google.protobuf.Timestamp server_receipt_time = 7;
}

message RetentionTruncation {
  OutputTruncation truncation = 1;
  google.protobuf.Timestamp server_recorded_at = 2;
}

message GetOutputResponse {
  repeated OutputSlice output = 1;
  string next_page_token = 2;
  bool output_truncated = 3;
  repeated RetentionTruncation truncations = 4;
  OutputIncomplete incomplete = 5;
}

enum StorageIncidentState {
  STORAGE_INCIDENT_STATE_UNSPECIFIED = 0;
  STORAGE_INCIDENT_STATE_OPEN = 1;
  STORAGE_INCIDENT_STATE_REPAIRED = 2;
  STORAGE_INCIDENT_STATE_ACKNOWLEDGED = 3;
}

message StorageIncident {
  string incident_id = 1;
  google.protobuf.Timestamp detected_at = 2;
  google.protobuf.Timestamp resolved_at = 3;
  StorageIncidentState state = 4;
  string scope = 5;
  string client_id = 6;
  string issue_uuid = 7;
  string summary = 8;
  bool data_loss = 9;
  bool automatically_repairable = 10;
}

message ListStorageIncidentsRequest {
  bool include_resolved = 1;
  uint32 page_size = 2;
  string page_token = 3;
}

message ListStorageIncidentsResponse {
  repeated StorageIncident incidents = 1;
  string next_page_token = 2;
}

message RepairStorageIncidentRequest {
  string incident_id = 1;
  string request_id = 2;
}

message RepairStorageIncidentResponse {
  StorageIncident incident = 1;
}

message AcknowledgeStorageIncidentRequest {
  string incident_id = 1;
  string note = 2;
  string request_id = 3;
}

message AcknowledgeStorageIncidentResponse {
  StorageIncident incident = 1;
}

message AuthorizeClientTakeoverRequest {
  string client_id = 1;
  string client_instance_id = 2;
  string request_id = 3;
}

message AuthorizeClientTakeoverResponse {
  google.protobuf.Timestamp expires_at = 1;
}