feat(divide): optional deterministic key selection for sticky configuration (#8037) - #8212

Delivers the deterministic-key part of #8037 (the "configurable deterministic keys" phase), on top of the merged gateway-issued binding (#8098).

Problem

Sticky affinity so far covers explicit bindings only. The issue asks for deterministic key hashing as a separate mode: map a request carrying an operator-chosen key (a single header or cookie) onto the candidate set through a consistent hash ring, without creating a binding by itself. The existing hash load balancer has a consistent ring but is pinned to the client IP, and its data carrier deliberately receives empty request collections to avoid copying headers per allocation.

Change

• Configuration: StickySessionConfig gains an optional nested key (DeterministicKeyConfig: type HEADER (default) / COOKIE, name). Absent configuration keeps the plain load-balancing behavior — nothing is extracted, nothing copied. The key lives inside the active sticky configuration, so it shares that single enablement surface rather than adding a second switch.
• Extraction: DeterministicKeyExtractor reads exactly one named location and treats a missing or blank key as absent; the request falls back to the base algorithm.
• Load Balancer Data: LoadBalanceData carries an optional hashKey; the hash load balancer prefers it over the legacy client-ip key, which remains the default. Other algorithms ignore it.
• Admission & Accounting: In DividePlugin, the deterministic key applies only to binding-less requests (an explicit binding always wins) and is resolved from the candidate set that already passed canary and circuit-breaker admission — hashing can never bypass eligibility. With a P2C rule, a hash pick reserves the attempt exactly like a P2C selection does.
• Semantics: Kept distinct per the issue: this is key hashing, not an explicit binding — no cookie is written for the key itself, STRICT is defined only for presented bindings, and the mapping is stable only while configuration, identities and candidate set are equivalent across gateway replicas. It is not topology-independent session persistence.

Tests

• Mapping consistency: The same header value maps to the same target across requests; the target is always inside the admitted candidates.
• Fallbacks & parsing: Missing/blank key falls back to the base algorithm; COOKIE mode reads the cookie, not a same-named header; blank behaves like missing; no configured name means no extraction.
• Precedence & admission: An explicit binding wins over the key; a key never bypasses circuit-breaker admission (blocked target, ring lands on the survivor).
• Accounting: Under P2C a keyed pick reserves the attempt inside the request (inflight 2 at chain entry) and releases it on completion (back to baseline), so key hashing cannot drift P2C counts.
• Configuration contract: The nested key parses from the rule-handle JSON (COOKIE + name round-trip), so the operator-facing schema is exercised rather than only programmatic construction.
• Ring & Distribution: Re-mapping stays within the live candidate set; a 64-key distribution reaches all four candidates and is reproducible (MD5 ring, no randomness).
  • Red/green: Removing the explicit-key preference turns the distribution test into expected 4 but was 1 (everything lands on the client-ip node); removing the keyed pick's P2C reservation turns the accounting test red.

Verification

shenyu-loadbalancer: 83
shenyu-plugin-divide: 155
(clean reactor; shenyu-plugin-base 334 and shenyu-common 626/4 skipped green)
checkstyle: clean on the three touched modules