Cleanup; improve prose tests

source/retryable-reads/retryable-reads.rst

@@ -268,8 +268,10 @@ selecting a server for a retry attempt.
 3a. Selecting the server for retry
 ''''''''''''''''''''''''''''''''''
 
-The server on which the operation failed MUST be provided to the server selection
-mechanism as a deprioritized server. If the driver cannot select a server for
+In sharded topology, the server on which the operation failed MUST be provided
+to the server selection mechanism as a deprioritized server.
+
+If the driver cannot select a server for
 a retry attempt or the newly selected server does not support retryable reads,
 retrying is not possible and drivers MUST raise the previous retryable error.
 In both cases, the caller is able to infer that an attempt was made.
@@ -690,6 +692,9 @@ degraded performance can simply disable ``retryableReads``.
 Changelog
 =========
 
+:2023-08-??: Require that in a sharded topology the server on which the
+ operation failed MUST be provided to the server selection
+ mechanism as a deprioritized server.
 :2022-11-09: CLAM must apply both events and log messages.
 :2022-10-18: When CSOT is enabled multiple retry attempts may occur.
 :2022-10-05: Remove spec front matter, move footnote, and reformat changelog.

source/retryable-reads/tests/README.rst

@@ -248,14 +248,23 @@ mongos instances.
  mongoses. If there are more than two mongoses in the cluster, pick two to
  test against.
 
-2. Create a client per mongos using the direct connection, and configure fail
- points on each of the picked mongoses, so that each mongos raises
- a retryable error once.
+2. Create a client per mongos using the direct connection, and configure the
+ following fail points on each mongos::
+
+ {
+ configureFailPoint: "failCommand",
+ mode: { times: 1 },
+ data: {
+ failCommands: ["find"],
+ errorCode: 6,
+ closeConnection: true
+ }
+ }
 
 3. Create a client with ``retryReads=true`` that connects to the cluster,
  providing the two selected mongoses as seeds.
 
-4. Enable command monitoring, and execute a read command that is
+4. Enable command monitoring, and execute ``find`` command that is
  supposed to fail on both mongoses.
 
 5. Asserts that there were failed command events from each mongos.
@@ -270,13 +279,22 @@ Retryable Reads Are Retried on the Same Mongos if No Other Available
  mongoses in the cluster, pick one to test against.
 
 2. Create a client that connects to the mongos using the direct connection,
- and configure a fail point so that the mongos raises a retryable error once.
+ and configure the following fail point on the mongos::
+
+ {
+ configureFailPoint: "failCommand",
+ mode: { times: 1 },
+ data: {
+ failCommands: ["find"],
+ errorCode: 6,
+ closeConnection: true
+ }
+ }
 
 3. Create a client with ``retryReads=true`` that connects to the cluster,
  providing the selected mongos as the seed.
 
-4. Enable command monitoring, and execute a read command that is
- supposed to fail.
+4. Enable command monitoring, and execute ``find`` command.
 
 5. Asserts that there was a failed command and a successful command event.
 
@@ -286,6 +304,8 @@ Retryable Reads Are Retried on the Same Mongos if No Other Available
 Changelog
 =========
 
+:2023-08-??: Add prose tests for retrying in a sharded cluster.
+
 :2022-04-22: Clarifications to ``serverless`` and ``useMultipleMongoses``.
 
 :2022-01-10: Create legacy and unified subdirectories for new unified tests

source/retryable-writes/retryable-writes.rst

@@ -395,9 +395,11 @@ of the following conditions is reached:
  <../client-side-operations-timeout/client-side-operations-timeout.rst#retryability>`__.
 - CSOT is not enabled and one retry was attempted.
 
-For each retry attempt, drivers MUST select a writable server. Server on which
-the operation failed MUST be provided to the server selection mechanism as
-a deprioritized server. If the driver cannot select a server for a retry attempt
+For each retry attempt, drivers MUST select a writable server. In sharded
+topology, the server on which the operation failed MUST be provided to
+the server selection mechanism as a deprioritized server.
+
+If the driver cannot select a server for a retry attempt
 or the selected server does not support retryable writes, retrying is not
 possible and drivers MUST raise the retryable error from the previous attempt.
 In both cases, the caller is able to infer that an attempt was made.
@@ -827,6 +829,9 @@ inconsistent with the server and potentially confusing to developers.
 Changelog
 =========
 
+:2023-08-??: Require that in a sharded topology the server on which the
+ operation failed MUST be provided to the server selection
+ mechanism as a deprioritized server.
 :2022-11-17: Add logic for persisting "currentError" as "previousError" on first
  retry attempt, avoiding raising "null" errors.
 :2022-11-09: CLAM must apply both events and log messages.

source/retryable-writes/tests/README.rst

@@ -462,47 +462,70 @@ and sharded clusters.
  This test MUST be executed against a sharded cluster that has at least two
  mongos instances.
 
-  1. Ensure that a test is run against a sharded cluster that has at least two
-  mongoses. If there are more than two mongoses in the cluster, pick two to
-  test against.
+ 1. Ensure that a test is run against a sharded cluster that has at least two
+ mongoses. If there are more than two mongoses in the cluster, pick two to
+ test against.
 
- 2. Create a client per mongos using the direct connection, and configure fail
- points on each of the picked mongoses, so that each mongos raises
- a retryable error once.
+ 2. Create a client per mongos using the direct connection, and configure the
+ following fail point on each mongos::
 
- 3. Create a client with ``retryWrites=true`` that connects to the cluster,
- providing the two selected mongoses as seeds.
+ {
+ configureFailPoint: "failCommand",
+ mode: { times: 1 },
+ data: {
+ failCommands: ["insert"],
+ errorCode: 6,
+ errorLabels: ["RetryableWriteError"],
+ closeConnection: true
+ }
+ }
 
-  4. Enable command monitoring, and execute a write command that is
-  supposed to fail on both mongoses.
+ 3. Create a client with ``retryWrites=true`` that connects to the cluster,
+ providing the two selected mongoses as seeds.
 
- 5. Asserts that there were failed command events from each mongos.
+ 4. Enable command monitoring, and execute a write command that is
+ supposed to fail on both mongoses.
 
- 6. Disable the fail points.
+ 5. Asserts that there were failed command events from each mongos.
+
+ 6. Disable the fail points.
 
 #. Test that in a sharded cluster on the same mongos if no other available
 
  This test MUST be executed against a sharded cluster
 
- 1. Ensure that a test is run against a sharded cluster. If there are multiple
- mongoses in the cluster, pick one to test against.
+ 1. Ensure that a test is run against a sharded cluster. If there are multiple
+ mongoses in the cluster, pick one to test against.
+
+ 2. Create a client that connects to the mongos using the direct connection,
+ and configure the following fail point on the mongos::
 
- 2. Create a client that connects to the mongos using the direct connection,
- and configure a fail point so that the mongos raises a retryable error once.
+ {
+ configureFailPoint: "failCommand",
+ mode: { times: 1 },
+ data: {
+ failCommands: ["insert"],
+ errorCode: 6,
+ errorLabels: ["RetryableWriteError"],
+ closeConnection: true
+ }
+ }
 
-  3. Create a client with ``retryWrites=true`` that connects to the cluster,
-  providing the selected mongos as the seed.
+ 3. Create a client with ``retryWrites=true`` that connects to the cluster,
+ providing the selected mongos as the seed.
 
-  4. Enable command monitoring, and execute a write command that is
-  supposed to fail.
+ 4. Enable command monitoring, and execute a write command that is
+ supposed to fail.
 
-  5. Asserts that there was a failed command and a successful command event.
+ 5. Asserts that there was a failed command and a successful command event.
 
-  6. Disable the fail point.
+ 6. Disable the fail point.
 
 Changelog
 =========
 
+:2023-08-??: Add prose tests for retrying in a sharded cluster.
+
 :2022-08-30: Add prose test verifying correct error handling for errors with
  the NoWritesPerformed label, which is to return the original
  error.
@@ -529,3 +552,4 @@ Changelog
  which are now expressed within ``runOn`` elements.
 
  Add test-level ``useMultipleMongoses`` field.
+``

source/server-selection/server-selection.rst

@@ -2074,3 +2074,4 @@ Changelog
 :2022-01-19: Require that timeouts be applied per the client-side operations timeout spec
 :2022-10-05: Remove spec front matter, move footnote, and reformat changelog.
 :2022-11-09: Add log messages and tests.
+:2023-08-??: Add list of deprioritized servers for sharded cluster topology.