[Preview] Change Feed: Add FeedRange and continuation separate

[ealsur]

This PR applies a refactoring on the existing FeedToken concept plus, adds support for Queries.

Replacing FeedToken for FeedRange + Continuation

This change conceptually decouples the range represented by a FeedToken from the continuation. A FeedRange now simply represents a Range of partition key values and nothing more. This range could be matching a complete physical partition, a smaller range, or a single partition key value.

Task<IReadOnlyList<FeedRange>> Container.GetFeedRangesAsync(CancellationToken cancellationToken = default(CancellationToken));

provides a way to obtain the list of ranges, very much like FeedToken previously (see #1210).

Separating FeedRange from Continuation provides two major benefits:

1. A FeedRange is now valid to be used for a Change Feed operation or for a Query.
2. The concept of Continuation Token as a string is more familiar to our users than having to learn how to acquire and serialize (and then deserialize) the FeedToken.

Change Feed

Most of the functionality from the previous Change Feed using FeedToken remains the same with some slight changes.

Iterator

Change Feed is an infinite feed, but we detect the case where no more changes are pending to be read through the HasMoreResults flag:

FeedIterator iterator = container.GetChangeFeedStreamIterator();
string continuation = null;
while (iterator.HasMoreResults)
{
    // Stream iterator returns a response with status code
    using(ResponseMessage response = await iterator.ReadNextAsync())
    {
       // consume message
       continuation = response.ContinuationToken;
    }
}

// Means no more changes in the Change Feed

// Some time later, we can check for new changes
ChangeFeedIterator iterator = container.GetChangeFeedStreamIterator(continuation);

Parallelization

IReadOnlyList<FeedRange> ranges = await container.GetFeedRangesAsync();

// Machine or Thread 1
FeedIterator iteratorForToken = container.GetChangeFeedStreamIterator(ranges[0]);
while (iteratorForToken.HasMoreResults)
{
    // Stream iterator returns a response with status code
    using(ResponseMessage response = await iteratorForToken .ReadNextAsync())
    {
        if(response.IsSuccessStatusCode)
        {
            // Consume response.Content stream
        }
    }
}

// Machine or Thread 2
FeedIterator iteratorForToken = container.GetChangeFeedStreamIterator(ranges[1]);
while (iteratorForToken.HasMoreResults)
{
    // Stream iterator returns a response with status code
    using(ResponseMessage response = await iteratorForToken .ReadNextAsync())
    {
        if(response.IsSuccessStatusCode)
        {
            // Consume response.Content stream
        }
    }
}

Consume the entire Container

Scenario is exactly as it was for FeedToken:

FeedIterator iteratorForTheEntireContainer = container.GetChangeFeedStreamIterator();
while (iteratorForTheEntireContainer.HasMoreResults)
{
    // Stream iterator returns a response with status code
    using(ResponseMessage response = await iteratorForTheEntireContainer.ReadNextAsync())
    {
        if(response.IsSuccessStatusCode)
        {
            // Consume response.Content stream
        }
    }
}

Change Feed for a Partition Key

Same scenario as with FeedTokens, it's an overload of the GetChangeFeedStreamIterator or GetChangeFeedIterator:

FeedIterator iteratorForTheEntireContainer= container.GetChangeFeedStreamIterator(new PartitionKey("myPartitionKeyValueToRead");

Diagnostics

Added Diagnostics information to show which was the FeedRange used for a particular Change Feed request.

Read Feed

Previously we were using the same FeedIteratorCore implementation for non-partitioned (metadata) resources and partitioned (documents) resources with conditional logic.

This PR leaves the FeedIteratorCore class for non-partitioned resources, while adding FeedRangeIteratorCore for partitioned resources with explicit logic to handle FeedRanges and keep supporting parallelization of ReadFeed operations (introduced on #1230). The key here is the introduction of FeedRangeResponseMessage that wraps ResponseMessage and promotes the continuation format for FeedRange on ResponseMessage.Continuation.

Same concepts of parallelization through FeedRange are maintained in this refactoring.

Queries

This PR adds new APIs for Queries to take FeedRange as an input parameter. This effectively scopes the query to the defined Range.

public abstract FeedIterator GetItemQueryStreamIterator(
            FeedRange feedRange,
            QueryDefinition queryDefinition,
            string continuationToken = null,
            QueryRequestOptions requestOptions = null);

public abstract FeedIterator<T> GetItemQueryIterator<T>(
            FeedRange feedRange,
            QueryDefinition queryDefinition,
            string continuationToken = null,
            QueryRequestOptions requestOptions = null);

Once the scope is set and the query is executed, continuation is used the same way as a normal query flow (capture from the Response/FeedResponse if loop needs to be stopped). The continuation is valid for the FeedRange used.

Removed APIs

Scaling a FeedToken has been removed.

Closing issues

This PR closes #1228.
This PR closes #1262.
This PR closes #1226.
This PR closes #1225.
This PR closes #1241