DRIVERS-2993 specify behavior of w:0 with MongoClient.bulkWrite (#1670)

* add CRUD prose test 15
* use unordered write in prose test 10
* use unordered write in existing `unacknowledged-client-bulkWrite.yml`
* ban `w:0` with `verboseResults` / `ordered`
* test `w:0` and `verboseResults` / `ordered`

Author: kevinAlbs

source/command-logging-and-monitoring/tests/monitoring/unacknowledged-client-bulkWrite.json

@@ -50,6 +50,7 @@ tests:
                 namespace: *namespace
                 filter: { _id: 3 }
                 update: { $set: { x: 333 } }
+          ordered: false
         expectResult:
           insertedCount:
             $$unsetOrMatches: 0
@@ -89,7 +90,7 @@ tests:
               command:
                 bulkWrite: 1
                 errorsOnly: true
-                ordered: true
+                ordered: false
                 ops:
                   - insert: 0
                     document: { _id: 4, x: 44 }

source/command-logging-and-monitoring/tests/monitoring/unacknowledged-client-bulkWrite.yml

@@ -614,6 +614,11 @@ returned. This field is optional and defaults to false on the server.
 value for `verboseResults`, drivers MUST define `errorsOnly` as the opposite of `verboseResults`. If the user did not
 specify a value for `verboseResults`, drivers MUST define `errorsOnly` as `true`.
 
+Drivers MUST return a client-side error if `verboseResults` is true with an unacknowledged write concern containing the
+following message:
+
+> Cannot request unacknowledged write concern and verbose results
+
 ### `ordered`
 
 The `ordered` field defines whether writes should be executed in the order in which they were specified, and, if an
@@ -622,6 +627,11 @@ server. Drivers MUST explicitly define `ordered` as `true` in the `bulkWrite` co
 `BulkWriteOptions`. This is required to avoid inconsistencies between server and driver behavior if the server default
 changes in the future.
 
+Drivers MUST return a client-side error if `ordered` is true (including when default is applied) with an unacknowledged
+write concern containing the following message:
+
+> Cannot request unacknowledged write concern and ordered writes
+
 ### Size Limits
 
 The server reports a `maxBsonObjectSize` in its `hello` response. This value defines the maximum size for documents that
@@ -925,6 +935,8 @@ batch-splitting to standardize implementations across drivers and simplify batch
 
 ## **Changelog**
 
+- 2024-10-07: Error if `w:0` is used with `ordered=true` or `verboseResults=true`.
+
 - 2024-10-01: Add sort option to `replaceOne` and `updateOne`.
 
 - 2024-09-30: Define more options for modeling summary vs. verbose results.

source/crud/bulk-write.md

@@ -397,7 +397,8 @@ InsertOne: {
 
 Construct as list of write models (referred to as `models`) with the one `model`.
 
-Call `MongoClient.bulkWrite` with `models` and `BulkWriteOptions.writeConcern` set to an unacknowledged write concern.
+Call `MongoClient.bulkWrite` with `models`. Pass `BulkWriteOptions` with `ordered` set to `false` and `writeConcern` set
+to an unacknowledged write concern.
 
 Expect a client-side error due the size.
 
@@ -415,7 +416,8 @@ ReplaceOne: {
 
 Construct as list of write models (referred to as `models`) with the one `model`.
 
-Call `MongoClient.bulkWrite` with `models` and `BulkWriteOptions.writeConcern` set to an unacknowledged write concern.
+Call `MongoClient.bulkWrite` with `models`. Pass `BulkWriteOptions` with `ordered` set to `false` and `writeConcern` set
+to an unacknowledged write concern.
 
 Expect a client-side error due the size.
 
@@ -693,3 +695,45 @@ maxTimeMS value of 2000ms for the `explain`.
 
 Obtain the command started event for the explain. Confirm that the top-level explain command should has a `maxTimeMS`
 value of `2000`.
+
+### 15. `MongoClient.bulkWrite` with unacknowledged write concern uses `w:0` for all batches
+
+This test must only be run on 8.0+ servers. This test must be skipped on Atlas Serverless.
+
+If testing with a sharded cluster, only connect to one mongos. This is intended to ensure the `countDocuments` operation
+uses the same connection as the `bulkWrite` to get the correct connection count. (See
+[DRIVERS-2921](https://jira.mongodb.org/browse/DRIVERS-2921)).
+
+Construct a `MongoClient` (referred to as `client`) with
+[command monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md) enabled to observe
+CommandStartedEvents. Perform a `hello` command using `client` and record the `maxBsonObjectSize` and
+`maxMessageSizeBytes` values in the response.
+
+Construct a `MongoCollection` (referred to as `coll`) for the collection "db.coll". Drop `coll`.
+
+Use the `create` command to create "db.coll" to workaround [SERVER-95537](https://jira.mongodb.org/browse/SERVER-95537).
+
+Construct the following write model (referred to as `model`):
+
+```javascript
+InsertOne: {
+  "namespace": "db.coll",
+  "document": { "a": "b".repeat(maxBsonObjectSize - 500) }
+}
+```
+
+Construct a list of write models (referred to as `models`) with `model` repeated
+`maxMessageSizeBytes / maxBsonObjectSize + 1` times.
+
+Call `client.bulkWrite` with `models`. Pass `BulkWriteOptions` with `ordered` set to `false` and `writeConcern` set to
+an unacknowledged write concern. Assert no error occurred. Assert the result indicates the write was unacknowledged.
+
+Assert that two CommandStartedEvents (referred to as `firstEvent` and `secondEvent`) were observed for the `bulkWrite`
+command. Assert that the length of `firstEvent.command.ops` is `maxMessageSizeBytes / maxBsonObjectSize`. Assert that
+the length of `secondEvent.command.ops` is 1. If the driver exposes `operationId`s in its CommandStartedEvents, assert
+that `firstEvent.operationId` is equal to `secondEvent.operationId`. Assert both commands include
+`writeConcern: {w: 0}`.
+
+To force completion of the `w:0` writes, execute `coll.countDocuments` and expect the returned count is
+`maxMessageSizeBytes / maxBsonObjectSize + 1`. This is intended to avoid incomplete writes interfering with other tests
+that may use this collection.

source/crud/tests/README.md

@@ -239,3 +239,32 @@ tests:
           verboseResults: true
         expectError:
           isClientError: true
+  - description: "Requesting unacknowledged write with verboseResults is a client-side error"
+    operations:
+      - name: clientBulkWrite
+        object: *client0
+        arguments:
+          models:
+            - insertOne:
+                namespace: *namespace
+                document: { _id: 10 }
+          verboseResults: true
+          ordered: false
+          writeConcern: { w: 0 }
+        expectError:
+          isClientError: true
+          errorContains: "Cannot request unacknowledged write concern and verbose results"
+  - description: "Requesting unacknowledged write with ordered is a client-side error"
+    operations:
+      - name: clientBulkWrite
+        object: *client0
+        arguments:
+          models:
+            - insertOne:
+                namespace: *namespace
+                document: { _id: 10 }
+          # Omit `ordered` option. Defaults to true.
+          writeConcern: { w: 0 }
+        expectError:
+          isClientError: true
+          errorContains: "Cannot request unacknowledged write concern and ordered writes"