@depup/mongodb 7.1.0-depup.0

package/src/operations/distinct.ts

@@ -0,0 +1,92 @@
+import { type Document } from '../bson';
+import { type Connection } from '../cmap/connection';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import type { Collection } from '../collection';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export type DistinctOptions = CommandOperationOptions & {
+  /**
+   * @sinceServerVersion 7.1
+   *
+   * The index to use. Specify either the index name as a string or the index key pattern.
+   * If specified, then the query system will only consider plans using the hinted index.
+   *
+   * If provided as a string, `hint` must be index name for an index on the collection.
+   * If provided as an object, `hint` must be an index description for an index defined on the collection.
+   *
+   * See https://www.mongodb.com/docs/manual/reference/command/distinct/#command-fields.
+   */
+  hint?: Document | string;
+};
+
+/**
+ * Return a list of distinct values for the given key across a collection.
+ * @internal
+ */
+export class DistinctOperation extends CommandOperation<any[] | Document> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: DistinctOptions;
+  collection: Collection;
+  /** Field of the document to find distinct values for. */
+  key: string;
+  /** The query for filtering the set of documents to which we apply the distinct filter. */
+  query: Document;
+
+  /**
+   * Construct a Distinct operation.
+   *
+   * @param collection - Collection instance.
+   * @param key - Field of the document to find distinct values for.
+   * @param query - The query for filtering the set of documents to which we apply the distinct filter.
+   * @param options - Optional settings. See Collection.prototype.distinct for a list of options.
+   */
+  constructor(collection: Collection, key: string, query: Document, options?: DistinctOptions) {
+    super(collection, options);
+
+    this.options = options ?? {};
+    this.collection = collection;
+    this.key = key;
+    this.query = query;
+  }
+
+  override get commandName() {
+    return 'distinct' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection): Document {
+    const command: Document = {
+      distinct: this.collection.collectionName,
+      key: this.key,
+      query: this.query
+    };
+    // we check for undefined specifically here to allow falsy values
+    // eslint-disable-next-line no-restricted-syntax
+    if (this.options.comment !== undefined) {
+      command.comment = this.options.comment;
+    }
+
+    if (this.options.hint != null) {
+      command.hint = this.options.hint;
+    }
+
+    return command;
+  }
+
+  override handleOk(
+    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
+  ): any[] | Document {
+    if (this.explain) {
+      return response.toObject(this.bsonOptions);
+    }
+    return response.toObject(this.bsonOptions).values;
+  }
+}
+
+defineAspects(DistinctOperation, [
+  Aspect.READ_OPERATION,
+  Aspect.RETRYABLE,
+  Aspect.EXPLAINABLE,
+  Aspect.SUPPORTS_RAW_DATA
+]);

package/src/operations/drop.ts

@@ -0,0 +1,130 @@
+import { type Connection, type MongoError, MongoServerError } from '..';
+import type { Document } from '../bson';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import { CursorTimeoutContext } from '../cursor/abstract_cursor';
+import type { Db } from '../db';
+import { MONGODB_ERROR_CODES } from '../error';
+import type { ClientSession } from '../sessions';
+import { TimeoutContext } from '../timeout';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { executeOperation } from './execute_operation';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export interface DropCollectionOptions extends Omit<CommandOperationOptions, 'rawData'> {
+  /** @experimental */
+  encryptedFields?: Document;
+}
+
+/** @internal */
+export class DropCollectionOperation extends CommandOperation<boolean> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+
+  override options: DropCollectionOptions;
+  name: string;
+
+  constructor(db: Db, name: string, options: DropCollectionOptions = {}) {
+    super(db, options);
+    this.options = options;
+    this.name = name;
+  }
+
+  override get commandName() {
+    return 'drop' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    return { drop: this.name };
+  }
+
+  override handleOk(_response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): boolean {
+    return true;
+  }
+
+  override handleError(error: MongoError): boolean {
+    if (!(error instanceof MongoServerError)) throw error;
+    if (Number(error.code) !== MONGODB_ERROR_CODES.NamespaceNotFound) throw error;
+
+    return false;
+  }
+}
+
+export async function dropCollections(
+  db: Db,
+  name: string,
+  options: DropCollectionOptions
+): Promise<boolean> {
+  const timeoutContext = TimeoutContext.create({
+    session: options.session,
+    serverSelectionTimeoutMS: db.client.s.options.serverSelectionTimeoutMS,
+    waitQueueTimeoutMS: db.client.s.options.waitQueueTimeoutMS,
+    timeoutMS: options.timeoutMS
+  });
+
+  const encryptedFieldsMap = db.client.s.options.autoEncryption?.encryptedFieldsMap;
+  let encryptedFields: Document | undefined =
+    options.encryptedFields ?? encryptedFieldsMap?.[`${db.databaseName}.${name}`];
+
+  if (!encryptedFields && encryptedFieldsMap) {
+    // If the MongoClient was configured with an encryptedFieldsMap,
+    // and no encryptedFields config was available in it or explicitly
+    // passed as an argument, the spec tells us to look one up using
+    // listCollections().
+    const listCollectionsResult = await db
+      .listCollections(
+        { name },
+        {
+          nameOnly: false,
+          session: options.session,
+          timeoutContext: new CursorTimeoutContext(timeoutContext, Symbol())
+        }
+      )
+      .toArray();
+    encryptedFields = listCollectionsResult?.[0]?.options?.encryptedFields;
+  }
+
+  if (encryptedFields) {
+    const escCollection = encryptedFields.escCollection || `enxcol_.${name}.esc`;
+    const ecocCollection = encryptedFields.ecocCollection || `enxcol_.${name}.ecoc`;
+
+    for (const collectionName of [escCollection, ecocCollection]) {
+      // Drop auxilliary collections, ignoring potential NamespaceNotFound errors.
+      const dropOp = new DropCollectionOperation(db, collectionName, options);
+      await executeOperation(db.client, dropOp, timeoutContext);
+    }
+  }
+
+  return await executeOperation(
+    db.client,
+    new DropCollectionOperation(db, name, options),
+    timeoutContext
+  );
+}
+
+/** @public */
+export type DropDatabaseOptions = CommandOperationOptions;
+
+/** @internal */
+export class DropDatabaseOperation extends CommandOperation<boolean> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: DropDatabaseOptions;
+
+  constructor(db: Db, options: DropDatabaseOptions) {
+    super(db, options);
+    this.options = options;
+  }
+  override get commandName() {
+    return 'dropDatabase' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    return { dropDatabase: 1 };
+  }
+
+  override handleOk(_response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): boolean {
+    return true;
+  }
+}
+
+defineAspects(DropCollectionOperation, [Aspect.WRITE_OPERATION]);
+defineAspects(DropDatabaseOperation, [Aspect.WRITE_OPERATION]);

package/src/operations/end_sessions.ts

@@ -0,0 +1,44 @@
+import {
+  type ClientSession,
+  type Connection,
+  type ServerCommandOptions,
+  type ServerSessionId,
+  type TimeoutContext,
+  type WriteConcern
+} from '..';
+import { type Document } from '../bson';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import { CommandOperation } from '../operations/command';
+import { ReadPreference } from '../read_preference';
+import { MongoDBNamespace } from '../utils';
+import { Aspect, defineAspects } from './operation';
+
+export class EndSessionsOperation extends CommandOperation<void> {
+  override writeConcern: WriteConcern = { w: 0 };
+  override ns = MongoDBNamespace.fromString('admin.$cmd');
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+
+  private sessions: Array<ServerSessionId>;
+
+  constructor(sessions: Array<ServerSessionId>) {
+    super();
+    this.sessions = sessions;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    return {
+      endSessions: this.sessions
+    };
+  }
+  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {
+    return {
+      timeoutContext,
+      readPreference: ReadPreference.primaryPreferred
+    };
+  }
+  override get commandName(): string {
+    return 'endSessions';
+  }
+}
+
+defineAspects(EndSessionsOperation, Aspect.WRITE_OPERATION);

package/src/operations/estimated_document_count.ts

@@ -0,0 +1,61 @@
+import { type Connection } from '..';
+import type { Document } from '../bson';
+import { MongoDBResponse } from '../cmap/wire_protocol/responses';
+import type { Collection } from '../collection';
+import type { ClientSession } from '../sessions';
+import { CommandOperation, type CommandOperationOptions } from './command';
+import { Aspect, defineAspects } from './operation';
+
+/** @public */
+export interface EstimatedDocumentCountOptions extends CommandOperationOptions {
+  /**
+   * The maximum amount of time to allow the operation to run.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   */
+  maxTimeMS?: number;
+}
+
+/** @internal */
+export class EstimatedDocumentCountOperation extends CommandOperation<number> {
+  override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
+  override options: EstimatedDocumentCountOptions;
+  collectionName: string;
+
+  constructor(collection: Collection, options: EstimatedDocumentCountOptions = {}) {
+    super(collection, options);
+    this.options = options;
+    this.collectionName = collection.collectionName;
+  }
+
+  override get commandName() {
+    return 'count' as const;
+  }
+
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
+    const cmd: Document = { count: this.collectionName };
+
+    if (typeof this.options.maxTimeMS === 'number') {
+      cmd.maxTimeMS = this.options.maxTimeMS;
+    }
+
+    // we check for undefined specifically here to allow falsy values
+    // eslint-disable-next-line no-restricted-syntax
+    if (this.options.comment !== undefined) {
+      cmd.comment = this.options.comment;
+    }
+
+    return cmd;
+  }
+
+  override handleOk(response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): number {
+    return response.getNumber('n') ?? 0;
+  }
+}
+
+defineAspects(EstimatedDocumentCountOperation, [
+  Aspect.READ_OPERATION,
+  Aspect.RETRYABLE,
+  Aspect.CURSOR_CREATING,
+  Aspect.SUPPORTS_RAW_DATA
+]);

package/src/operations/execute_operation.ts

@@ -0,0 +1,319 @@
+import { MIN_SUPPORTED_SNAPSHOT_READS_WIRE_VERSION } from '../cmap/wire_protocol/constants';
+import {
+  isRetryableReadError,
+  isRetryableWriteError,
+  MongoCompatibilityError,
+  MONGODB_ERROR_CODES,
+  MongoError,
+  MongoErrorLabel,
+  MongoExpiredSessionError,
+  MongoInvalidArgumentError,
+  MongoNetworkError,
+  MongoNotConnectedError,
+  MongoRuntimeError,
+  MongoServerError,
+  MongoTransactionError,
+  MongoUnexpectedServerResponseError
+} from '../error';
+import type { MongoClient } from '../mongo_client';
+import { ReadPreference } from '../read_preference';
+import {
+  DeprioritizedServers,
+  sameServerSelector,
+  secondaryWritableServerSelector,
+  type ServerSelector
+} from '../sdam/server_selection';
+import type { Topology } from '../sdam/topology';
+import type { ClientSession } from '../sessions';
+import { TimeoutContext } from '../timeout';
+import { abortable, maxWireVersion, supportsRetryableWrites } from '../utils';
+import { AggregateOperation } from './aggregate';
+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 extends AbstractOperation> = ReturnType<
+  TOperation['handleOk']
+>;
+
+/**
+ * Executes the given operation with provided arguments.
+ * @internal
+ *
+ * @remarks
+ * Allows for a single point of entry to provide features such as implicit sessions, which
+ * are required by the Driver Sessions specification in the event that a ClientSession is
+ * not provided.
+ *
+ * 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}
+ *
+ * @typeParam T - The operation's type
+ * @typeParam TResult - The type of the operation's result, calculated from T
+ *
+ * @param client - The MongoClient to execute this operation with
+ * @param operation - The operation to execute
+ */
+export async function executeOperation<
+  T extends AbstractOperation,
+  TResult = ResultTypeFromOperation<T>
+>(client: MongoClient, operation: T, timeoutContext?: TimeoutContext | null): Promise<TResult> {
+  if (!(operation instanceof AbstractOperation)) {
+    // TODO(NODE-3483): Extend MongoRuntimeError
+    throw new MongoRuntimeError('This method requires a valid operation instance');
+  }
+
+  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.
+  let session = operation.session;
+  let owner: symbol | undefined;
+
+  if (session == null) {
+    owner = Symbol();
+    session = client.startSession({ owner, explicit: false });
+  } else if (session.hasEnded) {
+    throw new MongoExpiredSessionError('Use of expired sessions is not permitted');
+  } else if (
+    session.snapshotEnabled &&
+    maxWireVersion(topology) < MIN_SUPPORTED_SNAPSHOT_READS_WIRE_VERSION
+  ) {
+    throw new MongoCompatibilityError('Snapshot reads require MongoDB 5.0 or later');
+  } else if (session.client !== client) {
+    throw new MongoInvalidArgumentError('ClientSession must be from the same MongoClient');
+  }
+
+  operation.session ??= session;
+
+  const readPreference = operation.readPreference ?? ReadPreference.primary;
+  const inTransaction = !!session?.inTransaction();
+
+  const hasReadAspect = operation.hasAspect(Aspect.READ_OPERATION);
+
+  if (
+    inTransaction &&
+    !readPreference.equals(ReadPreference.primary) &&
+    (hasReadAspect || operation.commandName === 'runCommand')
+  ) {
+    throw new MongoTransactionError(
+      `Read preference in a transaction must be primary, not: ${readPreference.mode}`
+    );
+  }
+
+  if (session?.isPinned && session.transaction.isCommitted && !operation.bypassPinningCheck) {
+    session.unpin();
+  }
+
+  timeoutContext ??= TimeoutContext.create({
+    session,
+    serverSelectionTimeoutMS: client.s.options.serverSelectionTimeoutMS,
+    waitQueueTimeoutMS: client.s.options.waitQueueTimeoutMS,
+    timeoutMS: operation.options.timeoutMS
+  });
+
+  try {
+    return await tryOperation(operation, {
+      topology,
+      timeoutContext,
+      session,
+      readPreference
+    });
+  } finally {
+    if (session?.owner != null && session.owner === owner) {
+      await session.endSession();
+    }
+  }
+}
+
+/**
+ * Connects a client if it has not yet been connected
+ * @internal
+ */
+export 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.__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.__skipPingOnConnect;
+    }
+  }
+  return client.topology;
+}
+
+/** @internal */
+type RetryOptions = {
+  session: ClientSession | undefined;
+  readPreference: ReadPreference;
+  topology: Topology;
+  timeoutContext: TimeoutContext;
+};
+
+/**
+ * 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 = ResultTypeFromOperation<T>>(
+  operation: T,
+  { topology, timeoutContext, session, readPreference }: RetryOptions
+): Promise<TResult> {
+  let selector: ReadPreference | ServerSelector;
+
+  if (operation.hasAspect(Aspect.MUST_SELECT_SAME_SERVER)) {
+    // GetMore and KillCursor operations must always select the same server, but run through
+    // server selection to potentially force monitor checks if the server is
+    // in an unknown state.
+    selector = sameServerSelector(operation.server?.description);
+  } else if (operation instanceof AggregateOperation && operation.hasWriteStage) {
+    // If operation should try to write to secondary use the custom server selector
+    // otherwise provide the read preference.
+    selector = secondaryWritableServerSelector(topology.commonWireVersion, readPreference);
+  } else {
+    selector = readPreference;
+  }
+
+  let server = await topology.selectServer(selector, {
+    session,
+    operationName: operation.commandName,
+    timeoutContext,
+    signal: operation.options.signal,
+    deprioritizedServers: new DeprioritizedServers()
+  });
+
+  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;
+
+  const willRetryWrite =
+    topology.s.options.retryWrites &&
+    !inTransaction &&
+    supportsRetryableWrites(server) &&
+    operation.canRetryWrite;
+
+  const willRetry =
+    operation.hasAspect(Aspect.RETRYABLE) &&
+    session != null &&
+    ((hasReadAspect && willRetryRead) || (hasWriteAspect && willRetryWrite));
+
+  if (hasWriteAspect && willRetryWrite && session != null) {
+    operation.options.willRetryWrite = true;
+    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) {
+        throw new MongoServerError({
+          message: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
+          errmsg: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,
+          originalError: previousOperationError
+        });
+      }
+
+      if (operation.hasAspect(Aspect.COMMAND_BATCHING) && !operation.canRetryWrite) {
+        throw previousOperationError;
+      }
+
+      if (hasWriteAspect && !isRetryableWriteError(previousOperationError))
+        throw previousOperationError;
+
+      if (hasReadAspect && !isRetryableReadError(previousOperationError)) {
+        throw previousOperationError;
+      }
+
+      if (
+        previousOperationError instanceof MongoNetworkError &&
+        operation.hasAspect(Aspect.CURSOR_CREATING) &&
+        session != null &&
+        session.isPinned &&
+        !session.inTransaction()
+      ) {
+        session.unpin({ force: true, forceClear: true });
+      }
+
+      server = await topology.selectServer(selector, {
+        session,
+        operationName: operation.commandName,
+        deprioritizedServers,
+        signal: operation.options.signal
+      });
+
+      if (hasWriteAspect && !supportsRetryableWrites(server)) {
+        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)) {
+        operation.resetBatch();
+      }
+
+      try {
+        const result = await server.command(operation, timeoutContext);
+        return operation.handleOk(result);
+      } catch (error) {
+        return operation.handleError(error);
+      }
+    } catch (operationError) {
+      if (!(operationError instanceof MongoError)) throw operationError;
+      if (
+        previousOperationError != null &&
+        operationError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)
+      ) {
+        throw previousOperationError;
+      }
+      deprioritizedServers.add(server.description);
+      previousOperationError = operationError;
+
+      // Reset timeouts
+      timeoutContext.clear();
+    }
+  }
+
+  throw (
+    previousOperationError ??
+    new MongoRuntimeError('Tried to propagate retryability error, but no error was found.')
+  );
+}