ziti/common/pb/ctrl_pb/ctrl.proto

syntax = "proto3";

package ziti.ctrl.pb;
option go_package = "github.com/openziti/fabric/pb/ctrl_pb";

// ContentTypes should be in the range 1000 - 1999, to ensure they don't overlap with cmd_pb messages
enum ContentType {
  Zero = 0;

  CircuitRequestType = 1000;
  // defined in ctrl_msg/messages.go now
  // CircuitSuccessType = 1001;

  // Deprecated now that links are router managed, keeping here for historical and debug purposes
  // DialType = 1002;
  // LinkConnectedType = 1003;

  FaultType = 1004;
  RouteType = 1005;
  UnrouteType = 1006;
  MetricsType = 1007;
  TogglePipeTracesRequestType = 1008;
  TraceEventType = 1010;
  CreateTerminatorRequestType = 1011;
  RemoveTerminatorRequestType = 1012;
  InspectRequestType = 1013;
  InspectResponseType = 1014;
  // defined in ctrl_msg/messages.go now
  // CircuitFailedType = 1016;
  ValidateTerminatorsRequestType = 1017;
  UpdateTerminatorRequestType = 1018;
  // VerifyLinkType = 1019; Unusable since links are now generated by routers
  SettingsType = 1020;
  CircuitConfirmationType = 1034;
  RouterLinksType = 1035;
  VerifyRouterType = 1036;
  UpdateCtrlAddressesType = 1037;

  RemoveTerminatorsRequestType = 1038;
  QuiesceRouterRequestType = 1039;
  DequiesceRouterRequestType = 1040;
  ValidateTerminatorsV2RequestType = 1041;
  ValidateTerminatorsV2ResponseType = 1042;
  DecommissionRouterRequestType = 1043;

  PeerStateChangeRequestType = 1050;
  UpdateClusterLeaderRequestType = 1051;

  UpdateRouterInterfaces = 1052;
  LinkState = 1053;

  AlertsType = 1054;
  RequestClusterMembers = 1055;
  UpdateLinkListenersType = 1056;
  CheckStaleLinksRequestType = 1057;
  CheckStaleLinksResponseType = 1058;

  RemoveTerminatorsV2RequestType = 1059;
  RemoveTerminatorsV2ResponseType = 1060;
}

enum ControlHeaders {
  NoneHeader = 0;
  ListenersHeader = 1000;
  RouterMetadataHeader = 1001;
  CapabilitiesHeader = 1002;
  CtrlChanListenersHeader = 1003;
}

enum RouterCapability {
  CapabilityZero = 0;
  LinkManagement = 1;
}

// SettingTypes are used with the Settings message send arbitrary settings to routers.
// SettingTypes default to int32 which can be used seamlessly for keys in the Settings.data field
enum SettingTypes {
  //unused, consume to avoid zero value accidents
  UnusedSetting = 0;
  //Sent to routers to notify them of a controller IP/hostname move
  NewCtrlAddress = 1;
}

// Settings are sent to to routers to configure arbitrary runtime settings.
message Settings {
  map<int32, bytes> data = 1;
}

message CircuitRequest {
  string ingressId = 1;
  string service = 2;
  map<uint32, bytes> peerData = 3;
}

message CircuitConfirmation {
  repeated string circuitIds = 1;
  map<string, int64> idleTimes = 2;
}

enum TerminatorPrecedence {
  Default = 0;
  Required = 1;
  Failed = 2;
}

message CreateTerminatorRequest {
  string serviceId = 2;
  string binding = 3;
  string address = 4;
  map<uint32, bytes> peerData = 5;
  uint32 cost = 6;
  TerminatorPrecedence precedence = 7;
  string instanceId = 8;
  bytes instanceSecret = 9;
}

message RemoveTerminatorRequest {
  string terminatorId = 1;
}

message RemoveTerminatorsRequest {
  repeated string terminatorIds = 1;
}

// RemoveTerminatorsV2Request asks the controller to remove a batch of terminators. Unlike
// RemoveTerminatorsRequest, it is answered asynchronously with a RemoveTerminatorsV2Response
// rather than a synchronous result, so the router does not block a request slot waiting for the
// reply. requestId correlates the response back to the sending batch.
message RemoveTerminatorsV2Request {
  repeated string terminatorIds = 1;
  string requestId = 2;
  // createConfirmed is index-aligned with terminatorIds: entry i is true when the router received
  // the create acknowledgement for terminatorIds[i], meaning its create is committed. The controller
  // uses this to safely skip (as a confirmed no-op) a delete for a terminator it no longer has;
  // absent or false entries force the normal ordered delete, since an unconfirmed create may be
  // committed but not yet applied. Older routers omit it, which decodes as empty (all false).
  repeated bool createConfirmed = 3;
}

// RemoveTerminatorsV2Response reports the outcome of a RemoveTerminatorsV2Request. requestId echoes
// the request's id so the router can match it to the originating batch. wasRateLimited is set when
// the removal was rejected because the controller was too busy, so the router should back off and
// retry rather than treat it as a hard failure.
message RemoveTerminatorsV2Response {
  string requestId = 1;
  bool success = 2;
  bool wasRateLimited = 3;
  string msg = 4;
}

message Terminator {
  string id = 1;
  string binding = 2;
  string address = 3;
  uint64 marker = 4;
}

message ValidateTerminatorsRequest {
  repeated Terminator terminators = 1;
}

message ValidateTerminatorsV2Request {
  repeated Terminator terminators = 1;
  bool fixInvalid = 2;
  bool postCreate = 3;
}

enum TerminatorInvalidReason {
  UnknownBinding = 0;
  UnknownTerminator = 1;
  BadState = 2;
}

message RouterTerminatorState {
  bool valid = 1;
  TerminatorInvalidReason reason = 2;
  string detail = 3; // inspect info if valid
  uint64 marker = 4;
}

message ValidateTerminatorsV2Response {
  map<string, RouterTerminatorState> states = 1;
}

message UpdateTerminatorRequest {
  string terminatorId = 1;
  bool updatePrecedence = 2;
  bool updateCost = 3;
  TerminatorPrecedence precedence = 4;
  uint32 cost = 5;
}

message LinkConn {
  string type = 1;
  string localAddr = 2;
  string remoteAddr = 3;
}

message LinkConnState {
  uint32 stateIteration = 1;
  repeated LinkConn conns = 2;
}

message RouterLinks {
  message RouterLink {
    string id = 1;
    string destRouterId = 2;
    string linkProtocol = 3;
    reserved 4; // formerly linkCostTags, removed as unused
    reserved "linkCostTags";
    string dialAddress = 5;
    uint32 iteration = 6;
    LinkConnState connState = 7;
  }

  repeated RouterLink links = 1;
  bool fullRefresh = 2;
}

enum FaultSubject {
  IngressFault = 0;
  EgressFault = 1;
  LinkFault = 2;
  ForwardFault = 3;
  UnknownOwnerForwardFault = 4;
  LinkDuplicate = 5;
}

message Fault {
  FaultSubject subject = 1;
  string id = 2;
  uint32 iteration = 3;
}

message Context {
  map<string, string> fields = 1;
  uint32 channelMask = 2;
}

enum DestType {
  Start = 0;
  End = 1;
  Link = 2;
}

message Route {
  string circuitId = 1;
  uint32 attempt = 2;
  message Egress {
    string binding = 1;
    string address = 2;
    string destination = 3;
    map<uint32, bytes> peerData = 4;
  }
  Egress egress = 3;
  message Forward {
    string srcAddress = 1;
    string dstAddress = 2;
    DestType dstType = 3;
  }
  repeated Forward forwards = 4;
  Context context = 5;
  uint64 timeout = 6;
  map<string, string> tags = 7;
}

message Unroute {
  string circuitId = 1;
  bool now = 2;
}

message InspectRequest {
  repeated string requestedValues = 1;
}

message InspectResponse {
  bool success = 1;
  repeated string errors = 2;
  repeated InspectValue values = 3;

  message InspectValue {
    string name = 1;
    string value = 2;
  }
}

message VerifyRouter {
  string routerId = 1;
  repeated string fingerprints = 2;
}

message Listener {
  string address = 1;
  string protocol = 2;
  reserved 3; // formerly costTags, removed as unused
  reserved "costTags";
  repeated string groups = 4;
  string localBinding = 5;
}

message Listeners {
  repeated Listener listeners = 1;
  // generation identifies the router link config this set came from. It
  // increases with each applied config and restarts with the router process, so
  // a receiver compares it only within one control channel session. Updates can
  // arrive out of order (a multi-underlay channel gives no ordering across
  // underlays), so a receiver drops a generation it has already passed.
  uint64 generation = 2;
}

// StaleLinkMatchMode controls when an established link is considered
// stale relative to the current local link configuration.
//
// Orphaned: the link's supporting listener or dialer is entirely absent
//   from the current configuration. The mildest stale criterion.
// Changed: any detail of the link's supporting listener/dialer differs
//   from the current configuration (e.g., advertise address changed).
//   The aggressive stale criterion.
//
// The same vocabulary is used by the router.link gcMode config field,
// which adds a 'preserve' value to mean "never act."
enum StaleLinkMatchMode {
  StaleLinkMatchChanged = 0;
  StaleLinkMatchOrphaned = 1;
}

message CheckStaleLinksRequest {
  StaleLinkMatchMode mode = 1;
}

// StaleLinkSide identifies which side of a link the reporting router
// represents. A link has two endpoints; each endpoint reports its own
// side. The controller aggregates the two reports.
enum StaleLinkSide {
  StaleLinkSideDialer = 0;
  StaleLinkSideListener = 1;
}

message LinkStaleReport {
  string linkId = 1;
  StaleLinkSide side = 2;
  bool stale = 3;
  // reason is human-readable; populated when stale is true.
  string reason = 4;
  // iteration is the link incarnation this verdict was computed against. A link
  // id is reused across re-dials, so a verdict is only valid for the iteration
  // that produced it.
  uint32 iteration = 5;
}

message CheckStaleLinksResponse {
  string routerId = 1;
  bool success = 2;
  string message = 3;
  repeated LinkStaleReport reports = 4;
}

message CtrlEndpoint {
  string address = 1;
  repeated string groups = 2;
}

message CtrlDetail {
  string id = 1;
  repeated CtrlEndpoint endpoints = 2;
}

message UpdateCtrlAddresses {
  repeated string addresses = 1;
  uint64 index = 2;
  bool isLeader = 3;
  repeated CtrlDetail controllers = 4;
}

message UpdateClusterLeader {
  uint64 index = 1;
}

enum PeerState {
  Healthy = 0;
  Unhealthy = 1;
  Removed = 2;
}

message PeerStateChange {
  string id = 1 ;
  string version = 2;
  PeerState state = 3;
  repeated Listener listeners = 4;
}

message PeerStateChanges {
  repeated PeerStateChange changes = 1;
}

message RouterMetadata {
  repeated RouterCapability capabilities = 1;
}

message Interface {
  string name = 1;
  string hardwareAddress = 2;
  int64 mtu = 3;
  int64 index = 4;
  uint64 flags = 5;
  repeated string addresses = 6;
}

message RouterInterfacesUpdate {
  repeated Interface interfaces = 1;
}

message LinkStateUpdate {
  string linkId = 1;
  uint32 linkIteration = 2;
  LinkConnState connState = 3;
}

message Alert {
  string sourceType = 1;
  string sourceId = 2;
  int64 timestamp = 3;
  string severity = 4;
  string message = 5;
  repeated string details = 6;
  map<string, string> relatedEntities = 7;
}

message Alerts {
  repeated Alert alerts = 1;
}

message CtrlChanListener {
    string address = 1;
    repeated string groups = 2;
}

message CtrlChanListeners {
    repeated CtrlChanListener listeners = 1;
}