mongodb 6.10.0-dev.20241102.sha.2f3fb466 → 6.10.0-dev.20241107.sha.e5582ed7

package/src/cursor/find_cursor.ts

@@ -1,7 +1,13 @@
 import { type Document } from '../bson';
 import { CursorResponse } from '../cmap/wire_protocol/responses';
-import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
-import { type ExplainCommandOptions, type ExplainVerbosityLike } from '../explain';
+import { MongoAPIError, MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
+import {
+  Explain,
+  ExplainableCursor,
+  type ExplainCommandOptions,
+  type ExplainVerbosityLike,
+  validateExplainTimeoutOptions
+} from '../explain';
 import type { MongoClient } from '../mongo_client';
 import type { CollationOptions } from '../operations/command';
 import { CountOperation, type CountOptions } from '../operations/count';
@@ -11,7 +17,7 @@ import type { Hint } from '../operations/operation';
 import type { ClientSession } from '../sessions';
 import { formatSort, type Sort, type SortDirection } from '../sort';
 import { emitWarningOnce, mergeOptions, type MongoDBNamespace, squashError } from '../utils';
-import { AbstractCursor, type InitialCursorResponse } from './abstract_cursor';
+import { type InitialCursorResponse } from './abstract_cursor';
 
 /** @public Flags allowed for cursor */
 export const FLAGS = [
@@ -24,7 +30,7 @@ export const FLAGS = [
 ] as const;
 
 /** @public */
-export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
+export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
   /** @internal */
   private cursorFilter: Document;
   /** @internal */
@@ -63,13 +69,25 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
 
   /** @internal */
   async _initialize(session: ClientSession): Promise<InitialCursorResponse> {
-    const findOperation = new FindOperation(this.namespace, this.cursorFilter, {
+    const options = {
       ...this.findOptions, // NOTE: order matters here, we may need to refine this
       ...this.cursorOptions,
       session
-    });
+    };
+
+    if (options.explain) {
+      try {
+        validateExplainTimeoutOptions(options, Explain.fromOptions(options));
+      } catch {
+        throw new MongoAPIError(
+          'timeoutMS cannot be used with explain when explain is specified in findOptions'
+        );
+      }
+    }
 
-    const response = await executeOperation(this.client, findOperation);
+    const findOperation = new FindOperation(this.namespace, this.cursorFilter, options);
+
+    const response = await executeOperation(this.client, findOperation, this.timeoutContext);
 
     // the response is not a cursor when `explain` is enabled
     this.numReturned = response.batchSize;
@@ -133,14 +151,27 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   }
 
   /** Execute the explain for the cursor */
-  async explain(verbosity?: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document> {
+  async explain(): Promise<Document>;
+  async explain(verbosity: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document>;
+  async explain(options: { timeoutMS?: number }): Promise<Document>;
+  async explain(
+    verbosity: ExplainVerbosityLike | ExplainCommandOptions,
+    options: { timeoutMS?: number }
+  ): Promise<Document>;
+  async explain(
+    verbosity?: ExplainVerbosityLike | ExplainCommandOptions | { timeoutMS?: number },
+    options?: { timeoutMS?: number }
+  ): Promise<Document> {
+    const { explain, timeout } = this.resolveExplainTimeoutOptions(verbosity, options);
+
     return (
       await executeOperation(
         this.client,
         new FindOperation(this.namespace, this.cursorFilter, {
           ...this.findOptions, // NOTE: order matters here, we may need to refine this
           ...this.cursorOptions,
-          explain: verbosity ?? true
+          ...timeout,
+          explain: explain ?? true
         })
       )
     ).shift(this.deserializationOptions);

package/src/cursor/list_collections_cursor.ts

@@ -41,7 +41,7 @@ export class ListCollectionsCursor<
       session
     });
 
-    const response = await executeOperation(this.parent.client, operation);
+    const response = await executeOperation(this.parent.client, operation, this.timeoutContext);
 
     return { server: operation.server, session, response };
   }

package/src/cursor/list_indexes_cursor.ts

@@ -30,7 +30,7 @@ export class ListIndexesCursor extends AbstractCursor {
       session
     });
 
-    const response = await executeOperation(this.parent.client, operation);
+    const response = await executeOperation(this.parent.client, operation, this.timeoutContext);
 
     return { server: operation.server, session, response };
   }

package/src/cursor/run_command_cursor.ts

@@ -9,12 +9,55 @@ import type { ReadConcernLike } from '../read_concern';
 import type { ReadPreferenceLike } from '../read_preference';
 import type { ClientSession } from '../sessions';
 import { ns } from '../utils';
-import { AbstractCursor, type InitialCursorResponse } from './abstract_cursor';
+import {
+  AbstractCursor,
+  type CursorTimeoutMode,
+  type InitialCursorResponse
+} from './abstract_cursor';
 
 /** @public */
 export type RunCursorCommandOptions = {
   readPreference?: ReadPreferenceLike;
   session?: ClientSession;
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error. Note that if
+   * `maxTimeMS` is provided in the command in addition to setting `timeoutMS` in the options, then
+   * the original value of `maxTimeMS` will be overwritten.
+   */
+  timeoutMS?: number;
+  /**
+   * @public
+   * @experimental
+   * Specifies how `timeoutMS` is applied to the cursor. Can be either `'cursorLifeTime'` or `'iteration'`
+   * When set to `'iteration'`, the deadline specified by `timeoutMS` applies to each call of
+   * `cursor.next()`.
+   * When set to `'cursorLifetime'`, the deadline applies to the life of the entire cursor.
+   *
+   * Depending on the type of cursor being used, this option has different default values.
+   * For non-tailable cursors, this value defaults to `'cursorLifetime'`
+   * For tailable cursors, this value defaults to `'iteration'` since tailable cursors, by
+   * definition can have an arbitrarily long lifetime.
+   *
+   * @example
+   * ```ts
+   * const cursor = collection.find({}, {timeoutMS: 100, timeoutMode: 'iteration'});
+   * for await (const doc of cursor) {
+   *  // process doc
+   *  // This will throw a timeout error if any of the iterator's `next()` calls takes more than 100ms, but
+   *  // will continue to iterate successfully otherwise, regardless of the number of batches.
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * const cursor = collection.find({}, { timeoutMS: 1000, timeoutMode: 'cursorLifetime' });
+   * const docs = await cursor.toArray(); // This entire line will throw a timeout error if all batches are not fetched and returned within 1000ms.
+   * ```
+   */
+  timeoutMode?: CursorTimeoutMode;
+  tailable?: boolean;
+  awaitData?: boolean;
 } & BSONSerializeOptions;
 
 /** @public */
@@ -46,7 +89,7 @@ export class RunCommandCursor extends AbstractCursor {
 
   /**
    * Controls the `getMore.batchSize` field
-   * @param maxTimeMS - the number documents to return in the `nextBatch`
+   * @param batchSize - the number documents to return in the `nextBatch`
    */
   public setBatchSize(batchSize: number): this {
     this.getMoreOptions.batchSize = batchSize;
@@ -72,7 +115,9 @@ export class RunCommandCursor extends AbstractCursor {
     );
   }
 
-  /** Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document */
+  /**
+   * Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document
+   */
   public override maxTimeMS(_: number): never {
     throw new MongoAPIError(
       'maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()'
@@ -105,7 +150,7 @@ export class RunCommandCursor extends AbstractCursor {
       responseType: CursorResponse
     });
 
-    const response = await executeOperation(this.client, operation);
+    const response = await executeOperation(this.client, operation, this.timeoutContext);
 
     return {
       server: operation.server,
@@ -123,6 +168,6 @@ export class RunCommandCursor extends AbstractCursor {
       ...this.getMoreOptions
     });
 
-    return await executeOperation(this.client, getMoreOperation);
+    return await executeOperation(this.client, getMoreOperation, this.timeoutContext);
   }
 }

package/src/db.ts

@@ -97,7 +97,10 @@ export interface DbOptions extends BSONSerializeOptions, WriteConcernOptions {
   readConcern?: ReadConcern;
   /** Should retry failed writes */
   retryWrites?: boolean;
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error
+   */
   timeoutMS?: number;
 }
 
@@ -222,6 +225,10 @@ export class Db {
     return this.s.namespace.toString();
   }
 
+  public get timeoutMS(): number | undefined {
+    return this.s.options?.timeoutMS;
+  }
+
   /**
    * Create a new collection on a server with the specified options. Use this to create capped collections.
    * More information about command options available at https://www.mongodb.com/docs/manual/reference/command/create/
@@ -270,11 +277,16 @@ export class Db {
     // Intentionally, we do not inherit options from parent for this operation.
     return await executeOperation(
       this.client,
-      new RunCommandOperation(this, command, {
-        ...resolveBSONOptions(options),
-        session: options?.session,
-        readPreference: options?.readPreference
-      })
+      new RunCommandOperation(
+        this,
+        command,
+        resolveOptions(undefined, {
+          ...resolveBSONOptions(options),
+          timeoutMS: options?.timeoutMS ?? this.timeoutMS,
+          session: options?.session,
+          readPreference: options?.readPreference
+        })
+      )
     );
   }
 
@@ -379,7 +391,11 @@ export class Db {
       new RenameOperation(
         this.collection<TSchema>(fromCollection) as TODO_NODE_3286,
         toCollection,
-        { ...options, new_collection: true, readPreference: ReadPreference.primary }
+        resolveOptions(undefined, {
+          ...options,
+          new_collection: true,
+          readPreference: ReadPreference.primary
+        })
       ) as TODO_NODE_3286
     );
   }
@@ -517,6 +533,58 @@ export class Db {
    * - The first is to provide the schema that may be defined for all the collections within this database
    * - The second is to override the shape of the change stream document entirely, if it is not provided the type will default to ChangeStreamDocument of the first argument
    *
+   * @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 TSchema - Type of the data being detected by the change stream

package/src/error.ts

@@ -311,7 +311,7 @@ export class MongoAPIError extends MongoDriverError {
 
 /**
  * An error generated when the driver encounters unexpected input
- * or reaches an unexpected/invalid internal state
+ * or reaches an unexpected/invalid internal state.
  *
  * @privateRemarks
  * Should **never** be directly instantiated.
@@ -857,6 +857,31 @@ export class MongoUnexpectedServerResponseError extends MongoRuntimeError {
   }
 }
 
+/**
+ * @public
+ * @category Error
+ *
+ * The `MongoOperationTimeoutError` class represents an error that occurs when an operation could not be completed within the specified `timeoutMS`.
+ * It is generated by the driver in support of the "client side operation timeout" feature so inherits from `MongoDriverError`.
+ * When `timeoutMS` is enabled `MongoServerError`s relating to `MaxTimeExpired` errors will be converted to `MongoOperationTimeoutError`
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await blogs.insertOne(blogPost, { timeoutMS: 60_000 })
+ * } catch (error) {
+ *   if (error instanceof MongoOperationTimeoutError) {
+ *     console.log(`Oh no! writer's block!`, error);
+ *   }
+ * }
+ * ```
+ */
+export class MongoOperationTimeoutError extends MongoDriverError {
+  override get name(): string {
+    return 'MongoOperationTimeoutError';
+  }
+}
+
 /**
  * An error thrown when the user attempts to add options to a cursor that has already been
  * initialized

package/src/explain.ts

@@ -1,3 +1,7 @@
+import { type Document } from './bson';
+import { AbstractCursor } from './cursor/abstract_cursor';
+import { MongoAPIError } from './error';
+
 /** @public */
 export const ExplainVerbosity = Object.freeze({
   queryPlanner: 'queryPlanner',
@@ -86,3 +90,84 @@ export class Explain {
     return new Explain(verbosity, maxTimeMS);
   }
 }
+
+export function validateExplainTimeoutOptions(options: Document, explain?: Explain) {
+  const { maxTimeMS, timeoutMS } = options;
+  if (timeoutMS != null && (maxTimeMS != null || explain?.maxTimeMS != null)) {
+    throw new MongoAPIError('Cannot use maxTimeMS with timeoutMS for explain commands.');
+  }
+}
+
+/**
+ * Applies an explain to a given command.
+ * @internal
+ *
+ * @param command - the command on which to apply the explain
+ * @param options - the options containing the explain verbosity
+ */
+export function decorateWithExplain(
+  command: Document,
+  explain: Explain
+): {
+  explain: Document;
+  verbosity: ExplainVerbosity;
+  maxTimeMS?: number;
+} {
+  type ExplainCommand = ReturnType<typeof decorateWithExplain>;
+  const { verbosity, maxTimeMS } = explain;
+  const baseCommand: ExplainCommand = { explain: command, verbosity };
+
+  if (typeof maxTimeMS === 'number') {
+    baseCommand.maxTimeMS = maxTimeMS;
+  }
+
+  return baseCommand;
+}
+
+/**
+ * @public
+ *
+ * A base class for any cursors that have `explain()` methods.
+ */
+export abstract class ExplainableCursor<TSchema> extends AbstractCursor<TSchema> {
+  /** Execute the explain for the cursor */
+  abstract explain(): Promise<Document>;
+  abstract explain(verbosity: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document>;
+  abstract explain(options: { timeoutMS?: number }): Promise<Document>;
+  abstract explain(
+    verbosity: ExplainVerbosityLike | ExplainCommandOptions,
+    options: { timeoutMS?: number }
+  ): Promise<Document>;
+  abstract explain(
+    verbosity?: ExplainVerbosityLike | ExplainCommandOptions | { timeoutMS?: number },
+    options?: { timeoutMS?: number }
+  ): Promise<Document>;
+
+  protected resolveExplainTimeoutOptions(
+    verbosity?: ExplainVerbosityLike | ExplainCommandOptions | { timeoutMS?: number },
+    options?: { timeoutMS?: number }
+  ): { timeout?: { timeoutMS?: number }; explain?: ExplainVerbosityLike | ExplainCommandOptions } {
+    let explain: ExplainVerbosityLike | ExplainCommandOptions | undefined;
+    let timeout: { timeoutMS?: number } | undefined;
+
+    if (verbosity == null && options == null) {
+      explain = undefined;
+      timeout = undefined;
+    } else if (verbosity != null && options == null) {
+      explain =
+        typeof verbosity !== 'object'
+          ? verbosity
+          : 'verbosity' in verbosity
+            ? verbosity
+            : undefined;
+
+      timeout = typeof verbosity === 'object' && 'timeoutMS' in verbosity ? verbosity : undefined;
+    } else {
+      // @ts-expect-error TS isn't smart enough to determine that if both options are provided, the first is explain options
+      explain = verbosity;
+      timeout = options;
+    }
+
+    return { timeout, explain };
+  }
+}

package/src/gridfs/download.ts

@@ -2,6 +2,7 @@ import { Readable } from 'stream';
 
 import type { Document, ObjectId } from '../bson';
 import type { Collection } from '../collection';
+import { CursorTimeoutMode } from '../cursor/abstract_cursor';
 import type { FindCursor } from '../cursor/find_cursor';
 import {
   MongoGridFSChunkError,
@@ -12,6 +13,7 @@ import {
 import type { FindOptions } from '../operations/find';
 import type { ReadPreference } from '../read_preference';
 import type { Sort } from '../sort';
+import { CSOTTimeoutContext } from '../timeout';
 import type { Callback } from '../utils';
 import type { GridFSChunk } from './upload';
 
@@ -28,7 +30,10 @@ export interface GridFSBucketReadStreamOptions {
    * to be returned by the stream. `end` is non-inclusive
    */
   end?: number;
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error
+   */
   timeoutMS?: number;
 }
 
@@ -98,8 +103,10 @@ export interface GridFSBucketReadStreamPrivate {
     skip?: number;
     start: number;
     end: number;
+    timeoutMS?: number;
   };
   readPreference?: ReadPreference;
+  timeoutContext?: CSOTTimeoutContext;
 }
 
 /**
@@ -148,7 +155,11 @@ export class GridFSBucketReadStream extends Readable {
         end: 0,
         ...options
       },
-      readPreference
+      readPreference,
+      timeoutContext:
+        options?.timeoutMS != null
+          ? new CSOTTimeoutContext({ timeoutMS: options.timeoutMS, serverSelectionTimeoutMS: 0 })
+          : undefined
     };
   }
 
@@ -196,7 +207,8 @@ export class GridFSBucketReadStream extends Readable {
   async abort(): Promise<void> {
     this.push(null);
     this.destroy();
-    await this.s.cursor?.close();
+    const remainingTimeMS = this.s.timeoutContext?.getRemainingTimeMSOrThrow();
+    await this.s.cursor?.close({ timeoutMS: remainingTimeMS });
   }
 }
 
@@ -352,7 +364,22 @@ function init(stream: GridFSBucketReadStream): void {
         filter['n'] = { $gte: skip };
       }
     }
-    stream.s.cursor = stream.s.chunks.find(filter).sort({ n: 1 });
+
+    let remainingTimeMS: number | undefined;
+    try {
+      remainingTimeMS = stream.s.timeoutContext?.getRemainingTimeMSOrThrow(
+        `Download timed out after ${stream.s.timeoutContext?.timeoutMS}ms`
+      );
+    } catch (error) {
+      return stream.destroy(error);
+    }
+
+    stream.s.cursor = stream.s.chunks
+      .find(filter, {
+        timeoutMode: stream.s.options.timeoutMS != null ? CursorTimeoutMode.LIFETIME : undefined,
+        timeoutMS: remainingTimeMS
+      })
+      .sort({ n: 1 });
 
     if (stream.s.readPreference) {
       stream.s.cursor.withReadPreference(stream.s.readPreference);
@@ -371,6 +398,18 @@ function init(stream: GridFSBucketReadStream): void {
     return;
   };
 
+  let remainingTimeMS: number | undefined;
+  try {
+    remainingTimeMS = stream.s.timeoutContext?.getRemainingTimeMSOrThrow(
+      `Download timed out after ${stream.s.timeoutContext?.timeoutMS}ms`
+    );
+  } catch (error) {
+    if (!stream.destroyed) stream.destroy(error);
+    return;
+  }
+
+  findOneOptions.timeoutMS = remainingTimeMS;
+
   stream.s.files.findOne(stream.s.filter, findOneOptions).then(handleReadResult, error => {
     if (stream.destroyed) return;
     stream.destroy(error);