Merge drivers-2789-fix-history-load-balancers (510a1e7)

mongodb · Mar 20, 2024 · 1f3dcc9 · 1f3dcc9
2 parents b0d8207 + 510a1e7
commit 1f3dcc9
Show file tree

Hide file tree

Showing 15 changed files with 65 additions and 83 deletions.
diff --git a/source/command-logging-and-monitoring/command-logging-and-monitoring.rst b/source/command-logging-and-monitoring/command-logging-and-monitoring.rst
@@ -190,7 +190,7 @@ into account. See the previously mentioned MongoDB Handshake spec for details.
 Events API
 ----------
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#events>`__ for details on the ``serviceId`` field.
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#events>`__ for details on the ``serviceId`` field.
 
 .. code:: typescript
 

diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md
@@ -717,7 +717,7 @@ MUST remove the entry for a `serviceId` once the connection count reaches 0. Onc
 connection MUST get the generation number that applies to its `serviceId` from the map and update the map to increment
 the connection count for this `serviceId`.
 
-See the [Load Balancer Specification](../load-balancers/load-balancers.rst#connection-pooling) for details.
+See the [Load Balancer Specification](../load-balancers/load-balancers.md#connection-pooling) for details.
 
 #### Forking
 
@@ -777,7 +777,7 @@ driver.
 
 #### Events
 
-See the [Load Balancer Specification](../load-balancers/load-balancers.rst#events) for details on the `serviceId` field.
+See the [Load Balancer Specification](../load-balancers/load-balancers.md#events) for details on the `serviceId` field.
 
 ```typescript
 /**

diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst
@@ -782,7 +782,7 @@ Once the MongoDB handshake is done, the connection MUST get the
 generation number that applies to its ``serviceId`` from the map and update the
 map to increment the connection count for this ``serviceId``.
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#connection-pooling>`__ for details.
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#connection-pooling>`__ for details.
 
 
 Forking
@@ -842,7 +842,7 @@ All drivers that implement a connection pool MUST provide an API that allows use
 Events
 ------
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#events>`__ for details on the ``serviceId`` field.
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#events>`__ for details on the ``serviceId`` field.
 
 .. code:: typescript
 

diff --git a/source/index.md b/source/index.md
@@ -18,6 +18,7 @@
 - [Handling of DBRefs](./dbref.md)
 - [Index Management](index-management/index-management.md)
 - [Initial DNS Seedlist Discovery](initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md)
+- [Load Balancer Support](load-balancers/load-balancers.md)
 - [MongoDB Driver Performance Benchmarking](benchmarking/benchmarking.md)
 - [Server Selection](server-selection/server-selection.md)
 - [Server Selection Test Plan](server-selection/server-selection-tests.md)

diff --git a/source/load-balancers/tests/README.md b/source/load-balancers/tests/README.md
@@ -0,0 +1,49 @@
+# Load Balancer Support Tests
+
+______________________________________________________________________
+
+## Introduction
+
+This document describes how drivers should create load balanced clusters for testing and how tests should be executed
+for such clusters.
+
+## Testing Requirements
+
+For each server version that supports load balanced clusters, drivers MUST add two Evergreen tasks: one with a sharded
+cluster with both authentication and TLS enabled and one with a sharded cluster with authentication and TLS disabled. In
+each task, the sharded cluster MUST be configured with two mongos nodes running on localhost ports 27017 and 27018. The
+shard and config servers may run on any free ports. Each task MUST also start up two TCP load balancers operating in
+round-robin mode: one fronting both mongos servers and one fronting a single mongos.
+
+### Load Balancer Configuration
+
+Drivers MUST use the `run-load-balancer.sh` script in `drivers-evergreen-tools` to start the TCP load balancers for
+Evergreen tasks. This script MUST be run after the backing sharded cluster has already been started. The script writes
+the URIs of the load balancers to a YAML expansions file, which can be read by drivers via the `expansions.update`
+Evergreen command. This will store the URIs into the `SINGLE_MONGOS_LB_URI` and `MULTI_MONGOS_LB_URI` environment
+variables.
+
+### Test Runner Configuration
+
+If the backing sharded cluster is configured with TLS enabled, drivers MUST add the relevant TLS options to both
+`SINGLE_MONGOS_LB_URI` and `MULTI_MONGOS_LB_URI` to ensure that test clients can connect to the cluster. Drivers MUST
+use the final URI stored in `SINGLE_MONGOS_LB_URI` (with additional TLS options if required) to configure internal
+clients for test runners (e.g. the internal MongoClient described by the
+[Unified Test Format spec](../../unified-test-format/unified-test-format.md)).
+
+In addition to modifying load balancer URIs, drivers MUST also mock server support for returning a `serviceId` field in
+`hello` or legacy `hello` command responses when running tests against a load-balanced cluster. This can be done by
+using the value of `topologyVersion.processId` to set `serviceId`. This MUST be done for all connections established by
+the test runner, including those made by any internal clients.
+
+## Tests
+
+The YAML and JSON files in this directory contain platform-independent tests written in the
+[Unified Test Format](../../unified-test-format/unified-test-format.md). Drivers MUST run the following test suites
+against a load balanced cluster:
+
+1. All test suites written in the Unified Test Format
+2. Retryable Reads
+3. Retryable Writes
+4. Change Streams
+5. Initial DNS Seedlist Discovery
diff --git a/source/load-balancers/tests/README.rst b/source/load-balancers/tests/README.rst
diff --git a/source/run-command/run-command.rst b/source/run-command/run-command.rst
@@ -287,7 +287,7 @@ Load Balancers
 
 When in ``loadBalanced`` mode, a driver MUST pin the connection used to execute the initial operation, and reuse it for subsequent ``getMore`` operations.
 
-* See Load Balancer's section on `Behaviour With Cursors <https://github.com/mongodb/specifications/blob/master/source/load-balancers/load-balancers.rst#behaviour-with-cursors>`_
+* See Load Balancer's section on `Behaviour With Cursors <../load-balancers/load-balancers.md#behaviour-with-cursors>`_
 
 Iterating the Cursor
 """"""""""""""""""""

diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst
@@ -853,7 +853,7 @@ type Unknown.
 TopologyType LoadBalanced
 `````````````````````````
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-discovery-logging-and-monitoring>`__ for details.
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#server-discovery-logging-and-monitoring>`__ for details.
 
 Other TopologyTypes
 ```````````````````

diff --git a/source/server-selection/server-selection.md b/source/server-selection/server-selection.md
@@ -778,7 +778,7 @@ The single server is always suitable for write operations if it is available.
 
 During command construction, drivers MUST add a $readPreference field to the command when required by
 [Passing read preference to mongos and load balancers](#passing-read-preference-to-mongos-and-load-balancers); see the
-[Load Balancer Specification](../load-balancers/load-balancers.rst#server-selection) for details.
+[Load Balancer Specification](../load-balancers/load-balancers.md#server-selection) for details.
 
 #### Topology types: ReplicaSetWithPrimary or ReplicaSetNoPrimary
 

diff --git a/source/server-selection/server-selection.rst b/source/server-selection/server-selection.rst
@@ -1010,7 +1010,7 @@ Topology type: LoadBalanced
 
 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>`__
+see the `Load Balancer Specification <../load-balancers/load-balancers.md#server-selection>`__
 for details.
 
 

diff --git a/source/serverless-testing/README.rst b/source/serverless-testing/README.rst
@@ -53,7 +53,7 @@ In contrast to the `Load Balancer testing`_, which has separate URIs for load
 balancers fronting a single or multiple servers, there is only a single URI for
 Atlas Serverless testing (i.e. ``SERVERLESS_URI``).
 
-.. _Load Balancer testing: ../load-balancers/tests/README.rst
+.. _Load Balancer testing: ../load-balancers/tests/README.md
 
 The TXT record for ``SERVERLESS_URI`` already specifies ``loadBalanced=true`` so
 drivers need not add that.

diff --git a/source/sessions/driver-sessions.rst b/source/sessions/driver-sessions.rst
@@ -837,7 +837,7 @@ Algorithm to acquire a ServerSession instance from the server session pool
    * If it has at least one minute left before becoming stale use this ``ServerSession``
    * If it has less than one minute left before becoming stale discard it (let it be garbage collected) and return to step 1.
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#session-expiration>`__
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#session-expiration>`__
 for details on session expiration.
 
 

diff --git a/source/transactions/transactions.md b/source/transactions/transactions.md
@@ -652,7 +652,7 @@ called multiple times.
 
 #### Pinning in Load Balancer Mode
 
-See the [Load Balancer Specification](../load-balancers/load-balancers.rst#connection-pooling) for details.
+See the [Load Balancer Specification](../load-balancers/load-balancers.md#connection-pooling) for details.
 
 ### recoveryToken field
 

diff --git a/source/transactions/transactions.rst b/source/transactions/transactions.rst
@@ -842,7 +842,7 @@ the session as ``commitTransaction`` may be called multiple times.
 Pinning in Load Balancer Mode
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#connection-pooling>`__ for details.
+See the `Load Balancer Specification <../load-balancers/load-balancers.md#connection-pooling>`__ for details.
 
 
 recoveryToken field

diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.rst
@@ -81,7 +81,7 @@ Load Balancer Mode
 
 For URI option validation in Load Balancer mode (i.e. ``loadBalanced=true``),
 please see the
-`Load Balancer spec <../load-balancers/load-balancers.rst#uri-validation>`_ for
+`Load Balancer spec <../load-balancers/load-balancers.md#uri-validation>`_ for
 details.
 
 
@@ -186,7 +186,7 @@ pertaining to URI options apply here.
 
    * - loadBalanced
      - "true" or "false"
-     - defined in `Load Balancer spec <../load-balancers/load-balancers.rst#loadbalanced>`__
+     - defined in `Load Balancer spec <../load-balancers/load-balancers.md#loadbalanced>`__
      - no
      - Whether the driver is connecting to a load balancer.