NxMesh/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;
  // The root config is the main nginx.conf file, this file will be used as the entry point for nginx configuration. The content of this file should include references to other config files if needed. The agent will write this root config to the nginx config directory and use it to reload nginx.
  ConfigContent root_config = 3;
  // The other config files that are referenced by the root config, e.g. "site.conf", "private/example.com.conf". If the root config does not reference any other config files, this field can be left empty. The agent will write these config files to the nginx config directory and ensure they are included in the root config.
  repeated ConfigContent configs = 4;
  repeated CertificateContent certificates = 5;
}

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;
}