CSHARP-2808: Support ability to pass hint to update

Author: MikalaiMazurenka

src/MongoDB.Driver.Core/Core/Misc/Feature.cs

@@ -58,6 +58,7 @@ public class Feature
         private static readonly Feature __findCommand = new Feature("FindCommand", new SemanticVersion(3, 2, 0));
         private static readonly Feature __geoNearCommand = new Feature("GeoNearCommand", new SemanticVersion(1, 0, 0), new SemanticVersion(4, 1, 0, ""));
         private static readonly Feature __groupCommand = new Feature("GroupCommand", new SemanticVersion(1, 0, 0), new SemanticVersion(4, 1, 1, ""));
+        private static readonly HintForUpdateAndReplaceOperationsFeature __hintForUpdateAndReplaceOperations = new HintForUpdateAndReplaceOperationsFeature("HintForUpdateAndReplaceOperations", new SemanticVersion(4, 2, 0));
         private static readonly Feature __keepConnectionPoolWhenNotMasterConnectionException = new Feature("KeepConnectionPoolWhenNotMasterConnectionException", new SemanticVersion(4, 1, 10));
         private static readonly Feature __keepConnectionPoolWhenReplSetStepDown = new Feature("KeepConnectionPoolWhenReplSetStepDown", new SemanticVersion(4, 1, 10));
         private static readonly Feature __killCursorsCommand = new Feature("KillCursorsCommand", new SemanticVersion(3, 2, 0));
@@ -258,6 +259,11 @@ public class Feature
         /// </summary>
         public static Feature GroupCommand => __groupCommand;
 
+        /// <summary>
+        /// Gets the hint for write operations feature.
+        /// </summary>
+        public static HintForUpdateAndReplaceOperationsFeature HintForUpdateAndReplaceOperations => __hintForUpdateAndReplaceOperations;
+
         /// <summary>
         /// Gets the keep connection pool when NotMaster connection exception feature.
         /// </summary>

src/MongoDB.Driver.Core/Core/Misc/HintForUpdateAndReplaceOperationsFeature.cs

@@ -0,0 +1,46 @@
+/* Copyright 2020-present MongoDB Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+namespace MongoDB.Driver.Core.Misc
+{
+    /// <summary>
+    /// Represents the hint for update and replace operations feature.
+    /// </summary>
+    /// <seealso cref="MongoDB.Driver.Core.Misc.Feature" />
+    public class HintForUpdateAndReplaceOperationsFeature : Feature
+    {
+        private readonly SemanticVersion _firstServerVersionWhereWeRelyOnServerToReturnError = new SemanticVersion(3, 4, 0);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HintForUpdateAndReplaceOperationsFeature"/> class.
+        /// </summary>
+        /// <param name="name">The name of the feature.</param>
+        /// <param name="firstSupportedVersion">The first server version that supports the feature.</param>
+        public HintForUpdateAndReplaceOperationsFeature(string name, SemanticVersion firstSupportedVersion)
+            : base(name, firstSupportedVersion)
+        {
+        }
+
+        /// <summary>
+        /// Determines whether the driver must throw an exception if the feature is not supported by the server.
+        /// </summary>
+        /// <param name="serverVersion">The server version.</param>
+        /// <returns>Whether the driver must throw if feature is not supported.</returns>
+        public bool DriverMustThrowIfNotSupported(SemanticVersion serverVersion)
+        {
+            return serverVersion < _firstServerVersionWhereWeRelyOnServerToReturnError;
+        }
+    }
+}

src/MongoDB.Driver.Core/Core/Operations/BulkDeleteOperation.cs

@@ -47,5 +47,10 @@ protected override bool RequestHasCollation(DeleteRequest request)
         {
             return request.Collation != null;
         }
+
+        protected override bool RequestHasHint(DeleteRequest request)
+        {
+            return false;
+        }
     }
 }

src/MongoDB.Driver.Core/Core/Operations/BulkInsertOperation.cs

@@ -13,7 +13,6 @@
 * limitations under the License.
 */
 
-using System;
 using System.Collections.Generic;
 using MongoDB.Bson;
 using MongoDB.Bson.Serialization;
@@ -51,6 +50,11 @@ protected override bool RequestHasCollation(InsertRequest request)
             return false;
         }
 
+        protected override bool RequestHasHint(InsertRequest request)
+        {
+            return false;
+        }
+
         // nested types
         private class InsertRequestSerializer : SealedClassSerializerBase<InsertRequest>
         {

src/MongoDB.Driver.Core/Core/Operations/BulkMixedWriteOperation.cs

@@ -214,6 +214,7 @@ public BulkWriteOperationResult Execute(IWriteBinding binding, CancellationToken
             using (var context = RetryableWriteContext.Create(binding, _retryRequested, cancellationToken))
             {
                 EnsureCollationIsSupportedIfAnyRequestHasCollation(context);
+                EnsureHintIsSupportedIfAnyRequestHasHint(context);
                 context.DisableRetriesIfAnyWriteRequestIsNotRetryable(_requests);
                 var helper = new BatchHelper(_requests, _isOrdered, _writeConcern);
                 foreach (var batch in helper.GetBatches())
@@ -231,6 +232,7 @@ public async Task<BulkWriteOperationResult> ExecuteAsync(IWriteBinding binding,
             using (var context = await RetryableWriteContext.CreateAsync(binding, _retryRequested, cancellationToken).ConfigureAwait(false))
             {
                 EnsureCollationIsSupportedIfAnyRequestHasCollation(context);
+                EnsureHintIsSupportedIfAnyRequestHasHint(context);
                 context.DisableRetriesIfAnyWriteRequestIsNotRetryable(_requests);
                 var helper = new BatchHelper(_requests, _isOrdered, _writeConcern);
                 foreach (var batch in helper.GetBatches())
@@ -309,6 +311,21 @@ private void EnsureCollationIsSupportedIfAnyRequestHasCollation(RetryableWriteCo
             }
         }
 
+        private void EnsureHintIsSupportedIfAnyRequestHasHint(RetryableWriteContext context)
+        {
+            var serverVersion = context.Channel.ConnectionDescription.ServerVersion;
+            if (Feature.HintForUpdateAndReplaceOperations.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                foreach (var request in _requests)
+                {
+                    if (RequestHasHint(request))
+                    {
+                        throw new NotSupportedException($"Server version {serverVersion} does not support hints.");
+                    }
+                }
+            }
+        }
+
         private BulkWriteBatchResult ExecuteBatch(RetryableWriteContext context, Batch batch, CancellationToken cancellationToken)
         {
             BulkWriteOperationResult result;
@@ -362,6 +379,11 @@ private bool RequestHasCollation(WriteRequest request)
             return false;
         }
 
+        private bool RequestHasHint(WriteRequest request)
+        {
+            return request is UpdateRequest updateRequest && updateRequest.Hint != null;
+        }
+
         // nested types
         private class Batch
         {

src/MongoDB.Driver.Core/Core/Operations/BulkUnmixedWriteOperationBase.cs

@@ -116,6 +116,7 @@ public WriteConcern WriteConcern
         public BulkWriteOperationResult Execute(RetryableWriteContext context, CancellationToken cancellationToken)
         {
             EnsureCollationIsSupportedIfAnyRequestHasCollation(context, _requests);
+            EnsureHintIsSupportedIfAnyRequestHasHint(context, _requests);
 
             return ExecuteBatches(context, cancellationToken);
         }
@@ -133,6 +134,7 @@ public BulkWriteOperationResult Execute(IWriteBinding binding, CancellationToken
         public Task<BulkWriteOperationResult> ExecuteAsync(RetryableWriteContext context, CancellationToken cancellationToken)
         {
             EnsureCollationIsSupportedIfAnyRequestHasCollation(context, _requests);
+            EnsureHintIsSupportedIfAnyRequestHasHint(context, _requests);
 
             return ExecuteBatchesAsync(context, cancellationToken);
         }
@@ -152,6 +154,8 @@ public async Task<BulkWriteOperationResult> ExecuteAsync(IWriteBinding binding,
 
         protected abstract bool RequestHasCollation(TWriteRequest request);
 
+        protected abstract bool RequestHasHint(TWriteRequest request);
+
         // private methods
         private BulkWriteBatchResult CreateBatchResult(Batch batch, BsonDocument writeCommandResult)
         {
@@ -179,6 +183,22 @@ private void EnsureCollationIsSupportedIfAnyRequestHasCollation(RetryableWriteCo
                 }
             }
         }
+
+        private void EnsureHintIsSupportedIfAnyRequestHasHint(RetryableWriteContext context, IEnumerable<TWriteRequest> requests)
+        {
+            var serverVersion = context.Channel.ConnectionDescription.ServerVersion;
+            if (Feature.HintForUpdateAndReplaceOperations.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                foreach (var request in requests)
+                {
+                    if (RequestHasHint(request))
+                    {
+                        throw new NotSupportedException($"Server version {serverVersion} does not support hints.");
+                    }
+                }
+            }
+        }
+
         private BulkWriteBatchResult ExecuteBatch(RetryableWriteContext context, Batch batch, CancellationToken cancellationToken)
         {
             var operation = CreateBatchOperation(batch);

src/MongoDB.Driver.Core/Core/Operations/BulkUpdateOperation.cs

@@ -48,5 +48,10 @@ protected override bool RequestHasCollation(UpdateRequest request)
         {
             return request.Collation != null;
         }
+
+        protected override bool RequestHasHint(UpdateRequest request)
+        {
+            return request.Hint != null;
+        }
     }
 }

src/MongoDB.Driver.Core/Core/Operations/RetryableUpdateCommandOperation.cs

@@ -108,6 +108,13 @@ protected override BsonDocument CreateCommand(ICoreSessionHandle session, Connec
                     throw new NotSupportedException($"Server version {serverVersion} does not support arrayFilters.");
                 }
             }
+            if (Feature.HintForUpdateAndReplaceOperations.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                if (_updates.Items.Skip(_updates.Offset).Take(_updates.Count).Any(u => u.Hint != null))
+                {
+                    throw new NotSupportedException($"Server version {serverVersion} does not support hints.");
+                }
+            }
 
             var writeConcern = WriteConcernHelper.GetWriteConcernForWriteCommand(session, WriteConcern);
             return new BsonDocument
@@ -176,6 +183,11 @@ protected override void SerializeValue(BsonSerializationContext context, BsonSer
                     }
                     writer.WriteEndArray();
                 }
+                if (value.Hint != null)
+                {
+                    writer.WriteName("hint");
+                    BsonValueSerializer.Instance.Serialize(context, value.Hint);
+                }
                 writer.WriteEndDocument();
             }
 

src/MongoDB.Driver.Core/Core/Operations/UpdateRequest.cs

@@ -30,6 +30,7 @@ public sealed class UpdateRequest : WriteRequest
         private IEnumerable<BsonDocument> _arrayFilters;
         private Collation _collation;
         private readonly BsonDocument _filter;
+        private BsonValue _hint;
         private bool _isMulti;
         private bool _isUpsert;
         private readonly BsonValue _update;
@@ -80,6 +81,15 @@ public BsonDocument Filter
             get { return _filter; }
         }
 
+        /// <summary>
+        /// Gets or sets the hint.
+        /// </summary>
+        public BsonValue Hint
+        {
+            get { return _hint; }
+            set { _hint = value; }
+        }
+
         /// <summary>
         /// Gets or sets a value indicating whether this update should affect all matching documents.
         /// </summary>

src/MongoDB.Driver/FilteredMongoCollectionBase.cs

@@ -341,6 +341,7 @@ private IEnumerable<WriteModel<TDocument>> CombineModelFilters(IEnumerable<Write
                         return new ReplaceOneModel<TDocument>(CombineFilters(replaceOneModel.Filter), replaceOneModel.Replacement)
                         {
                             Collation = replaceOneModel.Collation,
+                            Hint = replaceOneModel.Hint,
                             IsUpsert = replaceOneModel.IsUpsert
                         };
                     case WriteModelType.UpdateMany:
@@ -349,6 +350,7 @@ private IEnumerable<WriteModel<TDocument>> CombineModelFilters(IEnumerable<Write
                         {
                             ArrayFilters = updateManyModel.ArrayFilters,
                             Collation = updateManyModel.Collation,
+                            Hint = updateManyModel.Hint,
                             IsUpsert = updateManyModel.IsUpsert
                         };
                     case WriteModelType.UpdateOne:
@@ -357,6 +359,7 @@ private IEnumerable<WriteModel<TDocument>> CombineModelFilters(IEnumerable<Write
                         {
                             ArrayFilters = updateOneModel.ArrayFilters,
                             Collation = updateOneModel.Collation,
+                            Hint = updateOneModel.Hint,
                             IsUpsert = updateOneModel.IsUpsert
                         };
                     default: