From c5deb518943789a8a217bf4fb82099e68811839b Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 14 Dec 2023 15:50:46 -0500 Subject: [PATCH 01/27] DRIVERS-2677: clarify heartbeat started event ordering and field requirements --- ...server-discovery-and-monitoring-logging-and-monitoring.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 66e171ddfb..2af53b5348 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -263,7 +263,7 @@ Events that MUST be published (with their conditions) are as follows. * The name of this field is flexible to match the object that is returned from the driver. * Examples are, but not limited to, 'address', 'serverAddress', 'connectionId', */ - connectionId: ConnectionId; + connectionId: Optional; /** * Determines if this heartbeat event is for an awaitable ``hello`` or legacy hello. @@ -462,7 +462,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 MAY 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 From 00304baed3bd877fd52e86061be47e67f70709cb Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 11:12:35 -0500 Subject: [PATCH 02/27] DRIVERS-2677 Clarify ordering of ServerHeartbeatStartedEvent and monitor connection creation --- ...iscovery-and-monitoring-logging-and-monitoring.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 2af53b5348..36f4b16a85 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. First published just before the monitor creates the socket for this connection. * - ``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 just starting, the first instance of this event is fired just before the + * socket is opened. */ interface ServerHeartbeatStartedEvent { @@ -263,7 +265,7 @@ Events that MUST be published (with their conditions) are as follows. * The name of this field is flexible to match the object that is returned from the driver. * Examples are, but not limited to, 'address', 'serverAddress', 'connectionId', */ - connectionId: Optional; + connectionId: ConnectionId; /** * Determines if this heartbeat event is for an awaitable ``hello`` or legacy hello. @@ -462,8 +464,8 @@ 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 MAY be omitted in certain cases, e.g. the first - "heartbeat started" message for a monitoring connection. Only present on server versions 4.2+. + - 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. This value MUST never be given a default value if it is unknown. Only present on server versions 4.2+. "Starting Topology Monitoring" Log Message ------------------------------------------ @@ -696,6 +698,7 @@ See the `README Date: Fri, 5 Jan 2024 11:14:41 -0500 Subject: [PATCH 03/27] Correct typo --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 36f4b16a85..62c7020e88 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -698,7 +698,7 @@ See the `README Date: Fri, 5 Jan 2024 11:49:38 -0500 Subject: [PATCH 04/27] Update wording on undefined value --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 62c7020e88..ec20401076 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -465,7 +465,7 @@ The following key-value pairs are common to all or several log messages and MUST - Heartbeat-related log messages - Int - 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. This value MUST never be given a default value if it is unknown. Only present on server versions 4.2+. + "heartbeat started" message for a monitoring connection. This value MUST be given a value that explicitly communicates that the value is undefined if it is unknown (e.g.: ``undefined`` in Javascript or ``None`` in Python). Only present on server versions 4.2+. "Starting Topology Monitoring" Log Message ------------------------------------------ From 879e676663c18ded627b958a668509c65367327e Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 11:52:07 -0500 Subject: [PATCH 05/27] Update wording on undefined value --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index ec20401076..7659546f6f 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -465,7 +465,7 @@ The following key-value pairs are common to all or several log messages and MUST - Heartbeat-related log messages - Int - 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. This value MUST be given a value that explicitly communicates that the value is undefined if it is unknown (e.g.: ``undefined`` in Javascript or ``None`` in Python). Only present on server versions 4.2+. + "heartbeat started" message for a monitoring connection. Only present on server versions 4.2+. "Starting Topology Monitoring" Log Message ------------------------------------------ From fd946d2aa613daa534c11591b2fd5c428ac14118 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 15:54:43 -0500 Subject: [PATCH 06/27] add rationale --- ...iscovery-and-monitoring-logging-and-monitoring.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 7659546f6f..6f90c5f787 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -694,6 +694,17 @@ Tests See the `README `_. +--------- +Rationale +--------- + +Why is the ``ServerHeartbeatStartedEvent`` emitted before monitor connection establishment? +------------------------------------------------------------------------------------------- + +In the event that a driver fails to create a connection, this would result in the emission of the +``ServerHeartbeatFailedEvent``, implying that the creation of the monitor connection is a part the +initial heartbeat and so should be accounted for in the ``duration`` field of the +``ServerHeartbeatFailedEvent`` and ``ServerHeartbeatSucceededEvent``. Changelog ========= From 6372ba38f96cf99d723875724071109517568d67 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:00:52 -0500 Subject: [PATCH 07/27] revise ordering --- ...ery-and-monitoring-logging-and-monitoring.rst | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 6f90c5f787..1bbc3a6cc3 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. First published just before the monitor creates the socket for this connection. + - Published when the server monitor sends its ``hello`` or legacy hello call to the server. First published just after the monitor creates the socket for this connection and just before the ``hello`` or legacy hello call. * - ``ServerHeartbeatSucceededEvent`` - Published on successful completion of the server monitor's ``hello`` or legacy hello call. * - ``ServerHeartbeatFailedEvent`` @@ -251,7 +251,7 @@ 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 just starting, the first instance of this event is fired just before the + * When the monitor is just starting, the first instance of this event is fired just after the * socket is opened. */ interface ServerHeartbeatStartedEvent { @@ -694,18 +694,6 @@ Tests See the `README `_. ---------- -Rationale ---------- - -Why is the ``ServerHeartbeatStartedEvent`` emitted before monitor connection establishment? -------------------------------------------------------------------------------------------- - -In the event that a driver fails to create a connection, this would result in the emission of the -``ServerHeartbeatFailedEvent``, implying that the creation of the monitor connection is a part the -initial heartbeat and so should be accounted for in the ``duration`` field of the -``ServerHeartbeatFailedEvent`` and ``ServerHeartbeatSucceededEvent``. - Changelog ========= From 5816c83fdc5acbee954ade3c2f46495f6b99f40f Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:42:30 -0500 Subject: [PATCH 08/27] Update spacing --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 1bbc3a6cc3..089b50add7 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -694,6 +694,7 @@ Tests See the `README `_. + Changelog ========= From 3bc7921f56462efc198a201d585df812d2e610d0 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:42:52 -0500 Subject: [PATCH 09/27] Add prose test in progress --- .../tests/README.rst | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 9dce162f3d..58ae623f02 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -262,6 +262,34 @@ Run the following test(s) on MongoDB 4.4+. mode: "off", }); +Heartbeat Started Tests +~~~~~~~~~~~~~~~~~~~~~~~ + +All drivers should test the following scenario, making any adjustments necessary to accommodate your +language. + +Run the following test(s) against MongoDB 4.2+ standalone server. + +1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made + + #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, + ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. + + #. Connect to the server + + #. Sleep for 2 seconds + + #. Close the client + + #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted + + #. Assert that the client has created one socket and that it was created before the + ``ServerHeartbeatStartedEvent`` was emitted + + #. Assert that the ``hello`` was sent after the ``ServerHeartbeatStartedEvent`` was emitted. + + #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted + .. Section for links. .. _Server Description Equality: /source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#server-description-equality From c448f03ad92e70080fd9e4d4bc77c801b97de037 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:44:31 -0500 Subject: [PATCH 10/27] formatting --- source/server-discovery-and-monitoring/tests/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 58ae623f02..497c822a73 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -272,8 +272,8 @@ Run the following test(s) against MongoDB 4.2+ standalone server. 1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made - #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, - ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. + #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, + ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. #. Connect to the server From b7677989669e8847c1d22369f1f441bc85841e60 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:45:15 -0500 Subject: [PATCH 11/27] formatting --- source/server-discovery-and-monitoring/tests/README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 497c822a73..c46d7f85fd 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -271,9 +271,8 @@ language. Run the following test(s) against MongoDB 4.2+ standalone server. 1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made - - #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, - ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. + #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, + ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. #. Connect to the server From cedb0a26e1d0541aeec6b6589099d29e6889d084 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:46:41 -0500 Subject: [PATCH 12/27] formatting --- .../tests/README.rst | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index c46d7f85fd..66af342586 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -270,24 +270,16 @@ language. Run the following test(s) against MongoDB 4.2+ standalone server. -1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made - #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, - ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. - - #. Connect to the server - - #. Sleep for 2 seconds - - #. Close the client - - #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted - - #. Assert that the client has created one socket and that it was created before the - ``ServerHeartbeatStartedEvent`` was emitted - - #. Assert that the ``hello`` was sent after the ``ServerHeartbeatStartedEvent`` was emitted. - - #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted +1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made. + + #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. + #. Connect to the server + #. Sleep for 2 seconds + #. Close the client + #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted + #. Assert that the client has created one socket and that it was created before the ``ServerHeartbeatStartedEvent`` was emitted + #. Assert that the ``hello`` was sent after the ``ServerHeartbeatStartedEvent`` was emitted. + #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted .. Section for links. From f23648964bdcfd73a7c86449692d35d9677ab29f Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:47:04 -0500 Subject: [PATCH 13/27] formatting --- source/server-discovery-and-monitoring/tests/README.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 66af342586..c45356dd28 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -273,12 +273,19 @@ Run the following test(s) against MongoDB 4.2+ standalone server. 1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made. #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. + #. Connect to the server + #. Sleep for 2 seconds + #. Close the client + #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted + #. Assert that the client has created one socket and that it was created before the ``ServerHeartbeatStartedEvent`` was emitted + #. Assert that the ``hello`` was sent after the ``ServerHeartbeatStartedEvent`` was emitted. + #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted .. Section for links. From e1d798d0a887b63de5adb5a88317c0b2b259359e Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 5 Jan 2024 17:47:44 -0500 Subject: [PATCH 14/27] ordering --- source/server-discovery-and-monitoring/tests/README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index c45356dd28..dd4080ec90 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -262,14 +262,14 @@ Run the following test(s) on MongoDB 4.4+. mode: "off", }); -Heartbeat Started Tests +Heartbeat Tests ~~~~~~~~~~~~~~~~~~~~~~~ +Run the following test(s) against MongoDB 4.2+ standalone server. + All drivers should test the following scenario, making any adjustments necessary to accommodate your language. -Run the following test(s) against MongoDB 4.2+ standalone server. - 1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made. #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. From 8d1b6be86663fd999f1a4bb2f57591458a5707e0 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 10:21:35 -0500 Subject: [PATCH 15/27] add new prose test --- .../tests/README.rst | 38 +++++++++++++++++-- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index dd4080ec90..f7b5841757 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -276,10 +276,6 @@ language. #. Connect to the server - #. Sleep for 2 seconds - - #. Close the client - #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted #. Assert that the client has created one socket and that it was created before the ``ServerHeartbeatStartedEvent`` was emitted @@ -288,6 +284,40 @@ language. #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted + #. Close the client + +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, maxPoolSize: 1, minPoolSize: 0`` 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 a length of 4 + + #. Assert that the first event is the ``client connected`` event + + #. Assert that the second event is the ``serverHeartbeatStartedEvent`` + + #. Assert that the third event is the ``client hello received`` event + + #. Assert that the fourth event is the ``serverHeartbeatFailedEvent`` + .. Section for links. .. _Server Description Equality: /source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#server-description-equality From 1279fa8c60838222763d0084777bdaf7798d1753 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 10:22:01 -0500 Subject: [PATCH 16/27] remove old prose test --- .../tests/README.rst | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index f7b5841757..34c29ce513 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -262,30 +262,6 @@ Run the following test(s) on MongoDB 4.4+. mode: "off", }); -Heartbeat Tests -~~~~~~~~~~~~~~~~~~~~~~~ - -Run the following test(s) against MongoDB 4.2+ standalone server. - -All drivers should test the following scenario, making any adjustments necessary to accommodate your -language. - -1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` call was made. - - #. Create a client with ``heartbeatFrequencyMS=10000``, ``appName=heartbeatTest``, ``minPoolSize=0``, ``maxPoolSize=1`` and listen to server events. - - #. Connect to the server - - #. Assert that one ``ServerHeartbeatStartedEvent`` has been emitted - - #. Assert that the client has created one socket and that it was created before the ``ServerHeartbeatStartedEvent`` was emitted - - #. Assert that the ``hello`` was sent after the ``ServerHeartbeatStartedEvent`` was emitted. - - #. Assert that the ``ServerHeartbeatSucceededEvent`` was emitted - - #. Close the client - Heartbeat Tests ~~~~~~~~~~~~~~~ From 434acab0f39d0d48c131ae6f953ff86a96399432 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 14:40:27 -0500 Subject: [PATCH 17/27] remove poolSize settings --- source/server-discovery-and-monitoring/tests/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 34c29ce513..bfcec95fd6 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -280,7 +280,7 @@ Heartbeat Tests }); server.listen(9999); - #. Create a client with ``serverSelectionTimeoutMS: 500, maxPoolSize: 1, minPoolSize: 0`` and listen to ``ServerHeartbeatStartedEvent`` and ``ServerHeartbeatFailedEvent``, pushing the event name to the same shared array as the mock TCP server. + #. 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 From 9ec5ddff85012d476cd14f68cc13d793090d886a Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 14:49:02 -0500 Subject: [PATCH 18/27] Fix wording and remove unnecessary config --- ...discovery-and-monitoring-logging-and-monitoring.rst | 2 +- .../server-discovery-and-monitoring/tests/README.rst | 10 ++-------- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 089b50add7..b4e76d0191 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -251,7 +251,7 @@ 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 just starting, the first instance of this event is fired just after the + * When the monitor is creating a new monitoring connection, this event is fired just after the * socket is opened. */ interface ServerHeartbeatStartedEvent { diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index bfcec95fd6..efc66fd3b7 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -284,15 +284,9 @@ Heartbeat Tests #. Attempt to connect client to previously created TCP server, catching the error when the client fails to connect - #. Assert that the event array has a length of 4 + #. Assert that the event array has the following contents in the same order:: - #. Assert that the first event is the ``client connected`` event - - #. Assert that the second event is the ``serverHeartbeatStartedEvent`` - - #. Assert that the third event is the ``client hello received`` event - - #. Assert that the fourth event is the ``serverHeartbeatFailedEvent`` + ``['client connected', 'serverHeartbeatStartedEvent', 'client hello received', 'serverHeartbeatFailedEvent']`` .. Section for links. From d8ecff37f404197735e192b6f46a55d554fa3fe4 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 14:51:45 -0500 Subject: [PATCH 19/27] refine wording --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index b4e76d0191..f75cd983a3 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. First published just after the monitor creates the socket for this connection and just before the ``hello`` or legacy hello call. + - 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 is 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`` From ee6c986c9f9f8ed7b0628229e53ad37171505113 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 14:53:05 -0500 Subject: [PATCH 20/27] strengthen wording --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index f75cd983a3..7f5ef43678 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. When the monitor is creating a new connection, this event is published just after the socket is created and just before the ``hello`` or legacy hello. + - 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`` From 1072e224b331909f9e8867dcbc60627b504a2e47 Mon Sep 17 00:00:00 2001 From: Warren James Date: Tue, 9 Jan 2024 14:54:19 -0500 Subject: [PATCH 21/27] remove backticks --- source/server-discovery-and-monitoring/tests/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index efc66fd3b7..9cf71e2cde 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -286,7 +286,7 @@ Heartbeat Tests #. Assert that the event array has the following contents in the same order:: - ``['client connected', 'serverHeartbeatStartedEvent', 'client hello received', 'serverHeartbeatFailedEvent']`` + ['client connected', 'serverHeartbeatStartedEvent', 'client hello received', 'serverHeartbeatFailedEvent'] .. Section for links. From 6b93f0c302c3f61c470b1eb4a01a7f55a7c5420a Mon Sep 17 00:00:00 2001 From: Warren James Date: Wed, 10 Jan 2024 16:22:59 -0500 Subject: [PATCH 22/27] Reorder events --- ...r-discovery-and-monitoring-logging-and-monitoring.rst | 9 +++++++-- source/server-discovery-and-monitoring/tests/README.rst | 2 +- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 7f5ef43678..9a63469309 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. 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. + - 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,7 +251,7 @@ 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 + * When the monitor is creating a new monitoring connection, this event is fired just before the * socket is opened. */ interface ServerHeartbeatStartedEvent { @@ -614,6 +614,11 @@ The unstructured form SHOULD be as follows, using the values defined in the stru Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} and server-generated ID {{serverConnectionId}} in topology with ID {{topologyId}}. Awaited: {{awaited}} +If the ``serverConnectionId`` is not yet known at the time this log is emitted, the unstructured form should be as follows: + + Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} in topology with ID + {{topologyId}}. Awaited: {{awaited}} + "Server Heartbeat Succeeded" Log Message ---------------------------------------- This message MUST be published under the same circumstances as a ``ServerHeartbeatSucceededEvent`` as detailed in `Events API <#events-api>`_. diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index 9cf71e2cde..dde6a0756c 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -286,7 +286,7 @@ Heartbeat Tests #. Assert that the event array has the following contents in the same order:: - ['client connected', 'serverHeartbeatStartedEvent', 'client hello received', 'serverHeartbeatFailedEvent'] + ['serverHeartbeatStartedEvent', 'client connected', 'client hello received', 'serverHeartbeatFailedEvent'] .. Section for links. From 6b0e0eee5c8e5ae03453d75d91f2c3d176ccd460 Mon Sep 17 00:00:00 2001 From: Warren James Date: Wed, 10 Jan 2024 16:24:57 -0500 Subject: [PATCH 23/27] capitalize --- .../server-discovery-and-monitoring-logging-and-monitoring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 9a63469309..ee42ce76e0 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -614,7 +614,7 @@ The unstructured form SHOULD be as follows, using the values defined in the stru Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} and server-generated ID {{serverConnectionId}} in topology with ID {{topologyId}}. Awaited: {{awaited}} -If the ``serverConnectionId`` is not yet known at the time this log is emitted, the unstructured form should be as follows: +If the ``serverConnectionId`` is not yet known at the time this log is emitted, the unstructured form SHOULD be as follows: Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} in topology with ID {{topologyId}}. Awaited: {{awaited}} From c6cc6250b738c9fb53564a0d9612eb6c4a49adc5 Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 11 Jan 2024 16:09:57 -0500 Subject: [PATCH 24/27] Fix spelling and update prose test --- ...-and-monitoring-logging-and-monitoring.rst | 2 +- .../tests/README.rst | 22 +++++-------------- 2 files changed, 6 insertions(+), 18 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index ee42ce76e0..a934a21142 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/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. When the monitor is creating a new connection, this event MUST be published just before the socket is created + - 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`` diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index dde6a0756c..9dbccbba4f 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -265,28 +265,16 @@ Run the following test(s) on MongoDB 4.4+. Heartbeat Tests ~~~~~~~~~~~~~~~ -1. Test that ``ServerHeartbeatStartedEvent`` is emitted after the monitoring socket was created and before the ``hello`` is sent to the server +1. Test that a failure to create a monitoring connection results in the emission of a + ``ServerHeartbeatStartedEvent`` and a ``ServerHeartbeatFailedEvent`` - #. 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'); + #. Create a client with ``serverSelectionTimeoutMS: 500`` and listen to ``ServerHeartbeatStartedEvent`` and ``ServerHeartbeatFailedEvent``, pushing the event names to an array. - 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 + #. Attempt to connect client to a local port that is not listening for connections. e.g. ``mongodb://localhost:9999`` #. Assert that the event array has the following contents in the same order:: - ['serverHeartbeatStartedEvent', 'client connected', 'client hello received', 'serverHeartbeatFailedEvent'] + ['serverHeartbeatStartedEvent', 'serverHeartbeatFailedEvent'] .. Section for links. From 9d33a8951ba795cd0874b352299db8ab1a6d7dcc Mon Sep 17 00:00:00 2001 From: Warren James Date: Thu, 11 Jan 2024 16:14:04 -0500 Subject: [PATCH 25/27] Remove section on serverConnectionId --- ...erver-discovery-and-monitoring-logging-and-monitoring.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index a934a21142..541e56555c 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -614,11 +614,6 @@ The unstructured form SHOULD be as follows, using the values defined in the stru Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} and server-generated ID {{serverConnectionId}} in topology with ID {{topologyId}}. Awaited: {{awaited}} -If the ``serverConnectionId`` is not yet known at the time this log is emitted, the unstructured form SHOULD be as follows: - - Heartbeat started for {{serverHost}}:{{serverPort}} on connection with driver-generated ID {{driverConnectionId}} in topology with ID - {{topologyId}}. Awaited: {{awaited}} - "Server Heartbeat Succeeded" Log Message ---------------------------------------- This message MUST be published under the same circumstances as a ``ServerHeartbeatSucceededEvent`` as detailed in `Events API <#events-api>`_. From ac2e8bc879d83a1eae8e73dc49b78c69bb5e1a24 Mon Sep 17 00:00:00 2001 From: Warren James Date: Fri, 12 Jan 2024 15:22:43 -0500 Subject: [PATCH 26/27] Remove references to serverConnectionId --- ...server-discovery-and-monitoring-logging-and-monitoring.rst | 4 ++-- source/server-discovery-and-monitoring/tests/README.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst index 541e56555c..1232e2c964 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst @@ -464,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 MUST 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 can 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 @@ -698,7 +698,7 @@ See the `README Date: Tue, 16 Jan 2024 14:21:07 -0500 Subject: [PATCH 27/27] update prose tests --- .../tests/README.rst | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/source/server-discovery-and-monitoring/tests/README.rst b/source/server-discovery-and-monitoring/tests/README.rst index bc59ec198b..06006a17b1 100644 --- a/source/server-discovery-and-monitoring/tests/README.rst +++ b/source/server-discovery-and-monitoring/tests/README.rst @@ -265,16 +265,28 @@ Run the following test(s) on MongoDB 4.4+. Heartbeat Tests ~~~~~~~~~~~~~~~ -1. Test that a failure to create a monitoring connection results in the emission of a - ``ServerHeartbeatStartedEvent`` and a ``ServerHeartbeatFailedEvent`` +1. Test that ``ServerHeartbeatStartedEvent`` is emitted before the monitoring socket was created - #. Create a client with ``serverSelectionTimeoutMS: 500`` and listen to ``ServerHeartbeatStartedEvent`` and ``ServerHeartbeatFailedEvent``, pushing the event names to an array. + #. 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'); - #. Attempt to connect client to a local port that is not listening for connections. e.g. ``mongodb://localhost:9999`` + clientSocket.on('data', () => { + events.push('client hello received'); + clientSocket.destroy(); + }); + }); + server.listen(9999); - #. Assert that the first two elements in the array are: :: + #. 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 - ['serverHeartbeatStartedEvent', 'serverHeartbeatFailedEvent'] + #. Assert that the first four elements in the array are: :: + + ['serverHeartbeatStartedEvent', 'client connected', 'client hello received', 'serverHeartbeatFailedEvent'] .. Section for links.