uncloud/internal/machine/api/pb/machine.proto

syntax = "proto3";

package api;

option go_package = "github.com/psviderski/uncloud/internal/machine/api/pb";

import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "internal/machine/api/pb/common.proto";

service Machine {
  // CheckPrerequisites verifies if the machine meets all necessary system requirements to participate in the cluster.
  rpc CheckPrerequisites(google.protobuf.Empty) returns (CheckPrerequisitesResponse);
  rpc InitCluster(InitClusterRequest) returns (InitClusterResponse);
  rpc JoinCluster(JoinClusterRequest) returns (google.protobuf.Empty);
  rpc Token(google.protobuf.Empty) returns (TokenResponse);
  // Deprecated: use InspectMachine instead.
  rpc Inspect(google.protobuf.Empty) returns (MachineInfo);
  // InspectMachine retrieves detailed information about the machine. Supports broadcasting to multiple machines.
  rpc InspectMachine(google.protobuf.Empty) returns (InspectMachineResponse);
  // UpdateMachine updates the configuration of the machine.
  rpc UpdateMachine(UpdateMachineRequest) returns (UpdateMachineResponse);
  // InspectWireGuardNetwork retrieves the current WireGuard network configuration and peer status.
  rpc InspectWireGuardNetwork(google.protobuf.Empty) returns (InspectWireGuardNetworkResponse);
  // Reset restores the machine to a clean state, removing all cluster-related configuration and data.
  rpc Reset(ResetRequest) returns (google.protobuf.Empty);

  rpc InspectService(InspectServiceRequest) returns (InspectServiceResponse);

  rpc MachineLogs(LogsRequest) returns (stream LogEntry);
}

message MachineInfo {
  string id = 1;
  string name = 2;
  NetworkConfig network = 3;
  IP public_ip = 4;
  // Operating system hostname of the machine.
  string hostname = 5;
}

message NetworkConfig {
  IPPrefix subnet = 1;
  IP management_ip = 2;
  repeated IPPort endpoints = 3;
  bytes public_key = 4;
}

message UpdateMachineRequest {
  // Updated machine information. Only the set fields are applied.
  optional string name = 1;
  optional IP public_ip = 2;
  repeated IPPort endpoints = 3;
}

message UpdateMachineResponse {
  MachineInfo machine = 1;
}

message CheckPrerequisitesResponse {
  // Overall status of the checks.
  bool satisfied = 1;
  // Error message if not satisfied (empty if all checks pass).
  string error = 2;
}

message InitClusterRequest {
  string machineName = 1;
  IPPrefix network = 2;

  oneof public_ip_config {
    IP public_ip = 3;
    bool public_ip_auto = 4;
  }

  // Optional WireGuard endpoints other machines will use to connect to this machine instead of auto-discovered ones.
  repeated IPPort wireguard_endpoints = 5;
  // WireGuard listen port for this machine. Uses the default port (51820) if 0 or not set.
  int32 wireguard_port = 6;
  // MTU of the WireGuard interface on this machine. The daemon auto-detects the optimal MTU if 0 or not set.
  int32 wireguard_mtu = 7;
}

message InitClusterResponse {
  MachineInfo machine = 1;
}

message JoinClusterRequest {
  MachineInfo machine = 1;
  repeated MachineInfo other_machines = 3;
  // WireGuard listen port for this machine. Uses the default port (51820) if 0 or not set.
  int32 wireguard_port = 5;
  // MTU of the WireGuard interface on this machine. The daemon auto-detects the optimal MTU if 0 or not set.
  int32 wireguard_mtu = 7;
  // Cluster store version this machine must reach before participating.
  // Per-actor vector (Corrosion actor UUID → max applied db_version).
  map<string, int64> min_store_version = 6;
}

message InspectMachineResponse {
  // Must contain only one repeated messages field to allow broadcasting InspectMachine requests to multiple machines.
  repeated MachineDetails machines = 1;
}

message MachineDetails {
  Metadata metadata = 1;
  MachineInfo machine = 2;
  // Round-trip times to other machines in the cluster, keyed by peer machine ID.
  map<string, RTTStats> rtts = 4;
  // Current cluster store version observed on this machine.
  // Per-actor vector (Corrosion actor UUID → max applied db_version) read from Corrosion crsql_db_versions.
  map<string, int64> store_version = 5;
}

message TokenResponse {
  string token = 1;
}

message ResetRequest {
}

message Service {
  string id = 1;
  string name = 2;
  string mode = 3;

  message Container {
    string machine_id = 1;
    // JSON encoded Docker types.Container.
    bytes container = 2;
  }

  repeated Container containers = 4;
}

message InspectServiceRequest {
  string id = 1;
}

message InspectServiceResponse {
  Service service = 1;
}

message InspectWireGuardNetworkResponse {
  string interface_name = 1;
  bytes public_key = 2;
  int32 listen_port = 3;
  repeated WireGuardPeer peers = 4;
}

message WireGuardPeer {
  bytes public_key = 1;
  string endpoint = 2;
  google.protobuf.Timestamp last_handshake_time = 3;
  int64 receive_bytes = 4;
  int64 transmit_bytes = 5;
  repeated string allowed_ips = 6;
}

message RTTStats {
  google.protobuf.Duration median = 1;
  google.protobuf.Duration std_dev = 2;
}