Skip to content

Commit 7f8dea8

Browse files
rstamrstam
committed
CSHARP-4825: Make ReadConcernMajorityNotAvailableYet a retryable read error.
1 parent d8f7530 commit 7f8dea8

File tree

5 files changed

+337
-39
lines changed

5 files changed

+337
-39
lines changed

‎specifications/retryable-reads/tests/README.rst

Lines changed: 115 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,10 @@ Retryable Reads Tests
99
Introduction
1010
============
1111

12-
The YAML and JSON files in this directory tree are platform-independent tests
13-
that drivers can use to prove their conformance to the Retryable Reads spec.
12+
The YAML and JSON files in the ``legacy`` and ``unified`` sub-directories are platform-independent tests
13+
that drivers can use to prove their conformance to the Retryable Reads spec. Tests in the
14+
``unified`` directory are written using the `Unified Test Format <../../unified-test-format/unified-test-format.rst>`_.
15+
Tests in the ``legacy`` directory are written using the format described below.
1416

1517
Prose tests, which are not easily expressed in YAML, are also presented
1618
in this file. Those tests will need to be manually implemented by each driver.
@@ -79,53 +81,54 @@ Each YAML file has the following keys:
7981
the default is all topologies (i.e. ``["single", "replicaset", "sharded",
8082
"load-balanced"]``).
8183

82-
- ``serverless``: Optional string. Whether or not the test should be run on
83-
serverless instances imitating sharded clusters. Valid values are "require",
84-
"forbid", and "allow". If "require", the test MUST only be run on serverless
85-
instances. If "forbid", the test MUST NOT be run on serverless instances. If
86-
omitted or "allow", this option has no effect.
87-
88-
The test runner MUST be informed whether or not serverless is being used in
89-
order to determine if this requirement is met (e.g. through an environment
90-
variable or configuration option). Since the serverless proxy imitates a
91-
mongos, the runner is not capable of determining this by issuing a server
92-
command such as ``buildInfo`` or ``hello``.
93-
94-
- ``serverless``: Optional string. Whether or not the test should be run on
95-
serverless instances imitating sharded clusters. Valid values are "require",
96-
"forbid", and "allow". If "require", the test MUST only be run on serverless
97-
instances. If "forbid", the test MUST NOT be run on serverless instances. If
98-
omitted or "allow", this option has no effect.
99-
100-
The test runner MUST be informed whether or not serverless is being used in
101-
order to determine if this requirement is met (e.g. through an environment
102-
variable or configuration option). Since the serverless proxy imitates a
103-
mongos, the runner is not capable of determining this by issuing a server
104-
command such as ``buildInfo`` or ``hello``.
84+
- ``serverless``: (optional): Whether or not the test should be run on Atlas
85+
Serverless instances. Valid values are "require", "forbid", and "allow". If
86+
"require", the test MUST only be run on Atlas Serverless instances. If
87+
"forbid", the test MUST NOT be run on Atlas Serverless instances. If omitted
88+
or "allow", this option has no effect.
89+
90+
The test runner MUST be informed whether or not Atlas Serverless is being
91+
used in order to determine if this requirement is met (e.g. through an
92+
environment variable or configuration option).
93+
94+
Note: the Atlas Serverless proxy imitates mongos, so the test runner is not
95+
capable of determining if Atlas Serverless is in use by issuing commands
96+
such as ``buildInfo`` or ``hello``. Furthermore, connections to Atlas
97+
Serverless use a load balancer, so the topology will appear as
98+
"load-balanced".
10599

106100
- ``database_name`` and ``collection_name``: Optional. The database and
107101
collection to use for testing.
108-
102+
109103
- ``bucket_name``: Optional. The GridFS bucket name to use for testing.
110104

111105
- ``data``: The data that should exist in the collection(s) under test before
112106
each test run. This will typically be an array of documents to be inserted
113107
into the collection under test (i.e. ``collection_name``); however, this field
114108
may also be an object mapping collection names to arrays of documents to be
115109
inserted into the specified collection.
116-
110+
117111
- ``tests``: An array of tests that are to be run independently of each other.
118112
Each test will have some or all of the following fields:
119113

120114
- ``description``: The name of the test.
121-
115+
122116
- ``clientOptions``: Optional, parameters to pass to MongoClient().
123117

124-
- ``useMultipleMongoses`` (optional): If ``true``, the MongoClient for this
125-
test should be initialized with multiple mongos seed addresses. If ``false``
126-
or omitted, only a single mongos address should be specified. This field has
127-
no effect for non-sharded topologies.
128-
118+
- ``useMultipleMongoses`` (optional): If ``true``, and the topology type is
119+
``Sharded``, the MongoClient for this test should be initialized with multiple
120+
mongos seed addresses. If ``false`` or omitted, only a single mongos address
121+
should be specified.
122+
123+
If ``true``, the topology type is ``LoadBalanced``, and Atlas Serverless is
124+
not being used, the MongoClient for this test should be initialized with the
125+
URI of the load balancer fronting multiple servers. If ``false`` or omitted,
126+
the MongoClient for this test should be initialized with the URI of the load
127+
balancer fronting a single server.
128+
129+
``useMultipleMongoses`` only affects ``Sharded`` and ``LoadBalanced``
130+
topologies (excluding Atlas Serverless).
131+
129132
- ``skipReason``: Optional, string describing why this test should be skipped.
130133

131134
- ``failPoint``: Optional, a server fail point to enable, expressed as the
@@ -144,10 +147,10 @@ Each YAML file has the following keys:
144147
- ``result``: Optional. The return value from the operation, if any. This
145148
field may be a scalar (e.g. in the case of a count), a single document, or
146149
an array of documents in the case of a multi-document read.
147-
150+
148151
- ``error``: Optional. If ``true``, the test should expect an error or
149152
exception.
150-
153+
151154
- ``expectations``: Optional list of command-started events.
152155

153156
GridFS Tests
@@ -171,7 +174,7 @@ data.
171174

172175

173176
.. _GridFSBucket spec: https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst#configurable-gridfsbucket-class
174-
177+
175178

176179
Speeding Up Tests
177180
-----------------
@@ -229,10 +232,86 @@ This test requires MongoDB 4.2.9+ for ``blockConnection`` support in the failpoi
229232

230233
9. Disable the failpoint.
231234

235+
Retrying Reads in a Sharded Cluster
236+
===================================
237+
238+
These tests will be used to ensure drivers properly retry reads on a different
239+
mongos.
240+
241+
Retryable Reads Are Retried on a Different mongos if One is Available
242+
---------------------------------------------------------------------
243+
244+
This test MUST be executed against a sharded cluster that has at least two
245+
mongos instances.
246+
247+
1. Ensure that a test is run against a sharded cluster that has at least two
248+
mongoses. If there are more than two mongoses in the cluster, pick two to
249+
test against.
250+
251+
2. Create a client per mongos using the direct connection, and configure the
252+
following fail points on each mongos::
253+
254+
{
255+
configureFailPoint: "failCommand",
256+
mode: { times: 1 },
257+
data: {
258+
failCommands: ["find"],
259+
errorCode: 6,
260+
closeConnection: true
261+
}
262+
}
263+
264+
3. Create a client with ``retryReads=true`` that connects to the cluster,
265+
providing the two selected mongoses as seeds.
266+
267+
4. Enable command monitoring, and execute a ``find`` command that is
268+
supposed to fail on both mongoses.
269+
270+
5. Asserts that there were failed command events from each mongos.
271+
272+
6. Disable the fail points.
273+
274+
275+
Retryable Reads Are Retried on the Same mongos if No Others are Available
276+
-------------------------------------------------------------------------
277+
278+
1. Ensure that a test is run against a sharded cluster. If there are multiple
279+
mongoses in the cluster, pick one to test against.
280+
281+
2. Create a client that connects to the mongos using the direct connection,
282+
and configure the following fail point on the mongos::
283+
284+
{
285+
configureFailPoint: "failCommand",
286+
mode: { times: 1 },
287+
data: {
288+
failCommands: ["find"],
289+
errorCode: 6,
290+
closeConnection: true
291+
}
292+
}
293+
294+
3. Create a client with ``retryReads=true`` that connects to the cluster,
295+
providing the selected mongos as the seed.
296+
297+
4. Enable command monitoring, and execute a ``find`` command.
298+
299+
5. Asserts that there was a failed command and a successful command event.
300+
301+
6. Disable the fail point.
302+
232303

233304
Changelog
234305
=========
235306

307+
:2023-08-26 Add prose tests for retrying in a sharded cluster.
308+
309+
:2022-04-22: Clarifications to ``serverless`` and ``useMultipleMongoses``.
310+
311+
:2022-01-10: Create legacy and unified subdirectories for new unified tests
312+
313+
:2021-08-27: Clarify behavior of ``useMultipleMongoses`` for ``LoadBalanced`` topologies.
314+
236315
:2019-03-19: Add top-level ``runOn`` field to denote server version and/or
237316
topology requirements requirements for the test file. Removes the
238317
``minServerVersion`` and ``topology`` top-level fields, which are

‎specifications/retryable-reads/tests/unified/readConcernMajorityNotAvailableYet.json

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
{
2+
"description": "ReadConcernMajorityNotAvailableYet is a retryable read",
3+
"schemaVersion": "1.3",
4+
"runOnRequirements": [
5+
{
6+
"minServerVersion": "4.0",
7+
"topologies": [
8+
"single",
9+
"replicaset"
10+
]
11+
},
12+
{
13+
"minServerVersion": "4.1.7",
14+
"topologies": [
15+
"sharded",
16+
"load-balanced"
17+
]
18+
}
19+
],
20+
"createEntities": [
21+
{
22+
"client": {
23+
"id": "client0",
24+
"useMultipleMongoses": false,
25+
"observeEvents": [
26+
"commandStartedEvent"
27+
]
28+
}
29+
},
30+
{
31+
"database": {
32+
"id": "database0",
33+
"client": "client0",
34+
"databaseName": "retryable-reads-tests"
35+
}
36+
},
37+
{
38+
"collection": {
39+
"id": "collection0",
40+
"database": "database0",
41+
"collectionName": "readconcernmajoritynotavailableyet_test"
42+
}
43+
}
44+
],
45+
"initialData": [
46+
{
47+
"collectionName": "readconcernmajoritynotavailableyet_test",
48+
"databaseName": "retryable-reads-tests",
49+
"documents": [
50+
{
51+
"_id": 1,
52+
"x": 11
53+
},
54+
{
55+
"_id": 2,
56+
"x": 22
57+
},
58+
{
59+
"_id": 3,
60+
"x": 33
61+
}
62+
]
63+
}
64+
],
65+
"tests": [
66+
{
67+
"description": "Find succeeds on second attempt after ReadConcernMajorityNotAvailableYet",
68+
"operations": [
69+
{
70+
"name": "failPoint",
71+
"object": "testRunner",
72+
"arguments": {
73+
"client": "client0",
74+
"failPoint": {
75+
"configureFailPoint": "failCommand",
76+
"mode": {
77+
"times": 1
78+
},
79+
"data": {
80+
"failCommands": [
81+
"find"
82+
],
83+
"errorCode": 134
84+
}
85+
}
86+
}
87+
},
88+
{
89+
"name": "find",
90+
"arguments": {
91+
"filter": {
92+
"_id": {
93+
"$gt": 1
94+
}
95+
}
96+
},
97+
"object": "collection0",
98+
"expectResult": [
99+
{
100+
"_id": 2,
101+
"x": 22
102+
},
103+
{
104+
"_id": 3,
105+
"x": 33
106+
}
107+
]
108+
}
109+
],
110+
"expectEvents": [
111+
{
112+
"client": "client0",
113+
"events": [
114+
{
115+
"commandStartedEvent": {
116+
"command": {
117+
"find": "readconcernmajoritynotavailableyet_test",
118+
"filter": {
119+
"_id": {
120+
"$gt": 1
121+
}
122+
}
123+
},
124+
"commandName": "find",
125+
"databaseName": "retryable-reads-tests"
126+
}
127+
},
128+
{
129+
"commandStartedEvent": {
130+
"command": {
131+
"find": "readconcernmajoritynotavailableyet_test",
132+
"filter": {
133+
"_id": {
134+
"$gt": 1
135+
}
136+
}
137+
},
138+
"commandName": "find",
139+
"databaseName": "retryable-reads-tests"
140+
}
141+
}
142+
]
143+
}
144+
]
145+
}
146+
]
147+
}

0 commit comments

Comments
 (0)