Fix: LWT routing enhancements to utilize LBP

[nikagra]

Addresses: #384

Summary

LWT statements previously bypassed the configured LoadBalancingPolicy and used raw replicas from the token map, which ignored DC/rack-aware policies. This PR routes LWT through LBP, introduces explicit routing hints, and adjusts replica handling to prefer local-DC replicas and avoid rack-local bias.

Motivation

In clusters using TokenAware with DC/rack-aware policies, LWT traffic was coordinated against replicas in a fixed order, sometimes in a different DC or rack than intended. This led to suboptimal coordination and unexpected cross-DC behavior.

Changes

• Public API:
  • Add RequestRoutingType enum: REGULAR, LWT.
  • Add RequestRoutingMethod enum: REGULAR, PRESERVE_REPLICA_ORDER, TOKEN_BASED_REPLICA_SHUFFLING (hint; only PRESERVE_REPLICA_ORDER is honored in this PR).
  • Extend Request:
    • @Nullable RequestRoutingType getRequestType()
    • default RequestRoutingMethod getRoutingMethod() { return RequestRoutingMethod.REGULAR; }
• Statements:
  • SimpleStatement, BoundStatement, BatchStatement, graph statements, and PrepareRequest now implement getRequestType() (LWT when applicable; otherwise REGULAR).
  • Refactor BatchStatementBuilder and DefaultBatchStatement: replace isLWT plumbing with RequestRoutingType. isLWT() now derives from routing type or constituent statements.
• Request execution:
  • Remove LWT-specific replica lookup from CqlRequestHandler; routing for both LWT and non-LWT is delegated to LBP via DefaultLoadBalancingPolicy.newQueryPlan(...).
• Load balancing (DefaultLoadBalancingPolicy):
  • Derive replicas from the request when available.
  • LWT:
    • Build the plan from replicas, preferring local-DC replicas when a local DC is configured; preserve original replica order.
    • Ignore local rack prioritization to avoid rack-local leader congestion; treat local-DC replicas uniformly.
  • Non-LWT: preserve existing behavior (local-DC live nodes; replicas bubbled to the front).
  • Honor RequestRoutingMethod.PRESERVE_REPLICA_ORDER by skipping shuffling.
  • Factor replica movement/shuffling and slow-replica avoidance into helpers; apply health-based reordering only when avoidSlowReplicas is enabled.
  • Accept @Nullable Request and @Nullable Session to align with updated call sites.
• Nullability/test adjustments:
  • Update NodeStateIT to accept nullable params in newQueryPlan.
  • Update examples (KeyRequest) to implement getRequestType().

Tests

• LWTLoadBalancingIT: assert coordinators are a subset of replicas (not a single fixed node).
• LWTLoadBalancingMultiDcIT: new test verifying LWT routing prefers local-DC replicas in multi-DC setups.
• BatchStatementIT: strengthen LWT batch coverage; validate serial consistency, RequestRoutingType, presence of routing key, and rerun behavior.
• Minor test rule/constant cleanups.

Behavior

• LWT requests:
  • Routed through LBP using the computed replica set.
  • Prefer local-DC replicas; do not enforce rack-local prioritization.
  • Optionally preserve replica order when getRoutingMethod() == PRESERVE_REPLICA_ORDER.
• Non-LWT requests:
  • Unchanged; existing DC/rack-aware + token-aware behavior remains.

Backward Compatibility

• API additions are backward-compatible (new enums and default methods).
• Existing client code continues to work; advanced users can opt into routing hints via Request.

Notes for Reviewers

• RequestRoutingMethod.TOKEN_BASED_REPLICA_SHUFFLING is introduced as a hint but not actively applied in DefaultLoadBalancingPolicy in this PR; scope limited to PRESERVE_REPLICA_ORDER.
• Graph statements and PrepareRequest report REGULAR routing type by default.

[avikivity]

Fix: LWT routing enhancements to utilize LBP

What's LBP?

[dkropachev]

Fix: LWT routing enhancements to utilize LBP

What's LBP?

LoadBalancingPolicy

[dkropachev]

Last ask

[dkropachev]

1. Add setRequestRoutingType in DefaultBatchStatement
2. Make setRequestRoutingType and getRequestRoutingType consistent everywhere, routingType should be @nullable everywhere.
3. For that you will need also update all the instance variables of requestRoutingType to be @nullable too, or just leave them without annotation.

[dkropachev]

Great job @nikagra .