DRIVERS-3218 Avoid clearing the connection pool when the server connection rate limiter triggers

source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md

@@ -284,6 +284,13 @@ Endpoint. The pool has the following properties:
 - **Rate-limited:** A Pool MUST limit the number of [Connections](#connection) being
     [established](#establishing-a-connection-internal-implementation) concurrently via the **maxConnecting**
     [pool option](#connection-pool-options).
+- **Backpressure-enabled** - The pool MUST add the error labels `SystemOverloadedError` and `RetryableError` to network
+    errors or network timeouts it encounters during the TLS Handshake or the `hello` message. These labels are used by
+    the [server monitor](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#error-handling-pseudocode)
+    to avoid clearing the pool. The pool MUST not add the backpressure error labels during an authentication step
+    after the `hello` message. If the driver cannot distinguish between TLS Handshake and TCP connection or DNS lookup,
+    it MUST add the backpressure error labels to network errors or network timeouts during initial connection
+    establishment.
 
 ```typescript
 interface ConnectionPool {
@@ -1375,6 +1382,8 @@ to close and remove from its pool a [Connection](#connection) which has unread e
 
 ## Changelog
 
+- 2025-XX-YY: Add handling of backpressure error labels.
+
 - 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double.
 
 - 2024-11-27: Relaxed the WaitQueue fairness requirement.

source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size-error.yml

@@ -11,11 +11,14 @@ failPoint:
   mode: { times: 50 }
   data:
     failCommands: ["isMaster","hello"]
-    closeConnection: true
+    blockConnection: true
+    blockTimeMS: 1000
     appName: "poolCreateMinSizeErrorTest"
 poolOptions:
   minPoolSize: 1
   backgroundThreadIntervalMS: 50
+  socketTimeoutMS: 500
+  connectTimeoutMS: 500
   appName: "poolCreateMinSizeErrorTest"
 operations:
   - name: ready

source/server-discovery-and-monitoring/server-discovery-and-monitoring.md

@@ -1056,6 +1056,9 @@ def handleError(error):
                 if isNotWritablePrimary(error):
                     check failing server
         elif isNetworkError(error) or (not error.completedHandshake and (isNetworkTimeout(error) or isAuthError(error))):
+            # Ignore errors that have backpressure error labels applied.
+            if error.hasLabel("SystemOverloadedError") and error.hasLabel("RetryableError"):
+                continue
             if type != LoadBalanced
               # Mark the server Unknown
               unknown = new ServerDescription(type=Unknown, error=error)
@@ -1255,7 +1258,8 @@ and [other transient errors](#other-transient-errors) and
 
 ##### Authentication and Handshake errors
 
-If the driver encounters errors when establishing application connections (this includes the initial handshake and
+If the driver encounters errors that do not have the backpressure error labels (`SystemOverloadedError` and
+`RetryableError`) applied when establishing application connections (this includes the initial handshake and
 authentication), the driver MUST mark the server Unknown and clear the server's connection pool if the TopologyType is
 not LoadBalanced. (See [Why mark a server Unknown after an auth error?](#why-mark-a-server-unknown-after-an-auth-error))
 
@@ -2027,6 +2031,8 @@ oversaw the specification process.
 - 2025-01-22: Add error messages when a new primary is elected or a primary with a stale electionId or setVersion is
     discovered.
 
+- 2025-XX-YY: Add handling of backpressure error labels.
+
 ______________________________________________________________________
 
 [^1]: "localThresholdMS" was called "secondaryAcceptableLatencyMS" in the Read Preferences Spec, before it was superseded

source/server-discovery-and-monitoring/tests/unified/backpressure-network-error-fail.yml

@@ -0,0 +1,83 @@
+description: backpressure-network-error-fail
+schemaVersion: "1.4"
+runOnRequirements:
+  - minServerVersion: "4.4"
+    serverless: forbid
+    topologies:
+      - single
+      - replicaset
+      - sharded
+createEntities:
+  - client:
+      id: setupClient
+      useMultipleMongoses: false
+initialData:
+  - collectionName: backpressure-network-error-fail
+    databaseName: sdam-tests
+    documents:
+      - _id: 1
+      - _id: 2
+tests:
+  - description: Apply backpressure on network connection errors during connection establishment
+    operations:
+      - name: createEntities
+        object: testRunner
+        arguments:
+          entities:
+            - client:
+                id: client
+                useMultipleMongoses: false
+                observeEvents:
+                  - serverHeartbeatSucceededEvent
+                  - poolReadyEvent
+                  - poolClearedEvent
+                uriOptions:
+                  retryWrites: false
+                  heartbeatFrequencyMS: 10000
+                  serverMonitoringMode: poll
+                  directConnection: true
+                  appname: backpressureNetworkErrorFailTest
+            - database:
+                id: database
+                client: client
+                databaseName: sdam-tests
+            - collection:
+                id: collection
+                database: database
+                collectionName: backpressure-network-error-fail
+      - name: waitForEvent
+        object: testRunner
+        arguments:
+          client: client
+          event:
+            serverHeartbeatSucceededEvent: {}
+          count: 1
+      - name: failPoint
+        object: testRunner
+        arguments:
+          client: setupClient
+          failPoint:
+            configureFailPoint: failCommand
+            mode: alwaysOn
+            data:
+              failCommands:
+                - isMaster
+                - hello
+              appName: backpressureNetworkErrorFailTest
+              closeConnection: true
+      - name: insertMany
+        object: collection
+        arguments:
+          documents:
+            - _id: 3
+            - _id: 4
+        expectError:
+          isError: true
+          errorLabelsContain:
+            - SystemOverloadedError
+            - RetryableError
+    expectEvents:
+      - client: client
+        eventType: cmap
+        events:
+          - poolReadyEvent: {}