DRIVERS-3262: appendMetadata() does not append duplicate metdata

source/mongodb-handshake/handshake.md

@@ -185,8 +185,8 @@ Drivers MUST NOT provide a default value for this key.
 
 This value is required and is not application configurable.
 
-The internal driver name. For drivers written on-top of other core drivers, the underlying driver will typically expose
-a function to append additional name to this field.
+The internal driver name. For drivers written on-top of other core drivers, the `appendMetadata()` method can be used to
+add package information to an existing MongoClient.
 
 Example:
 
@@ -200,7 +200,7 @@ Example:
 This value is required and is not application configurable.
 
 The internal driver version. The version formatting is not defined. For drivers written on-top of other core drivers,
-the underlying driver will typically expose a function to append additional name to this field.
+the `appendMetadata()` method can be used to add package information to an existing MongoClient.
 
 Example:
 
@@ -405,6 +405,9 @@ class DriverInfoOptions {
 }
 ```
 
+Two `DriverInfoOptions` objects are considered identical if all fields are strictly equal with case sensitive string
+comparison.
+
 Note that how these options are provided to a driver during `MongoClient` initialization is left up to the implementer.
 
 ### Metadata updates after MongoClient initialization
@@ -442,6 +445,11 @@ be appended to their respective fields, and be delimited by a `|` character. For
 }
 ```
 
+Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
+is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
+metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` object can be appended to a MongoClient
+exactly once.
+
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.
 
@@ -553,6 +561,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg
 
 ## Changelog
 
+- 2025-09-04: Clarify that drivers do not append the same metadata multiple times.
 - 2025-06-09: 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.

source/mongodb-handshake/tests/README.md

@@ -202,8 +202,102 @@ Before each test case, perform the setup.
         - `client.driver.version`:
             - If test case's version is non-null: `1.2|<version>`
             - Otherwise, the field remains unchanged: `1.2`
-        - `client.driver.platform`:
+        - `client.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: Multiple Successive Metadata Updates with Identical/Partially Identical `DriverInfo`
+
+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    | library   | 1.2     | Library Platform   |
+| 2    | framework | 1.2     | Library Platform   |
+| 3    | library   | 2.0     | Library Platform   |
+| 4    | library   | 1.2     | Framework Platform |
+| 5    | framework | 2.0     | Library Platform   |
+| 6    | framework | 1.2     | Framework Platform |
+| 7    | library   | 2.0     | Framework Platform |
+| 8    | framework | 2.0     | Framework Platform |
+
+#### 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 `|`. To simplify assertions in these tests, strip out the default driver
+        info that is automatically added by the driver (ex: `metadata.name.split('|').slice(1).join('|')`).
+
+        - If the test case's DriverInfo is identical to the driver info from setup step 2 (test case 1):
+            - Assert metadata.name is equal to `library`
+            - Assert metadata.version is equal to `1.2`
+            - Assert metadata.platform is equal to `LibraryPlatform`
+        - Otherwise:
+            - Assert metadata.name is equal to `library|<name>`
+            - Assert metadata.version is equal to `1.2|<version>`
+            - Assert metadata.platform is equal to `LibraryPlatform|<platform>`
+
+    - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
+
+## Test 4: Metadata is not appended if identical to initial metadata
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+    - `driverInfo` set to the following:
+
+    | 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 `clientMetadata`.
+
+4. Wait 5ms for the connection to become idle.
+
+5. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+6. Send a `ping` command to the server and verify that the command succeeds.
+
+7. Save intercepted `client` document as `updatedClientMetadata`.
+
+8. Assert that `clientMetadata` is identical to `updatedClientMetadata`.