[Feature] Design and implement new conditional rules V3.1
- Dominant language
- Java
- Stars
- 41.6k
- Forks
- 26.4k
- Avg merge
- 15h 13m
- Merged PRs (30d)
- 4
Description
### Pre-check
- [X] I am sure that all the content I provide is in English.
### Search before asking
- [X] I had searched in the [issues](https://github.com/apache/dubbo/issues?q=is%3Aissue) and found no similar feature requirement.
### Apache Dubbo Component
Java SDK (apache/dubbo)
### Descriptions
## 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 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 subset.
- **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.
### Related issues
https://github.com/apache/dubbo-go/pull/2686
https://github.com/apache/dubbo-go/issues/2684
https://github.com/apache/dubbo/pull/14343
### Are you willing to submit a pull request to fix on your own?
- [X] Yes I am willing to submit a pull request on my own!
### Code of Conduct
- [X] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct)
Contributor guide
Research direction
The issue names no files, tests, or Java entry point. Start by locating Dubbo's conditional-router implementation and its existing configuration tests, then compare the requested V3.1 structure and matching rules with the related dubbo-go issue and pull request. Done means the documented V3.1 configuration and listed condition behavior are implemented and covered by tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100