@@ -226,7 +226,8 @@ Fields:
226
226
field in the server's hello or legacy hello response, in the case that the server reports an address different from
227
227
the address the client uses.
228
228
229
- - (=) ` error ` : information about the last error related to this server. Default null.
229
+ - (=) ` error ` : information about the last error related to this server. Default null. MUST contain or be able to produce
230
+ a string describing the error.
230
231
231
232
- ` roundTripTime ` : the duration of the hello or legacy hello call. Default null.
232
233
@@ -485,7 +486,13 @@ removed once the primary is checked.
485
486
#### error
486
487
487
488
If the client experiences any error when checking a server, it stores error information in the ServerDescription's error
488
- field.
489
+ field. The message contained in this field MUST contain the substrings detailed in the table below when the
490
+ ServerDescription is changed to Unknown in the circumstances outlined.
491
+
492
+ | circumstance | error substring |
493
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
494
+ | RSPrimary with a stale electionId/setVersion is discovered | ` 'primary marked stale due to electionId/setVersion mismatch, <stale tuple> is stale compared to <max tuple>' ` |
495
+ | New primary is elected/discovered | ` 'primary marked stale due to discovery of newer primary' ` |
489
496
490
497
#### roundTripTime
491
498
@@ -871,7 +878,8 @@ if serverDescription.maxWireVersion >= 17: # MongoDB 6.0+
871
878
topologyDescription.maxSetVersion = serverDescription.setVersion
872
879
else :
873
880
# Stale primary.
874
- # replace serverDescription with a default ServerDescription of type "Unknown"
881
+ # The error field MUST include the substring "primary marked stale due to electionId/setVersion mismatch"
882
+ replace serverDescription with a default ServerDescription of type " Unknown"
875
883
checkIfHasPrimary()
876
884
return
877
885
else :
@@ -889,7 +897,8 @@ else:
889
897
)
890
898
):
891
899
# Stale primary.
892
- # replace serverDescription with a default ServerDescription of type "Unknown"
900
+ # The error field MUST include the substring "primary marked stale due to electionId/setVersion mismatch"
901
+ replace serverDescription with a default ServerDescription of type " Unknown"
893
902
checkIfHasPrimary()
894
903
return
895
904
@@ -906,6 +915,7 @@ for each server in topologyDescription.servers:
906
915
if server.address != serverDescription.address:
907
916
if server.type is RSPrimary:
908
917
# See note below about invalidating an old primary.
918
+ # the error field MUST include the substring "primary marked stale due to discovery of newer primary"
909
919
replace the server with a default ServerDescription of type " Unknown"
910
920
911
921
for each address in serverDescription' s "hosts", "passives", and "arbiters":
@@ -921,9 +931,10 @@ checkIfHasPrimary()
921
931
```
922
932
923
933
A note on invalidating the old primary: when a new primary is discovered, the client finds the previous primary (there
924
- should be none or one) and replaces its description with a default ServerDescription of type "Unknown." A multi-threaded
925
- client MUST [ request an immediate check] ( server-monitoring.md#requesting-an-immediate-check ) for that server as soon as
926
- possible.
934
+ should be none or one) and replaces its description with a default ServerDescription of type "Unknown". Additionally,
935
+ the ` error ` field of the new ` ServerDescription ` object MUST include a descriptive error explaining that it was
936
+ invalidated because the primary was determined to be stale. A multi-threaded client MUST
937
+ [ request an immediate check] ( server-monitoring.md#requesting-an-immediate-check ) for that server as soon as possible.
927
938
928
939
If the old primary server version is 4.0 or earlier, the client MUST clear its connection pool for the old primary, too:
929
940
the connections are all bad because the old primary has closed its sockets. If the old primary server version is 4.2 or
@@ -934,6 +945,8 @@ See [replica set monitoring with and without a primary](#replica-set-monitoring-
934
945
If the server is primary with an obsolete electionId or setVersion, it is likely a stale primary that is going to step
935
946
down. Mark it Unknown and let periodic monitoring detect when it becomes secondary. See
936
947
[ using electionId and setVersion to detect stale primaries] ( #using-electionid-and-setversion-to-detect-stale-primaries ) .
948
+ Drivers MAY additionally specify whether this was due to an electionId or setVersion mismatch as described in the
949
+ [ ServerDescripion.error section] ( #error ) .
937
950
938
951
A note on checking "me": Unlike ` updateRSWithPrimaryFromMember ` , there is no need to remove the server if the address is
939
952
not equal to "me": since the server address will not be a member of either "hosts", "passives", or "arbiters", the
@@ -1921,16 +1934,6 @@ oversaw the specification process.
1921
1934
1922
1935
## Changelog
1923
1936
1924
- - 2024-11-11: Removed references to ` getLastError `
1925
-
1926
- - 2024-11-04: Make the description of ` TopologyDescription.servers ` consistent with the spec tests.
1927
-
1928
- - 2024-08-16: Updated host b wire versions in ` too_new ` and ` too_old ` tests
1929
-
1930
- - 2024-08-09: Updated wire versions in tests to 4.0+.
1931
-
1932
- - 2024-05-08: Migrated from reStructuredText to Markdown.
1933
-
1934
1937
- 2015-12-17: Require clients to compare (setVersion, electionId) tuples.
1935
1938
1936
1939
- 2015-10-09: Specify electionID comparison method.
@@ -2012,6 +2015,19 @@ oversaw the specification process.
2012
2015
2013
2016
- 2024-01-17: Add section on expected client close behaviour
2014
2017
2018
+ - 2024-05-08: Migrated from reStructuredText to Markdown.
2019
+
2020
+ - 2024-08-09: Updated wire versions in tests to 4.0+.
2021
+
2022
+ - 2024-08-16: Updated host b wire versions in ` too_new ` and ` too_old ` tests
2023
+
2024
+ - 2024-11-04: Make the description of ` TopologyDescription.servers ` consistent with the spec tests.
2025
+
2026
+ - 2024-11-11: Removed references to ` getLastError `
2027
+
2028
+ - 2025-01-22: Add error messages when a new primary is elected or a primary with a stale electionId or setVersion is
2029
+ discovered.
2030
+
2015
2031
______________________________________________________________________
2016
2032
2017
2033
[ ^ 1 ] : "localThresholdMS" was called "secondaryAcceptableLatencyMS" in the Read Preferences Spec, before it was superseded
0 commit comments