Sentinel scan iterator

[harshrai654]

Description

This PR implements the scanIterator method for the RedisSentinel client.
Previously, scanIterator was not exposed on the Sentinel client, limiting the ability to iterate over keys on the master node directly through the Sentinel interface. This implementation adds that capability with handling for failovers.

Issue: #2999

Changes:

• Automatic Failover Handling: If a master failover occurs during iteration, the iterator detects the MASTER_CHANGE topology event and automatically restarts the scan from the beginning on the new master. This ensures all keys are eventually covered, even if the topology changes mid-scan.
• Reset-on-Failover Strategy: Since Redis cursors are stateful and specific to a node instance, the iterator deliberately restarts from cursor 0 (the beginning) upon detecting a master failover. This guarantees data completeness but may result in duplicate keys being yielded, as documented.

---

Checklist

• Does npm test pass with this change (including linting)?
• Is the new or changed code fully tested?
• Is a documentation update included (if this change modifies existing APIs, or introduces new ones)?

---

Note

Medium Risk
New public API on the Sentinel master path; failover restart can yield duplicate or briefly inconsistent keys during iteration, though behavior is documented and tested.

Overview
Adds scanIterator on the Redis Sentinel client so callers can async-iterate master keys with the same ScanOptions as standalone clients.

On MASTER_CHANGE, the iterator resets the cursor to 0 and restarts (and discards a batch if failover happened mid-SCAN). That can duplicate keys and briefly skew the keyset vs replication; docs/sentinel.md documents dedup and pool behavior.

Each SCAN acquires/releases a master lease only around the command so loop bodies can run other commands (e.g. mGet) without deadlocking when masterPoolSize is 1. Integration tests cover normal scan, MATCH, in-loop commands, and failover during iteration.

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

[jit-ci]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[jit-ci]

❌ The following Jit checks failed to run:

• secret-detection-trufflehog

#jit_bypass_commit in this PR to bypass, Jit Admin privileges required.

More info in the Jit platform.

[nkaradzhov]

Hi @harshrai654, thanks for the contribution! On first glance, this looks good, gut it looks like there are some failing tests. Can you please resolve those, so we can have more thorough look on the final state of the code

[jit-ci]

❌ The following Jit checks failed to run:

• secret-detection-trufflehog
• static-code-analysis-semgrep-pro

#jit_bypass_commit in this PR to bypass, Jit Admin privileges required.

More info in the Jit platform.

[harshrai654]

Hey @nkaradzhov I have fixed the tests. A stopped node in previous test of the describe block was causing issues in the next test which requires healthy nodes in the sentinel. Added cleaning up of nodes of frame between these two tests.

[elimelt]

nit: Bloom filter is not really a sound way to deduplicate on its own, so I'm not sure about the phrasing "Set or Bloom filter".

I'm not an expert on Sentinel or Redis replication, but is there any chance the two values differ between old and new master?

[harshrai654]

• I agree, A Bloom filter isn’t a perfect deduplication mechanism.
  The reason I mentioned it is because it provides a very low-memory way to reduce duplicates for large keyspaces, even though it can still produce false positives and skip some unseen keys.
  I’ll update the documentation to clarify this tradeoff: using a Set gives strict, 100% deduplication, while a Bloom filter is only suitable when occasional false positives are acceptable in exchange for significantly lower memory usage.

• Yes, the results may differ between the old and new master.
  Redis replication is asynchronous, so a replica promoted to master may not contain exactly the same
  keyspace as the previous master at the moment of failover. Some writes may not yet have replicated,
  and new writes may occur on the promoted master after the failover.
  Because the iterator restarts from cursor 0 on the new master, any additions or deletions that
  happened around the failover will be reflected in the new scan.
  Reference: https://redis.io/docs/latest/commands/scan/#scan-guarantees

[elimelt]

• Yeah I only called it out because of the implication you made, i.e. "application requires processing each key exactly once" -> "use set or bloom filter"
• Difference in semantics between this and a regular scan is probably worth noting in the docs as well

[nkaradzhov]

@harshrai654 thank you so much! I will need to take a thorough look into this before passing it, and I am extremely busy on a big change that needs to happen very soon. So, apologies, but I will have to delay my full review here.

[harshrai654]

@harshrai654 thank you so much! I will need to take a thorough look into this before passing it, and I am extremely busy on a big change that needs to happen very soon. So, apologies, but I will have to delay my full review here.

No worries, Thanks for the update and for letting me know!

[TheIndra55]

This seems to cause a deadlock when the consumer tries to do another operation during the scan and there's not enough master clients available.

for await (const keys of sentinel.scanIterator()) {
    console.log(keys)

    // Hangs forever
    const values = await sentinel.mGet(keys)
    console.log(values)
}

[harshrai654]

Hey @TheIndra55, thanks for catching this! You are absolutely correct.

Acquiring the master connection for the entire lifespan of the iterator causes a resource starvation deadlock. Since acquire reserves a client from the pool and doesn't release it until the iterator finishes, any operation inside the consumer's loop (like your mGet example) that requires a connection will block indefinitely if the pool is exhausted (e.g., a single-connection pool).

Even with a larger pool, this implementation unnecessarily holds a connection idle while the user's code executes, reducing overall throughput.

The fix can be to do an "Acquire->Scan->Release" loop: we should acquire the connection only for the scan operation itself and release it immediately before yielding to the user. This ensures the pool is free for other operations during the consumer's processing phase.

Here is the proposed implementation:

async *scanIterator(
  this: RedisSentinelType<M, F, S, RESP, TYPE_MAPPING>,
  options?: ScanOptions & ScanIteratorOptions
) {
  let cursor = options?.cursor ?? "0";
  let shouldRestart = false;

  // This listener persists for the entire iterator life to track failovers
  const handleTopologyChange = (event: RedisSentinelEvent) => {
    if (event.type === "MASTER_CHANGE") {
      shouldRestart = true;
    }
  };
  this.on("topology-change", handleTopologyChange);

  try {
    do {
      // 1. Acquire lease JUST for the scan command
      const masterClient = await this.acquire();
      
      let reply;
      try {
        // If master changed since last loop, reset cursor to 0
        if (shouldRestart) {
          cursor = "0";
          shouldRestart = false;
        }
        
        reply = await masterClient.scan(cursor, options);
        
      } finally {
        // 2. Release IMMEDIATELY so the pool is available for the user
        masterClient.release();
      }

      // Handle edge case: Topology changed *during* the scan
      if (shouldRestart) {
        // Data might be from the old master, so we discard this batch 
        // and restart from cursor 0 on the new master.
        cursor = "0"; 
        continue;
      }

      // 3. Yield to user
      // The connection is released, so `await sentinel.mGet()` will succeed
      cursor = reply.cursor;
      yield reply.keys;

    } while (cursor !== "0");

  } finally {
    this.removeListener("topology-change", handleTopologyChange);
  }
}

This ensures we respect the pool limits and handle topology changes correctly by resetting the cursor if a failover occurs between (or during) iterations.

What do you think?

[nkaradzhov]

Hi @harshrai654 — first off, apologies for sitting on this for so long.
I pushed your Dec 9 proposal (acquire/release per scan page) onto the branch and rebased over master:

• Reworked the docs (docs/sentinel.md) to
  • (a) make the Set vs Bloom filter trade-off explicit per @elimelt's nit,
  • (b) call out the divergence from standalone SCAN guarantees, and
  • (c) document the per-page lease behavior so users know commands inside the loop are safe.
• Added a regression test (should not deadlock when consumer runs commands inside the loop with masterPoolSize 1)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 27f3d53. Configure here.}

[cursor]

Failover during cursor-zero scan silently terminates iterator

High Severity

When a MASTER_CHANGE event fires during a scan call where cursor is "0" (e.g., the very first iteration, or right after a failover restart), the continue at line 699 jumps to the do…while condition. Because line 702 (cursor = reply.cursor) was skipped, cursor is still "0", so cursor !== "0" evaluates to false and the loop exits immediately — yielding zero keys and silently terminating the iterator instead of restarting the scan on the new master.

 

^{Reviewed by Cursor Bugbot for commit 27f3d53. Configure here.}