GODRIVER-3037 Support internal-only options.

[qingyang-hu]

GODRIVER-3037

Summary

Support setting internal-only options with a helper function.

Background & Motivation

This proposal does not change the current interface.
The option names are not publicly exposed to the user, so it is less likely to be used without internal knowledge.
We can add a map[string]any named custom in ClientOptions struct for future internal options, such as AuthenticateToAnything.
The Crypt and Deployment fields in ClientOptions will be merged into the aforementioned map in v3.

[mongodb-drivers-pr-bot]

API Change Report

./v2/mongo/options

compatible changes

ClientOptions.Custom: added

./v2/x/mongo/driver/xoptions

compatible changes

package added

[prestonvasquez]

Could this function live in the experimental API? What is the pattern for future custom data? Should ClientOptions be extended with a Custom field of type map[string]any?

[prestonvasquez]

Consider the following pattern:

type ClientOptions struct {
	custom map[string]any
}

func WithCustomValue(co ClientOptions, key string, val any) ClientOptions {}
func CustomValue(co ClientOptions key string) any {}

Then in x/mongo/driver:

const someExperimentKey = "x/mongo/driver:myExperiment"

func WithSomeExperimentValue(co options.ClientOptions, on bool) options.ClientOptions {
	return options.WithCustomValue(co, someExperimentKey, on)
}

func SomeExperimentValue(co options.ClientOptions) bool {
	val := options.CustomValue(co, someExperimentKey)
	if b, ok := val.(bool); ok {
		return b
	}

	return false
}

The usage would look something like this:

	clientOpts, _ := options.Client()
	clientOpts = driver.WithSomeExperimentValue(clientOpts, true)

	// ...

And we would check it internally like this:

	expVal := driver.SomeExperimentValue(clientOpts)
	// ...

[qingyang-hu]

Instead of an expressive interface, I'd prefer a map-style interface without any hint other than a user-provided option name to add obfuscation to discourage general users from using it. However, it makes sense to wrap the map[string]any in a struct and move it to "x/mongo/driver" to emphasize it is "experimental".

I can stack another PR for GODRIVER-3429 (internal-only "AuthenticateToAnything") on top of this one to demonstrate future custom data.

[prestonvasquez]

I think this solution is fine for now, we can update if needed later.

[prestonvasquez]

Should we name this package something different to avoid import conflicts? Perhaps xoptions?

[prestonvasquez]

Do we need this to return an error? Should we just do nothing if an unsupported option is set?

[qingyang-hu]

I prefer to keep the return to avoid silent errors, for example, a typo in the key name. Otherwise, these errors would be difficult to find.