Skip to content

Commit 9546ff8

Browse files
JamesKovacsJamesKovacs
authored
DRIVERS-1293: Updated retryable reads/writes specs with modern terminology. (#974)
1 parent a9790ac commit 9546ff8

File tree

47 files changed

+258
-276
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+258
-276
lines changed

‎source/retryable-reads/retryable-reads.rst

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,16 @@ Retryable Reads
33
===============
44

55
:Spec Title: Retryable Reads
6-
:Spec Version: 1.2
7-
:Author: Vincent Kam
6+
:Spec Version: 1.2.1
7+
:Author: Vincent Kam
88
:Lead: Bernie Hackett
99
:Advisory Group: Shane Harvey, Scott L’Hommedieu, Jeremy Mikola
1010
:Approvers: Jason Carey, Bernie Hackett, Shane Harvey, Eliot Horowitz, Scott L’Hommedieu, Jeremy Mikola, Dan Pasette, Jeff Yemin
1111
:Status: Accepted
1212
:Type: Standards
1313
:Minimum Server Version: 3.6
14-
:Last Modified: 2021-03-24
15-
14+
:Last Modified: 2021-04-26
15+
1616
.. contents::
1717

1818
--------
@@ -22,7 +22,7 @@ Abstract
2222

2323
This specification is about the ability for drivers to automatically retry any
2424
read operation that has not yet received any results—due to a transient network
25-
error, a "not master" error after a replica set failover, etc.—exactly once.
25+
error, a "not writable primary" error after a replica set failover, etc.—exactly once.
2626

2727
This specification will
2828

@@ -36,7 +36,7 @@ META
3636

3737
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
3838
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
39-
interpreted as described in `RFC 2119 <https://www.ietf.org/rfc/rfc2119.txt>`_.
39+
interpreted as described in `RFC 2119 <https://www.ietf.org/rfc/rfc2119.txt>`_.
4040

4141
Specification
4242
=============
@@ -64,9 +64,9 @@ An error is considered retryable if it meets any of the following criteria:
6464
=============================== ==============
6565
InterruptedAtShutdown 11600
6666
InterruptedDueToReplStateChange 11602
67-
NotMaster 10107
68-
NotMasterNoSlaveOk 13435
69-
NotMasterOrSecondary 13436
67+
NotWritablePrimary 10107
68+
NotPrimaryNoSecondaryOk 13435
69+
NotPrimaryOrSecondary 13436
7070
PrimarySteppedDown 189
7171
ShutdownInProgress 91
7272
HostNotFound 7
@@ -75,10 +75,6 @@ NetworkTimeout 89
7575
SocketException 9001
7676
=============================== ==============
7777

78-
- a server error response without an error code or one different from those
79-
listed above, but with an error message containing the substring "not
80-
master" or "node is recovering"
81-
8278
- a `PoolClearedError`_
8379

8480
.. _PoolClearedError: ../connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst#connection-pool-errors
@@ -377,15 +373,15 @@ and reflects the flow described above.
377373
return executeCommand(connection, command);
378374
}
379375
380-
/* NetworkException and NotMasterException are both retryable errors. If
376+
/* NetworkException and NotWritablePrimaryException are both retryable errors. If
381377
* caught, remember the exception, update SDAM accordingly, and proceed with
382378
* retrying the operation. */
383379
try {
384380
return executeCommand(server, command);
385381
} catch (NetworkException originalError) {
386382
updateTopologyDescriptionForNetworkError(server, originalError);
387-
} catch (NotMasterException originalError) {
388-
updateTopologyDescriptionForNotMasterError(server, originalError);
383+
} catch (NotWritablePrimaryException originalError) {
384+
updateTopologyDescriptionForNotWritablePrimaryError(server, originalError);
389385
}
390386
return executeRetry(command, session, originalError);
391387
}
@@ -430,8 +426,8 @@ and reflects the flow described above.
430426
} catch (NetworkException secondError) {
431427
updateTopologyDescriptionForNetworkError(server, secondError);
432428
throw secondError;
433-
} catch (NotMasterException secondError) {
434-
updateTopologyDescriptionForNotMasterError(server, secondError);
429+
} catch (NotWritablePrimaryException secondError) {
430+
updateTopologyDescriptionForNotWritabelPrimaryError(server, secondError);
435431
throw secondError;
436432
} catch (DriverException ignoredError) {
437433
throw originalError;
@@ -677,6 +673,8 @@ degraded performance can simply disable ``retryableReads``.
677673
Changelog
678674
==========
679675

676+
2021-04-26: Replaced deprecated terminology; removed requirement to parse error message text as MongoDB 3.6+ servers will always return an error code
677+
680678
2021-03-23: Require that PoolClearedErrors are retried
681679

682680
2019-06-07: Mention $merge stage for aggregate alongside $out

‎source/retryable-reads/tests/aggregate-serverErrors.json

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@
218218
]
219219
},
220220
{
221-
"description": "Aggregate succeeds after NotMaster",
221+
"description": "Aggregate succeeds after NotWritablePrimary",
222222
"failPoint": {
223223
"configureFailPoint": "failCommand",
224224
"mode": {
@@ -311,7 +311,7 @@
311311
]
312312
},
313313
{
314-
"description": "Aggregate succeeds after NotMasterNoSlaveOk",
314+
"description": "Aggregate succeeds after NotPrimaryNoSecondaryOk",
315315
"failPoint": {
316316
"configureFailPoint": "failCommand",
317317
"mode": {
@@ -404,7 +404,7 @@
404404
]
405405
},
406406
{
407-
"description": "Aggregate succeeds after NotMasterOrSecondary",
407+
"description": "Aggregate succeeds after NotPrimaryOrSecondary",
408408
"failPoint": {
409409
"configureFailPoint": "failCommand",
410410
"mode": {
@@ -1055,7 +1055,7 @@
10551055
]
10561056
},
10571057
{
1058-
"description": "Aggregate fails after two NotMaster errors",
1058+
"description": "Aggregate fails after two NotWritablePrimary errors",
10591059
"failPoint": {
10601060
"configureFailPoint": "failCommand",
10611061
"mode": {
@@ -1139,7 +1139,7 @@
11391139
]
11401140
},
11411141
{
1142-
"description": "Aggregate fails after NotMaster when retryReads is false",
1142+
"description": "Aggregate fails after NotWritablePrimary when retryReads is false",
11431143
"clientOptions": {
11441144
"retryReads": false
11451145
},

‎source/retryable-reads/tests/aggregate-serverErrors.yml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ tests:
5252
- *retryable_command_started_event
5353
- *retryable_command_started_event
5454
-
55-
description: "Aggregate succeeds after NotMaster"
55+
description: "Aggregate succeeds after NotWritablePrimary"
5656
failPoint:
5757
<<: *failCommand_failPoint
5858
data: { failCommands: [aggregate], errorCode: 10107 }
@@ -61,7 +61,7 @@ tests:
6161
- *retryable_command_started_event
6262
- *retryable_command_started_event
6363
-
64-
description: "Aggregate succeeds after NotMasterNoSlaveOk"
64+
description: "Aggregate succeeds after NotPrimaryNoSecondaryOk"
6565
failPoint:
6666
<<: *failCommand_failPoint
6767
data: { failCommands: [aggregate], errorCode: 13435 }
@@ -70,7 +70,7 @@ tests:
7070
- *retryable_command_started_event
7171
- *retryable_command_started_event
7272
-
73-
description: "Aggregate succeeds after NotMasterOrSecondary"
73+
description: "Aggregate succeeds after NotPrimaryOrSecondary"
7474
failPoint:
7575
<<: *failCommand_failPoint
7676
data: { failCommands: [aggregate], errorCode: 13436 }
@@ -133,7 +133,7 @@ tests:
133133
- *retryable_command_started_event
134134
- *retryable_command_started_event
135135
-
136-
description: "Aggregate fails after two NotMaster errors"
136+
description: "Aggregate fails after two NotWritablePrimary errors"
137137
failPoint:
138138
<<: *failCommand_failPoint
139139
mode: { times: 2 }
@@ -146,7 +146,7 @@ tests:
146146
- *retryable_command_started_event
147147
- *retryable_command_started_event
148148
-
149-
description: "Aggregate fails after NotMaster when retryReads is false"
149+
description: "Aggregate fails after NotWritablePrimary when retryReads is false"
150150
clientOptions:
151151
retryReads: false
152152
failPoint:

‎source/retryable-reads/tests/aggregate.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,4 +84,4 @@ tests:
8484
aggregate: *collection_name
8585
pipeline: [{$match: {_id: {$gt: 1}}}, {$sort: {x: 1}}, {$out: 'output-collection'}]
8686
command_name: aggregate
87-
database_name: *database_name
87+
database_name: *database_name

‎source/retryable-reads/tests/changeStreams-client.watch-serverErrors.json

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@
142142
]
143143
},
144144
{
145-
"description": "client.watch succeeds after NotMaster",
145+
"description": "client.watch succeeds after NotWritablePrimary",
146146
"failPoint": {
147147
"configureFailPoint": "failCommand",
148148
"mode": {
@@ -197,7 +197,7 @@
197197
]
198198
},
199199
{
200-
"description": "client.watch succeeds after NotMasterNoSlaveOk",
200+
"description": "client.watch succeeds after NotPrimaryNoSecondaryOk",
201201
"failPoint": {
202202
"configureFailPoint": "failCommand",
203203
"mode": {
@@ -252,7 +252,7 @@
252252
]
253253
},
254254
{
255-
"description": "client.watch succeeds after NotMasterOrSecondary",
255+
"description": "client.watch succeeds after NotPrimaryOrSecondary",
256256
"failPoint": {
257257
"configureFailPoint": "failCommand",
258258
"mode": {
@@ -637,7 +637,7 @@
637637
]
638638
},
639639
{
640-
"description": "client.watch fails after two NotMaster errors",
640+
"description": "client.watch fails after two NotWritablePrimary errors",
641641
"failPoint": {
642642
"configureFailPoint": "failCommand",
643643
"mode": {
@@ -693,7 +693,7 @@
693693
]
694694
},
695695
{
696-
"description": "client.watch fails after NotMaster when retryReads is false",
696+
"description": "client.watch fails after NotWritablePrimary when retryReads is false",
697697
"clientOptions": {
698698
"retryReads": false
699699
},

‎source/retryable-reads/tests/changeStreams-client.watch-serverErrors.yml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ tests:
4545
- *retryable_command_started_event
4646
- *retryable_command_started_event
4747
-
48-
description: "client.watch succeeds after NotMaster"
48+
description: "client.watch succeeds after NotWritablePrimary"
4949
failPoint:
5050
<<: *failCommand_failPoint
5151
data: { failCommands: [aggregate], errorCode: 10107 }
@@ -54,7 +54,7 @@ tests:
5454
- *retryable_command_started_event
5555
- *retryable_command_started_event
5656
-
57-
description: "client.watch succeeds after NotMasterNoSlaveOk"
57+
description: "client.watch succeeds after NotPrimaryNoSecondaryOk"
5858
failPoint:
5959
<<: *failCommand_failPoint
6060
data: { failCommands: [aggregate], errorCode: 13435 }
@@ -63,7 +63,7 @@ tests:
6363
- *retryable_command_started_event
6464
- *retryable_command_started_event
6565
-
66-
description: "client.watch succeeds after NotMasterOrSecondary"
66+
description: "client.watch succeeds after NotPrimaryOrSecondary"
6767
failPoint:
6868
<<: *failCommand_failPoint
6969
data: { failCommands: [aggregate], errorCode: 13436 }
@@ -126,7 +126,7 @@ tests:
126126
- *retryable_command_started_event
127127
- *retryable_command_started_event
128128
-
129-
description: "client.watch fails after two NotMaster errors"
129+
description: "client.watch fails after two NotWritablePrimary errors"
130130
failPoint:
131131
<<: *failCommand_failPoint
132132
mode: { times: 2 }
@@ -139,7 +139,7 @@ tests:
139139
- *retryable_command_started_event
140140
- *retryable_command_started_event
141141
-
142-
description: "client.watch fails after NotMaster when retryReads is false"
142+
description: "client.watch fails after NotWritablePrimary when retryReads is false"
143143
clientOptions:
144144
retryReads: false
145145
failPoint:

‎source/retryable-reads/tests/changeStreams-db.coll.watch-serverErrors.json

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@
134134
]
135135
},
136136
{
137-
"description": "db.coll.watch succeeds after NotMaster",
137+
"description": "db.coll.watch succeeds after NotWritablePrimary",
138138
"failPoint": {
139139
"configureFailPoint": "failCommand",
140140
"mode": {
@@ -185,7 +185,7 @@
185185
]
186186
},
187187
{
188-
"description": "db.coll.watch succeeds after NotMasterNoSlaveOk",
188+
"description": "db.coll.watch succeeds after NotPrimaryNoSecondaryOk",
189189
"failPoint": {
190190
"configureFailPoint": "failCommand",
191191
"mode": {
@@ -236,7 +236,7 @@
236236
]
237237
},
238238
{
239-
"description": "db.coll.watch succeeds after NotMasterOrSecondary",
239+
"description": "db.coll.watch succeeds after NotPrimaryOrSecondary",
240240
"failPoint": {
241241
"configureFailPoint": "failCommand",
242242
"mode": {
@@ -593,7 +593,7 @@
593593
]
594594
},
595595
{
596-
"description": "db.coll.watch fails after two NotMaster errors",
596+
"description": "db.coll.watch fails after two NotWritablePrimary errors",
597597
"failPoint": {
598598
"configureFailPoint": "failCommand",
599599
"mode": {
@@ -645,7 +645,7 @@
645645
]
646646
},
647647
{
648-
"description": "db.coll.watch fails after NotMaster when retryReads is false",
648+
"description": "db.coll.watch fails after NotWritablePrimary when retryReads is false",
649649
"clientOptions": {
650650
"retryReads": false
651651
},

‎source/retryable-reads/tests/changeStreams-db.coll.watch-serverErrors.yml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ tests:
4545
- *retryable_command_started_event
4646
- *retryable_command_started_event
4747
-
48-
description: "db.coll.watch succeeds after NotMaster"
48+
description: "db.coll.watch succeeds after NotWritablePrimary"
4949
failPoint:
5050
<<: *failCommand_failPoint
5151
data: { failCommands: [aggregate], errorCode: 10107 }
@@ -54,7 +54,7 @@ tests:
5454
- *retryable_command_started_event
5555
- *retryable_command_started_event
5656
-
57-
description: "db.coll.watch succeeds after NotMasterNoSlaveOk"
57+
description: "db.coll.watch succeeds after NotPrimaryNoSecondaryOk"
5858
failPoint:
5959
<<: *failCommand_failPoint
6060
data: { failCommands: [aggregate], errorCode: 13435 }
@@ -63,7 +63,7 @@ tests:
6363
- *retryable_command_started_event
6464
- *retryable_command_started_event
6565
-
66-
description: "db.coll.watch succeeds after NotMasterOrSecondary"
66+
description: "db.coll.watch succeeds after NotPrimaryOrSecondary"
6767
failPoint:
6868
<<: *failCommand_failPoint
6969
data: { failCommands: [aggregate], errorCode: 13436 }
@@ -126,7 +126,7 @@ tests:
126126
- *retryable_command_started_event
127127
- *retryable_command_started_event
128128
-
129-
description: "db.coll.watch fails after two NotMaster errors"
129+
description: "db.coll.watch fails after two NotWritablePrimary errors"
130130
failPoint:
131131
<<: *failCommand_failPoint
132132
mode: { times: 2 }
@@ -139,7 +139,7 @@ tests:
139139
- *retryable_command_started_event
140140
- *retryable_command_started_event
141141
-
142-
description: "db.coll.watch fails after NotMaster when retryReads is false"
142+
description: "db.coll.watch fails after NotWritablePrimary when retryReads is false"
143143
clientOptions:
144144
retryReads: false
145145
failPoint:

0 commit comments

Comments
 (0)