[Preview] PriorityBasedExecution: Adds PriorityLevel as a RequestOpti…

…on (#3672)

* Added Priority Level as a Request Option

* Changed Priority Level Low and High to 1 and 2 respectively

* Bumped DirectVersion

* Added made PriorityLevel internal for non preview packages

* Deleted PriorityLevelTests.cs

* Added description of Priority Level in RequestOptions.cs

* Modified comments for PriorityLevel in RequestOptions.cs

* Updated Contracts

* Modified Remarks for PriorityLevel and added see also link.

* Updated contracts

---------

Co-authored-by: Matias Quaranta <ealsur@users.noreply.github.com>

Microsoft.Azure.Cosmos/src/DocumentClient.cs

@@ -6909,6 +6909,11 @@ private INameValueCollection GetRequestHeaders(
                 headers.Set(HttpConstants.HttpHeaders.ConsistencyLevel, options.ConsistencyLevel.ToString());
             }
 
+            if (options.PriorityLevel.HasValue)
+            {
+                headers.Set(HttpConstants.HttpHeaders.PriorityLevel, options.PriorityLevel.ToString());
+            }
+
             if (options.IndexingDirective.HasValue)
             {
                 headers.Set(HttpConstants.HttpHeaders.IndexingDirective, options.IndexingDirective.ToString());

Microsoft.Azure.Cosmos/src/RequestOptions/RequestOptions.cs

@@ -42,11 +42,32 @@ public class RequestOptions
         /// </summary>
         public Action<Headers> AddRequestHeaders { get; set; }
 
+        /// <summary>
+        /// Gets or sets the priority level for a request.
+        /// </summary>
+        /// <remarks>
+        /// Setting priority level only has an effect if Priority Based Execution is enabled.
+        /// If it is not enabled, the priority level is ignored by the backend.
+        /// Default PriorityLevel for each request is treated as High. It can be explicitly set to Low for some requests.
+        /// When Priority based execution is enabled, if there are more requests than the configured RU/S in a second, 
+        /// then Cosmos DB will throttle low priority requests to allow high priority requests to execute.
+        /// This does not limit the throughput available to each priority level. Each priority level can consume the complete
+        /// provisioned throughput in absence of the other. If both priorities are present and the user goes above the
+        /// configured RU/s, low priority requests start getting throttled first to allow execution of mission critical workloads.
+        /// </remarks>
+        /// <seealso href="https://aka.ms/CosmosDB/PriorityBasedExecution"/>
+#if PREVIEW
+        public
+#else
+        internal
+#endif
+        PriorityLevel? PriorityLevel { get; set; }
+
         /// <summary>
         /// Set Request Level Distributed Tracing Options.
         /// </summary>
         internal DistributedTracingOptions DistributedTracingOptions { get; set; }
-        
+
         /// <summary>
         /// Gets or sets the boolean to use effective partition key routing in the cosmos db request.
         /// </summary>
@@ -91,6 +112,11 @@ internal virtual void PopulateRequestOptions(RequestMessage request)
                 request.Headers.Add(HttpConstants.HttpHeaders.IfNoneMatch, this.IfNoneMatchEtag);
             }
 
+            if (this.PriorityLevel.HasValue)
+            {
+                request.Headers.Add(HttpConstants.HttpHeaders.PriorityLevel, this.PriorityLevel.ToString());
+            }
+
             this.AddRequestHeaders?.Invoke(request.Headers);
         }
 

Microsoft.Azure.Cosmos/src/Resource/Settings/PriorityLevel.cs

@@ -0,0 +1,39 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+
+namespace Microsoft.Azure.Cosmos
+{
+    /// <summary> 
+    /// Valid values of Priority Level for a request
+    /// </summary>
+    /// <remarks>
+    /// Setting priority level only has an effect if Priority Based Execution is enabled.
+    /// If it is not enabled, the priority level is ignored by the backend.
+    /// Default PriorityLevel for each request is treated as High. It can be explicitly set to Low for some requests.
+    /// When Priority based execution is enabled, if there are more requests than the configured RU/S in a second, 
+    /// then Cosmos DB will throttle low priority requests to allow high priority requests to execute.
+    /// This does not limit the throughput available to each priority level. Each priority level can consume the complete
+    /// provisioned throughput in absence of the other. If both priorities are present and the user goes above the
+    /// configured RU/s, low priority requests start getting throttled first to allow execution of mission critical workloads.
+    /// </remarks>
+    /// <seealso href="https://aka.ms/CosmosDB/PriorityBasedExecution"/>
+
+#if PREVIEW
+    public
+#else
+    internal
+#endif
+    enum PriorityLevel
+    {
+        /// <summary> 
+        /// High Priority
+        /// </summary>
+        High = 1,
+
+        /// <summary> 
+        /// Low Priority
+        /// </summary>
+        Low = 2,
+    }
+}

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/Contracts/DotNetPreviewSDKAPI.json

@@ -362,6 +362,52 @@
         }
       },
       "NestedTypes": {}
+    },
+    "Microsoft.Azure.Cosmos.PriorityLevel;System.Enum;IsAbstract:False;IsSealed:True;IsInterface:False;IsEnum:True;IsClass:False;IsValueType:True;IsNested:False;IsGenericType:False;IsSerializable:True": {
+      "Subclasses": {},
+      "Members": {
+        "Int32 value__": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": "Int32 value__;IsInitOnly:False;IsStatic:False;"
+        },
+        "Microsoft.Azure.Cosmos.PriorityLevel High": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": "Microsoft.Azure.Cosmos.PriorityLevel High;IsInitOnly:False;IsStatic:True;"
+        },
+        "Microsoft.Azure.Cosmos.PriorityLevel Low": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": "Microsoft.Azure.Cosmos.PriorityLevel Low;IsInitOnly:False;IsStatic:True;"
+        }
+      },
+      "NestedTypes": {}
+    },
+    "Microsoft.Azure.Cosmos.RequestOptions;System.Object;IsAbstract:False;IsSealed:False;IsInterface:False;IsEnum:False;IsClass:True;IsValueType:False;IsNested:False;IsGenericType:False;IsSerializable:False": {
+      "Subclasses": {},
+      "Members": {
+        "System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel] get_PriorityLevel()[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
+          "Type": "Method",
+          "Attributes": [
+            "CompilerGeneratedAttribute"
+          ],
+          "MethodInfo": "System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel] get_PriorityLevel();IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
+        "System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel] PriorityLevel": {
+          "Type": "Property",
+          "Attributes": [],
+          "MethodInfo": "System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel] PriorityLevel;CanRead:True;CanWrite:True;System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel] get_PriorityLevel();IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;Void set_PriorityLevel(System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        },
+        "Void set_PriorityLevel(System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel])[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
+          "Type": "Method",
+          "Attributes": [
+            "CompilerGeneratedAttribute"
+          ],
+          "MethodInfo": "Void set_PriorityLevel(System.Nullable`1[Microsoft.Azure.Cosmos.PriorityLevel]);IsAbstract:False;IsStatic:False;IsVirtual:False;IsGenericMethod:False;IsConstructor:False;IsFinal:False;"
+        }
+      },
+      "NestedTypes": {}
     }
   },
   "Members": {},