mongodb 4.4.1 → 4.6.0

package/src/sessions.ts

@@ -6,16 +6,14 @@ import { PINNED, UNPINNED } from './constants';
 import type { AbstractCursor } from './cursor/abstract_cursor';
 import {
   AnyError,
-  isRetryableEndTransactionError,
-  isRetryableError,
   MongoAPIError,
   MongoCompatibilityError,
   MONGODB_ERROR_CODES,
   MongoDriverError,
   MongoError,
+  MongoErrorLabel,
   MongoExpiredSessionError,
   MongoInvalidArgumentError,
-  MongoNetworkError,
   MongoRuntimeError,
   MongoServerError,
   MongoTransactionError,
@@ -41,24 +39,9 @@ import {
   now,
   uuidV4
 } from './utils';
-import type { WriteConcern } from './write_concern';
 
 const minWireVersionForShardedTransactions = 8;
 
-function assertAlive(session: ClientSession, callback?: Callback): boolean {
-  if (session.serverSession == null) {
-    const error = new MongoExpiredSessionError();
-    if (typeof callback === 'function') {
-      callback(error);
-      return false;
-    }
-
-    throw error;
-  }
-
-  return true;
-}
-
 /** @public */
 export interface ClientSessionOptions {
   /** Whether causal consistency should be enabled on this session */
@@ -92,6 +75,8 @@ const kSnapshotTime = Symbol('snapshotTime');
 const kSnapshotEnabled = Symbol('snapshotEnabled');
 /** @internal */
 const kPinnedConnection = Symbol('pinnedConnection');
+/** @internal Accumulates total number of increments to add to txnNumber when applying session to command */
+const kTxnNumberIncrement = Symbol('txnNumberIncrement');
 
 /** @public */
 export interface EndSessionOptions {
@@ -126,13 +111,15 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   defaultTransactionOptions: TransactionOptions;
   transaction: Transaction;
   /** @internal */
-  [kServerSession]?: ServerSession;
+  [kServerSession]: ServerSession | null;
   /** @internal */
   [kSnapshotTime]?: Timestamp;
   /** @internal */
   [kSnapshotEnabled] = false;
   /** @internal */
   [kPinnedConnection]?: Connection;
+  /** @internal */
+  [kTxnNumberIncrement]: number;
 
   /**
    * Create a client session.
@@ -175,7 +162,10 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     this.sessionPool = sessionPool;
     this.hasEnded = false;
     this.clientOptions = clientOptions;
-    this[kServerSession] = undefined;
+
+    this.explicit = !!options.explicit;
+    this[kServerSession] = this.explicit ? this.sessionPool.acquire() : null;
+    this[kTxnNumberIncrement] = 0;
 
     this.supports = {
       causalConsistency: options.snapshot !== true && options.causalConsistency !== false
@@ -184,7 +174,6 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     this.clusterTime = options.initialClusterTime;
 
     this.operationTime = undefined;
-    this.explicit = !!options.explicit;
     this.owner = options.owner;
     this.defaultTransactionOptions = Object.assign({}, options.defaultTransactionOptions);
     this.transaction = new Transaction();
@@ -192,16 +181,22 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
 
   /** The server id associated with this session */
   get id(): ServerSessionId | undefined {
-    return this.serverSession?.id;
+    return this[kServerSession]?.id;
   }
 
   get serverSession(): ServerSession {
-    if (this[kServerSession] == null) {
-      this[kServerSession] = this.sessionPool.acquire();
+    let serverSession = this[kServerSession];
+    if (serverSession == null) {
+      if (this.explicit) {
+        throw new MongoRuntimeError('Unexpected null serverSession for an explicit session');
+      }
+      if (this.hasEnded) {
+        throw new MongoRuntimeError('Unexpected null serverSession for an ended implicit session');
+      }
+      serverSession = this.sessionPool.acquire();
+      this[kServerSession] = serverSession;
     }
-
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    return this[kServerSession]!;
+    return serverSession;
   }
 
   /** Whether or not this session is configured for snapshot reads */
@@ -270,9 +265,15 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
       const completeEndSession = () => {
         maybeClearPinnedConnection(this, finalOptions);
 
-        // release the server session back to the pool
-        this.sessionPool.release(this.serverSession);
-        this[kServerSession] = undefined;
+        const serverSession = this[kServerSession];
+        if (serverSession != null) {
+          // release the server session back to the pool
+          this.sessionPool.release(serverSession);
+          // Make sure a new serverSession never makes it on to the ClientSession
+          Object.defineProperty(this, kServerSession, {
+            value: ServerSession.clone(serverSession)
+          });
+        }
 
         // mark the session as ended, and emit a signal
         this.hasEnded = true;
@@ -282,7 +283,9 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
         done();
       };
 
-      if (this.serverSession && this.inTransaction()) {
+      if (this.inTransaction()) {
+        // If we've reached endSession and the transaction is still active
+        // by default we abort it
         this.abortTransaction(err => {
           if (err) return done(err);
           completeEndSession();
@@ -356,12 +359,16 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     return this.id.id.buffer.equals(session.id.id.buffer);
   }
 
-  /** Increment the transaction number on the internal ServerSession */
+  /**
+   * Increment the transaction number on the internal ServerSession
+   *
+   * @privateRemarks
+   * This helper increments a value stored on the client session that will be
+   * added to the serverSession's txnNumber upon applying it to a command.
+   * This is because the serverSession is lazily acquired after a connection is obtained
+   */
   incrementTransactionNumber(): void {
-    if (this.serverSession) {
-      this.serverSession.txnNumber =
-        typeof this.serverSession.txnNumber === 'number' ? this.serverSession.txnNumber + 1 : 0;
-    }
+    this[kTxnNumberIncrement] += 1;
   }
 
   /** @returns whether this session is currently in a transaction or not */
@@ -379,7 +386,6 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
       throw new MongoCompatibilityError('Transactions are not allowed with snapshot sessions');
     }
 
-    assertAlive(this);
     if (this.inTransaction()) {
       throw new MongoTransactionError('Transaction already in progress');
     }
@@ -507,7 +513,7 @@ export function maybeClearPinnedConnection(
     session.inTransaction() &&
     error &&
     error instanceof MongoError &&
-    error.hasErrorLabel('TransientTransactionError')
+    error.hasErrorLabel(MongoErrorLabel.TransientTransactionError)
   ) {
     return;
   }
@@ -559,11 +565,11 @@ function attemptTransactionCommit<T>(
       hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT) &&
       !isMaxTimeMSExpiredError(err)
     ) {
-      if (err.hasErrorLabel('UnknownTransactionCommitResult')) {
+      if (err.hasErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult)) {
         return attemptTransactionCommit(session, startTime, fn, options);
       }
 
-      if (err.hasErrorLabel('TransientTransactionError')) {
+      if (err.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
         return attemptTransaction(session, startTime, fn, options);
       }
     }
@@ -617,20 +623,20 @@ function attemptTransaction<TSchema>(
       function maybeRetryOrThrow(err: MongoError): Promise<any> {
         if (
           err instanceof MongoError &&
-          err.hasErrorLabel('TransientTransactionError') &&
+          err.hasErrorLabel(MongoErrorLabel.TransientTransactionError) &&
           hasNotTimedOut(startTime, MAX_WITH_TRANSACTION_TIMEOUT)
         ) {
           return attemptTransaction(session, startTime, fn, options);
         }
 
         if (isMaxTimeMSExpiredError(err)) {
-          err.addErrorLabel('UnknownTransactionCommitResult');
+          err.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
         }
 
         throw err;
       }
 
-      if (session.transaction.isActive) {
+      if (session.inTransaction()) {
         return session.abortTransaction().then(() => maybeRetryOrThrow(err));
       }
 
@@ -639,12 +645,11 @@ function attemptTransaction<TSchema>(
   );
 }
 
-function endTransaction(session: ClientSession, commandName: string, callback: Callback<Document>) {
-  if (!assertAlive(session, callback)) {
-    // checking result in case callback was called
-    return;
-  }
-
+function endTransaction(
+  session: ClientSession,
+  commandName: 'abortTransaction' | 'commitTransaction',
+  callback: Callback<Document>
+) {
   // handle any initial problematic cases
   const txnState = session.transaction.state;
 
@@ -717,7 +722,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
     Object.assign(command, { maxTimeMS: session.transaction.options.maxTimeMS });
   }
 
-  function commandHandler(e?: MongoError, r?: Document) {
+  function commandHandler(error?: Error, result?: Document) {
     if (commandName !== 'commitTransaction') {
       session.transaction.transition(TxnState.TRANSACTION_ABORTED);
       if (session.loadBalanced) {
@@ -729,47 +734,45 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
     }
 
     session.transaction.transition(TxnState.TRANSACTION_COMMITTED);
-    if (e) {
+    if (error instanceof MongoError) {
       if (
-        e instanceof MongoNetworkError ||
-        e instanceof MongoWriteConcernError ||
-        isRetryableError(e) ||
-        isMaxTimeMSExpiredError(e)
+        error.hasErrorLabel(MongoErrorLabel.RetryableWriteError) ||
+        error instanceof MongoWriteConcernError ||
+        isMaxTimeMSExpiredError(error)
       ) {
-        if (isUnknownTransactionCommitResult(e)) {
-          e.addErrorLabel('UnknownTransactionCommitResult');
+        if (isUnknownTransactionCommitResult(error)) {
+          error.addErrorLabel(MongoErrorLabel.UnknownTransactionCommitResult);
 
           // per txns spec, must unpin session in this case
-          session.unpin({ error: e });
+          session.unpin({ error });
         }
-      } else if (e.hasErrorLabel('TransientTransactionError')) {
-        session.unpin({ error: e });
+      } else if (error.hasErrorLabel(MongoErrorLabel.TransientTransactionError)) {
+        session.unpin({ error });
       }
     }
 
-    callback(e, r);
+    callback(error, result);
   }
 
-  // Assumption here that commandName is "commitTransaction" or "abortTransaction"
   if (session.transaction.recoveryToken) {
     command.recoveryToken = session.transaction.recoveryToken;
   }
 
   // send the command
   executeOperation(
-    session.topology,
+    session,
     new RunAdminCommandOperation(undefined, command, {
       session,
       readPreference: ReadPreference.primary,
       bypassPinningCheck: true
     }),
-    (err, reply) => {
+    (error, result) => {
       if (command.abortTransaction) {
         // always unpin on abort regardless of command outcome
         session.unpin();
       }
 
-      if (err && isRetryableEndTransactionError(err as MongoError)) {
+      if (error instanceof MongoError && error.hasErrorLabel(MongoErrorLabel.RetryableWriteError)) {
         // SPEC-1185: apply majority write concern when retrying commitTransaction
         if (command.commitTransaction) {
           // per txns spec, must unpin session in this case
@@ -781,17 +784,17 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
         }
 
         return executeOperation(
-          session.topology,
+          session,
           new RunAdminCommandOperation(undefined, command, {
             session,
             readPreference: ReadPreference.primary,
             bypassPinningCheck: true
           }),
-          (_err, _reply) => commandHandler(_err as MongoError, _reply)
+          commandHandler
         );
       }
 
-      commandHandler(err as MongoError, reply);
+      commandHandler(error, result);
     }
   );
 }
@@ -832,6 +835,30 @@ export class ServerSession {
 
     return idleTimeMinutes > sessionTimeoutMinutes - 1;
   }
+
+  /**
+   * @internal
+   * Cloning meant to keep a readable reference to the server session data
+   * after ClientSession has ended
+   */
+  static clone(serverSession: ServerSession): Readonly<ServerSession> {
+    const arrayBuffer = new ArrayBuffer(16);
+    const idBytes = Buffer.from(arrayBuffer);
+    idBytes.set(serverSession.id.id.buffer);
+
+    const id = new Binary(idBytes, serverSession.id.id.sub_type);
+
+    // Manual prototype construction to avoid modifying the constructor of this class
+    return Object.setPrototypeOf(
+      {
+        id: { id },
+        lastUse: serverSession.lastUse,
+        txnNumber: serverSession.txnNumber,
+        isDirty: serverSession.isDirty
+      },
+      ServerSession.prototype
+    );
+  }
 }
 
 /**
@@ -936,26 +963,27 @@ export class ServerSessionPool {
  * @param session - the session tracking transaction state
  * @param command - the command to decorate
  * @param options - Optional settings passed to calling operation
+ *
+ * @internal
  */
 export function applySession(
   session: ClientSession,
   command: Document,
-  options?: CommandOptions
+  options: CommandOptions
 ): MongoDriverError | undefined {
-  // TODO: merge this with `assertAlive`, did not want to throw a try/catch here
   if (session.hasEnded) {
     return new MongoExpiredSessionError();
   }
 
+  // May acquire serverSession here
   const serverSession = session.serverSession;
   if (serverSession == null) {
     return new MongoRuntimeError('Unable to acquire server session');
   }
 
-  // SPEC-1019: silently ignore explicit session with unacknowledged write for backwards compatibility
-  // FIXME: NODE-2781, this check for write concern shouldn't be happening here, but instead during command construction
-  if (options && options.writeConcern && (options.writeConcern as WriteConcern).w === 0) {
+  if (options.writeConcern?.w === 0) {
     if (session && session.explicit) {
+      // Error if user provided an explicit session to an unacknowledged write (SPEC-1019)
       return new MongoAPIError('Cannot have explicit session with unacknowledged writes');
     }
     return;
@@ -965,15 +993,16 @@ export function applySession(
   serverSession.lastUse = now();
   command.lsid = serverSession.id;
 
-  // first apply non-transaction-specific sessions data
-  const inTransaction = session.inTransaction() || isTransactionCommand(command);
-  const isRetryableWrite = options?.willRetryWrite || false;
+  const inTxnOrTxnCommand = session.inTransaction() || isTransactionCommand(command);
+  const isRetryableWrite = !!options.willRetryWrite;
 
-  if (serverSession.txnNumber && (isRetryableWrite || inTransaction)) {
+  if (isRetryableWrite || inTxnOrTxnCommand) {
+    serverSession.txnNumber += session[kTxnNumberIncrement];
+    session[kTxnNumberIncrement] = 0;
     command.txnNumber = Long.fromNumber(serverSession.txnNumber);
   }
 
-  if (!inTransaction) {
+  if (!inTxnOrTxnCommand) {
     if (session.transaction.state !== TxnState.NO_TRANSACTION) {
       session.transaction.transition(TxnState.NO_TRANSACTION);
     }
@@ -1015,6 +1044,7 @@ export function applySession(
       Object.assign(command.readConcern, { afterClusterTime: session.operationTime });
     }
   }
+  return;
 }
 
 export function updateSessionFromResponse(session: ClientSession, document: Document): void {

package/src/utils.ts

@@ -8,11 +8,12 @@ import type { Connection } from './cmap/connection';
 import { MAX_SUPPORTED_WIRE_VERSION } from './cmap/wire_protocol/constants';
 import type { Collection } from './collection';
 import { LEGACY_HELLO_COMMAND } from './constants';
+import type { AbstractCursor } from './cursor/abstract_cursor';
+import type { FindCursor } from './cursor/find_cursor';
 import type { Db } from './db';
 import {
   AnyError,
   MongoCompatibilityError,
-  MongoExpiredSessionError,
   MongoInvalidArgumentError,
   MongoNotConnectedError,
   MongoParseError,
@@ -37,8 +38,6 @@ import { W, WriteConcern, WriteConcernOptions } from './write_concern';
  * @public
  */
 export type Callback<T = any> = (error?: AnyError, result?: T) => void;
-/** @public */
-export type CallbackWithType<E = AnyError, T0 = any> = (error?: E, result?: T0) => void;
 
 export const MAX_JS_INT = Number.MAX_SAFE_INTEGER + 1;
 
@@ -177,7 +176,7 @@ export function mergeOptions<T, S>(target: T, source: S): T & S {
 }
 
 /** @internal */
-export function filterOptions(options: AnyOptions, names: string[]): AnyOptions {
+export function filterOptions(options: AnyOptions, names: ReadonlyArray<string>): AnyOptions {
   const filterOptions: AnyOptions = {};
 
   for (const name in options) {
@@ -190,110 +189,6 @@ export function filterOptions(options: AnyOptions, names: string[]): AnyOptions
   return filterOptions;
 }
 
-/**
- * Executes the given operation with provided arguments.
- *
- * @remarks
- * This method reduces large amounts of duplication in the entire codebase by providing
- * a single point for determining whether callbacks or promises should be used. Additionally
- * it allows for a single point of entry to provide features such as implicit sessions, which
- * are required by the Driver Sessions specification in the event that a ClientSession is
- * not provided
- *
- * @internal
- *
- * @param topology - The topology to execute this operation on
- * @param operation - The operation to execute
- * @param args - Arguments to apply the provided operation
- * @param options - Options that modify the behavior of the method
- */
-export function executeLegacyOperation(
-  topology: Topology,
-  operation: (...args: any[]) => void | Promise<Document>,
-  args: any[],
-  options?: AnyOptions
-): void | Promise<any> {
-  const Promise = PromiseProvider.get();
-
-  if (!Array.isArray(args)) {
-    // TODO(NODE-3483)
-    throw new MongoRuntimeError('This method requires an array of arguments to apply');
-  }
-
-  options = options ?? {};
-
-  let callback = args[args.length - 1];
-
-  // The driver sessions spec mandates that we implicitly create sessions for operations
-  // that are not explicitly provided with a session.
-  let session: ClientSession;
-  let opOptions: any;
-  let owner: any;
-  if (!options.skipSessions && topology.hasSessionSupport()) {
-    opOptions = args[args.length - 2];
-    if (opOptions == null || opOptions.session == null) {
-      owner = Symbol();
-      session = topology.startSession({ owner });
-      const optionsIndex = args.length - 2;
-      args[optionsIndex] = Object.assign({}, args[optionsIndex], { session: session });
-    } else if (opOptions.session && opOptions.session.hasEnded) {
-      throw new MongoExpiredSessionError();
-    }
-  }
-
-  function makeExecuteCallback(
-    resolve: (value?: Document) => void,
-    reject: (reason?: AnyError) => void
-  ) {
-    return function (err?: AnyError, result?: any) {
-      if (session && session.owner === owner && !options?.returnsCursor) {
-        session.endSession(() => {
-          delete opOptions.session;
-          if (err) return reject(err);
-          resolve(result);
-        });
-      } else {
-        if (err) return reject(err);
-        resolve(result);
-      }
-    };
-  }
-
-  // Execute using callback
-  if (typeof callback === 'function') {
-    callback = args.pop();
-    const handler = makeExecuteCallback(
-      result => callback(undefined, result),
-      err => callback(err, null)
-    );
-    args.push(handler);
-
-    try {
-      return operation(...args);
-    } catch (e) {
-      handler(e);
-      throw e;
-    }
-  }
-
-  // Return a Promise
-  if (args[args.length - 1] != null) {
-    // TODO(NODE-3483)
-    throw new MongoRuntimeError('Final argument to `executeLegacyOperation` must be a callback');
-  }
-
-  return new Promise<any>((resolve, reject) => {
-    const handler = makeExecuteCallback(resolve, reject);
-    args[args.length - 1] = handler;
-
-    try {
-      return operation(...args);
-    } catch (e) {
-      handler(e);
-    }
-  });
-}
-
 interface HasRetryableWrites {
   retryWrites?: boolean;
 }
@@ -434,17 +329,30 @@ export function decorateWithExplain(command: Document, explain: Explain): Docume
   return { explain: command, verbosity: explain.verbosity };
 }
 
+/**
+ * @internal
+ */
+export type TopologyProvider =
+  | MongoClient
+  | ClientSession
+  | FindCursor
+  | AbstractCursor
+  | Collection<any>
+  | Db;
+
 /**
  * A helper function to get the topology from a given provider. Throws
  * if the topology cannot be found.
+ * @throws MongoNotConnectedError
  * @internal
  */
-export function getTopology<T>(provider: MongoClient | Db | Collection<T>): Topology {
+export function getTopology(provider: TopologyProvider): Topology {
+  // MongoClient or ClientSession or AbstractCursor
   if (`topology` in provider && provider.topology) {
     return provider.topology;
-  } else if ('client' in provider.s && provider.s.client.topology) {
+  } else if ('s' in provider && 'client' in provider.s && provider.s.client.topology) {
     return provider.s.client.topology;
-  } else if ('db' in provider.s && provider.s.db.s.client.topology) {
+  } else if ('s' in provider && 'db' in provider.s && provider.s.db.s.client.topology) {
     return provider.s.db.s.client.topology;
   }
 
@@ -1181,7 +1089,7 @@ export function deepCopy<T>(value: T): T {
       case 'set':
         return new Set(value as any) as unknown as T;
       case 'buffer':
-        return Buffer.from(value as Buffer) as unknown as T;
+        return Buffer.from(value as unknown as Buffer) as unknown as T;
     }
   }
 
@@ -1419,13 +1327,25 @@ export function enumToString(en: Record<string, unknown>): string {
  *
  * @internal
  */
-export function supportsRetryableWrites(server: Server): boolean {
-  return (
-    !!server.loadBalanced ||
-    (server.description.maxWireVersion >= 6 &&
-      !!server.description.logicalSessionTimeoutMinutes &&
-      server.description.type !== ServerType.Standalone)
-  );
+export function supportsRetryableWrites(server?: Server): boolean {
+  if (!server) {
+    return false;
+  }
+
+  if (server.loadBalanced) {
+    // Loadbalanced topologies will always support retry writes
+    return true;
+  }
+
+  if (server.description.logicalSessionTimeoutMinutes != null) {
+    // that supports sessions
+    if (server.description.type !== ServerType.Standalone) {
+      // and that is not a standalone
+      return true;
+    }
+  }
+
+  return false;
 }
 
 export function parsePackageVersion({ version }: { version: string }): {

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "compilerOptions": {
+    "allowJs": false,
+    "checkJs": false,
+    "strict": true,
+    "alwaysStrict": true,
+    "target": "ES2019",
+    "module": "commonJS",
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "lib": ["es2020"],
+    // We don't make use of tslib helpers, all syntax used is supported by target engine
+    "importHelpers": false,
+    "noEmitHelpers": true,
+    // Never emit error filled code
+    "noEmitOnError": true,
+    "outDir": "lib",
+    "importsNotUsedAsValues": "error",
+    // We want the sourcemaps in a separate file
+    "inlineSourceMap": false,
+    "sourceMap": true,
+    // API-Extractor uses declaration maps to report problems in source, no need to distribute
+    "declaration": true,
+    "declarationMap": true,
+    // we include sources in the release
+    "inlineSources": false,
+    // Prevents web types from being suggested by vscode.
+    "types": ["node"],
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    // TODO(NODE-3659): Enable useUnknownInCatchVariables and add type assertions or remove unnecessary catch blocks
+    "useUnknownInCatchVariables": false
+  },
+  "ts-node": {
+    "transpileOnly": true,
+    "compiler": "typescript-cached-transpile"
+  },
+  "include": ["src/**/*"]
+}