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

source/mongodb-handshake/handshake.md

@@ -405,10 +405,29 @@ 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 appending `DriverInfoOptions` to a `MongoClient` instance after initialization,
+adhering to the pattern described below while following idioms of the language of the driver:
+
+```java
+interface MongoClient { 
+  void appendMetadata(DriverInfoOptions driverInfoOptions);
+  // other existing members of MongoClient
+}
+```
+
+After client metadata update, drivers MUST apply updated metadata to newly created connections. Drivers MUST NOT apply
+updated metadata to already established connections, create new connections, or close existing connections solely for
+the purpose of transferring updated metadata.
+
+### 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":
 
@@ -534,6 +553,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg
 
 ## Changelog
 
+- 2025-05-20: 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,160 @@ 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
+
+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.
+
+There are multiple test cases parameterized with `DriverInfoOptions` to be appended after `MongoClient` initialization.
+Before each test case, perform the setup.
+
+#### Setup
+
+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 that the command succeeds.
+
+3. Save intercepted `client` document as `initialClientMetadata`.
+
+4. Wait 5ms for the connection to become idle.
+
+#### Parameterized test cases
+
+| Case | Name      | Version | Platform           |
+| ---- | --------- | ------- | ------------------ |
+| 1    | framework | 2.0     | Framework Platform |
+| 2    | framework | 2.0     | null               |
+| 3    | framework | null    | Framework Platform |
+| 4    | framework | null    | null               |
+
+#### Running a test case
+
+1. Append the `DriverInfoOptions` from the selected test case to the `MongoClient` metadata.
+
+2. Send a `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, with values separated by a pipe `|`.
+
+        - `client.driver.name`:
+            - If test case's name is non-null: `library|<name>`
+            - Otherwise, the field remains unchanged: `library`
+        - `client.driver.version`:
+            - If test case's version is non-null: `1.2|<version>`
+            - Otherwise, the field remains unchanged: `1.2`
+        - `client.driver.platform`:
+            - If test case's platform is non-null: `Library Platform|<platform>`
+            - Otherwise, the field remains unchanged: `Library Platform`
+
+    - All other subfields in the `client` document remain unchanged from `initialClientMetadata`.
+
+## Test 2: Multiple Successive Metadata Updates
+
+Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
+is visible in the `hello` command of new connections.
+
+There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
+Before each test case, perform the setup.
+
+### Setup
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+
+2. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+3. Send a `ping` command to the server and verify that the command succeeds.
+
+4. Save intercepted `client` document as `updatedClientMetadata`.
+
+5. Wait 5ms for the connection to become idle.
+
+#### Parameterized test cases
+
+| Case | Name      | Version | Platform           |
+| ---- | --------- | ------- | ------------------ |
+| 1    | framework | 2.0     | Framework Platform |
+| 2    | framework | 2.0     | null               |
+| 3    | framework | null    | Framework Platform |
+| 4    | framework | null    | null               |
+
+#### Running a test case
+
+1. Append the `DriverInfoOptions` from the selected test case to the `MongoClient` metadata.
+
+2. Send a `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, with values separated by a pipe `|`.
+
+        - `client.driver.name`:
+            - If test case's name is non-null: `library|<name>`
+            - Otherwise, the field remains unchanged: `library`
+        - `client.driver.version`:
+            - If test case's version is non-null: `1.2|<version>`
+            - Otherwise, the field remains unchanged: `1.2`
+        - `client.driver.platform`:
+            - If test case's platform is non-null: `Library Platform|<platform>`
+            - Otherwise, the field remains unchanged: `Library Platform`
+
+    - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
+
+### Test 3: 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 a `ping` command to the server and verify:
+
+    - The command succeeds.
+    - No `hello` command is sent.
+    - No `ConnectionClosedEvent` is emitted.