mongodb 6.10.0-dev.20241106.sha.dc3fe957 → 6.10.0-dev.20241107.sha.e5582ed7

package/src/cmap/connection.ts

@@ -21,9 +21,11 @@ import {
 } from '../constants';
 import {
   MongoCompatibilityError,
+  MONGODB_ERROR_CODES,
   MongoMissingDependencyError,
   MongoNetworkError,
   MongoNetworkTimeoutError,
+  MongoOperationTimeoutError,
   MongoParseError,
   MongoServerError,
   MongoUnexpectedServerResponseError
@@ -35,6 +37,7 @@ import { type CancellationToken, TypedEventEmitter } from '../mongo_types';
 import { ReadPreference, type ReadPreferenceLike } from '../read_preference';
 import { ServerType } from '../sdam/common';
 import { applySession, type ClientSession, updateSessionFromResponse } from '../sessions';
+import { type TimeoutContext, TimeoutError } from '../timeout';
 import {
   BufferPool,
   calculateDurationInMs,
@@ -88,6 +91,7 @@ export interface CommandOptions extends BSONSerializeOptions {
   documentsReturnedIn?: string;
   noResponse?: boolean;
   omitReadPreference?: boolean;
+  omitMaxTimeMS?: boolean;
 
   // TODO(NODE-2802): Currently the CommandOptions take a property willRetryWrite which is a hint
   // from executeOperation that the txnNum should be applied to this command.
@@ -99,6 +103,9 @@ export interface CommandOptions extends BSONSerializeOptions {
   writeConcern?: WriteConcern;
 
   directConnection?: boolean;
+
+  /** @internal */
+  timeoutContext?: TimeoutContext;
 }
 
 /** @public */
@@ -420,6 +427,11 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
       ...options
     };
 
+    if (!options.omitMaxTimeMS) {
+      const maxTimeMS = options.timeoutContext?.maxTimeMS;
+      if (maxTimeMS && maxTimeMS > 0 && Number.isFinite(maxTimeMS)) cmd.maxTimeMS = maxTimeMS;
+    }
+
     const message = this.supportsOpMsg
       ? new OpMsgRequest(db, cmd, commandOptions)
       : new OpQueryRequest(db, cmd, commandOptions);
@@ -434,7 +446,9 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
   ): AsyncGenerator<MongoDBResponse> {
     this.throwIfAborted();
 
-    if (typeof options.socketTimeoutMS === 'number') {
+    if (options.timeoutContext?.csotEnabled()) {
+      this.socket.setTimeout(0);
+    } else if (typeof options.socketTimeoutMS === 'number') {
       this.socket.setTimeout(options.socketTimeoutMS);
     } else if (this.socketTimeoutMS !== 0) {
       this.socket.setTimeout(this.socketTimeoutMS);
@@ -443,7 +457,8 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
     try {
       await this.writeCommand(message, {
         agreedCompressor: this.description.compressor ?? 'none',
-        zlibCompressionLevel: this.description.zlibCompressionLevel
+        zlibCompressionLevel: this.description.zlibCompressionLevel,
+        timeoutContext: options.timeoutContext
       });
 
       if (options.noResponse || message.moreToCome) {
@@ -453,7 +468,17 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
       this.throwIfAborted();
 
-      for await (const response of this.readMany()) {
+      if (
+        options.timeoutContext?.csotEnabled() &&
+        options.timeoutContext.minRoundTripTime != null &&
+        options.timeoutContext.remainingTimeMS < options.timeoutContext.minRoundTripTime
+      ) {
+        throw new MongoOperationTimeoutError(
+          'Server roundtrip time is greater than the time remaining'
+        );
+      }
+
+      for await (const response of this.readMany({ timeoutContext: options.timeoutContext })) {
         this.socket.setTimeout(0);
         const bson = response.parse();
 
@@ -480,7 +505,6 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
     responseType?: MongoDBResponseConstructor
   ) {
     const message = this.prepareCommand(ns.db, command, options);
-
     let started = 0;
     if (this.shouldEmitAndLogCommand) {
       started = now();
@@ -522,6 +546,11 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
         }
 
         if (document.ok === 0) {
+          if (options.timeoutContext?.csotEnabled() && document.isMaxTimeExpiredError) {
+            throw new MongoOperationTimeoutError('Server reported a timeout error', {
+              cause: new MongoServerError((object ??= document.toObject(bsonOptions)))
+            });
+          }
           throw new MongoServerError((object ??= document.toObject(bsonOptions)));
         }
 
@@ -595,6 +624,28 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
   ): Promise<Document> {
     this.throwIfAborted();
     for await (const document of this.sendCommand(ns, command, options, responseType)) {
+      if (options.timeoutContext?.csotEnabled()) {
+        if (MongoDBResponse.is(document)) {
+          if (document.isMaxTimeExpiredError) {
+            throw new MongoOperationTimeoutError('Server reported a timeout error', {
+              cause: new MongoServerError(document.toObject())
+            });
+          }
+        } else {
+          if (
+            (Array.isArray(document?.writeErrors) &&
+              document.writeErrors.some(
+                error => error?.code === MONGODB_ERROR_CODES.MaxTimeMSExpired
+              )) ||
+            document?.writeConcernError?.code === MONGODB_ERROR_CODES.MaxTimeMSExpired
+          ) {
+            throw new MongoOperationTimeoutError('Server reported a timeout error', {
+              cause: new MongoServerError(document)
+            });
+          }
+        }
+      }
+
       return document;
     }
     throw new MongoUnexpectedServerResponseError('Unable to get response from server');
@@ -630,7 +681,11 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
    */
   private async writeCommand(
     command: WriteProtocolMessageType,
-    options: { agreedCompressor?: CompressorName; zlibCompressionLevel?: number }
+    options: {
+      agreedCompressor?: CompressorName;
+      zlibCompressionLevel?: number;
+      timeoutContext?: TimeoutContext;
+    }
   ): Promise<void> {
     const finalCommand =
       options.agreedCompressor === 'none' || !OpCompressedRequest.canCompress(command)
@@ -642,8 +697,36 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
 
     const buffer = Buffer.concat(await finalCommand.toBin());
 
+    if (options.timeoutContext?.csotEnabled()) {
+      if (
+        options.timeoutContext.minRoundTripTime != null &&
+        options.timeoutContext.remainingTimeMS < options.timeoutContext.minRoundTripTime
+      ) {
+        throw new MongoOperationTimeoutError(
+          'Server roundtrip time is greater than the time remaining'
+        );
+      }
+    }
+
     if (this.socket.write(buffer)) return;
-    return await once(this.socket, 'drain');
+
+    const drainEvent = once<void>(this.socket, 'drain');
+    const timeout = options?.timeoutContext?.timeoutForSocketWrite;
+    if (timeout) {
+      try {
+        return await Promise.race([drainEvent, timeout]);
+      } catch (error) {
+        let err = error;
+        if (TimeoutError.is(error)) {
+          err = new MongoOperationTimeoutError('Timed out at socket write');
+          this.cleanup(err);
+        }
+        throw error;
+      } finally {
+        timeout.clear();
+      }
+    }
+    return await drainEvent;
   }
 
   /**
@@ -655,10 +738,13 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
    *
    * Note that `for-await` loops call `return` automatically when the loop is exited.
    */
-  private async *readMany(): AsyncGenerator<OpMsgResponse | OpReply> {
+  private async *readMany(options: {
+    timeoutContext?: TimeoutContext;
+  }): AsyncGenerator<OpMsgResponse | OpReply> {
     try {
-      this.dataEvents = onData(this.messageStream);
+      this.dataEvents = onData(this.messageStream, options);
       this.messageStream.resume();
+
       for await (const message of this.dataEvents) {
         const response = await decompressResponse(message);
         yield response;
@@ -667,6 +753,17 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
           return;
         }
       }
+    } catch (readError) {
+      const err = readError;
+      if (TimeoutError.is(readError)) {
+        const error = new MongoOperationTimeoutError(
+          `Timed out during socket read (${readError.duration}ms)`
+        );
+        this.dataEvents = null;
+        this.onError(error);
+        throw error;
+      }
+      throw err;
     } finally {
       this.dataEvents = null;
       this.messageStream.pause();

package/src/cmap/connection_pool.ts

@@ -21,12 +21,13 @@ import {
   MongoInvalidArgumentError,
   MongoMissingCredentialsError,
   MongoNetworkError,
+  MongoOperationTimeoutError,
   MongoRuntimeError,
   MongoServerError
 } from '../error';
 import { CancellationToken, TypedEventEmitter } from '../mongo_types';
 import type { Server } from '../sdam/server';
-import { Timeout, TimeoutError } from '../timeout';
+import { type TimeoutContext, TimeoutError } from '../timeout';
 import { type Callback, List, makeCounter, now, promiseWithResolvers } from '../utils';
 import { connect } from './connect';
 import { Connection, type ConnectionEvents, type ConnectionOptions } from './connection';
@@ -102,7 +103,6 @@ export interface ConnectionPoolOptions extends Omit<ConnectionOptions, 'id' | 'g
 export interface WaitQueueMember {
   resolve: (conn: Connection) => void;
   reject: (err: AnyError) => void;
-  timeout: Timeout;
   [kCancelled]?: boolean;
   checkoutTime: number;
 }
@@ -355,23 +355,20 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
    * will be held by the pool. This means that if a connection is checked out it MUST be checked back in or
    * explicitly destroyed by the new owner.
    */
-  async checkOut(): Promise<Connection> {
+  async checkOut(options: { timeoutContext: TimeoutContext }): Promise<Connection> {
     const checkoutTime = now();
     this.emitAndLog(
       ConnectionPool.CONNECTION_CHECK_OUT_STARTED,
       new ConnectionCheckOutStartedEvent(this)
     );
 
-    const waitQueueTimeoutMS = this.options.waitQueueTimeoutMS;
-
     const { promise, resolve, reject } = promiseWithResolvers<Connection>();
 
-    const timeout = Timeout.expires(waitQueueTimeoutMS);
+    const timeout = options.timeoutContext.connectionCheckoutTimeout;
 
     const waitQueueMember: WaitQueueMember = {
       resolve,
       reject,
-      timeout,
       checkoutTime
     };
 
@@ -379,13 +376,13 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
     process.nextTick(() => this.processWaitQueue());
 
     try {
-      return await Promise.race([promise, waitQueueMember.timeout]);
+      timeout?.throwIfExpired();
+      return await (timeout ? Promise.race([promise, timeout]) : promise);
     } catch (error) {
       if (TimeoutError.is(error)) {
+        timeout?.clear();
         waitQueueMember[kCancelled] = true;
 
-        waitQueueMember.timeout.clear();
-
         this.emitAndLog(
           ConnectionPool.CONNECTION_CHECK_OUT_FAILED,
           new ConnectionCheckOutFailedEvent(this, 'timeout', waitQueueMember.checkoutTime)
@@ -396,9 +393,16 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
             : 'Timed out while checking out a connection from connection pool',
           this.address
         );
+        if (options.timeoutContext.csotEnabled()) {
+          throw new MongoOperationTimeoutError('Timed out during connection checkout', {
+            cause: timeoutError
+          });
+        }
         throw timeoutError;
       }
       throw error;
+    } finally {
+      if (options.timeoutContext.clearConnectionCheckoutTimeout) timeout?.clear();
     }
   }
 
@@ -764,7 +768,6 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
           ConnectionPool.CONNECTION_CHECK_OUT_FAILED,
           new ConnectionCheckOutFailedEvent(this, reason, waitQueueMember.checkoutTime, error)
         );
-        waitQueueMember.timeout.clear();
         this[kWaitQueue].shift();
         waitQueueMember.reject(error);
         continue;
@@ -785,7 +788,6 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
           ConnectionPool.CONNECTION_CHECKED_OUT,
           new ConnectionCheckedOutEvent(this, connection, waitQueueMember.checkoutTime)
         );
-        waitQueueMember.timeout.clear();
 
         this[kWaitQueue].shift();
         waitQueueMember.resolve(connection);
@@ -828,8 +830,6 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
             );
             waitQueueMember.resolve(connection);
           }
-
-          waitQueueMember.timeout.clear();
         }
         process.nextTick(() => this.processWaitQueue());
       });

package/src/cmap/wire_protocol/on_data.ts

@@ -1,5 +1,6 @@
 import { type EventEmitter } from 'events';
 
+import { type TimeoutContext } from '../../timeout';
 import { List, promiseWithResolvers } from '../../utils';
 
 /**
@@ -18,7 +19,10 @@ type PendingPromises = Omit<
  * Returns an AsyncIterator that iterates each 'data' event emitted from emitter.
  * It will reject upon an error event.
  */
-export function onData(emitter: EventEmitter) {
+export function onData(
+  emitter: EventEmitter,
+  { timeoutContext }: { timeoutContext?: TimeoutContext }
+) {
   // Setup pending events and pending promise lists
   /**
    * When the caller has not yet called .next(), we store the
@@ -87,6 +91,10 @@ export function onData(emitter: EventEmitter) {
   emitter.on('data', eventHandler);
   emitter.on('error', errorHandler);
 
+  const timeoutForSocketRead = timeoutContext?.timeoutForSocketRead;
+  timeoutForSocketRead?.throwIfExpired();
+  timeoutForSocketRead?.then(undefined, errorHandler);
+
   return iterator;
 
   function eventHandler(value: Buffer) {
@@ -97,6 +105,7 @@ export function onData(emitter: EventEmitter) {
 
   function errorHandler(err: Error) {
     const promise = unconsumedPromises.shift();
+
     if (promise != null) promise.reject(err);
     else error = err;
     void closeHandler();
@@ -107,6 +116,7 @@ export function onData(emitter: EventEmitter) {
     emitter.off('data', eventHandler);
     emitter.off('error', errorHandler);
     finished = true;
+    timeoutForSocketRead?.clear();
     const doneResult = { value: undefined, done: finished } as const;
 
     for (const promise of unconsumedPromises) {

package/src/cmap/wire_protocol/responses.ts

@@ -10,7 +10,7 @@ import {
   pluckBSONSerializeOptions,
   type Timestamp
 } from '../../bson';
-import { MongoUnexpectedServerResponseError } from '../../error';
+import { MONGODB_ERROR_CODES, MongoUnexpectedServerResponseError } from '../../error';
 import { type ClusterTime } from '../../sdam/common';
 import { decorateDecryptionResult, ns } from '../../utils';
 import {
@@ -110,6 +110,40 @@ export class MongoDBResponse extends OnDemandDocument {
   // {ok:1}
   static empty = new MongoDBResponse(new Uint8Array([13, 0, 0, 0, 16, 111, 107, 0, 1, 0, 0, 0, 0]));
 
+  /**
+   * Returns true iff:
+   * - ok is 0 and the top-level code === 50
+   * - ok is 1 and the writeErrors array contains a code === 50
+   * - ok is 1 and the writeConcern object contains a code === 50
+   */
+  get isMaxTimeExpiredError() {
+    // {ok: 0, code: 50 ... }
+    const isTopLevel = this.ok === 0 && this.code === MONGODB_ERROR_CODES.MaxTimeMSExpired;
+    if (isTopLevel) return true;
+
+    if (this.ok === 0) return false;
+
+    // {ok: 1, writeConcernError: {code: 50 ... }}
+    const isWriteConcern =
+      this.get('writeConcernError', BSONType.object)?.getNumber('code') ===
+      MONGODB_ERROR_CODES.MaxTimeMSExpired;
+    if (isWriteConcern) return true;
+
+    const writeErrors = this.get('writeErrors', BSONType.array);
+    if (writeErrors?.size()) {
+      for (let i = 0; i < writeErrors.size(); i++) {
+        const isWriteError =
+          writeErrors.get(i, BSONType.object)?.getNumber('code') ===
+          MONGODB_ERROR_CODES.MaxTimeMSExpired;
+
+        // {ok: 1, writeErrors: [{code: 50 ... }]}
+        if (isWriteError) return true;
+      }
+    }
+
+    return false;
+  }
+
   /**
    * Drivers can safely assume that the `recoveryToken` field is always a BSON document but drivers MUST NOT modify the
    * contents of the document.

package/src/collection.ts

@@ -11,7 +11,7 @@ import {
   type ListSearchIndexesOptions
 } from './cursor/list_search_indexes_cursor';
 import type { Db } from './db';
-import { MongoInvalidArgumentError } from './error';
+import { MongoInvalidArgumentError, MongoOperationTimeoutError } from './error';
 import type { MongoClient, PkFactory } from './mongo_client';
 import type {
   Filter,
@@ -115,7 +115,10 @@ export interface CollectionOptions extends BSONSerializeOptions, WriteConcernOpt
   readConcern?: ReadConcernLike;
   /** The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). */
   readPreference?: ReadPreferenceLike;
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error
+   */
   timeoutMS?: number;
 }
 
@@ -262,6 +265,10 @@ export class Collection<TSchema extends Document = Document> {
     this.s.collectionHint = normalizeHintField(v);
   }
 
+  public get timeoutMS(): number | undefined {
+    return this.s.options.timeoutMS;
+  }
+
   /**
    * Inserts a single document into MongoDB. If documents passed in do not contain the **_id** field,
    * one will be added to each of the documents missing it by the driver, mutating the document. This behavior
@@ -465,10 +472,14 @@ export class Collection<TSchema extends Document = Document> {
     // Intentionally, we do not inherit options from parent for this operation.
     return await executeOperation(
       this.client,
-      new RenameOperation(this as TODO_NODE_3286, newName, {
-        ...options,
-        readPreference: ReadPreference.PRIMARY
-      }) as TODO_NODE_3286
+      new RenameOperation(
+        this as TODO_NODE_3286,
+        newName,
+        resolveOptions(undefined, {
+          ...options,
+          readPreference: ReadPreference.PRIMARY
+        })
+      ) as TODO_NODE_3286
     );
   }
 
@@ -492,12 +503,18 @@ export class Collection<TSchema extends Document = Document> {
    */
   async findOne(): Promise<WithId<TSchema> | null>;
   async findOne(filter: Filter<TSchema>): Promise<WithId<TSchema> | null>;
-  async findOne(filter: Filter<TSchema>, options: FindOptions): Promise<WithId<TSchema> | null>;
+  async findOne(
+    filter: Filter<TSchema>,
+    options: Omit<FindOptions, 'timeoutMode'>
+  ): Promise<WithId<TSchema> | null>;
 
   // allow an override of the schema.
   async findOne<T = TSchema>(): Promise<T | null>;
   async findOne<T = TSchema>(filter: Filter<TSchema>): Promise<T | null>;
-  async findOne<T = TSchema>(filter: Filter<TSchema>, options?: FindOptions): Promise<T | null>;
+  async findOne<T = TSchema>(
+    filter: Filter<TSchema>,
+    options?: Omit<FindOptions, 'timeoutMode'>
+  ): Promise<T | null>;
 
   async findOne(
     filter: Filter<TSchema> = {},
@@ -669,7 +686,9 @@ export class Collection<TSchema extends Document = Document> {
         new DropIndexOperation(this as TODO_NODE_3286, '*', resolveOptions(this, options))
       );
       return true;
-    } catch {
+    } catch (error) {
+      // TODO(NODE-6517): Driver should only filter for namespace not found error. Other errors should be thrown.
+      if (error instanceof MongoOperationTimeoutError) throw error;
       return false;
     }
   }
@@ -1033,6 +1052,59 @@ export class Collection<TSchema extends Document = Document> {
    *   });
    * ```
    *
+   * @remarks
+   * When `timeoutMS` is configured for a change stream, it will have different behaviour depending
+   * on whether the change stream is in iterator mode or emitter mode. In both cases, a change
+   * stream will time out if it does not receive a change event within `timeoutMS` of the last change
+   * event.
+   *
+   * Note that if a change stream is consistently timing out when watching a collection, database or
+   * client that is being changed, then this may be due to the server timing out before it can finish
+   * processing the existing oplog. To address this, restart the change stream with a higher
+   * `timeoutMS`.
+   *
+   * If the change stream times out the initial aggregate operation to establish the change stream on
+   * the server, then the client will close the change stream. If the getMore calls to the server
+   * time out, then the change stream will be left open, but will throw a MongoOperationTimeoutError
+   * when in iterator mode and emit an error event that returns a MongoOperationTimeoutError in
+   * emitter mode.
+   *
+   * To determine whether or not the change stream is still open following a timeout, check the
+   * {@link ChangeStream.closed} getter.
+   *
+   * @example
+   * In iterator mode, if a next() call throws a timeout error, it will attempt to resume the change stream.
+   * The next call can just be retried after this succeeds.
+   * ```ts
+   * const changeStream = collection.watch([], { timeoutMS: 100 });
+   * try {
+   *     await changeStream.next();
+   * } catch (e) {
+   *     if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
+   *       await changeStream.next();
+   *     }
+   *     throw e;
+   * }
+   * ```
+   *
+   * @example
+   * In emitter mode, if the change stream goes `timeoutMS` without emitting a change event, it will
+   * emit an error event that returns a MongoOperationTimeoutError, but will not close the change
+   * stream unless the resume attempt fails. There is no need to re-establish change listeners as
+   * this will automatically continue emitting change events once the resume attempt completes.
+   *
+   * ```ts
+   * const changeStream = collection.watch([], { timeoutMS: 100 });
+   * changeStream.on('change', console.log);
+   * changeStream.on('error', e => {
+   *     if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
+   *         // do nothing
+   *     } else {
+   *         changeStream.close();
+   *     }
+   * });
+   * ```
+   *
    * @param pipeline - An array of {@link https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/|aggregation pipeline stages} through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
    * @param options - Optional settings for the command
    * @typeParam TLocal - Type of the data being detected by the change stream

package/src/connection_string.ts

@@ -1092,6 +1092,7 @@ export const OPTIONS = {
     type: 'string'
   },
   socketTimeoutMS: {
+    // TODO(NODE-6491): deprecated: 'Please use timeoutMS instead',
     default: 0,
     type: 'uint'
   },
@@ -1162,6 +1163,7 @@ export const OPTIONS = {
     }
   },
   waitQueueTimeoutMS: {
+    // TODO(NODE-6491): deprecated: 'Please use timeoutMS instead',
     default: 0,
     type: 'uint'
   },