DRIVERS-2677: clarify when ServerHeartbeatStartedEvent should be emitted

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 after the socket is created and just before the ``hello`` or legacy hello.
    * - ``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 after the
+   * socket is opened.
    */
   interface ServerHeartbeatStartedEvent {
 
@@ -462,7 +464,7 @@ The following key-value pairs are common to all or several log messages and MUST
    * - serverConnectionId
      - Heartbeat-related log messages
      - Int
-     - The server's ID for the monitoring connection, if known. This value will be unknown and can be omitted in certain cases, e.g. the first
+     - The server's ID for the monitoring connection, if known. This value will be unknown and MUST be omitted in certain cases, e.g. the first
        "heartbeat started" message for a monitoring connection. Only present on server versions 4.2+.
 
 "Starting Topology Monitoring" Log Message
@@ -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 and when the serverConnectionId should be undefined.
 :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 after the monitoring socket was created and before the ``hello`` is sent to the server
+
+   #. 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.end();
+          });
+        });
+        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 event array has the following contents in the same order:: 
+
+        ['client connected', 'serverHeartbeatStartedEvent', 'client hello received', 'serverHeartbeatFailedEvent']
+
 .. Section for links.
 
 .. _Server Description Equality: /source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#server-description-equality