feat: add timeout blocking commands (#2052)

* fix: add blockingTimeout option for blocking commands

* docs: update readme with blockingTimeout

* fix: resolve blocking commands with null on timeout instead of hanging

- Blocking commands (BLPOP, BRPOP, BZPOPMIN, XREAD, etc.) now resolve
  with `null` when their timeout expires without a response, matching
  Redis behavior and preventing indefinite hangs during undetectable
  network failures

- Added `blockingTimeout` option as a safety net for commands that
  block forever (timeout=0 / BLOCK 0)

- Automatically extracts and tracks timeout from command arguments,
  adding a 100ms grace period for finite timeouts

- Protects commands in both offline queue and command queue with
  absolute deadline tracking

- Simplified setBlockingTimeout API to resolve with null (no callback,
  no error rejection)

* refactor(command): move blocking timeout extraction to Command class

* fix: blocking timeout reamde and add more unit tests

* test: add more unit and functional tests

* feat: add configurable blockingTimeoutGrace option

---------

Co-authored-by: Pavel Pashov <pavel.pashov@redis.com>

Author: manast

README.md

@@ -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:

lib/Command.ts

@@ -9,6 +9,10 @@ import {
   convertObjectToArray,
 } from "./utils";
 import { Callback, Respondable, CommandParameter } from "./types";
+import {
+  parseBlockOption,
+  parseSecondsArgument,
+} from "./utils/argumentParsers";
 
 export type ArgumentType =
   | string
@@ -59,6 +63,32 @@ export interface CommandNameFlags {
   HANDSHAKE_COMMANDS: ["auth", "select", "client", "readonly", "info"];
   // Commands that should not trigger a reconnection when errors occur
   IGNORE_RECONNECT_ON_ERROR: ["client"];
+  // Commands that block
+  BLOCKING_COMMANDS: [
+    "blpop",
+    "brpop",
+    "brpoplpush",
+    "blmove",
+    "bzpopmin",
+    "bzpopmax",
+    "bzmpop",
+    "blmpop",
+    "xread",
+    "xreadgroup"
+  ];
+  // Commands that have timeout as the last argument
+  LAST_ARG_TIMEOUT_COMMANDS: [
+    "blpop",
+    "brpop",
+    "brpoplpush",
+    "blmove",
+    "bzpopmin",
+    "bzpopmax"
+  ];
+  // Commands that have timeout as the first argument
+  FIRST_ARG_TIMEOUT_COMMANDS: ["bzmpop", "blmpop"];
+  // Commands that have BLOCK option
+  BLOCK_OPTION_COMMANDS: ["xread", "xreadgroup"];
 }
 
 /**
@@ -101,6 +131,28 @@ export default class Command implements Respondable {
     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"],
   };
 
   private static flagMap?: FlagMap;
@@ -165,6 +217,8 @@ export default class Command implements Respondable {
   private callback: Callback;
   private transformed = false;
   private _commandTimeoutTimer?: NodeJS.Timeout;
+  private _blockingTimeoutTimer?: NodeJS.Timeout;
+  private _blockingDeadline?: number;
 
   private slot?: number | null;
   private keys?: Array<string | Buffer>;
@@ -327,6 +381,98 @@ export default class Command implements Respondable {
     }
   }
 
+  /**
+   * 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) {
+    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(): number | null | undefined {
+    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 parseSecondsArgument(args[args.length - 1]);
+    }
+
+    if (Command.checkFlag("FIRST_ARG_TIMEOUT_COMMANDS", name)) {
+      return parseSecondsArgument(args[0]);
+    }
+
+    if (Command.checkFlag("BLOCK_OPTION_COMMANDS", name)) {
+      return parseBlockOption(args);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Clear the command and blocking timers
+   */
+  private _clearTimers() {
+    const existingTimer = this._commandTimeoutTimer;
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+      delete this._commandTimeoutTimer;
+    }
+
+    const blockingTimer = this._blockingTimeoutTimer;
+    if (blockingTimer) {
+      clearTimeout(blockingTimer);
+      delete this._blockingTimeoutTimer;
+    }
+  }
+
   private initPromise() {
     const promise = new Promise((resolve, reject) => {
       if (!this.transformed) {
@@ -339,13 +485,14 @@ export default class Command implements Respondable {
       }
 
       this.resolve = this._convertValue(resolve);
-      if (this.errorStack) {
-        this.reject = (err) => {
+      this.reject = (err: Error) => {
+        this._clearTimers();
+        if (this.errorStack) {
           reject(optimizeErrorStack(err, this.errorStack.stack, __dirname));
-        };
-      } else {
-        this.reject = reject;
-      }
+        } else {
+          reject(err);
+        }
+      };
     });
 
     this.promise = asCallback(promise, this.callback);
@@ -379,12 +526,7 @@ export default class Command implements Respondable {
   private _convertValue(resolve: Function): (result: any) => void {
     return (value) => {
       try {
-        const existingTimer = this._commandTimeoutTimer;
-        if (existingTimer) {
-          clearTimeout(existingTimer);
-          delete this._commandTimeoutTimer;
-        }
-
+        this._clearTimers();
         resolve(this.transformReply(value));
         this.isResolved = true;
       } catch (err) {

lib/Redis.ts

@@ -445,6 +445,8 @@ class Redis extends Commander implements DataHandledable {
       command.setTimeout(this.options.commandTimeout);
     }
 
+    const blockingTimeout = this.getBlockingTimeoutInMs(command);
+
     let writable =
       this.status === "ready" ||
       (!stream &&
@@ -495,6 +497,18 @@ class Redis extends Commander implements DataHandledable {
         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.checkFlag("BLOCKING_COMMANDS", command.name)) {
+        const offlineTimeout =
+          this.getConfiguredBlockingTimeout() ?? blockingTimeout;
+
+        if (offlineTimeout !== undefined) {
+          command.setBlockingTimeout(offlineTimeout);
+        }
+      }
     } else {
       // @ts-expect-error
       if (debug.enabled) {
@@ -523,6 +537,10 @@ class Redis extends Commander implements DataHandledable {
         select: this.condition.select,
       });
 
+      if (blockingTimeout !== undefined) {
+        command.setBlockingTimeout(blockingTimeout);
+      }
+
       if (Command.checkFlag("WILL_DISCONNECT", command.name)) {
         this.manuallyClosing = true;
       }
@@ -544,6 +562,40 @@ class Redis extends Commander implements DataHandledable {
     return command.promise;
   }
 
+  private getBlockingTimeoutInMs(command: Command): number | undefined {
+    if (!Command.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 + (this.options.blockingTimeoutGrace ?? 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;
+  }
+
+  private getConfiguredBlockingTimeout(): number | undefined {
+    if (
+      typeof this.options.blockingTimeout === "number" &&
+      this.options.blockingTimeout > 0
+    ) {
+      return this.options.blockingTimeout;
+    }
+
+    return undefined;
+  }
+
   private setSocketTimeout() {
     this.socketTimeoutTimer = setTimeout(() => {
       this.stream.destroy(new Error(`Socket timeout. Expecting data, but didn't receive any in ${this.options.socketTimeout}ms.`));

lib/redis/RedisOptions.ts

@@ -15,6 +15,18 @@ export interface CommonRedisOptions extends CommanderOptions {
    */
   commandTimeout?: number;
 
+  /**
+   * Timeout (ms) for blocking commands with timeout=0 / BLOCK 0.
+   * When exceeded, the command resolves with null.
+   */
+  blockingTimeout?: number;
+
+  /**
+   * Grace period (ms) added to blocking command timeouts to account for network latency.
+   * @default 100
+   */
+  blockingTimeoutGrace?: number;
+
   /**
    * If the socket does not receive data within a set number of milliseconds:
    * 1. the socket is considered "dead" and will be destroyed
@@ -262,4 +274,5 @@ export const DEFAULT_REDIS_OPTIONS: RedisOptions = {
   enableAutoPipelining: false,
   autoPipeliningIgnoredCommands: [],
   sentinelMaxConnections: 10,
+  blockingTimeoutGrace: 100,
 };