apache / apache/dubbo

[Feature] Design and implement new conditional rules V3.1

Open
#14,344 0 comments 0 reactions 0 assignees View on GitHub
component/need-triage type/need-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.