CSHARP-2840: Allow passing hint to findAndModify update and replace operations

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 HintForFindAndModifyFeature __hintForFindAndModifyFeature = new HintForFindAndModifyFeature("HintForFindAndModify", new SemanticVersion(4, 3, 0, ""));
         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));
@@ -259,6 +260,11 @@ public class Feature
         /// </summary>
         public static Feature GroupCommand => __groupCommand;
 
+        /// <summary>
+        /// Gets the hint for find and modify operations feature.
+        /// </summary>
+        public static HintForFindAndModifyFeature HintForFindAndModifyFeature => __hintForFindAndModifyFeature;
+
         /// <summary>
         /// Gets the hint for write operations feature.
         /// </summary>

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

@@ -0,0 +1,45 @@
+/* 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 find and modify feature.
+    /// </summary>
+    public class HintForFindAndModifyFeature : Feature
+    {
+        private readonly SemanticVersion _firstServerVersionWhereWeRelyOnServerToReturnError = new SemanticVersion(4, 2, 0);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HintForFindAndModifyFeature"/> class.
+        /// </summary>
+        /// <param name="name">The name of the feature.</param>
+        /// <param name="firstSupportedVersion">The first server version that supports the feature.</param>
+        public HintForFindAndModifyFeature(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/FindOneAndReplaceOperation.cs

@@ -14,10 +14,6 @@
 */
 
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 using MongoDB.Bson;
 using MongoDB.Bson.IO;
 using MongoDB.Bson.Serialization;
@@ -39,6 +35,7 @@ public class FindOneAndReplaceOperation<TResult> : FindAndModifyOperationBase<TR
         // fields
         private bool? _bypassDocumentValidation;
         private readonly BsonDocument _filter;
+        private BsonValue _hint;
         private bool _isUpsert;
         private TimeSpan? _maxTime;
         private BsonDocument _projection;
@@ -87,6 +84,18 @@ public BsonDocument Filter
             get { return _filter; }
         }
 
+        /// <summary>
+        /// Gets or sets the hint.
+        /// </summary>
+        /// <value>
+        /// The hint.
+        /// </value>
+        public BsonValue Hint
+        {
+            get { return _hint; }
+            set { _hint = value; }
+        }
+
         /// <summary>
         /// Gets a value indicating whether a document should be inserted if no matching document is found.
         /// </summary>
@@ -163,6 +172,13 @@ internal override BsonDocument CreateCommand(ICoreSessionHandle session, Connect
         {
             var serverVersion = connectionDescription.ServerVersion;
             Feature.Collation.ThrowIfNotSupported(serverVersion, Collation);
+            if (Feature.HintForFindAndModifyFeature.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                if (_hint != null)
+                {
+                    throw new NotSupportedException($"Server version {serverVersion} does not support hints.");
+                }
+            }
 
             var writeConcern = WriteConcernHelper.GetWriteConcernForCommand(session, WriteConcern, serverVersion, Feature.FindAndModifyWriteConcern);
             return new BsonDocument
@@ -178,6 +194,7 @@ internal override BsonDocument CreateCommand(ICoreSessionHandle session, Connect
                 { "writeConcern", writeConcern, writeConcern != null },
                 { "bypassDocumentValidation", () => _bypassDocumentValidation.Value, _bypassDocumentValidation.HasValue && Feature.BypassDocumentValidation.IsSupported(serverVersion) },
                 { "collation", () => Collation.ToBsonDocument(), Collation != null },
+                { "hint", () => _hint, _hint != null },
                 { "txnNumber", () => transactionNumber, transactionNumber.HasValue }
             };
         }

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

@@ -37,6 +37,7 @@ public class FindOneAndUpdateOperation<TResult> : FindAndModifyOperationBase<TRe
         private IEnumerable<BsonDocument> _arrayFilters;
         private bool? _bypassDocumentValidation;
         private readonly BsonDocument _filter;
+        private BsonValue _hint;
         private bool _isUpsert;
         private TimeSpan? _maxTime;
         private BsonDocument _projection;
@@ -97,6 +98,18 @@ public BsonDocument Filter
             get { return _filter; }
         }
 
+        /// <summary>
+        /// Gets or sets the hint.
+        /// </summary>
+        /// <value>
+        /// The hint.
+        /// </value>
+        public BsonValue Hint
+        {
+            get { return _hint; }
+            set { _hint = value; }
+        }
+
         /// <summary>
         /// Gets a value indicating whether a document should be inserted if no matching document is found.
         /// </summary>
@@ -173,6 +186,13 @@ internal override BsonDocument CreateCommand(ICoreSessionHandle session, Connect
         {
             var serverVersion = connectionDescription.ServerVersion;
             Feature.Collation.ThrowIfNotSupported(serverVersion, Collation);
+            if (Feature.HintForFindAndModifyFeature.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                if (_hint != null)
+                {
+                    throw new NotSupportedException($"Server version {serverVersion} does not support hints.");
+                }
+            }
 
             var writeConcern = WriteConcernHelper.GetWriteConcernForCommand(session, WriteConcern, serverVersion, Feature.FindAndModifyWriteConcern);
             return new BsonDocument
@@ -188,6 +208,7 @@ internal override BsonDocument CreateCommand(ICoreSessionHandle session, Connect
                 { "writeConcern", writeConcern, writeConcern != null },
                 { "bypassDocumentValidation", () => _bypassDocumentValidation.Value, _bypassDocumentValidation.HasValue && Feature.BypassDocumentValidation.IsSupported(serverVersion) },
                 { "collation", () => Collation.ToBsonDocument(), Collation != null },
+                { "hint", () => _hint, _hint != null },
                 { "arrayFilters", () => new BsonArray(_arrayFilters), _arrayFilters != null },
                 { "txnNumber", () => transactionNumber, transactionNumber.HasValue }
             };

src/MongoDB.Driver/FindOneAndReplaceOptions.cs

@@ -14,6 +14,7 @@
 */
 
 using System;
+using MongoDB.Bson;
 using MongoDB.Driver.Core.Misc;
 
 namespace MongoDB.Driver
@@ -28,6 +29,7 @@ public class FindOneAndReplaceOptions<TDocument, TProjection>
         // fields
         private bool? _bypassDocumentValidation;
         private Collation _collation;
+        private BsonValue _hint;
         private bool _isUpsert;
         private TimeSpan? _maxTime;
         private ProjectionDefinition<TDocument, TProjection> _projection;
@@ -44,6 +46,15 @@ public FindOneAndReplaceOptions()
         }
 
         // properties
+        /// <summary>
+        /// Gets or sets a value indicating whether to bypass document validation.
+        /// </summary>
+        public bool? BypassDocumentValidation
+        {
+            get { return _bypassDocumentValidation; }
+            set { _bypassDocumentValidation = value; }
+        }
+
         /// <summary>
         /// Gets or sets the collation.
         /// </summary>
@@ -54,12 +65,12 @@ public Collation Collation
         }
 
         /// <summary>
-        /// Gets or sets a value indicating whether to bypass document validation.
+        /// Gets or sets the hint.
         /// </summary>
-        public bool? BypassDocumentValidation
+        public BsonValue Hint
         {
-            get { return _bypassDocumentValidation; }
-            set { _bypassDocumentValidation = value; }
+            get { return _hint; }
+            set { _hint = value; }
         }
 
         /// <summary>

src/MongoDB.Driver/FindOneAndUpdateOptions.cs

@@ -15,7 +15,7 @@
 
 using System;
 using System.Collections.Generic;
-using System.Linq;
+using MongoDB.Bson;
 using MongoDB.Driver.Core.Misc;
 
 namespace MongoDB.Driver
@@ -31,6 +31,7 @@ public class FindOneAndUpdateOptions<TDocument, TProjection>
         private IEnumerable<ArrayFilterDefinition> _arrayFilters;
         private bool? _bypassDocumentValidation;
         private Collation _collation;
+        private BsonValue _hint;
         private bool _isUpsert;
         private TimeSpan? _maxTime;
         private ProjectionDefinition<TDocument, TProjection> _projection;
@@ -77,6 +78,15 @@ public Collation Collation
             set { _collation = value; }
         }
 
+        /// <summary>
+        /// Gets or sets the hint.
+        /// </summary>
+        public BsonValue Hint
+        {
+            get { return _hint; }
+            set { _hint = value; }
+        }
+
         /// <summary>
         /// Gets or sets a value indicating whether to insert the document if it doesn't already exist.
         /// </summary>

src/MongoDB.Driver/MongoCollectionImpl.cs

@@ -921,6 +921,7 @@ private FindOneAndReplaceOperation<TProjection> CreateFindOneAndReplaceOperation
             {
                 BypassDocumentValidation = options.BypassDocumentValidation,
                 Collation = options.Collation,
+                Hint = options.Hint,
                 IsUpsert = options.IsUpsert,
                 MaxTime = options.MaxTime,
                 Projection = renderedProjection.Document,
@@ -946,6 +947,7 @@ private FindOneAndUpdateOperation<TProjection> CreateFindOneAndUpdateOperation<T
                 ArrayFilters = RenderArrayFilters(options.ArrayFilters),
                 BypassDocumentValidation = options.BypassDocumentValidation,
                 Collation = options.Collation,
+                Hint = options.Hint,
                 IsUpsert = options.IsUpsert,
                 MaxTime = options.MaxTime,
                 Projection = renderedProjection.Document,

tests/MongoDB.Driver.Core.Tests/Core/Operations/FindOneAndReplaceOperationTests.cs

@@ -98,6 +98,7 @@ public void Constructor_should_initialize_object()
 
             subject.BypassDocumentValidation.Should().NotHaveValue();
             subject.Collation.Should().BeNull();
+            subject.Hint.Should().BeNull();
             subject.IsUpsert.Should().BeFalse();
             subject.MaxTime.Should().NotHaveValue();
             subject.Projection.Should().BeNull();
@@ -135,6 +136,20 @@ public void Collation_get_and_set_should_work(
             result.Should().BeSameAs(value);
         }
 
+        [Theory]
+        [ParameterAttributeData]
+        public void Hint_get_and_set_should_work(
+            [Values(null, "_id_")] string hintString)
+        {
+            var subject = new FindOneAndReplaceOperation<BsonDocument>(_collectionNamespace, _filter, _replacement, BsonDocumentSerializer.Instance, _messageEncoderSettings);
+            var value = (BsonValue)hintString;
+
+            subject.Hint = value;
+            var result = subject.Hint;
+
+            result.Should().Be(value);
+        }
+
         [Theory]
         [ParameterAttributeData]
         public void IsUpsert_get_and_set_should_work(
@@ -311,6 +326,31 @@ public void CreateCommand_should_return_expected_result_when_Collation_is_set(
             result.Should().Be(expectedResult);
         }
 
+        [Theory]
+        [ParameterAttributeData]
+        public void CreateCommand_should_return_expected_result_when_Hint_is_set(
+            [Values(null, "_id_")] string hintString)
+        {
+            var hint = (BsonValue)hintString;
+            var subject = new FindOneAndReplaceOperation<BsonDocument>(_collectionNamespace, _filter, _replacement, BsonDocumentSerializer.Instance, _messageEncoderSettings)
+            {
+                Hint = hint
+            };
+            var session = OperationTestHelper.CreateSession();
+            var connectionDescription = OperationTestHelper.CreateConnectionDescription(serverVersion: Feature.HintForFindAndModifyFeature.FirstSupportedVersion);
+
+            var result = subject.CreateCommand(session, connectionDescription, null);
+
+            var expectedResult = new BsonDocument
+            {
+                { "findAndModify", _collectionNamespace.CollectionName },
+                { "query", _filter },
+                { "update", _replacement },
+                { "hint", () => hint, hint != null }
+            };
+            result.Should().Be(expectedResult);
+        }
+
         [Theory]
         [ParameterAttributeData]
         public void CreateCommand_should_return_expected_result_when_IsUpsert_is_set(
@@ -671,6 +711,33 @@ public void Execute_should_throw_when_there_is_a_write_concern_error(
             );
         }
 
+        [SkippableTheory]
+        [ParameterAttributeData]
+        public void Execute_with_hint_should_throw_when_hint_is_not_supported(
+            [Values(false, true)] bool async)
+        {
+            var serverVersion = CoreTestConfiguration.ServerVersion;
+            var subject = new FindOneAndReplaceOperation<BsonDocument>(_collectionNamespace, _filter, _replacement, _findAndModifyValueDeserializer, _messageEncoderSettings)
+            {
+                Hint = new BsonDocument("_id", 1)
+            };
+
+            var exception = Record.Exception(() => ExecuteOperation(subject, async));
+
+            if (Feature.HintForFindAndModifyFeature.IsSupported(serverVersion))
+            {
+                exception.Should().BeNull();
+            }
+            else if (Feature.HintForFindAndModifyFeature.DriverMustThrowIfNotSupported(serverVersion))
+            {
+                exception.Should().BeOfType<NotSupportedException>();
+            }
+            else
+            {
+                exception.Should().BeOfType<MongoCommandException>();
+            }
+        }
+
         private void EnsureTestData()
         {
             DropCollection();