fix: keep colliding virtual nodes in ConsistentHash

[pjfanning]

Motivation

ConsistentHash stores ring positions in a SortedMap[Int, T]. When virtual nodes of two different nodes hash to the same position, the later entry silently overwrites the earlier one. As a result:

• the ring depends on the order in which nodes were given or added, so two instances built from the same nodes can route the same key to different nodes
• removing a node also deletes any position it collides on, even if another node owns that position (or the removed node was never in the ring), so the remaining node loses virtual nodes

Modification

• Keep every node that claims a ring position: the owner stays in the ring, and the others go in a collisions map, which is normally empty.

• On a collision, the node with the lowest toString owns the position, independent of insertion order. Nodes are already identified by toString, per the class docs.

• :- only releases the removed node's claims, and promotes the next claimant if the owner is removed.

• Documented the collision rule in the class Scaladoc.

• Added ConsistentHashSpec, using the two node names from the issue whose virtual nodes are known to collide with a factor of 10.

• apply builds the ring in one sorted batch: each virtual node is encoded as (ring position << 32 | index) in a primitive Long array and sorted once. Single-claimant positions go through a TreeMap builder, and only colliding runs go through the owner rule shared with :+.

Performance

JMH, 10 virtual nodes per node, old = current main, new = this PR:

Operation	Nodes	Old alloc	New alloc	Old time	New time
nodeFor	10 / 100 / 1000	24 B	24 B	0.08 / 0.17 / 0.21 us	0.08 / 0.11 / 0.21 us
apply	10	24.4 KB	18.5 KB	12 us	22 us (±20, noisy)
apply	100	230 KB	201 KB	219 us	235 us
apply	1000	2.39 MB	1.87 MB	3378 us	2899 us
:+ / :-	10 / 100 / 1000	16 KB / 125 KB / 1.31 MB	within ~10%		within noise

nodeFor, which is on the per-message path, is unchanged. apply, :+ and :- only run when the set of nodes or routees changes.

Result

The ring, and so nodeFor, is the same regardless of node order, and ch :- node routes like a ring built without that node.

Compared with the current release, routing only changes for keys that land on a colliding ring position. During a rolling upgrade, nodes on old and new versions could route those few keys differently.

Tests

• actor-tests/Test/testOnly org.apache.pekko.routing.ConsistentHashSpec without the fix: 5 of 6 failed (the remaining one is an "empty after removing all nodes" sanity check)
• actor-tests/Test/testOnly org.apache.pekko.routing.ConsistentHashSpec org.apache.pekko.routing.ConsistentHashingRouterSpec with the fix: 10 passed on 2.13.18 and 3.3.8, including a check that apply builds the same ring as adding the nodes one by one with :+
• JMH ConsistentHashBench (local only, not committed) comparing main and this PR, results above
• actor/mimaReportBinaryIssues: passed on 2.13.18 and 3.3.8
• scalafmt run on changed files

References

Fixes #3279

[pjfanning]

Impact of the routing change for colliding ring positions

Routing only changes for keys that land on a ring position where virtual nodes of two different nodes collide. Everywhere else the ring is identical to main.

How likely a collision is. Ring positions are 32-bit hashes. With P = nodes × virtual nodes positions, the expected number of colliding positions is about P²/2³³ (the default virtual-nodes-factor is 10):

Nodes × virtual nodes	Chance of any collision	Share of keys that change owner if there is one
10 × 10	~0.0001%	0.5%
100 × 10	0.01%	0.05%
1000 × 10	1.2%	0.005%
1000 × 100	69%	0.0005%

Only keys on the arc owned by the colliding position (about 1/P of keys) can move, and only when the previous last-written-wins owner differs from the new lowest-toString owner (about half the time).

What this means for each user, including mixed versions during a rolling upgrade:

• ConsistentHashingShardAllocationStrategy: only the coordinator runs it, and it sorts the nodes, so old and new versions never disagree at the same time. Once the coordinator runs this version, a shard whose id lands on a changed arc may be rebalanced once. For example, with 1000 shards on a 1000 × 10 ring that is about 0.05 shards, and only in the ~1.2% of clusters with a collision.
• Classic ConsistentHashingRoutingLogic: each sender routes independently, so during an upgrade old and new nodes could send those few keys to different routees, as already happens briefly on any membership change. On main the result depends on routee order, and cluster-aware routers don't sort routees, so two nodes on main can already disagree about colliding keys indefinitely. With this change they agree.
• ClusterClient receptionist: the ring only chooses which contact points to hand to a client, so a different choice doesn't affect correctness.
• Typed ConsistentHashingLogic: each router instance is local, so there is no cross-node agreement to break. It uses :-/:+, where main could also drop colliding positions owned by remaining routees when a routee was removed. That is fixed here.

Separately, ch :- node on main can strip virtual nodes from remaining nodes, or change the ring when removing a node that was never in it. Both are fixed here.

Suggested release note: "ConsistentHash now resolves virtual-node hash collisions deterministically and no longer drops virtual nodes; keys at colliding ring positions may map to a different node than before."