[Internal] - Introduce Binary Encoding in .NET v3 SDK

[kundadebdatta]

Description

This PR introduces binary encoding support on request and responses for different Point operations.

What is Binary Encoding?

As the name suggests, binary encoding is a encoding mechanism through which the request payload will be encoded to binary first and sent to backend for processing. Decoding to Text will happen on the response path. The biggest benefit of binary encoding is to reduce cost on backend storage which helps to reduce the overall COGS.

Scope

The point operations that are currently in and out of scope for binary encoding are given below in tabular format:

Operations Currently in Scope	Operations Currently Out of Scope	Reason for Out of Scope
CreateItemAsync()	PatchItemAsync()	Operation Currently not Supported in BE
CreateItemStreamAsync()	PatchItemStreamAsync()	Operation Currently not Supported in BE
ReadItemAsync()	TransactionalBatches	Operation Currently not Supported in BE
ReadItemStreamAsync()	Bulk APIs	Operation Currently not Supported in BE
UpsertItemAsync()
UpsertItemStreamAsync()
RepalceItemAsync()
ReplaceItemStreamAsync()
DeleteItemAsync()
DeleteItemStreamAsync()

How to Enable Binary Encoding?

This PR introduces a new environment variable AZURE_COSMOS_BINARY_ENCODING_ENABLED to opt-in or opt-out the binary encoding feature on demand. Setting this environment variable to True will enable Binary encoding support.

How Binary Encoding has been Achieved?

The binary encoding in the .NET SDK has been divided into two parts which are applicable differently for ItemAsync() and ItemStreamAsync() apis. The details are given below:

• ItemAsync() APIs: Currently the CosmosJsonDotNetSerializer has been refactored to read and write the binary bits directly into the stream. This reduces any conversion of the text stream to binary and vice versa and makes the serialization and de-serialization process even faster.

• ItemStreamAsync() APIs: For these APIs, there are literally no serializes involved and the stream is returned directly to the caller. Therefore, this flow converts a Text stream into Binary and does the opposite on the response path. Conversion is a little bit costlier operation, in comparison with directly writing the binary stream using the serializer. Note that, irrespective of the binary encoding feature enabled or disabled, the output stream will always be in Text format, unless otherwise requested explicitly.

Are There Any Way to Request Binary Bits on Response?

The answer is yes. We introduced a new internal request option: EnableBinaryResponseOnPointOperations in the ItemRequestOptions, and setting this flag to True will not do any Text conversation, and will return the raw binary bits to the caller. However, please note that this option is applicable only for the ItemStreamAsync() APIs and will be helpful for some of the internal teams.

Flow Diagrams

To understand the changes better, please take a look at the flow diagrams below for both ItemAsync() and ItemStreamAsync() APIs.

Flow Diagram for ItemAsync() APIs that are in Scope per the Above Table:

flowchart TD
    A[All 'ItemAsync' APIs in Scope] -->|SerializerCore.ToStream| B{Select <br> Serializer}
    B -->|One| C[CosmosJsonDotNetSerializer]
    B -->|Two| D[CosmosSystemTextJsonSerializer]
    B -->|Three| E[Any Custom <br> Serializer]
    C -->|Serialize to <br> Binary Stream| F[ContainerCore<br>.ProcessItemStreamAsync]
    D -->|Serialize to <br> Text Stream| F[ContainerCore<br>.ProcessItemStreamAsync]
    E -->|Stream may or <br> may not be <br> Serialized to Binary| F[ContainerCore<br>.ProcessItemStreamAsync]
    F --> G{Is Input <br> Stream in <br> Binary ?}
    G -->|True| I[ProcessResourceOperationStreamAsync]
    G -->|False| H[Convert Input Text <br> Stream to <br> Binary Stream]
    H --> I 
    I --> |SendAsync| J[RequestInvokerHandler]
    J --> |Sets following headers to request response in binary format: 
    x-ms-cosmos-supported-serialization-formats = CosmosBinary
    x-ms-documentdb-content-serialization-format = CosmosBinary| K[TransportHandler]
    K --> |Binary Response <br> Stream|L[ContainerCore<br>.ProcessItemStreamAsync]
    L --> |Note: No explicit conversion to binary stream happens because we let the serializer directly de-serialize the binary stream into text. SerializerCore.FromStream| M{Select <br> Serializer}
    M -->|One| N[CosmosJsonDotNetSerializer]
    M -->|Two| O[CosmosSystemTextJsonSerializer]
    M -->|Three| P[Any Custom <br> Serializer]    
    N -->|De-Serialize to <br> Text Stream| Q[Container<br>.ItemAsync Response]
    O -->|De-Serialize to <br> Text Stream| Q[Container<br>.ItemAsync Response]
    P -->|Stream may or <br> may not be <br> De-Serialized to Text| Q[Container<br>.ItemAsync Response <br> in Text]

Loading

Flow Diagram for ItemStreamAsync() APIs that are in Scope per the Above Table:

flowchart TD
    A[All 'ItemStreamAsync' APIs in Scope]
    A -->|Stream may or <br> may not be <br> Serialized to Binary| F[ContainerCore<br>.ProcessItemStreamAsync]
    F --> G{Is Input <br> Stream in <br> Binary ?}
    G -->|True| I[ProcessResourceOperationStreamAsync]
    G -->|False| H[Convert Input Text <br> Stream to <br> Binary Stream]
    H --> I 
    I --> |SendAsync| J[RequestInvokerHandler]
    J --> |Sets following headers to get binary response: 
    x-ms-cosmos-supported-serialization-formats = CosmosBinary
    x-ms-documentdb-content-serialization-format = CosmosBinary| K[TransportHandler]
    K --> |Binary Response <br> Stream|L[ContainerCore<br>.ProcessItemStreamAsync]
    L --> M{Is Response <br> Stream in <br> Binary ?}
    M -->|Yes| N[CosmosSerializationUtil]
    M -->|No| Q
    N -->|Convert Binary Stream to <br> Text Stream| Q[Container<br>.ItemAsync Response]

Loading

Tasks

Beta Give feedback

1. Binary Encoding - Add Support for Point Operations #4644
   BinaryEncoding Selenium +2
   
2. Binary Encoding - Add Support for Change Feed Operations #4645
   BinaryEncoding +1
   
3. Binary Encoding - Fix Existing Serialization Gaps on Newtonsoft Reader and Writer #4719
   BinaryEncoding +1
   
4. Binary Encoding - Introduce Object Pooling to use Memory Stream Across Serializers #4720
   BinaryEncoding +1
5. Binary Encoding - Add Enable/ Disable Support for Per Request Model #4721
   BinaryEncoding +1
6. Binary Encoding - Add/ Extend Performance Tests and Support for End to End Validation #4722
   BinaryEncoding +1
   
7. Binary Encoding - Add Bulk, Batch and Patch Support when Backend starts Supporting Those Operations #4723
   BinaryEncoding +1
8. Binary Encoding - Optimize CosmosBufferedStreamWrapper to Support Seekable and Non-Seekable Streams #4784
   BinaryEncoding +1
   
9. Binary Encoding - Create/ Update Emulator Tests to Validate Database/ Container Creation With Binary Encoding Enabled #4821
   needs-investigation +1
   
10. Binary Encoding - Optimize Internal Types Detection Logic #4844
    needs-investigation +1