mongodb 6.5.0 → 6.6.0-dev.20240504.sha.2609953

package/src/sessions.ts

@@ -1,8 +1,7 @@
-import { promisify } from 'util';
-
 import { Binary, 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';
 import { isSharded } from './cmap/wire_protocol/shared';
 import { PINNED, UNPINNED } from './constants';
 import type { AbstractCursor } from './cursor/abstract_cursor';
@@ -38,12 +37,12 @@ import {
 import {
   ByteUtils,
   calculateDurationInMs,
-  type Callback,
   commandSupportsReadConcern,
   isPromiseLike,
   List,
   maxWireVersion,
   now,
+  squashError,
   uuidV4
 } from './utils';
 import { WriteConcern } from './write_concern';
@@ -58,6 +57,9 @@ export interface ClientSessionOptions {
   snapshot?: boolean;
   /** The default TransactionOptions to use for transactions started on this session. */
   defaultTransactionOptions?: TransactionOptions;
+  /** @internal
+   * The value of timeoutMS used for CSOT. Used to override client timeoutMS */
+  defaultTimeoutMS?: number;
 
   /** @internal */
   owner?: symbol | AbstractCursor;
@@ -128,6 +130,8 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   [kPinnedConnection]?: Connection;
   /** @internal */
   [kTxnNumberIncrement]: number;
+  /** @internal */
+  timeoutMS?: number;
 
   /**
    * Create a client session.
@@ -170,6 +174,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     this.sessionPool = sessionPool;
     this.hasEnded = false;
     this.clientOptions = clientOptions;
+    this.timeoutMS = options.defaultTimeoutMS ?? client.options?.timeoutMS;
 
     this.explicit = !!options.explicit;
     this[kServerSession] = this.explicit ? this.sessionPool.acquire() : null;
@@ -185,7 +190,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
 
     this.operationTime = undefined;
     this.owner = options.owner;
-    this.defaultTransactionOptions = Object.assign({}, options.defaultTransactionOptions);
+    this.defaultTransactionOptions = { ...options.defaultTransactionOptions };
     this.transaction = new Transaction();
   }
 
@@ -274,8 +279,9 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
         this.hasEnded = true;
         this.emit('ended', this);
       }
-    } catch {
+    } catch (error) {
       // spec indicates that we should ignore all errors for `endSessions`
+      squashError(error);
     } finally {
       maybeClearPinnedConnection(this, { force: true, ...options });
     }
@@ -415,14 +421,14 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
    * Commits the currently active transaction in this session.
    */
   async commitTransaction(): Promise<void> {
-    return endTransactionAsync(this, 'commitTransaction');
+    return await endTransaction(this, 'commitTransaction');
   }
 
   /**
    * Aborts the currently active transaction in this session.
    */
   async abortTransaction(): Promise<void> {
-    return endTransactionAsync(this, 'abortTransaction');
+    return await endTransaction(this, 'abortTransaction');
   }
 
   /**
@@ -435,18 +441,26 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   /**
    * Starts a transaction and runs a provided function, ensuring the commitTransaction is always attempted when all operations run in the function have completed.
    *
-   * **IMPORTANT:** This method requires the user to return a Promise, and `await` all operations.
+   * **IMPORTANT:** This method requires the function passed in to return a Promise. That promise must be made by `await`-ing all operations in such a way that rejections are propagated to the returned promise.
    *
    * @remarks
-   * This function:
-   * - If all operations successfully complete and the `commitTransaction` operation is successful, then this function will return the result of the provided function.
-   * - If the transaction is unable to complete or an error is thrown from within the provided function, then this function will throw an error.
+   * - If all operations successfully complete and the `commitTransaction` operation is successful, then the provided function will return the result of the provided function.
+   * - If the transaction is unable to complete or an error is thrown from within the provided function, then the provided function will throw an error.
    *   - If the transaction is manually aborted within the provided function it will not throw.
-   * - May be called multiple times if the driver needs to attempt to retry the operations.
+   * - If the driver needs to attempt to retry the operations, the provided function may be called multiple times.
    *
    * Checkout a descriptive example here:
    * @see https://www.mongodb.com/blog/post/quick-start-nodejs--mongodb--how-to-implement-transactions
    *
+   * If a command inside withTransaction fails:
+   * - It may cause the transaction on the server to be aborted.
+   * - This situation is normally handled transparently by the driver.
+   * - However, if the application catches such an error and does not rethrow it, the driver will not be able to determine whether the transaction was aborted or not.
+   * - The driver will then retry the transaction indefinitely.
+   *
+   * To avoid this situation, the application must not silently handle errors within the provided function.
+   * If the application needs to handle errors within, it must await all operations such that if an operation is rejected it becomes the rejection of the callback function passed into withTransaction.
+   *
    * @param fn - callback to run within a transaction
    * @param options - optional settings for the transaction
    * @returns A raw command response or undefined
@@ -456,7 +470,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     options?: TransactionOptions
   ): Promise<T> {
     const startTime = now();
-    return attemptTransaction(this, startTime, fn, options);
+    return await attemptTransaction(this, startTime, fn, options);
   }
 }
 
@@ -511,6 +525,7 @@ export function maybeClearPinnedConnection(
 
     if (options?.error == null || options?.force) {
       loadBalancer.pool.checkIn(conn);
+      session[kPinnedConnection] = undefined;
       conn.emit(
         UNPINNED,
         session.transaction.state !== TxnState.NO_TRANSACTION
@@ -522,8 +537,6 @@ export function maybeClearPinnedConnection(
         loadBalancer.pool.clear({ serviceId: conn.serviceId });
       }
     }
-
-    session[kPinnedConnection] = undefined;
   }
 }
 
@@ -538,33 +551,33 @@ function isMaxTimeMSExpiredError(err: MongoError) {
   );
 }
 
-function attemptTransactionCommit<T>(
+async function attemptTransactionCommit<T>(
   session: ClientSession,
   startTime: number,
   fn: WithTransactionCallback<T>,
-  result: any,
+  result: T,
   options: TransactionOptions
 ): Promise<T> {
-  return session.commitTransaction().then(
-    () => result,
-    (err: MongoError) => {
-      if (
-        err instanceof MongoError &&
-        hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT) &&
-        !isMaxTimeMSExpiredError(err)
-      ) {
-        if (err.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult)) {
-          return attemptTransactionCommit(session, startTime, fn, result, options);
-        }
-
-        if (err.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
-          return attemptTransaction(session, startTime, fn, options);
-        }
+  try {
+    await session.commitTransaction();
+    return result;
+  } catch (commitErr) {
+    if (
+      commitErr instanceof MongoError &&
+      hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT) &&
+      !isMaxTimeMSExpiredError(commitErr)
+    ) {
+      if (commitErr.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult)) {
+        return await attemptTransactionCommit(session, startTime, fn, result, options);
       }
 
-      throw err;
+      if (commitErr.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
+        return await attemptTransaction(session, startTime, fn, options);
+      }
     }
-  );
+
+    throw commitErr;
+  }
 }
 
 const USER_EXPLICIT_TXN_END_STATES = new Set<TxnState>([
@@ -577,12 +590,12 @@ function userExplicitlyEndedTransaction(session: ClientSession) {
   return USER_EXPLICIT_TXN_END_STATES.has(session.transaction.state);
 }
 
-function attemptTransaction<T>(
+async function attemptTransaction<T>(
   session: ClientSession,
   startTime: number,
   fn: WithTransactionCallback<T>,
   options: TransactionOptions = {}
-): Promise<any> {
+): Promise<T> {
   session.startTransaction(options);
 
   let promise;
@@ -593,65 +606,52 @@ function attemptTransaction<T>(
   }
 
   if (!isPromiseLike(promise)) {
-    session.abortTransaction().catch(() => null);
-    return Promise.reject(
-      new MongoInvalidArgumentError('Function provided to `withTransaction` must return a Promise')
+    try {
+      await session.abortTransaction();
+    } catch (error) {
+      squashError(error);
+    }
+    throw new MongoInvalidArgumentError(
+      'Function provided to `withTransaction` must return a Promise'
     );
   }
 
-  return promise.then(
-    result => {
-      if (userExplicitlyEndedTransaction(session)) {
-        return result;
-      }
-
-      return attemptTransactionCommit(session, startTime, fn, result, options);
-    },
-    err => {
-      function maybeRetryOrThrow(err: MongoError): Promise<any> {
-        if (
-          err instanceof MongoError &&
-          err.hasErrorLabel(MongoErrorLabel.TransientTransactionError) &&
-          hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT)
-        ) {
-          return attemptTransaction(session, startTime, fn, options);
-        }
-
-        if (isMaxTimeMSExpiredError(err)) {
-          err.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
-        }
-
-        throw err;
-      }
+  try {
+    const result = await promise;
+    if (userExplicitlyEndedTransaction(session)) {
+      return result;
+    }
+    return await attemptTransactionCommit(session, startTime, fn, result, options);
+  } catch (err) {
+    if (session.inTransaction()) {
+      await session.abortTransaction();
+    }
 
-      if (session.inTransaction()) {
-        return session.abortTransaction().then(() => maybeRetryOrThrow(err));
-      }
+    if (
+      err instanceof MongoError &&
+      err.hasErrorLabel(MongoErrorLabel.TransientTransactionError) &&
+      hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT)
+    ) {
+      return await attemptTransaction(session, startTime, fn, options);
+    }
 
-      return maybeRetryOrThrow(err);
+    if (isMaxTimeMSExpiredError(err)) {
+      err.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
     }
-  );
-}
 
-const endTransactionAsync = promisify(
-  endTransaction as (
-    session: ClientSession,
-    commandName: 'abortTransaction' | 'commitTransaction',
-    callback: (error: Error) => void
-  ) => void
-);
+    throw err;
+  }
+}
 
-function endTransaction(
+async function endTransaction(
   session: ClientSession,
-  commandName: 'abortTransaction' | 'commitTransaction',
-  callback: Callback<void>
-) {
+  commandName: 'abortTransaction' | 'commitTransaction'
+): Promise<void> {
   // handle any initial problematic cases
   const txnState = session.transaction.state;
 
   if (txnState === TxnState.NO_TRANSACTION) {
-    callback(new MongoTransactionError('No transaction started'));
-    return;
+    throw new MongoTransactionError('No transaction started');
   }
 
   if (commandName === 'commitTransaction') {
@@ -661,37 +661,32 @@ function endTransaction(
     ) {
       // the transaction was never started, we can safely exit here
       session.transaction.transition(TxnState.TRANSACTION_COMMITTED_EMPTY);
-      callback();
       return;
     }
 
     if (txnState === TxnState.TRANSACTION_ABORTED) {
-      callback(
-        new MongoTransactionError('Cannot call commitTransaction after calling abortTransaction')
+      throw new MongoTransactionError(
+        'Cannot call commitTransaction after calling abortTransaction'
       );
-      return;
     }
   } else {
     if (txnState === TxnState.STARTING_TRANSACTION) {
       // the transaction was never started, we can safely exit here
       session.transaction.transition(TxnState.TRANSACTION_ABORTED);
-      callback();
       return;
     }
 
     if (txnState === TxnState.TRANSACTION_ABORTED) {
-      callback(new MongoTransactionError('Cannot call abortTransaction twice'));
-      return;
+      throw new MongoTransactionError('Cannot call abortTransaction twice');
     }
 
     if (
       txnState === TxnState.TRANSACTION_COMMITTED ||
       txnState === TxnState.TRANSACTION_COMMITTED_EMPTY
     ) {
-      callback(
-        new MongoTransactionError('Cannot call abortTransaction after calling commitTransaction')
+      throw new MongoTransactionError(
+        'Cannot call abortTransaction after calling commitTransaction'
       );
-      return;
     }
   }
 
@@ -718,49 +713,38 @@ function endTransaction(
     Object.assign(command, { maxTimeMS: session.transaction.options.maxTimeMS });
   }
 
-  function commandHandler(error?: Error) {
+  if (session.transaction.recoveryToken) {
+    command.recoveryToken = session.transaction.recoveryToken;
+  }
+
+  try {
+    // send the command
+    await executeOperation(
+      session.client,
+      new RunAdminCommandOperation(command, {
+        session,
+        readPreference: ReadPreference.primary,
+        bypassPinningCheck: true
+      })
+    );
+    if (command.abortTransaction) {
+      // always unpin on abort regardless of command outcome
+      session.unpin();
+    }
     if (commandName !== 'commitTransaction') {
       session.transaction.transition(TxnState.TRANSACTION_ABORTED);
       if (session.loadBalanced) {
         maybeClearPinnedConnection(session, { force: false });
       }
-
-      // The spec indicates that we should ignore all errors on `abortTransaction`
-      return callback();
-    }
-
-    session.transaction.transition(TxnState.TRANSACTION_COMMITTED);
-    if (error instanceof MongoError) {
-      if (
-        isRetryableWriteError(error) ||
-        error instanceof MongoWriteConcernError ||
-        isMaxTimeMSExpiredError(error)
-      ) {
-        if (isUnknownTransactionCommitResult(error)) {
-          error.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
-
-          // per txns spec, must unpin session in this case
-          session.unpin({ error });
-        }
-      } else if (error.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
-        session.unpin({ error });
-      }
+    } else {
+      session.transaction.transition(TxnState.TRANSACTION_COMMITTED);
     }
-
-    callback(error);
-  }
-
-  if (session.transaction.recoveryToken) {
-    command.recoveryToken = session.transaction.recoveryToken;
-  }
-
-  const handleFirstCommandAttempt = (error?: Error) => {
+  } catch (firstAttemptErr) {
     if (command.abortTransaction) {
       // always unpin on abort regardless of command outcome
       session.unpin();
     }
-
-    if (error instanceof MongoError && isRetryableWriteError(error)) {
+    if (firstAttemptErr instanceof MongoError && isRetryableWriteError(firstAttemptErr)) {
       // SPEC-1185: apply majority write concern when retrying commitTransaction
       if (command.commitTransaction) {
         // per txns spec, must unpin session in this case
@@ -771,29 +755,65 @@ function endTransaction(
         });
       }
 
-      executeOperation(
-        session.client,
-        new RunAdminCommandOperation(command, {
-          session,
-          readPreference: ReadPreference.primary,
-          bypassPinningCheck: true
-        })
-      ).then(() => commandHandler(), commandHandler);
-      return;
+      try {
+        await executeOperation(
+          session.client,
+          new RunAdminCommandOperation(command, {
+            session,
+            readPreference: ReadPreference.primary,
+            bypassPinningCheck: true
+          })
+        );
+        if (commandName !== 'commitTransaction') {
+          session.transaction.transition(TxnState.TRANSACTION_ABORTED);
+          if (session.loadBalanced) {
+            maybeClearPinnedConnection(session, { force: false });
+          }
+        } else {
+          session.transaction.transition(TxnState.TRANSACTION_COMMITTED);
+        }
+      } catch (secondAttemptErr) {
+        handleEndTransactionError(session, commandName, secondAttemptErr);
+      }
+    } else {
+      handleEndTransactionError(session, commandName, firstAttemptErr);
+    }
+  }
+}
+
+function handleEndTransactionError(
+  session: ClientSession,
+  commandName: 'abortTransaction' | 'commitTransaction',
+  error: Error
+) {
+  if (commandName !== 'commitTransaction') {
+    session.transaction.transition(TxnState.TRANSACTION_ABORTED);
+    if (session.loadBalanced) {
+      maybeClearPinnedConnection(session, { force: false });
     }
+    // The spec indicates that if the operation times out or fails with a non-retryable error, we should ignore all errors on `abortTransaction`
+    return;
+  }
+
+  session.transaction.transition(TxnState.TRANSACTION_COMMITTED);
+  if (error instanceof MongoError) {
+    if (
+      isRetryableWriteError(error) ||
+      error instanceof MongoWriteConcernError ||
+      isMaxTimeMSExpiredError(error)
+    ) {
+      if (isUnknownTransactionCommitResult(error)) {
+        error.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
+
+        // per txns spec, must unpin session in this case
+        session.unpin({ error });
+      }
+    } else if (error.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
+      session.unpin({ error });
+    }
+  }
 
-    commandHandler(error);
-  };
-
-  // send the command
-  executeOperation(
-    session.client,
-    new RunAdminCommandOperation(command, {
-      session,
-      readPreference: ReadPreference.primary,
-      bypassPinningCheck: true
-    })
-  ).then(() => handleFirstCommandAttempt(), handleFirstCommandAttempt);
+  throw error;
 }
 
 /** @public */
@@ -1030,7 +1050,7 @@ export function applySession(
   return;
 }
 
-export function updateSessionFromResponse(session: ClientSession, document: Document): void {
+export function updateSessionFromResponse(session: ClientSession, document: MongoDBResponse): void {
   if (document.$clusterTime) {
     _advanceClusterTime(session, document.$clusterTime);
   }
@@ -1046,7 +1066,7 @@ export function updateSessionFromResponse(session: ClientSession, document: Docu
   if (session?.[kSnapshotEnabled] && session[kSnapshotTime] == null) {
     // find and aggregate commands return atClusterTime on the cursor
     // distinct includes it in the response body
-    const atClusterTime = document.cursor?.atClusterTime || document.atClusterTime;
+    const atClusterTime = document.atClusterTime;
     if (atClusterTime) {
       session[kSnapshotTime] = atClusterTime;
     }

package/src/timeout.ts

@@ -0,0 +1,96 @@
+import { clearTimeout, setTimeout } from 'timers';
+
+import { MongoInvalidArgumentError } from './error';
+import { noop } from './utils';
+
+/** @internal */
+export class TimeoutError extends Error {
+  override get name(): 'TimeoutError' {
+    return 'TimeoutError';
+  }
+
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, options);
+  }
+
+  static is(error: unknown): error is TimeoutError {
+    return (
+      error != null && typeof error === 'object' && 'name' in error && error.name === 'TimeoutError'
+    );
+  }
+}
+
+type Executor = ConstructorParameters<typeof Promise<never>>[0];
+type Reject = Parameters<ConstructorParameters<typeof Promise<never>>[0]>[1];
+/**
+ * @internal
+ * This class is an abstraction over timeouts
+ * The Timeout class can only be in the pending or rejected states. It is guaranteed not to resolve
+ * if interacted with exclusively through its public API
+ * */
+export class Timeout extends Promise<never> {
+  get [Symbol.toStringTag](): 'MongoDBTimeout' {
+    return 'MongoDBTimeout';
+  }
+
+  private id?: NodeJS.Timeout;
+
+  public readonly start: number;
+  public ended: number | null = null;
+  public duration: number;
+  public timedOut = false;
+
+  /** Create a new timeout that expires in `duration` ms */
+  private constructor(executor: Executor = () => null, duration: number) {
+    let reject!: Reject;
+
+    if (duration < 0) {
+      throw new MongoInvalidArgumentError('Cannot create a Timeout with a negative duration');
+    }
+
+    super((_, promiseReject) => {
+      reject = promiseReject;
+
+      executor(noop, promiseReject);
+    });
+
+    this.duration = duration;
+    this.start = Math.trunc(performance.now());
+
+    if (this.duration > 0) {
+      this.id = setTimeout(() => {
+        this.ended = Math.trunc(performance.now());
+        this.timedOut = true;
+        reject(new TimeoutError(`Expired after ${duration}ms`));
+      }, this.duration);
+      // Ensure we do not keep the Node.js event loop running
+      if (typeof this.id.unref === 'function') {
+        this.id.unref();
+      }
+    }
+  }
+
+  /**
+   * Clears the underlying timeout. This method is idempotent
+   */
+  clear(): void {
+    clearTimeout(this.id);
+    this.id = undefined;
+  }
+
+  public static expires(durationMS: number): Timeout {
+    return new Timeout(undefined, durationMS);
+  }
+
+  static is(timeout: unknown): timeout is Timeout {
+    return (
+      typeof timeout === 'object' &&
+      timeout != null &&
+      Symbol.toStringTag in timeout &&
+      timeout[Symbol.toStringTag] === 'MongoDBTimeout' &&
+      'then' in timeout &&
+      // eslint-disable-next-line github/no-then
+      typeof timeout.then === 'function'
+    );
+  }
+}