DRIVERS-1785: clarify ordering of CMAP events when pool is cleared (#1690)

Author: baileympearson

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

@@ -30,11 +30,11 @@ events:
     address: 42
   - type: ConnectionCreated
     address: 42
+  - type: ConnectionPoolCleared
+    address: 42
   - type: ConnectionClosed
     address: 42
     connectionId: 42
     reason: error
-  - type: ConnectionPoolCleared
-    address: 42
 ignore:
   - ConnectionPoolCreated

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

@@ -1241,11 +1241,11 @@ if and only if the error is "node is shutting down" or the error originated from
 and [other transient errors](#other-transient-errors) and
 [Why close connections when a node is shutting down?](#why-close-connections-when-a-node-is-shutting-down).)
 
-##### Authentication errors
+##### Authentication and Handshake errors
 
-If the authentication handshake fails for a connection, drivers 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))
+If the driver encounters errors 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))
 
 ### Monitoring SDAM events
 

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

@@ -0,0 +1,88 @@
+---
+description: pool-clear-application-error
+
+schemaVersion: "1.4"
+
+runOnRequirements:
+  # failCommand appName requirements
+  - minServerVersion: "4.4"
+    serverless: forbid
+    topologies: [ single, replicaset, sharded ]
+
+createEntities:
+  - client:
+      id: &setupClient setupClient
+      useMultipleMongoses: false
+
+initialData: &initialData
+  - collectionName: &collectionName find-network-error
+    databaseName: &databaseName sdam-tests
+    documents:
+      - _id: 1
+      - _id: 2
+
+tests:
+  - description: Pool is cleared before application connection is checked into the pool
+    operations:
+      - name: failPoint
+        object: testRunner
+        arguments:
+          client: *setupClient
+          failPoint:
+            configureFailPoint: failCommand
+            mode:
+              times: 1
+            data:
+              failCommands:
+                - find
+              closeConnection: true
+              appName: findNetworkErrorTest
+      - name: createEntities
+        object: testRunner
+        arguments:
+          entities:
+            - client:
+                id: &client client
+                useMultipleMongoses: false
+                observeEvents:
+                  - poolClearedEvent
+                  - connectionCheckedInEvent
+                uriOptions:
+                  retryWrites: false
+                  retryReads: false
+                  appname: findNetworkErrorTest
+            - database:
+                id: &database database
+                client: *client
+                databaseName: *databaseName
+            - collection:
+                id: &collection collection
+                database: *database
+                collectionName: *collectionName
+      - name: find
+        object: *collection
+        arguments:
+          filter:
+            _id: 1
+        expectError:
+          isError: true
+      - name: waitForEvent
+        object: testRunner
+        arguments:
+          client: *client
+          event:
+            poolClearedEvent: {}
+          count: 1
+      - name: waitForEvent
+        object: testRunner
+        arguments:
+          client: *client
+          event:
+            connectionCheckedInEvent: {}
+          count: 1
+    expectEvents:
+      - client: *client
+        eventType: cmap
+        events:
+          - poolClearedEvent: {}
+          - connectionCheckedInEvent: {}