NxMesh-old-2/crates/nxmesh-proto/proto/agent.proto

syntax = "proto3";
package nxmesh.agent.v1;

option go_package = "github.com/nxmesh/api/agent/v1";

// For all file paths in this proto, we use forward slashes ("/") as the separator, even on Windows. This is because gRPC and protobuf are designed to be cross-platform and forward slashes are universally accepted as path separators in URLs and many programming languages. Using forward slashes ensures consistency and avoids issues with escaping backslashes on different platforms.
// All file paths MUST be relative paths from other config files, e.g. "site.conf", "private/example.com.conf". Absolute paths or path traversal above the config directory should be rejected by the agent for security reasons. The config files must live within the generated config directory, e.g. "/etc/nginx/conf-<timestamp>/site.conf". This allows the agent to manage the lifecycle of config files, e.g. cleanup old configs after successful apply.

// AgentService defines the bidirectional communication between master and agents
service AgentService {
  // Stream establishes a persistent connection for real-time communication
  rpc Stream(stream AgentMessage) returns (stream MasterMessage);

  // ReportHealth sends a health report to the master
  rpc ReportHealth(HealthReport) returns (Ack);

  // ReportMetrics sends metrics batch to the master
  rpc ReportMetrics(MetricsBatch) returns (Ack);
}

// Messages sent from agent to master
message AgentMessage {
  string agent_id = 1;
  int64 timestamp = 2;
  oneof payload {
    RegistrationRequest registration = 3;
    HealthReport health = 4;
    ConfigStatus config_status = 5;
    MetricsBatch metrics = 6;
    LogBatch logs = 7;
    Event event = 8;
  }
}

// Messages sent from master to agent
message MasterMessage {
  int64 timestamp = 1;
  oneof payload {
    RegistrationResponse registration_response = 2;
    ConfigUpdate config_update = 3;
    Command command = 4;
    Ack ack = 5;
    Error error = 6;
  }
}

// Registration
message RegistrationRequest {
  string hostname = 1;
  string ip_address = 2;
  string version = 3;
  repeated string capabilities = 4;
  map<string, string> labels = 5;
  DeploymentMode deployment_mode = 6;
}

message RegistrationResponse {
  string agent_id = 1;
  bool success = 2;
  string error_message = 3;
  int64 heartbeat_interval_seconds = 4;
}

enum DeploymentMode {
  DEPLOYMENT_MODE_UNSPECIFIED = 0;
  DOCKER_SIDECAR = 1;
  KUBERNETES_SIDECAR = 2;
  STANDALONE = 3;
}

// Health Reporting
message HealthReport {
  NginxStatus nginx = 1;
  SystemMetrics system = 2;
  string config_checksum = 3;
  int64 config_version = 4;
  repeated Alert alerts = 5;
}

message NginxStatus {
  bool is_running = 1;
  uint32 pid = 2;
  uint64 uptime_seconds = 3;
  uint32 active_connections = 4;
  uint64 total_requests = 5;
  float requests_per_second = 6;
}

message SystemMetrics {
  float cpu_percent = 1;
  uint64 memory_used_bytes = 2;
  uint64 memory_total_bytes = 3;
  uint64 disk_used_bytes = 4;
  uint64 disk_total_bytes = 5;
  float load_average_1m = 6;
}

message Alert {
  string id = 1;
  string severity = 2;  // info, warning, error, critical
  string message = 3;
  int64 timestamp = 4;
}

// Configuration
message ConfigUpdate {
  string config_id = 1;
  int64 version = 2;
  repeated ConfigContent configs = 3;
  repeated CertificateContent certificates = 4;
}

message ConfigContent {
  // relative path from other config files, e.g. "site.conf", "private/example.com.conf"
  string path = 1;
  string content = 2;
}

message CertificateContent {
  string id = 1;
  // relative path from other config files, e.g. "certs/example.com.pem"
  string path = 2;
  string certificate_pem = 3;
  string private_key_pem = 4;
}

message ConfigStatus {
  string config_id = 1;
  int64 version = 2;
  ConfigApplyStatus status = 3;
  string error_message = 4;
  int64 applied_at = 5;
}

enum ConfigApplyStatus {
  CONFIG_APPLY_STATUS_UNSPECIFIED = 0;
  PENDING = 1;
  VALIDATING = 2;
  APPLYING = 3;
  SUCCESS = 4;
  FAILED = 5;
  ROLLED_BACK = 6;
}

// Metrics
message MetricsBatch {
  int64 timestamp = 1;
  repeated Metric metrics = 2;
}

message Metric {
  string name = 1;
  double value = 2;
  int64 timestamp = 3;
  map<string, string> labels = 4;
  MetricType type = 5;
}

enum MetricType {
  METRIC_TYPE_UNSPECIFIED = 0;
  GAUGE = 1;
  COUNTER = 2;
  HISTOGRAM = 3;
}

// Logs
message LogBatch {
  repeated LogEntry entries = 1;
}

message LogEntry {
  int64 timestamp = 1;
  string level = 2;
  string message = 3;
  map<string, string> fields = 4;
}

// Commands
message Command {
  string command_id = 1;
  oneof command {
    ReloadCommand reload = 2;
    RestartCommand restart = 3;
    StopCommand stop = 4;
    GetStatusCommand get_status = 5;
    ValidateConfigCommand validate_config = 6;
  }
}

message ReloadCommand {
  bool graceful = 1;
}

message RestartCommand {
  bool force = 1;
}

message StopCommand {
  bool graceful = 1;
  uint32 timeout_seconds = 2;
}

message GetStatusCommand {}

message ValidateConfigCommand {
  string config_content = 1;
}

// Events
message Event {
  string event_id = 1;
  string event_type = 2;
  int64 timestamp = 3;
  map<string, string> data = 4;
}

// Common messages
message Ack {
  string message_id = 1;
  bool success = 2;
  string error_message = 3;
}

message Error {
  string code = 1;
  string message = 2;
  map<string, string> details = 3;
}