Paging ContinuationToken

[lmazuel]

Support the continuation token paging feature of TypeSpec. This applies to unbranded, but there is no reason to make make it work for Azure (Storage needs it if one day we do storage).

Doc from TypeSpec:
https://typespec.io/docs/standard-library/pagination/#example-1-using-continuation-token

The concept is that this decorator is used twice:

• Once in the response
• Once in the operation that act as next operation

Codegen must do the link between those two, and then:

• Use the page1 url as base url
• Add continuation token extracted from the response.

We will limit ourselves to:

• Extraction from response header and response body (JSON path)
• Injection as header parameter and query parameter

Which means we should have at least 4 spector scenarios:

• Extract from JSON body, inject as query parameter
• Extract from JSON body, inject as header parameter
• Extract response header, inject as query parameter
• Extract response header, inject as header parameter

Note that if the initial operation had optional query parameters that were passed, they stay in the url used for the next page. IOW, whatever url was used for page 1, is the one used as basis for building the next HTTP request.

Spec

Preview Give feedback

1. Paging ContinuationToken Scenario tests #2140
   lib:azure-http-specs +1
   
2. Paging ContinuationToken TCGC Author doc #2138
   docs lib:tcgc +2
   
3. Paging ContinuationToken Scenario tests microsoft/typespec#6060
   lib:http-specs +1

Implementation

Preview Give feedback

1. Paging ContinuationToken TCGC Implementation #2139
   lib:tcgc +1
   
2. http-client-python Paging ContinuationToken Implementation microsoft/typespec#5791
   emitter:client:python +1
   
3. http-client-java Paging ContinuationToken Implementation microsoft/typespec#5792
   emitter:client:java +1
   
4. http-client-ts Paging ContinuationToken Implementation autorest.typescript#3041
   CodeGen HRLC p0 +3
   
5. http-client-csharp Paging ContinuationToken Implementation microsoft/typespec#5793
   emitter:client:csharp +1
6. http-client-go Paging ContinuationToken Implementation autorest.go#1494
   CodeGen TypeSpec +2
7. https://github.com/Azure/autorest.cpp/issues/485
8. https://github.com/Azure/typespec-rust/issues/236
9. typespec-java, Paging ContinuationToken Implementation for Azure autorest.java#3026
   DPG +1
10. [typespec-ts] Support continuationToken in Azure Scope autorest.typescript#3062
    HRLC P1 RLC +3
    

[msyyc]

@lmazuel, according to https://typespec.io/docs/standard-library/pagination/#_top:

it is also valid scenario to pass token in payload. Shall we support it? If yes, there shall be more 2 spector scenarios:

• Extract from JSON body, inject as payload parameter
• Extract response header, inject as payload parameter

[msyyc]

@lmazuel, according to https://typespec.io/docs/standard-library/pagination/#_top:

it is also valid scenario to pass token in payload. Shall we support it? If yes, there shall be more 2 spector scenarios:

• Extract from JSON body, inject as payload parameter
• Extract response header, inject as payload parameter

Confirmed that continuation token in request body is not in scope : https://teams.microsoft.com/l/message/19:[email protected]/1739898764679?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&parentMessageId=1739861699306&teamName=Azure%20SDK&channelName=TypeSpec%20Discussion&createdTime=1739898764679