Add PortReuseMode to CosmosClientOptions

Microsoft.Azure.Cosmos/src/ConnectionPolicy.cs

@@ -379,6 +379,18 @@ public int? MaxTcpConnectionsPerEndpoint
             set;
         }
 
+        /// <summary>
+        /// (Direct/TCP) Controls the client port reuse policy used by the transport stack.
+        /// </summary>
+        /// <value>
+        /// The default value is PortReuseMode.ReuseUnicastPort.
+        /// </value>
+        public PortReuseMode? PortReuseMode
+        {
+            get;
+            set;
+        }
+
         /// <summary>
         /// (Direct/TCP) This is an advanced setting that controls the number of TCP connections that will be opened eagerly to each Cosmos DB back-end.
         /// </summary>

Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs

@@ -62,6 +62,7 @@ public class CosmosClientOptions
         private TimeSpan? openTcpConnectionTimeout;
         private int? maxRequestsPerTcpConnection;
         private int? maxTcpConnectionsPerEndpoint;
+        private PortReuseMode? portReuseMode;
         private IWebProxy webProxy;
 
         /// <summary>
@@ -274,6 +275,27 @@ public int? MaxTcpConnectionsPerEndpoint
             }
         }
 
+        /// <summary>
+        /// (Direct/TCP) Controls the client port reuse policy used by the transport stack.
+        /// </summary>
+        /// <value>
+        /// The default value is PortReuseMode.ReuseUnicastPort.
+        /// </value>
+        /// <remarks>
+        /// ReuseUnicastPort and PrivatePortPool are not mutually exclusive.
+        /// When PrivatePortPool is enabled, the client first tries to reuse a port it already has.
+        /// It falls back to allocating a new port if the initial attempts failed. If this fails, too, the client then falls back to ReuseUnicastPort.
+        /// </remarks>
+        public PortReuseMode? PortReuseMode
+        {
+            get => this.portReuseMode;
+            set
+            {
+                this.portReuseMode = value;
+                this.ValidateDirectTCPSettings();
+            }
+        }
+
         /// <summary>
         /// (Gateway/Https) Get or set the proxy information used for web requests.
         /// </summary>
@@ -522,7 +544,8 @@ internal ConnectionPolicy GetConnectionPolicy()
                 OpenTcpConnectionTimeout = this.OpenTcpConnectionTimeout,
                 MaxRequestsPerTcpConnection = this.MaxRequestsPerTcpConnection,
                 MaxTcpConnectionsPerEndpoint = this.MaxTcpConnectionsPerEndpoint,
-                EnableEndpointDiscovery = !this.LimitToEndpoint
+                EnableEndpointDiscovery = !this.LimitToEndpoint,
+                PortReuseMode = this.portReuseMode
             };
 
             if (this.ApplicationRegion != null)
@@ -650,6 +673,10 @@ private void ValidateDirectTCPSettings()
                 {
                     settingName = nameof(this.MaxTcpConnectionsPerEndpoint);
                 }
+                else if (this.PortReuseMode.HasValue)
+                {
+                    settingName = nameof(this.PortReuseMode);
+                }
             }
 
             if (!string.IsNullOrEmpty(settingName))

Microsoft.Azure.Cosmos/src/DocumentClient.cs

@@ -84,6 +84,7 @@ internal partial class DocumentClient : IDisposable, IAuthorizationTokenProvider
         private const string MaxRequestsPerChannelConfig = "CosmosDbMaxRequestsPerTcpChannel";
         private const string TcpPartitionCount = "CosmosDbTcpPartitionCount";
         private const string MaxChannelsPerHostConfig = "CosmosDbMaxTcpChannelsPerHost";
+        private const string RntbdPortReuseMode = "CosmosDbTcpPortReusePolicy";
         private const string RntbdReceiveHangDetectionTimeConfig = "CosmosDbTcpReceiveHangDetectionTimeSeconds";
         private const string RntbdSendHangDetectionTimeConfig = "CosmosDbTcpSendHangDetectionTimeSeconds";
         private const string EnableCpuMonitorConfig = "CosmosDbEnableCpuMonitor";
@@ -96,6 +97,7 @@ internal partial class DocumentClient : IDisposable, IAuthorizationTokenProvider
         private const int DefaultMaxRequestsPerRntbdChannel = 30;
         private const int DefaultRntbdPartitionCount = 1;
         private const int DefaultMaxRntbdChannelsPerHost = ushort.MaxValue;
+        private const PortReuseMode DefaultRntbdPortReuseMode = PortReuseMode.ReuseUnicastPort;
         private const int DefaultRntbdReceiveHangDetectionTimeSeconds = 65;
         private const int DefaultRntbdSendHangDetectionTimeSeconds = 10;
         private const bool DefaultEnableCpuMonitor = true;
@@ -112,6 +114,7 @@ internal partial class DocumentClient : IDisposable, IAuthorizationTokenProvider
         private int maxRequestsPerRntbdChannel = DefaultMaxRequestsPerRntbdChannel;
         private int rntbdPartitionCount = DefaultRntbdPartitionCount;
         private int maxRntbdChannels = DefaultMaxRntbdChannelsPerHost;
+        private PortReuseMode rntbdPortReuseMode = DefaultRntbdPortReuseMode;
         private int rntbdReceiveHangDetectionTimeSeconds = DefaultRntbdReceiveHangDetectionTimeSeconds;
         private int rntbdSendHangDetectionTimeSeconds = DefaultRntbdSendHangDetectionTimeSeconds;
         private bool enableCpuMonitor = DefaultEnableCpuMonitor;
@@ -912,6 +915,16 @@ internal virtual void Initialize(Uri serviceEndpoint,
                     }
                 }
 
+                string rntbdPortReuseModeOverrideString = System.Configuration.ConfigurationManager.AppSettings[DocumentClient.RntbdPortReuseMode];
+                if (!string.IsNullOrEmpty(rntbdPortReuseModeOverrideString))
+                {
+                    PortReuseMode portReuseMode = DefaultRntbdPortReuseMode;
+                    if (Enum.TryParse<PortReuseMode>(rntbdPortReuseModeOverrideString, out portReuseMode))
+                    {
+                        this.rntbdPortReuseMode = portReuseMode;
+                    }
+                }
+
                 string rntbdReceiveHangDetectionTimeSecondsString = System.Configuration.ConfigurationManager.AppSettings[DocumentClient.RntbdReceiveHangDetectionTimeConfig];
                 if (!string.IsNullOrEmpty(rntbdReceiveHangDetectionTimeSecondsString))
                 {
@@ -980,6 +993,11 @@ internal virtual void Initialize(Uri serviceEndpoint,
                 {
                     this.maxRntbdChannels = this.ConnectionPolicy.MaxTcpConnectionsPerEndpoint.Value;
                 }
+
+                if (this.ConnectionPolicy.PortReuseMode.HasValue)
+                {
+                    this.rntbdPortReuseMode = this.ConnectionPolicy.PortReuseMode.Value;
+                }
             }
 
             this.ServiceEndpoint = serviceEndpoint.OriginalString.EndsWith("/", StringComparison.Ordinal) ? serviceEndpoint : new Uri(serviceEndpoint.OriginalString + "/");
@@ -6480,7 +6498,8 @@ private void InitializeDirectConnectivity(IStoreClientFactory storeClientFactory
                     receiveHangDetectionTimeSeconds: this.rntbdReceiveHangDetectionTimeSeconds,
                     sendHangDetectionTimeSeconds: this.rntbdSendHangDetectionTimeSeconds,
                     enableCpuMonitor: this.enableCpuMonitor,
-                    retryWithConfiguration: this.connectionPolicy.RetryOptions?.GetRetryWithConfiguration());
+                    retryWithConfiguration: this.connectionPolicy.RetryOptions?.GetRetryWithConfiguration(),
+                    rntbdPortReuseMode: (Documents.PortReuseMode)this.rntbdPortReuseMode);
 
                 if (this.transportClientHandlerFactory != null)
                 {

Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs

@@ -230,6 +230,10 @@ public CosmosClientBuilder WithConnectionModeDirect()
         /// Together with MaxRequestsPerTcpConnection, this setting limits the number of requests that are simultaneously sent to a single Cosmos DB back-end(MaxRequestsPerTcpConnection x MaxTcpConnectionPerEndpoint).
         /// The default value is 65,535. Value must be greater than or equal to 16.
         /// </param>
+        /// <param name="portReuseMode">
+        /// (Direct/TCP) Controls the client port reuse policy used by the transport stack.
+        /// The default value is PortReuseMode.ReuseUnicastPort.
+        /// </param>
         /// <remarks>
         /// For more information, see <see href="https://docs.microsoft.com/azure/documentdb/documentdb-performance-tips#direct-connection">Connection policy: Use direct connection mode</see>.
         /// </remarks>
@@ -238,12 +242,14 @@ public CosmosClientBuilder WithConnectionModeDirect()
         internal CosmosClientBuilder WithConnectionModeDirect(TimeSpan? idleTcpConnectionTimeout = null,
             TimeSpan? openTcpConnectionTimeout = null,
             int? maxRequestsPerTcpConnection = null,
-            int? maxTcpConnectionsPerEndpoint = null)
+            int? maxTcpConnectionsPerEndpoint = null,
+            Cosmos.PortReuseMode? portReuseMode = null)
         {
             this.clientOptions.IdleTcpConnectionTimeout = idleTcpConnectionTimeout;
             this.clientOptions.OpenTcpConnectionTimeout = openTcpConnectionTimeout;
             this.clientOptions.MaxRequestsPerTcpConnection = maxRequestsPerTcpConnection;
             this.clientOptions.MaxTcpConnectionsPerEndpoint = maxTcpConnectionsPerEndpoint;
+            this.clientOptions.PortReuseMode = portReuseMode;
 
             this.clientOptions.ConnectionMode = ConnectionMode.Direct;
             this.clientOptions.ConnectionProtocol = Protocol.Tcp;

Microsoft.Azure.Cosmos/src/PortReuseMode.cs

@@ -0,0 +1,28 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+namespace Microsoft.Azure.Cosmos
+{
+    /// <summary>
+    /// Port reuse policy options used by the transport stack
+    /// </summary>
+    public enum PortReuseMode
+    {
+        /// <summary>
+        /// Windows Server 2016 and newer: Uses the SO_REUSE_UNICASTPORT option if the operating system has automatic client port reuse enabled.
+        /// Older versions of Windows, Linux, other: Uses default socket options.
+        /// </summary>
+        /// <remarks>
+        /// see also
+        /// https://docs.microsoft.com/en-us/windows/win32/winsock/sol-socket-socket-options
+        /// https://docs.microsoft.com/en-us/powershell/module/nettcpip/set-nettcpsetting?view=win10-ps
+        /// https://support.microsoft.com/en-us/help/3149157/reliability-and-scalability-improvements-in-tcp-ip-for-windows-8-1-and
+        /// </remarks>
+        ReuseUnicastPort = 0,
+        /// <summary>
+        /// Windows: Tracks client ports used by the Cosmos DB client and reuses them. Ports are reused at DocumentClient scope.
+        /// Linux: Uses default socket options.
+        /// </summary>
+        PrivatePortPool = 1,
+    }
+}

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/CosmosClientOptionsUnitTests.cs

@@ -6,6 +6,7 @@ namespace Microsoft.Azure.Cosmos.Tests
 {
     using System;
     using System.IO;
+    using System.Linq;
     using System.Net;
     using System.Net.Http;
     using Microsoft.Azure.Cosmos.Client.Core.Tests;
@@ -44,6 +45,7 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
             TimeSpan openTcpConnectionTimeout = new TimeSpan(0, 0, 5);
             int maxRequestsPerTcpConnection = 30;
             int maxTcpConnectionsPerEndpoint = 65535;
+            Cosmos.PortReuseMode portReuseMode = Cosmos.PortReuseMode.PrivatePortPool;
             IWebProxy webProxy = new TestWebProxy();
 
             CosmosClientBuilder cosmosClientBuilder = new CosmosClientBuilder(
@@ -131,7 +133,8 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
                 idleTcpConnectionTimeout,
                 openTcpConnectionTimeout,
                 maxRequestsPerTcpConnection,
-                maxTcpConnectionsPerEndpoint
+                maxTcpConnectionsPerEndpoint,
+                portReuseMode
             );
 
             cosmosClient = cosmosClientBuilder.Build(new MockDocumentClient());
@@ -142,13 +145,29 @@ public void VerifyCosmosConfigurationPropertiesGetUpdated()
             Assert.AreEqual(openTcpConnectionTimeout, clientOptions.OpenTcpConnectionTimeout);
             Assert.AreEqual(maxRequestsPerTcpConnection, clientOptions.MaxRequestsPerTcpConnection);
             Assert.AreEqual(maxTcpConnectionsPerEndpoint, clientOptions.MaxTcpConnectionsPerEndpoint);
+            Assert.AreEqual(portReuseMode, clientOptions.PortReuseMode);
 
             //Verify GetConnectionPolicy returns the correct values
             policy = clientOptions.GetConnectionPolicy();
             Assert.AreEqual(idleTcpConnectionTimeout, policy.IdleTcpConnectionTimeout);
             Assert.AreEqual(openTcpConnectionTimeout, policy.OpenTcpConnectionTimeout);
             Assert.AreEqual(maxRequestsPerTcpConnection, policy.MaxRequestsPerTcpConnection);
             Assert.AreEqual(maxTcpConnectionsPerEndpoint, policy.MaxTcpConnectionsPerEndpoint);
+            Assert.AreEqual(portReuseMode, policy.PortReuseMode);
+        }
+
+        [TestMethod]
+        public void VerifyPortReuseModeIsSyncedWithDirect()
+        {
+            CollectionAssert.AreEqual(
+                Enum.GetNames(typeof(PortReuseMode)).OrderBy(x => x).ToArray(),
+                Enum.GetNames(typeof(Cosmos.PortReuseMode)).OrderBy(x => x).ToArray()
+            );
+
+            CollectionAssert.AreEqual(
+                Enum.GetValues(typeof(PortReuseMode)).Cast<int>().ToArray(),
+                Enum.GetValues(typeof(Cosmos.PortReuseMode)).Cast<int>().ToArray()
+            );
         }
 
         [TestMethod]

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/DotNetSDKAPI.json

@@ -1346,6 +1346,16 @@
           ],
           "MethodInfo": "System.Nullable`1[Microsoft.Azure.Cosmos.ConsistencyLevel] get_ConsistencyLevel()"
         },
+        "System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode] get_PortReuseMode()": {
+          "Type": "Method",
+          "Attributes": [],
+          "MethodInfo": "System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode] get_PortReuseMode()"
+        },
+        "System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode] PortReuseMode": {
+          "Type": "Property",
+          "Attributes": [],
+          "MethodInfo": null
+        },
         "System.Nullable`1[System.Int32] get_MaxRequestsPerTcpConnection()": {
           "Type": "Method",
           "Attributes": [],
@@ -1530,6 +1540,11 @@
           "Attributes": [],
           "MethodInfo": "Void set_OpenTcpConnectionTimeout(System.Nullable`1[System.TimeSpan])"
         },
+        "Void set_PortReuseMode(System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode])": {
+          "Type": "Method",
+          "Attributes": [],
+          "MethodInfo": "Void set_PortReuseMode(System.Nullable`1[Microsoft.Azure.Cosmos.PortReuseMode])"
+        },
         "Void set_RequestTimeout(System.TimeSpan)[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]": {
           "Type": "Method",
           "Attributes": [
@@ -3737,6 +3752,27 @@
       },
       "NestedTypes": {}
     },
+    "PortReuseMode": {
+      "Subclasses": {},
+      "Members": {
+        "Int32 value__": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": null
+        },
+        "Microsoft.Azure.Cosmos.PortReuseMode PrivatePortPool": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": null
+        },
+        "Microsoft.Azure.Cosmos.PortReuseMode ReuseUnicastPort": {
+          "Type": "Field",
+          "Attributes": [],
+          "MethodInfo": null
+        }
+      },
+      "NestedTypes": {}
+    },
     "QueryDefinition": {
       "Subclasses": {},
       "Members": {

changelog.md

@@ -9,13 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- [#995](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/995) Included session token in diagnostics
+- [#995](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/995) Included session token in diagnostics.
+- [#1000](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/1000) Add PortReuseMode to CosmosClientOptions.
 
 ### Fixed
 
 - [#944](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/944) Change Feed Processor won't use user serializer for internal operations
 
-
 ## <a name="3.4.1"/> [3.4.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.4.1) - 2019-11-06
 
 ### Fixed