Change Feed mode design

Change Feed is introducing in preview shortly the Full Fidelity Change Feed.

The way to enable the retention on a container is defined in PR https://github.com/Azure/azure-cosmos-dotnet-v3/pull/2020.

Once retention has been enabled on a container, the user can consume the change feed in Full Fidelity mode, exposing deletes (within the retention period configured in the container).

The user can still consume Change Feed in the normal mode (Incremental) even if the retention is enabled, so they should be able to select one or the other when starting the Change Feed consumptions.

Because the continuations are valid for both modes, it is also possible to change the mode after capturing some previous continuation, so maintaining the mode as part of the continuation state is not really required.

Proposed API

Exposing a configuration on the ChangeFeedRequestOptions that allows the user to set the mode, similar to the page size hint:

public class ChangeFeedRequestOptions
{

        /// <summary>
        /// Gets or sets the desired mode on which to consume the Change Feed.
        /// </summary>
        /// <value>Default value is <see cref="ChangeFeedMode.Incremental"/>. </value>
        public ChangeFeedMode FeedMode { get; set; } = ChangeFeedRequestOptions.DefaultMode;

}

Following a similar model to StartFrom, the different modes can be implemented as abstract class implementations.

The user can then set the FeedMode to two different values:

• Incremental (default): This is the default Change Feed, the current mode that surfaces creations and replaces.
• Full Fidelity: Available if the container has a retention period defined.

Setting the FeedMode

Setting it to Incremental (the default):

ChangeFeedRequestOptions changeFeedRequestOptions = new ChangeFeedRequestOptions
            {
                FeedMode = ChangeFeedMode.Incremental()
            };

Setting it to Full Fidelity:

ChangeFeedRequestOptions changeFeedRequestOptions = new ChangeFeedRequestOptions
            {
                FeedMode = ChangeFeedMode.FullFidelity()
            };

And use it as part of the iterator:

FeedIterator feedIterator = container.GetChangeFeedStreamIterator(
        ChangeFeedStartFrom.Now(),
        new ChangeFeedRequestOptions()
       {
            FeedMode = ChangeFeedMode.FullFidelity(),
            PageSizeHint = 50
        });

The FeedMode implementation will define the A_IM header correctly to specify the desired mode.

[ealsur]

@DmitryKhilyai, Full Fidelity is still in private preview. When the feature GAs we will certainly add Functions support, it is part of the roadmap.

[ealsur]

We could use an enum, thought it would be cleaner to have an abstract class, like :

public abstract class ChangeFeedMode
{
    internal abstract void Accept(RequestMessage requestMessage);
    public static ChangeFeedMode Incremental()
    {
        return ChangeFeedModeIncremental.Instance;
    }
    
    public static ChangeFeedMode FullFidelity()
    {
        return ChangeFeedModeFullFidelity.Instance;
    }
}

internal sealed class ChangeFeedModeIncremental : ChangeFeedMode
{
    internal override void Accept(RequestMessage requestMessage)
    {
        requestMessage.Headers.Add(HttpConstants.HttpHeaders.A_IM, HttpConstants.A_IMHeaderValues.IncrementalFeed);
    }
}

internal sealed class ChangeFeedModeFullFidelity : ChangeFeedMode
{
    internal override void Accept(RequestMessage requestMessage)
    {
        requestMessage.Headers.Add(HttpConstants.HttpHeaders.A_IM, HttpConstants.A_IMHeaderValues.FullFidelityFeed);
    }
}

So if we need to add more modes, we touch nothing else other than implementing a new type, instead of fishing where the value is and having a switch over an enum.