mongodb 6.8.2 → 6.9.0

package/src/operations/execute_operation.ts

@@ -24,16 +24,15 @@ import {
 } from '../sdam/server_selection';
 import type { Topology } from '../sdam/topology';
 import type { ClientSession } from '../sessions';
-import { squashError, supportsRetryableWrites } from '../utils';
+import { supportsRetryableWrites } from '../utils';
 import { AbstractOperation, Aspect } from './operation';
 
 const MMAPv1_RETRY_WRITES_ERROR_CODE = MONGODB_ERROR_CODES.IllegalOperation;
 const MMAPv1_RETRY_WRITES_ERROR_MESSAGE =
   'This MongoDB deployment does not support retryable writes. Please add retryWrites=false to your connection string.';
 
-type ResultTypeFromOperation<TOperation> = TOperation extends AbstractOperation<infer K>
-  ? K
-  : never;
+type ResultTypeFromOperation<TOperation> =
+  TOperation extends AbstractOperation<infer K> ? K : never;
 
 /**
  * Executes the given operation with provided arguments.
@@ -45,10 +44,9 @@ type ResultTypeFromOperation<TOperation> = TOperation extends AbstractOperation<
  * not provided.
  *
  * The expectation is that this function:
- * - Connects the MongoClient if it has not already been connected
+ * - Connects the MongoClient if it has not already been connected, see {@link autoConnect}
  * - Creates a session if none is provided and cleans up the session it creates
- * - Selects a server based on readPreference or various factors
- * - Retries an operation if it fails for certain errors, see {@link retryOperation}
+ * - Tries an operation and retries under certain conditions, see {@link tryOperation}
  *
  * @typeParam T - The operation's type
  * @typeParam TResult - The type of the operation's result, calculated from T
@@ -65,23 +63,7 @@ export async function executeOperation<
     throw new MongoRuntimeError('This method requires a valid operation instance');
   }
 
-  if (client.topology == null) {
-    // Auto connect on operation
-    if (client.s.hasBeenClosed) {
-      throw new MongoNotConnectedError('Client must be connected before running operations');
-    }
-    client.s.options[Symbol.for('@@mdb.skipPingOnConnect')] = true;
-    try {
-      await client.connect();
-    } finally {
-      delete client.s.options[Symbol.for('@@mdb.skipPingOnConnect')];
-    }
-  }
-
-  const { topology } = client;
-  if (topology == null) {
-    throw new MongoRuntimeError('client.connect did not create a topology but also did not throw');
-  }
+  const topology = await autoConnect(client);
 
   // The driver sessions spec mandates that we implicitly create sessions for operations
   // that are not explicitly provided with a session.
@@ -108,7 +90,6 @@ export async function executeOperation<
   const inTransaction = !!session?.inTransaction();
 
   const hasReadAspect = operation.hasAspect(Aspect.READ_OPERATION);
-  const hasWriteAspect = operation.hasAspect(Aspect.WRITE_OPERATION);
 
   if (
     inTransaction &&
@@ -124,6 +105,73 @@ export async function executeOperation<
     session.unpin();
   }
 
+  try {
+    return await tryOperation(operation, {
+      topology,
+      session,
+      readPreference
+    });
+  } finally {
+    if (session?.owner != null && session.owner === owner) {
+      await session.endSession();
+    }
+  }
+}
+
+/**
+ * Connects a client if it has not yet been connected
+ * @internal
+ */
+async function autoConnect(client: MongoClient): Promise<Topology> {
+  if (client.topology == null) {
+    if (client.s.hasBeenClosed) {
+      throw new MongoNotConnectedError('Client must be connected before running operations');
+    }
+    client.s.options[Symbol.for('@@mdb.skipPingOnConnect')] = true;
+    try {
+      await client.connect();
+      if (client.topology == null) {
+        throw new MongoRuntimeError(
+          'client.connect did not create a topology but also did not throw'
+        );
+      }
+      return client.topology;
+    } finally {
+      delete client.s.options[Symbol.for('@@mdb.skipPingOnConnect')];
+    }
+  }
+  return client.topology;
+}
+
+/** @internal */
+type RetryOptions = {
+  session: ClientSession | undefined;
+  readPreference: ReadPreference;
+  topology: Topology;
+};
+
+/**
+ * Executes an operation and retries as appropriate
+ * @internal
+ *
+ * @remarks
+ * Implements behaviour described in [Retryable Reads](https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.md) and [Retryable
+ * Writes](https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.md) specification
+ *
+ * This function:
+ * - performs initial server selection
+ * - attempts to execute an operation
+ * - retries the operation if it meets the criteria for a retryable read or a retryable write
+ *
+ * @typeParam T - The operation's type
+ * @typeParam TResult - The type of the operation's result, calculated from T
+ *
+ * @param operation - The operation to execute
+ * */
+async function tryOperation<
+  T extends AbstractOperation<TResult>,
+  TResult = ResultTypeFromOperation<T>
+>(operation: T, { topology, session, readPreference }: RetryOptions): Promise<TResult> {
   let selector: ReadPreference | ServerSelector;
 
   if (operation.hasAspect(Aspect.MUST_SELECT_SAME_SERVER)) {
@@ -139,30 +187,14 @@ export async function executeOperation<
     selector = readPreference;
   }
 
-  const server = await topology.selectServer(selector, {
+  let server = await topology.selectServer(selector, {
     session,
     operationName: operation.commandName
   });
 
-  if (session == null) {
-    // No session also means it is not retryable, early exit
-    return await operation.execute(server, undefined);
-  }
-
-  if (!operation.hasAspect(Aspect.RETRYABLE)) {
-    // non-retryable operation, early exit
-    try {
-      return await operation.execute(server, session);
-    } finally {
-      if (session?.owner != null && session.owner === owner) {
-        try {
-          await session.endSession();
-        } catch (error) {
-          squashError(error);
-        }
-      }
-    }
-  }
+  const hasReadAspect = operation.hasAspect(Aspect.READ_OPERATION);
+  const hasWriteAspect = operation.hasAspect(Aspect.WRITE_OPERATION);
+  const inTransaction = session?.inTransaction() ?? false;
 
   const willRetryRead = topology.s.options.retryReads && !inTransaction && operation.canRetryRead;
 
@@ -172,105 +204,79 @@ export async function executeOperation<
     supportsRetryableWrites(server) &&
     operation.canRetryWrite;
 
-  const willRetry = (hasReadAspect && willRetryRead) || (hasWriteAspect && willRetryWrite);
+  const willRetry =
+    operation.hasAspect(Aspect.RETRYABLE) &&
+    session != null &&
+    ((hasReadAspect && willRetryRead) || (hasWriteAspect && willRetryWrite));
 
-  if (hasWriteAspect && willRetryWrite) {
+  if (hasWriteAspect && willRetryWrite && session != null) {
     operation.options.willRetryWrite = true;
     session.incrementTransactionNumber();
   }
 
-  try {
-    return await operation.execute(server, session);
-  } catch (operationError) {
-    if (willRetry && operationError instanceof MongoError) {
-      return await retryOperation(operation, operationError, {
-        session,
-        topology,
-        selector,
-        previousServer: server.description
-      });
-    }
-    throw operationError;
-  } finally {
-    if (session?.owner != null && session.owner === owner) {
-      try {
-        await session.endSession();
-      } catch (error) {
-        squashError(error);
-      }
-    }
-  }
-}
+  // TODO(NODE-6231): implement infinite retry within CSOT timeout here
+  const maxTries = willRetry ? 2 : 1;
+  let previousOperationError: MongoError | undefined;
+  let previousServer: ServerDescription | undefined;
 
-/** @internal */
-type RetryOptions = {
-  session: ClientSession;
-  topology: Topology;
-  selector: ReadPreference | ServerSelector;
-  previousServer: ServerDescription;
-};
+  // TODO(NODE-6231): implement infinite retry within CSOT timeout here
+  for (let tries = 0; tries < maxTries; tries++) {
+    if (previousOperationError) {
+      if (hasWriteAspect && previousOperationError.code === MMAPv1_RETRY_WRITES_ERROR_CODE) {
+        throw new MongoServerError({
+          message: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
+          errmsg: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
+          originalError: previousOperationError
+        });
+      }
 
-async function retryOperation<
-  T extends AbstractOperation<TResult>,
-  TResult = ResultTypeFromOperation<T>
->(
-  operation: T,
-  originalError: MongoError,
-  { session, topology, selector, previousServer }: RetryOptions
-): Promise<TResult> {
-  const isWriteOperation = operation.hasAspect(Aspect.WRITE_OPERATION);
-  const isReadOperation = operation.hasAspect(Aspect.READ_OPERATION);
+      if (hasWriteAspect && !isRetryableWriteError(previousOperationError))
+        throw previousOperationError;
 
-  if (isWriteOperation && originalError.code === MMAPv1_RETRY_WRITES_ERROR_CODE) {
-    throw new MongoServerError({
-      message: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
-      errmsg: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
-      originalError
-    });
-  }
+      if (hasReadAspect && !isRetryableReadError(previousOperationError))
+        throw previousOperationError;
 
-  if (isWriteOperation && !isRetryableWriteError(originalError)) {
-    throw originalError;
-  }
-
-  if (isReadOperation && !isRetryableReadError(originalError)) {
-    throw originalError;
-  }
+      if (
+        previousOperationError instanceof MongoNetworkError &&
+        operation.hasAspect(Aspect.CURSOR_CREATING) &&
+        session != null &&
+        session.isPinned &&
+        !session.inTransaction()
+      ) {
+        session.unpin({ force: true, forceClear: true });
+      }
 
-  if (
-    originalError instanceof MongoNetworkError &&
-    session.isPinned &&
-    !session.inTransaction() &&
-    operation.hasAspect(Aspect.CURSOR_CREATING)
-  ) {
-    // If we have a cursor and the initial command fails with a network error,
-    // we can retry it on another connection. So we need to check it back in, clear the
-    // pool for the service id, and retry again.
-    session.unpin({ force: true, forceClear: true });
-  }
+      server = await topology.selectServer(selector, {
+        session,
+        operationName: operation.commandName,
+        previousServer
+      });
 
-  // select a new server, and attempt to retry the operation
-  const server = await topology.selectServer(selector, {
-    session,
-    operationName: operation.commandName,
-    previousServer
-  });
+      if (hasWriteAspect && !supportsRetryableWrites(server)) {
+        throw new MongoUnexpectedServerResponseError(
+          'Selected server does not support retryable writes'
+        );
+      }
+    }
 
-  if (isWriteOperation && !supportsRetryableWrites(server)) {
-    throw new MongoUnexpectedServerResponseError(
-      'Selected server does not support retryable writes'
-    );
-  }
+    try {
+      return await operation.execute(server, session);
+    } catch (operationError) {
+      if (!(operationError instanceof MongoError)) throw operationError;
 
-  try {
-    return await operation.execute(server, session);
-  } catch (retryError) {
-    if (
-      retryError instanceof MongoError &&
-      retryError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)
-    ) {
-      throw originalError;
+      if (
+        previousOperationError != null &&
+        operationError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)
+      ) {
+        throw previousOperationError;
+      }
+      previousServer = server.description;
+      previousOperationError = operationError;
     }
-    throw retryError;
   }
+
+  throw (
+    previousOperationError ??
+    new MongoRuntimeError('Tried to propagate retryability error, but no error was found.')
+  );
 }

package/src/operations/find_and_modify.ts

@@ -192,12 +192,7 @@ export class FindAndModifyOperation extends CommandOperation<Document> {
       ...this.cmdBase
     };
 
-    // Have we specified collation
-    try {
-      decorateWithCollation(cmd, coll, options);
-    } catch (err) {
-      return err;
-    }
+    decorateWithCollation(cmd, coll, options);
 
     if (options.hint) {
       // TODO: once this method becomes a CommandOperation we will have the server
@@ -214,7 +209,7 @@ export class FindAndModifyOperation extends CommandOperation<Document> {
 
     // Execute the command
     const result = await super.executeCommand(server, session, cmd);
-    return options.includeResultMetadata ? result : result.value ?? null;
+    return options.includeResultMetadata ? result : (result.value ?? null);
   }
 }
 

package/src/operations/insert.ts

@@ -5,8 +5,7 @@ import { MongoInvalidArgumentError, MongoServerError } from '../error';
 import type { InferIdType } from '../mongo_types';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
-import type { MongoDBNamespace } from '../utils';
-import { maybeAddIdToDocuments } from '../utils';
+import { maybeAddIdToDocuments, type MongoDBNamespace } from '../utils';
 import { WriteConcern } from '../write_concern';
 import { BulkWriteOperation } from './bulk_write';
 import { CommandOperation, type CommandOperationOptions } from './command';
@@ -104,9 +103,9 @@ export interface InsertManyResult<TSchema = Document> {
 export class InsertManyOperation extends AbstractOperation<InsertManyResult> {
   override options: BulkWriteOptions;
   collection: Collection;
-  docs: Document[];
+  docs: ReadonlyArray<Document>;
 
-  constructor(collection: Collection, docs: Document[], options: BulkWriteOptions) {
+  constructor(collection: Collection, docs: ReadonlyArray<Document>, options: BulkWriteOptions) {
     super(options);
 
     if (!Array.isArray(docs)) {

package/src/operations/operation.ts

@@ -17,11 +17,6 @@ export const Aspect = {
 /** @public */
 export type Hint = string | Document;
 
-// eslint-disable-next-line @typescript-eslint/ban-types
-export interface OperationConstructor extends Function {
-  aspects?: Set<symbol>;
-}
-
 /** @public */
 export interface OperationOptions extends BSONSerializeOptions {
   /** Specify ClientSession for this command */
@@ -63,10 +58,12 @@ export abstract class AbstractOperation<TResult = any> {
 
   [kSession]: ClientSession | undefined;
 
+  static aspects?: Set<symbol>;
+
   constructor(options: OperationOptions = {}) {
     this.readPreference = this.hasAspect(Aspect.WRITE_OPERATION)
       ? ReadPreference.primary
-      : ReadPreference.fromOptions(options) ?? ReadPreference.primary;
+      : (ReadPreference.fromOptions(options) ?? ReadPreference.primary);
 
     // Pull the BSON serialize options from the already-resolved options
     this.bsonOptions = resolveBSONOptions(options);
@@ -85,7 +82,7 @@ export abstract class AbstractOperation<TResult = any> {
   abstract execute(server: Server, session: ClientSession | undefined): Promise<TResult>;
 
   hasAspect(aspect: symbol): boolean {
-    const ctor = this.constructor as OperationConstructor;
+    const ctor = this.constructor as { aspects?: Set<symbol> };
     if (ctor.aspects == null) {
       return false;
     }
@@ -102,16 +99,16 @@ export abstract class AbstractOperation<TResult = any> {
   }
 
   get canRetryRead(): boolean {
-    return true;
+    return this.hasAspect(Aspect.RETRYABLE) && this.hasAspect(Aspect.READ_OPERATION);
   }
 
   get canRetryWrite(): boolean {
-    return true;
+    return this.hasAspect(Aspect.RETRYABLE) && this.hasAspect(Aspect.WRITE_OPERATION);
   }
 }
 
 export function defineAspects(
-  operation: OperationConstructor,
+  operation: { aspects?: Set<symbol> },
   aspects: symbol | symbol[] | Set<symbol>
 ): Set<symbol> {
   if (!Array.isArray(aspects) && !(aspects instanceof Set)) {

package/src/operations/search_indexes/drop.ts

@@ -8,7 +8,10 @@ import { AbstractOperation } from '../operation';
 
 /** @internal */
 export class DropSearchIndexOperation extends AbstractOperation<void> {
-  constructor(private readonly collection: Collection, private readonly name: string) {
+  constructor(
+    private readonly collection: Collection,
+    private readonly name: string
+  ) {
     super();
   }
 

package/src/resource_management.ts

@@ -0,0 +1,74 @@
+/**
+ * @public
+ */
+export interface AsyncDisposable {
+  /**
+   * @beta
+   * @experimental
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+
+  /**
+   * @internal
+   *
+   * A method that wraps disposal semantics for a given resource in the class.
+   */
+  asyncDispose(): Promise<void>;
+}
+
+/** @internal */
+export function configureResourceManagement(target: AsyncDisposable) {
+  Symbol.asyncDispose &&
+    Object.defineProperty(target, Symbol.asyncDispose, {
+      value: async function asyncDispose(this: AsyncDisposable) {
+        await this.asyncDispose();
+      },
+      enumerable: false,
+      configurable: true,
+      writable: true
+    });
+}
+
+/**
+ * @beta
+ * @experimental
+ *
+ * Attaches `Symbol.asyncDispose` methods to the MongoClient, Cursors, sessions and change streams
+ * if Symbol.asyncDispose is defined.
+ *
+ * It's usually not necessary to call this method - the driver attempts to attach these methods
+ * itself when its loaded.  However, sometimes the driver may be loaded before `Symbol.asyncDispose`
+ * is defined, in which case it is necessary to call this method directly.  This can happen if the
+ * application is polyfilling `Symbol.asyncDispose`.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { configureExplicitResourceManagement, MongoClient } from 'mongodb/lib/beta';
+ *
+ * Symbol.asyncDispose ??= Symbol('dispose');
+ * load();
+ *
+ * await using client = new MongoClient(...);
+ * ```
+ */
+export function configureExplicitResourceManagement() {
+  // We must import lazily here, because there's a circular dependency between the resource management
+  // file and each resources' file.  We could move `configureResourceManagement` to a separate
+  // function, but keeping all resource-management related code together seemed preferable and I chose
+  // lazy requiring of resources instead.
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { MongoClient } = require('./mongo_client');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { ClientSession } = require('./sessions');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { AbstractCursor } = require('./cursor/abstract_cursor');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { ChangeStream } = require('./change_stream');
+
+  configureResourceManagement(MongoClient.prototype);
+  configureResourceManagement(ClientSession.prototype);
+  configureResourceManagement(AbstractCursor.prototype);
+  configureResourceManagement(ChangeStream.prototype);
+}

package/src/sdam/monitor.ts

@@ -308,7 +308,7 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
     // duration
     const duration =
       isAwaitable && monitor.rttPinger
-        ? monitor.rttPinger.latestRtt ?? calculateDurationInMs(start)
+        ? (monitor.rttPinger.latestRtt ?? calculateDurationInMs(start))
         : calculateDurationInMs(start);
 
     monitor.addRttSample(duration);
@@ -378,7 +378,7 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
     awaited = false;
     connection
       .command(ns('admin.$cmd'), cmd, options)
-      // eslint-disable-next-line github/no-then
+
       .then(onHeartbeatSucceeded, onHeartbeatFailed);
 
     return;
@@ -397,7 +397,6 @@ function checkServer(monitor: Monitor, callback: Callback<Document | null>) {
       connection.destroy();
       throw error;
     }
-    // eslint-disable-next-line github/no-then
   })().then(
     connection => {
       if (isInCloseState(monitor)) {
@@ -547,7 +546,6 @@ export class RTTPinger {
 
     const connection = this.connection;
     if (connection == null) {
-      // eslint-disable-next-line github/no-then
       connect(this.monitor.connectOptions).then(
         connection => {
           this.measureAndReschedule(start, connection);
@@ -561,7 +559,7 @@ export class RTTPinger {
 
     const commandName =
       connection.serverApi?.version || connection.helloOk ? 'hello' : LEGACY_HELLO_COMMAND;
-    // eslint-disable-next-line github/no-then
+
     connection.command(ns('admin.$cmd'), { [commandName]: 1 }, undefined).then(
       () => this.measureAndReschedule(start),
       () => {

package/src/sdam/server.ts

@@ -453,7 +453,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
     } else {
       if (
         (isRetryableWritesEnabled(this.topology) || isTransactionCommand(cmd)) &&
-        needsRetryableWriteLabel(error, maxWireVersion(this)) &&
+        needsRetryableWriteLabel(error, maxWireVersion(this), this.description.type) &&
         !inActiveTransaction(session, cmd)
       ) {
         error.addErrorLabel(MongoErrorLabel.RetryableWriteError);

package/src/sdam/server_description.ts

@@ -1,8 +1,7 @@
 import { type Document, Long, type ObjectId } from '../bson';
 import { type MongoError, MongoRuntimeError } from '../error';
 import { arrayStrictEqual, compareObjectId, errorStrictEqual, HostAddress, now } from '../utils';
-import type { ClusterTime } from './common';
-import { ServerType } from './common';
+import { type ClusterTime, ServerType } from './common';
 
 const WRITABLE_SERVER_TYPES = new Set<ServerType>([
   ServerType.RSPrimary,
@@ -262,15 +261,15 @@ export function compareTopologyVersion(
     typeof currentTv.counter === 'bigint'
       ? Long.fromBigInt(currentTv.counter)
       : Long.isLong(currentTv.counter)
-      ? currentTv.counter
-      : Long.fromNumber(currentTv.counter);
+        ? currentTv.counter
+        : Long.fromNumber(currentTv.counter);
 
   const newCounter =
     typeof newTv.counter === 'bigint'
       ? Long.fromBigInt(newTv.counter)
       : Long.isLong(newTv.counter)
-      ? newTv.counter
-      : Long.fromNumber(newTv.counter);
+        ? newTv.counter
+        : Long.fromNumber(newTv.counter);
 
   return currentCounter.compare(newCounter);
 }

package/src/sdam/srv_polling.ts

@@ -95,7 +95,6 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
     }
 
     this._timeout = setTimeout(() => {
-      // eslint-disable-next-line github/no-then
       this._poll().then(undefined, squashError);
     }, this.intervalMS);
   }
@@ -117,7 +116,7 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
 
     try {
       srvRecords = await dns.promises.resolveSrv(this.srvAddress);
-    } catch (dnsError) {
+    } catch {
       this.failure();
       return;
     }