From da5d42ae15a2c29e08c61ac1e46d99e100319bed Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 18 Mar 2021 16:17:46 -0400 Subject: [PATCH 1/5] GODRIVER-852 Add documentation warning against the use of duplicate key names --- bson/bson.go | 3 +++ mongo/collection.go | 6 ++++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/bson/bson.go b/bson/bson.go index ae1a87faa7..33dde3ea57 100644 --- a/bson/bson.go +++ b/bson/bson.go @@ -25,6 +25,9 @@ type Zeroer interface { // D is an ordered representation of a BSON document. This type should be used when the order of the elements matters, // such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead. // +// Note that a D can be constructed with duplicate key names which should be avoided as they can cause undefined behavior +// from the server. +// // Example usage: // // bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}} diff --git a/mongo/collection.go b/mongo/collection.go index fd9c1811dd..19902b3501 100644 --- a/mongo/collection.go +++ b/mongo/collection.go @@ -319,7 +319,8 @@ func (coll *Collection) insert(ctx context.Context, documents []interface{}, // // The document parameter must be the document to be inserted. It cannot be nil. If the document does not have an _id // field when transformed into BSON, one will be added automatically to the marshalled document. The original document -// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. +// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. Note that +// duplicate key names in the document parameter can result in undefined behavior from the server. // // The opts parameter can be used to specify options for the operation (see the options.InsertOneOptions documentation.) // @@ -348,7 +349,8 @@ func (coll *Collection) InsertOne(ctx context.Context, document interface{}, // The documents parameter must be a slice of documents to insert. The slice cannot be nil or empty. The elements must // all be non-nil. For any document that does not have an _id field when transformed into BSON, one will be added // automatically to the marshalled document. The original document will not be modified. The _id values for the inserted -// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. +// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. Note that duplicate key names +// within a single document in the documents parameter can result in undefined behavior from the server. // // The opts parameter can be used to specify options for the operation (see the options.InsertManyOptions documentation.) // From b98828d554c6ca0a6106ad45e6bfdf4afc0a2bb2 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 25 Mar 2021 10:39:40 -0400 Subject: [PATCH 2/5] Use stronger phrasing --- bson/bson.go | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/bson/bson.go b/bson/bson.go index 33dde3ea57..0c739dd0ac 100644 --- a/bson/bson.go +++ b/bson/bson.go @@ -25,8 +25,7 @@ type Zeroer interface { // D is an ordered representation of a BSON document. This type should be used when the order of the elements matters, // such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead. // -// Note that a D can be constructed with duplicate key names which should be avoided as they can cause undefined behavior -// from the server. +// A D should not be constructed with duplicate key names, as that can cause undefined server behavior. // // Example usage: // From 1702bfcdfaa5eeae36e9e9638595595b6b554d55 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Thu, 25 Mar 2021 14:54:53 -0400 Subject: [PATCH 3/5] Even stronger --- mongo/collection.go | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/mongo/collection.go b/mongo/collection.go index 19902b3501..5f359bf2c0 100644 --- a/mongo/collection.go +++ b/mongo/collection.go @@ -319,8 +319,9 @@ func (coll *Collection) insert(ctx context.Context, documents []interface{}, // // The document parameter must be the document to be inserted. It cannot be nil. If the document does not have an _id // field when transformed into BSON, one will be added automatically to the marshalled document. The original document -// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. Note that -// duplicate key names in the document parameter can result in undefined behavior from the server. +// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. The document +// parameter should NOT contain duplicate key names, as that can result in undefined behavior from the server. +// // // The opts parameter can be used to specify options for the operation (see the options.InsertOneOptions documentation.) // @@ -349,8 +350,8 @@ func (coll *Collection) InsertOne(ctx context.Context, document interface{}, // The documents parameter must be a slice of documents to insert. The slice cannot be nil or empty. The elements must // all be non-nil. For any document that does not have an _id field when transformed into BSON, one will be added // automatically to the marshalled document. The original document will not be modified. The _id values for the inserted -// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. Note that duplicate key names -// within a single document in the documents parameter can result in undefined behavior from the server. +// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. No single document in the +// documents parameter should contain duplicate key names, as that can result in undefined behavior from the server. // // The opts parameter can be used to specify options for the operation (see the options.InsertManyOptions documentation.) // From 8d5e828acd363ee6ac3ee18e201253650a39e093 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Fri, 2 Apr 2021 10:55:18 -0400 Subject: [PATCH 4/5] Add documentation to bson/doc.go --- bson/doc.go | 2 ++ mongo/collection.go | 6 ++---- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/bson/doc.go b/bson/doc.go index 9d5f30de0b..094be934f0 100644 --- a/bson/doc.go +++ b/bson/doc.go @@ -29,6 +29,8 @@ // slice and M is a map. For more information about the use cases for these types, see the documentation on the type // definitions. // +// Note that a D should not be constructed with duplicate key names, as that can cause undefined server behavior. +// // Example: // bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}} // bson.M{"foo": "bar", "hello": "world", "pi": 3.14159} diff --git a/mongo/collection.go b/mongo/collection.go index 5f359bf2c0..836e484760 100644 --- a/mongo/collection.go +++ b/mongo/collection.go @@ -319,8 +319,7 @@ func (coll *Collection) insert(ctx context.Context, documents []interface{}, // // The document parameter must be the document to be inserted. It cannot be nil. If the document does not have an _id // field when transformed into BSON, one will be added automatically to the marshalled document. The original document -// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. The document -// parameter should NOT contain duplicate key names, as that can result in undefined behavior from the server. +// will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. // // // The opts parameter can be used to specify options for the operation (see the options.InsertOneOptions documentation.) @@ -350,8 +349,7 @@ func (coll *Collection) InsertOne(ctx context.Context, document interface{}, // The documents parameter must be a slice of documents to insert. The slice cannot be nil or empty. The elements must // all be non-nil. For any document that does not have an _id field when transformed into BSON, one will be added // automatically to the marshalled document. The original document will not be modified. The _id values for the inserted -// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. No single document in the -// documents parameter should contain duplicate key names, as that can result in undefined behavior from the server. +// documents can be retrieved from the InsertedIDs field of the returned InsertManyResult. // // The opts parameter can be used to specify options for the operation (see the options.InsertManyOptions documentation.) // From 86574e2f1a33f237e6aa46e2563329607d340b70 Mon Sep 17 00:00:00 2001 From: Benjamin Rewis Date: Fri, 16 Apr 2021 10:48:01 -0400 Subject: [PATCH 5/5] Remove extra whitespace --- mongo/collection.go | 1 - 1 file changed, 1 deletion(-) diff --git a/mongo/collection.go b/mongo/collection.go index 836e484760..fd9c1811dd 100644 --- a/mongo/collection.go +++ b/mongo/collection.go @@ -321,7 +321,6 @@ func (coll *Collection) insert(ctx context.Context, documents []interface{}, // field when transformed into BSON, one will be added automatically to the marshalled document. The original document // will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult. // -// // The opts parameter can be used to specify options for the operation (see the options.InsertOneOptions documentation.) // // For more information about the command, see https://docs.mongodb.com/manual/reference/command/insert/.