mongodb 7.1.1 → 7.2.0

package/src/sessions.ts

@@ -1,6 +1,6 @@
 import { setTimeout } from 'timers/promises';
 
-import { Binary, type Document, Long, type Timestamp } from './bson';
+import { Binary, ByteUtils, type Document, Long, type Timestamp } from './bson';
 import type { CommandOptions, Connection } from './cmap/connection';
 import { ConnectionPoolMetrics } from './cmap/metrics';
 import { type MongoDBResponse } from './cmap/wire_protocol/responses';
@@ -17,6 +17,7 @@ import {
   MongoErrorLabel,
   MongoExpiredSessionError,
   MongoInvalidArgumentError,
+  MongoOperationTimeoutError,
   MongoRuntimeError,
   MongoServerError,
   MongoTransactionError,
@@ -37,7 +38,6 @@ import {
   TxnState
 } from './transactions';
 import {
-  ByteUtils,
   calculateDurationInMs,
   commandSupportsReadConcern,
   isPromiseLike,
@@ -468,7 +468,11 @@ export class ClientSession
       } else {
         const wcKeys = Object.keys(wc);
         if (wcKeys.length > 2 || (!wcKeys.includes('wtimeoutMS') && !wcKeys.includes('wTimeoutMS')))
-          // if the write concern was specified with wTimeoutMS, then we set both wtimeoutMS and wTimeoutMS, guaranteeing at least two keys, so if we have more than two keys, then we can automatically assume that we should add the write concern to the command. If it has 2 or fewer keys, we need to check that those keys aren't the wtimeoutMS or wTimeoutMS options before we add the write concern to the command
+          // if the write concern was specified with wTimeoutMS, then we set both wtimeoutMS
+          // and wTimeoutMS, guaranteeing at least two keys, so if we have more than two keys,
+          // then we can automatically assume that we should add the write concern to the command.
+          // If it has 2 or fewer keys, we need to check that those keys aren't the wtimeoutMS
+          // or wTimeoutMS options before we add the write concern to the command
           WriteConcern.apply(command, { ...wc, wtimeoutMS: undefined });
       }
     }
@@ -494,6 +498,7 @@ export class ClientSession
       readPreference: ReadPreference.primary,
       bypassPinningCheck: true
     });
+    operation.maxAttempts = this.clientOptions.maxAdaptiveRetries + 1;
 
     const timeoutContext =
       this.timeoutContext ??
@@ -511,6 +516,12 @@ export class ClientSession
       return;
     } catch (firstCommitError) {
       this.commitAttempted = true;
+
+      const remainingAttempts = this.clientOptions.maxAdaptiveRetries + 1 - operation.attemptsMade;
+      if (remainingAttempts <= 0) {
+        throw firstCommitError;
+      }
+
       if (firstCommitError instanceof MongoError && isRetryableWriteError(firstCommitError)) {
         // SPEC-1185: apply majority write concern when retrying commitTransaction
         WriteConcern.apply(command, { wtimeoutMS: 10000, ...wc, w: 'majority' });
@@ -518,15 +529,13 @@ export class ClientSession
         this.unpin({ force: true });
 
         try {
-          await executeOperation(
-            this.client,
-            new RunCommandOperation(new MongoDBNamespace('admin'), command, {
-              session: this,
-              readPreference: ReadPreference.primary,
-              bypassPinningCheck: true
-            }),
-            timeoutContext
-          );
+          const op = new RunCommandOperation(new MongoDBNamespace('admin'), command, {
+            session: this,
+            readPreference: ReadPreference.primary,
+            bypassPinningCheck: true
+          });
+          op.maxAttempts = remainingAttempts;
+          await executeOperation(this.client, op, timeoutContext);
           return;
         } catch (retryCommitError) {
           // If the retry failed, we process that error instead of the original
@@ -716,7 +725,7 @@ export class ClientSession
       timeoutMS?: number;
     }
   ): Promise<T> {
-    const MAX_TIMEOUT = 120000;
+    const MAX_TIMEOUT = 120_000;
 
     const timeoutMS = options?.timeoutMS ?? this.timeoutMS ?? null;
     this.timeoutContext =
@@ -728,10 +737,27 @@ export class ClientSession
           })
         : null;
 
-    // 1. Record the current monotonic time, which will be used to enforce the 120-second timeout before later retry attempts.
-    const startTime = this.timeoutContext?.csotEnabled() // This is strictly to appease TS.  We must narrow the context to a CSOT context before accessing `.start`.
-      ? this.timeoutContext.start
-      : processTimeMS();
+    // 1. Define the following:
+    // 1.1 Record the current monotonic time, which will be used to enforce the 120-second / CSOT timeout before later retry attempts.
+    // 1.2 Set `transactionAttempt` to `0`.
+    // 1.3 Set `TIMEOUT_MS` to be `timeoutMS` if given, otherwise MAX_TIMEOUT (120-seconds).
+
+    // Timeout Error propagation
+    // When the previously encountered error needs to be propagated because there is no more time for another attempt,
+    // and it is not already a timeout error, then:
+    //  - A timeout error MUST be propagated instead. It MUST expose the previously encountered error as specified in
+    //    the "Errors" section of the CSOT specification.
+    //  - If exposing the previously encountered error from a timeout error is impossible in a driver, then the driver
+    //    is exempt from the requirement and MUST propagate the previously encountered error as is. The timeout error
+    //    MUST copy all error labels from the previously encountered error.
+
+    // The spec describes timeout checks as "elapsed time < TIMEOUT_MS" (where elapsed = now - start).
+    // We precompute `deadline = now + remainingTimeMS` so each check becomes simply `now < deadline`.
+    const csotEnabled = !!this.timeoutContext?.csotEnabled();
+    const remainingTimeMS = this.timeoutContext?.csotEnabled()
+      ? this.timeoutContext.remainingTimeMS
+      : MAX_TIMEOUT;
+    const deadline = processTimeMS() + remainingTimeMS;
 
     let committed = false;
     let result: T;
@@ -740,20 +766,20 @@ export class ClientSession
 
     try {
       retryTransaction: for (
-        // 2. Set `transactionAttempt` to `0`.
         let transactionAttempt = 0, isRetry = false;
         !committed;
         ++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
+          // 2.1 Calculate backoffMS to be jitter * min(BACKOFF_INITIAL * 1.5 ** (transactionAttempt - 1), BACKOFF_MAX).
+          //  If elapsed time + backoffMS > TIMEOUT_MS, then propagate the previously encountered error to the caller of
+          //  withTransaction as per timeout error propagation and return immediately. Otherwise, sleep for backoffMS.
+          //  2.1.1 jitter is a random float between [0, 1), optionally including 1, depending on what is most natural
+          //    for the given driver language.
+          //  2.1.2 transactionAttempt is the variable defined in step 1.
+          //  2.1.3 BACKOFF_INITIAL is 5ms
+          //  2.1.4 BACKOFF_MAX is 500ms
           const BACKOFF_INITIAL_MS = 5;
           const BACKOFF_MAX_MS = 500;
           const BACKOFF_GROWTH = 1.5;
@@ -765,30 +791,30 @@ export class ClientSession
               BACKOFF_MAX_MS
             );
 
-          const willExceedTransactionDeadline =
-            (this.timeoutContext?.csotEnabled() &&
-              backoffMS > this.timeoutContext.remainingTimeMS) ||
-            processTimeMS() + backoffMS > startTime + MAX_TIMEOUT;
-
-          if (willExceedTransactionDeadline) {
-            throw (
+          if (processTimeMS() + backoffMS >= deadline) {
+            throw makeTimeoutError(
               lastError ??
-              new MongoRuntimeError(
-                `Transaction retry did not record an error: should never occur. Please file a bug.`
-              )
+                new MongoRuntimeError(
+                  `Transaction retry did not record an error: should never occur. Please file a bug.`
+                ),
+              csotEnabled
             );
           }
 
           await setTimeout(backoffMS);
         }
 
-        // 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
+        // 3. Invoke startTransaction on the session and increment transactionAttempt. If TransactionOptions were
+        // specified in the call to withTransaction, those MUST be used for startTransaction. Note that
+        // ClientSession.defaultTransactionOptions will be used in the absence of any explicit TransactionOptions.
+        // 4. If startTransaction reported an error, propagate that error to the caller of withTransaction as is and
+        // return immediately.
+        this.startTransaction(options);
 
         try {
-          // 5. Invoke the callback.
-          // 6. Control returns to withTransaction. (continued below)
+          // 5. Invoke the callback. Drivers MUST ensure that the ClientSession can be accessed within the callback
+          // (e.g. pass ClientSession as the first parameter, rely on lexical scoping). Drivers MAY pass additional
+          // parameters as needed (e.g. user data solicited by withTransaction).
           const promise = fn(this);
           if (!isPromiseLike(promise)) {
             throw new MongoInvalidArgumentError(
@@ -796,21 +822,21 @@ export class ClientSession
             );
           }
 
+          // 6. Control returns to withTransaction. Determine the current state of the ClientSession and whether the
+          // callback reported an error (e.g. thrown exception, error output parameter).
           result = await promise;
 
-          // 6. (cont.) Determine the current state of the ClientSession (continued below)
+          // 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.
           if (
             this.transaction.state === TxnState.NO_TRANSACTION ||
             this.transaction.state === TxnState.TRANSACTION_COMMITTED ||
             this.transaction.state === TxnState.TRANSACTION_ABORTED
           ) {
-            // 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
-          // 7. If the callback reported an error:
         } catch (fnError) {
+          // 7. If the callback reported an error
           if (!(fnError instanceof MongoError) || fnError instanceof MongoInvalidArgumentError) {
             // This first preemptive abort regardless of TxnState isn't spec,
             // and it's unclear whether it's serving a practical purpose, but this logic is OLD
@@ -818,83 +844,70 @@ export class ClientSession
             throw fnError;
           }
 
+          lastError = fnError;
+
+          // 7.1 If the ClientSession is in the "starting transaction" or "transaction in progress"
+          // state, invoke abortTransaction on the session.
           if (
             this.transaction.state === TxnState.STARTING_TRANSACTION ||
             this.transaction.state === TxnState.TRANSACTION_IN_PROGRESS
           ) {
-            // 7.i If the ClientSession is in the "starting transaction" or "transaction in progress" state,
-            // invoke abortTransaction on the session
             await this.abortTransaction();
           }
 
-          if (
-            fnError.hasErrorLabel(MongoErrorLabel.TransientTransactionError) &&
-            (this.timeoutContext?.csotEnabled() || processTimeMS() - startTime < MAX_TIMEOUT)
-          ) {
-            // 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;
+          // 7.2 If the callback's error includes a "TransientTransactionError" label, jump back to step two.
+          if (fnError.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
+            if (processTimeMS() >= deadline) {
+              throw makeTimeoutError(lastError, csotEnabled);
+            }
             continue retryTransaction;
           }
 
-          // 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 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.
+          // 7.3 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
+          // as is and return immediately.
+          // 7.4 Otherwise, propagate the callback's error to the caller of withTransaction as is and return immediately.
           throw fnError;
         }
 
         retryCommit: while (!committed) {
           try {
-            /*
-             * We will rely on ClientSession.commitTransaction() to
-             * apply a majority write concern if commitTransaction is
-             * being retried (see: DRIVERS-601)
-             */
             // 9. Invoke commitTransaction on the session.
             await this.commitTransaction();
             committed = true;
-            // 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
-            // abort the withTransaction call).
-            // If CSOT is not enabled, do we still have time remaining or have we timed out?
-            const hasTimedOut =
-              !this.timeoutContext?.csotEnabled() && processTimeMS() - startTime >= MAX_TIMEOUT;
-
-            if (!hasTimedOut) {
-              /*
-               * Note: a maxTimeMS error will have the MaxTimeMSExpired
-               * code (50) and can be reported as a top-level error or
-               * inside writeConcernError, ex.
-               * { ok:0, code: 50, codeName: 'MaxTimeMSExpired' }
-               * { ok:1, writeConcernError: { code: 50, codeName: 'MaxTimeMSExpired' } }
-               */
-              if (
-                !isMaxTimeMSExpiredError(commitError) &&
-                commitError.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult)
-              ) {
-                // 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;
+            // 10. If commitTransaction reported an error:
+            lastError = commitError;
+
+            // 10.1 If the commitTransaction error includes a UnknownTransactionCommitResult label and the error is
+            // not MaxTimeMSExpired
+            if (
+              commitError.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult) &&
+              !isMaxTimeMSExpiredError(commitError)
+            ) {
+              // 10.1.1 If the elapsed time of withTransaction exceeded TIMEOUT_MS, propagate the commitTransaction
+              // error to the caller of withTransaction as per timeout error propagation and return immediately.
+              if (processTimeMS() >= deadline) {
+                throw makeTimeoutError(commitError, csotEnabled);
               }
+              // 10.1.2 Otherwise, jump back to step nine. We will trust commitTransaction to apply a majority write
+              // concern on retry attempts (see: Majority write concern is used when retrying commitTransaction).
+              continue retryCommit;
+            }
 
-              if (commitError.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
-                // 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;
-              }
+            // 10.2 If the commitTransaction error includes a TransientTransactionError label, jump back to step two.
+            if (commitError.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
+              continue retryTransaction;
             }
 
-            // 10.iii Otherwise, propagate the commitTransaction error to the caller of withTransaction and return immediately.
+            // 10.3 Otherwise, propagate the commitTransaction error to the caller of withTransaction as is and return
+            // immediately.
             throw commitError;
           }
         }
       }
 
+      // 11. The transaction was committed successfully. Return immediately.
       // @ts-expect-error Result is always defined if we reach here, the for-loop above convinces TS it is not.
       return result;
     } finally {
@@ -903,6 +916,25 @@ export class ClientSession
   }
 }
 
+function makeTimeoutError(cause: Error, csotEnabled: boolean): Error {
+  // Async APIs know how to cancel themselves and might return CSOT error
+  if (cause instanceof MongoOperationTimeoutError) {
+    return cause;
+  }
+  if (csotEnabled) {
+    const timeoutError = new MongoOperationTimeoutError('Timed out during withTransaction', {
+      cause
+    });
+    if (cause instanceof MongoError) {
+      for (const label of cause.errorLabels) {
+        timeoutError.addErrorLabel(label);
+      }
+    }
+    return timeoutError;
+  }
+  return cause;
+}
+
 const NON_DETERMINISTIC_WRITE_CONCERN_ERRORS = new Set([
   'CannotSatisfyWriteConcern',
   'UnknownReplWriteConcern',
@@ -1018,7 +1050,7 @@ export class ServerSession {
   /** @internal */
   constructor(cloned?: ServerSession | null) {
     if (cloned != null) {
-      const idBytes = Buffer.allocUnsafe(16);
+      const idBytes = ByteUtils.allocateUnsafe(16);
       idBytes.set(cloned.id.id.buffer);
       this.id = { id: new Binary(idBytes, cloned.id.id.sub_type) };
       this.lastUse = cloned.lastUse;
@@ -1203,7 +1235,6 @@ export function applySession(
   command.autocommit = false;
 
   if (session.transaction.state === TxnState.STARTING_TRANSACTION) {
-    session.transaction.transition(TxnState.TRANSACTION_IN_PROGRESS);
     command.startTransaction = true;
 
     const readConcern =
@@ -1241,4 +1272,17 @@ export function updateSessionFromResponse(session: ClientSession, document: Mong
       session.snapshotTime = atClusterTime;
     }
   }
+
+  if (session.transaction.state === TxnState.STARTING_TRANSACTION) {
+    if (document.ok === 1) {
+      session.transaction.transition(TxnState.TRANSACTION_IN_PROGRESS);
+    } else {
+      const error = new MongoServerError(document.toObject());
+      const isRetryableError = error.hasErrorLabel(MongoErrorLabel.RetryableError);
+
+      if (!isRetryableError) {
+        session.transaction.transition(TxnState.TRANSACTION_IN_PROGRESS);
+      }
+    }
+  }
 }

package/src/utils.ts

@@ -1,4 +1,3 @@
-import * as crypto from 'crypto';
 import type { SrvRecord } from 'dns';
 import { type EventEmitter } from 'events';
 import { promises as fs } from 'fs';
@@ -6,7 +5,14 @@ import * as http from 'http';
 import * as process from 'process';
 import { clearTimeout, setTimeout } from 'timers';
 
-import { deserialize, type Document, ObjectId, resolveBSONOptions } from './bson';
+import {
+  ByteUtils,
+  deserialize,
+  type Document,
+  NumberUtils,
+  ObjectId,
+  resolveBSONOptions
+} from './bson';
 import type { Connection } from './cmap/connection';
 import { MAX_SUPPORTED_WIRE_VERSION } from './cmap/wire_protocol/constants';
 import type { Collection } from './collection';
@@ -44,26 +50,6 @@ export type Callback<T = any> = (error?: AnyError, result?: T) => void;
 
 export type AnyOptions = Document;
 
-export const ByteUtils = {
-  toLocalBufferType(this: void, buffer: Buffer | Uint8Array): Buffer {
-    return Buffer.isBuffer(buffer)
-      ? buffer
-      : Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-  },
-
-  equals(this: void, seqA: Uint8Array, seqB: Uint8Array) {
-    return ByteUtils.toLocalBufferType(seqA).equals(seqB);
-  },
-
-  compare(this: void, seqA: Uint8Array, seqB: Uint8Array) {
-    return ByteUtils.toLocalBufferType(seqA).compare(seqB);
-  },
-
-  toBase64(this: void, uint8array: Uint8Array) {
-    return ByteUtils.toLocalBufferType(uint8array).toString('base64');
-  }
-};
-
 /**
  * Returns true if value is a Uint8Array or a Buffer
  * @param value - any value that may be a Uint8Array
@@ -332,8 +318,8 @@ export function* makeCounter(seed = 0): Generator<number> {
  * Synchronously Generate a UUIDv4
  * @internal
  */
-export function uuidV4(): Buffer {
-  const result = crypto.randomBytes(16);
+export function uuidV4(): Uint8Array {
+  const result = crypto.getRandomValues(new Uint8Array(16));
   result[6] = (result[6] & 0x0f) | 0x40;
   result[8] = (result[8] & 0x3f) | 0x80;
   return result;
@@ -807,7 +793,7 @@ export class List<T = unknown> {
  * @internal
  */
 export class BufferPool {
-  private buffers: List<Buffer>;
+  private buffers: List<Uint8Array>;
   private totalByteLength: number;
 
   constructor() {
@@ -820,7 +806,7 @@ export class BufferPool {
   }
 
   /** Adds a buffer to the internal buffer pool list */
-  append(buffer: Buffer): void {
+  append(buffer: Uint8Array): void {
     this.buffers.push(buffer);
     this.totalByteLength += buffer.length;
   }
@@ -835,13 +821,13 @@ export class BufferPool {
     }
     const firstBuffer = this.buffers.first();
     if (firstBuffer != null && firstBuffer.byteLength >= 4) {
-      return firstBuffer.readInt32LE(0);
+      return NumberUtils.getInt32LE(firstBuffer, 0);
     }
 
     // Unlikely case: an int32 is split across buffers.
     // Use read and put the returned buffer back on top
     const top4Bytes = this.read(4);
-    const value = top4Bytes.readInt32LE(0);
+    const value = NumberUtils.getInt32LE(top4Bytes, 0);
 
     // Put it back.
     this.totalByteLength += 4;
@@ -851,19 +837,19 @@ export class BufferPool {
   }
 
   /** Reads the requested number of bytes, optionally consuming them */
-  read(size: number): Buffer {
+  read(size: number): Uint8Array {
     if (typeof size !== 'number' || size < 0) {
       throw new MongoInvalidArgumentError('Argument "size" must be a non-negative number');
     }
 
     // oversized request returns empty buffer
     if (size > this.totalByteLength) {
-      return Buffer.alloc(0);
+      return ByteUtils.allocate(0);
     }
 
     // We know we have enough, we just don't know how it is spread across chunks
     // TODO(NODE-4732): alloc API should change based on raw option
-    const result = Buffer.allocUnsafe(size);
+    const result = ByteUtils.allocateUnsafe(size);
 
     for (let bytesRead = 0; bytesRead < size; ) {
       const buffer = this.buffers.shift();
@@ -1253,13 +1239,8 @@ export function squashError(_error: unknown) {
   return;
 }
 
-export const randomBytes = (size: number) => {
-  return new Promise<Buffer>((resolve, reject) => {
-    crypto.randomBytes(size, (error: Error | null, buf: Buffer) => {
-      if (error) return reject(error);
-      resolve(buf);
-    });
-  });
+export const randomBytes = (size: number): Promise<Uint8Array> => {
+  return Promise.resolve(crypto.getRandomValues(new Uint8Array(size)));
 };
 
 /**
@@ -1345,10 +1326,10 @@ export function decorateDecryptionResult(
 ): void {
   if (isTopLevelDecorateCall) {
     // The original value could have been either a JS object or a BSON buffer
-    if (Buffer.isBuffer(original)) {
+    if (ByteUtils.isUint8Array(original)) {
       original = deserialize(original);
     }
-    if (Buffer.isBuffer(decrypted)) {
+    if (ByteUtils.isUint8Array(decrypted)) {
       throw new MongoRuntimeError('Expected result of decryption to be deserialized BSON object');
     }
   }

package/tsconfig.json

@@ -43,4 +43,4 @@
   "include": [
     "src/**/*"
   ]
-}
+}