DRIVERS-2985: Allow on-demand client metadata updates after MongoClient initialization.

[vbabanin]

Description

MongoDB’s handshake specification allows libraries and frameworks that wrap MongoDB drivers (e.g., ODMs, integrations) to append their own metadata.

However, this mechanism assumes the wrapping layer creates the MongoClient. When a wrapping environment instead receives a pre-created MongoClient (e.g., via dependency injection), there was no way to append additional metadata.

Changes

This PR updates the handshake specification with the following additions:

• Specifies that drivers MUST provide an API to allow updating client metadata (name, version, platform) after initialization.
• Appended values must be joined to existing client.driver fields using a | delimiter.
• Only new connections will include the updated metadata; existing connections MUST remain unaffected, as metadata propagation depends on the creation of new connections over time.
• Adds suggested prose tests to validate the above behavior. As some drivers may not support a testing backdoor to intercept handshake command events, or may face technical limitations, the exact test implementation is left to the discretion of the driver team.

Please complete the following before merging:

• Update changelog.
• Test changes in at least one language driver.
  Java Driver implementation: Add Client Metadata Update Support. mongo-java-driver#1708
  Secondary Python Driver implementation: PYTHON-5344 Allow Instantiated MongoClients to Send Client Metadata On-Demand mongo-python-driver#2358
• Test these changes against all server versions and topologies (including standalone, replica set, sharded
  clusters, and serverless). Evergreen path of aforementioned Java driver implementation: Link

[sleepyStick]

Just a couple minor comments, everything else looks good! great work!

[sleepyStick]

is this white space change intentional?

[vbabanin]

Removed in 5ce8b92, thanks!

[sleepyStick]

"...that allows to append..." reads weirdly to me? not sure if its just me or not though. It's possible that my brain just isn't parsing it correctly? I think my brain wants it to be "...that allows to append..."

[vbabanin]

Yeah, you're right, that allows to append is not correct. Originally, it was supposed to be that allows wrapping libraries to append.

I think my brain wants it to be "...that allows to append..."

Did you mean something like 'that allows appending' or 'that allows [users/wrapping libraries] to append'?

I currently changed it to that allows appending to keep it more general and avoid over-specifying "users" or "wrapping libraries". Let me know what you think!

Changed in 5ce8b92

[sleepyStick]

Yeah, this is much better. (upon re-reading, realized my suggestion at the end makes no sense because i wrote the same thing HAHA sorry for the confusion) thanks!

[vbabanin]

Lint errors are unrelated to the changes in this PR. See #1808 for reference.

[alcaeus]

@vbabanin #1808 was merged, so a rebase should fix the pre-commit checks here

[ShaneHarvey]

We usually give an example API (or at least function signature) that implementors can reference. Could we add that here?

For example, see how startSession is documented: https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.md#mongoclient-changes

[vbabanin]

Thank you for the reference! I have added explicit API guidance for clarity.

Previously, the specification left the mechanism for providing metadata during initialization up to the implementer.

(“Note that how these options are provided to a driver is left up to the implementer.”).

I have refined the language to clarify that this flexibility applies only during initialization. For subsequent metadata updates, the API guidance is now clearly defined, requiring the update method to reside on MongoClient.

Updated in: 4be80aa

[sleepyStick]

Great work!

[ShaneHarvey]

Could we simplify this test by removing the "library metadata" in step 1 and removing this assert from step 2?

[vbabanin]

Good catch - I missed removing the assertions in test 3. Removed assertions and library metadata in f0315f4, thanks!

[ShaneHarvey]

Actually, couldn't this particular test be a unified spec test? It doesn't rely on any mocking.

[vbabanin]

Yes, good point - it makes sense to convert this to a unified test. I’ve updated it accordingly.

I also added an assertion to verify no new connection is created. Since unified tests don’t assume a test backdoor, we can’t directly assert on handshake commands. However, verifying that no new connection is established indirectly ensures no hello was sent during the handshake. Any subsequent hello's over an existing connection would appear as regular commands and cause the test to fail.