circuitbreaker.proto

syntax = "proto3";

package v1;

import "google/protobuf/wrappers.proto";
import "google/protobuf/duration.proto";
import "model.proto";

option go_package = "github.com/polarismesh/specification/source/go/api/v1/fault_tolerance";
option java_package = "com.tencent.polaris.specification.api.v1.fault.tolerance";
option java_outer_classname = "CircuitBreakerProto";

//单个熔断规则定义
message CircuitBreaker {
  // deprecated
  google.protobuf.StringValue id = 1;

  // 规则版本
  // deprecated
  google.protobuf.StringValue version = 2;

  // 规则名
  // deprecated
  google.protobuf.StringValue name = 3;

  // 规则命名空间
  // deprecated
  google.protobuf.StringValue namespace = 4;

  // 规则所属服务
  google.protobuf.StringValue service = 5;
  google.protobuf.StringValue service_namespace = 6;

  //熔断规则可以分为被调规则和主调规则
  //被调规则针对所有的指定主调生效，假如不指定则对所有的主调生效
  //主调规则为当前主调方的规则，假如不指定则针对所有被调生效
  // deprecated
  repeated CbRule inbounds = 7;
  // deprecated
  repeated CbRule outbounds = 8;

  // deprecated
  google.protobuf.StringValue token = 9;
  // deprecated
  google.protobuf.StringValue owners = 10;

  // 业务
  // deprecated
  google.protobuf.StringValue business = 11;
  // 部门
  // deprecated
  google.protobuf.StringValue department = 12;

  // 规则描述
  // deprecated
  google.protobuf.StringValue comment = 13;
  // deprecated
  google.protobuf.StringValue ctime = 14;
  // deprecated
  google.protobuf.StringValue mtime = 15;

  google.protobuf.StringValue revision = 16;

  reserved 17 to 20;
  // circuitbreaker rules for current service
  repeated CircuitBreakerRule rules = 21;
}

// 主调匹配规则
message SourceMatcher {
  // 主调命名空间以及服务名，可以为*，代表全匹配
  google.protobuf.StringValue service = 1;
  google.protobuf.StringValue namespace = 2;
  // 可选，主调业务标签，用于匹配是否使用该熔断规则，可放置用户的接口信息等
  map<string, MatchString> labels = 3;
}

// 熔断恢复配置
message RecoverConfig {
  // 触发熔断后到半开状态之间的等待间隔
  google.protobuf.Duration sleepWindow = 1;
  // 半开后，最多重试多少次恢复
  google.protobuf.UInt32Value maxRetryAfterHalfOpen = 2;
  // 半开后放量的最大百分比
  repeated google.protobuf.UInt32Value requestRateAfterHalfOpen = 3;
  // 熔断器半开到关闭所必须的最少成功率，默认100%
  google.protobuf.UInt32Value successRateToClose = 4;
  // 半开后最大放量数（用户不配置最大百分比时默认使用该配置）
  google.protobuf.UInt32Value requestCountAfterHalfOpen = 5;
  //主动探测配置
  enum OutlierDetectWhen {
    //不开启监控探测
    NEVER = 0;
    //只有在熔断恢复时才开启健康探测
    ON_RECOVER = 1;
    //一直开启健康探测
    ALWAYS = 2;
  }
  OutlierDetectWhen outlierDetectWhen = 6;
}

// 熔断策略
message CbPolicy {
  // 错误率熔断配置
  message ErrRateConfig {
    //是否启用错误率配置
    google.protobuf.BoolValue enable = 1;
    // 触发错误率熔断的最低请求阈值
    google.protobuf.UInt32Value requestVolumeThreshold = 2;
    // 可选。触发保持状态的错误率阈值，假如不配置，则默认不会进入Preserved状态
    google.protobuf.UInt32Value errorRateToPreserved = 3;
    // 触发熔断的错误率阈值
    google.protobuf.UInt32Value errorRateToOpen = 4;
    //错误码相关特定配置
    message SpecialConfig {
      // 熔断关心的错误类型，用户可以自己定义
      google.protobuf.StringValue  type = 1;
      repeated google.protobuf.Int64Value errorCodes = 2;
      google.protobuf.UInt32Value errorRateToPreserved = 3;
      google.protobuf.UInt32Value errorRateToOpen = 4;
    }
    repeated SpecialConfig specials = 5;
  }
  ErrRateConfig errorRate = 1;
  // 慢调用率熔断策略配置
  message SlowRateConfig {
    // 是否启用慢调用率配置
    google.protobuf.BoolValue enable = 1;
    // 最大响应时间，超过该时间属于慢调用请求
    google.protobuf.Duration maxRt = 2;
    // 可选。触发保持状态的超时率阈值，假如不配置，则默认不会进入Preserved状态
    google.protobuf.UInt32Value slowRateToPreserved = 3;
    // 触发熔断的超时率阈值
    google.protobuf.UInt32Value slowRateToOpen = 4;
  }
  SlowRateConfig slowRate = 2;
  // 熔断的决策周期，多久触发一次熔断决策
  google.protobuf.Duration judgeDuration = 3;
  //最大熔断比例，超过多少比例后不会继续熔断
  google.protobuf.UInt32Value maxEjectionPercent = 4;
  //连续错误数熔断配置
  message ConsecutiveErrConfig {
    // 是否启用连续错误数配置
    google.protobuf.BoolValue enable = 1;
    // 连续错误数阈值，进入Preserved状态
    google.protobuf.UInt32Value consecutiveErrorToPreserved = 2;
    // 连续错误数阈值，进入Open状态
    google.protobuf.UInt32Value consecutiveErrorToOpen = 3;
  }
  ConsecutiveErrConfig consecutive = 5;
}

// 目标set的规则
message DestinationSet {
  // 被调命名空间以及服务名，可以为*，代表全匹配
  google.protobuf.StringValue service = 1;
  google.protobuf.StringValue namespace = 2;
  // 可选，SUBSET标识
  map<string, MatchString> metadata = 3;
  // 需要进行熔断的资源
  // 支持SUBSET（子集群），以及INSTANCE（单个实例），默认为SUBSET
  enum Resource {
    // 针对实例分组进行熔断
    SUBSET = 0;
    // 针对实例进行熔断
    INSTANCE = 1;
  }
  Resource resource = 4;
  // 熔断决策类型，支持GLOBAL（分布式决策）以及LOCAL(本地决策），默认GLOBAL
  // 当指定为GLOBAL时，则会定期上报统计数据并根据汇总数据进行熔断决策
  enum Type {
    GLOBAL = 0;
    LOCAL = 1;
  }
  Type type = 5;

  //熔断范围，是否扩散针对相同服务下所有接口进行熔断
  enum Scope {
    //触发熔断条件，扩散熔断所有接口
    ALL = 0;
    //触发熔断条件，只熔断当前接口
    CURRENT = 1;
  }
  Scope scope = 6;

  // 熔断数据度量周期
  // 所有的阈值指标按此周期进行统计
  google.protobuf.Duration metricWindow = 7;

  // 熔断数据统计精度，决定数据度量的最小周期
  // 度量滑窗的步长=window/precision
  google.protobuf.UInt32Value metricPrecision = 8;

  // 熔断数据上报周期，对分布式熔断有效
  google.protobuf.Duration updateInterval = 9;

  // 触发熔断后恢复配置
  RecoverConfig recover = 10;

  // 熔断策略
  CbPolicy policy = 11;

  // 被调的接口信息，指定哪些接口会使用该规则
  MatchString method = 12;

  // 返回码，指定哪些返回码会使用该规则
  repeated google.protobuf.Int64Value errorCodes = 13;
}

// 具体熔断规则
message CbRule {
  // 如果匹配Source规则，按照Destination进行熔断
  // 多个Source之间的关系为或
  repeated SourceMatcher sources = 1;
  repeated DestinationSet destinations = 2;
}

message RuleMatcher {
  message SourceService {
    string service = 1;
    string namespace = 2;
  }

  message DestinationService {
    string service = 1;
    string namespace = 2;
    // deprecated_filed  using api.path in blockConfig instead
    MatchString method = 3 [deprecated = true];
  }
  SourceService source = 1;
  DestinationService destination = 2;
}

// circuitbreaking level
enum Level {
  UNKNOWN = 0;
  // service level circuitbreaking
  SERVICE = 1;
  // method level circuitbreaking
  METHOD = 2;
  // group level circuitbreaking
  GROUP = 3;
  // instance level circuitbreaking
  INSTANCE = 4;
}

// new specific rule for circuitbreaker config
message CircuitBreakerRule {
  string id = 1;
  // rule name
  string name = 2;
  // namespace of rule
  string namespace = 3;
  // enable this router
  bool enable = 4;
  // revision routing version
  string revision = 5;
  // ctime create time of the rules
  string ctime = 6;
  // mtime modify time of the rules
  string mtime = 7;
  // etime enable time of the rules
  string etime = 8;
  // description simple description rules
  string description = 9;
  // reserve for metadata
  reserved 10 to 20;
  // the circuitbreaking level
  Level level = 21;
  // match condition for this rule
  RuleMatcher rule_matcher = 22;
  // deprecated_filed error conditions to judge an invocation as an error
  repeated ErrorCondition error_conditions = 23 [deprecated = true];
  // deprecated_filed trigger condition to trigger circuitbreaking
  repeated TriggerCondition trigger_condition = 24 [deprecated = true];
  // the maximum % of an upstream cluster that can be ejected
  uint32 max_ejection_percent = 25;
  // recover condition to make resource open to close
  RecoverCondition recoverCondition = 26;
  // fault detection enable config
  FaultDetectConfig faultDetectConfig = 27;
  // fall back configuration
  FallbackConfig fallbackConfig = 28;
  // list for block configuration
  repeated BlockConfig block_configs = 29 [ json_name = "block_configs" ];
  // priority rules priority
  uint32 priority = 30 [ json_name = "priority" ];
  // 熔断规则标签数据
  map<string, string> metadata = 31 [ json_name = "metadata" ];
  // 操作标志位
  bool editable = 40 [ json_name = "editable" ];
  bool deleteable = 41 [ json_name = "deleteable" ];
}

// the condition to judge an input invocation as an error
message ErrorCondition {
  enum InputType {
    UNKNOWN = 0;
    RET_CODE = 1;
    DELAY = 2;
  }
  InputType input_type = 1;
  MatchString condition = 2;
}

// the error condition to trigger circuitbreaking
message TriggerCondition {
  enum TriggerType {
    UNKNOWN = 0;
    ERROR_RATE = 1;
    CONSECUTIVE_ERROR = 2;
  }
  TriggerType trigger_type = 1;
  uint32 error_count = 2;
  uint32 error_percent = 3;
  uint32 interval = 4;
  uint32 minimum_request = 5;
}

// circuitbreaking OPEN status recover
message RecoverCondition {
  // seconds from open to half-open
  uint32 sleep_window = 1;
  // consecutive success request to recover
  uint32 consecutiveSuccess = 2;
}

// fault detect config within circuitbreaking
message FaultDetectConfig {
  bool enable = 1;
}

// blocking strategy
message BlockConfig {
  string name = 1 [ json_name = "name" ];
  // blocking target api
  API api = 2 [ json_name = "api" ];
  // conditions to judge an invocation as an error
  repeated ErrorCondition error_conditions = 3 [ json_name = "error_conditions" ];
  // trigger condition to trigger circuitbreaking
  repeated TriggerCondition trigger_conditions = 4 [ json_name = "trigger_conditions" ];
}

// fallback config
message FallbackConfig {
  bool enable = 1;
  FallbackResponse response = 2;
}

// fallback response
message FallbackResponse {
  int32 code = 1;
  message MessageHeader {
    string key = 1;
    string value = 2;
  }
  repeated MessageHeader headers = 2;
  string body = 3;
}