mongodb 6.12.0-dev.20250125.sha.c1bcf0de → 6.12.0-dev.20250129.sha.907aac19

package/src/cursor/abstract_cursor.ts

@@ -12,7 +12,7 @@ import {
   MongoTailableCursorError
 } from '../error';
 import type { MongoClient } from '../mongo_client';
-import { TypedEventEmitter } from '../mongo_types';
+import { type Abortable, TypedEventEmitter } from '../mongo_types';
 import { executeOperation } from '../operations/execute_operation';
 import { GetMoreOperation } from '../operations/get_more';
 import { KillCursorsOperation } from '../operations/kill_cursors';
@@ -22,7 +22,13 @@ import { type AsyncDisposable, configureResourceManagement } from '../resource_m
 import type { Server } from '../sdam/server';
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
 import { type CSOTTimeoutContext, type Timeout, TimeoutContext } from '../timeout';
-import { type MongoDBNamespace, squashError } from '../utils';
+import {
+  addAbortListener,
+  type Disposable,
+  kDispose,
+  type MongoDBNamespace,
+  squashError
+} from '../utils';
 
 /**
  * @internal
@@ -61,6 +67,10 @@ export interface CursorStreamOptions {
 /** @public */
 export type CursorFlag = (typeof CURSOR_FLAGS)[number];
 
+function removeActiveCursor(this: AbstractCursor) {
+  this.client.s.activeCursors.delete(this);
+}
+
 /**
  * @public
  * @experimental
@@ -247,12 +257,14 @@ export abstract class AbstractCursor<
 
   /** @internal */
   protected deserializationOptions: OnDemandDocumentDeserializeOptions;
+  protected signal: AbortSignal | undefined;
+  private abortListener: Disposable | undefined;
 
   /** @internal */
   protected constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
-    options: AbstractCursorOptions = {}
+    options: AbstractCursorOptions & Abortable = {}
   ) {
     super();
 
@@ -352,6 +364,12 @@ export abstract class AbstractCursor<
     };
 
     this.timeoutContext = options.timeoutContext;
+    this.signal = options.signal;
+    this.abortListener = addAbortListener(
+      this.signal,
+      () => void this.close().then(undefined, squashError)
+    );
+    this.trackCursor();
   }
 
   /**
@@ -431,6 +449,14 @@ export abstract class AbstractCursor<
     await this.close();
   }
 
+  /** Adds cursor to client's tracking so it will be closed by MongoClient.close() */
+  private trackCursor() {
+    this.cursorClient.s.activeCursors.add(this);
+    if (!this.listeners('close').includes(removeActiveCursor)) {
+      this.once('close', removeActiveCursor);
+    }
+  }
+
   /** Returns current buffered documents length */
   bufferedCount(): number {
     return this.documents?.length ?? 0;
@@ -455,6 +481,8 @@ export abstract class AbstractCursor<
   }
 
   async *[Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void> {
+    this.signal?.throwIfAborted();
+
     if (this.closed) {
       return;
     }
@@ -481,6 +509,8 @@ export abstract class AbstractCursor<
         }
 
         yield document;
+
+        this.signal?.throwIfAborted();
       }
     } finally {
       // Only close the cursor if it has not already been closed. This finally clause handles
@@ -496,9 +526,16 @@ export abstract class AbstractCursor<
   }
 
   stream(options?: CursorStreamOptions): Readable & AsyncIterable<TSchema> {
+    const readable = new ReadableCursorStream(this);
+    const abortListener = addAbortListener(this.signal, function () {
+      readable.destroy(this.reason);
+    });
+    readable.once('end', () => {
+      abortListener?.[kDispose]();
+    });
+
     if (options?.transform) {
       const transform = options.transform;
-      const readable = new ReadableCursorStream(this);
 
       const transformedStream = readable.pipe(
         new Transform({
@@ -522,10 +559,12 @@ export abstract class AbstractCursor<
       return transformedStream;
     }
 
-    return new ReadableCursorStream(this);
+    return readable;
   }
 
   async hasNext(): Promise<boolean> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       return false;
     }
@@ -551,6 +590,8 @@ export abstract class AbstractCursor<
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
   async next(): Promise<TSchema | null> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
@@ -581,6 +622,8 @@ export abstract class AbstractCursor<
    * Try to get the next available document from the cursor or `null` if an empty batch is returned
    */
   async tryNext(): Promise<TSchema | null> {
+    this.signal?.throwIfAborted();
+
     if (this.cursorId === Long.ZERO) {
       throw new MongoCursorExhaustedError();
     }
@@ -620,6 +663,8 @@ export abstract class AbstractCursor<
    * @deprecated - Will be removed in a future release. Use for await...of instead.
    */
   async forEach(iterator: (doc: TSchema) => boolean | void): Promise<void> {
+    this.signal?.throwIfAborted();
+
     if (typeof iterator !== 'function') {
       throw new MongoInvalidArgumentError('Argument "iterator" must be a function');
     }
@@ -645,6 +690,8 @@ export abstract class AbstractCursor<
    * cursor.rewind() can be used to reset the cursor.
    */
   async toArray(): Promise<TSchema[]> {
+    this.signal?.throwIfAborted();
+
     const array: TSchema[] = [];
     // at the end of the loop (since readBufferedDocuments is called) the buffer will be empty
     // then, the 'await of' syntax will run a getMore call
@@ -824,16 +871,15 @@ export abstract class AbstractCursor<
     this.isClosed = false;
     this.isKilled = false;
     this.initialized = false;
+    this.hasEmittedClose = false;
+    this.trackCursor();
 
-    const session = this.cursorSession;
-    if (session) {
-      // We only want to end this session if we created it, and it hasn't ended yet
-      if (session.explicit === false) {
-        if (!session.hasEnded) {
-          session.endSession().then(undefined, squashError);
-        }
-        this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
+    // We only want to end this session if we created it, and it hasn't ended yet
+    if (this.cursorSession.explicit === false) {
+      if (!this.cursorSession.hasEnded) {
+        this.cursorSession.endSession().then(undefined, squashError);
       }
+      this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
     }
   }
 
@@ -968,8 +1014,8 @@ export abstract class AbstractCursor<
 
   /** @internal */
   private async cleanup(timeoutMS?: number, error?: Error) {
+    this.abortListener?.[kDispose]();
     this.isClosed = true;
-    const session = this.cursorSession;
     const timeoutContextForKillCursors = (): CursorTimeoutContext | undefined => {
       if (timeoutMS != null) {
         this.timeoutContext?.clear();
@@ -991,7 +1037,7 @@ export abstract class AbstractCursor<
         !this.cursorId.isZero() &&
         this.cursorNamespace &&
         this.selectedServer &&
-        !session.hasEnded
+        !this.cursorSession.hasEnded
       ) {
         this.isKilled = true;
         const cursorId = this.cursorId;
@@ -1000,7 +1046,7 @@ export abstract class AbstractCursor<
         await executeOperation(
           this.cursorClient,
           new KillCursorsOperation(cursorId, this.cursorNamespace, this.selectedServer, {
-            session
+            session: this.cursorSession
           }),
           timeoutContextForKillCursors()
         );
@@ -1008,14 +1054,16 @@ export abstract class AbstractCursor<
     } catch (error) {
       squashError(error);
     } finally {
-      if (session?.owner === this) {
-        await session.endSession({ error });
-      }
-      if (!session?.inTransaction()) {
-        maybeClearPinnedConnection(session, { error });
+      try {
+        if (this.cursorSession?.owner === this) {
+          await this.cursorSession.endSession({ error });
+        }
+        if (!this.cursorSession?.inTransaction()) {
+          maybeClearPinnedConnection(this.cursorSession, { error });
+        }
+      } finally {
+        this.emitClose();
       }
-
-      this.emitClose();
     }
   }
 

package/src/cursor/aggregation_cursor.ts

@@ -8,6 +8,7 @@ import {
   validateExplainTimeoutOptions
 } from '../explain';
 import type { MongoClient } from '../mongo_client';
+import { type Abortable } from '../mongo_types';
 import { AggregateOperation, type AggregateOptions } from '../operations/aggregate';
 import { executeOperation } from '../operations/execute_operation';
 import type { ClientSession } from '../sessions';
@@ -32,14 +33,14 @@ export interface AggregationCursorOptions extends AbstractCursorOptions, Aggrega
 export class AggregationCursor<TSchema = any> extends ExplainableCursor<TSchema> {
   public readonly pipeline: Document[];
   /** @internal */
-  private aggregateOptions: AggregateOptions;
+  private aggregateOptions: AggregateOptions & Abortable;
 
   /** @internal */
   constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
     pipeline: Document[] = [],
-    options: AggregateOptions = {}
+    options: AggregateOptions & Abortable = {}
   ) {
     super(client, namespace, options);
 
@@ -73,7 +74,8 @@ export class AggregationCursor<TSchema = any> extends ExplainableCursor<TSchema>
     const options = {
       ...this.aggregateOptions,
       ...this.cursorOptions,
-      session
+      session,
+      signal: this.signal
     };
     if (options.explain) {
       try {

package/src/cursor/find_cursor.ts

@@ -9,6 +9,7 @@ import {
   validateExplainTimeoutOptions
 } from '../explain';
 import type { MongoClient } from '../mongo_client';
+import { type Abortable } from '../mongo_types';
 import type { CollationOptions } from '../operations/command';
 import { CountOperation, type CountOptions } from '../operations/count';
 import { executeOperation } from '../operations/execute_operation';
@@ -36,14 +37,14 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
   /** @internal */
   private numReturned = 0;
   /** @internal */
-  private readonly findOptions: FindOptions;
+  private readonly findOptions: FindOptions & Abortable;
 
   /** @internal */
   constructor(
     client: MongoClient,
     namespace: MongoDBNamespace,
     filter: Document = {},
-    options: FindOptions = {}
+    options: FindOptions & Abortable = {}
   ) {
     super(client, namespace, options);
 
@@ -72,7 +73,8 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
     const options = {
       ...this.findOptions, // NOTE: order matters here, we may need to refine this
       ...this.cursorOptions,
-      session
+      session,
+      signal: this.signal
     };
 
     if (options.explain) {

package/src/cursor/list_collections_cursor.ts

@@ -1,5 +1,6 @@
 import type { Document } from '../bson';
 import type { Db } from '../db';
+import { type Abortable } from '../mongo_types';
 import { executeOperation } from '../operations/execute_operation';
 import {
   type CollectionInfo,
@@ -17,9 +18,9 @@ export class ListCollectionsCursor<
 > extends AbstractCursor<T> {
   parent: Db;
   filter: Document;
-  options?: ListCollectionsOptions;
+  options?: ListCollectionsOptions & Abortable;
 
-  constructor(db: Db, filter: Document, options?: ListCollectionsOptions) {
+  constructor(db: Db, filter: Document, options?: ListCollectionsOptions & Abortable) {
     super(db.client, db.s.namespace, options);
     this.parent = db;
     this.filter = filter;
@@ -38,7 +39,8 @@ export class ListCollectionsCursor<
     const operation = new ListCollectionsOperation(this.parent, this.filter, {
       ...this.cursorOptions,
       ...this.options,
-      session
+      session,
+      signal: this.signal
     });
 
     const response = await executeOperation(this.parent.client, operation, this.timeoutContext);

package/src/db.ts

@@ -8,7 +8,7 @@ import { ListCollectionsCursor } from './cursor/list_collections_cursor';
 import { RunCommandCursor, type RunCursorCommandOptions } from './cursor/run_command_cursor';
 import { MongoInvalidArgumentError } from './error';
 import type { MongoClient, PkFactory } from './mongo_client';
-import type { TODO_NODE_3286 } from './mongo_types';
+import type { Abortable, TODO_NODE_3286 } from './mongo_types';
 import type { AggregateOptions } from './operations/aggregate';
 import { CollectionsOperation } from './operations/collections';
 import {
@@ -273,7 +273,7 @@ export class Db {
    * @param command - The command to run
    * @param options - Optional settings for the command
    */
-  async command(command: Document, options?: RunCommandOptions): Promise<Document> {
+  async command(command: Document, options?: RunCommandOptions & Abortable): Promise<Document> {
     // Intentionally, we do not inherit options from parent for this operation.
     return await executeOperation(
       this.client,
@@ -284,7 +284,8 @@ export class Db {
           ...resolveBSONOptions(options),
           timeoutMS: options?.timeoutMS ?? this.timeoutMS,
           session: options?.session,
-          readPreference: options?.readPreference
+          readPreference: options?.readPreference,
+          signal: options?.signal
         })
       )
     );
@@ -351,22 +352,25 @@ export class Db {
    */
   listCollections(
     filter: Document,
-    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: true }
+    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: true } & Abortable
   ): ListCollectionsCursor<Pick<CollectionInfo, 'name' | 'type'>>;
   listCollections(
     filter: Document,
-    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: false }
+    options: Exclude<ListCollectionsOptions, 'nameOnly'> & { nameOnly: false } & Abortable
   ): ListCollectionsCursor<CollectionInfo>;
   listCollections<
     T extends Pick<CollectionInfo, 'name' | 'type'> | CollectionInfo =
       | Pick<CollectionInfo, 'name' | 'type'>
       | CollectionInfo
-  >(filter?: Document, options?: ListCollectionsOptions): ListCollectionsCursor<T>;
+  >(filter?: Document, options?: ListCollectionsOptions & Abortable): ListCollectionsCursor<T>;
   listCollections<
     T extends Pick<CollectionInfo, 'name' | 'type'> | CollectionInfo =
       | Pick<CollectionInfo, 'name' | 'type'>
       | CollectionInfo
-  >(filter: Document = {}, options: ListCollectionsOptions = {}): ListCollectionsCursor<T> {
+  >(
+    filter: Document = {},
+    options: ListCollectionsOptions & Abortable = {}
+  ): ListCollectionsCursor<T> {
     return new ListCollectionsCursor<T>(this, filter, resolveOptions(this, options));
   }
 

package/src/index.ts

@@ -430,6 +430,7 @@ export type {
   SeverityLevel
 } from './mongo_logger';
 export type {
+  Abortable,
   CommonEvents,
   EventsDescription,
   GenericListener,

package/src/mongo_client.ts

@@ -18,6 +18,7 @@ import type { ClientMetadata } from './cmap/handshake/client_metadata';
 import type { CompressorName } from './cmap/wire_protocol/compression';
 import { parseOptions, resolveSRVRecord } from './connection_string';
 import { MONGO_CLIENT_EVENTS } from './constants';
+import { type AbstractCursor } from './cursor/abstract_cursor';
 import { Db, type DbOptions } from './db';
 import type { Encrypter } from './encrypter';
 import { MongoInvalidArgumentError } from './error';
@@ -323,6 +324,12 @@ export interface MongoClientPrivate {
    * - used to notify the leak checker in our tests if test author forgot to clean up explicit sessions
    */
   readonly activeSessions: Set<ClientSession>;
+  /**
+   * We keep a reference to the cursors that are created from this client.
+   * - used to track and close all cursors in client.close().
+   *   Cursors in this set are ones that still need to have their close method invoked (no other conditions are considered)
+   */
+  readonly activeCursors: Set<AbstractCursor>;
   readonly sessionPool: ServerSessionPool;
   readonly options: MongoOptions;
   readonly readConcern?: ReadConcern;
@@ -398,6 +405,7 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
       hasBeenClosed: false,
       sessionPool: new ServerSessionPool(this),
       activeSessions: new Set(),
+      activeCursors: new Set(),
       authProviders: new MongoClientAuthProviders(),
 
       get options() {
@@ -650,6 +658,11 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
       writable: false
     });
 
+    const activeCursorCloses = Array.from(this.s.activeCursors, cursor => cursor.close());
+    this.s.activeCursors.clear();
+
+    await Promise.all(activeCursorCloses);
+
     const activeSessionEnds = Array.from(this.s.activeSessions, session => session.endSession());
     this.s.activeSessions.clear();
 

package/src/mongo_types.ts

@@ -474,6 +474,44 @@ export class TypedEventEmitter<Events extends EventsDescription> extends EventEm
 /** @public */
 export class CancellationToken extends TypedEventEmitter<{ cancel(): void }> {}
 
+/** @public */
+export type Abortable = {
+  /**
+   * @experimental
+   * When provided, the corresponding `AbortController` can be used to abort an asynchronous action.
+   *
+   * The `signal.reason` value is used as the error thrown.
+   *
+   * @remarks
+   * **NOTE:** If an abort signal aborts an operation while the driver is writing to the underlying
+   * socket or reading the response from the server, the socket will be closed.
+   * If signals are aborted at a high rate during socket read/writes this can lead to a high rate of connection reestablishment.
+   *
+   * We plan to mitigate this in a future release, please follow NODE-6062 (`timeoutMS` expiration suffers the same limitation).
+   *
+   * AbortSignals are likely a best fit for human interactive interruption (ex. ctrl-C) where the frequency
+   * of cancellation is reasonably low. If a signal is programmatically aborted for 100s of operations you can empty
+   * the driver's connection pool.
+   *
+   * @example
+   * ```js
+   * const controller = new AbortController();
+   * const { signal } = controller;
+   * process.on('SIGINT', () => controller.abort(new Error('^C pressed')));
+   *
+   * try {
+   *   const res = await fetch('...', { signal });
+   *   await collection.findOne(await res.json(), { signal });
+   * catch (error) {
+   *   if (error === signal.reason) {
+   *     // signal abort error handling
+   *   }
+   * }
+   * ```
+   */
+  signal?: AbortSignal | undefined;
+};
+
 /**
  * Helper types for dot-notation filter attributes
  */

package/src/operations/execute_operation.ts

@@ -25,7 +25,7 @@ import {
 import type { Topology } from '../sdam/topology';
 import type { ClientSession } from '../sessions';
 import { TimeoutContext } from '../timeout';
-import { supportsRetryableWrites } from '../utils';
+import { abortable, supportsRetryableWrites } from '../utils';
 import { AbstractOperation, Aspect } from './operation';
 
 const MMAPv1_RETRY_WRITES_ERROR_CODE = MONGODB_ERROR_CODES.IllegalOperation;
@@ -64,7 +64,10 @@ export async function executeOperation<
     throw new MongoRuntimeError('This method requires a valid operation instance');
   }
 
-  const topology = await autoConnect(client);
+  const topology =
+    client.topology == null
+      ? await abortable(autoConnect(client), operation.options)
+      : client.topology;
 
   // The driver sessions spec mandates that we implicitly create sessions for operations
   // that are not explicitly provided with a session.
@@ -198,7 +201,8 @@ async function tryOperation<
   let server = await topology.selectServer(selector, {
     session,
     operationName: operation.commandName,
-    timeoutContext
+    timeoutContext,
+    signal: operation.options.signal
   });
 
   const hasReadAspect = operation.hasAspect(Aspect.READ_OPERATION);
@@ -260,7 +264,8 @@ async function tryOperation<
       server = await topology.selectServer(selector, {
         session,
         operationName: operation.commandName,
-        previousServer
+        previousServer,
+        signal: operation.options.signal
       });
 
       if (hasWriteAspect && !supportsRetryableWrites(server)) {

package/src/operations/list_collections.ts

@@ -2,6 +2,7 @@ import type { Binary, Document } from '../bson';
 import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { type CursorTimeoutContext, type CursorTimeoutMode } from '../cursor/abstract_cursor';
 import type { Db } from '../db';
+import { type Abortable } from '../mongo_types';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
 import { type TimeoutContext } from '../timeout';
@@ -10,7 +11,9 @@ import { CommandOperation, type CommandOperationOptions } from './command';
 import { Aspect, defineAspects } from './operation';
 
 /** @public */
-export interface ListCollectionsOptions extends Omit<CommandOperationOptions, 'writeConcern'> {
+export interface ListCollectionsOptions
+  extends Omit<CommandOperationOptions, 'writeConcern'>,
+    Abortable {
   /** Since 4.0: If true, will only return the collection name in the response, and will omit additional info */
   nameOnly?: boolean;
   /** Since 4.0: If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */

package/src/operations/operation.ts

@@ -1,4 +1,5 @@
 import { type BSONSerializeOptions, type Document, resolveBSONOptions } from '../bson';
+import { type Abortable } from '../mongo_types';
 import { ReadPreference, type ReadPreferenceLike } from '../read_preference';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
@@ -59,7 +60,7 @@ export abstract class AbstractOperation<TResult = any> {
   // BSON serialization options
   bsonOptions?: BSONSerializeOptions;
 
-  options: OperationOptions;
+  options: OperationOptions & Abortable;
 
   /** Specifies the time an operation will run until it throws a timeout error. */
   timeoutMS?: number;
@@ -68,7 +69,7 @@ export abstract class AbstractOperation<TResult = any> {
 
   static aspects?: Set<symbol>;
 
-  constructor(options: OperationOptions = {}) {
+  constructor(options: OperationOptions & Abortable = {}) {
     this.readPreference = this.hasAspect(Aspect.WRITE_OPERATION)
       ? ReadPreference.primary
       : (ReadPreference.fromOptions(options) ?? ReadPreference.primary);