Merge pull request #3563 from iclanton/runWithRetriesAsync

[node-core-library] Add an Async.runWithRetriesAsync API to run and a retry an async function that may intermittently fail.

Author: iclanton

common/changes/@rushstack/node-core-library/runWithRetriesAsync_2022-08-01-01-22.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "Add an Async.runWithRetriesAsync() API to run and a retry an async function that may intermittently fail.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library"
+}

common/reviews/api/node-core-library.api.md

@@ -33,6 +33,7 @@ export class AnsiEscape {
 export class Async {
     static forEachAsync<TEntry>(iterable: Iterable<TEntry> | AsyncIterable<TEntry>, callback: (entry: TEntry, arrayIndex: number) => Promise<void>, options?: IAsyncParallelismOptions | undefined): Promise<void>;
     static mapAsync<TEntry, TRetVal>(iterable: Iterable<TEntry> | AsyncIterable<TEntry>, callback: (entry: TEntry, arrayIndex: number) => Promise<TRetVal>, options?: IAsyncParallelismOptions | undefined): Promise<TRetVal[]>;
+    static runWithRetriesAsync<TResult>({ action, maxRetries, retryDelayMs }: IRunWithRetriesOptions<TResult>): Promise<TResult>;
     static sleep(ms: number): Promise<void>;
 }
 
@@ -595,6 +596,16 @@ export interface IProtectableMapParameters<K, V> {
     onSet?: (source: ProtectableMap<K, V>, key: K, value: V) => V;
 }
 
+// @beta (undocumented)
+export interface IRunWithRetriesOptions<TResult> {
+    // (undocumented)
+    action: () => Promise<TResult> | TResult;
+    // (undocumented)
+    maxRetries: number;
+    // (undocumented)
+    retryDelayMs?: number;
+}
+
 // @beta (undocumented)
 export interface IStringBufferOutputOptions {
     normalizeSpecialCharacters: boolean;

libraries/node-core-library/src/Async.ts

@@ -17,6 +17,18 @@ export interface IAsyncParallelismOptions {
   concurrency?: number;
 }
 
+/**
+ * @remarks
+ * Used with {@link Async.runWithRetriesAsync}.
+ *
+ * @beta
+ */
+export interface IRunWithRetriesOptions<TResult> {
+  action: () => Promise<TResult> | TResult;
+  maxRetries: number;
+  retryDelayMs?: number;
+}
+
 /**
  * Utilities for parallel asynchronous operations, for use with the system `Promise` APIs.
  *
@@ -154,4 +166,27 @@ export class Async {
       setTimeout(resolve, ms);
     });
   }
+
+  /**
+   * Executes an async function and optionally retries it if it fails.
+   */
+  public static async runWithRetriesAsync<TResult>({
+    action,
+    maxRetries,
+    retryDelayMs = 0
+  }: IRunWithRetriesOptions<TResult>): Promise<TResult> {
+    let retryCounter: number = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      try {
+        return await action();
+      } catch (e) {
+        if (++retryCounter > maxRetries) {
+          throw e;
+        } else if (retryDelayMs > 0) {
+          await Async.sleep(retryDelayMs);
+        }
+      }
+    }
+  }
 }

libraries/node-core-library/src/index.ts

@@ -9,7 +9,7 @@
 
 export { AlreadyReportedError } from './AlreadyReportedError';
 export { AnsiEscape, IAnsiEscapeConvertForTestsOptions } from './Terminal/AnsiEscape';
-export { Async, IAsyncParallelismOptions } from './Async';
+export { Async, IAsyncParallelismOptions, IRunWithRetriesOptions } from './Async';
 export { Brand } from './PrimitiveTypes';
 export { FileConstants, FolderConstants } from './Constants';
 export { Enum } from './Enum';

libraries/node-core-library/src/test/Async.test.ts

@@ -313,4 +313,149 @@ describe(Async.name, () => {
       ).rejects.toThrow(expectedError);
     });
   });
+
+  describe(Async.runWithRetriesAsync.name, () => {
+    it('Correctly handles a sync function that succeeds the first time', async () => {
+      const expectedResult: string = 'RESULT';
+      const result: string = await Async.runWithRetriesAsync({ action: () => expectedResult, maxRetries: 0 });
+      expect(result).toEqual(expectedResult);
+    });
+
+    it('Correctly handles an async function that succeeds the first time', async () => {
+      const expectedResult: string = 'RESULT';
+      const result: string = await Async.runWithRetriesAsync({
+        action: async () => expectedResult,
+        maxRetries: 0
+      });
+      expect(result).toEqual(expectedResult);
+    });
+
+    it('Correctly handles a sync function that throws and does not allow retries', async () => {
+      await expect(
+        async () =>
+          await Async.runWithRetriesAsync({
+            action: () => {
+              throw new Error('error');
+            },
+            maxRetries: 0
+          })
+      ).rejects.toThrowErrorMatchingSnapshot();
+    });
+
+    it('Correctly handles an async function that throws and does not allow retries', async () => {
+      await expect(
+        async () =>
+          await Async.runWithRetriesAsync({
+            action: async () => {
+              throw new Error('error');
+            },
+            maxRetries: 0
+          })
+      ).rejects.toThrowErrorMatchingSnapshot();
+    });
+
+    it('Correctly handles a sync function that always throws and allows several retries', async () => {
+      await expect(
+        async () =>
+          await Async.runWithRetriesAsync({
+            action: () => {
+              throw new Error('error');
+            },
+            maxRetries: 5
+          })
+      ).rejects.toThrowErrorMatchingSnapshot();
+    });
+
+    it('Correctly handles an async function that always throws and allows several retries', async () => {
+      await expect(
+        async () =>
+          await Async.runWithRetriesAsync({
+            action: async () => {
+              throw new Error('error');
+            },
+            maxRetries: 5
+          })
+      ).rejects.toThrowErrorMatchingSnapshot();
+    });
+
+    it('Correctly handles a sync function that throws once and then succeeds', async () => {
+      const expectedResult: string = 'RESULT';
+      let callCount: number = 0;
+      const result: string = await Async.runWithRetriesAsync({
+        action: () => {
+          if (callCount++ === 0) {
+            throw new Error('error');
+          } else {
+            return expectedResult;
+          }
+        },
+        maxRetries: 1
+      });
+      expect(result).toEqual(expectedResult);
+    });
+
+    it('Correctly handles an async function that throws once and then succeeds', async () => {
+      const expectedResult: string = 'RESULT';
+      let callCount: number = 0;
+      const result: string = await Async.runWithRetriesAsync({
+        action: () => {
+          if (callCount++ === 0) {
+            throw new Error('error');
+          } else {
+            return expectedResult;
+          }
+        },
+        maxRetries: 1
+      });
+      expect(result).toEqual(expectedResult);
+    });
+
+    it('Correctly handles a sync function that throws once and then succeeds with a timeout', async () => {
+      const expectedResult: string = 'RESULT';
+      let callCount: number = 0;
+      const sleepSpy: jest.SpyInstance = jest
+        .spyOn(Async, 'sleep')
+        .mockImplementation(() => Promise.resolve());
+
+      const resultPromise: Promise<string> = Async.runWithRetriesAsync({
+        action: () => {
+          if (callCount++ === 0) {
+            throw new Error('error');
+          } else {
+            return expectedResult;
+          }
+        },
+        maxRetries: 1,
+        retryDelayMs: 5
+      });
+
+      expect(await resultPromise).toEqual(expectedResult);
+      expect(sleepSpy).toHaveBeenCalledTimes(1);
+      expect(sleepSpy).toHaveBeenLastCalledWith(5);
+    });
+
+    it('Correctly handles an async function that throws once and then succeeds with a timeout', async () => {
+      const expectedResult: string = 'RESULT';
+      let callCount: number = 0;
+      const sleepSpy: jest.SpyInstance = jest
+        .spyOn(Async, 'sleep')
+        .mockImplementation(() => Promise.resolve());
+
+      const resultPromise: Promise<string> = Async.runWithRetriesAsync({
+        action: async () => {
+          if (callCount++ === 0) {
+            throw new Error('error');
+          } else {
+            return expectedResult;
+          }
+        },
+        maxRetries: 1,
+        retryDelayMs: 5
+      });
+
+      expect(await resultPromise).toEqual(expectedResult);
+      expect(sleepSpy).toHaveBeenCalledTimes(1);
+      expect(sleepSpy).toHaveBeenLastCalledWith(5);
+    });
+  });
 });

libraries/node-core-library/src/test/__snapshots__/Async.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Async runWithRetriesAsync Correctly handles a sync function that always throws and allows several retries 1`] = `"error"`;
+
+exports[`Async runWithRetriesAsync Correctly handles a sync function that throws and does not allow retries 1`] = `"error"`;
+
+exports[`Async runWithRetriesAsync Correctly handles an async function that always throws and allows several retries 1`] = `"error"`;
+
+exports[`Async runWithRetriesAsync Correctly handles an async function that throws and does not allow retries 1`] = `"error"`;