Restore changes lost after rebase

- Add SYSTEM_OVERLOADED_ERROR_LABEL and RETRYABLE_ERROR_LABEL constants to MongoException
- Add backpressure:true to hello command in InternalStreamConnectionInitializer
- Make CommandOperationHelper and its error label constants public
- Replace hardcoded error label strings with constants in tests and examples
- Refactor ExponentialBackoff: make TRANSACTION_BASE_MS and TRANSACTION_GROWTH private,
  split testCustomJitter into two tests, minor Javadoc/assertion message fixes
- Remove redundant private constructor from TimeoutContext
- Convert block comments to Javadoc in WithTransactionProseTest, refactor testRetryBackoffIsEnforced

Author: nhachicha

driver-core/src/main/com/mongodb/MongoException.java

@@ -39,6 +39,7 @@ public class MongoException extends RuntimeException {
      *
      * @see #hasErrorLabel(String)
      * @since 3.8
+     * @mongodb.driver.manual core/transactions-in-applications/#std-label-transient-transaction-error
      */
     public static final String TRANSIENT_TRANSACTION_ERROR_LABEL = "TransientTransactionError";
 
@@ -47,9 +48,32 @@ public class MongoException extends RuntimeException {
      *
      * @see #hasErrorLabel(String)
      * @since 3.8
+     * @mongodb.driver.manual core/transactions-in-applications/#std-label-unknown-transaction-commit-result
      */
     public static final String UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL = "UnknownTransactionCommitResult";
 
+    /**
+     * Server is overloaded and shedding load.
+     * If you retry, use exponential backoff because the server has indicated overload.
+     * This label on its own does not mean that the operation can be safely retried.
+     *
+     * @see #hasErrorLabel(String)
+     * @since 5.7
+     * @mongodb.server.release 8.3
+     */
+    // TODO-BACKPRESSURE Valentin Add a @mongodb.driver.manual link or something similar, see `content/atlas/source/overload-errors.txt` in https://github.com/10gen/docs-mongodb-internal/pull/17281
+    public static final String SYSTEM_OVERLOADED_ERROR_LABEL = "SystemOverloadedError";
+
+    /**
+     * The operation was not executed and is safe to retry.
+     *
+     * @see #hasErrorLabel(String)
+     * @since 5.7
+     * @mongodb.server.release 8.3
+     */
+    // TODO-BACKPRESSURE Valentin Add a @mongodb.driver.manual link or something similar, see `content/atlas/source/overload-errors.txt` in https://github.com/10gen/docs-mongodb-internal/pull/17281
+    public static final String RETRYABLE_ERROR_LABEL = "RetryableError";
+
     private static final long serialVersionUID = -4415279469780082174L;
 
     private final int code;

driver-core/src/main/com/mongodb/internal/TimeoutContext.java

@@ -109,10 +109,6 @@ public TimeoutContext(final TimeoutSettings timeoutSettings) {
         this(false, timeoutSettings, startTimeout(timeoutSettings.getTimeoutMS()));
     }
 
-    private TimeoutContext(final TimeoutSettings timeoutSettings, @Nullable final Timeout timeout) {
-        this(false, timeoutSettings, timeout);
-    }
-
     private TimeoutContext(final boolean isMaintenanceContext,
                            final TimeoutSettings timeoutSettings,
                            @Nullable final Timeout timeout) {

driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnectionInitializer.java

@@ -172,7 +172,8 @@ private InternalConnectionInitializationDescription createInitializationDescript
 
     private BsonDocument createHelloCommand(final Authenticator authenticator, final InternalConnection connection) {
         BsonDocument helloCommandDocument = new BsonDocument(getHandshakeCommandName(), new BsonInt32(1))
-                .append("helloOk", BsonBoolean.TRUE);
+                .append("helloOk", BsonBoolean.TRUE)
+                .append("backpressure", BsonBoolean.TRUE);
         if (clientMetadataDocument != null) {
             helloCommandDocument.append("client", clientMetadataDocument);
         }

driver-core/src/main/com/mongodb/internal/operation/CommandOperationHelper.java

@@ -51,7 +51,7 @@
 import static java.util.Arrays.asList;
 
 @SuppressWarnings("overloads")
-final class CommandOperationHelper {
+public final class CommandOperationHelper {
     static WriteConcern validateAndGetEffectiveWriteConcern(final WriteConcern writeConcernSetting, final SessionContext sessionContext)
             throws MongoClientException {
         boolean activeTransaction = sessionContext.hasActiveTransaction();
@@ -223,8 +223,8 @@ static boolean isRetryWritesEnabled(@Nullable final BsonDocument command) {
                 || command.getFirstKey().equals("commitTransaction") || command.getFirstKey().equals("abortTransaction")));
     }
 
-    static final String RETRYABLE_WRITE_ERROR_LABEL = "RetryableWriteError";
-    private static final String NO_WRITES_PERFORMED_ERROR_LABEL = "NoWritesPerformed";
+    public static final String RETRYABLE_WRITE_ERROR_LABEL = "RetryableWriteError";
+    public static final String NO_WRITES_PERFORMED_ERROR_LABEL = "NoWritesPerformed";
 
     private static boolean decideRetryableAndAddRetryableWriteErrorLabel(final Throwable t, @Nullable final Integer maxWireVersion) {
         if (!(t instanceof MongoException)) {

driver-core/src/main/com/mongodb/internal/time/ExponentialBackoff.java

@@ -29,13 +29,10 @@
  */
 public final class ExponentialBackoff {
 
-    // Constants for transaction retry backoff
-    @VisibleForTesting(otherwise = PRIVATE)
-    static final double TRANSACTION_BASE_MS = 5.0;
+    private static final double TRANSACTION_BASE_MS = 5.0;
     @VisibleForTesting(otherwise = PRIVATE)
     static final double TRANSACTION_MAX_MS = 500.0;
-    @VisibleForTesting(otherwise = PRIVATE)
-    static final double TRANSACTION_GROWTH = 1.5;
+    private static final double TRANSACTION_GROWTH = 1.5;
 
     // TODO-JAVA-6079
     private static DoubleSupplier testJitterSupplier = null;
@@ -46,11 +43,11 @@ private ExponentialBackoff() {
     /**
      * Calculate the backoff in milliseconds for transaction retries.
      *
-     * @param attemptNumber 0-based attempt number
+     * @param attemptNumber attempt number > 0
      * @return The calculated backoff in milliseconds.
      */
     public static long calculateTransactionBackoffMs(final int attemptNumber) {
-        assertTrue(attemptNumber > 0, "Attempt number must be greater than 0 in the context of transaction backoff calculation");
+        assertTrue(attemptNumber > 0, "Attempt number must be at least 1 (1-based) in the context of transaction backoff calculation");
         double jitter = testJitterSupplier != null
                 ? testJitterSupplier.getAsDouble()
                 : ThreadLocalRandom.current().nextDouble();
@@ -62,7 +59,7 @@ public static long calculateTransactionBackoffMs(final int attemptNumber) {
     /**
      * Set a custom jitter supplier for testing purposes.
      *
-     * @param supplier A DoubleSupplier that returns values in [0, 1) range.
+     * @param supplier A DoubleSupplier that returns values in [0, 1] range.
      */
     @VisibleForTesting(otherwise = PRIVATE)
     public static void setTestJitterSupplier(final DoubleSupplier supplier) {

driver-core/src/test/unit/com/mongodb/internal/connection/InternalStreamConnectionInitializerSpecification.groovy

@@ -201,6 +201,7 @@ class InternalStreamConnectionInitializerSpecification extends Specification {
         def initializer = new InternalStreamConnectionInitializer(SINGLE, null, clientMetadataDocument, [], null)
         def expectedHelloCommandDocument = new BsonDocument(LEGACY_HELLO, new BsonInt32(1))
                 .append('helloOk', BsonBoolean.TRUE)
+                .append('backpressure', BsonBoolean.TRUE)
                 .append('\$db', new BsonString('admin'))
         if (clientMetadataDocument != null) {
              expectedHelloCommandDocument.append('client', clientMetadataDocument)
@@ -233,6 +234,7 @@ class InternalStreamConnectionInitializerSpecification extends Specification {
         def initializer = new InternalStreamConnectionInitializer(SINGLE, null, null, compressors, null)
         def expectedHelloCommandDocument = new BsonDocument(LEGACY_HELLO, new BsonInt32(1))
                 .append('helloOk', BsonBoolean.TRUE)
+                .append('backpressure', BsonBoolean.TRUE)
                 .append('\$db', new BsonString('admin'))
 
         def compressionArray = new BsonArray()
@@ -403,7 +405,8 @@ class InternalStreamConnectionInitializerSpecification extends Specification {
         ((SpeculativeAuthenticator) authenticator).getSpeculativeAuthenticateResponse() == null
         ((SpeculativeAuthenticator) authenticator)
                 .createSpeculativeAuthenticateCommand(internalConnection) == null
-        BsonDocument.parse("{$LEGACY_HELLO: 1, helloOk: true, '\$db': 'admin'}") == decodeCommand(internalConnection.getSent()[0])
+        BsonDocument.parse("{$LEGACY_HELLO: 1, helloOk: true, backpressure: true, '\$db': 'admin'}") ==
+                decodeCommand(internalConnection.getSent()[0])
 
         where:
         async << [true, false]
@@ -500,7 +503,7 @@ class InternalStreamConnectionInitializerSpecification extends Specification {
 
     def createHelloCommand(final String firstClientChallenge, final String mechanism,
                               final boolean hasSaslSupportedMechs) {
-        String hello = "{$LEGACY_HELLO: 1, helloOk: true, " +
+        String hello = "{$LEGACY_HELLO: 1, helloOk: true, backpressure: true, " +
                 (hasSaslSupportedMechs ? 'saslSupportedMechs: "database.user", ' : '') +
                 (mechanism == 'MONGODB-X509' ?
                         'speculativeAuthenticate: { authenticate: 1, ' +

driver-core/src/test/unit/com/mongodb/internal/time/ExponentialBackoffTest.java

@@ -33,22 +33,17 @@ class ExponentialBackoffTest {
 
     @Test
     void testCalculateTransactionBackoffMs() {
-        // Test that the backoff sequence follows the expected pattern with growth factor ExponentialBackoff.TRANSACTION_GROWTH
-        // Expected sequence (without jitter): 5, 7.5, 11.25, ...
-        // With jitter, actual values will be between 0 and these maxima
-
         for (int attemptNumber = 1; attemptNumber <= EXPECTED_BACKOFFS_MAX_VALUES.length; attemptNumber++) {
             long backoff = ExponentialBackoff.calculateTransactionBackoffMs(attemptNumber);
             long expectedBackoff = Math.round(EXPECTED_BACKOFFS_MAX_VALUES[attemptNumber - 1]);
-                    assertTrue(backoff >= 0 && backoff <= expectedBackoff,
-                String.format("Attempt %d: backoff should be between 0 ms and %d ms, got: %d", attemptNumber,
-                        expectedBackoff, backoff));
+            assertTrue(backoff >= 0 && backoff <= expectedBackoff,
+                    String.format("Attempt %d: backoff should be between 0 ms and %d ms, got: %d", attemptNumber,
+                            expectedBackoff, backoff));
         }
     }
 
     @Test
     void testCalculateTransactionBackoffMsRespectsMaximum() {
-        // Even at high attempt numbers, backoff should never exceed ExponentialBackoff.TRANSACTION_MAX_MS
         for (int attemptNumber = 1; attemptNumber < EXPECTED_BACKOFFS_MAX_VALUES.length * 2; attemptNumber++) {
             long backoff = ExponentialBackoff.calculateTransactionBackoffMs(attemptNumber);
             assertTrue(backoff >= 0 && backoff <= ExponentialBackoff.TRANSACTION_MAX_MS,
@@ -58,24 +53,25 @@ void testCalculateTransactionBackoffMsRespectsMaximum() {
     }
 
     @Test
-    void testCustomJitter() {
-        // Test with jitter = 1.0
+    void testCustomJitterWithOne() {
         ExponentialBackoff.setTestJitterSupplier(() -> 1.0);
         try {
             for (int attemptNumber = 1; attemptNumber <= EXPECTED_BACKOFFS_MAX_VALUES.length; attemptNumber++) {
                 long backoff = ExponentialBackoff.calculateTransactionBackoffMs(attemptNumber);
                 long expected = Math.round(EXPECTED_BACKOFFS_MAX_VALUES[attemptNumber - 1]);
                 assertEquals(expected, backoff,
-                    String.format("Attempt %d: with jitter=1.0, backoff should be %d ms", attemptNumber, expected));
+                        String.format("Attempt %d: with jitter=1.0, backoff should be %d ms", attemptNumber, expected));
             }
         } finally {
             ExponentialBackoff.clearTestJitterSupplier();
         }
+    }
 
-        // Test with jitter = 0, all backoffs should be 0
+    @Test
+    void testCustomJitterWithZero() {
         ExponentialBackoff.setTestJitterSupplier(() -> 0.0);
         try {
-            for (int attemptNumber = 1; attemptNumber < EXPECTED_BACKOFFS_MAX_VALUES.length; attemptNumber++) {
+            for (int attemptNumber = 1; attemptNumber <= EXPECTED_BACKOFFS_MAX_VALUES.length; attemptNumber++) {
                 long backoff = ExponentialBackoff.calculateTransactionBackoffMs(attemptNumber);
                 assertEquals(0, backoff, "With jitter=0, backoff should always be 0 ms");
             }

driver-sync/src/examples/documentation/TransactionExample.java

@@ -77,7 +77,8 @@ private void runTransactionWithRetry(final Runnable transactional) {
                 System.out.println("Transaction aborted. Caught exception during transaction.");
 
                 if (e.hasErrorLabel(MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL)) {
-                    System.out.println("TransientTransactionError, aborting transaction and retrying ...");
+                    System.out.printf("%s, aborting transaction and retrying ...%n",
+                            MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL);
                 } else {
                     throw e;
                 }
@@ -94,7 +95,8 @@ private void commitWithRetry(final ClientSession clientSession) {
             } catch (MongoException e) {
                 // can retry commit
                 if (e.hasErrorLabel(MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL)) {
-                    System.out.println("UnknownTransactionCommitResult, retrying commit operation ...");
+                    System.out.printf("%s, retrying commit operation ...%n",
+                            MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL);
                 } else {
                     System.out.println("Exception during commit ...");
                     throw e;

driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideOperationsTimeoutProseTest.java

@@ -84,6 +84,7 @@
 import static com.mongodb.ClusterFixture.isStandalone;
 import static com.mongodb.ClusterFixture.serverVersionAtLeast;
 import static com.mongodb.ClusterFixture.sleep;
+import static com.mongodb.MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL;
 import static com.mongodb.client.Fixture.getDefaultDatabaseName;
 import static com.mongodb.client.Fixture.getPrimary;
 import static com.mongodb.internal.connection.CommandHelper.HELLO;
@@ -685,7 +686,7 @@ public void test10CustomTestWithTransactionUsesASingleTimeoutWithLock() {
                 + "    blockConnection: true,"
                 + "    blockTimeMS: " + 25
                 + "    errorCode: " + 24
-                + "    errorLabels: [\"TransientTransactionError\"]"
+                + "    errorLabels: [\"" + TRANSIENT_TRANSACTION_ERROR_LABEL + "\"]"
                 + "  }"
                 + "}");
 

driver-sync/src/test/functional/com/mongodb/client/MongoWriteConcernWithResponseExceptionTest.java

@@ -43,6 +43,8 @@
 import static com.mongodb.ClusterFixture.serverVersionAtLeast;
 import static com.mongodb.client.Fixture.getDefaultDatabaseName;
 import static com.mongodb.client.Fixture.getMongoClientSettingsBuilder;
+import static com.mongodb.internal.operation.CommandOperationHelper.NO_WRITES_PERFORMED_ERROR_LABEL;
+import static com.mongodb.internal.operation.CommandOperationHelper.RETRYABLE_WRITE_ERROR_LABEL;
 import static java.util.Collections.singletonList;
 import static org.junit.Assert.assertThrows;
 import static org.junit.Assume.assumeTrue;
@@ -69,7 +71,7 @@ public static void doesNotLeak(final Function<MongoClientSettings, MongoClient>
                 .append("data", new BsonDocument()
                         .append("writeConcernError", new BsonDocument()
                                 .append("code", new BsonInt32(91))
-                                .append("errorLabels", new BsonArray(Stream.of("RetryableWriteError")
+                                .append("errorLabels", new BsonArray(Stream.of(RETRYABLE_WRITE_ERROR_LABEL)
                                         .map(BsonString::new).collect(Collectors.toList())))
                                 .append("errmsg", new BsonString(""))
                         )
@@ -81,7 +83,7 @@ public static void doesNotLeak(final Function<MongoClientSettings, MongoClient>
                 .append("data", new BsonDocument()
                         .append("failCommands", new BsonArray(singletonList(new BsonString("insert"))))
                         .append("errorCode", new BsonInt32(10107))
-                        .append("errorLabels", new BsonArray(Stream.of("RetryableWriteError", "NoWritesPerformed")
+                        .append("errorLabels", new BsonArray(Stream.of(RETRYABLE_WRITE_ERROR_LABEL, NO_WRITES_PERFORMED_ERROR_LABEL)
                                 .map(BsonString::new).collect(Collectors.toList()))));
         doesNotLeak(clientCreator, writeConcernErrorFpDoc, true, noWritesPerformedFpDoc);
         doesNotLeak(clientCreator, noWritesPerformedFpDoc, false, writeConcernErrorFpDoc);