Design and implement new conditional rules V3.1

[YarBor]

to support #2684

Doc for New Routing Configuration

Configuration Format

This doc show how to set up condition-router configurations for your services/application.

The configurations are defined in a YAML format and must adhere to specific rules and parameters to ensure proper functioning.

Examples

configVersion: v3.1 # be v3.1 or V3.1 to use this
scope: service      # must be 'service' or 'application'
key: org.apache.dubbo.samples.CommentService # [service name] or [application name]
force: false        # decide hole condition route an empty set, return err Or ignore this rule
runtime: true       # decide is use cache
enabled: true       # decide is the rule enabled 
conditions:         # contains by many conditions, sort by condition.priority

  - priority: 10    # default 0, expect > 0
    from:           # match consumer-side url, match fail jump next condition, match success to match provider-side urls
      match: region=$region & version=v1    # string, use '&' to separate rules
    trafficDisable: false # default false, if set true & from match successfully,
                          # it will ignore ./{'to','force','ratio'} value AND ../../{'force'} value, return empty.
    to:             # match provider-side urls, contains by many destination-subsets
      - match: env=$env & region=shanghai   # if match fail, ignore subset
        weight: 100                         # int, default 100, Max INT_MAX, Min 0
      - match: env=$env & region=beijing
        weight: 200
      - match: env=$env & region=hangzhou
        weight: 300
    force: false    # here [force] decide to jump next or return empty, when get empty peer-set or ratio check false
    ratio: 20       # default 0, Max 100, Min 0 -- e.g. expect $result/$all-peers >= 20% -- fail to jump next(or return empty [decide by key(force)])

# e.g. this condition rule will ban all traffic which sent from version=1
  - priority: 5     
    from:
      match: version=v1
    trafficDisable: true

# e.g. this condition rule will show how to set region priority
  - priority: 20
    from:
      match:
    to:
      - match: region=$region
    ratio: 20

Configuration Structure

Top-Level Structure

• configVersion: (Required) Specifies the version of the configuration. Must be v3.1 or V3.1 to use this configuration format.
• scope: (Required) Defines the scope of the configuration. Must be either service or application.
• key: (Required) Specifies the name of the service or application. For example, org.apache.dubbo.samples.CommentService.
• force: (Optional) Boolean value that determines the behavior when a condition results in an empty set. If true, it returns an error; if false, it ignores this rule.
• runtime: (Optional) Boolean value that indicates whether to use cache.
• enabled: (Optional) Boolean value that indicates whether the rule is enabled.
• conditions: (Required) A list of conditions. Each condition contains matching rules for consumer-side and provider-side URLs and it will sort by condition.priority.

Conditions

Each condition block contains the following parameters:

• priority: (Optional) An integer that specifies the priority of the condition. Default is 0, with higher numbers indicating higher priority.(if trafficDisable == true, priority will be highest)
• from: (Required) Specifies the criteria for matching consumer-side URLs. If the match fails, it jumps to the next condition. If it matches successfully, it proceeds to match provider-side URLs.
  • match: (Required) A string that defines the matching rules using '&' to separate multiple rules. For example, region=$region & version=v1.
• trafficDisable: (Optional) Boolean value that defaults to false. If set to true and from matches successfully, it ignores the to, force, and ratio values within the condition, and the force value at the top level, returning empty.
• to: (Required) Specifies the criteria for matching provider-side URLs. It can contain multiple destination subsets.
  • match: (Required) A string that defines the matching rules for each subset.
  • weight: (Optional) An integer that specifies the weight of the subset. Default is 100, with a maximum of INT_MAX and a minimum of 0.
• force: (Optional) Boolean value that determines the behavior when a subset results in an empty set or fails a ratio check. If true, it returns empty; if false, it jumps to the next condition.
• ratio: (Optional) An integer that specifies the expected ratio of the result to all peers. Default is 0, with a maximum of 100 and a minimum of 0. For example, 20 means result/all-peers >= 20%.

Matching and Filtering Conditions

Supported Parameters

• Service Invocation Context: Such as interface, method, group, version.
• Request Context: Such as attachments[key] = value.
• Method Parameters: Such as arguments[0] = tom.
• URL Fields: Such as protocol, host, port.
• URL Extended Parameters: Such as application, organization.
• Custom Extensions: Developers can define custom extensions as needed.

Condition Operators

• Equal (=): Indicates a match. For example, method = getComment.
• Not Equal (!=): Indicates a mismatch. For example, method != getComment.

Value Support

• Comma-Separated Values: Multiple values separated by commas. For example, host != 10.20.153.10,10.20.153.11.
• Wildcard: Values ending with an asterisk () indicate a wildcard match. For example, `host != 10.20.`.
• Parameter Reference: Values starting with a dollar sign ($) reference consumer parameters. For example, region = $region.
• Integer Range: Integer value ranges. For example, userId = 1~100 or userId = 101~.
• Custom Extensions: Developers can define custom extensions as needed.

[sonarcloud[bot]]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
2.5% Duplication on New Code

See analysis details on SonarCloud

[wcy666103]

Is it better to trafficDisable by default to false? Every traffic rule that is written should be meaningful by default, instead of having to be shown to be false, and a false value that works by default gives the impression that it doesn't work, I think it can be set to false to reduce that thinking for the user and omit the line by default