feat: RedisOptions.familyFallback

README.md

@@ -786,6 +786,19 @@ This feature is useful when using Amazon ElastiCache instances with Auto-failove
 
 On ElastiCache instances with Auto-failover enabled, `reconnectOnError` does not execute. Instead of returning a Valkey error, AWS closes all connections to the master endpoint until the new primary node is ready. iovalkey reconnects via `retryStrategy` instead of `reconnectOnError` after about a minute. On ElastiCache instances with Auto-failover enabled, test failover events with the `Failover primary` option in the AWS console.
 
+## Family Fallback
+
+iovalkey supports family fallback, which allows the client to attempt family 4 or 6 if initial connection fails. This is enabled by default. By default alternate is false, which means it will attempt to use the other family (if `options.family = undefined or 4, it will attempt to use 6, and vice versa). If alternate is true, it will alternate between family 4 and 6, possibly leading to a lot of error logs.
+
+```js
+const redis = new Redis({
+  familyFallback: {
+    enabled: true,
+    alternate: false,
+  },
+});
+```
+
 ## Connection Events
 
 The Valkey instance will emit some events about the state of the connection to the Valkey server.

lib/Redis.ts

@@ -27,6 +27,7 @@
 import Commander from "./utils/Commander";
 import { defaults, noop } from "./utils/lodash";
 import Deque = require("denque");
+import { updateTriedFamilies, validateFamilyFallbackOptions } from "./redis/event_handler";
 const debug = Debug("redis");
 
 type RedisStatus =
@@ -179,6 +180,8 @@
 
       this.connectionEpoch += 1;
       this.setStatus("connecting");
+      validateFamilyFallbackOptions(this);
+      updateTriedFamilies(this, this.options.family as 4 | 6);
 
       const { options } = this;
 
@@ -559,35 +562,35 @@
     });
   }
 
   scanStream(options?: ScanStreamOptions) {
     return this.createScanStream("scan", { options });
   }
 
   scanBufferStream(options?: ScanStreamOptions) {
     return this.createScanStream("scanBuffer", { options });
   }
 
   sscanStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("sscan", { key, options });
   }
 
   sscanBufferStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("sscanBuffer", { key, options });
   }
 
   hscanStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("hscan", { key, options });
   }
 
   hscanBufferStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("hscanBuffer", { key, options });
   }
 
   zscanStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("zscan", { key, options });
   }
 
   zscanBufferStream(key: string, options?: ScanStreamOptions) {
     return this.createScanStream("zscanBuffer", { key, options });
   }
 
@@ -596,7 +599,7 @@
    *
    * @ignore
    */
   silentEmit(eventName: string, arg?: unknown): boolean {
     let error: unknown;
     if (eventName === "error") {
       error = arg;
@@ -631,7 +634,7 @@
   /**
    * @ignore
    */
   recoverFromFatalError(
     _commandError: Error,
     err: Error,
     options: FlushQueueOptions

lib/redis/RedisOptions.ts

@@ -5,6 +5,24 @@ import { StandaloneConnectionOptions } from "../connectors/StandaloneConnector";
 
 export type ReconnectOnError = (err: Error) => boolean | 1 | 2;
 
+export type FamilyFallback = {
+  /**
+   * If true, the client will attempt family 4 and 6 once.
+   * If false, the client will only attempt to connect using options.family or default (family: 4).
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * If true, the client will alternate between family 4 and 6.
+   * If false, the client will attempt family 4 and 6 once.
+   * @default false
+   */
+  alternate?: boolean;
+  _initialFamily?: 4 | 6;
+  _triedFamilyFour?: boolean;
+  _triedFamilySix?: boolean;
+};
+
 export interface CommonRedisOptions extends CommanderOptions {
   Connector?: ConnectorConstructor;
   retryStrategy?: (times: number) => number | void | null;
@@ -188,6 +206,21 @@ export interface CommonRedisOptions extends CommanderOptions {
     string,
     { lua: string; numberOfKeys?: number; readOnly?: boolean }
   >;
+
+  /**
+   * Allows the client to attempt family 4 or 6 if initial connection fails.
+   * @example
+   * ```js
+   * const redis = new Redis({
+   *   familyFallback: {
+   *     enabled: true,
+   *     alternate: false,
+   *   },
+   * });
+   * ```
+   * @default undefined
+   */
+  familyFallback?: FamilyFallback;
 }
 
 export type RedisOptions = CommonRedisOptions &

lib/redis/event_handler.ts

@@ -4,7 +4,9 @@ import Deque = require("denque");
 import { AbortError } from "redis-errors";
 import Command from "../Command";
 import { MaxRetriesPerRequestError } from "../errors";
+import Redis from "../Redis";
 import { CommandItem, Respondable } from "../types";
+import { FamilyFallback } from "./RedisOptions";
 import { Debug, noop, CONNECTION_CLOSED_ERROR_MSG } from "../utils";
 import DataHandler from "../DataHandler";
 
@@ -198,6 +200,7 @@ export function closeHandler(self) {
     self.setStatus("reconnecting", retryDelay);
     self.reconnectTimeout = setTimeout(function () {
       self.reconnectTimeout = null;
+      handleFamilyFallbackOptions(self);
       self.connect().catch(noop);
     }, retryDelay);
 
@@ -337,3 +340,77 @@ export function readyHandler(self) {
     }
   };
 }
+
+/**
+ * Handles the family fallback logic for reconnection attempts
+ * @param self - The Redis client instance
+ */
+export function handleFamilyFallbackOptions(self: Redis): void {
+  validateFamilyFallbackOptions(self);
+  const fallback = self.options.familyFallback;
+  if (!fallback.enabled) {
+    return;
+  }
+
+  const currentFamily = self.options.family as 4 | 6;
+  const nextFamily = getNextFamilyToTry(fallback, currentFamily);
+
+  self.options.family = nextFamily;
+  updateTriedFamilies(self, nextFamily);
+}
+
+/**
+ * Validates and normalizes the family fallback options
+ * @param self - The Redis client instance
+ * @throws {Error} If validation fails
+ */
+export function validateFamilyFallbackOptions(self: Redis) {
+  const { familyFallback: options } = self.options;
+  const initialFamily =
+    options?._initialFamily ?? (self.options.family as 4 | 6);
+
+  const fallback: FamilyFallback = {
+    enabled: true,
+    alternate: false,
+    _initialFamily: initialFamily,
+    _triedFamilyFour: false,
+    _triedFamilySix: false,
+    ...options,
+  };
+  self.options.familyFallback = fallback;
+}
+
+/**
+ * Determines the next IP family to try based on the fallback strategy
+ * @param fallback - The family fallback configuration
+ * @param currentFamily - The current IP family (4 or 6)
+ * @returns The next IP family to try (4 or 6)
+ */
+export function getNextFamilyToTry(
+  fallback: FamilyFallback,
+  currentFamily: 4 | 6
+): 4 | 6 {
+  if (fallback.alternate) {
+    return currentFamily === 4 ? 6 : 4;
+  }
+
+  if (!fallback._triedFamilyFour) return 4;
+  if (!fallback._triedFamilySix) return 6;
+
+  return fallback._initialFamily;
+}
+
+/**
+ * Updates the tried families tracking in the fallback options
+ * @param self - The Redis client instance
+ * @param family - The family that was just tried (4 or 6)
+ */
+export function updateTriedFamilies(self: Redis, family: 4 | 6): void {
+  const { familyFallback } = self.options;
+
+  if (family === 4 && !familyFallback._triedFamilyFour) {
+    familyFallback._triedFamilyFour = true;
+  } else if (family === 6 && !familyFallback._triedFamilySix) {
+    familyFallback._triedFamilySix = true;
+  }
+}