update with comments

Author: baileympearson

src/sessions.ts

@@ -740,17 +740,30 @@ export class ClientSession
 
     try {
       retryTransaction: for (
-        let attempt = 0, isRetry = false;
+        // 2. Set `transactionAttempt` to `0`.
+        let transactionAttempt = 0, isRetry = false;
         !committed;
-        ++attempt, isRetry = attempt > 0
+        ++transactionAttempt, isRetry = transactionAttempt > 0
       ) {
+        // 2. If `transactionAttempt` > 0:
         if (isRetry) {
+          // 2.i If elapsed time + `backoffMS` > `TIMEOUT_MS`, then raise the previously encountered error. If the elapsed time of
+          //     `withTransaction` is less than TIMEOUT_MS, calculate the backoffMS to be
+          //     `jitter * min(BACKOFF_INITIAL * 1.5 ** (transactionAttempt - 1), BACKOFF_MAX)`. sleep for `backoffMS`.
+          // 2.i.i jitter is a random float between \[0, 1)
+          // 2.i.ii `transactionAttempt` is the variable defined in step 1.
+          // 2.i.iii `BACKOFF_INITIAL` is 5ms
+          // 2.i.iv `BACKOFF_MAX` is 500ms
           const BACKOFF_INITIAL_MS = 5;
           const BACKOFF_MAX_MS = 500;
           const BACKOFF_GROWTH = 1.5;
           const jitter = Math.random();
           const backoffMS =
-            jitter * Math.min(BACKOFF_INITIAL_MS * BACKOFF_GROWTH ** attempt, BACKOFF_MAX_MS);
+            jitter *
+            Math.min(
+              BACKOFF_INITIAL_MS * BACKOFF_GROWTH ** (transactionAttempt - 1),
+              BACKOFF_MAX_MS
+            );
 
           const willExceedTransactionDeadline =
             (this.timeoutContext?.csotEnabled() &&
@@ -769,13 +782,13 @@ export class ClientSession
           await setTimeout(backoffMS);
         }
 
-        // 2. Invoke startTransaction on the session
-        // 3. If `startTransaction` reported an error, propagate that error to the caller of `withTransaction` and return immediately.
+        // 3. Invoke startTransaction on the session
+        // 4. If `startTransaction` reported an error, propagate that error to the caller of `withTransaction` and return immediately.
         this.startTransaction(options); // may throw on error
 
         try {
-          // 4. Invoke the callback.
-          // 5. Control returns to withTransaction. (continued below)
+          // 5. Invoke the callback.
+          // 6. Control returns to withTransaction. (continued below)
           const promise = fn(this);
           if (!isPromiseLike(promise)) {
             throw new MongoInvalidArgumentError(
@@ -785,18 +798,18 @@ export class ClientSession
 
           result = await promise;
 
-          // 5. (cont.) Determine the current state of the ClientSession (continued below)
+          // 6. (cont.) Determine the current state of the ClientSession (continued below)
           if (
             this.transaction.state === TxnState.NO_TRANSACTION ||
             this.transaction.state === TxnState.TRANSACTION_COMMITTED ||
             this.transaction.state === TxnState.TRANSACTION_ABORTED
           ) {
-            // 7. If the ClientSession is in the "no transaction", "transaction aborted", or "transaction committed" state,
+            // 8. If the ClientSession is in the "no transaction", "transaction aborted", or "transaction committed" state,
             // assume the callback intentionally aborted or committed the transaction and return immediately.
             return result;
           }
           // 5. (cont.) and whether the callback reported an error
-          // 6. If the callback reported an error:
+          // 7. If the callback reported an error:
         } catch (fnError) {
           if (!(fnError instanceof MongoError) || fnError instanceof MongoInvalidArgumentError) {
             // This first preemptive abort regardless of TxnState isn't spec,
@@ -809,7 +822,7 @@ export class ClientSession
             this.transaction.state === TxnState.STARTING_TRANSACTION ||
             this.transaction.state === TxnState.TRANSACTION_IN_PROGRESS
           ) {
-            // 6.i If the ClientSession is in the "starting transaction" or "transaction in progress" state,
+            // 7.i If the ClientSession is in the "starting transaction" or "transaction in progress" state,
             // invoke abortTransaction on the session
             await this.abortTransaction();
           }
@@ -818,16 +831,16 @@ export class ClientSession
             fnError.hasErrorLabel(MongoErrorLabel.TransientTransactionError) &&
             (this.timeoutContext?.csotEnabled() || processTimeMS() - startTime < MAX_TIMEOUT)
           ) {
-            // 6.ii If the callback's error includes a "TransientTransactionError" label and the elapsed time of `withTransaction`
+            // 7.ii If the callback's error includes a "TransientTransactionError" label and the elapsed time of `withTransaction`
             // is less than 120 seconds, jump back to step two.
             lastError = fnError;
             continue retryTransaction;
           }
 
-          // 6.iii If the callback's error includes a "UnknownTransactionCommitResult" label, the callback must have manually committed a transaction,
+          // 7.iii If the callback's error includes a "UnknownTransactionCommitResult" label, the callback must have manually committed a transaction,
           // propagate the callback's error to the caller of withTransaction and return immediately.
-          // The 6.iii check is redundant with 6.iv, so we don't write code for it
-          // 6.iv Otherwise, propagate the callback's error to the caller of withTransaction and return immediately.
+          // The 7.iii check is redundant with 6.iv, so we don't write code for it
+          // 7.iv Otherwise, propagate the callback's error to the caller of withTransaction and return immediately.
           throw fnError;
         }
 
@@ -838,10 +851,10 @@ export class ClientSession
              * apply a majority write concern if commitTransaction is
              * being retried (see: DRIVERS-601)
              */
-            // 8. Invoke commitTransaction on the session.
+            // 9. Invoke commitTransaction on the session.
             await this.commitTransaction();
             committed = true;
-            // 9. If commitTransaction reported an error:
+            // 10. If commitTransaction reported an error:
           } catch (commitError) {
             // If CSOT is enabled, we repeatedly retry until timeoutMS expires.  This is enforced by providing a
             // timeoutContext to each async API, which know how to cancel themselves (i.e., the next retry will
@@ -862,21 +875,21 @@ export class ClientSession
                 !isMaxTimeMSExpiredError(commitError) &&
                 commitError.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult)
               ) {
-                // 9.i If the `commitTransaction` error includes a "UnknownTransactionCommitResult" label and the error is not
+                // 10.i If the `commitTransaction` error includes a "UnknownTransactionCommitResult" label and the error is not
                 // MaxTimeMSExpired and the elapsed time of `withTransaction` is less than 120 seconds, jump back to step eight.
                 continue retryCommit;
               }
 
               if (commitError.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
-                // 9.ii If the commitTransaction error includes a "TransientTransactionError" label
+                // 10.ii If the commitTransaction error includes a "TransientTransactionError" label
                 // and the elapsed time of withTransaction is less than 120 seconds, jump back to step two.
                 lastError = commitError;
 
                 continue retryTransaction;
               }
             }
 
-            // 9.iii Otherwise, propagate the commitTransaction error to the caller of withTransaction and return immediately.
+            // 10.iii Otherwise, propagate the commitTransaction error to the caller of withTransaction and return immediately.
             throw commitError;
           }
         }