[improve][broker][PIP-379] Improve hash collision handling by restoring consumer when other leaves

[lhotari]

Fixes #23443

Motivation

In the current ConsistentHashingStickyKeyConsumerSelector implementation, when there's a hash ring point collision,
the original entry will be preserved and the attempted addition will be rejected.
This isn't a problem with the consumerNameIndexTracker solution since the collisions won't align for all hash ring points when using the same consumer name. Because of this, collisions won't affect the overall distribution significantly when the number of hash ring points is sufficiently large (>100).

However, when the "selected" consumer is removed, the colliding consumer should be selected and take over it's hash ring point. This PR implements that logic.

Modifications

• add HashRingPointEntry which holds the selected consumer and the colliding consumers
• add logic for adding and removing to handle the colliding consumers in the designed way.
• add test coverage
  • replace previous test that had too strict expectations.
• add methods to range classes to be used in tests

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 92.10526% with 3 lines in your changes missing coverage. Please review.

Project coverage is 74.28%. Comparing base (bbc6224) to head (97f7eb8).
Report is 672 commits behind head on master.

Files with missing lines	Patch %	Lines
...ce/ConsistentHashingStickyKeyConsumerSelector.java	91.17%	1 Missing and 2 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #23447      +/-   ##
============================================
+ Coverage     73.57%   74.28%   +0.71%     
- Complexity    32624    34374    +1750     
============================================
  Files          1877     1940      +63     
  Lines        139502   146929    +7427     
  Branches      15299    16186     +887     
============================================
+ Hits         102638   109146    +6508     
- Misses        28908    29350     +442     
- Partials       7956     8433     +477     

Flag	Coverage Δ
inttests	27.32% <63.15%> (+2.74%)	⬆️
systests	24.39% <68.42%> (+0.07%)	⬆️
unittests	73.65% <92.10%> (+0.80%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...pache/pulsar/broker/service/RemovedHashRanges.java	72.72% <100.00%> (ø)
.../main/java/org/apache/pulsar/client/api/Range.java	86.20% <100.00%> (+8.93%)	⬆️
...ce/ConsistentHashingStickyKeyConsumerSelector.java	91.26% <91.17%> (-2.97%)	⬇️

... and 653 files with indirect coverage changes

[equanz]

LGTM