mongodb 7.1.0 → 7.2.0

package/src/operations/execute_operation.ts

@@ -1,3 +1,5 @@
+import { setTimeout } from 'timers/promises';
+
 import { MIN_SUPPORTED_SNAPSHOT_READS_WIRE_VERSION } from '../cmap/wire_protocol/constants';
 import {
   isRetryableReadError,
@@ -17,6 +19,7 @@ import {
 } from '../error';
 import type { MongoClient } from '../mongo_client';
 import { ReadPreference } from '../read_preference';
+import { TopologyType } from '../sdam/common';
 import {
   DeprioritizedServers,
   sameServerSelector,
@@ -29,6 +32,7 @@ import { TimeoutContext } from '../timeout';
 import { abortable, maxWireVersion, supportsRetryableWrites } from '../utils';
 import { AggregateOperation } from './aggregate';
 import { AbstractOperation, Aspect } from './operation';
+import { RunCommandOperation } from './run_command';
 
 const MMAPv1_RETRY_WRITES_ERROR_CODE = MONGODB_ERROR_CODES.IllegalOperation;
 const MMAPv1_RETRY_WRITES_ERROR_MESSAGE =
@@ -50,7 +54,7 @@ type ResultTypeFromOperation<TOperation extends AbstractOperation> = ReturnType<
  * The expectation is that this function:
  * - 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
- * - Tries an operation and retries under certain conditions, see {@link tryOperation}
+ * - Tries an operation and retries under certain conditions, see {@link executeOperationWithRetries}
  *
  * @typeParam T - The operation's type
  * @typeParam TResult - The type of the operation's result, calculated from T
@@ -120,7 +124,7 @@ export async function executeOperation<
   });
 
   try {
-    return await tryOperation(operation, {
+    return await executeOperationWithRetries(operation, {
       topology,
       timeoutContext,
       session,
@@ -165,6 +169,10 @@ type RetryOptions = {
   topology: Topology;
   timeoutContext: TimeoutContext;
 };
+/** @internal The base backoff duration in milliseconds */
+const BASE_BACKOFF_MS = 100;
+/** @internal The maximum backoff duration in milliseconds */
+const MAX_BACKOFF_MS = 10_000;
 
 /**
  * Executes an operation and retries as appropriate
@@ -183,8 +191,11 @@ type RetryOptions = {
  * @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 = ResultTypeFromOperation<T>>(
+ */
+async function executeOperationWithRetries<
+  T extends AbstractOperation,
+  TResult = ResultTypeFromOperation<T>
+>(
   operation: T,
   { topology, timeoutContext, session, readPreference }: RetryOptions
 ): Promise<TResult> {
@@ -233,33 +244,70 @@ async function tryOperation<T extends AbstractOperation, TResult = ResultTypeFro
     session.incrementTransactionNumber();
   }
 
-  const maxTries = willRetry ? (timeoutContext.csotEnabled() ? Infinity : 2) : 1;
-  let previousOperationError: MongoError | undefined;
   const deprioritizedServers = new DeprioritizedServers();
 
-  for (let tries = 0; tries < maxTries; tries++) {
-    if (previousOperationError) {
-      if (hasWriteAspect && previousOperationError.code === MMAPv1_RETRY_WRITES_ERROR_CODE) {
+  let maxAttempts =
+    typeof operation.maxAttempts === 'number'
+      ? operation.maxAttempts
+      : willRetry
+        ? timeoutContext.csotEnabled()
+          ? Infinity
+          : 2
+        : 1;
+
+  let error: MongoError | null = null;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    operation.attemptsMade = attempt + 1;
+    operation.server = server;
+
+    try {
+      try {
+        const result = await server.command(operation, timeoutContext);
+        return operation.handleOk(result);
+      } catch (error) {
+        return operation.handleError(error);
+      }
+    } catch (operationError) {
+      // Should never happen but if it does - propagate the error.
+      if (!(operationError instanceof MongoError)) throw operationError;
+
+      // Preserve the original error once a write has been performed.
+      // Only update to the latest error if no writes were performed.
+      if (error == null) {
+        error = operationError;
+      } else {
+        if (!operationError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)) {
+          error = operationError;
+        }
+      }
+
+      // Reset timeouts
+      timeoutContext.clear();
+
+      if (hasWriteAspect && operationError.code === MMAPv1_RETRY_WRITES_ERROR_CODE) {
         throw new MongoServerError({
           message: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
           errmsg: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
-          originalError: previousOperationError
+          originalError: operationError
         });
       }
 
-      if (operation.hasAspect(Aspect.COMMAND_BATCHING) && !operation.canRetryWrite) {
-        throw previousOperationError;
+      if (!canRetry(operation, operationError)) {
+        throw error;
       }
 
-      if (hasWriteAspect && !isRetryableWriteError(previousOperationError))
-        throw previousOperationError;
+      if (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)) {
+        const maxOverloadAttempts = topology.s.options.maxAdaptiveRetries + 1;
+        maxAttempts = Math.min(maxOverloadAttempts, operation.maxAttempts ?? maxOverloadAttempts);
+      }
 
-      if (hasReadAspect && !isRetryableReadError(previousOperationError)) {
-        throw previousOperationError;
+      if (attempt + 1 >= maxAttempts) {
+        throw error;
       }
 
       if (
-        previousOperationError instanceof MongoNetworkError &&
+        operationError instanceof MongoNetworkError &&
         operation.hasAspect(Aspect.CURSOR_CREATING) &&
         session != null &&
         session.isPinned &&
@@ -268,6 +316,35 @@ async function tryOperation<T extends AbstractOperation, TResult = ResultTypeFro
         session.unpin({ force: true, forceClear: true });
       }
 
+      if (
+        operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError) &&
+        operation.hasAspect(Aspect.CURSOR_CREATING) &&
+        session != null &&
+        session.isPinned &&
+        !session.inTransaction()
+      ) {
+        session.unpin({ force: true });
+      }
+
+      if (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)) {
+        const backoffMS = Math.random() * Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempt);
+
+        // if the backoff would exhaust the CSOT timeout, short-circuit.
+        if (timeoutContext.csotEnabled() && backoffMS > timeoutContext.remainingTimeMS) {
+          throw error;
+        }
+
+        await setTimeout(backoffMS);
+      }
+
+      if (
+        topology.description.type === TopologyType.Sharded ||
+        (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError) &&
+          topology.s.options.enableOverloadRetargeting)
+      ) {
+        deprioritizedServers.add(server.description);
+      }
+
       server = await topology.selectServer(selector, {
         session,
         operationName: operation.commandName,
@@ -275,45 +352,69 @@ async function tryOperation<T extends AbstractOperation, TResult = ResultTypeFro
         signal: operation.options.signal
       });
 
-      if (hasWriteAspect && !supportsRetryableWrites(server)) {
+      if (
+        hasWriteAspect &&
+        !supportsRetryableWrites(server) &&
+        !operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)
+      ) {
         throw new MongoUnexpectedServerResponseError(
           'Selected server does not support retryable writes'
         );
       }
-    }
-
-    operation.server = server;
 
-    try {
-      // If tries > 0 and we are command batching we need to reset the batch.
-      if (tries > 0 && operation.hasAspect(Aspect.COMMAND_BATCHING)) {
+      // Batched operations must reset the batch before retry,
+      // otherwise building a command will build the _next_ batch, not the current batch.
+      if (operation.hasAspect(Aspect.COMMAND_BATCHING)) {
         operation.resetBatch();
       }
+    }
+  }
 
-      try {
-        const result = await server.command(operation, timeoutContext);
-        return operation.handleOk(result);
-      } catch (error) {
-        return operation.handleError(error);
+  throw (
+    error ??
+    new MongoRuntimeError(
+      'Should never happen: operation execution loop terminated but no error was recorded.'
+    )
+  );
+
+  function canRetry(operation: AbstractOperation, error: MongoError) {
+    // SystemOverloadedError is retryable, but must respect retryReads/retryWrites settings
+    // Check topology options directly (not operation.canRetryRead/Write) because backpressure
+    // expands retry support beyond traditional retryable reads/writes
+    // NOTE: Unlike traditional retries, backpressure retries ARE allowed inside transactions
+    if (
+      error.hasErrorLabel(MongoErrorLabel.SystemOverloadedError) &&
+      error.hasErrorLabel(MongoErrorLabel.RetryableError)
+    ) {
+      // runCommand requires BOTH retryReads and retryWrites to be enabled (per spec step 2.4)
+      if (operation instanceof RunCommandOperation) {
+        return topology.s.options.retryReads && topology.s.options.retryWrites;
       }
-    } catch (operationError) {
-      if (!(operationError instanceof MongoError)) throw operationError;
-      if (
-        previousOperationError != null &&
-        operationError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)
-      ) {
-        throw previousOperationError;
+
+      // Write-stage aggregates ($out/$merge) require retryWrites
+      if (operation instanceof AggregateOperation && operation.hasWriteStage) {
+        return topology.s.options.retryWrites;
       }
-      deprioritizedServers.add(server.description);
-      previousOperationError = operationError;
 
-      // Reset timeouts
-      timeoutContext.clear();
+      // For other operations, check if retries are enabled based on operation type
+      const canRetryAsRead = hasReadAspect && topology.s.options.retryReads;
+      const canRetryAsWrite = hasWriteAspect && topology.s.options.retryWrites;
+      return canRetryAsRead || canRetryAsWrite;
     }
-  }
 
-  throw (
-    previousOperationError ??
-    new MongoRuntimeError('Tried to propagate retryability error, but no error was found.')
-  );
+    // run command is only retryable if we get retryable overload errors
+    if (operation instanceof RunCommandOperation) {
+      return false;
+    }
+
+    // batch operations are only retryable if the batch is retryable
+    if (operation.hasAspect(Aspect.COMMAND_BATCHING)) {
+      return operation.canRetryWrite && isRetryableWriteError(error);
+    }
+
+    return (
+      (hasWriteAspect && willRetryWrite && isRetryableWriteError(error)) ||
+      (hasReadAspect && willRetryRead && isRetryableReadError(error))
+    );
+  }
 }

package/src/operations/operation.ts

@@ -66,6 +66,12 @@ export abstract class AbstractOperation<TResult = any> {
   /** Specifies the time an operation will run until it throws a timeout error. */
   timeoutMS?: number;
 
+  /** Used by commitTransaction to share the retry budget across two executeOperation calls. */
+  maxAttempts?: number;
+
+  /** Tracks how many attempts were made in the last executeOperation call. */
+  attemptsMade: number;
+
   private _session: ClientSession | undefined;
 
   static aspects?: Set<symbol>;
@@ -82,6 +88,8 @@ export abstract class AbstractOperation<TResult = any> {
 
     this.options = options;
     this.bypassPinningCheck = !!options.bypassPinningCheck;
+
+    this.attemptsMade = 0;
   }
 
   /** Must match the first key of the command object sent to the server.

package/src/runtime_adapters.ts

@@ -0,0 +1,64 @@
+/* eslint-disable no-restricted-imports*/
+
+// We squash the restricted import errors here because we are using type-only imports, which
+// do not impact the driver's actual runtime dependencies.
+// We also allow restricted imports in this file, because we expect this file to be the only place actually importing restricted Node APIs.
+
+import type * as os from 'os';
+
+import { type MongoClientOptions } from './mongo_client';
+
+/**
+ * @internal
+ *
+ * This propery can be set on the global object to allow the driver to require otherwise blocked modules.
+ * This is used by our test suite to allow tests to access the `os` module without allowing user code to do so.
+ */
+export const ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME = 'allowedDriverRequire';
+
+/**
+ * @public
+ * @experimental
+ *
+ * Represents the set of dependencies that the driver uses from the [Node.js OS module](https://nodejs.org/api/os.html).
+ */
+export type OsAdapter = Pick<typeof os, 'release' | 'platform' | 'arch' | 'type'>;
+
+/**
+ * @public
+ * @experimental
+ *
+ * This type represents the set of dependencies that the driver needs from the Javascript runtime in order to function.
+ */
+export interface RuntimeAdapters {
+  os?: OsAdapter;
+}
+
+/**
+ * @internal
+ *
+ * Represents a complete, parsed set of runtime adapters.  After options parsing, all adapters
+ * are always present (either using the user's provided adapter, or defaulting to the Node.js module).
+ */
+export interface Runtime {
+  os: OsAdapter;
+}
+
+/**
+ * @internal
+ *
+ * Given a MongoClientOptions, this function resolves the set of runtime options, providing Nodejs implementations if
+ * not provided by in `options`, and returns a `Runtime`.
+ */
+export function resolveRuntimeAdapters(options: MongoClientOptions): Runtime {
+  (globalThis as any)[ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME] = true;
+  try {
+    const runtime = {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      os: options.runtimeAdapters?.os ?? require('os')
+    };
+    return runtime;
+  } finally {
+    (globalThis as any)[ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME] = false;
+  }
+}

package/src/sdam/srv_polling.ts

@@ -116,7 +116,7 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
     let srvRecords;
 
     try {
-      srvRecords = await dns.promises.resolveSrv(this.srvAddress);
+      srvRecords = await dns.promises.resolve(this.srvAddress, 'SRV');
     } catch {
       this.failure();
       return;

package/src/sdam/topology.ts

@@ -145,6 +145,8 @@ export interface TopologyOptions extends BSONSerializeOptions, ServerOptions {
   hosts: HostAddress[];
   retryWrites: boolean;
   retryReads: boolean;
+  maxAdaptiveRetries: number;
+  enableOverloadRetargeting: boolean;
   /** How long to block for server selection before throwing an error */
   serverSelectionTimeoutMS: number;
   /** The name of the replica set to connect to */
@@ -207,18 +209,13 @@ export type TopologyEvents = {
  * @internal
  */
 export class Topology extends TypedEventEmitter<TopologyEvents> {
-  /** @internal */
   s: TopologyPrivate;
-  /** @internal */
   waitQueue: List<ServerSelectionRequest>;
-  /** @internal */
   hello?: Document;
-  /** @internal */
   _type?: string;
 
   client!: MongoClient;
 
-  /** @internal */
   private connectionLock?: Promise<Topology>;
 
   /** @event */
@@ -595,7 +592,11 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
           )
         );
       }
-      if (options.timeoutContext?.clearServerSelectionTimeout) timeout?.clear();
+
+      if (!options.timeoutContext || options.timeoutContext.clearServerSelectionTimeout) {
+        timeout?.clear();
+      }
+
       return transaction.server;
     }
 
@@ -666,7 +667,9 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
       throw error;
     } finally {
       abortListener?.[kDispose]();
-      if (options.timeoutContext?.clearServerSelectionTimeout) timeout?.clear();
+      if (!options.timeoutContext || options.timeoutContext.clearServerSelectionTimeout) {
+        timeout?.clear();
+      }
     }
   }
   /**