@azure/arm-managedapplications 1.1.0 → 2.0.0-beta.1

package/src/lro/azureAsyncPolling.ts

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import {
+  failureStates,
+  LroResourceLocationConfig,
+  LongRunningOperation,
+  LroBody,
+  LroResponse,
+  LroStatus,
+  RawResponse,
+  successStates
+} from "./models";
+import { isUnexpectedPollingResponse } from "./requestUtils";
+
+function getResponseStatus(rawResponse: RawResponse): string {
+  const { status } = (rawResponse.body as LroBody) ?? {};
+  return status?.toLowerCase() ?? "succeeded";
+}
+
+function isAzureAsyncPollingDone(rawResponse: RawResponse): boolean {
+  const state = getResponseStatus(rawResponse);
+  if (
+    isUnexpectedPollingResponse(rawResponse) ||
+    failureStates.includes(state)
+  ) {
+    throw new Error(`Operation status: ${state}`);
+  }
+  return successStates.includes(state);
+}
+
+async function sendFinalRequest<TResult>(
+  lro: LongRunningOperation<TResult>,
+  lroResourceLocationConfig?: LroResourceLocationConfig,
+  resourceLocation?: string
+): Promise<LroResponse<TResult> | undefined> {
+  switch (lroResourceLocationConfig) {
+    case "original-uri":
+      return lro.retrieveAzureAsyncResource();
+    case "azure-async-operation":
+      return Promise.resolve(undefined);
+    case "location":
+    default:
+      return lro.retrieveAzureAsyncResource(resourceLocation);
+  }
+}
+
+export function processAzureAsyncOperationResult<TResult>(
+  lro: LongRunningOperation<TResult>,
+  resourceLocation?: string,
+  lroResourceLocationConfig?: LroResourceLocationConfig
+): (rawResponse: RawResponse, flatResponse: TResult) => LroStatus<TResult> {
+  return (
+    rawResponse: RawResponse,
+    flatResponse: TResult
+  ): LroStatus<TResult> => {
+    if (isAzureAsyncPollingDone(rawResponse)) {
+      if (resourceLocation === undefined) {
+        return { rawResponse, flatResponse, done: true };
+      } else {
+        return {
+          rawResponse,
+          flatResponse,
+          done: false,
+          next: async () => {
+            const finalResponse = await sendFinalRequest(
+              lro,
+              lroResourceLocationConfig,
+              resourceLocation
+            );
+            return {
+              ...(finalResponse ?? {
+                rawResponse,
+                flatResponse
+              }),
+              done: true
+            };
+          }
+        };
+      }
+    }
+    return {
+      rawResponse,
+      flatResponse,
+      done: false
+    };
+  };
+}

package/src/lro/bodyPolling.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import {
+  failureStates,
+  LroBody,
+  LroStatus,
+  RawResponse,
+  successStates
+} from "./models";
+import { isUnexpectedPollingResponse } from "./requestUtils";
+
+function getProvisioningState(rawResponse: RawResponse): string {
+  const { properties, provisioningState } = (rawResponse.body as LroBody) ?? {};
+  const state: string | undefined =
+    properties?.provisioningState ?? provisioningState;
+  return state?.toLowerCase() ?? "succeeded";
+}
+
+export function isBodyPollingDone(rawResponse: RawResponse): boolean {
+  const state = getProvisioningState(rawResponse);
+  if (
+    isUnexpectedPollingResponse(rawResponse) ||
+    failureStates.includes(state)
+  ) {
+    throw new Error(
+      `The long running operation has failed. The provisioning state: ${state}.`
+    );
+  }
+  return successStates.includes(state);
+}
+
+/**
+ * Creates a polling strategy based on BodyPolling which uses the provisioning state
+ * from the result to determine the current operation state
+ */
+export function processBodyPollingOperationResult<TResult>(
+  rawResponse: RawResponse,
+  flatResponse: TResult
+): LroStatus<TResult> {
+  return {
+    rawResponse,
+    flatResponse,
+    done: isBodyPollingDone(rawResponse)
+  };
+}

package/src/lro/index.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export { LroEngine } from "./lroEngine";
+export { createGetLroStatusFromResponse } from "./stateMachine";
+export {
+  LroResourceLocationConfig,
+  GetLroStatusFromResponse,
+  RawResponse,
+  LongRunningOperation,
+  LroConfig,
+  LroMode,
+  LroResponse,
+  LroStatus,
+  LroTerminalState,
+  LroInProgressState,
+  LroEngineOptions
+} from "./models";

package/src/lro/locationPolling.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { LroStatus, RawResponse } from "./models";
+import { isUnexpectedPollingResponse } from "./requestUtils";
+
+function isLocationPollingDone(rawResponse: RawResponse): boolean {
+  return (
+    !isUnexpectedPollingResponse(rawResponse) && rawResponse.statusCode !== 202
+  );
+}
+
+export function processLocationPollingOperationResult<TResult>(
+  rawResponse: RawResponse,
+  flatResponse: TResult
+): LroStatus<TResult> {
+  return {
+    rawResponse,
+    flatResponse,
+    done: isLocationPollingDone(rawResponse)
+  };
+}

package/src/lro/lroEngine.ts

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { Poller, PollOperationState } from "@azure/core-lro";
+import {
+  LongRunningOperation,
+  LroEngineOptions,
+  ResumablePollOperationState
+} from "./models";
+import { GenericPollOperation } from "./operation";
+
+/**
+ * The LRO Engine, a class that performs polling.
+ */
+export class LroEngine<
+  TResult,
+  TState extends PollOperationState<TResult>
+> extends Poller<TState, TResult> {
+  private intervalInMs: number;
+
+  constructor(lro: LongRunningOperation<TResult>, options?: LroEngineOptions) {
+    const { intervalInMs = 2000, resumeFrom } = options || {};
+    function deserializeState(
+      resumeFrom: string
+    ): TState & ResumablePollOperationState<TResult> {
+      try {
+        return JSON.parse(resumeFrom).state;
+      } catch (e) {
+        throw new Error(
+          `LroEngine: Unable to deserialize state: ${resumeFrom}`
+        );
+      }
+    }
+    const state: TState & ResumablePollOperationState<TResult> = resumeFrom
+      ? deserializeState(resumeFrom)
+      : ({} as any);
+
+    const operation = new GenericPollOperation(state, lro);
+    super(operation);
+
+    this.intervalInMs = intervalInMs;
+    operation.setPollerConfig(this as any);
+  }
+
+  /**
+   * The method used by the poller to wait before attempting to update its operation.
+   */
+  delay(): Promise<void> {
+    return new Promise((resolve) =>
+      setTimeout(() => resolve(), this.intervalInMs)
+    );
+  }
+}

package/src/lro/models.ts

@@ -0,0 +1,173 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { PollOperationState } from "@azure/core-lro";
+
+/**
+ * Options for the LRO poller.
+ */
+export interface LroEngineOptions {
+  /**
+   * Defines how much time the poller is going to wait before making a new request to the service.
+   */
+  intervalInMs?: number;
+  /**
+   * A serialized poller which can be used to resume an existing paused Long-Running-Operation.
+   */
+  resumeFrom?: string;
+}
+
+export const successStates = ["succeeded"];
+export const failureStates = ["failed", "canceled", "cancelled"];
+/**
+ * The LRO states that signal that the LRO has completed.
+ */
+export const terminalStates = successStates.concat(failureStates);
+
+/**
+ * The potential location of the result of the LRO if specified by the LRO extension in the swagger.
+ */
+export type LroResourceLocationConfig =
+  | "azure-async-operation"
+  | "location"
+  | "original-uri";
+
+/**
+ * The type of a LRO response body. This is just a convenience type for checking the status of the operation.
+ */
+
+export interface LroBody extends Record<string, unknown> {
+  /** The status of the operation. */
+  status?: string;
+  /** The state of the provisioning process */
+  provisioningState?: string;
+  /** The properties of the provisioning process */
+  properties?: { provisioningState?: string } & Record<string, unknown>;
+}
+
+/**
+ * Simple type of the raw response.
+ */
+export interface RawResponse {
+  /** The HTTP status code */
+  statusCode: number;
+  /** A HttpHeaders collection in the response represented as a simple JSON object where all header names have been normalized to be lower-case. */
+  headers: {
+    [headerName: string]: string;
+  };
+  /** The parsed response body */
+  body?: unknown;
+}
+
+/**
+ * The type of the response of a LRO.
+ */
+export interface LroResponse<T> {
+  /** The flattened response */
+  flatResponse: T;
+  /** The raw response */
+  rawResponse: RawResponse;
+}
+
+/** The type of which LRO implementation being followed by a specific API. */
+export type LroMode = "AzureAsync" | "Location" | "Body";
+
+/**
+ * The configuration of a LRO to determine how to perform polling and checking whether the operation has completed.
+ */
+export interface LroConfig {
+  /** The LRO mode */
+  mode?: LroMode;
+  /** The path of a provisioned resource */
+  resourceLocation?: string;
+}
+
+/**
+ * Type of a polling operation state that can actually be resumed.
+ */
+export type ResumablePollOperationState<T> = PollOperationState<T> & {
+  initialRawResponse?: RawResponse;
+  config?: LroConfig;
+  pollingURL?: string;
+};
+
+export interface PollerConfig {
+  intervalInMs: number;
+}
+
+/**
+ * The type of a terminal state of an LRO.
+ */
+export interface LroTerminalState<T> extends LroResponse<T> {
+  /**
+   * Whether the operation has finished.
+   */
+  done: true;
+}
+
+/**
+ * The type of an in-progress state of an LRO.
+ */
+export interface LroInProgressState<T> extends LroResponse<T> {
+  /**
+   * Whether the operation has finished.
+   */
+  done: false;
+  /**
+   * The request to be sent next if it is different from the standard polling one.
+   * Notice that it will disregard any polling URLs provided to it.
+   */
+  next?: () => Promise<LroStatus<T>>;
+}
+
+/**
+ * The type of an LRO state which is a tagged union of terminal and in-progress states.
+ */
+export type LroStatus<T> = LroTerminalState<T> | LroInProgressState<T>;
+
+/**
+ * The type of the getLROStatusFromResponse method. It takes the response as input and returns along the response whether the operation has finished.
+ */
+export type GetLroStatusFromResponse<T> = (
+  rawResponse: RawResponse,
+  flatResponse: T
+) => LroStatus<T>;
+
+/**
+ * Description of a long running operation.
+ */
+export interface LongRunningOperation<T> {
+  /**
+   * The request path.
+   */
+  requestPath: string;
+  /**
+   * The HTTP request method.
+   */
+  requestMethod: string;
+  /**
+   * A function that can be used to send initial request to the service.
+   */
+  sendInitialRequest: (
+    initializeState: (
+      rawResponse: RawResponse,
+      flatResponse: unknown
+    ) => boolean
+  ) => Promise<LroResponse<T>>;
+  /**
+   * A function that can be used to poll for the current status of a long running operation.
+   */
+  sendPollRequest: (config: LroConfig, path: string) => Promise<LroStatus<T>>;
+  /**
+   * A function that can be used to retrieve the provisioned azure resource.
+   */
+  retrieveAzureAsyncResource: (path?: string) => Promise<LroResponse<T>>;
+}

package/src/lro/operation.ts

@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { AbortSignalLike } from "@azure/abort-controller";
+import { PollOperationState, PollOperation } from "@azure/core-lro";
+import {
+  PollerConfig,
+  ResumablePollOperationState,
+  LongRunningOperation,
+  LroStatus
+} from "./models";
+import { getPollingUrl } from "./requestUtils";
+import { createInitializeState, createPollForLROStatus } from "./stateMachine";
+
+export class GenericPollOperation<
+  TResult,
+  TState extends PollOperationState<TResult>
+> implements PollOperation<TState, TResult> {
+  private getLROStatusFromResponse?: (
+    pollingURL: string,
+    pollerConfig: PollerConfig
+  ) => Promise<LroStatus<TResult>>;
+  private pollerConfig?: PollerConfig;
+  constructor(
+    public state: TState & ResumablePollOperationState<TResult>,
+    private lro: LongRunningOperation<TResult>
+  ) {}
+
+  public setPollerConfig(pollerConfig: PollerConfig): void {
+    this.pollerConfig = pollerConfig;
+  }
+
+  /**
+   * General update function for LROPoller, the general process is as follows
+   * 1. Check initial operation result to determine the strategy to use
+   *  - Strategies: Location, Azure-AsyncOperation, Original Uri
+   * 2. Check if the operation result has a terminal state
+   *  - Terminal state will be determined by each strategy
+   *  2.1 If it is terminal state Check if a final GET request is required, if so
+   *      send final GET request and return result from operation. If no final GET
+   *      is required, just return the result from operation.
+   *      - Determining what to call for final request is responsibility of each strategy
+   *  2.2 If it is not terminal state, call the polling operation and go to step 1
+   *      - Determining what to call for polling is responsibility of each strategy
+   *      - Strategies will always use the latest URI for polling if provided otherwise
+   *        the last known one
+   */
+  async update(options?: {
+    abortSignal?: AbortSignalLike | undefined;
+    fireProgress?: ((state: TState) => void) | undefined;
+  }): Promise<PollOperation<TState, TResult>> {
+    const state = this.state;
+    if (!state.isStarted) {
+      const initializeState = createInitializeState(
+        state,
+        this.lro.requestPath,
+        this.lro.requestMethod
+      );
+      await this.lro.sendInitialRequest(initializeState);
+    }
+
+    if (!state.isCompleted) {
+      if (this.getLROStatusFromResponse === undefined) {
+        if (state.config === undefined) {
+          throw new Error(
+            "Bad state: LRO mode is undefined. Please check if the serialized state is well-formed."
+          );
+        }
+        this.getLROStatusFromResponse = createPollForLROStatus(
+          this.lro,
+          state.config
+        );
+      }
+      if (state.pollingURL === undefined) {
+        throw new Error(
+          "Bad state: polling URL is undefined. Please check if the serialized state is well-formed."
+        );
+      }
+      const currentState = await this.getLROStatusFromResponse(
+        state.pollingURL,
+        this.pollerConfig!
+      );
+      if (currentState.done) {
+        state.result = currentState.flatResponse;
+        state.isCompleted = true;
+      } else {
+        this.getLROStatusFromResponse =
+          currentState.next ?? this.getLROStatusFromResponse;
+        state.pollingURL = getPollingUrl(
+          currentState.rawResponse,
+          state.pollingURL
+        );
+      }
+    }
+    options?.fireProgress?.(state);
+    return this;
+  }
+
+  async cancel(): Promise<PollOperation<TState, TResult>> {
+    this.state.isCancelled = true;
+    return this;
+  }
+
+  /**
+   * Serializes the Poller operation.
+   */
+  public toString(): string {
+    return JSON.stringify({
+      state: this.state
+    });
+  }
+}

package/src/lro/passthrough.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { LroStatus, RawResponse } from "./models";
+
+export function processPassthroughOperationResult<TResult>(
+  rawResponse: RawResponse,
+  flatResponse: TResult
+): LroStatus<TResult> {
+  return {
+    rawResponse,
+    flatResponse,
+    done: true
+  };
+}

package/src/lro/requestUtils.ts

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { LroConfig, RawResponse } from "./models";
+
+/**
+ * Detects where the continuation token is and returns it. Notice that azure-asyncoperation
+ * must be checked first before the other location headers because there are scenarios
+ * where both azure-asyncoperation and location could be present in the same response but
+ * azure-asyncoperation should be the one to use for polling.
+ */
+export function getPollingUrl(
+  rawResponse: RawResponse,
+  defaultPath: string
+): string {
+  return (
+    getAzureAsyncOperation(rawResponse) ??
+    getLocation(rawResponse) ??
+    getOperationLocation(rawResponse) ??
+    defaultPath
+  );
+}
+
+function getLocation(rawResponse: RawResponse): string | undefined {
+  return rawResponse.headers["location"];
+}
+
+function getOperationLocation(rawResponse: RawResponse): string | undefined {
+  return rawResponse.headers["operation-location"];
+}
+
+function getAzureAsyncOperation(rawResponse: RawResponse): string | undefined {
+  return rawResponse.headers["azure-asyncoperation"];
+}
+
+export function inferLroMode(
+  requestPath: string,
+  requestMethod: string,
+  rawResponse: RawResponse
+): LroConfig {
+  if (getAzureAsyncOperation(rawResponse) !== undefined) {
+    return {
+      mode: "AzureAsync",
+      resourceLocation:
+        requestMethod === "PUT"
+          ? requestPath
+          : requestMethod === "POST"
+          ? getLocation(rawResponse)
+          : undefined
+    };
+  } else if (
+    getLocation(rawResponse) !== undefined ||
+    getOperationLocation(rawResponse) !== undefined
+  ) {
+    return {
+      mode: "Location"
+    };
+  } else if (["PUT", "PATCH"].includes(requestMethod)) {
+    return {
+      mode: "Body"
+    };
+  }
+  return {};
+}
+
+export class RestError extends Error {
+  public statusCode?: number;
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "RestError";
+    this.statusCode = statusCode;
+
+    Object.setPrototypeOf(this, RestError.prototype);
+  }
+}
+
+export function isUnexpectedInitialResponse(rawResponse: RawResponse): boolean {
+  const code = rawResponse.statusCode;
+  if (![203, 204, 202, 201, 200, 500].includes(code)) {
+    throw new RestError(
+      `Received unexpected HTTP status code ${code} in the initial response. This may indicate a server issue.`,
+      code
+    );
+  }
+  return false;
+}
+
+export function isUnexpectedPollingResponse(rawResponse: RawResponse): boolean {
+  const code = rawResponse.statusCode;
+  if (![202, 201, 200, 500].includes(code)) {
+    throw new RestError(
+      `Received unexpected HTTP status code ${code} while polling. This may indicate a server issue.`,
+      code
+    );
+  }
+  return false;
+}