mongodb 4.0.0 → 4.1.2

package/src/sessions.ts

@@ -2,16 +2,23 @@ import { PromiseProvider } from './promise_provider';
 import { Binary, Long, Timestamp, Document } from './bson';
 import { ReadPreference } from './read_preference';
 import { isTransactionCommand, TxnState, Transaction, TransactionOptions } from './transactions';
-import { resolveClusterTime, ClusterTime } from './sdam/common';
+import { _advanceClusterTime, ClusterTime, TopologyType } from './sdam/common';
 import { isSharded } from './cmap/wire_protocol/shared';
 import {
   MongoError,
+  MongoInvalidArgumentError,
   isRetryableError,
+  MongoCompatibilityError,
   MongoNetworkError,
   MongoWriteConcernError,
   MONGODB_ERROR_CODES,
+  MongoServerError,
   MongoDriverError,
-  MongoServerError
+  MongoAPIError,
+  AnyError,
+  MongoExpiredSessionError,
+  MongoTransactionError,
+  MongoRuntimeError
 } from './error';
 import {
   now,
@@ -28,6 +35,8 @@ import { executeOperation } from './operations/execute_operation';
 import { RunAdminCommandOperation } from './operations/run_command';
 import type { AbstractCursor } from './cursor/abstract_cursor';
 import type { CommandOptions } from './cmap/connection';
+import { Connection } from './cmap/connection';
+import { ConnectionPoolMetrics } from './cmap/metrics';
 import type { WriteConcern } from './write_concern';
 import { TypedEventEmitter } from './mongo_types';
 import { ReadConcernLevel } from './read_concern';
@@ -36,7 +45,7 @@ const minWireVersionForShardedTransactions = 8;
 
 function assertAlive(session: ClientSession, callback?: Callback): boolean {
   if (session.serverSession == null) {
-    const error = new MongoDriverError('Cannot use a session that has ended');
+    const error = new MongoExpiredSessionError();
     if (typeof callback === 'function') {
       callback(error);
       return false;
@@ -79,6 +88,19 @@ const kServerSession = Symbol('serverSession');
 const kSnapshotTime = Symbol('snapshotTime');
 /** @internal */
 const kSnapshotEnabled = Symbol('snapshotEnabled');
+/** @internal */
+const kPinnedConnection = Symbol('pinnedConnection');
+
+/** @public */
+export interface EndSessionOptions {
+  /**
+   * An optional error which caused the call to end this session
+   * @internal
+   */
+  error?: AnyError;
+  force?: boolean;
+  forceClear?: boolean;
+}
 
 /**
  * A class representing a client session on the server
@@ -107,6 +129,8 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   [kSnapshotTime]?: Timestamp;
   /** @internal */
   [kSnapshotEnabled] = false;
+  /** @internal */
+  [kPinnedConnection]?: Connection;
 
   /**
    * Create a client session.
@@ -125,11 +149,13 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     super();
 
     if (topology == null) {
-      throw new MongoDriverError('ClientSession requires a topology');
+      // TODO(NODE-3483)
+      throw new MongoRuntimeError('ClientSession requires a topology');
     }
 
     if (sessionPool == null || !(sessionPool instanceof ServerSessionPool)) {
-      throw new MongoDriverError('ClientSession requires a ServerSessionPool');
+      // TODO(NODE-3483)
+      throw new MongoRuntimeError('ClientSession requires a ServerSessionPool');
     }
 
     options = options ?? {};
@@ -137,7 +163,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     if (options.snapshot === true) {
       this[kSnapshotEnabled] = true;
       if (options.causalConsistency === true) {
-        throw new MongoDriverError(
+        throw new MongoInvalidArgumentError(
           'Properties "causalConsistency" and "snapshot" are mutually exclusive'
         );
       }
@@ -181,6 +207,41 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     return this[kSnapshotEnabled];
   }
 
+  get loadBalanced(): boolean {
+    return this.topology.description.type === TopologyType.LoadBalanced;
+  }
+
+  /** @internal */
+  get pinnedConnection(): Connection | undefined {
+    return this[kPinnedConnection];
+  }
+
+  /** @internal */
+  pin(conn: Connection): void {
+    if (this[kPinnedConnection]) {
+      throw TypeError('Cannot pin multiple connections to the same session');
+    }
+
+    this[kPinnedConnection] = conn;
+    conn.emit(
+      Connection.PINNED,
+      this.inTransaction() ? ConnectionPoolMetrics.TXN : ConnectionPoolMetrics.CURSOR
+    );
+  }
+
+  /** @internal */
+  unpin(options?: { force?: boolean; forceClear?: boolean; error?: AnyError }): void {
+    if (this.loadBalanced) {
+      return maybeClearPinnedConnection(this, options);
+    }
+
+    this.transaction.unpinServer();
+  }
+
+  get isPinned(): boolean {
+    return this.loadBalanced ? !!this[kPinnedConnection] : this.transaction.isPinned;
+  }
+
   /**
    * Ends this session on the server
    *
@@ -189,21 +250,24 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
    */
   endSession(): Promise<void>;
   endSession(callback: Callback<void>): void;
-  endSession(options: Record<string, unknown>): Promise<void>;
-  endSession(options: Record<string, unknown>, callback: Callback<void>): void;
+  endSession(options: EndSessionOptions): Promise<void>;
+  endSession(options: EndSessionOptions, callback: Callback<void>): void;
   endSession(
-    options?: Record<string, unknown> | Callback<void>,
+    options?: EndSessionOptions | Callback<void>,
     callback?: Callback<void>
   ): void | Promise<void> {
     if (typeof options === 'function') (callback = options), (options = {});
-    options = options ?? {};
+    const finalOptions = { force: true, ...options };
 
     return maybePromise(callback, done => {
       if (this.hasEnded) {
+        maybeClearPinnedConnection(this, finalOptions);
         return done();
       }
 
       const completeEndSession = () => {
+        maybeClearPinnedConnection(this, finalOptions);
+
         // release the server session back to the pool
         this.sessionPool.release(this.serverSession);
         this[kServerSession] = undefined;
@@ -245,6 +309,34 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
     }
   }
 
+  /**
+   * Advances the clusterTime for a ClientSession to the provided clusterTime of another ClientSession
+   *
+   * @param clusterTime - the $clusterTime returned by the server from another session in the form of a document containing the `BSON.Timestamp` clusterTime and signature
+   */
+  advanceClusterTime(clusterTime: ClusterTime): void {
+    if (!clusterTime || typeof clusterTime !== 'object') {
+      throw new MongoInvalidArgumentError('input cluster time must be an object');
+    }
+    if (!clusterTime.clusterTime || clusterTime.clusterTime._bsontype !== 'Timestamp') {
+      throw new MongoInvalidArgumentError(
+        'input cluster time "clusterTime" property must be a valid BSON Timestamp'
+      );
+    }
+    if (
+      !clusterTime.signature ||
+      clusterTime.signature.hash?._bsontype !== 'Binary' ||
+      (typeof clusterTime.signature.keyId !== 'number' &&
+        clusterTime.signature.keyId?._bsontype !== 'Long') // apparently we decode the key to number?
+    ) {
+      throw new MongoInvalidArgumentError(
+        'input cluster time must have a valid "signature" property with BSON Binary hash and BSON Long keyId'
+      );
+    }
+
+    _advanceClusterTime(this, clusterTime);
+  }
+
   /**
    * Used to determine if this session equals another
    *
@@ -282,12 +374,16 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
    */
   startTransaction(options?: TransactionOptions): void {
     if (this[kSnapshotEnabled]) {
-      throw new MongoDriverError('Transactions are not allowed with snapshot sessions');
+      throw new MongoCompatibilityError('Transactions are not allowed with snapshot sessions');
     }
 
     assertAlive(this);
     if (this.inTransaction()) {
-      throw new MongoDriverError('Transaction already in progress');
+      throw new MongoTransactionError('Transaction already in progress');
+    }
+
+    if (this.isPinned && this.transaction.isCommitted) {
+      this.unpin();
     }
 
     const topologyMaxWireVersion = maxWireVersion(this.topology);
@@ -296,7 +392,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
       topologyMaxWireVersion != null &&
       topologyMaxWireVersion < minWireVersionForShardedTransactions
     ) {
-      throw new MongoDriverError(
+      throw new MongoCompatibilityError(
         'Transactions are not supported on sharded clusters in MongoDB < 4.2.'
       );
     }
@@ -349,7 +445,7 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
    * This is here to ensure that ClientSession is never serialized to BSON.
    */
   toBSON(): never {
-    throw new MongoDriverError('ClientSession cannot be serialized to BSON.');
+    throw new MongoRuntimeError('ClientSession cannot be serialized to BSON.');
   }
 
   /**
@@ -397,6 +493,47 @@ function isUnknownTransactionCommitResult(err: MongoError) {
   );
 }
 
+export function maybeClearPinnedConnection(
+  session: ClientSession,
+  options?: EndSessionOptions
+): void {
+  // unpin a connection if it has been pinned
+  const conn = session[kPinnedConnection];
+  const error = options?.error;
+
+  if (
+    session.inTransaction() &&
+    error &&
+    error instanceof MongoError &&
+    error.hasErrorLabel('TransientTransactionError')
+  ) {
+    return;
+  }
+
+  // NOTE: the spec talks about what to do on a network error only, but the tests seem to
+  //       to validate that we don't unpin on _all_ errors?
+  if (conn) {
+    const servers = Array.from(session.topology.s.servers.values());
+    const loadBalancer = servers[0];
+
+    if (options?.error == null || options?.force) {
+      loadBalancer.s.pool.checkIn(conn);
+      conn.emit(
+        Connection.UNPINNED,
+        session.transaction.state !== TxnState.NO_TRANSACTION
+          ? ConnectionPoolMetrics.TXN
+          : ConnectionPoolMetrics.CURSOR
+      );
+
+      if (options?.forceClear) {
+        loadBalancer.s.pool.clear(conn.serviceId);
+      }
+    }
+
+    session[kPinnedConnection] = undefined;
+  }
+}
+
 function isMaxTimeMSExpiredError(err: MongoError) {
   if (err == null || !(err instanceof MongoServerError)) {
     return false;
@@ -461,7 +598,9 @@ function attemptTransaction<TSchema>(
 
   if (!isPromiseLike(promise)) {
     session.abortTransaction();
-    throw new MongoDriverError('Function provided to `withTransaction` must return a Promise');
+    throw new MongoInvalidArgumentError(
+      'Function provided to `withTransaction` must return a Promise'
+    );
   }
 
   return promise.then(
@@ -508,7 +647,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
   const txnState = session.transaction.state;
 
   if (txnState === TxnState.NO_TRANSACTION) {
-    callback(new MongoDriverError('No transaction started'));
+    callback(new MongoTransactionError('No transaction started'));
     return;
   }
 
@@ -525,7 +664,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
 
     if (txnState === TxnState.TRANSACTION_ABORTED) {
       callback(
-        new MongoDriverError('Cannot call commitTransaction after calling abortTransaction')
+        new MongoTransactionError('Cannot call commitTransaction after calling abortTransaction')
       );
       return;
     }
@@ -538,7 +677,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
     }
 
     if (txnState === TxnState.TRANSACTION_ABORTED) {
-      callback(new MongoDriverError('Cannot call abortTransaction twice'));
+      callback(new MongoTransactionError('Cannot call abortTransaction twice'));
       return;
     }
 
@@ -547,7 +686,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
       txnState === TxnState.TRANSACTION_COMMITTED_EMPTY
     ) {
       callback(
-        new MongoDriverError('Cannot call abortTransaction after calling commitTransaction')
+        new MongoTransactionError('Cannot call abortTransaction after calling commitTransaction')
       );
       return;
     }
@@ -579,6 +718,10 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
   function commandHandler(e?: MongoError, r?: Document) {
     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();
     }
@@ -595,12 +738,13 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
           e.addErrorLabel('UnknownTransactionCommitResult');
 
           // per txns spec, must unpin session in this case
-          session.transaction.unpinServer();
+          session.unpin({ error: e });
         }
       } else if (e.hasErrorLabel('TransientTransactionError')) {
-        session.transaction.unpinServer();
+        session.unpin({ error: e });
       }
     }
+
     callback(e, r);
   }
 
@@ -614,14 +758,20 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
     session.topology,
     new RunAdminCommandOperation(undefined, command, {
       session,
-      readPreference: ReadPreference.primary
+      readPreference: ReadPreference.primary,
+      bypassPinningCheck: true
     }),
     (err, reply) => {
+      if (command.abortTransaction) {
+        // always unpin on abort regardless of command outcome
+        session.unpin();
+      }
+
       if (err && isRetryableError(err as MongoError)) {
         // SPEC-1185: apply majority write concern when retrying commitTransaction
         if (command.commitTransaction) {
           // per txns spec, must unpin session in this case
-          session.transaction.unpinServer();
+          session.unpin({ force: true });
 
           command.writeConcern = Object.assign({ wtimeout: 10000 }, command.writeConcern, {
             w: 'majority'
@@ -632,7 +782,8 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
           session.topology,
           new RunAdminCommandOperation(undefined, command, {
             session,
-            readPreference: ReadPreference.primary
+            readPreference: ReadPreference.primary,
+            bypassPinningCheck: true
           }),
           (_err, _reply) => commandHandler(_err as MongoError, _reply)
         );
@@ -692,7 +843,7 @@ export class ServerSessionPool {
 
   constructor(topology: Topology) {
     if (topology == null) {
-      throw new MongoDriverError('ServerSessionPool requires a topology');
+      throw new MongoRuntimeError('ServerSessionPool requires a topology');
     }
 
     this.topology = topology;
@@ -731,7 +882,7 @@ export class ServerSessionPool {
 
     while (this.sessions.length) {
       const session = this.sessions.shift();
-      if (session && !session.hasTimedOut(sessionTimeoutMinutes)) {
+      if (session && (this.topology.loadBalanced || !session.hasTimedOut(sessionTimeoutMinutes))) {
         return session;
       }
     }
@@ -748,6 +899,11 @@ export class ServerSessionPool {
    */
   release(session: ServerSession): void {
     const sessionTimeoutMinutes = this.topology.logicalSessionTimeoutMinutes;
+
+    if (this.topology.loadBalanced && !sessionTimeoutMinutes) {
+      this.sessions.unshift(session);
+    }
+
     if (!sessionTimeoutMinutes) {
       return;
     }
@@ -805,19 +961,19 @@ export function applySession(
 ): MongoDriverError | undefined {
   // TODO: merge this with `assertAlive`, did not want to throw a try/catch here
   if (session.hasEnded) {
-    return new MongoDriverError('Attempted to use a session that has ended');
+    return new MongoExpiredSessionError();
   }
 
   const serverSession = session.serverSession;
   if (serverSession == null) {
-    return new MongoDriverError('Unable to acquire server session');
+    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 (session && session.explicit) {
-      return new MongoDriverError('Cannot have explicit session with unacknowledged writes');
+      return new MongoAPIError('Cannot have explicit session with unacknowledged writes');
     }
     return;
   }
@@ -848,7 +1004,7 @@ export function applySession(
       Object.assign(command.readConcern, { afterClusterTime: session.operationTime });
     } else if (session[kSnapshotEnabled]) {
       command.readConcern = command.readConcern || { level: ReadConcernLevel.snapshot };
-      if (session[kSnapshotTime] !== undefined) {
+      if (session[kSnapshotTime] != null) {
         Object.assign(command.readConcern, { atClusterTime: session[kSnapshotTime] });
       }
     }
@@ -880,7 +1036,7 @@ export function applySession(
 
 export function updateSessionFromResponse(session: ClientSession, document: Document): void {
   if (document.$clusterTime) {
-    resolveClusterTime(session, document.$clusterTime);
+    _advanceClusterTime(session, document.$clusterTime);
   }
 
   if (document.operationTime && session && session.supports.causalConsistency) {
@@ -891,11 +1047,12 @@ export function updateSessionFromResponse(session: ClientSession, document: Docu
     session.transaction._recoveryToken = document.recoveryToken;
   }
 
-  if (
-    document.cursor?.atClusterTime &&
-    session?.[kSnapshotEnabled] &&
-    session[kSnapshotTime] === undefined
-  ) {
-    session[kSnapshotTime] = document.cursor.atClusterTime;
+  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;
+    if (atClusterTime) {
+      session[kSnapshotTime] = atClusterTime;
+    }
   }
 }

package/src/sort.ts

@@ -1,4 +1,4 @@
-import { MongoDriverError } from './error';
+import { MongoInvalidArgumentError } from './error';
 
 /** @public */
 export type SortDirection =
@@ -45,13 +45,13 @@ function prepareDirection(direction: any = 1): SortDirectionForCmd {
     case '-1':
       return -1;
     default:
-      throw new MongoDriverError(`Invalid sort direction: ${JSON.stringify(direction)}`);
+      throw new MongoInvalidArgumentError(`Invalid sort direction: ${JSON.stringify(direction)}`);
   }
 }
 
 /** @internal */
 function isMeta(t: SortDirection): t is { $meta: string } {
-  return typeof t === 'object' && t !== null && '$meta' in t && typeof t.$meta === 'string';
+  return typeof t === 'object' && t != null && '$meta' in t && typeof t.$meta === 'string';
 }
 
 /** @internal */
@@ -118,7 +118,9 @@ export function formatSort(
   if (sort == null) return undefined;
   if (typeof sort === 'string') return new Map([[sort, prepareDirection(direction)]]);
   if (typeof sort !== 'object') {
-    throw new MongoDriverError(`Invalid sort format: ${JSON.stringify(sort)}`);
+    throw new MongoInvalidArgumentError(
+      `Invalid sort format: ${JSON.stringify(sort)} Sort must be a valid object`
+    );
   }
   if (!Array.isArray(sort)) {
     return isMap(sort) ? mapToMap(sort) : Object.keys(sort).length ? objectToMap(sort) : undefined;

package/src/transactions.ts

@@ -1,5 +1,5 @@
 import { ReadPreference } from './read_preference';
-import { MongoDriverError } from './error';
+import { MongoRuntimeError, MongoTransactionError } from './error';
 import { ReadConcern } from './read_concern';
 import { WriteConcern } from './write_concern';
 import type { Server } from './sdam/server';
@@ -45,6 +45,17 @@ const stateMachine: { [state in TxnState]: TxnState[] } = {
   ]
 };
 
+const ACTIVE_STATES: Set<TxnState> = new Set([
+  TxnState.STARTING_TRANSACTION,
+  TxnState.TRANSACTION_IN_PROGRESS
+]);
+
+const COMMITTED_STATES: Set<TxnState> = new Set([
+  TxnState.TRANSACTION_COMMITTED,
+  TxnState.TRANSACTION_COMMITTED_EMPTY,
+  TxnState.TRANSACTION_ABORTED
+]);
+
 /**
  * Configuration options for a transaction.
  * @public
@@ -77,14 +88,13 @@ export class Transaction {
   /** Create a transaction @internal */
   constructor(options?: TransactionOptions) {
     options = options ?? {};
-
     this.state = TxnState.NO_TRANSACTION;
     this.options = {};
 
     const writeConcern = WriteConcern.fromOptions(options);
     if (writeConcern) {
       if (writeConcern.w === 0) {
-        throw new MongoDriverError('Transactions do not support unacknowledged write concern');
+        throw new MongoTransactionError('Transactions do not support unacknowledged write concern');
       }
 
       this.options.writeConcern = writeConcern;
@@ -129,13 +139,12 @@ export class Transaction {
    * @returns Whether this session is presently in a transaction
    */
   get isActive(): boolean {
-    const activeStates: TxnState[] = [
-      TxnState.STARTING_TRANSACTION,
-      TxnState.TRANSACTION_IN_PROGRESS
-    ];
-    return activeStates.includes(this.state);
+    return ACTIVE_STATES.has(this.state);
   }
 
+  get isCommitted(): boolean {
+    return COMMITTED_STATES.has(this.state);
+  }
   /**
    * Transition the transaction in the state machine
    * @internal
@@ -155,7 +164,7 @@ export class Transaction {
       return;
     }
 
-    throw new MongoDriverError(
+    throw new MongoRuntimeError(
       `Attempted illegal state transition from [${this.state}] to [${nextState}]`
     );
   }