ioredis 5.8.1 → 5.9.0

package/README.md

@@ -21,7 +21,7 @@ ioredis is a stable project and maintenance is done on a best-effort basis for r
 ioredis is a robust, full-featured Redis client that is
 used in the world's biggest online commerce company [Alibaba](http://www.alibaba.com/) and many other awesome companies.
 
-0. Full-featured. It supports [Cluster](http://redis.io/topics/cluster-tutorial), [Sentinel](https://redis.io/docs/reference/sentinel-clients), [Streams](https://redis.io/topics/streams-intro), [Pipelining](http://redis.io/topics/pipelining), and of course [Lua scripting](http://redis.io/commands/eval), [Redis Functions](https://redis.io/topics/functions-intro), [Pub/Sub](http://redis.io/topics/pubsub) (with the support of binary messages).
+0. Full-featured. It supports [Cluster](http://redis.io/topics/cluster-tutorial), [Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/), [Streams](https://redis.io/topics/streams-intro), [Pipelining](http://redis.io/topics/pipelining), and of course [Lua scripting](http://redis.io/commands/eval), [Redis Functions](https://redis.io/topics/functions-intro), [Pub/Sub](http://redis.io/topics/pubsub) (with the support of binary messages).
 1. High performance 🚀.
 2. Delightful API 😄. It works with Node callbacks and Native promises.
 3. Transformation of command arguments and replies.
@@ -798,6 +798,20 @@ const redis = new Redis({
 
 Set maxRetriesPerRequest to `null` to disable this behavior, and every command will wait forever until the connection is alive again (which is the default behavior before ioredis v4).
 
+### Blocking Command Timeout
+
+ioredis can apply a client-side timeout to blocking commands (such as `blpop`, `brpop`, `bzpopmin`, `bzmpop`, `blmpop`, `xread`, `xreadgroup`, etc.). This protects against scenarios where the TCP connection becomes a zombie (e.g., due to a silent network failure like a Docker network disconnect) and Redis never replies.
+
+For commands with a finite timeout (e.g., `blpop("key", 5)`), ioredis automatically sets a client-side deadline based on the command's timeout plus a small grace period. If no reply arrives before the deadline, the command resolves with `null`—the same value Redis returns when a blocking command times out normally.
+
+For commands that intentionally block forever (e.g., `timeout = 0` or `BLOCK 0`), you can provide a safety net via the optional `blockingTimeout` option (milliseconds):
+
+```javascript
+const redis = new Redis({
+  blockingTimeout: 30000, // Resolve with null after 30 seconds when timeout=0/BLOCK 0
+});
+```
+
 ### Reconnect on Error
 
 Besides auto-reconnect when the connection is closed, ioredis supports reconnecting on certain Redis errors using the `reconnectOnError` option. Here's an example that will reconnect when receiving `READONLY` error:
@@ -1213,7 +1227,7 @@ cluster.on("smessage", (channel, message) => {
     console.log(message);
 });
 
-        
+
 //Subscribe to the channels on the same slot
 cluster.ssubscribe("channel{my}:1", "channel{my}:2").then( ( count: number ) => {
     console.log(count);

package/built/Command.d.ts

@@ -30,6 +30,30 @@ export interface CommandNameFlags {
     ENTER_SUBSCRIBER_MODE: ["subscribe", "psubscribe", "ssubscribe"];
     EXIT_SUBSCRIBER_MODE: ["unsubscribe", "punsubscribe", "sunsubscribe"];
     WILL_DISCONNECT: ["quit"];
+    HANDSHAKE_COMMANDS: ["auth", "select", "client", "readonly", "info"];
+    IGNORE_RECONNECT_ON_ERROR: ["client"];
+    BLOCKING_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+        "bzmpop",
+        "blmpop",
+        "xread",
+        "xreadgroup"
+    ];
+    LAST_ARG_TIMEOUT_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax"
+    ];
+    FIRST_ARG_TIMEOUT_COMMANDS: ["bzmpop", "blmpop"];
+    BLOCK_OPTION_COMMANDS: ["xread", "xreadgroup"];
 }
 /**
  * Command instance
@@ -80,6 +104,8 @@ export default class Command implements Respondable {
     private callback;
     private transformed;
     private _commandTimeoutTimer?;
+    private _blockingTimeoutTimer?;
+    private _blockingDeadline?;
     private slot?;
     private keys?;
     /**
@@ -108,6 +134,24 @@ export default class Command implements Respondable {
      * and generating an error.
      */
     setTimeout(ms: number): void;
+    /**
+     * Set a timeout for blocking commands.
+     * When the timeout expires, the command resolves with null (matching Redis behavior).
+     * This handles the case of undetectable network failures (e.g., docker network disconnect)
+     * where the TCP connection becomes a zombie and no close event fires.
+     */
+    setBlockingTimeout(ms: number): void;
+    /**
+     * Extract the blocking timeout from the command arguments.
+     *
+     * @returns The timeout in seconds, null for indefinite blocking (timeout of 0),
+     *          or undefined if this is not a blocking command
+     */
+    extractBlockingTimeout(): number | null | undefined;
+    /**
+     * Clear the command and blocking timers
+     */
+    private _clearTimers;
     private initPromise;
     /**
      * Iterate through the command arguments that are considered keys.

package/built/Command.js

@@ -4,6 +4,7 @@ const commands_1 = require("@ioredis/commands");
 const calculateSlot = require("cluster-key-slot");
 const standard_as_callback_1 = require("standard-as-callback");
 const utils_1 = require("./utils");
+const argumentParsers_1 = require("./utils/argumentParsers");
 /**
  * Command instance
  *
@@ -72,6 +73,7 @@ class Command {
      * Check whether the command has the flag
      */
     static checkFlag(flagName, commandName) {
+        commandName = commandName.toLowerCase();
         return !!this.getFlagMap()[flagName][commandName];
     }
     static setArgumentTransformer(name, func) {
@@ -194,6 +196,81 @@ class Command {
             }, ms);
         }
     }
+    /**
+     * Set a timeout for blocking commands.
+     * When the timeout expires, the command resolves with null (matching Redis behavior).
+     * This handles the case of undetectable network failures (e.g., docker network disconnect)
+     * where the TCP connection becomes a zombie and no close event fires.
+     */
+    setBlockingTimeout(ms) {
+        if (ms <= 0) {
+            return;
+        }
+        // Clear existing timer if any (can happen when command moves from offline to command queue)
+        if (this._blockingTimeoutTimer) {
+            clearTimeout(this._blockingTimeoutTimer);
+            this._blockingTimeoutTimer = undefined;
+        }
+        const now = Date.now();
+        // First call: establish absolute deadline
+        if (this._blockingDeadline === undefined) {
+            this._blockingDeadline = now + ms;
+        }
+        // Check if we've already exceeded the deadline
+        const remaining = this._blockingDeadline - now;
+        if (remaining <= 0) {
+            // Resolve with null to indicate timeout (same as Redis behavior)
+            this.resolve(null);
+            return;
+        }
+        this._blockingTimeoutTimer = setTimeout(() => {
+            if (this.isResolved) {
+                this._blockingTimeoutTimer = undefined;
+                return;
+            }
+            this._blockingTimeoutTimer = undefined;
+            // Timeout expired - resolve with null (same as Redis behavior when blocking command times out)
+            this.resolve(null);
+        }, remaining);
+    }
+    /**
+     * Extract the blocking timeout from the command arguments.
+     *
+     * @returns The timeout in seconds, null for indefinite blocking (timeout of 0),
+     *          or undefined if this is not a blocking command
+     */
+    extractBlockingTimeout() {
+        const args = this.args;
+        if (!args || args.length === 0) {
+            return undefined;
+        }
+        const name = this.name.toLowerCase();
+        if (Command.checkFlag("LAST_ARG_TIMEOUT_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseSecondsArgument)(args[args.length - 1]);
+        }
+        if (Command.checkFlag("FIRST_ARG_TIMEOUT_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseSecondsArgument)(args[0]);
+        }
+        if (Command.checkFlag("BLOCK_OPTION_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseBlockOption)(args);
+        }
+        return undefined;
+    }
+    /**
+     * Clear the command and blocking timers
+     */
+    _clearTimers() {
+        const existingTimer = this._commandTimeoutTimer;
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+            delete this._commandTimeoutTimer;
+        }
+        const blockingTimer = this._blockingTimeoutTimer;
+        if (blockingTimer) {
+            clearTimeout(blockingTimer);
+            delete this._blockingTimeoutTimer;
+        }
+    }
     initPromise() {
         const promise = new Promise((resolve, reject) => {
             if (!this.transformed) {
@@ -205,14 +282,15 @@ class Command {
                 this.stringifyArguments();
             }
             this.resolve = this._convertValue(resolve);
-            if (this.errorStack) {
-                this.reject = (err) => {
+            this.reject = (err) => {
+                this._clearTimers();
+                if (this.errorStack) {
                     reject((0, utils_1.optimizeErrorStack)(err, this.errorStack.stack, __dirname));
-                };
-            }
-            else {
-                this.reject = reject;
-            }
+                }
+                else {
+                    reject(err);
+                }
+            };
         });
         this.promise = (0, standard_as_callback_1.default)(promise, this.callback);
     }
@@ -222,9 +300,11 @@ class Command {
     _iterateKeys(transform = (key) => key) {
         if (typeof this.keys === "undefined") {
             this.keys = [];
-            if ((0, commands_1.exists)(this.name)) {
+            if ((0, commands_1.exists)(this.name, { caseInsensitive: true })) {
                 // @ts-expect-error
-                const keyIndexes = (0, commands_1.getKeyIndexes)(this.name, this.args);
+                const keyIndexes = (0, commands_1.getKeyIndexes)(this.name, this.args, {
+                    nameCaseInsensitive: true,
+                });
                 for (const index of keyIndexes) {
                     this.args[index] = transform(this.args[index]);
                     this.keys.push(this.args[index]);
@@ -239,11 +319,7 @@ class Command {
     _convertValue(resolve) {
         return (value) => {
             try {
-                const existingTimer = this._commandTimeoutTimer;
-                if (existingTimer) {
-                    clearTimeout(existingTimer);
-                    delete this._commandTimeoutTimer;
-                }
+                this._clearTimers();
                 resolve(this.transformReply(value));
                 this.isResolved = true;
             }
@@ -270,6 +346,30 @@ Command.FLAGS = {
     ENTER_SUBSCRIBER_MODE: ["subscribe", "psubscribe", "ssubscribe"],
     EXIT_SUBSCRIBER_MODE: ["unsubscribe", "punsubscribe", "sunsubscribe"],
     WILL_DISCONNECT: ["quit"],
+    HANDSHAKE_COMMANDS: ["auth", "select", "client", "readonly", "info"],
+    IGNORE_RECONNECT_ON_ERROR: ["client"],
+    BLOCKING_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+        "bzmpop",
+        "blmpop",
+        "xread",
+        "xreadgroup",
+    ],
+    LAST_ARG_TIMEOUT_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+    ],
+    FIRST_ARG_TIMEOUT_COMMANDS: ["bzmpop", "blmpop"],
+    BLOCK_OPTION_COMMANDS: ["xread", "xreadgroup"],
 };
 Command._transformer = {
     argument: {},

package/built/Pipeline.js

@@ -101,7 +101,8 @@ class Pipeline extends Commander_1.default {
                     }
                 }
                 else if (!command.inTransaction) {
-                    const isReadOnly = (0, commands_1.exists)(command.name) && (0, commands_1.hasFlag)(command.name, "readonly");
+                    const isReadOnly = (0, commands_1.exists)(command.name, { caseInsensitive: true }) &&
+                        (0, commands_1.hasFlag)(command.name, "readonly", { nameCaseInsensitive: true });
                     if (!isReadOnly) {
                         retriable = false;
                         break;

package/built/Redis.d.ts

@@ -161,6 +161,8 @@ declare class Redis extends Commander implements DataHandledable {
      * @ignore
      */
     sendCommand(command: Command, stream?: WriteableStream): unknown;
+    private getBlockingTimeoutInMs;
+    private getConfiguredBlockingTimeout;
     private setSocketTimeout;
     scanStream(options?: ScanStreamOptions): ScanStream;
     scanBufferStream(options?: ScanStreamOptions): ScanStream;

package/built/Redis.js

@@ -325,7 +325,7 @@ class Redis extends Commander_1.default {
      * @ignore
      */
     sendCommand(command, stream) {
-        var _a, _b;
+        var _a, _b, _c;
         if (this.status === "wait") {
             this.connect().catch(lodash_1.noop);
         }
@@ -341,11 +341,13 @@ class Redis extends Commander_1.default {
         if (typeof this.options.commandTimeout === "number") {
             command.setTimeout(this.options.commandTimeout);
         }
+        const blockingTimeout = this.getBlockingTimeoutInMs(command);
         let writable = this.status === "ready" ||
             (!stream &&
                 this.status === "connect" &&
-                (0, commands_1.exists)(command.name) &&
-                (0, commands_1.hasFlag)(command.name, "loading"));
+                (0, commands_1.exists)(command.name, { caseInsensitive: true }) &&
+                ((0, commands_1.hasFlag)(command.name, "loading", { nameCaseInsensitive: true }) ||
+                    Command_1.default.checkFlag("HANDSHAKE_COMMANDS", command.name)));
         if (!this.stream) {
             writable = false;
         }
@@ -377,11 +379,20 @@ class Redis extends Commander_1.default {
                 stream: stream,
                 select: this.condition.select,
             });
+            // For blocking commands, set a timeout while queued to ensure they don't wait forever
+            // if connection never becomes ready (e.g., docker network disconnect scenario)
+            // Use blockingTimeout if configured, otherwise fall back to the command's own timeout
+            if (Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
+                const offlineTimeout = (_b = this.getConfiguredBlockingTimeout()) !== null && _b !== void 0 ? _b : blockingTimeout;
+                if (offlineTimeout !== undefined) {
+                    command.setBlockingTimeout(offlineTimeout);
+                }
+            }
         }
         else {
             // @ts-expect-error
             if (debug.enabled) {
-                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_b = this.condition) === null || _b === void 0 ? void 0 : _b.select, command.name, command.args);
+                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_c = this.condition) === null || _c === void 0 ? void 0 : _c.select, command.name, command.args);
             }
             if (stream) {
                 if ("isPipeline" in stream && stream.isPipeline) {
@@ -399,6 +410,9 @@ class Redis extends Commander_1.default {
                 stream: stream,
                 select: this.condition.select,
             });
+            if (blockingTimeout !== undefined) {
+                command.setBlockingTimeout(blockingTimeout);
+            }
             if (Command_1.default.checkFlag("WILL_DISCONNECT", command.name)) {
                 this.manuallyClosing = true;
             }
@@ -416,6 +430,33 @@ class Redis extends Commander_1.default {
         }
         return command.promise;
     }
+    getBlockingTimeoutInMs(command) {
+        var _a;
+        if (!Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
+            return undefined;
+        }
+        const timeout = command.extractBlockingTimeout();
+        if (typeof timeout === "number") {
+            if (timeout > 0) {
+                // Finite timeout from command args - add grace period
+                return timeout + ((_a = this.options.blockingTimeoutGrace) !== null && _a !== void 0 ? _a : RedisOptions_1.DEFAULT_REDIS_OPTIONS.blockingTimeoutGrace);
+            }
+            // Command has timeout=0 (block forever), use blockingTimeout option as safety net
+            return this.getConfiguredBlockingTimeout();
+        }
+        if (timeout === null) {
+            // No BLOCK option found (e.g., XREAD without BLOCK), use blockingTimeout as safety net
+            return this.getConfiguredBlockingTimeout();
+        }
+        return undefined;
+    }
+    getConfiguredBlockingTimeout() {
+        if (typeof this.options.blockingTimeout === "number" &&
+            this.options.blockingTimeout > 0) {
+            return this.options.blockingTimeout;
+        }
+        return undefined;
+    }
     setSocketTimeout() {
         this.socketTimeoutTimer = setTimeout(() => {
             this.stream.destroy(new Error(`Socket timeout. Expecting data, but didn't receive any in ${this.options.socketTimeout}ms.`));
@@ -501,7 +542,8 @@ class Redis extends Commander_1.default {
     handleReconnection(err, item) {
         var _a;
         let needReconnect = false;
-        if (this.options.reconnectOnError) {
+        if (this.options.reconnectOnError &&
+            !Command_1.default.checkFlag("IGNORE_RECONNECT_ON_ERROR", item.command.name)) {
             needReconnect = this.options.reconnectOnError(err);
         }
         switch (needReconnect) {

package/built/autoPipelining.js

@@ -19,6 +19,7 @@ exports.notAllowedAutoPipelineCommands = [
     "unsubscribe",
     "unpsubscribe",
     "select",
+    "client",
 ];
 function executeAutoPipeline(client, slotKey) {
     /*

package/built/cluster/ClusterSubscriberGroup.d.ts

@@ -1,37 +1,39 @@
 /// <reference types="node" />
-import ClusterSubscriber from "./ClusterSubscriber";
-import Cluster from "./index";
+import * as EventEmitter from "events";
+import ShardedSubscriber from "./ShardedSubscriber";
 /**
- * Redis differs between "normal" and sharded PubSub. If using the "normal" PubSub feature, exactly one
- * ClusterSubscriber exists per cluster instance. This works because the Redis cluster bus forwards m
- * messages between shards. However, this has scalability limitations, which is the reason why the sharded
- * PubSub feature was added to Redis. With sharded PubSub, each shard is responsible for its own messages.
- * Given that, we need at least one ClusterSubscriber per master endpoint/node.
+ * Redis distinguishes between "normal" and sharded PubSub. When using the normal PubSub feature,
+ * exactly one subscriber exists per cluster instance because the Redis cluster bus forwards
+ * messages between shards. Sharded PubSub removes this limitation by making each shard
+ * responsible for its own messages.
  *
- * This class leverages the previously exising ClusterSubscriber by adding support for multiple such subscribers
- * in alignment to the master nodes of the cluster. The ClusterSubscriber class was extended in a non-breaking way
- * to support this feature.
+ * This class coordinates one ShardedSubscriber per master node in the cluster, providing
+ * sharded PubSub support while keeping the public API backward compatible.
  */
 export default class ClusterSubscriberGroup {
-    private cluster;
+    private readonly subscriberGroupEmitter;
     private shardedSubscribers;
     private clusterSlots;
     private subscriberToSlotsIndex;
     private channels;
+    private failedAttemptsByNode;
+    private isResetting;
+    private pendingReset;
+    private static readonly MAX_RETRY_ATTEMPTS;
+    private static readonly MAX_BACKOFF_MS;
+    private static readonly BASE_BACKOFF_MS;
     /**
      * Register callbacks
      *
      * @param cluster
      */
-    constructor(cluster: Cluster, refreshSlotsCacheCallback: () => void);
+    constructor(subscriberGroupEmitter: EventEmitter);
     /**
      * Get the responsible subscriber.
      *
-     * Returns null if no subscriber was found
-     *
      * @param slot
      */
-    getResponsibleSubscriber(slot: number): ClusterSubscriber;
+    getResponsibleSubscriber(slot: number): ShardedSubscriber | undefined;
     /**
      * Adds a channel for which this subscriber group is responsible
      *
@@ -50,24 +52,17 @@ export default class ClusterSubscriberGroup {
     /**
      * Start all not yet started subscribers
      */
-    start(): void;
-    /**
-     * Add a subscriber to the group of subscribers
-     *
-     * @param redis
-     */
-    private _addSubscriber;
+    start(): Promise<any[]>;
     /**
-     * Removes a subscriber from the group
-     * @param redis
+     * Resets the subscriber group by disconnecting all subscribers that are no longer needed and connecting new ones.
      */
-    private _removeSubscriber;
+    reset(clusterSlots: string[][], clusterNodes: any[]): Promise<void>;
     /**
      * Refreshes the subscriber-related slot ranges
      *
      * Returns false if no refresh was needed
      *
-     * @param cluster
+     * @param targetSlots
      */
     private _refreshSlots;
     /**
@@ -83,4 +78,28 @@ export default class ClusterSubscriberGroup {
      * @private
      */
     private _slotsAreEqual;
+    /**
+     * Checks if any subscribers are in an unhealthy state.
+     *
+     * A subscriber is considered unhealthy if:
+     * - It exists but is not started (failed/disconnected)
+     * - It's missing entirely for a node that should have one
+     *
+     * @returns true if any subscribers need to be recreated
+     */
+    private hasUnhealthySubscribers;
+    /**
+     * Handles failed subscriber connections by emitting an event to refresh the slots cache
+     * after a backoff period.
+     *
+     * @param error
+     * @param nodeKey
+     */
+    private handleSubscriberConnectFailed;
+    /**
+     * Handles successful subscriber connections by resetting the failed attempts counter.
+     *
+     * @param nodeKey
+     */
+    private handleSubscriberConnectSucceeded;
 }