DRIVERS-2677: clarify when ServerHeartbeatStartedEvent should be emit…

…ted (#1483)

source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst

@@ -138,7 +138,7 @@ Events that MUST be published (with their conditions) are as follows.
    * - ``TopologyClosedEvent``
      - When a topology is shut down - this MUST be the last SDAM event fired.
    * - ``ServerHeartbeatStartedEvent``
-     - Published when the server monitor sends its ``hello`` or legacy hello call to the server.
+     - Published when the server monitor sends its ``hello`` or legacy hello call to the server. When the monitor is creating a new connection, this event MUST be published just before the socket is created.
    * - ``ServerHeartbeatSucceededEvent``
      - Published on successful completion of the server monitor's ``hello`` or legacy hello call.
    * - ``ServerHeartbeatFailedEvent``
@@ -251,6 +251,8 @@ Events that MUST be published (with their conditions) are as follows.
   /**
    * Fired when the server monitor's ``hello`` or legacy hello command is started - immediately before
    * the ``hello`` or legacy hello command is serialized into raw BSON and written to the socket.
+   * When the monitor is creating a new monitoring connection, this event is fired just before the
+   * socket is opened.
    */
   interface ServerHeartbeatStartedEvent {
 
@@ -696,6 +698,7 @@ See the `README <https://github.com/mongodb/specifications/server-discovery-and-
 Changelog
 =========
 
+:2024-01-04: Updated to clarify when ServerHeartbeatStartedEvent should be emitted
 :2023-03-31: Renamed to include "logging" in the title. Reorganized contents and made consistent with CLAM spec, and added requirements
              for SDAM log messages. 
 :2022-10-05: Remove spec front matter and reformat changelog.

source/server-discovery-and-monitoring/tests/README.rst

@@ -262,6 +262,32 @@ Run the following test(s) on MongoDB 4.4+.
              mode: "off",
          });
 
+Heartbeat Tests
+~~~~~~~~~~~~~~~
+
+1. Test that ``ServerHeartbeatStartedEvent`` is emitted before the monitoring socket was created
+
+   #. Create a mock TCP server (example shown below) that pushes a ``client connected`` event to a shared array when a client connects and a ``client hello received`` event when the server receives the client hello and then closes the connection::
+         
+        let events = [];
+        server = createServer(clientSocket => {
+          events.push('client connected');
+
+          clientSocket.on('data', () => {
+            events.push('client hello received');
+            clientSocket.destroy();
+          });
+        });
+        server.listen(9999);
+
+   #. Create a client with ``serverSelectionTimeoutMS: 500`` and listen to ``ServerHeartbeatStartedEvent`` and ``ServerHeartbeatFailedEvent``, pushing the event name to the same shared array as the mock TCP server
+
+   #. Attempt to connect client to previously created TCP server, catching the error when the client fails to connect
+
+   #. Assert that the first four elements in the array are: ::
+
+        ['serverHeartbeatStartedEvent', 'client connected', 'client hello received', 'serverHeartbeatFailedEvent']
+
 .. Section for links.
 
 .. _Server Description Equality: /source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#server-description-equality