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

source/mongodb-handshake/handshake.md

@@ -405,15 +405,25 @@ class DriverInfoOptions {
 }
 ```
 
-Note that how these options are provided to a driver is left up to the implementer.
+Note that how these options are provided to a driver during `MongoClient` initialization is left up to the implementer.
 
-If provided, these options MUST NOT replace the values used for metadata generation. The provided options MUST be
-appended to their respective fields, and be delimited by a `|` character. For example, when
+### Metadata updates after MongoClient initialization
+
+Drivers MUST provide an API that allows to append `DriverInfoOptions` to a MongoClient instance after initialization.
+
+After client metadata update, drivers MUST apply updated metadata to newly created connections and MUST NOT apply it to
+already established connections.
+
+### Appending metadata
+
+If `DriverInfoOptions` are provided during or after MongoClient initialization, these options MUST NOT replace any
+existing metadata values, including driver-generated metadata and previously provided options. The provided options MUST
+be appended to their respective fields, and be delimited by a `|` character. For example, when
 [Motor](https://www.mongodb.com/docs/drivers/motor/) wraps PyMongo, the following fields are updated to include Motor's
 "driver info":
 
 ```typescript
-{
+{ 
     client: {
         driver: {
             name: "PyMongo|Motor",
@@ -534,6 +544,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg
 
 ## Changelog
 
+- 2025-05-07: Add requirement to allow appending to client metadata after MongoClient initialization.
 - 2024-11-05: Move handshake prose tests from spec file to prose test file.
 - 2024-10-09: Clarify that FaaS and container metadata must both be populated when both are present.
 - 2024-08-16: Migrated from reStructuredText to Markdown.

source/mongodb-handshake/tests/README.md

@@ -82,3 +82,89 @@ the following sets of environment variables:
 2. Create and connect a `Connection` object that connects to the server that returns the mocked response.
 
 3. Assert that no error is raised.
+
+## Client Metadata Update Prose Tests
+
+The driver **MAY** implement the following tests. Drivers that do not emit events for commands issued as part of the
+handshake with the server will need to create a test-only backdoor mechanism to intercept the handshake `hello` command
+for verification purposes.
+
+### Test 1: Test that the driver updates metadata
+
+Drivers should verify that metadata provided after `MongoClient` initialization is appended, not replaced, and is
+visible in the `hello` command of new connections.
+
+1. Create a `MongoClient` instance with the following:
+
+    - `maxIdleTimeMS` set to `1ms`
+
+    - Wrapping library metadata:
+
+        | Field    | Value            |
+        | -------- | ---------------- |
+        | name     | library          |
+        | version  | 1.2              |
+        | platform | Library Platform |
+
+2. Send a `ping` command to the server and verify:
+
+    - The command succeeds.
+    - The wrapping library metadata is appended to the respective `client.driver` fields of the `hello` command.
+    - Save intercepted `client` document as `initialClientMetadata`.
+
+3. Wait 5ms for the connection to become idle.
+
+4. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value              |
+    | -------- | ------------------ |
+    | name     | framework          |
+    | version  | 2.0                |
+    | platform | Framework Platform |
+
+5. Send `ping` command to the server and verify:
+
+    - The command succeeds.
+
+    - The framework metadata is appended to the existing `DriverInfoOptions` in the `client.driver` fields of the `hello`
+        command.
+
+        | Field    | Value                                |
+        | -------- | ------------------------------------ |
+        | name     | library\|framework                   |
+        | version  | 1.2\|2.0                             |
+        | platform | Library Platform\|Framework Platform |
+
+    - All other subfields in the client document remain unchanged from `initialClientMetadata`.
+
+### Test 2: Test that metadata is not updated on established connections
+
+Drivers should verify that appending metadata after `MongoClient` initialization does **not** close existing
+connections, and that no new `hello` command is sent.
+
+1. Create a `MongoClient` instance with wrapping library metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+2. Send a `ping` command to the server and verify:
+
+    - The command succeeds.
+    - The wrapping library metadata is appended to the respective `client.driver` fields of the `hello` command.
+
+3. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value              |
+    | -------- | ------------------ |
+    | name     | framework          |
+    | version  | 2.0                |
+    | platform | Framework Platform |
+
+4. Send another `ping` command to the server and verify:
+
+    - The command succeeds.
+    - No `hello` command is sent.
+    - No `ConnectionClosedEvent` is emitted.