Merge branch 'master' into dependabot/go_modules/golang.org/x/crypto-0.29.0

Author: matthewdale

docs/migration-2.0.md

@@ -1183,8 +1183,20 @@ A new `RawArray` type has been added to the `bson` package as a primitive type t
 
 ### ValueMarshaler
 
-The `MarshalBSONValue` method of the `ValueMarshaler` interface is only required to return a byte type value representing the BSON type to avoid importing the `bsontype` package.
+The `MarshalBSONValue` method of the [ValueMarshaler](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#ValueMarshaler) interface now returns a `byte` value representing the [BSON type](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#Type). That allows external packages to implement the `ValueMarshaler` interface without having to import the `bson` package. Convert a returned `byte` value to [bson.Type](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#Type) to compare with the BSON type constants. For example:
+
+```go
+btype, _, _ := m.MarshalBSONValue()
+fmt.Println("type of data: %s: ", bson.Type(btype))
+fmt.Println("type of data is an array: %v", bson.Type(btype) == bson.TypeArray)
+```
 
 ### ValueUnmarshaler
 
-The `UnmarshalBSONValue` method of the `ValueUnmarshaler` interface is only required to take a byte type argument representing the BSON type to avoid importing the Go driver package.
+The `UnmarshalBSONValue` method of the [ValueUnmarshaler](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#ValueUnmarshaler) interface now accepts a `byte` value representing the [BSON type](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#Type) for the first argument. That allows packages to implement `ValueUnmarshaler` without having to import the `bson` package. For example:
+
+```go
+if err := m.UnmarshalBSONValue(bson.TypeEmbeddedDocument, bytes); err != nil {
+    log.Fatalf("failed to decode embedded document: %v", err)
+}
+```

internal/integration/client_side_encryption_prose_test.go

@@ -1381,8 +1381,9 @@ func TestClientSideEncryptionProse(t *testing.T) {
 		}
 	})
 
-	// These tests only run when 3 KMS HTTP servers and 1 KMS KMIP server are running. See specification for port numbers and necessary arguments:
-	// https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.rst#kms-tls-options-tests
+	// These tests only run when 3 KMS HTTP servers and 1 KMS KMIP server are
+	// running. See specification for port numbers and necessary arguments:
+	// https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.md#10-kms-tls-tests
 	mt.RunOpts("10. kms tls tests", noClientOpts, func(mt *mtest.T) {
 		kmsTlsTestcase := os.Getenv("KMS_TLS_TESTCASE")
 		if kmsTlsTestcase == "" {
@@ -1436,8 +1437,9 @@ func TestClientSideEncryptionProse(t *testing.T) {
 		}
 	})
 
-	// These tests only run when 3 KMS HTTP servers and 1 KMS KMIP server are running. See specification for port numbers and necessary arguments:
-	// https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.rst#kms-tls-options-tests
+	// These tests only run when 3 KMS HTTP servers and 1 KMS KMIP server are
+	// running. See specification for port numbers and necessary arguments:
+	// https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/tests/README.md#11-kms-tls-options-tests
 	mt.RunOpts("11. kms tls options tests", noClientOpts, func(mt *mtest.T) {
 		if os.Getenv("KMS_MOCK_SERVERS_RUNNING") == "" {
 			mt.Skipf("Skipping test as KMS_MOCK_SERVERS_RUNNING is not set")

internal/integration/server_selection_prose_test.go

@@ -105,7 +105,7 @@ func runsServerSelection(mt *mtest.T, monitor *eventtest.TestPoolMonitor,
 }
 
 // TestServerSelectionProse implements the Server Selection prose tests:
-// https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection-tests.rst
+// https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection-tests.md
 func TestServerSelectionProse(t *testing.T) {
 	const maxPoolSize = 10
 	const localThreshold = 30 * time.Second

internal/integration/unified/collection_operation_execution.go

@@ -523,6 +523,8 @@ func executeDistinct(ctx context.Context, operation *operation) (*operationResul
 		val := elem.Value()
 
 		switch key {
+		case "hint":
+			opts.SetHint(val)
 		case "collation":
 			collation, err := createCollation(val.Document())
 			if err != nil {

mongo/collection.go

@@ -1281,6 +1281,16 @@ func (coll *Collection) Distinct(
 		}
 		op.Comment(comment)
 	}
+	if args.Hint != nil {
+		if isUnorderedMap(args.Hint) {
+			return &DistinctResult{err: ErrMapForOrderedArgument{"hint"}}
+		}
+		hint, err := marshalValue(args.Hint, coll.bsonOpts, coll.registry)
+		if err != nil {
+			return &DistinctResult{err: err}
+		}
+		op.Hint(hint)
+	}
 	retry := driver.RetryNone
 	if coll.client.retryReads {
 		retry = driver.RetryOncePerCommand

mongo/options/distinctoptions.go

@@ -13,6 +13,7 @@ package options
 type DistinctOptions struct {
 	Collation *Collation
 	Comment   interface{}
+	Hint      interface{}
 }
 
 // DistinctOptionsBuilder contains options to configure distinct operations. Each
@@ -60,3 +61,21 @@ func (do *DistinctOptionsBuilder) SetComment(comment interface{}) *DistinctOptio
 
 	return do
 }
+
+// SetHint specifies the index to use for the operation. This should either be
+// the index name as a string or the index specification as a document. This
+// option is only valid for MongoDB versions >= 7.1. Previous server versions
+// will return an error if an index hint is specified. Distinct returns an error
+// if the hint parameter is a multi-key map. The default value is nil, which
+// means that no index hint will be sent.
+//
+// SetHint sets the Hint field.
+func (do *DistinctOptionsBuilder) SetHint(hint interface{}) *DistinctOptionsBuilder {
+	do.Opts = append(do.Opts, func(opts *DistinctOptions) error {
+		opts.Hint = hint
+
+		return nil
+	})
+
+	return do
+}