fix(redis): use SCAN instead of KEYS for bucket deletion

  - KEYS command blocks Redis and is disabled in production.
  - SCAN provides production-safe incremental scanning.

Author: rojae

fluxgate-redis-ratelimiter/src/main/java/org/fluxgate/redis/connection/ClusterRedisConnection.java

@@ -1,6 +1,8 @@
 package org.fluxgate.redis.connection;
 
+import io.lettuce.core.KeyScanCursor;
 import io.lettuce.core.RedisURI;
+import io.lettuce.core.ScanArgs;
 import io.lettuce.core.ScriptOutputType;
 import io.lettuce.core.cluster.RedisClusterClient;
 import io.lettuce.core.cluster.api.StatefulRedisClusterConnection;
@@ -179,11 +181,29 @@ public long ttl(String key) {
   }
 
   @Override
+  @Deprecated
   public List<String> keys(String pattern) {
     // In cluster mode, this scans all nodes
     return new ArrayList<>(commands.keys(pattern));
   }
 
+  @Override
+  public List<String> scan(String pattern) {
+    // In cluster mode, Lettuce's scan() automatically scans all master nodes
+    List<String> result = new ArrayList<>();
+    ScanArgs scanArgs = ScanArgs.Builder.matches(pattern).limit(100);
+
+    KeyScanCursor<String> cursor = commands.scan(scanArgs);
+    result.addAll(cursor.getKeys());
+
+    while (!cursor.isFinished()) {
+      cursor = commands.scan(cursor, scanArgs);
+      result.addAll(cursor.getKeys());
+    }
+
+    return result;
+  }
+
   @Override
   public String flushdb() {
     // In cluster mode, this flushes all nodes

fluxgate-redis-ratelimiter/src/main/java/org/fluxgate/redis/connection/RedisConnectionProvider.java

@@ -127,13 +127,42 @@ public interface RedisConnectionProvider extends AutoCloseable {
   /**
    * Finds all keys matching the given pattern.
    *
-   * <p>Warning: This operation can be slow on large databases. Use with caution in production.
+   * <p><b>WARNING: DEPRECATED - Use {@link #scan(String)} instead.</b>
+   *
+   * <p>This operation uses the KEYS command which:
+   *
+   * <ul>
+   *   <li>Blocks Redis during execution (O(N) complexity)
+   *   <li>Is often disabled in production environments
+   *   <li>Can cause performance issues with large datasets
+   * </ul>
    *
    * @param pattern the pattern to match (e.g., "fluxgate:*")
    * @return list of matching keys
+   * @deprecated Use {@link #scan(String)} instead for production-safe key scanning
    */
+  @Deprecated
   java.util.List<String> keys(String pattern);
 
+  /**
+   * Scans keys matching the given pattern using SCAN command.
+   *
+   * <p>This is the production-safe alternative to {@link #keys(String)}:
+   *
+   * <ul>
+   *   <li>Non-blocking - scans incrementally without blocking Redis
+   *   <li>Production-safe - not disabled in production environments
+   *   <li>Memory-efficient - processes keys in batches
+   * </ul>
+   *
+   * <p>Note: SCAN may return duplicates in some cases (e.g., during rehashing). The caller should
+   * handle deduplication if needed.
+   *
+   * @param pattern the pattern to match (e.g., "fluxgate:*")
+   * @return list of matching keys (may contain duplicates)
+   */
+  java.util.List<String> scan(String pattern);
+
   /**
    * Flushes the current database (deletes all keys).
    *

fluxgate-redis-ratelimiter/src/main/java/org/fluxgate/redis/connection/StandaloneRedisConnection.java

@@ -1,11 +1,14 @@
 package org.fluxgate.redis.connection;
 
+import io.lettuce.core.KeyScanCursor;
 import io.lettuce.core.RedisClient;
 import io.lettuce.core.RedisURI;
+import io.lettuce.core.ScanArgs;
 import io.lettuce.core.ScriptOutputType;
 import io.lettuce.core.api.StatefulRedisConnection;
 import io.lettuce.core.api.sync.RedisCommands;
 import java.time.Duration;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -154,10 +157,27 @@ public long ttl(String key) {
   }
 
   @Override
+  @Deprecated
   public List<String> keys(String pattern) {
     return commands.keys(pattern);
   }
 
+  @Override
+  public List<String> scan(String pattern) {
+    List<String> result = new ArrayList<>();
+    ScanArgs scanArgs = ScanArgs.Builder.matches(pattern).limit(100);
+
+    KeyScanCursor<String> cursor = commands.scan(scanArgs);
+    result.addAll(cursor.getKeys());
+
+    while (!cursor.isFinished()) {
+      cursor = commands.scan(cursor, scanArgs);
+      result.addAll(cursor.getKeys());
+    }
+
+    return result;
+  }
+
   @Override
   public String flushdb() {
     return commands.flushdb();

fluxgate-redis-ratelimiter/src/main/java/org/fluxgate/redis/store/RedisTokenBucketStore.java

@@ -146,8 +146,7 @@ public RedisConnectionProvider.RedisMode getMode() {
    * <p>This is used when rules are changed to reset rate limit state. The pattern matches keys
    * like: {@code fluxgate:{ruleSetId}:*}
    *
-   * <p>Warning: Uses KEYS command which can be slow on large databases. Consider using SCAN in
-   * high-traffic production environments.
+   * <p>Uses SCAN command which is production-safe (non-blocking, incremental scanning).
    *
    * @param ruleSetId the rule set ID to match
    * @return the number of buckets deleted
@@ -156,9 +155,9 @@ public long deleteBucketsByRuleSetId(String ruleSetId) {
     Objects.requireNonNull(ruleSetId, "ruleSetId must not be null");
 
     String pattern = "fluxgate:" + ruleSetId + ":*";
-    log.debug("Deleting token buckets matching pattern: {}", pattern);
+    log.debug("Scanning token buckets matching pattern: {}", pattern);
 
-    java.util.List<String> keys = connectionProvider.keys(pattern);
+    java.util.List<String> keys = connectionProvider.scan(pattern);
     if (keys.isEmpty()) {
       log.debug("No token buckets found for ruleSetId: {}", ruleSetId);
       return 0;
@@ -175,15 +174,15 @@ public long deleteBucketsByRuleSetId(String ruleSetId) {
    * <p>This is used when a full reload is triggered to reset all rate limit state. The pattern
    * matches all FluxGate keys: {@code fluxgate:*}
    *
-   * <p>Warning: Uses KEYS command which can be slow on large databases.
+   * <p>Uses SCAN command which is production-safe (non-blocking, incremental scanning).
    *
    * @return the number of buckets deleted
    */
   public long deleteAllBuckets() {
     String pattern = "fluxgate:*";
-    log.debug("Deleting all token buckets matching pattern: {}", pattern);
+    log.debug("Scanning all token buckets matching pattern: {}", pattern);
 
-    java.util.List<String> keys = connectionProvider.keys(pattern);
+    java.util.List<String> keys = connectionProvider.scan(pattern);
     if (keys.isEmpty()) {
       log.debug("No token buckets found");
       return 0;