Summary

This change updates grpc-gcp channel-affinity behavior and location-aware retry behavior in the Java Spanner client.

It does three things:

1. Uses random channel hints for grpc-gcp-backed single-use operations and multi-use transactions instead of reusing the session-affined hint.
2. Adds explicit affinity unbind handling for single-use read/query RPCs and terminal commit/rollback RPCs, including the retry-to-different-channel path.
3. Updates location-aware routing so retries for RESOURCE_EXHAUSTED do not go back to the same routed endpoint for the same logical request.

What Changed

grpc-gcp channel hints

When grpc-gcp is enabled:

• single-use read/query now uses a random channel hint
• single-use write (writeAtLeastOnce) now uses a random channel hint
• multi-use read-only transactions now get a random hint reused within that transaction
• multi-use read-write transactions now get a random hint reused within that transaction
• multiplexed single-use operations no longer use the bitset-based reserved single-use channel path

explicit affinity unbind

Added UNBIND_CHANNEL_HINT support and wired it through grpc-gcp call options.

This now:

• marks single-use read/query calls for unbind after completion
• preserves unbind when a streaming read/query is retried on a different grpc channel
• unbinds grpc-gcp affinity keys on commit
• unbinds grpc-gcp affinity keys on rollback

location-aware retry behavior

For location-aware routing:

• route selection now records tracing attributes/events
• if a routed endpoint returns RESOURCE_EXHAUSTED, the next retry attempt for that same logical request avoids that endpoint
• the skip is scoped by X-Goog-Spanner-Request-Id logical request identity, so unrelated transactions/requests do not nherit the exclusion
• if no alternate healthy replica is available, routing falls back to the default host