CSHARP-5513: Fix ChangeStream DisambiguatedPaths implementation (#1630)

Author: sanych-sun

src/MongoDB.Driver/Core/ChangeStreamDocument.cs

@@ -121,7 +121,8 @@ public ChangeStreamDocument(
         /// Added in MongoDB version 6.1.0.
         /// </para>
         /// </remarks>
-        public BsonDocument DisambiguatedPaths => GetValue<BsonDocument>(nameof(DisambiguatedPaths), null);
+        [Obsolete("DisambiguatedPaths is obsolete and will be removed in a future version. Use <see cref=\"ChangeStreamDocument{TDocument}.UpdateDescription.DisambiguatedPaths\"/> instead.")]
+        public BsonDocument DisambiguatedPaths => null;
 
         /// <summary>
         /// Gets the document key.

src/MongoDB.Driver/Core/ChangeStreamDocumentSerializer.cs

@@ -42,9 +42,8 @@ public ChangeStreamDocumentSerializer(
 
             RegisterMember("ClusterTime", "clusterTime", BsonTimestampSerializer.Instance);
             RegisterMember("CollectionNamespace", "ns", ChangeStreamDocumentCollectionNamespaceSerializer.Instance);
-            RegisterMember("CollectionUuid", "ui", GuidSerializer.StandardInstance);
+            RegisterMember("CollectionUuid", "collectionUUID", GuidSerializer.StandardInstance);
             RegisterMember("DatabaseNamespace", "ns", ChangeStreamDocumentDatabaseNamespaceSerializer.Instance);
-            RegisterMember("DisambiguatedPaths", "disambiguatedPaths", BsonDocumentSerializer.Instance);
             RegisterMember("DocumentKey", "documentKey", BsonDocumentSerializer.Instance);
             RegisterMember("FullDocument", "fullDocument", _documentSerializer);
             RegisterMember("FullDocumentBeforeChange", "fullDocumentBeforeChange", _documentSerializer);

src/MongoDB.Driver/Core/ChangeStreamUpdateDescription.cs

@@ -27,6 +27,7 @@ namespace MongoDB.Driver
     public sealed class ChangeStreamUpdateDescription
     {
         // private fields
+        private readonly BsonDocument _disambiguatedPaths;
         private readonly string[] _removedFields;
         private readonly BsonArray _truncatedArrays;
         private readonly BsonDocument _updatedFields;
@@ -54,12 +55,60 @@ public ChangeStreamUpdateDescription(
             BsonDocument updatedFields,
             string[] removedFields,
             BsonArray truncatedArrays)
+            : this(updatedFields, removedFields, truncatedArrays, null)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ChangeStreamUpdateDescription" /> class.
+        /// </summary>
+        /// <param name="updatedFields">The updated fields.</param>
+        /// <param name="removedFields">The removed fields.</param>
+        /// <param name="truncatedArrays">The truncated arrays.</param>
+        /// <param name="disambiguatedPaths">The DisambiguatedPaths document.</param>
+        public ChangeStreamUpdateDescription(
+            BsonDocument updatedFields,
+            string[] removedFields,
+            BsonArray truncatedArrays,
+            BsonDocument disambiguatedPaths)
         {
             _updatedFields = Ensure.IsNotNull(updatedFields, nameof(updatedFields));
             _removedFields = Ensure.IsNotNull(removedFields, nameof(removedFields));
             _truncatedArrays = truncatedArrays; // can be null
+            _disambiguatedPaths = disambiguatedPaths;
         }
 
+        /// <summary>
+        /// Gets the disambiguated paths if present.
+        /// </summary>
+        /// <value>
+        /// The disambiguated paths.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// A document containing a map that associates an update path to an array containing the path components used in the update document. This data
+        /// can be used in combination with the other fields in an <see cref="ChangeStreamDocument{TDocument}.UpdateDescription"/> to determine the
+        /// actual path in the document that was updated. This is necessary in cases where a key contains dot-separated strings (i.e. <c>{ "a.b": "c" }</c>) or
+        /// a document contains a numeric literal string key (i.e. <c>{ "a": { "0": "a" } }</c>). Note that in this scenario, the numeric key can't be the top
+        /// level key because <c>{ "0": "a" }</c> is not ambiguous - update paths would simply be <c>'0'</c> which is unambiguous because BSON documents cannot have
+        /// arrays at the top level. Each entry in the document maps an update path to an array which contains the actual path used when the document
+        /// was updated. For example, given a document with the following shape <c>{ "a": { "0": 0 } }</c> and an update of <c>{ $inc: { "a.0": 1 } }</c>,
+        /// <see cref="ChangeStreamDocument{TDocument}.DisambiguatedPaths"/> would look like the following:
+        /// </para>
+        /// <code>
+        ///   {
+        ///      "a.0": ["a", "0"]
+        ///   }
+        /// </code>
+        /// <para>
+        /// In each array, all elements will be returned as strings with the exception of array indices, which will be returned as 32-bit integers.
+        /// </para>
+        /// <para>
+        /// Added in MongoDB version 6.1.0.
+        /// </para>
+        /// </remarks>
+        public BsonDocument DisambiguatedPaths => _disambiguatedPaths;
+
         // public properties
         /// <summary>
         /// Gets the removed fields.
@@ -98,7 +147,8 @@ public override bool Equals(object obj)
             return
                 _removedFields.SequenceEqual(other._removedFields) &&
                 _updatedFields.Equals(other._updatedFields) &&
-                object.Equals(_truncatedArrays, other._truncatedArrays);
+                object.Equals(_truncatedArrays, other._truncatedArrays) &&
+                object.Equals(_disambiguatedPaths, other._disambiguatedPaths);
         }
 
         /// <inheritdoc />
@@ -108,6 +158,7 @@ public override int GetHashCode()
                 .HashElements(_removedFields)
                 .Hash(_updatedFields)
                 .Hash(_truncatedArrays)
+                .Hash(_disambiguatedPaths)
                 .GetHashCode();
         }
     }

src/MongoDB.Driver/Core/ChangeStreamUpdateDescriptionSerializer.cs

@@ -46,6 +46,7 @@ protected override ChangeStreamUpdateDescription DeserializeValue(BsonDeserializ
         {
             var reader = context.Reader;
 
+            BsonDocument disambiguatedPaths = null;
             BsonDocument updatedFields = null;
             string[] removedFields = null;
             BsonArray truncatedArrays = null;
@@ -56,6 +57,10 @@ protected override ChangeStreamUpdateDescription DeserializeValue(BsonDeserializ
                 var fieldName = reader.ReadName();
                 switch (fieldName)
                 {
+                    case "disambiguatedPaths":
+                        disambiguatedPaths = BsonDocumentSerializer.Instance.Deserialize(context);
+                        break;
+
                     case "updatedFields":
                         updatedFields = BsonDocumentSerializer.Instance.Deserialize(context);
                         break;
@@ -74,7 +79,7 @@ protected override ChangeStreamUpdateDescription DeserializeValue(BsonDeserializ
             }
             reader.ReadEndDocument();
 
-            return new ChangeStreamUpdateDescription(updatedFields, removedFields, truncatedArrays);
+            return new ChangeStreamUpdateDescription(updatedFields, removedFields, truncatedArrays, disambiguatedPaths);
         }
 
         /// <inheritdoc />
@@ -92,6 +97,13 @@ protected override void SerializeValue(BsonSerializationContext context, BsonSer
                 writer.WriteName("truncatedArrays");
                 BsonArraySerializer.Instance.Serialize(context, value.TruncatedArrays);
             }
+
+            if (value.DisambiguatedPaths != null)
+            {
+                writer.WriteName("disambiguatedPaths");
+                BsonDocumentSerializer.Instance.Serialize(context, value.DisambiguatedPaths);
+            }
+
             writer.WriteEndDocument();
         }
     }

tests/MongoDB.Driver.Tests/Core/ChangeStreamDocumentSerializerTests.cs

@@ -36,12 +36,11 @@ public void constructor_should_initialize_instance()
             var result = new ChangeStreamDocumentSerializer<BsonDocument>(documentSerializer);
 
             result._documentSerializer().Should().BeSameAs(documentSerializer);
-            result._memberSerializationInfo().Count.Should().Be(15);
+            result._memberSerializationInfo().Count.Should().Be(14);
             AssertRegisteredMember(result, "ClusterTime", "clusterTime", BsonTimestampSerializer.Instance);
             AssertRegisteredMember(result, "CollectionNamespace", "ns", ChangeStreamDocumentCollectionNamespaceSerializer.Instance);
-            AssertRegisteredMember(result, "CollectionUuid", "ui", GuidSerializer.StandardInstance);
+            AssertRegisteredMember(result, "CollectionUuid", "collectionUUID", GuidSerializer.StandardInstance);
             AssertRegisteredMember(result, "DatabaseNamespace", "ns", ChangeStreamDocumentDatabaseNamespaceSerializer.Instance);
-            AssertRegisteredMember(result, "DisambiguatedPaths", "disambiguatedPaths", BsonDocumentSerializer.Instance);
             AssertRegisteredMember(result, "DocumentKey", "documentKey", BsonDocumentSerializer.Instance);
             AssertRegisteredMember(result, "FullDocument", "fullDocument", documentSerializer);
             AssertRegisteredMember(result, "FullDocumentBeforeChange", "fullDocumentBeforeChange", documentSerializer);

tests/MongoDB.Driver.Tests/Core/ChangeStreamDocumentTests.cs

@@ -173,7 +173,7 @@ public void CollectionNamespace_should_allow_extra_elements()
         public void CollectionUuid_should_return_expected_result()
         {
             var value = Guid.NewGuid();
-            var backingDocument = new BsonDocument { { "other", 1 }, { "ui", new BsonBinaryData(value, GuidRepresentation.Standard) } };
+            var backingDocument = new BsonDocument { { "other", 1 }, { "collectionUUID", new BsonBinaryData(value, GuidRepresentation.Standard) } };
             var subject = CreateSubject(backingDocument: backingDocument);
 
             var result = subject.CollectionUuid;
@@ -246,29 +246,6 @@ public void DatabaseNamespace_should_return_null_if_invalid(string databaseName)
             result.Should().BeNull();
         }
 
-        [Fact]
-        public void DisambiguatedPaths_should_return_expected_result()
-        {
-            var value = new BsonDocument("a.0", new BsonArray {"a", "0"});
-            var backingDocument = new BsonDocument { { "other", 1 }, { "disambiguatedPaths", value } };
-            var subject = CreateSubject(backingDocument: backingDocument);
-
-            var result = subject.DisambiguatedPaths;
-
-            result.Should().Be(value);
-        }
-
-        [Fact]
-        public void DisambiguatedPaths_should_return_null_if_not_present()
-        {
-            var backingDocument = new BsonDocument { { "other", 1 } };
-            var subject = CreateSubject(backingDocument: backingDocument);
-
-            var result = subject.DisambiguatedPaths;
-
-            result.Should().BeNull();
-        }
-
         [Fact]
         public void DocumentKey_should_return_expected_result()
         {

tests/MongoDB.Driver.Tests/UnifiedTestOperations/UnifiedChangeStreamDocumentConverter.cs

@@ -0,0 +1,116 @@
+/* Copyright 2010-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.
+ */
+
+using System;
+using System.Linq;
+using MongoDB.Bson;
+using MongoDB.Bson.Serialization.Serializers;
+using MongoDB.Driver.Linq.Linq3Implementation.Misc;
+
+namespace MongoDB.Driver.Tests.UnifiedTestOperations
+{
+    public class UnifiedChangeStreamDocumentConverter
+    {
+        private static readonly string[] __changeStreamFields = ["_id", "clusterTime", "documentKey", "fullDocument", "fullDocumentBeforeChange", "ns", "operationDescription", "operationType", "to", "splitEvent", "collectionUUID", "updateDescription", "wallTime"];
+        private static readonly string[] __nsFields = ["db", "coll"];
+
+        public static BsonDocument Convert(ChangeStreamDocument<BsonDocument> changeStreamDocument)
+        {
+            var result = new BsonDocument()
+            {
+                { "_id", changeStreamDocument.ResumeToken },
+                { "clusterTime", changeStreamDocument.ClusterTime, changeStreamDocument.ClusterTime != null },
+                { "documentKey", changeStreamDocument.DocumentKey, changeStreamDocument.DocumentKey != null },
+                { "operationDescription", changeStreamDocument.OperationDescription, changeStreamDocument.OperationDescription != null },
+                { "to", () => SerializationHelper.SerializeValue(ChangeStreamDocumentCollectionNamespaceSerializer.Instance, changeStreamDocument.RenameTo), changeStreamDocument.RenameTo != null },
+                { "splitEvent", () => SerializationHelper.SerializeValue(ChangeStreamSplitEventSerializer.Instance, changeStreamDocument.SplitEvent), changeStreamDocument.SplitEvent != null },
+                { "collectionUUID", () => SerializationHelper.SerializeValue(GuidSerializer.StandardInstance, changeStreamDocument.CollectionUuid), changeStreamDocument.CollectionUuid != null },
+                { "updateDescription", () => SerializationHelper.SerializeValue(ChangeStreamUpdateDescriptionSerializer.Instance, changeStreamDocument.UpdateDescription), changeStreamDocument.UpdateDescription != null },
+                { "wallTime", () => SerializationHelper.SerializeValue(DateTimeSerializer.UtcInstance, changeStreamDocument.WallTime), changeStreamDocument.WallTime != null }
+            };
+            AppendDocumentFieldValue(result, changeStreamDocument, "fullDocument");
+            AppendDocumentFieldValue(result, changeStreamDocument, "fullDocumentBeforeChange");
+            AppendNsFieldValue(result, changeStreamDocument);
+            AppendOperationTypeFieldValue(result, changeStreamDocument);
+
+            // map the rest of change stream document
+            result.AddRange(changeStreamDocument.BackingDocument.Elements.Where(e => !__changeStreamFields.Contains(e.Name)));
+
+            return result;
+        }
+
+        private static void AppendDocumentFieldValue(BsonDocument document, ChangeStreamDocument<BsonDocument> changeStreamResult, string fieldName)
+        {
+            BsonValue value = fieldName == "fullDocument" ? changeStreamResult.FullDocument : changeStreamResult.FullDocumentBeforeChange;
+            if (value == null && !changeStreamResult.BackingDocument.Contains(fieldName))
+            {
+                return;
+            }
+
+            if (value == null)
+            {
+                value = BsonNull.Value;
+            }
+
+            document.Add(fieldName, value);
+        }
+
+        private static void AppendNsFieldValue(BsonDocument document, ChangeStreamDocument<BsonDocument> changeStreamDocument)
+        {
+            BsonDocument nsFieldValue;
+            if (changeStreamDocument.CollectionNamespace != null)
+            {
+                nsFieldValue = (BsonDocument)SerializationHelper.SerializeValue(ChangeStreamDocumentCollectionNamespaceSerializer.Instance, changeStreamDocument.CollectionNamespace);
+            }
+            else if (changeStreamDocument.DatabaseNamespace != null)
+            {
+                nsFieldValue = (BsonDocument)SerializationHelper.SerializeValue(ChangeStreamDocumentDatabaseNamespaceSerializer.Instance, changeStreamDocument.DatabaseNamespace);
+            }
+            else if (changeStreamDocument.BackingDocument.Contains("ns"))
+            {
+                nsFieldValue = new BsonDocument();
+            }
+            else
+            {
+                return;
+            }
+
+            // map the rest of ns document
+            nsFieldValue.AddRange(changeStreamDocument.BackingDocument["ns"].AsBsonDocument.Where(e => !__nsFields.Contains(e.Name)));
+            document.Add("ns", nsFieldValue);
+        }
+
+        private static void AppendOperationTypeFieldValue(BsonDocument document, ChangeStreamDocument<BsonDocument> changeStreamDocument)
+        {
+            BsonValue value = null;
+            if (Enum.IsDefined(typeof(ChangeStreamOperationType), changeStreamDocument.OperationType))
+            {
+                value = SerializationHelper.SerializeValue(ChangeStreamOperationTypeSerializer.Instance, changeStreamDocument.OperationType);
+            }
+            else if (changeStreamDocument.BackingDocument.Contains("operationType"))
+            {
+                value = changeStreamDocument.BackingDocument["operationType"];
+            }
+
+            if (value == null)
+            {
+                return;
+            }
+
+            document.Add("operationType", value);
+        }
+    }
+}
+

tests/MongoDB.Driver.Tests/UnifiedTestOperations/UnifiedIterateUntilDocumentOrErrorOperation.cs

@@ -103,7 +103,7 @@ public class UnifiedIterateUntilDocumentOrErrorOperationResultConverter
         public BsonDocument Convert<T>(T value) =>
             value switch
             {
-                ChangeStreamDocument<BsonDocument> changeStreamResult => changeStreamResult.BackingDocument,
+                ChangeStreamDocument<BsonDocument> changeStreamResult => UnifiedChangeStreamDocumentConverter.Convert(changeStreamResult),
                 BsonDocument bsonDocument => bsonDocument,
                 _ => throw new FormatException($"Unsupported enumerator document {value.GetType().Name}.")
             };