DRIVERS-2033 Require hello command + OP_MSG when 'loadBalanced=True' (#1123)

Author: juliusgeo

source/load-balancers/load-balancers.rst

@@ -9,7 +9,7 @@ Load Balancer Support
 :Status: Accepted
 :Type: Standards
 :Minimum Server Version: 5.0
-:Last Modified: 2021-12-22
+:Last Modified: 2022-01-18
 
 .. contents::
 
@@ -163,8 +163,10 @@ Connection Establishment
 
 In the case of the driver having the :code:`loadBalanced=true` connection string option
 specified, every pooled connection MUST add a :code:`loadBalanced` field to the
-:code:`hello` or legacy hello command in its `handshake <../mongodb-handshake/handshake.rst#connection-handshake>`__.
-The value of the field MUST be :code:`true`.
+:code:`hello` command in its `handshake <../mongodb-handshake/handshake.rst#connection-handshake>`__.
+The value of the field MUST be :code:`true`. If :code:`loadBalanced=true` is
+specified then the ``OP_MSG`` protocol MUST be used for all steps of the
+connection handshake.
 
 Example:
 
@@ -263,7 +265,7 @@ Initial Handshake Errors
 
 When establishing a new connection in load balanced mode, drivers MUST NOT perform SDAM
 error handling for any errors that occur before the MongoDB Handshake
-(i.e. :code:`hello` or legacy hello command) is complete. Errors during the MongoDB
+(i.e. :code:`hello` command) is complete. Errors during the MongoDB
 Handshake MUST also be ignored for SDAM error handling purposes. Once the initial
 handshake is complete, the connection MUST determine its generation number based
 on the :code:`serviceId` field in the handshake response. Any errors that occur
@@ -308,7 +310,7 @@ All services which terminate TLS MUST be configured to return a TLS certificate
 which matches the hostname the client is connecting to.
 
 All services behind a load balancer that have been started with the aforementioned option MUST
-add a top level :code:`serviceId` field to their response to the :code:`hello` or legacy hello
+add a top level :code:`serviceId` field to their response to the :code:`hello`
 command. This field MUST be a BSON :code:`ObjectId` and SHOULD NOT change while the service is running.
 When a driver is configured to not be in load balanced mode and the service is configured behind
 a load balancer, the service MAY return an error from the driver's :code:`hello` command that
@@ -342,7 +344,7 @@ Why explicitly opt-in to this behaviour instead of letting mongos inform the dri
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Other versions of this design proposed a scheme in which the application does not have to opt-in to
-load balanced mode. Instead, the server would send a special field in :code:`hello` and legacy hello
+load balanced mode. Instead, the server would send a special field in :code:`hello`
 command responses to indicate that it was running behind a load balancer and the driver would change
 its behavior accordingly. We opted to take an approach that required code changes instead because
 load balancing changes driver behavior in ways that could cause unexpected application errors, so
@@ -424,6 +426,6 @@ be supported.
 
 Change Log
 ==========
-
+- 2022-01-18: Clarify that ``OP_MSG`` must be used in load balanced mode.
 - 2021-12-22: Clarify that pinned connections in transactions are exclusive.
 - 2021-10-14: Note that ``loadBalanced=true`` conflicts with ``srvMaxHosts``.

source/mongodb-handshake/handshake.rst

@@ -76,13 +76,12 @@ always be sent using the ``OP_MSG`` protocol. ``isMaster`` is referred to as
 that do not support the ``hello`` command.
 
 If a `server API version <../versioned-api/versioned-api.rst>`__ is
-requested drivers MUST use the ``hello`` command
+requested or ``loadBalanced: True``, drivers MUST use the ``hello`` command
 for the initial handshake and use the ``OP_MSG`` protocol. If server API
-version is not requested drivers MUST
-use legacy hello for the first message of the initial handshake with the
-``OP_QUERY`` protocol (before switching to ``OP_MSG`` if the
-``maxWireVersion`` indicates compatibility), and include ``helloOk:true``in
-the handshake request.
+version is not requested and ``loadBalanced: False``, drivers MUST use legacy
+hello for the first message of the initial handshake with the ``OP_QUERY``
+protocol (before switching to ``OP_MSG`` if the ``maxWireVersion`` indicates
+compatibility), and include ``helloOk:true`` in the handshake request.
 
 ASIDE: If the legacy handshake response includes ``helloOk: true``, then
 subsequent topology monitoring commands MUST use the ``hello`` command. If the
@@ -113,7 +112,7 @@ Consider the following pseudo-code for establishing a new connection:
 
  conn = Connection()
  conn.connect()  # Connect via TCP / TLS
- if versioned_api_configured:
+ if versioned_api_configured or client_options.load_balanced:
      cmd = {"hello": 1}
      conn.supports_op_msg = True  # Send the initial command via OP_MSG.
  else: