DRIVERS-2972: add message requirement to ServerDescription.error

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

@@ -226,7 +226,8 @@ Fields:
     field in the server's hello or legacy hello response, in the case that the server reports an address different from
     the address the client uses.
 
-- (=) `error`: information about the last error related to this server. Default null.
+- (=) `error`: information about the last error related to this server. Default null. MUST contain
+  or be able to produce a string describing the error.
 
 - `roundTripTime`: the duration of the hello or legacy hello call. Default null.
 
@@ -871,7 +872,8 @@ if serverDescription.maxWireVersion >= 17:  # MongoDB 6.0+
         topologyDescription.maxSetVersion = serverDescription.setVersion
     else:
         # Stale primary.
-        # replace serverDescription with a default ServerDescription of type "Unknown"
+        # replace serverDescription with a default ServerDescription of type "Unknown" and an error
+        # field describing that that primary was stale
         checkIfHasPrimary()
         return
 else:
@@ -889,7 +891,9 @@ else:
             )
         ):
             # Stale primary.
-            # replace serverDescription with a default ServerDescription of type "Unknown"
+            # replace serverDescription with a default ServerDescription of type "Unknown" and an
+            # error field describing that that primary was stale
+
             checkIfHasPrimary()
             return
 
@@ -905,7 +909,8 @@ else:
 for each server in topologyDescription.servers:
     if server.address != serverDescription.address:
         if server.type is RSPrimary:
-            # See note below about invalidating an old primary.
+            # See note below about invalidating an old primary and an error field describing that
+            # the primary was stale
             replace the server with a default ServerDescription of type "Unknown"
 
 for each address in serverDescription's "hosts", "passives", and "arbiters":
@@ -921,9 +926,11 @@ checkIfHasPrimary()
 ```
 
 A note on invalidating the old primary: when a new primary is discovered, the client finds the previous primary (there
-should be none or one) and replaces its description with a default ServerDescription of type "Unknown." A multi-threaded
-client MUST [request an immediate check](server-monitoring.md#requesting-an-immediate-check) for that server as soon as
-possible.
+should be none or one) and replaces its description with a default ServerDescription of type "Unknown". Additionally,
+the `error` field of the new `ServerDescription` object MUST include a descriptive error explaining that it was
+invalidated because the primary was determined to be stale. Drivers MAY additionally specify whether this was due to an
+electionId or setVersion mismatch. A multi-threaded client MUST
+[request an immediate check](server-monitoring.md#requesting-an-immediate-check) for that server as soon as possible.
 
 If the old primary server version is 4.0 or earlier, the client MUST clear its connection pool for the old primary, too:
 the connections are all bad because the old primary has closed its sockets. If the old primary server version is 4.2 or

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

@@ -71,6 +71,8 @@ following keys:
 
 - type: A ServerType name, like "RSSecondary". See [ServerType](../server-discovery-and-monitoring.md#servertype) for
     details pertaining to async and multi-threaded drivers.
+- error: An optional object with a with a string field containing a string that must be matched
+  against the message in the actual `ServerDescription.error`
 - setName: A string with the expected replica set name, or null.
 - setVersion: absent or an integer.
 - electionId: absent, null, or an ObjectId.

source/tests_that_need_to_change

@@ -0,0 +1,10 @@
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/new_primary.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/primary_disconnect_setversion.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/set_version_can_rollback.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/setversion_equal_max_without_electionid.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/setversion_greaterthan_max_without_electionid.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/setversion_without_electionid-pre-6.0.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/setversion_without_electionid.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/stepdown_change_set_name.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/use_setversion_without_electionid-pre-6.0.yml
+https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/tests/rs/use_setversion_without_electionid.yml