[REST Clients] Add lro poller helper

[joheredi]

Introducing @azure-rest/core-client-lro

Note: Everything under src/lroEngine is interim, the plan is for it to live under @azure/core-lro and that work is tracked by #15775. For the purpose of this PR you can skip the contents of that folder.

This package exports getLongRunningPoller which is designed to be consumed by the REST client code generator and re-expose, this allows the code generator add additional metadata about the long running operation that may be present in the Swagger definition.

getLongRunningPoller takes:

• client which will be used internally to poll for the state
• initialResponse which is the response after submitting the initial response to the long running operation
• pollerOptions which has some setting that users can set such as intervalInMs to set the wait time before polls and resumeFrom which takes a serialized state to create a poller.
  - finalStateVia, this parameter is typically abstracted from the user and set by the generator taking the value of x-ms-long-running-operation in the swagger if it exists.

Sample usage by Generator:

export function getPoller<TResult extends HttpResponse>(
  client: FarmBeatsRestClient,
  initialResponse: TResult
): PollerLike<PollOperationState<TResult>, TResult> {
  // The generator would generate and export a function like this.
  return getLongRunningPoller(client, initialResponse);
}

Sample final user usage

const initialResponse = await client.path("/foo").put({body: {id: "1", name: "test"}});

if (initialResponse.status !== "202") {
  throw initialResponse.body.error ?? new Error(`Unexpected status ${initialResponse.status}`);
}

const poller = getPoller(client, initialResponse);
const result = await poller.pollUntilDone();

console.log(result.body);

[ellismg]

Didn't look at the core engine stuff at all, but have some feedback about the interface, specifically around falsy paths. Love the direction this is heading, though and the resulting FarmBeats samples look really nice.

[deyaaeldeen]

getLongRunningPoller feels a bit verbose, did you consider using just getPoller? cc @bterlson @xirzec @chradek

[joheredi]

Initially, I named it getPoller but when prototyping how this would be generated I decided to name it like this to avoid collisions, for example, this is how the generator would consume this to export getPoller

export function getPoller<TResult extends HttpResponse>(
  client: FarmBeatsRestClient,
  initialResponse: TResult
): PollerLike<PollOperationState<TResult>, TResult> {
  return getLongRunningPoller(client, initialResponse);
}

If this one is named getPoller as well we'd need an import alias. Not a big deal though, I'm happy to change it to getPoller I'll wait to get more opinions from @bterlson and @xirzec

[deyaaeldeen]

But why generating this wrapper? just to hide the pollerOptions? but again, why?

[joheredi]

Discussed offline. This wrapper is generated to pass additional info to the LRO engine that we can abstract from the user. For example, there are cases where the Swagger would define an LRO that needs FinalStateVia, we would set that in this wrapper. The end-user doesn't need to know about FinalStateVia, they would only care about the polling interval and also a state to resume the polling if they want. The other options are meant for internal use only. So this wrapper hides that from end users.

I added more feedback

[deyaaeldeen]

I deleted getPoller so I think we can move this dep to devDependencies now unless you want to add getPoller back but I do not see the point for it after the simplified getLongRunningPoller.

[joheredi]

Discussed offline. Brought back getPoller, see comment above for details

[deyaaeldeen]

This is going to be customer-facing, so should it be setIntervalInMs to be consistent with what we have in Track 2 packages? I know our guidelines have them as intervalInMs but it looks like we wanted to adopt the convention of having a prefix verb so our packages now uses setIntervalInMs. @bterlson what do you think about this?

[deyaaeldeen]

Actually, code gen generates updateIntervalInMs: https://github.com/Azure/autorest.typescript/blob/357d655a4b8414490c90145aa98ea1130e691b05/test/integration/generated/lro/src/models/index.ts#L655.

[deyaaeldeen]

Looks great, I left one last comment about naming.

[bterlson]

Very cool, nice work! Had much fun playing with it 😁