DRIVERS-1293: Updated change streams spec and tests to use modern terminology (#972)

Author: JamesKovacs

source/change-streams/change-streams.rst

@@ -9,8 +9,8 @@ Change Streams
 :Status: Accepted
 :Type: Standards
 :Minimum Server Version: 3.6
-:Last Modified: Febrary 8, 2021
-:Version: 1.9.0
+:Last Modified: April 23, 2021
+:Version: 1.9.1
 
 .. contents::
 
@@ -76,15 +76,15 @@ executed when checking these constraints.
       - 262
     * - SocketException
       - 9001
-    * - NotMaster
+    * - NotWritablePrimary
       - 10107
     * - InterruptedAtShutdown
       - 11600
     * - InterruptedDueToReplStateChange
       - 11602
-    * - NotMasterNoSlaveOk
+    * - NotPrimaryNoSecondaryOk
       - 13435
-    * - NotMasterOrSecondary
+    * - NotPrimaryOrSecondary
       - 13436
     * - StaleShardVersion
       - 63
@@ -404,7 +404,7 @@ Driver API
      * The server will report an error if `startAfter` and `resumeAfter` are both specified.
      *
      * @since 4.1.1
-     * @see https://docs.mongodb.com/master/changeStreams/#change-stream-start-after
+     * @see https://docs.mongodb.com/manual/changeStreams/#change-stream-start-after
      * @note this is an option of the `$changeStream` pipeline stage.
      */
      startAfter: Optional<Document>;
@@ -748,15 +748,15 @@ It was decided to remove this example from the specification for the following r
 - There are considerations to be made for languages that do not permit interruptible I/O (such as Java), where a change stream which blocks forever in a separate thread would necessitate killing the thread.
 - There is something to be said for an API that allows cooperation by default. The model in which a call to next only blocks until any response is returned (even an empty batch), allows for interruption and cooperation (e.g. interaction with other event loops).
 
-----------------------------------------
-Why is a whitelist of error codes preferable to a blacklist?
-----------------------------------------
+--------------------------------------------------------------
+Why is an allow list of error codes preferable to a deny list?
+--------------------------------------------------------------
 
-Change streams originally used a blacklist of error codes to determine which errors were not resumable. However, this
-allowed for the possibility of infinite resume loops if an error was not correctly blacklisted. Due to the fact that
-all errors aside from transient issues such as failovers are not resumable, the resume behavior was changed to use a
-whitelist. Part of this change was to introduce the ``ResumableChangeStreamError`` label so the server can add new error
-codes to the whitelist without requiring changes to drivers.
+Change streams originally used a deny list of error codes to determine which errors were not resumable. However, this
+allowed for the possibility of infinite resume loops if an error was not correctly deny listed. Due to the fact that
+all errors aside from transient issues such as failovers are not resumable, the resume behavior was changed to use an
+allow list. Part of this change was to introduce the ``ResumableChangeStreamError`` label so the server can add new error
+codes to the allow list without requiring changes to drivers.
 
 ----------------------------------------------------------------------
 Why is ``CursorNotFound`` special-cased when determining resumability?
@@ -881,7 +881,9 @@ Changelog
 | 2019-07-15 | Clarify resume process for change streams started with     |
 |            | the ``startAfter`` option.                                 |
 +------------+------------------------------------------------------------+
-| 2020-02-10 | Changed error handling approach to use a whitelist         |
+| 2020-02-10 | Changed error handling approach to use an allow list       |
 +------------+------------------------------------------------------------+
 | 2021-02-08 | Added the ``UpdateDescription.truncatedArrays`` field      |
 +------------+------------------------------------------------------------+
+| 2021-04-23 | Updated to use modern terminology                          |
++------------+------------------------------------------------------------+

source/change-streams/tests/README.rst

@@ -121,7 +121,7 @@ For each YAML file, for each element in ``tests``:
     Transactions spec test documentation for more information.
 
 - Create a new MongoClient ``client``
-- Begin monitoring all APM events for ``client``. (If the driver uses global listeners, filter out all events that do not originate with ``client``). Filter out any "internal" commands (e.g. ``isMaster``)
+- Begin monitoring all APM events for ``client``. (If the driver uses global listeners, filter out all events that do not originate with ``client``). Filter out any "internal" commands (e.g. ``hello`` or legacy hello)
 - Using ``client``, create a changeStream ``changeStream`` against the specified ``target``. Use ``changeStreamPipeline`` and ``changeStreamOptions`` if they are non-empty. Capture any error.
 - If there was no error, use ``globalClient`` and run every operation in ``operations`` in serial against the server until all operations have been executed or an error is thrown. Capture any error.
 - If there was no error and ``result.error`` is set, iterate ``changeStream`` once and capture any error.

source/change-streams/tests/legacy/change-streams-errors.yml

@@ -80,7 +80,7 @@ tests:
       mode: { times: 1 }
       data:
           failCommands: ["getMore"]
-          errorCode: 216 # An error code that's not on the old blacklist or whitelist
+          errorCode: 216 # An error code that's not on the old deny or allow lists
           closeConnection: false
     target: collection
     topology:

source/change-streams/tests/legacy/change-streams-resume-whitelist.json renamed to source/change-streams/tests/legacy/change-streams-resume-allowlist.json

@@ -777,7 +777,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMaster",
+      "description": "change stream resumes after NotWritablePrimary",
       "minServerVersion": "4.2",
       "maxServerVersion": "4.2.99",
       "failPoint": {
@@ -1068,7 +1068,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMasterNoSlaveOk",
+      "description": "change stream resumes after NotPrimaryNoSecondaryOk",
       "minServerVersion": "4.2",
       "maxServerVersion": "4.2.99",
       "failPoint": {
@@ -1165,7 +1165,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMasterOrSecondary",
+      "description": "change stream resumes after NotPrimaryOrSecondary",
       "minServerVersion": "4.2",
       "maxServerVersion": "4.2.99",
       "failPoint": {

source/change-streams/tests/legacy/change-streams-resume-whitelist.yml renamed to source/change-streams/tests/legacy/change-streams-resume-allowlist.yml

@@ -521,7 +521,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMaster"
+    description: "change stream resumes after NotWritablePrimary"
     minServerVersion: "4.2"
     maxServerVersion: "4.2.99"
     failPoint:
@@ -716,7 +716,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMasterNoSlaveOk"
+    description: "change stream resumes after NotPrimaryNoSecondaryOk"
     minServerVersion: "4.2"
     maxServerVersion: "4.2.99"
     failPoint:
@@ -781,7 +781,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMasterOrSecondary"
+    description: "change stream resumes after NotPrimaryOrSecondary"
     minServerVersion: "4.2"
     maxServerVersion: "4.2.99"
     failPoint:

source/change-streams/tests/legacy/change-streams-resume-errorLabels.json

@@ -654,7 +654,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMaster",
+      "description": "change stream resumes after NotWritablePrimary",
       "minServerVersion": "4.3.1",
       "failPoint": {
         "configureFailPoint": "failGetMoreAfterCursorCheckout",
@@ -933,7 +933,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMasterNoSlaveOk",
+      "description": "change stream resumes after NotPrimaryNoSecondaryOk",
       "minServerVersion": "4.3.1",
       "failPoint": {
         "configureFailPoint": "failGetMoreAfterCursorCheckout",
@@ -1026,7 +1026,7 @@
       }
     },
     {
-      "description": "change stream resumes after NotMasterOrSecondary",
+      "description": "change stream resumes after NotPrimaryOrSecondary",
       "minServerVersion": "4.3.1",
       "failPoint": {
         "configureFailPoint": "failGetMoreAfterCursorCheckout",

source/change-streams/tests/legacy/change-streams-resume-errorLabels.yml

@@ -444,7 +444,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMaster"
+    description: "change stream resumes after NotWritablePrimary"
     minServerVersion: "4.3.1"
     failPoint:
       configureFailPoint: failGetMoreAfterCursorCheckout
@@ -633,7 +633,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMasterNoSlaveOk"
+    description: "change stream resumes after NotPrimaryNoSecondaryOk"
     minServerVersion: "4.3.1"
     failPoint:
       configureFailPoint: failGetMoreAfterCursorCheckout
@@ -696,7 +696,7 @@ tests:
             x:
               $numberInt: "1"
   -
-    description: "change stream resumes after NotMasterOrSecondary"
+    description: "change stream resumes after NotPrimaryOrSecondary"
     minServerVersion: "4.3.1"
     failPoint:
       configureFailPoint: failGetMoreAfterCursorCheckout
@@ -1010,7 +1010,7 @@ tests:
           fullDocument:
             x:
               $numberInt: "1"
-  # The next two tests ensure that the driver only uses the error label, not the whitelist.
+  # The next two tests ensure that the driver only uses the error label, not the allow list.
   -
     description: "change stream resumes if error contains ResumableChangeStreamError"
     minServerVersion: "4.3.1"
@@ -1019,7 +1019,7 @@ tests:
       mode: { times: 1 }
       data:
           failCommands: ["getMore"]
-          errorCode: 50 # Use an error code that does not have the whitelist label by default
+          errorCode: 50 # Use an error code that does not have the allow list label by default
           closeConnection: false
           errorLabels: ["ResumableChangeStreamError"]
     target: collection
@@ -1080,11 +1080,11 @@ tests:
     description: "change stream does not resume if error does not contain ResumableChangeStreamError"
     minServerVersion: "4.3.1"
     failPoint:
-      configureFailPoint: failCommand # failCommand will not add the whitelist error label
+      configureFailPoint: failCommand # failCommand will not add the allow list error label
       mode: { times: 1 }
       data:
           failCommands: ["getMore"]
-          errorCode: 6 # Use an error code that is on the whitelist
+          errorCode: 6 # Use an error code that is on the allow list
           closeConnection: false
     target: collection
     topology: