DRIVERS-2711: Publish Topology Description Changed Event on Topology …

…Close (#1495)

source/load-balancers/load-balancers.md

@@ -81,8 +81,9 @@ Although there is no monitoring connection in load balanced mode, drivers MUST e
 - `TopologyDescriptionChangedEvent`. The `newDescription` MUST have `TopologyType` `LoadBalanced` and one server with
  `ServerType` `LoadBalancer`.
 
-Drivers MUST also emit a `ServerClosedEvent` and `TopologyClosedEvent` when the topology is closed and MUST NOT emit any
-other events when operating in this mode.
+Drivers MUST also emit a `ServerClosedEvent` followed by a `TopologyDescriptionChangedEvent` that transitions the
+`Topology` to the `UNKNOWN` state and a `TopologyClosedEvent` when the topology is closed and MUST NOT emit any other
+events when operating in this mode.
 
 #### Log Messages
 
@@ -328,6 +329,7 @@ only load balancers that support the PROXY protocol would be supported.
 
 ## Changelog
 
+- 2024-04-25: Clarify that `TopologyDescriptionChangedEvent` must be emitted on topology close
 - 2024-03-06: Migrated from reStructuredText to Markdown.
 - 2022-10-05: Remove spec front matter and reformat changelog.
 - 2022-01-18: Clarify that `OP_MSG` must be used in load balanced mode.

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

@@ -117,6 +117,12 @@ Initial Topology Description
 
 The first ``TopologyDescriptionChangedEvent`` to be emitted from a monitored Topology MUST set its ``previousDescription`` property to be a ``TopologyDescription`` object in the "unknown" state.
 
+Closing Topology Description
+----------------------------
+
+When a ``Topology`` object or equivalent is being shut-down or closed, the driver MUST change the
+``TopologyDescription`` to an "unknown" state.
+
 ----------
 Events API
 ----------
@@ -706,6 +712,7 @@ Changelog
 
 :2024-03-29: Updated to clarify expected initial value of TopologyDescriptionChangedEvent's
  previousDescription field
+:2024-01-17: Updated to require that ``TopologyDescriptionChangedEvent`` should be emitted before just ``TopologyClosedEvent`` is emitted
 :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. 

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

@@ -533,6 +533,15 @@ Single-threaded clients do no I/O in the constructor.
 They MUST `scan`_ the servers on demand,
 when the first operation is attempted.
 
+Client closing
+''''''''''''''
+
+When a client is closing, before it emits the ``TopologyClosedEvent`` as per the
+`Events API <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst#events-api>`_, 
+it SHOULD `remove`_ all servers from its ``TopologyDescription`` and set its
+``TopologyType`` to ``Unknown``, emitting the corresponding
+``TopologyDescriptionChangedEvent``.
+
 Monitoring
 ''''''''''
 
@@ -2543,6 +2552,7 @@ Changelog
 :2022-09-30: Update ``updateRSFromPrimary`` to include logic before and after 6.0 servers
 :2022-10-05: Remove spec front matter, move footnote, and reformat changelog.
 :2022-11-17: Add minimum RTT tracking and remove 90th percentile RTT.
+:2024-01-17: Add section on expected client close behaviour
 
 ----
 

source/server-discovery-and-monitoring/tests/unified/loadbalanced-emit-topology-changed-before-close.yml

@@ -0,0 +1,49 @@
+description: "loadbalanced-emit-topology-description-changed-before-close"
+
+schemaVersion: "1.20"
+
+runOnRequirements:
+ - topologies:
+ - load-balanced
+ minServerVersion: "4.4" # awaitable hello
+
+tests:
+ - description: "Topology lifecycle"
+ operations:
+ - name: createEntities
+ object: testRunner
+ arguments:
+ entities:
+ - client:
+ id: &client client
+ observeEvents:
+ - topologyDescriptionChangedEvent
+ - topologyOpeningEvent
+ - topologyClosedEvent
+ # ensure the topology has been fully discovered before closing the client.
+ # expected events are initial server discovery and server connect event.
+ - name: waitForEvent
+ object: testRunner
+ arguments:
+ client: *client
+ event:
+ topologyDescriptionChangedEvent: {}
+ count: 2
+ - name: close
+ object: *client
+ expectEvents:
+ - client: *client
+ eventType: sdam
+ events:
+ - topologyOpeningEvent: {}
+ - topologyDescriptionChangedEvent: # unknown -> unknown w disconnected server
+ previousDescription: 
+ type: "Unknown"
+ newDescription: {}
+ - topologyDescriptionChangedEvent: # unknown w disconnected server -> loadBalanced
+ newDescription:
+ type: "LoadBalanced"
+ - topologyDescriptionChangedEvent: # loadbalanced -> unknown
+ newDescription:
+ type: "Unknown"
+ - topologyClosedEvent: {}

source/server-discovery-and-monitoring/tests/unified/logging-loadbalanced.yml

@@ -67,8 +67,15 @@ tests:
  topologyId: { $$exists: true }
  serverHost: { $$type: string }
  serverPort: { $$type: [int, long] }
+ - level: debug
+ component: topology
+ data:
+ message: "Topology description changed"
+ topologyId: { $$exists: true }
+ previousDescription: { $$exists: true } # loadBalanced topology
+ newDescription: { $$exists: true } # unknown topology
  - level: debug
  component: topology
  data:
  message: "Stopped topology monitoring"
- topologyId: { $$exists: true }
+ topologyId: { $$exists: true }

source/server-discovery-and-monitoring/tests/unified/replicaset-emit-topology-changed-before-close.yml

@@ -0,0 +1,49 @@
+description: "replicaset-emit-topology-description-changed-before-close"
+
+schemaVersion: "1.20"
+
+runOnRequirements:
+ - topologies:
+ - replicaset
+ minServerVersion: "4.4" # awaitable hello
+
+tests:
+ - description: "Topology lifecycle"
+ operations:
+ - name: createEntities
+ object: testRunner
+ arguments:
+ entities:
+ - client:
+ id: &client client
+ observeEvents:
+ - topologyDescriptionChangedEvent
+ - topologyOpeningEvent
+ - topologyClosedEvent
+ # ensure the topology has been fully discovered before closing the client.
+ # expected events are initial server discovery and 3 server connect events.
+ - name: waitForEvent
+ object: testRunner
+ arguments:
+ client: *client
+ event:
+ topologyDescriptionChangedEvent: {}
+ count: 4
+ - name: close
+ object: *client
+ expectEvents:
+ - client: *client
+ eventType: sdam
+ ignoreExtraEvents: false
+ events:
+ - topologyOpeningEvent: {}
+ - topologyDescriptionChangedEvent: {} # unknown -> replset no primary
+ - topologyDescriptionChangedEvent: {} # server connected
+ - topologyDescriptionChangedEvent: {} # server connected
+ - topologyDescriptionChangedEvent: {} # server connected
+ - topologyDescriptionChangedEvent: # replicaset -> unknown
+ previousDescription:
+ type: "ReplicaSetWithPrimary"
+ newDescription:
+ type: "Unknown"
+ - topologyClosedEvent: {}