Skip to content

Commit 0320e89

Browse files
committed
feat(divide): optional deterministic key selection for sticky configuration (#8037)
1 parent 44a7f75 commit 0320e89

7 files changed

Lines changed: 586 additions & 1 deletion

File tree

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
package org.apache.shenyu.common.dto.convert.rule.sticky;
19+
20+
import java.util.Objects;
21+
22+
/**
23+
* Deterministic key extraction for hash-based selection (#8037).
24+
*
25+
* <p>Absent configuration keeps the plain load-balancing behavior: no key is
26+
* extracted and no request data is read. Deterministic hashing is not an
27+
* explicit binding — it writes no cookie of its own, while an active sticky
28+
* binding still records the chosen target for new sessions — and it re-maps
29+
* whenever the candidate set changes; it maps a key to the same target only
30+
* while configuration, identities and candidate set are equivalent across
31+
* gateway replicas.
32+
*/
33+
public class DeterministicKeyConfig {
34+
35+
/**
36+
* Where the deterministic key comes from.
37+
*/
38+
public enum KeyType {
39+
40+
/**
41+
* A single request header, addressed by name.
42+
*/
43+
HEADER,
44+
45+
/**
46+
* A single request cookie, addressed by name.
47+
*/
48+
COOKIE
49+
}
50+
51+
/**
52+
* Default source when a key is configured without an explicit type.
53+
*/
54+
public static final KeyType DEFAULT_TYPE = KeyType.HEADER;
55+
56+
/**
57+
* Where the key is read from.
58+
*/
59+
private KeyType type = DEFAULT_TYPE;
60+
61+
/**
62+
* The header or cookie name the key is read from.
63+
*/
64+
private String name;
65+
66+
/**
67+
* Get the key source.
68+
*
69+
* @return the key source
70+
*/
71+
public KeyType getType() {
72+
return type;
73+
}
74+
75+
/**
76+
* Set the key source.
77+
*
78+
* @param type the key source
79+
*/
80+
public void setType(final KeyType type) {
81+
this.type = type;
82+
}
83+
84+
/**
85+
* Get the header or cookie name.
86+
*
87+
* @return the name
88+
*/
89+
public String getName() {
90+
return name;
91+
}
92+
93+
/**
94+
* Set the header or cookie name.
95+
*
96+
* @param name the name
97+
*/
98+
public void setName(final String name) {
99+
this.name = name;
100+
}
101+
102+
/**
103+
* Whether a usable key source is configured.
104+
*
105+
* @return true when a non-blank name is configured
106+
*/
107+
public boolean isConfigured() {
108+
return Objects.nonNull(name) && !name.isBlank();
109+
}
110+
}

‎shenyu-common/src/main/java/org/apache/shenyu/common/dto/convert/rule/sticky/StickySessionConfig.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,19 @@ public class StickySessionConfig {
7171
*/
7272
private String onUnavailable = "REBIND";
7373

74+
/**
75+
* Optional deterministic key for hash-based selection. Absent configuration
76+
* keeps the plain load-balancing behavior; when configured, a request that
77+
* carries the key is mapped onto the candidate set by the consistent hash
78+
* ring instead of the load-balancing algorithm. This is key hashing, not an
79+
* explicit binding: no cookie is written for the key itself, while an active
80+
* binding still records the chosen target for new sessions. The mapping
81+
* re-applies from the live candidate set whenever no binding is present.
82+
* The key applies only while the enclosing configuration is active — enabled
83+
* with binding secrets, a cookie name and a positive lifetime (#8037).
84+
*/
85+
private DeterministicKeyConfig key;
86+
7487
/**
7588
* Whether affinity is enabled.
7689
*
@@ -160,4 +173,22 @@ public String getOnUnavailable() {
160173
public void setOnUnavailable(final String onUnavailable) {
161174
this.onUnavailable = onUnavailable;
162175
}
176+
177+
/**
178+
* Get the optional deterministic key configuration.
179+
*
180+
* @return the key configuration, or null when not configured
181+
*/
182+
public DeterministicKeyConfig getKey() {
183+
return key;
184+
}
185+
186+
/**
187+
* Set the deterministic key configuration.
188+
*
189+
* @param key the key configuration
190+
*/
191+
public void setKey(final DeterministicKeyConfig key) {
192+
this.key = key;
193+
}
163194
}

‎shenyu-loadbalancer/src/main/java/org/apache/shenyu/loadbalancer/entity/LoadBalanceData.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ public class LoadBalanceData {
4040
private Map<String, Object> attributes = Collections.emptyMap();
4141

4242
private Map<String, Collection<String>> queryParams = Collections.emptyMap();
43+
44+
/**
45+
* An explicit deterministic hash key. When set, hash-based selection uses it
46+
* instead of the client ip; every other algorithm ignores it (#8037).
47+
*/
48+
private String hashKey;
4349

4450
/**
4551
* Instantiates a new Load balance data.
@@ -201,4 +207,22 @@ public void setUrl(final URI url) {
201207
public void setIp(final String ip) {
202208
this.ip = ip;
203209
}
210+
211+
/**
212+
* Get the explicit deterministic hash key.
213+
*
214+
* @return the hash key, or null when not set
215+
*/
216+
public String getHashKey() {
217+
return hashKey;
218+
}
219+
220+
/**
221+
* Set the explicit deterministic hash key.
222+
*
223+
* @param hashKey the hash key
224+
*/
225+
public void setHashKey(final String hashKey) {
226+
this.hashKey = hashKey;
227+
}
204228
}

‎shenyu-loadbalancer/src/main/java/org/apache/shenyu/loadbalancer/spi/HashLoadBalancer.java‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
package org.apache.shenyu.loadbalancer.spi;
1919

2020
import org.apache.shenyu.common.cache.WindowTinyLFUMap;
21+
import org.apache.commons.lang3.StringUtils;
2122
import org.apache.shenyu.common.constant.Constants;
2223
import org.apache.shenyu.loadbalancer.entity.LoadBalanceData;
2324
import org.apache.shenyu.loadbalancer.entity.Upstream;
@@ -53,7 +54,10 @@ public Upstream doSelect(final List<Upstream> upstreamList, final LoadBalanceDat
5354
final List<String> ringKey = new ArrayList<>(upstreamList.size());
5455
upstreamList.forEach(upstream -> ringKey.add(upstream.identity().hashKey()));
5556
final SortedMap<Long, Integer> treeMap = ringCache.computeIfAbsent(List.copyOf(ringKey), this::buildRing);
56-
long hash = hash(data.getIp());
57+
// an explicit deterministic key (e.g. extracted from a configured header or cookie)
58+
// takes precedence over the legacy client-ip key, which stays the default (#8037)
59+
final String key = StringUtils.isNotBlank(data.getHashKey()) ? data.getHashKey() : data.getIp();
60+
long hash = hash(key);
5761
SortedMap<Long, Integer> lastRing = treeMap.tailMap(hash);
5862
if (!lastRing.isEmpty()) {
5963
return upstreamList.get(lastRing.get(lastRing.firstKey()));

‎shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-divide/src/main/java/org/apache/shenyu/plugin/divide/DividePlugin.java‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
import org.apache.shenyu.common.dto.RuleData;
2424
import org.apache.shenyu.common.dto.SelectorData;
2525
import org.apache.shenyu.common.dto.convert.rule.canary.CanaryConfig;
26+
import org.apache.shenyu.common.dto.convert.rule.sticky.DeterministicKeyConfig;
2627
import org.apache.shenyu.common.dto.convert.rule.sticky.StickySessionConfig;
2728
import org.apache.shenyu.common.dto.convert.rule.impl.DivideRuleHandle;
2829
import org.apache.shenyu.common.enums.HttpRetryBackoffSpecEnum;
@@ -49,6 +50,9 @@
4950
import org.apache.shenyu.plugin.divide.canary.CanaryDecisionService;
5051
import org.apache.shenyu.plugin.divide.canary.DefaultCanaryDecisionService;
5152
import org.apache.shenyu.plugin.divide.handler.DividePluginDataHandler;
53+
import org.apache.shenyu.loadbalancer.factory.LoadBalancerFactory;
54+
import org.apache.shenyu.loadbalancer.entity.LoadBalanceData;
55+
import org.apache.shenyu.plugin.divide.sticky.DeterministicKeyExtractor;
5256
import org.apache.shenyu.plugin.divide.sticky.StickySessionAffinity;
5357
import org.slf4j.Logger;
5458
import org.slf4j.LoggerFactory;
@@ -86,6 +90,8 @@ public class DividePlugin extends AbstractShenyuPlugin {
8690

8791
private final StickySessionAffinity stickySessionAffinity = new StickySessionAffinity();
8892

93+
private final DeterministicKeyExtractor deterministicKeyExtractor = new DeterministicKeyExtractor();
94+
8995
public DividePlugin() {
9096
this(new DefaultCanaryDecisionService());
9197
}
@@ -365,9 +371,41 @@ private Upstream resolveWithAffinity(final ServerWebExchange exchange, final Rul
365371
exchange.getResponse().setStatusCode(HttpStatus.SERVICE_UNAVAILABLE);
366372
return null;
367373
}
374+
// a configured deterministic key maps a binding-less request onto the admitted
375+
// candidates by the consistent hash ring; it is key hashing, not a binding —
376+
// no separate cookie is written for it and a missing key falls back to the
377+
// algorithm (#8037). The key is a sub-mode of the sticky configuration: it is
378+
// evaluated inside the affinity path, so sticky itself must be active (enabled
379+
// with usable binding secrets), which keeps one configuration surface.
380+
final Upstream keyed = resolveWithDeterministicKey(exchange, sticky, ruleHandle, breakeredUpstreamList);
381+
if (Objects.nonNull(keyed)) {
382+
return keyed;
383+
}
368384
return LoadbalancerUtils.getForExchange(breakeredUpstreamList, ruleHandle.getLoadBalance(), exchange);
369385
}
370386

387+
private Upstream resolveWithDeterministicKey(final ServerWebExchange exchange, final StickySessionConfig sticky,
388+
final DivideRuleHandle ruleHandle, final List<Upstream> breakeredUpstreamList) {
389+
final DeterministicKeyConfig keyConfig = Objects.nonNull(sticky) ? sticky.getKey() : null;
390+
if (Objects.isNull(keyConfig) || !keyConfig.isConfigured()) {
391+
return null;
392+
}
393+
final String key = deterministicKeyExtractor.extract(exchange, keyConfig);
394+
if (Objects.isNull(key)) {
395+
return null;
396+
}
397+
final LoadBalanceData data = new LoadBalanceData();
398+
data.setHashKey(key);
399+
final Upstream upstream = LoadBalancerFactory.selector(breakeredUpstreamList, LoadBalanceEnum.HASH.getName(), data);
400+
if (Objects.nonNull(upstream) && P2C.equals(ruleHandle.getLoadBalance())) {
401+
// the hash pick skips the P2C selection, which normally reserves the
402+
// attempt: the same accounting must apply or the count drifts down
403+
upstream.getInflight().incrementAndGet();
404+
upstream.setLastPicked(System.currentTimeMillis());
405+
}
406+
return upstream;
407+
}
408+
371409
private DivideRuleHandle buildRuleHandle(final RuleData rule) {
372410
return DividePluginDataHandler.CACHED_HANDLE.get().obtainHandle(CacheKeyUtils.INST.getKey(rule));
373411
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
package org.apache.shenyu.plugin.divide.sticky;
19+
20+
import org.apache.commons.lang3.StringUtils;
21+
import org.apache.shenyu.common.dto.convert.rule.sticky.DeterministicKeyConfig;
22+
import org.springframework.web.server.ServerWebExchange;
23+
24+
import java.util.Objects;
25+
26+
/**
27+
* Extracts the deterministic hash key from a single, explicitly configured request
28+
* location — one header or one cookie — addressed by name.
29+
*
30+
* <p>Nothing else about the request is read or copied: the extraction returns at most
31+
* one value, and a missing or blank key yields null so the request falls back to the
32+
* load-balancing algorithm. Forwarding headers are not trusted: only the name the
33+
* operator configured is consulted (#8037).
34+
*/
35+
public class DeterministicKeyExtractor {
36+
37+
/**
38+
* Extract the deterministic key for the request.
39+
*
40+
* @param exchange the current server exchange
41+
* @param config the key configuration
42+
* @return the key, or null when the configured location is missing or blank
43+
*/
44+
public String extract(final ServerWebExchange exchange, final DeterministicKeyConfig config) {
45+
if (Objects.isNull(config) || !config.isConfigured()) {
46+
return null;
47+
}
48+
final String key;
49+
if (DeterministicKeyConfig.KeyType.COOKIE == config.getType()) {
50+
key = Objects.nonNull(exchange.getRequest().getCookies().getFirst(config.getName()))
51+
? exchange.getRequest().getCookies().getFirst(config.getName()).getValue() : null;
52+
} else {
53+
key = exchange.getRequest().getHeaders().getFirst(config.getName());
54+
}
55+
return StringUtils.isBlank(key) ? null : key;
56+
}
57+
}

0 commit comments

Comments
 (0)