[core-lro] add a flag to control whether to throw when the operation is unsuccessful (Azure#23311)

Adds `resolveOnUnsuccessful` flag that controls whether to throw an error if the operation failed or was canceled. This flag is turned off by default but REST-level clients should turn it on to maintain the direction of not raising exceptions when receiving unexpected responses.

Author: deyaaeldeen

sdk/core/core-lro/CHANGELOG.md

@@ -1,9 +1,11 @@
 # Release History
 
-## 2.3.2 (Unreleased)
+## 2.4.0 (Unreleased)
 
 ### Features Added
 
+- Add `resolveOnUnsuccessful` to `CreatePollerOptions` and `LroEngineOptions` to control whether to throw an error if the operation failed or was canceled.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/core-lro/package.json

@@ -2,7 +2,7 @@
   "name": "@azure/core-lro",
   "author": "Microsoft Corporation",
   "sdk-type": "client",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Isomorphic client library for supporting long-running operations in node.js and browser.",
   "tags": [
     "isomorphic",

sdk/core/core-lro/review/core-lro.api.md

@@ -16,6 +16,7 @@ export function createHttpPoller<TResult, TState extends OperationState<TResult>
 export interface CreateHttpPollerOptions<TResult, TState> {
     intervalInMs?: number;
     processResult?: (result: unknown, state: TState) => TResult;
+    resolveOnUnsuccessful?: boolean;
     resourceLocationConfig?: LroResourceLocationConfig;
     restoreFrom?: string;
     updateState?: (state: TState, response: LroResponse) => void;
@@ -44,6 +45,7 @@ export interface LroEngineOptions<TResult, TState> {
     isDone?: (lastResponse: unknown, state: TState) => boolean;
     lroResourceLocationConfig?: LroResourceLocationConfig;
     processResult?: (result: unknown, state: TState) => TResult;
+    resolveOnUnsuccessful?: boolean;
     resumeFrom?: string;
     updateState?: (state: TState, lastResponse: RawResponse) => void;
 }
@@ -86,6 +88,7 @@ export abstract class Poller<TState extends PollOperationState<TResult>, TResult
     pollUntilDone(pollOptions?: {
         abortSignal?: AbortSignalLike;
     }): Promise<TResult>;
+    protected resolveOnUnsuccessful: boolean;
     stopPolling(): void;
     toString(): string;
 }

sdk/core/core-lro/src/http/models.ts

@@ -105,4 +105,8 @@ export interface CreateHttpPollerOptions<TResult, TState> {
    * service.
    */
   withOperationLocation?: (operationLocation: string) => void;
+  /**
+   * Control whether to throw an exception if the operation failed or was canceled.
+   */
+  resolveOnUnsuccessful?: boolean;
 }

sdk/core/core-lro/src/http/operation.ts

@@ -208,9 +208,10 @@ export async function initHttpOperation<TResult, TState>(inputs: {
   stateProxy: StateProxy<TState, TResult>;
   resourceLocationConfig?: LroResourceLocationConfig;
   processResult?: (result: unknown, state: TState) => TResult;
+  setErrorAsResult: boolean;
   lro: LongRunningOperation;
 }): Promise<RestorableOperationState<TState>> {
-  const { stateProxy, resourceLocationConfig, processResult, lro } = inputs;
+  const { stateProxy, resourceLocationConfig, processResult, lro, setErrorAsResult } = inputs;
   return initOperation({
     init: async () => {
       const response = await lro.sendInitialRequest();
@@ -232,6 +233,7 @@ export async function initHttpOperation<TResult, TState>(inputs: {
       ? ({ flatResponse }, state) => processResult(flatResponse, state)
       : ({ flatResponse }) => flatResponse as TResult,
     getOperationStatus: getStatusFromInitialResponse,
+    setErrorAsResult,
   });
 }
 
@@ -300,8 +302,18 @@ export async function pollHttpOperation<TState, TResult>(inputs: {
   setDelay: (intervalInMs: number) => void;
   options?: { abortSignal?: AbortSignalLike };
   state: RestorableOperationState<TState>;
+  setErrorAsResult: boolean;
 }): Promise<void> {
-  const { lro, stateProxy, options, processResult, updateState, setDelay, state } = inputs;
+  const {
+    lro,
+    stateProxy,
+    options,
+    processResult,
+    updateState,
+    setDelay,
+    state,
+    setErrorAsResult,
+  } = inputs;
   return pollOperation({
     state,
     stateProxy,
@@ -320,5 +332,6 @@ export async function pollHttpOperation<TState, TResult>(inputs: {
      * references an inner this, so we need to preserve a reference to it.
      */
     poll: async (location, inputOptions) => lro.sendPollRequest(location, inputOptions),
+    setErrorAsResult,
   });
 }

sdk/core/core-lro/src/http/poller.ts

@@ -31,13 +31,15 @@ export async function createHttpPoller<TResult, TState extends OperationState<TR
     restoreFrom,
     updateState,
     withOperationLocation,
+    resolveOnUnsuccessful = false,
   } = options || {};
   return buildCreatePoller<LroResponse, TResult, TState>({
     getStatusFromInitialResponse,
     getStatusFromPollResponse: getOperationStatus,
     getOperationLocation,
     getResourceLocation,
     getPollingInterval: parseRetryAfter,
+    resolveOnUnsuccessful,
   })(
     {
       init: async () => {

sdk/core/core-lro/src/legacy/lroEngine/lroEngine.ts

@@ -20,20 +20,29 @@ export class LroEngine<TResult, TState extends PollOperationState<TResult>> exte
   private config: PollerConfig;
 
   constructor(lro: LongRunningOperation<TResult>, options?: LroEngineOptions<TResult, TState>) {
-    const { intervalInMs = POLL_INTERVAL_IN_MS, resumeFrom } = options || {};
+    const {
+      intervalInMs = POLL_INTERVAL_IN_MS,
+      resumeFrom,
+      resolveOnUnsuccessful = false,
+      isDone,
+      lroResourceLocationConfig,
+      processResult,
+      updateState,
+    } = options || {};
     const state: RestorableOperationState<TState> = resumeFrom
       ? deserializeState(resumeFrom)
       : ({} as RestorableOperationState<TState>);
-
     const operation = new GenericPollOperation(
       state,
       lro,
-      options?.lroResourceLocationConfig,
-      options?.processResult,
-      options?.updateState,
-      options?.isDone
+      !resolveOnUnsuccessful,
+      lroResourceLocationConfig,
+      processResult,
+      updateState,
+      isDone
     );
     super(operation);
+    this.resolveOnUnsuccessful = resolveOnUnsuccessful;
 
     this.config = { intervalInMs: intervalInMs };
     operation.setPollerConfig(this.config);

sdk/core/core-lro/src/legacy/lroEngine/models.ts

@@ -31,6 +31,10 @@ export interface LroEngineOptions<TResult, TState> {
    * A predicate to determine whether the LRO finished processing.
    */
   isDone?: (lastResponse: unknown, state: TState) => boolean;
+  /**
+   * Control whether to throw an exception if the operation failed or was canceled.
+   */
+  resolveOnUnsuccessful?: boolean;
 }
 
 export interface PollerConfig {

sdk/core/core-lro/src/legacy/lroEngine/operation.ts

@@ -39,6 +39,7 @@ export class GenericPollOperation<TResult, TState extends PollOperationState<TRe
   constructor(
     public state: RestorableOperationState<TState>,
     private lro: LongRunningOperation,
+    private setErrorAsResult: boolean,
     private lroResourceLocationConfig?: LroResourceLocationConfig,
     private processResult?: (result: unknown, state: TState) => TResult,
     private updateState?: (state: TState, lastResponse: RawResponse) => void,
@@ -62,6 +63,7 @@ export class GenericPollOperation<TResult, TState extends PollOperationState<TRe
           stateProxy,
           resourceLocationConfig: this.lroResourceLocationConfig,
           processResult: this.processResult,
+          setErrorAsResult: this.setErrorAsResult,
         })),
       };
     }
@@ -84,6 +86,7 @@ export class GenericPollOperation<TResult, TState extends PollOperationState<TRe
         setDelay: (intervalInMs) => {
           this.pollerConfig!.intervalInMs = intervalInMs;
         },
+        setErrorAsResult: this.setErrorAsResult,
       });
     }
     options?.fireProgress?.(this.state);

sdk/core/core-lro/src/legacy/poller.ts

@@ -102,6 +102,8 @@ export class PollerCancelledError extends Error {
 export abstract class Poller<TState extends PollOperationState<TResult>, TResult>
   implements PollerLike<TState, TResult>
 {
+  /** controls whether to throw an error if the operation failed or was canceled. */
+  protected resolveOnUnsuccessful: boolean = false;
   private stopped: boolean = true;
   private resolve?: (value: TResult) => void;
   private reject?: (error: PollerStoppedError | PollerCancelledError | Error) => void;
@@ -247,14 +249,10 @@ export abstract class Poller<TState extends PollOperationState<TResult>, TResult
    */
   private async pollOnce(options: { abortSignal?: AbortSignalLike } = {}): Promise<void> {
     if (!this.isDone()) {
-      try {
-        this.operation = await this.operation.update({
-          abortSignal: options.abortSignal,
-          fireProgress: this.fireProgress.bind(this),
-        });
-      } catch (e: any) {
-        this.operation.state.error = e;
-      }
+      this.operation = await this.operation.update({
+        abortSignal: options.abortSignal,
+        fireProgress: this.fireProgress.bind(this),
+      });
     }
     this.processUpdatedState();
   }
@@ -302,21 +300,26 @@ export abstract class Poller<TState extends PollOperationState<TResult>, TResult
   private processUpdatedState(): void {
     if (this.operation.state.error) {
       this.stopped = true;
-      this.reject!(this.operation.state.error);
-      throw this.operation.state.error;
+      if (!this.resolveOnUnsuccessful) {
+        this.reject!(this.operation.state.error);
+        throw this.operation.state.error;
+      }
     }
     if (this.operation.state.isCancelled) {
       this.stopped = true;
-      const error = new PollerCancelledError("Operation was canceled");
-      this.reject!(error);
-      throw error;
-    } else if (this.isDone() && this.resolve) {
+      if (!this.resolveOnUnsuccessful) {
+        const error = new PollerCancelledError("Operation was canceled");
+        this.reject!(error);
+        throw error;
+      }
+    }
+    if (this.isDone() && this.resolve) {
       // If the poller has finished polling, this means we now have a result.
       // However, it can be the case that TResult is instantiated to void, so
       // we are not expecting a result anyway. To assert that we might not
       // have a result eventually after finishing polling, we cast the result
       // to TResult.
-      this.resolve(this.operation.state.result as TResult);
+      this.resolve(this.getResult() as TResult);
     }
   }