vpp-maglev/proto/maglev.proto

syntax = "proto3";

package maglev;

option go_package = "git.ipng.ch/ipng/vpp-maglev/internal/grpcapi";

// Maglev exposes the state of backend health for all frontends.
service Maglev {
  rpc ListFrontends(ListFrontendsRequest) returns (ListFrontendsResponse);
  rpc GetFrontend(GetFrontendRequest) returns (FrontendInfo);
  rpc ListBackends(ListBackendsRequest) returns (ListBackendsResponse);
  rpc GetBackend(GetBackendRequest) returns (BackendInfo);
  rpc PauseBackend(BackendRequest) returns (BackendInfo);
  rpc ResumeBackend(BackendRequest) returns (BackendInfo);
  rpc EnableBackend(BackendRequest) returns (BackendInfo);
  rpc DisableBackend(BackendRequest) returns (BackendInfo);
  rpc ListHealthChecks(ListHealthChecksRequest) returns (ListHealthChecksResponse);
  rpc GetHealthCheck(GetHealthCheckRequest) returns (HealthCheckInfo);
  rpc SetFrontendPoolBackendWeight(SetWeightRequest) returns (FrontendInfo);
  rpc WatchEvents(WatchRequest) returns (stream Event);
  rpc CheckConfig(CheckConfigRequest) returns (CheckConfigResponse);
  rpc ReloadConfig(ReloadConfigRequest) returns (ReloadConfigResponse);
}

// ---- requests ---------------------------------------------------------------

message ListFrontendsRequest {}

message GetFrontendRequest {
  string name = 1;
}

message ListBackendsRequest {}

message GetBackendRequest {
  string name = 1;
}

message BackendRequest {
  string name = 1;
}

message ListHealthChecksRequest {}

message GetHealthCheckRequest {
  string name = 1;
}

message CheckConfigRequest {}

message CheckConfigResponse {
  bool ok = 1;
  string parse_error = 2;    // set when YAML cannot be read or parsed
  string semantic_error = 3; // set when YAML is valid but semantically incorrect
}

message ReloadConfigRequest {}

message ReloadConfigResponse {
  bool ok = 1;
  string parse_error = 2;    // set when YAML cannot be read or parsed
  string semantic_error = 3; // set when YAML is valid but semantically incorrect
  string reload_error = 4;   // set when config is valid but the reload itself failed
}

message SetWeightRequest {
  string frontend = 1;
  string pool = 2;
  string backend = 3;
  int32 weight = 4; // 0-100
}

// WatchRequest controls which event types are streamed. All fields default to
// true (i.e. an empty request subscribes to everything at info level).
message WatchRequest {
  optional bool log = 1;       // include log events (default: true)
  string log_level = 2;        // minimum log level: debug|info|warn|error (default: info)
  optional bool backend = 3;   // include backend transition events (default: true)
  optional bool frontend = 4;  // include frontend events (default: true)
}

// ---- responses --------------------------------------------------------------

message ListFrontendsResponse {
  repeated string frontend_names = 1;
}

message PoolBackendInfo {
  string name = 1;
  int32 weight = 2;
}

message PoolInfo {
  string name = 1;
  repeated PoolBackendInfo backends = 2;
}

message FrontendInfo {
  string name = 1;
  string address = 2;
  string protocol = 3;
  uint32 port = 4;
  repeated PoolInfo pools = 5;
  string description = 6;
}

message ListBackendsResponse {
  repeated string backend_names = 1;
}

message ListHealthChecksResponse {
  repeated string names = 1;
}

message HTTPCheckParams {
  string path = 1;
  string host = 2;
  int32 response_code_min = 3;
  int32 response_code_max = 4;
  string response_regexp = 5;
  string server_name = 6;
  bool insecure_skip_verify = 7;
}

message TCPCheckParams {
  bool ssl = 1;
  string server_name = 2;
  bool insecure_skip_verify = 3;
}

message HealthCheckInfo {
  string name = 1;
  string type = 2;
  uint32 port = 3;
  string probe_ipv4_src = 4;
  string probe_ipv6_src = 5;
  int64 interval_ns = 6;
  int64 fast_interval_ns = 7;
  int64 down_interval_ns = 8;
  int64 timeout_ns = 9;
  int32 rise = 10;
  int32 fall = 11;
  HTTPCheckParams http = 12;
  TCPCheckParams tcp = 13;
}

message BackendInfo {
  string name = 1;
  string address = 2;
  string state = 3;
  repeated TransitionRecord transitions = 4;
  bool enabled = 5;
  string healthcheck = 6;
}

message TransitionRecord {
  string from = 1;
  string to = 2;
  int64 at_unix_ns = 3;
}

// ---- event stream -----------------------------------------------------------

// LogAttr is a single key/value attribute from a structured log record.
message LogAttr {
  string key = 1;
  string value = 2;
}

// LogEvent carries a single structured log record.
message LogEvent {
  int64 at_unix_ns = 1;
  string level = 2;
  string msg = 3;
  repeated LogAttr attrs = 4;
}

// BackendEvent is emitted on every backend state transition.
message BackendEvent {
  string backend_name = 1;
  TransitionRecord transition = 2;
}

// FrontendEvent is reserved for future frontend-level events.
message FrontendEvent {}

// Event is the envelope returned by WatchEvents.
message Event {
  oneof event {
    LogEvent log = 1;
    BackendEvent backend = 2;
    FrontendEvent frontend = 3;
  }
}