DRIVERS-1918 Update rules for $readPreference passing to include OP_MSG (#1076)

Author: abr-egn

source/server-selection/server-selection.rst

@@ -579,9 +579,20 @@ Passing read preference to mongos and load balancers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If a server of type Mongos or LoadBalancer is selected for a read operation, the read
-preference is passed to the selected mongos through the use of the
-``SecondaryOk`` wire protocol flag, the ``$readPreference`` query
-modifier or both, according to the following rules.
+preference is passed to the selected mongos through the use of ``$readPreference``
+(as a `Global Command Argument`_ for OP_MSG or a query modifier for OP_QUERY) and, for
+OP_QUERY only, the ``SecondaryOk`` wire protocol flag, according to the following rules.
+
+For OP_MSG:
+```````````
+
+- For mode 'primary', drivers MUST NOT set ``$readPreference``
+
+- For all other read preference modes (i.e. 'secondary', 'primaryPreferred',
+  ...), drivers MUST set ``$readPreference``
+
+For OP_QUERY:
+`````````````
 
 If the read preference contains **only** a ``mode`` parameter and the mode is
 'primary' or 'secondaryPreferred', for maximum backwards compatibility with
@@ -591,23 +602,23 @@ and MUST NOT use a ``$readPreference`` query modifier.
 
 Therefore, when sending queries to a mongos or load balancer, the following rules apply:
 
-  - For mode 'primary', drivers MUST NOT set the ``SecondaryOk`` wire protocol flag
-    and MUST NOT use ``$readPreference``
+- For mode 'primary', drivers MUST NOT set the ``SecondaryOk`` wire protocol flag
+  and MUST NOT use ``$readPreference``
 
-  - For mode 'secondary', drivers MUST set the ``SecondaryOk`` wire protocol flag
-    and MUST also use ``$readPreference``
+- For mode 'secondary', drivers MUST set the ``SecondaryOk`` wire protocol flag
+  and MUST also use ``$readPreference``
 
-  - For mode 'primaryPreferred', drivers MUST set the ``SecondaryOk`` wire protocol flag
-    and MUST also use ``$readPreference``
+- For mode 'primaryPreferred', drivers MUST set the ``SecondaryOk`` wire protocol flag
+  and MUST also use ``$readPreference``
 
-  - For mode 'secondaryPreferred', drivers MUST set the ``SecondaryOk`` wire protocol flag.
-    If the read preference contains a non-empty ``tag_sets`` parameter,
-    ``maxStalenessSeconds`` is a positive integer, or the ``hedge`` parameter is
-    non-empty, drivers MUST use ``$readPreference``; otherwise, drivers MUST NOT
-    use ``$readPreference``
+- For mode 'secondaryPreferred', drivers MUST set the ``SecondaryOk`` wire protocol flag.
+  If the read preference contains a non-empty ``tag_sets`` parameter,
+  ``maxStalenessSeconds`` is a positive integer, or the ``hedge`` parameter is
+  non-empty, drivers MUST use ``$readPreference``; otherwise, drivers MUST NOT
+  use ``$readPreference``
 
-  - For mode 'nearest', drivers MUST set the ``SecondaryOk`` wire protocol flag
-    and MUST also use ``$readPreference``
+- For mode 'nearest', drivers MUST set the ``SecondaryOk`` wire protocol flag
+  and MUST also use ``$readPreference``
 
 The ``$readPreference`` query modifier sends the read preference as part of the
 query.  The read preference fields ``tag_sets`` is represented in a ``$readPreference``
@@ -629,6 +640,9 @@ the query MUST be provided using the ``$query`` modifier like so::
         }
     }
 
+Document structure
+``````````````````
+
 A valid ``$readPreference`` document for mongos or load balancer has the following requirements:
 
 1.  The ``mode`` field MUST be present exactly once with the mode represented
@@ -955,14 +969,19 @@ to the server differently:
 - For all other types, using OP_MSG: If no read preference is configured by the
   application, or if the application read preference is Primary, then
   $readPreference MUST be set to ``{ "mode": "primaryPreferred" }`` to ensure
-  that any server type can handle the request.
+  that any server type can handle the request.  If the application read
+  preference is set otherwise, $readPreference MUST be set following
+  `Document structure`_.
 
 The single server is always suitable for write operations if it is available.
 
 Topology type: LoadBalanced
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-selection>`__ for details.
+During command construction, drivers MUST add a $readPreference field to the
+command when required by `Passing read preference to mongos and load balancers`_;
+see the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-selection>`__
+for details.
 
 
 Topology types: ReplicaSetWithPrimary or ReplicaSetNoPrimary
@@ -1789,10 +1808,13 @@ References
 .. _Driver Authentication: https://github.com/mongodb/specifications/blob/master/source/auth
 .. _maxConnecting: /source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst#connection-pool
 .. _Connection Monitoring and Pooling: /source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst
+.. _Global Command Argument: /source/message/OP_MSG.rst#global-command-arguments
 
 Changes
 =======
 
+2021-08-05: Updated $readPreference logic to describe OP_MSG behavior.
+
 2015-06-26: Updated single-threaded selection logic with "stale" and serverSelectionTryOnce.
 
 2015-08-10: Updated single-threaded selection logic to ensure a scan always