rvbox/protos/rvbox/v1/common.proto

syntax = "proto3";

package rvbox.v1;

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

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

// An inclusive protocol-version range advertised during registration.
message ProtocolRange {
  uint32 major = 1;
  uint32 min_minor = 2;
  uint32 max_minor = 3;
}

message ProtocolVersion {
  uint32 major = 1;
  uint32 minor = 2;
}

enum Platform {
  PLATFORM_UNSPECIFIED = 0;
  PLATFORM_LINUX = 1;
  PLATFORM_DARWIN = 2;
  PLATFORM_WINDOWS = 3;
  PLATFORM_OTHER_UNIX = 4;
}

enum ShellType {
  SHELL_TYPE_UNSPECIFIED = 0;
  SHELL_SH = 1;
  SHELL_BASH = 2;
  SHELL_CMD = 3;
  SHELL_POWERSHELL = 4;
}

// Effective Windows process token/session context selected by the client.
enum WindowsExecutionContext {
  WINDOWS_EXECUTION_CONTEXT_UNSPECIFIED = 0;
  WINDOWS_EXECUTION_CONTEXT_LOCAL_SERVICE = 1;
  WINDOWS_EXECUTION_CONTEXT_LOCAL_SYSTEM = 2;
  WINDOWS_EXECUTION_CONTEXT_ACTIVE_USER = 3;
  WINDOWS_EXECUTION_CONTEXT_ACTIVE_USER_ELEVATED = 4;
  WINDOWS_EXECUTION_CONTEXT_ACTIVE_SYSTEM = 5;
}

enum Compression {
  COMPRESSION_UNSPECIFIED = 0;
  COMPRESSION_NONE = 1;
  COMPRESSION_ZSTD = 2;
}

enum CommandLifecycle {
  COMMAND_LIFECYCLE_UNSPECIFIED = 0;
  COMMAND_QUEUED = 1;
  COMMAND_DISPATCHED = 2;
  COMMAND_ACCEPTED = 3;
  COMMAND_RUNNING = 4;
  COMMAND_SUCCEEDED = 5;
  COMMAND_FAILED = 6;
  COMMAND_TERMINATED = 7;
  COMMAND_CANCELLED = 8;
  COMMAND_INTERRUPTED = 9;
  COMMAND_EXPIRED = 10;
  COMMAND_REJECTED = 11;
}

enum StreamKind {
  STREAM_KIND_UNSPECIFIED = 0;
  STREAM_STDOUT = 1;
  STREAM_STDERR = 2;
}

enum SignalKind {
  SIGNAL_KIND_UNSPECIFIED = 0;
  SIGNAL_HUP = 1;
  SIGNAL_INT = 2;
  SIGNAL_TERM = 3;
  SIGNAL_KILL = 4;
  SIGNAL_USR1 = 5;
  SIGNAL_USR2 = 6;
}

// These flags are composable. Their numeric limits are local administrator
// policy rather than part of the interoperable protocol.
enum ExecutionProfile {
  EXECUTION_PROFILE_UNSPECIFIED = 0;
  EXECUTION_PROFILE_LIGHT = 1;
  EXECUTION_PROFILE_CPU_MEDIUM = 2;
  EXECUTION_PROFILE_CPU_HEAVY = 3;
  EXECUTION_PROFILE_MEM_MEDIUM = 4;
  EXECUTION_PROFILE_MEM_HEAVY = 5;
  EXECUTION_PROFILE_DISK_MEDIUM = 6;
  EXECUTION_PROFILE_DISK_HEAVY = 7;
}

message ScriptDescriptor {
  string filename = 1;
  uint64 size_bytes = 2;
  bytes sha256 = 3;
}

// Execution settings sent to the client. A script's bytes travel separately.
message ExecutionSpec {
  ShellType shell_type = 1;
  string cwd = 2;
  map<string, string> env_overrides = 3;
  repeated ExecutionProfile execution_profiles = 4;
  oneof source {
    string command_text = 5;
    ScriptDescriptor script = 6;
  }
  // Requests the platform's elevated execution policy. False is the normal
  // least-privilege policy. Non-Windows clients reject true in v1.
  bool elevated = 7;
}

// Effective Windows identity captured at launch. session_id and
// session_user_sid are absent for Session 0 contexts. effective_user_sid is
// the actual process-token user, not the owner of the target desktop session.
message WindowsExecutionIdentity {
  // Absent when every allowed context failed before launch preparation.
  optional WindowsExecutionContext effective_context = 1;
  optional uint32 session_id = 2;
  string session_user_sid = 3;
  string effective_user_sid = 4;
  // Ordered contexts considered during pre-launch selection, including the
  // effective final context. This is never a record of process retries.
  repeated WindowsExecutionContext attempted_contexts = 5;
  string selection_detail = 6;
}

message CommandRecord {
  string issue_uuid = 1;
  string target_client_id = 2;
  google.protobuf.Timestamp issue_time = 3;
  google.protobuf.Timestamp server_receipt_time = 4;
  ExecutionSpec spec = 5;
  CommandLifecycle lifecycle = 6;
  uint64 last_event_seq = 7;
  optional int32 exit_code = 8;
  google.protobuf.Timestamp terminal_time = 9;
  bool output_truncated = 10;
  uint64 retained_compressed_bytes = 11;
  google.protobuf.Timestamp queue_expiry_time = 12;
  bool output_incomplete = 13;
  // Present when lifecycle is COMMAND_REJECTED.
  ControlError rejection = 14;
  uint64 command_revision = 15;
  bool late_after_expiry = 16;
  // Present after Windows context selection was attempted, including a
  // pre-launch rejection for which effective_context is absent.
  WindowsExecutionIdentity windows_execution_identity = 17;
}

message LifecycleChange {
  CommandLifecycle lifecycle = 1;
  optional int32 exit_code = 2;
  string detail = 3;
  uint64 command_revision = 4;
  // Set on a Windows context-selection rejection or RUNNING, then repeated
  // unchanged on later lifecycle events.
  WindowsExecutionIdentity windows_execution_identity = 5;
}

// data is compressed according to compression. uncompressed_size is mandatory
// when compression is ZSTD and must be validated before decompression.
message OutputChunk {
  StreamKind stream = 1;
  Compression compression = 2;
  bytes data = 3;
  uint64 uncompressed_size = 4;
  uint64 compressed_size = 5;
}

message ResourceSnapshot {
  optional uint64 resident_memory_bytes = 1;
  optional uint64 virtual_memory_bytes = 2;
  google.protobuf.Duration cpu_time = 3;
  optional uint64 read_bytes = 4;
  optional uint64 write_bytes = 5;
  optional string process_state = 6;
  optional string wait_reason = 7;
  bool suspected_hung = 8;
  string diagnostic_detail = 9;
  optional string current_cwd = 10;
}

enum OutputTruncationSource {
  OUTPUT_TRUNCATION_SOURCE_UNSPECIFIED = 0;
  OUTPUT_TRUNCATION_SOURCE_CLIENT_SPOOL = 1;
  OUTPUT_TRUNCATION_SOURCE_SERVER_COMMAND_WINDOW = 2;
  OUTPUT_TRUNCATION_SOURCE_SERVER_CLIENT_CAP = 3;
  OUTPUT_TRUNCATION_SOURCE_CLIENT_OVERLOAD = 4;
  OUTPUT_TRUNCATION_SOURCE_SERVER_GLOBAL_CAP = 5;
}

// Metadata for missing output. Server-side retention supplies the optional
// event range. Client output discarded before wire sequence assignment omits
// the range and carries this as a normally sequenced CommandEvent.
message OutputTruncation {
  optional uint64 first_removed_event_seq = 1;
  optional uint64 last_removed_event_seq = 2;
  // Absent when bytes were discarded before compression.
  optional uint64 removed_compressed_bytes = 3;
  uint64 removed_uncompressed_bytes = 4;
  string reason = 5;
  OutputTruncationSource source = 6;
}

// Indicates that capture ended without a provably complete byte stream. It is
// sequenced before the terminal lifecycle event but does not claim an invented
// event or byte range.
message OutputIncomplete {
  repeated StreamKind streams = 1;
  string reason = 2;
}

message StdinAcknowledgement {
  uint64 write_seq = 1;
  bool stdin_closed = 2;
  string detail = 3;
}

message SignalResult {
  SignalKind signal = 1;
  bool accepted = 2;
  bool graceful_delivery_attempted = 3;
  bool forced_termination_used = 4;
  string detail = 5;
  uint64 command_revision = 6;
}

message ScriptUploadStatus {
  uint64 received_bytes = 1;
  bool complete = 2;
  string detail = 3;
}

// Client-originated ordered history. event_seq is strictly increasing per
// issue_uuid and is reused exactly on retransmission.
message CommandEvent {
  string issue_uuid = 1;
  uint64 event_seq = 2;
  google.protobuf.Timestamp observed_at = 3;
  oneof payload {
    LifecycleChange lifecycle = 4;
    OutputChunk output = 5;
    ResourceSnapshot resource = 6;
    StdinAcknowledgement stdin_ack = 7;
    SignalResult signal_result = 8;
    ScriptUploadStatus script_status = 9;
    OutputTruncation output_truncation = 10;
    OutputIncomplete output_incomplete = 11;
  }
  // SHA-256 of this event with this field cleared. It makes retransmission
  // conflicts detectable without trusting a reused event_seq.
  bytes immutable_event_sha256 = 12;
}

message ControlError {
  enum Code {
    CODE_UNSPECIFIED = 0;
    INVALID_ARGUMENT = 1;
    NOT_FOUND = 2;
    OFFLINE = 3;
    CAPACITY_EXHAUSTED = 4;
    CONFLICT = 5;
    UNSUPPORTED = 6;
    PROTOCOL_ERROR = 7;
    TRANSIENT = 8;
    INTERNAL = 9;
    CODE_ALREADY_EXECUTED = 10;
    CODE_EXECUTION_CONTEXT_UNAVAILABLE = 11;
    CODE_ELEVATION_UNAVAILABLE = 12;
  }
  Code code = 1;
  string message = 2;
  bool retryable = 3;
  string issue_uuid = 4;
}