comply with default values from hld

Author: nkaradzhov

packages/client/lib/client/enterprise-maintenance-manager.ts

@@ -26,51 +26,81 @@ export interface SocketTimeoutUpdate {
   timeout?: number;
 }
 
+const DEFAULT_OPTIONS = {
+  maintPushNotifications: "auto",
+  maintMovingEndpointType: "auto",
+  maintRelaxedCommandTimeout: 1000,
+  maintRelaxedSocketTimeout: 1000,
+} as const;
+
 export const dbgMaintenance = (...args: any[]) => {
   if (!process.env.DEBUG_MAINTENANCE) return;
-  return console.log('[MNT]', ...args);
-}
+  return console.log("[MNT]", ...args);
+};
 
 export default class EnterpriseMaintenanceManager extends EventEmitter {
   #commandsQueue: RedisCommandsQueue;
   #options: RedisClientOptions;
   #isMaintenance = 0;
 
-  static async getHandshakeCommand(tls: boolean, host: string): Promise<Array<RedisArgument>> {
-    const movingEndpointType = await determineEndpoint(tls, host);
-    return ["CLIENT", "MAINT_NOTIFICATIONS", "ON", "moving-endpoint-type", movingEndpointType];
+  static async getHandshakeCommand(
+    tls: boolean,
+    host: string,
+    options: RedisClientOptions,
+  ): Promise<
+    | { cmd: Array<RedisArgument>; errorHandler: (error: Error) => void }
+    | undefined
+  > {
+    if (options.maintPushNotifications === "disabled") return;
+
+    const movingEndpointType = await determineEndpoint(tls, host, options);
+    return {
+      cmd: [
+        "CLIENT",
+        "MAINT_NOTIFICATIONS",
+        "ON",
+        "moving-endpoint-type",
+        movingEndpointType,
+      ],
+      errorHandler: (error: Error) => {
+        dbgMaintenance('handshake failed:', error);
+        if(options.maintPushNotifications === 'enabled') {
+          throw error;
+        }
+      },
+    };
   }
 
   constructor(commandsQueue: RedisCommandsQueue, options: RedisClientOptions) {
     super();
     this.#commandsQueue = commandsQueue;
-    this.#options = options;
+    this.#options = { ...DEFAULT_OPTIONS, ...options };
 
     this.#commandsQueue.addPushHandler(this.#onPush);
   }
 
   #onPush = (push: Array<any>): boolean => {
-    dbgMaintenance(push.map(item => item.toString()))
+    dbgMaintenance(push.map((item) => item.toString()));
     switch (push[0].toString()) {
       case PN.MOVING: {
         // [ 'MOVING', '17', '15', '54.78.247.156:12075' ]
         //             ^seq   ^after    ^new ip
         const afterMs = push[2];
         const url = push[3];
         const [host, port] = url.toString().split(":");
-        dbgMaintenance('Received MOVING:', afterMs, host, Number(port));
+        dbgMaintenance("Received MOVING:", afterMs, host, Number(port));
         this.#onMoving(afterMs, host, Number(port));
         return true;
       }
       case PN.MIGRATING:
       case PN.FAILING_OVER: {
-        dbgMaintenance('Received MIGRATING|FAILING_OVER');
+        dbgMaintenance("Received MIGRATING|FAILING_OVER");
         this.#onMigrating();
         return true;
       }
       case PN.MIGRATED:
       case PN.FAILED_OVER: {
-        dbgMaintenance('Received MIGRATED|FAILED_OVER');
+        dbgMaintenance("Received MIGRATED|FAILED_OVER");
         this.#onMigrated();
         return true;
       }
@@ -99,16 +129,18 @@ export default class EnterpriseMaintenanceManager extends EventEmitter {
     this.#onMigrating();
 
     // 2 [ACTION] Pause writing
-    dbgMaintenance('Pausing writing of new commands to old socket');
+    dbgMaintenance("Pausing writing of new commands to old socket");
     this.emit(MAINTENANCE_EVENTS.PAUSE_WRITING);
 
     const newSocket = new RedisSocket({
       ...this.#options.socket,
       host,
       port,
     });
-    dbgMaintenance(`Set timeout for new socket to ${this.#options.gracefulMaintenance?.relaxedSocketTimeout}`);
-    newSocket.setMaintenanceTimeout(this.#options.gracefulMaintenance?.relaxedSocketTimeout);
+    dbgMaintenance(
+      `Set timeout for new socket to ${this.#options.maintRelaxedSocketTimeout}`,
+    );
+    newSocket.setMaintenanceTimeout(this.#options.maintRelaxedSocketTimeout);
     dbgMaintenance(`Connecting to new socket: ${host}:${port}`);
     await newSocket.connect();
     dbgMaintenance(`Connected to new socket`);
@@ -120,7 +152,7 @@ export default class EnterpriseMaintenanceManager extends EventEmitter {
     // 4 [EVENT] In-flight commands completed
 
     // 5 + 6
-    dbgMaintenance('Resume writing')
+    dbgMaintenance("Resume writing");
     this.emit(MAINTENANCE_EVENTS.RESUME_WRITING, newSocket);
     this.#onMigrated();
   };
@@ -130,23 +162,23 @@ export default class EnterpriseMaintenanceManager extends EventEmitter {
     if (this.#isMaintenance > 1) {
       dbgMaintenance(`Timeout relaxation already done`);
       return;
-    };
+    }
 
     this.#commandsQueue.inMaintenance = true;
     this.#commandsQueue.setMaintenanceCommandTimeout(
-      this.#options.gracefulMaintenance?.relaxedCommandTimeout,
+      this.#options.maintRelaxedCommandTimeout,
     );
 
     this.emit(MAINTENANCE_EVENTS.TIMEOUTS_UPDATE, {
       inMaintenance: true,
-      timeout: this.#options.gracefulMaintenance?.relaxedSocketTimeout,
+      timeout: this.#options.maintRelaxedSocketTimeout,
     } satisfies SocketTimeoutUpdate);
   };
 
   #onMigrated = async () => {
     this.#isMaintenance--;
     assert(this.#isMaintenance >= 0);
-    if(this.#isMaintenance > 0) {
+    if (this.#isMaintenance > 0) {
       dbgMaintenance(`Not ready to unrelax timeouts yet`);
       return;
     }
@@ -161,11 +193,13 @@ export default class EnterpriseMaintenanceManager extends EventEmitter {
   };
 }
 
-type MovingEndpointType =
+export type MovingEndpointType =
+  | "auto"
   | "internal-ip"
   | "internal-fqdn"
   | "external-ip"
-  | "external-fqdn";
+  | "external-fqdn"
+  | "none";
 
 function isPrivateIP(ip: string): boolean {
   const version = isIP(ip);
@@ -191,20 +225,23 @@ function isPrivateIP(ip: string): boolean {
 async function determineEndpoint(
   tlsEnabled: boolean,
   host: string,
+  options: RedisClientOptions
 ): Promise<MovingEndpointType> {
-  const ip = isIP(host)
-    ? host
-    : (await lookup(host, {family: 0})).address
+
+  assert(options.maintMovingEndpointType !== undefined);
+  if (options.maintMovingEndpointType !== 'auto') return options.maintMovingEndpointType;
+
+  const ip = isIP(host) ? host : (await lookup(host, { family: 0 })).address;
 
   const isPrivate = isPrivateIP(ip);
 
-  let result: MovingEndpointType
+  let result: MovingEndpointType;
   if (tlsEnabled) {
     result = isPrivate ? "internal-fqdn" : "external-fqdn";
   } else {
     result = isPrivate ? "internal-ip" : "external-ip";
   }
 
-  dbgMaintenance(`Determine endpoint format: ${result}`)
+  dbgMaintenance(`Determine endpoint format: ${result}`);
   return result;
 }

packages/client/lib/client/index.ts

@@ -20,7 +20,7 @@ import { BasicClientSideCache, ClientSideCacheConfig, ClientSideCacheProvider }
 import { BasicCommandParser, CommandParser } from './parser';
 import SingleEntryCache from '../single-entry-cache';
 import { version } from '../../package.json'
-import EnterpriseMaintenanceManager, { MAINTENANCE_EVENTS, SocketTimeoutUpdate, dbgMaintenance } from './enterprise-maintenance-manager';
+import EnterpriseMaintenanceManager, { MAINTENANCE_EVENTS, MovingEndpointType, SocketTimeoutUpdate } from './enterprise-maintenance-manager';
 import assert from 'node:assert';
 
 export interface RedisClientOptions<
@@ -146,53 +146,46 @@ export interface RedisClientOptions<
    * Tag to append to library name that is sent to the Redis server
    */
   clientInfoTag?: string;
-
   /**
-   * Configuration for handling Redis Enterprise graceful maintenance scenarios.
+   * Controls how the client handles Redis Enterprise maintenance push notifications.
    *
-   * When Redis Enterprise performs maintenance operations, nodes will be replaced, resulting in disconnects.
-   * This configuration allows the client to handle these scenarios gracefully by automatically
-   * reconnecting and managing command execution during maintenance windows.
+   * - `disabled`: The feature is not used by the client.
+   * - `enabled`: The client attempts to enable the feature on the server. If the server responds with an error, the connection is interrupted.
+   * - `auto`: The client attempts to enable the feature on the server. If the server returns an error, the client disables the feature and continues.
    *
-   * @example Basic graceful maintenance configuration
-   * ```
-   * const client = createClient({
-   *   gracefulMaintenance: {
-   *     handleFailedCommands: 'retry',
-   *     handleTimeouts: 'exception',
-   *   }
-   * });
-   * ```
+   * The default is `auto`.
+   */
+  maintPushNotifications?: 'disabled' | 'enabled' | 'auto';
+  /**
+   * Controls how the client requests the endpoint to reconnect to during a MOVING notification in Redis Enterprise maintenance.
    *
-   * @example Graceful maintenance with timeout smoothing
-   * ```
-   * const client = createClient({
-   *   gracefulMaintenance: {
-   *     handleFailedCommands: 'retry',
-   *     handleTimeouts: 5000, // Extend timeouts to 5 seconds during maintenance
-   *   }
-   * });
-   * ```
+   * - `auto`: If the connection is opened to a name or IP address that is from/resolves to a reserved private IP range, request an internal endpoint (e.g., internal-ip), otherwise an external one. If TLS is enabled, then request a FQDN.
+   * - `internal-ip`: Enforce requesting the internal IP.
+   * - `internal-fqdn`: Enforce requesting the internal FQDN.
+   * - `external-ip`: Enforce requesting the external IP address.
+   * - `external-fqdn`: Enforce requesting the external FQDN.
+   * - `none`: Used to request a null endpoint, which tells the client to reconnect based on its current config
+
+   * The default is `auto`.
    */
-  gracefulMaintenance?: {
-    /**
-     * Designates how failed commands should be handled. A failed command is when the time isn’t sufficient to deal with the responses on the old connection before the server shuts it down
-     */
-    handleFailedCommands?: 'exception' | 'retry',
-    /**
-     * Specifies a more relaxed timeout (in milliseconds) for commands during a maintenance window.
-     * This helps minimize command timeouts during maintenance. If not provided, the `commandOptions.timeout`
-     * will be used instead. Timeouts during maintenance period result in a `CommandTimeoutDuringMaintanance` error.
-     */
-    relaxedCommandTimeout?: number,
-    /**
-     * Specifies a more relaxed timeout (in milliseconds) for the socket during a maintenance window.
-     * This helps minimize socket timeouts during maintenance. If not provided, the `socket.timeout`
-     * will be used instead. Timeouts during maintenance period result in a `SocketTimeoutDuringMaintanance` error.
-     */
-    relaxedSocketTimeout?: number
-  }
-}
+  maintMovingEndpointType?: MovingEndpointType;
+  /**
+   * Specifies a more relaxed timeout (in milliseconds) for commands during a maintenance window.
+   * This helps minimize command timeouts during maintenance. If not provided, the `commandOptions.timeout`
+   * will be used instead. Timeouts during maintenance period result in a `CommandTimeoutDuringMaintanance` error.
+   *
+   * The default is 10000
+   */
+  maintRelaxedCommandTimeout?: number;
+  /**
+   * Specifies a more relaxed timeout (in milliseconds) for the socket during a maintenance window.
+   * This helps minimize socket timeouts during maintenance. If not provided, the `socket.timeout`
+   * will be used instead. Timeouts during maintenance period result in a `SocketTimeoutDuringMaintanance` error.
+   *
+   * The default is 10000
+   */
+  maintRelaxedSocketTimeout?: number;
+};
 
 type WithCommands<
   RESP extends RespVersions,
@@ -519,15 +512,15 @@ export default class RedisClient<
     this.#queue = this.#initiateQueue();
     this.#socket = this.#createSocket(this.#options);
 
-    if(options?.gracefulMaintenance) {
+    if(options?.maintPushNotifications !== 'disabled') {
       new EnterpriseMaintenanceManager(this.#queue, this.#options!)
-        .on(MAINTENANCE_EVENTS.PAUSE_WRITING, () => this._self.#pausedForMaintenance = true )
+        .on(MAINTENANCE_EVENTS.PAUSE_WRITING, () => this._self.#pausedForMaintenance = true)
         .on(MAINTENANCE_EVENTS.RESUME_WRITING, this.#resumeFromMaintenance.bind(this))
         .on(MAINTENANCE_EVENTS.TIMEOUTS_UPDATE, (value: SocketTimeoutUpdate) => {
           this._self.#socket.inMaintenance = value.inMaintenance;
           this._self.#socket.setMaintenanceTimeout(value.timeout);
-        })
-    }
+        });
+    };
 
     if (options?.clientSideCache) {
       if (options.clientSideCache instanceof ClientSideCacheProvider) {
@@ -557,7 +550,7 @@ export default class RedisClient<
       throw new Error('Client Side Caching is only supported with RESP3');
     }
 
-    if (options?.gracefulMaintenance && options?.RESP !== 3) {
+    if (options?.maintPushNotifications !== 'disabled' && options?.RESP !== 3) {
       throw new Error('Graceful Maintenance is only supported with RESP3');
     }
 
@@ -586,9 +579,13 @@ export default class RedisClient<
     }
 
     if (options) {
+
+      if (!options.maintPushNotifications) options.maintPushNotifications = 'auto';
+
       return RedisClient.parseOptions(options);
     }
 
+
     return options;
   }
 
@@ -762,18 +759,12 @@ export default class RedisClient<
       commands.push({cmd: this.#clientSideCache.trackingOn()});
     }
 
-    if(this.#options?.gracefulMaintenance) {
-      const socket = this.#options.socket;
-      assert(socket !== undefined);
-      const { tls, host } = socket as RedisTcpSocketOptions;
-      assert(host !== undefined);
-      commands.push({
-        cmd: await EnterpriseMaintenanceManager.getHandshakeCommand(!!tls, host),
-        errorHandler: (err: Error) => {
-          dbgMaintenance("Maintenance handshake failed: ", err);
-        }
-      });
-    }
+    assert(this.#options?.socket !== undefined);
+    const { tls, host } = this.#options?.socket as RedisTcpSocketOptions;
+    const maintenanceHandshakeCmd = await EnterpriseMaintenanceManager.getHandshakeCommand(!!tls, host!, this.#options);
+    if(maintenanceHandshakeCmd) {
+      commands.push(maintenanceHandshakeCmd);
+    };
 
     return commands;
   }