feat: add credentialProvider option when creating clients

In some instances, credentials for the redis client will be short-lived and need to be
fetched on-demand when connecting to redis. This is the case when connecting in AWS using
IAM authentication or Entra ID in Azure.

This feature allows for a credentialProvider to be provided which is a callable function
returning a Promise that resolves to a username/password object.

Author: dhensby

docs/client-configuration.md

@@ -22,6 +22,7 @@
 | scripts                      |                                          | Script definitions (see [Lua Scripts](../README.md#lua-scripts))                                                                                                                                                                                    |
 | functions                    |                                          | Function definitions (see [Functions](../README.md#functions))                                                                                                                                                                                      |
 | commandsQueueMaxLength       |                                          | Maximum length of the client's internal command queue                                                                                                                                                                                               |
+| credentialSupplier           |                                          | A callable function that returns a Promise which resolves to an object with username and password properties                                                                                                                                        |
 | disableOfflineQueue          | `false`                                  | Disables offline queuing, see [FAQ](./FAQ.md#what-happens-when-the-network-goes-down)                                                                                                                                                               |
 | readonly                     | `false`                                  | Connect in [`READONLY`](https://redis.io/commands/readonly) mode                                                                                                                                                                                    |
 | legacyMode                   | `false`                                  | Maintain some backwards compatibility (see the [Migration Guide](./v3-to-v4.md))                                                                                                                                                                    |

packages/client/lib/client/index.spec.ts

@@ -1,4 +1,5 @@
 import { strict as assert } from 'node:assert';
+import { setTimeout } from 'node:timers/promises';
 import testUtils, { GLOBAL, waitTillBeenCalled } from '../test-utils';
 import RedisClient, { RedisClientType } from '.';
 import { AbortError, ClientClosedError, ClientOfflineError, ConnectionTimeoutError, DisconnectsClientError, ErrorReply, MultiErrorReply, SocketClosedUnexpectedlyError, WatchError } from '../errors';
@@ -103,6 +104,21 @@ describe('Client', () => {
       },
       minimumDockerVersion: [6, 2]
     });
+
+    testUtils.testWithClient('should accept a credentialSupplier', async client => {
+      assert.equal(
+          await client.ping(),
+          'PONG'
+      );
+    }, {
+      ...GLOBAL.SERVERS.PASSWORD,
+      clientOptions: {
+        // simulate a slight pause to fetch the credentials
+        credentialSupplier: () => setTimeout(50).then(() => Promise.resolve({
+          ...GLOBAL.SERVERS.PASSWORD.clientOptions,
+        })),
+      }
+    });
   });
 
   testUtils.testWithClient('should set connection name', async client => {

packages/client/lib/client/index.ts

@@ -11,12 +11,15 @@ import { Command, CommandSignature, TypeMapping, CommanderConfig, RedisFunction,
 import RedisClientMultiCommand, { RedisClientMultiCommandType } from './multi-command';
 import { RedisMultiQueuedCommand } from '../multi-command';
 import HELLO, { HelloOptions } from '../commands/HELLO';
+import { AuthOptions } from '../commands/AUTH';
 import { ScanOptions, ScanCommonOptions } from '../commands/SCAN';
 import { RedisLegacyClient, RedisLegacyClientType } from './legacy-mode';
 import { RedisPoolOptions, RedisClientPool } from './pool';
 import { RedisVariadicArgument, parseArgs, pushVariadicArguments } from '../commands/generic-transformers';
 import { BasicCommandParser, CommandParser } from './parser';
 
+export type RedisCredentialSupplier = () => Promise<AuthOptions>;
+
 export interface RedisClientOptions<
   M extends RedisModules = RedisModules,
   F extends RedisFunctions = RedisFunctions,
@@ -34,6 +37,10 @@ export interface RedisClientOptions<
    * Socket connection properties
    */
   socket?: SocketOptions;
+  /**
+   * Credential supplier callback function
+   */
+  credentialSupplier?: RedisCredentialSupplier;
   /**
    * ACL username ([see ACL guide](https://redis.io/topics/acl))
    */
@@ -276,6 +283,7 @@ export default class RedisClient<
   readonly #options?: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>;
   readonly #socket: RedisSocket;
   readonly #queue: RedisCommandsQueue;
+  #credentialSupplier?: RedisCredentialSupplier;
   #selectedDB = 0;
   #monitorCallback?: MonitorCallback<TYPE_MAPPING>;
   private _self = this;
@@ -334,6 +342,13 @@ export default class RedisClient<
       this._commandOptions = options.commandOptions;
     }
 
+    // if a credential supplier has been provided, use it, otherwise create a provider from the
+    // supplier username and password (if provided), otherwise leave it undefined
+    this.#credentialSupplier = options?.credentialSupplier ?? ((options?.username || options?.password) ? () => Promise.resolve({
+      username: options?.username,
+      password: options?.password ?? '',
+    }) : undefined);
+
     return options;
   }
 
@@ -345,16 +360,16 @@ export default class RedisClient<
     );
   }
 
-  #handshake(selectedDB: number) {
+  #handshake(selectedDB: number, credential?: AuthOptions) {
     const commands = [];
 
     if (this.#options?.RESP) {
       const hello: HelloOptions = {};
 
-      if (this.#options.password) {
+      if (credential?.password) {
         hello.AUTH = {
-          username: this.#options.username ?? 'default',
-          password: this.#options.password
+          username: credential?.username ?? 'default',
+          password: credential?.password
         };
       }
 
@@ -366,11 +381,11 @@ export default class RedisClient<
         parseArgs(HELLO, this.#options.RESP, hello)
       );
     } else {
-      if (this.#options?.username || this.#options?.password) {
+      if (credential) {
         commands.push(
           parseArgs(COMMANDS.AUTH, {
-            username: this.#options.username,
-            password: this.#options.password ?? ''
+            username: credential.username,
+            password: credential.password ?? ''
           })
         );
       }
@@ -396,7 +411,11 @@ export default class RedisClient<
   }
 
   #initiateSocket(): RedisSocket {
-    const socketInitiator = () => {
+    const socketInitiator = async () => {
+      // we have to call the credential fetch before pushing any commands into the queue,
+      // so fetch the credentials before doing anything else.
+      const credential: AuthOptions | undefined = await this.#credentialSupplier?.();
+
       const promises = [],
         chainId = Symbol('Socket Initiator');
 
@@ -418,7 +437,7 @@ export default class RedisClient<
         );
       }
 
-      const commands = this.#handshake(this.#selectedDB);
+      const commands = this.#handshake(this.#selectedDB, credential);
       for (let i = commands.length - 1; i >= 0; --i) {
         promises.push(
           this.#queue.addCommand(commands[i], {
@@ -997,10 +1016,11 @@ export default class RedisClient<
    * Reset the client to its default state (i.e. stop PubSub, stop monitoring, select default DB, etc.)
    */
   async reset() {
+    const credential: AuthOptions | undefined = await this.#credentialSupplier?.();
     const chainId = Symbol('Reset Chain'),
       promises = [this._self.#queue.reset(chainId)],
       selectedDB = this._self.#options?.database ?? 0;
-    for (const command of this._self.#handshake(selectedDB)) {
+    for (const command of this._self.#handshake(selectedDB, credential)) {
       promises.push(
         this._self.#queue.addCommand(command, {
           chainId