From 055de12a4e81576c94da013d538c264512027df1 Mon Sep 17 00:00:00 2001 From: Mary Gao Date: Fri, 17 May 2024 11:53:52 +0800 Subject: [PATCH] GA core-lro v3 (#29450) The preview pr is merged here: https://github.com/Azure/azure-sdk-for-js/pull/29311. GA core-lro v3: - api view: [diff compared with v3](https://apiview.dev/Assemblies/Review/2c2e6c39be9f4efcb7dcb5812ec03caa?revisionId=aca67bf30ec540e6a93f093521d13b56&diffOnly=False&doc=False&diffRevisionId=c2c407f93624426090afa05dfb58d7c1) - migration guide: [here](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-lro/docs/MIGRATION.md) - design doc: [gist](https://gist.github.com/joheredi/09b81c192e8c7c4ee3581ac0b9f76c12#option-3-behavior-based-on-invocation), [loop 1](https://microsoft.sharepoint.com/:fl:/s/61554b56-c90b-4961-ba7c-61caae235335/ERp0F2QPyX9ElPkeL2U5pioB7_ar6uwHWYiTa7roChsHVw?e=FcS0YL&nav=cz0lMkZzaXRlcyUyRjYxNTU0YjU2LWM5MGItNDk2MS1iYTdjLTYxY2FhZTIzNTMzNSZkPWIhWkhjMnhhbl9nVXVNc3RET0NHaTNKMjZEQ09nVk5FRkxtTDg4UUNsZUpwaklYajhzTWlFSFRZVC02bTRGV2JkNSZmPTAxREdGMk9FWTJPUUxXSUQ2SlA1Q0pKNkk2RjVTVFRKUksmYz0lMkYmZmx1aWQ9MSZhPUxvb3BBcHAmcD0lNDBmbHVpZHglMkZsb29wLXBhZ2UtY29udGFpbmVyJng9JTdCJTIydyUyMiUzQSUyMlQwUlRVSHh0YVdOeWIzTnZablF1YzJoaGNtVndiMmx1ZEM1amIyMThZaUZhU0dNeWVHRnVYMmRWZFUxemRFUlBRMGRwTTBveU5rUkRUMmRXVGtWR1RHMU1PRGhSUTJ4bFNuQnFTVmhxT0hOTmFVVklWRmxVTFRadE5FWlhZbVExZkRBeFJFZEdNazlGTkZSRlRWRTBOMUpHUVRkYVJUSlBSazVEUkRSV1dEWTBNa1UlM0QlMjIlMkMlMjJpJTIyJTNBJTIyYjA3OTYyZWQtMWM4Ni00Zjg3LWE3OTctYjE0MDg1ZmEwYzY4JTIyJTdE), [loop 2](https://microsoft.sharepoint.com/:fl:/s/61554b56-c90b-4961-ba7c-61caae235335/EdO7c7zhNQ5PouqkX5YbPZ4BXAnvlDCvW9SiARuN8gMcww?e=LufGPM&nav=cz0lMkZzaXRlcyUyRjYxNTU0YjU2LWM5MGItNDk2MS1iYTdjLTYxY2FhZTIzNTMzNSZkPWIhWkhjMnhhbl9nVXVNc3RET0NHaTNKMjZEQ09nVk5FRkxtTDg4UUNsZUpwaklYajhzTWlFSFRZVC02bTRGV2JkNSZmPTAxREdGMk9FNlRYTlozWllKVkJaSDJGMlZFTDZMQldQTTYmYz0lMkYmZmx1aWQ9MSZhPUxvb3BBcHAmcD0lNDBmbHVpZHglMkZsb29wLXBhZ2UtY29udGFpbmVyJng9JTdCJTIydyUyMiUzQSUyMlQwUlRVSHh0YVdOeWIzTnZablF1YzJoaGNtVndiMmx1ZEM1amIyMThZaUZhU0dNeWVHRnVYMmRWZFUxemRFUlBRMGRwTTBveU5rUkRUMmRXVGtWR1RHMU1PRGhSUTJ4bFNuQnFTVmhxT0hOTmFVVklWRmxVTFRadE5FWlhZbVExZkRBeFJFZEdNazlGTkZSRlRWRTBOMUpHUVRkYVJUSlBSazVEUkRSV1dEWTBNa1UlM0QlMjIlMkMlMjJpJTIyJTNBJTIyYjA3OTYyZWQtMWM4Ni00Zjg3LWE3OTctYjE0MDg1ZmEwYzVjJTIyJTdE) Impacted SDKs: - Currently I think no SDKs would be impacted. - Existing HLC SDKs would use v2, no impact; - RLC LRO wrapped its interface with v3 and without any breakings([see pr detail](https://github.com/Azure/autorest.typescript/pull/2443)), no impact; - Modular would use v3. The only modular SDK that is OpenAI without LRO operations, so no impact. - In future there would be breaking when migrating HLC to Modular. Main changes: ```diff - export function createHttpPoller>(lro: LongRunningOperation, options?: CreateHttpPollerOptions): Promise>; + export function createHttpPoller>(lro: RunningOperation, options?: CreateHttpPollerOptions): PollerLike; - export interface SimplePollerLike, TResult> { + export interface PollerLike, TResult> extends Promise { - getOperationState(): TState; + readonly operationState: TState | undefined; - getResult(): TResult | undefined; + readonly result: TResult | undefined; - isDone(): boolean; + readonly isDone: boolean; - isStopped(): boolean; - stopPolling(): void; - toString(): string; + serialize(): Promise; + submitted(): Promise; onProgress(callback: (state: TState) => void): CancelOnProgress; poll(options?: { abortSignal?: AbortSignalLike; - }): Promise; + }): Promise; pollUntilDone(pollOptions?: { abortSignal?: AbortSignalLike; }): Promise; } ``` --- sdk/core/core-lro/CHANGELOG.md | 9 +- sdk/core/core-lro/docs/MIGRATION.md | 137 ++++++++++++++++++++++++++++ sdk/core/core-lro/package.json | 2 +- 3 files changed, 140 insertions(+), 8 deletions(-) diff --git a/sdk/core/core-lro/CHANGELOG.md b/sdk/core/core-lro/CHANGELOG.md index 2af63024fde8..f062d9f6d369 100644 --- a/sdk/core/core-lro/CHANGELOG.md +++ b/sdk/core/core-lro/CHANGELOG.md @@ -1,14 +1,9 @@ # Release History -## 3.0.0-beta.3 (Unreleased) +## 3.0.0 (Unreleased) -### Features Added - -### Breaking Changes +GA the v3 version. To migrate the existing applications to v3, please refer to [Migration Guide](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-lro/docs/MIGRATION.md). -### Bugs Fixed - -### Other Changes ## 3.0.0-beta.2 (2024-04-26) diff --git a/sdk/core/core-lro/docs/MIGRATION.md b/sdk/core/core-lro/docs/MIGRATION.md index b2431ed2ba9f..8c482a6b01ff 100644 --- a/sdk/core/core-lro/docs/MIGRATION.md +++ b/sdk/core/core-lro/docs/MIGRATION.md @@ -92,3 +92,140 @@ now ```ts const serializeState = await poller.serialize(); ``` + +## `core-lro-shim` + +There are situations where we don't want to break existing code and want to keep backward compatibility. Here we prepare `core-lro-shim` scripts for you, in which we implemented v2 `SimplePollerLike` interfaces with v3 interfaces. + +Once you copy them into your environment and the only thing you need to do is to update your lro references to that shim. + +```ts +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { AbortSignalLike } from "@azure/abort-controller"; +import { + CancelOnProgress, + CreateHttpPollerOptions, + OperationState, + RunningOperation, + createHttpPoller as createInternalHttpPoller, +} from "@azure/core-lro"; + +/** + * A simple poller that can be used to poll a long running operation. + */ +export interface SimplePollerLike, TResult> { + /** + * Returns true if the poller has finished polling. + */ + isDone(): boolean; + /** + * Returns true if the poller is stopped. + */ + isStopped(): boolean; + /** + * Returns the state of the operation. + */ + getOperationState(): TState; + /** + * Returns the result value of the operation, + * regardless of the state of the poller. + * It can return undefined or an incomplete form of the final TResult value + * depending on the implementation. + */ + getResult(): TResult | undefined; + /** + * Returns a promise that will resolve once a single polling request finishes. + * It does this by calling the update method of the Poller's operation. + */ + poll(options?: { abortSignal?: AbortSignalLike }): Promise; + /** + * Returns a promise that will resolve once the underlying operation is completed. + */ + pollUntilDone(pollOptions?: { abortSignal?: AbortSignalLike }): Promise; + /** + * Invokes the provided callback after each polling is completed, + * sending the current state of the poller's operation. + * + * It returns a method that can be used to stop receiving updates on the given callback function. + */ + onProgress(callback: (state: TState) => void): CancelOnProgress; + + /** + * Wait the poller to be submitted. + */ + submitted(): Promise; + + /** + * Returns a string representation of the poller's operation. Similar to serialize but returns a string. + */ + toString(): string; + + /** + * Stops the poller from continuing to poll. Please note this will only stop the client-side polling + */ + stopPolling(): void; +} + +export async function createHttpPoller>( + lro: RunningOperation, + options?: CreateHttpPollerOptions, +): Promise> { + const httpPoller = createInternalHttpPoller(lro, options); + const abortController = new AbortController(); + const simplePoller: SimplePollerLike = { + isDone() { + return httpPoller.isDone; + }, + isStopped() { + return abortController.signal.aborted; + }, + getOperationState() { + if (!httpPoller.operationState) { + throw new Error( + "Operation state is not available. The poller may not have been started and you could await submitted() before calling getOperationState().", + ); + } + return httpPoller.operationState; + }, + getResult() { + return httpPoller.result; + }, + toString() { + if (!httpPoller.operationState) { + throw new Error( + "Operation state is not available. The poller may not have been started and you could await submitted() before calling getOperationState().", + ); + } + return JSON.stringify({ + state: httpPoller.operationState, + }); + }, + stopPolling() { + abortController.abort(); + }, + onProgress: httpPoller.onProgress, + poll: httpPoller.poll, + pollUntilDone(pollOptions?: { abortSignal?: AbortSignalLike }) { + function abortListener(): void { + abortController.abort(); + } + const inputAbortSignal = pollOptions?.abortSignal; + const abortSignal = abortController.signal; + if (inputAbortSignal?.aborted) { + abortController.abort(); + } else if (!abortSignal.aborted) { + inputAbortSignal?.addEventListener("abort", abortListener, { + once: true, + }); + } + return httpPoller.pollUntilDone({ abortSignal: abortController.signal }); + }, + submitted: httpPoller.submitted, + }; + await httpPoller.submitted(); + return simplePoller; +} + +``` diff --git a/sdk/core/core-lro/package.json b/sdk/core/core-lro/package.json index a866ea18ab26..832fad15a852 100644 --- a/sdk/core/core-lro/package.json +++ b/sdk/core/core-lro/package.json @@ -2,7 +2,7 @@ "name": "@azure/core-lro", "author": "Microsoft Corporation", "sdk-type": "client", - "version": "3.0.0-beta.3", + "version": "3.0.0", "type": "module", "description": "Isomorphic client library for supporting long-running operations in node.js and browser.", "exports": {