Route Master/Replica SCAN continuations to the issuing node #3287

[lsh1215]

Fixes #3287 — undefined SCAN-family results when ReadFrom spreads reads across nodes on a Master/Replica connection.

Problem

SCAN/HSCAN/SSCAN/ZSCAN cursors are node-local state: the cursor value is a physical position in that node's hashtable, so a continuation request (cursor != 0) must return to the node that issued it. On Master/Replica, every replica holds a full copy of the keyspace, so ReadFrom load-balances individual reads across nodes. That is correct for stateless reads, but for the stateful SCAN family it means MasterReplicaConnectionProvider re-selects a read node per call, and a continuation can land on a different node that interprets the cursor against its own table — yielding undefined results (silently missing/duplicated elements).

Measured with a 1000-field hashtable-encoded hash:

ReadFrom.MASTER  -> 1000 / 1000
ReadFrom.ANY     -> ~740-780 / 1000   (nondeterministic)

Fix

Carry the issuing node on the cursor and pin continuations to it (the opposite direction of the cluster "aggregate" scan — here we stick):

• ScanCursor gains an optional, package-private source (RedisURI), exposed across packages via a new ScanCursorAccessor (following the existing OrderingReadFromAccessor pattern), so the public ScanCursor API is unchanged. Immutable INITIAL/FINISHED reject setSource.
• RedisCommandBuilder propagates the source hint from the input cursor to the cursor that carries the response, across all scan builders (incl. streaming). Reusing the returned cursor object — as ScanIterator/ScanStream already do — carries it automatically.
• MasterReplicaChannelWriter recognizes scan commands at the single routing choke point (covers sync/async/reactive): continuations pin to the issuing node; initial requests stamp the selected node onto the returned cursor.
• MasterReplicaConnectionProvider adds a node-reporting overload and getPinnedConnectionAsync, which fails fast with a descriptive RedisException if the issuing node has left the topology, instead of silently re-routing (which would reintroduce undefined results).

Read load-balancing for non-scan reads and for initial scan selection is unchanged; the cluster scan path is untouched.

Tests

• Unit: initial-stamp, continuation-pin, fail-fast, non-scan default route, MULTI/WRITE binding, batch stamping, and provider node-notification / pin / fail.
• Integration (MasterReplicaStickyScanIntegrationTests): {SCAN, HSCAN, SSCAN, ZSCAN} × {sync, async, reactive} under ReadFrom.ANY must return every element, plus a ReadFrom.UPSTREAM control, against the standard docker-env master/replica pair.

Notes for reviewers (draft)

• I chose the ScanCursorAccessor approach over a public ScanCursor.setSource to avoid widening the public API; happy to switch to public @since 7.7 accessors if you prefer.
• findNodeByUri matches by host:port; if a failover reassigns the same host:port to a different physical node, the pin would target it — a pre-existing Master/Replica assumption (ConnectionKey), not introduced here.
• Pinning of scan continuations dispatched inside a batch/transaction is out of scope (documented non-goal); the standard APIs dispatch scans as single commands.
• Still draft: the integration matrix needs a run against the real docker-env before this is ready for review.

---

Make sure that:

• You have read the contribution guidelines.
• There is a tracking issue (Undefined results when using ReadFrom with SCAN family commands #3287, help-wanted / mre-available).
• You applied code formatting rules using the mvn formatter:format target. No formatting-only changes are included.
• Unit and integration tests back the change.

---

Note

Medium Risk
Changes read routing for a core command family on Master/Replica connections; behavior is scoped to scan commands with solid tests, but incorrect pinning would still cause subtle data-iteration bugs.

Overview
Fixes #3287: under Master/Replica with ReadFrom load-balancing, SCAN/HSCAN/SSCAN/ZSCAN continuations could hit a different replica and return incomplete or duplicate results because cursors are node-local.

ScanCursor now carries an optional internal RedisURI source (via ScanCursorAccessor, public API unchanged). RedisCommandBuilder copies that hint from the request cursor onto the response cursor for all scan command builders (including streaming). MasterReplicaChannelWriter routes initial scans through read selection while stamping the chosen node on the cursor, and routes continuations through getPinnedConnectionAsync when a source is set; batched reads stamp unscanned cursors on the same selected node. MasterReplicaConnectionProvider adds a listener overload for reporting the selected node and fails fast if the pinned node left the topology.

Unit tests cover propagation, pinning, transactions, and batches; MasterReplicaStickyScanIntegrationTests exercises full iterations across sync/async/reactive under ReadFrom.ANY.

^{Reviewed by Cursor Bugbot for commit 7df3592. Bugbot is set up for automated code reviews on this repo. Configure here.}

[a-TODO-rov]

Hey @lsh1215
Thanks for the contribution. I am reviewing your PR.

[a-TODO-rov]

Hey again @lsh1215
I am considering another approach that is more consistent with the way the driver handles this problem in cluster mode.
You are welcome to contribute to the discussion #3287 (comment)